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

package/dist/runner/manager.js

@@ -22,6 +22,7 @@ import { fileURLToPath } from "node:url";
 import { AgentRuntimeError, } from "@rynx-ai/core";
 import { listRuntimeModels } from "../models-catalog.js";
 import { probeRuntimeStatus } from "../runtime-status.js";
+import { terminateTmuxServer } from "../terminal/tmux.js";
 import { fromWireError, } from "./protocol.js";
 import { StdioRunnerTransport } from "./transport.js";
 /** Routing key for the shared capability runner (slash-command RPCs). */
@@ -36,6 +37,13 @@ const DEFAULT_SHUTDOWN_KILL_GRACE_MS = 5_000;
 const DEFAULT_LIVE_START_TIMEOUT_MS = 10_000;
 /** Thread readiness may legitimately wait through Provider startup. */
 const DEFAULT_LIVE_READY_TIMEOUT_MS = 25_000;
+/** A submitted TUI command should become a mirrored turn or native rotation
+ * quickly. If it does not, the runner is fenced by a verified process-tree
+ * shutdown before maintenance may treat the submission as settled. */
+const DEFAULT_TERMINAL_INPUT_HANDOFF_TIMEOUT_MS = 30_000;
+/** Retry transient terminal-server cleanup without spinning forever. */
+const DEFAULT_TERMINAL_INPUT_CLEANUP_RETRY_MS = 1_000;
+const MAX_TERMINAL_INPUT_CLEANUP_RETRY_MS = 30_000;
 /** Keep per-Session spawn context small enough to remain an environment handoff,
  * not an unbounded transport. */
 const MAX_SESSION_CONTEXT_ENV_ENTRIES = 32;
@@ -139,6 +147,8 @@ export class RunnerManager {
     spawn;
     childEnv;
     sessionContextProvider;
+    admissionOpen;
+    admissionReserve;
     now;
     defaultRuntime;
     handles = new Map();
@@ -148,8 +158,13 @@ export class RunnerManager {
     reapTimer;
     shutdownGraceMs;
     shutdownKillGraceMs;
+    signalChild;
+    terminateTerminalServer;
     liveStartTimeoutMs;
     liveReadyTimeoutMs;
+    liveInterruptTimeoutMs;
+    terminalInputHandoffTimeoutMs;
+    terminalInputCleanupRetryMs;
     stopping = false;
     stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
@@ -160,6 +175,24 @@ export class RunnerManager {
     liveSessionKeys = new Set();
     /** Last live-start error per local session, surfaced by the control API. */
     liveErrors = new Map();
+    /** Last immutable launch snapshots seen for a Session. Used only to restore a
+     * target request that crossed a fork reservation boundary. */
+    liveOptions = new Map();
+    /** A fork reserves its target before the first asynchronous store read. This
+     * prevents another entry point from starting the target against an
+     * uncommitted Provider binding. */
+    forkReservations = new Map();
+    /** A native fork temporarily makes the source read-only so its canonical
+     * snapshot and Provider context are captured at the same boundary. */
+    sourceForkReservations = new Map();
+    /** Manager-wide fork de-duplication. LocalAgentHost only sees one source
+     * runner, so the fence must live here to cover concurrent source runners. */
+    forkOperations = new Map();
+    forkBufferedMessages = new Map();
+    forkBufferedTerminalInputs = new Map();
+    /** Owner TUI submissions accepted by the parent but not yet represented by a
+     * mirrored response or a durably published native rotation. */
+    terminalInputHandoffs = new Map();
     constructor(opts) {
         this.config = opts.config;
         this.sessionStore = opts.sessionStore;
@@ -168,12 +201,19 @@ export class RunnerManager {
         this.spawn = opts.spawn ?? nodeSpawn;
         this.childEnv = opts.childEnv ?? {};
         this.sessionContextProvider = opts.sessionContextProvider;
+        this.admissionOpen = opts.admissionOpen ?? (() => true);
+        this.admissionReserve = opts.admissionReserve;
         this.now = opts.now ?? (() => Date.now());
-        this.defaultRuntime = opts.config.AGENT_RUNTIME ?? "codex";
+        this.defaultRuntime = opts.config.DEFAULT_RUNTIME ?? "codex";
         this.shutdownGraceMs = Math.max(0, opts.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS);
         this.shutdownKillGraceMs = Math.max(0, opts.shutdownKillGraceMs ?? DEFAULT_SHUTDOWN_KILL_GRACE_MS);
+        this.signalChild = opts.signalChild ?? signalRunnerChild;
+        this.terminateTerminalServer = opts.terminateTerminalServer ?? terminateTmuxServer;
         this.liveStartTimeoutMs = Math.max(1, opts.liveStartTimeoutMs ?? DEFAULT_LIVE_START_TIMEOUT_MS);
         this.liveReadyTimeoutMs = Math.max(1, opts.liveReadyTimeoutMs ?? DEFAULT_LIVE_READY_TIMEOUT_MS);
+        this.liveInterruptTimeoutMs = Math.max(1, opts.liveInterruptTimeoutMs ?? 10_000);
+        this.terminalInputHandoffTimeoutMs = Math.max(1, opts.terminalInputHandoffTimeoutMs ?? DEFAULT_TERMINAL_INPUT_HANDOFF_TIMEOUT_MS);
+        this.terminalInputCleanupRetryMs = Math.max(1, opts.terminalInputCleanupRetryMs ?? DEFAULT_TERMINAL_INPUT_CLEANUP_RETRY_MS);
         const reapIntervalMs = opts.reapIntervalMs ?? 60_000;
         if (reapIntervalMs > 0) {
             this.reapTimer = setInterval(() => this.reapIdle(), reapIntervalMs);
@@ -201,6 +241,10 @@ export class RunnerManager {
      * and attach.
      */
     openLiveTerminal(localThreadId, opts) {
+        this.assertAdmissionOpen();
+        if (this.forkReservations.has(localThreadId)) {
+            throw new TerminalOpenError("Session fork is still being committed", "terminal_not_live");
+        }
         const handle = this.handles.get(localThreadId);
         if (!handle || handle.dead || !this.liveSessionKeys.has(localThreadId)) {
             throw new TerminalOpenError("terminal not live", "terminal_not_live");
@@ -210,7 +254,50 @@ export class RunnerManager {
     openTerminalOnHandle(handle, localThreadId, opts) {
         handle.lastUsedAt = this.now();
         const attachId = randomUUID();
-        const terminal = new ManagedTerminal(attachId, (msg) => handle.transport.send(msg), () => handle.terminals.delete(attachId));
+        const inputTracker = {
+            buffer: "",
+            previousWasCarriageReturn: false,
+            bracketedPaste: false,
+            pendingEscape: "",
+        };
+        const terminal = new ManagedTerminal(attachId, (msg) => {
+            const handoffs = msg.t === "term.input" && opts.role === "owner"
+                ? this.beginTerminalInputHandoffs(handle, this.currentTerminalSessionId(handle, localThreadId), trackedTerminalSubmissions(inputTracker, Buffer.from(msg.dataB64, "base64").toString("utf8")))
+                : [];
+            const send = () => {
+                try {
+                    handle.transport.send(msg);
+                }
+                catch (error) {
+                    for (const handoff of handoffs) {
+                        this.finishTerminalInputHandoff(handle, handoff);
+                    }
+                    throw error;
+                }
+            };
+            const sourceReservation = this.sourceForkReservations.get(localThreadId);
+            if (msg.t === "term.input" && sourceReservation) {
+                void sourceReservation.then(() => {
+                    if (!handle.dead)
+                        send();
+                }).catch((error) => {
+                    void this.terminateHandle(handle, `terminal input delivery failed: ${errorMessage(error)}`).catch((terminationError) => {
+                        logTerminationFailure(handle, terminationError);
+                    });
+                });
+                return;
+            }
+            // A terminal request may race a fork reservation. Never let later
+            // keystrokes reach an unpublished Provider target.
+            if (msg.t === "term.input") {
+                const target = this.reservedForkTarget(handle, localThreadId);
+                if (target) {
+                    this.forkBufferedTerminalInputs.get(target)?.push({ handle, message: msg });
+                    return;
+                }
+            }
+            send();
+        }, () => handle.terminals.delete(attachId));
         handle.terminals.set(attachId, terminal);
         handle.transport.send({
             t: "term.open",
@@ -229,6 +316,8 @@ export class RunnerManager {
     }
     /** Whether this process already owns a live runner for the Session. Read-only; never spawns. */
     hasLiveSession(localThreadId) {
+        if (this.forkReservations.has(localThreadId))
+            return false;
         const handle = this.handles.get(localThreadId);
         return Boolean(handle && !handle.dead && this.liveSessionKeys.has(localThreadId));
     }
@@ -245,6 +334,152 @@ export class RunnerManager {
     onRotate(listener) {
         this.rotateListener = listener;
     }
+    /** Accepted TUI submissions that have not crossed into an observable runtime
+     * state. The daemon folds this into runningTurns after closing admission. */
+    pendingTerminalInputCount() {
+        let count = 0;
+        for (const handoffs of this.terminalInputHandoffs.values()) {
+            count += handoffs.length;
+        }
+        return count;
+    }
+    beginTerminalInputHandoffs(handle, sessionId, kinds) {
+        if (kinds.length === 0)
+            return [];
+        const created = [];
+        try {
+            for (const kind of kinds) {
+                const handoff = {
+                    sessionId,
+                    kind,
+                    reservation: this.reserveAdmission(),
+                    timer: undefined,
+                };
+                handoff.timer = setTimeout(() => {
+                    this.expireTerminalInputHandoffs(handle);
+                }, this.terminalInputHandoffTimeoutMs);
+                handoff.timer.unref?.();
+                const handoffs = this.terminalInputHandoffs.get(handle);
+                if (handoffs)
+                    handoffs.push(handoff);
+                else
+                    this.terminalInputHandoffs.set(handle, [handoff]);
+                created.push(handoff);
+            }
+            return created;
+        }
+        catch (error) {
+            for (const handoff of created) {
+                this.finishTerminalInputHandoff(handle, handoff);
+            }
+            throw error;
+        }
+    }
+    settleTerminalInputHandoff(handle, sessionId, kind) {
+        const handoff = this.terminalInputHandoffs
+            .get(handle)
+            ?.find((candidate) => candidate.sessionId === sessionId);
+        // Runtime observations settle accepted input in submission order. In
+        // particular, a response from the source Session while /clear or /fork is
+        // still publishing must not skip that rotation and release a later turn
+        // which has not yet been rebound or delivered.
+        if (handoff?.kind === kind)
+            this.finishTerminalInputHandoff(handle, handoff);
+    }
+    settleTerminalRotationHandoff(handle, sourceSessionId, targetSessionId) {
+        const handoffs = this.terminalInputHandoffs.get(handle);
+        const rotationIndex = handoffs?.findIndex((handoff) => handoff.sessionId === sourceSessionId && handoff.kind === "rotation") ?? -1;
+        if (!handoffs || rotationIndex < 0)
+            return;
+        // Turns submitted before /clear or /fork are superseded once the rotation
+        // is published. Inputs accepted afterwards belong to the transferred pane
+        // and must follow it to the target Session.
+        const rotation = handoffs[rotationIndex];
+        for (const handoff of [...handoffs.slice(0, rotationIndex)]) {
+            if (handoff.sessionId === sourceSessionId && handoff.kind === "turn") {
+                this.finishTerminalInputHandoff(handle, handoff);
+            }
+        }
+        if (rotation)
+            this.finishTerminalInputHandoff(handle, rotation);
+        for (const handoff of this.terminalInputHandoffs.get(handle) ?? []) {
+            if (handoff.sessionId === sourceSessionId)
+                handoff.sessionId = targetSessionId;
+        }
+    }
+    currentTerminalSessionId(handle, fallback) {
+        for (const [sessionId, candidate] of this.handles) {
+            if (candidate === handle && this.liveSessionKeys.has(sessionId))
+                return sessionId;
+        }
+        return fallback;
+    }
+    finishTerminalInputHandoff(handle, handoff) {
+        if (handoff.timer) {
+            clearTimeout(handoff.timer);
+            handoff.timer = undefined;
+        }
+        handoff.reservation?.release();
+        handoff.reservation = undefined;
+        const handoffs = this.terminalInputHandoffs.get(handle);
+        if (!handoffs)
+            return;
+        const index = handoffs.indexOf(handoff);
+        if (index >= 0)
+            handoffs.splice(index, 1);
+        if (handoffs.length === 0)
+            this.terminalInputHandoffs.delete(handle);
+    }
+    finishAllTerminalInputHandoffs(handle) {
+        if (handle.terminalCleanupRetryTimer) {
+            clearTimeout(handle.terminalCleanupRetryTimer);
+            delete handle.terminalCleanupRetryTimer;
+        }
+        handle.terminalCleanupRetryFailures = 0;
+        for (const handoff of [...(this.terminalInputHandoffs.get(handle) ?? [])]) {
+            this.finishTerminalInputHandoff(handle, handoff);
+        }
+    }
+    preserveTerminalInputHandoffsAsActivity(handle) {
+        for (const handoff of this.terminalInputHandoffs.get(handle) ?? []) {
+            if (handoff.timer) {
+                clearTimeout(handoff.timer);
+                handoff.timer = undefined;
+            }
+            handoff.reservation?.release();
+            handoff.reservation = undefined;
+        }
+    }
+    scheduleTerminalInputCleanupRetry(handle) {
+        if (handle.terminalCleanupRetryTimer ||
+            !this.terminalInputHandoffs.has(handle))
+            return;
+        const exponent = Math.min(handle.terminalCleanupRetryFailures - 1, 10);
+        const delay = Math.min(this.terminalInputCleanupRetryMs * (2 ** Math.max(0, exponent)), MAX_TERMINAL_INPUT_CLEANUP_RETRY_MS);
+        handle.terminalCleanupRetryTimer = setTimeout(() => {
+            delete handle.terminalCleanupRetryTimer;
+            if (!this.terminalInputHandoffs.has(handle))
+                return;
+            void this.terminateHandle(handle, "retrying unproven terminal input cleanup").catch((error) => {
+                logTerminationFailure(handle, error);
+            });
+        }, delay);
+        handle.terminalCleanupRetryTimer.unref?.();
+    }
+    expireTerminalInputHandoffs(handle) {
+        const handoffs = this.terminalInputHandoffs.get(handle);
+        if (!handoffs?.length)
+            return;
+        for (const handoff of handoffs) {
+            if (handoff.timer) {
+                clearTimeout(handoff.timer);
+                handoff.timer = undefined;
+            }
+        }
+        void this.terminateHandle(handle, "accepted terminal input did not become observable before maintenance timeout").catch((error) => {
+            logTerminationFailure(handle, error);
+        });
+    }
     /**
      * Eagerly bring up a session's codex-native live view (persistent forwarder +
      * detached `codex --remote` TUI) in its runner child, spawning the runner if
@@ -252,16 +487,38 @@ export class RunnerManager {
      * non-codex / non-live session (the caller then uses the normal run path).
      */
     ensureLiveSession(localThreadId, opts) {
-        return this.requestLiveSession(localThreadId, opts, true);
+        const admission = this.reserveAdmission();
+        return this.requestLiveSession(localThreadId, opts, true)
+            .finally(() => admission.release());
     }
     /** Start the Provider pane without waiting for login/onboarding to create a
      * native thread. This is the setup-terminal gate; callers may attach as soon
      * as it resolves, while normal message delivery still uses ensureLiveSession. */
     startLiveSession(localThreadId, opts) {
-        return this.requestLiveSession(localThreadId, opts, false);
+        const admission = this.reserveAdmission();
+        return this.requestLiveSession(localThreadId, opts, false)
+            .finally(() => admission.release());
     }
-    requestLiveSession(localThreadId, opts, waitForReady) {
-        const handle = this.getOrSpawn(localThreadId);
+    requestLiveSession(localThreadId, opts, waitForReady, allowReservedForkTarget = false) {
+        const sourceReservation = allowReservedForkTarget
+            ? undefined
+            : this.sourceForkReservations.get(localThreadId);
+        if (sourceReservation) {
+            return sourceReservation.then(() => this.requestLiveSession(localThreadId, opts, waitForReady));
+        }
+        this.liveOptions.set(localThreadId, {
+            workspace: structuredClone(opts.workspace),
+            execution: structuredClone(opts.execution),
+            ...(opts.cols ? { cols: opts.cols } : {}),
+            ...(opts.rows ? { rows: opts.rows } : {}),
+        });
+        const reservation = allowReservedForkTarget
+            ? undefined
+            : this.forkReservations.get(localThreadId);
+        if (reservation) {
+            return reservation.then(() => this.requestLiveSession(localThreadId, opts, waitForReady));
+        }
+        const handle = this.getOrSpawn(localThreadId, allowReservedForkTarget);
         handle.lastUsedAt = this.now();
         this.liveSessionKeys.add(localThreadId);
         const reqId = randomUUID();
@@ -270,39 +527,60 @@ export class RunnerManager {
             const timeout = setTimeout(() => {
                 if (!handle.live.delete(reqId))
                     return;
-                const reason = `runner did not acknowledge ${waitForReady ? "live readiness" : "terminal start"} within ${timeoutMs}ms`;
-                this.liveErrors.set(localThreadId, reason);
-                this.liveSessionKeys.delete(localThreadId);
-                resolve(false);
-                // A child that cannot answer a bounded control round-trip is unsafe to
-                // reuse. Reap it so the next click gets a fresh runner.
-                void this.terminateHandle(handle, reason).catch((error) => {
-                    logTerminationFailure(handle, error);
-                });
+                const finishTimeout = () => {
+                    const reason = `runner did not acknowledge ${waitForReady ? "live readiness" : "terminal start"} within ${timeoutMs}ms`;
+                    this.liveErrors.set(localThreadId, reason);
+                    this.liveSessionKeys.delete(localThreadId);
+                    // A child that cannot answer a bounded control round-trip is unsafe
+                    // to reuse. Reap it so the next click gets a fresh runner.
+                    void this.terminateHandle(handle, reason).catch((error) => {
+                        logTerminationFailure(handle, error);
+                    });
+                    return false;
+                };
+                const reservation = allowReservedForkTarget
+                    ? undefined
+                    : this.forkReservations.get(localThreadId);
+                if (reservation) {
+                    void reservation
+                        .then(() => finishTimeout())
+                        .then(resolve, () => resolve(false));
+                    return;
+                }
+                resolve(finishTimeout());
             }, timeoutMs);
             timeout.unref?.();
             handle.live.set(reqId, (res) => {
                 clearTimeout(timeout);
                 const ok = res.ok ?? false;
-                if (ok) {
-                    this.liveErrors.delete(localThreadId);
-                }
-                else {
-                    this.liveErrors.set(localThreadId, res.error ?? "live session did not become ready");
+                const finish = () => {
+                    if (ok) {
+                        this.liveErrors.delete(localThreadId);
+                    }
+                    else {
+                        this.liveErrors.set(localThreadId, res.error ?? "live session did not become ready");
+                    }
+                    return ok;
+                };
+                const reservation = allowReservedForkTarget
+                    ? undefined
+                    : this.forkReservations.get(localThreadId);
+                if (reservation) {
+                    void reservation
+                        .then(() => finish())
+                        .then(resolve, () => resolve(false));
+                    return;
                 }
-                resolve(ok);
+                resolve(finish());
             });
             handle.transport.send({
                 t: "live.ensure",
                 reqId,
                 localThreadId,
-                ...(opts?.cwd ? { cwd: opts.cwd } : {}),
-                ...(opts?.cols ? { cols: opts.cols } : {}),
-                ...(opts?.rows ? { rows: opts.rows } : {}),
-                ...(opts?.runtime ? { runtime: opts.runtime } : {}),
-                ...(opts?.reasoningEffort ? { reasoningEffort: opts.reasoningEffort } : {}),
-                ...(opts?.agentName ? { agentName: opts.agentName } : {}),
-                ...(opts?.agentSpec ? { agentSpec: opts.agentSpec } : {}),
+                workspace: opts.workspace,
+                execution: opts.execution,
+                ...(opts.cols ? { cols: opts.cols } : {}),
+                ...(opts.rows ? { rows: opts.rows } : {}),
                 waitForReady,
             });
         });
@@ -317,11 +595,43 @@ export class RunnerManager {
      * the session has no live forwarder (caller falls back to the run path).
      */
     injectMessage(localThreadId, input) {
+        const admission = this.reserveAdmission();
+        return this.injectMessageAdmitted(localThreadId, input)
+            .finally(() => admission.release());
+    }
+    injectMessageAdmitted(localThreadId, input) {
+        const sourceReservation = this.sourceForkReservations.get(localThreadId);
+        if (sourceReservation) {
+            return sourceReservation.then(() => this.injectMessageAdmitted(localThreadId, input));
+        }
+        const reservation = this.forkReservations.get(localThreadId);
+        if (reservation) {
+            return reservation.then(() => this.injectMessageAdmitted(localThreadId, input));
+        }
         const handle = this.getOrSpawn(localThreadId);
         handle.lastUsedAt = this.now();
         const reqId = randomUUID();
         return new Promise((resolve) => {
-            handle.live.set(reqId, (res) => resolve(res.outcome ?? "failed"));
+            handle.live.set(reqId, (res) => {
+                const outcome = res.outcome ?? "failed";
+                const finish = () => {
+                    if (outcome === "injected") {
+                        this.liveErrors.delete(localThreadId);
+                    }
+                    else {
+                        this.liveErrors.set(localThreadId, res.error ?? `live injection ${outcome}`);
+                    }
+                    return outcome;
+                };
+                const reservation = this.forkReservations.get(localThreadId);
+                if (reservation) {
+                    void reservation
+                        .then(() => finish())
+                        .then(resolve, () => resolve("failed"));
+                    return;
+                }
+                resolve(finish());
+            });
             handle.transport.send(typeof input === "string"
                 ? { t: "inject", reqId, localThreadId, text: input }
                 : { t: "inject", reqId, localThreadId, input });
@@ -339,7 +649,16 @@ export class RunnerManager {
         handle.lastUsedAt = this.now();
         const reqId = randomUUID();
         return new Promise((resolve) => {
-            handle.live.set(reqId, (res) => resolve(res.ok ?? false));
+            const timeout = setTimeout(() => {
+                if (!handle.live.delete(reqId))
+                    return;
+                resolve(false);
+            }, this.liveInterruptTimeoutMs);
+            timeout.unref?.();
+            handle.live.set(reqId, (res) => {
+                clearTimeout(timeout);
+                resolve(res.ok ?? false);
+            });
             handle.transport.send({ t: "live.interrupt", reqId, localThreadId });
         });
     }
@@ -382,9 +701,83 @@ export class RunnerManager {
     clearGoal(localThreadId) {
         return this.forwardCap("clearGoal", [localThreadId], localThreadId);
     }
-    forkSession(currentLocalThreadId, newLocalThreadId) {
-        // Runs on the SOURCE session's child (its home has the source rollout to fork).
-        return this.forwardCap("forkSession", [currentLocalThreadId, newLocalThreadId], currentLocalThreadId);
+    forkSession(currentLocalThreadId, newLocalThreadId, options) {
+        this.assertAdmissionOpen();
+        if (currentLocalThreadId === newLocalThreadId) {
+            return Promise.resolve({
+                ok: false,
+                message: "source and target Session must differ",
+            });
+        }
+        const inflight = this.forkOperations.get(newLocalThreadId);
+        if (inflight) {
+            if (inflight.sourceSessionId === currentLocalThreadId) {
+                return inflight.operation.then(capabilityForkResult);
+            }
+            return Promise.resolve({
+                ok: false,
+                message: "target Session already has a fork in progress",
+            });
+        }
+        if (this.sourceForkReservations.has(currentLocalThreadId)) {
+            return Promise.resolve({
+                ok: false,
+                message: "source Session already has a fork in progress",
+            });
+        }
+        let releaseReservation;
+        const reservation = new Promise((resolve) => {
+            releaseReservation = resolve;
+        });
+        let releaseSource;
+        const sourceReservation = new Promise((resolve) => {
+            releaseSource = resolve;
+        });
+        this.forkReservations.set(newLocalThreadId, reservation);
+        this.sourceForkReservations.set(currentLocalThreadId, sourceReservation);
+        this.forkBufferedMessages.set(newLocalThreadId, []);
+        this.forkBufferedTerminalInputs.set(newLocalThreadId, []);
+        const retainedLiveOptions = this.liveOptions.get(newLocalThreadId);
+        const operation = (async () => {
+            await options.beforeProviderFork();
+            return this.performManagedFork(currentLocalThreadId, newLocalThreadId, options);
+        })()
+            .finally(() => {
+            const current = this.forkOperations.get(newLocalThreadId);
+            if (current?.operation === operation) {
+                this.forkOperations.delete(newLocalThreadId);
+            }
+            if (this.forkReservations.get(newLocalThreadId) === reservation) {
+                this.forkReservations.delete(newLocalThreadId);
+            }
+            if (this.sourceForkReservations.get(currentLocalThreadId) === sourceReservation) {
+                this.sourceForkReservations.delete(currentLocalThreadId);
+            }
+            const buffered = this.forkBufferedMessages.get(newLocalThreadId) ?? [];
+            this.forkBufferedMessages.delete(newLocalThreadId);
+            const bufferedTerminalInputs = this.forkBufferedTerminalInputs.get(newLocalThreadId) ?? [];
+            this.forkBufferedTerminalInputs.delete(newLocalThreadId);
+            for (const entry of buffered) {
+                this.deliverForkBufferedMessage(entry.handle, entry.message);
+            }
+            for (const entry of bufferedTerminalInputs) {
+                if (!entry.handle.dead)
+                    entry.handle.transport.send(entry.message);
+            }
+            releaseReservation();
+            releaseSource();
+            queueMicrotask(() => {
+                if (this.liveOptions.get(newLocalThreadId) === retainedLiveOptions
+                    && !this.handles.has(newLocalThreadId)) {
+                    this.liveOptions.delete(newLocalThreadId);
+                }
+            });
+        });
+        this.forkOperations.set(newLocalThreadId, {
+            sourceSessionId: currentLocalThreadId,
+            operation,
+        });
+        return operation.then(capabilityForkResult);
     }
     /**
      * Backend-free runtime readiness (not part of `AgentCapabilities`; surfaced for
@@ -395,7 +788,7 @@ export class RunnerManager {
     }
     /** Stop the runner bound to one session (if any), rejecting its in-flight work. */
     stopRunner(localThreadId) {
-        const handle = this.handles.get(localThreadId);
+        const handle = this.handleForCleanup(localThreadId);
         if (!handle) {
             return;
         }
@@ -403,6 +796,15 @@ export class RunnerManager {
             logTerminationFailure(handle, error);
         });
     }
+    /** Force-stop and join the runner bound to one Session. Unlike stopRunner,
+     * completion proves that the child process has exited. */
+    async terminateLiveSession(localThreadId) {
+        const handle = this.handleForCleanup(localThreadId);
+        if (!handle)
+            return false;
+        await this.terminateHandle(handle, "runner force-stopped");
+        return true;
+    }
     /** Stop every runner and join all child exits. Idempotent across concurrent calls. */
     stop() {
         if (this.stopPromise)
@@ -411,12 +813,16 @@ export class RunnerManager {
         if (this.reapTimer) {
             clearInterval(this.reapTimer);
         }
-        const children = [...this.childHandles];
-        this.stopPromise = (async () => {
-            const results = await Promise.allSettled(children.map((handle) => this.terminateHandle(handle, "runner manager stopped")));
+        const children = new Set([
+            ...this.childHandles,
+            ...this.terminalInputHandoffs.keys(),
+        ]);
+        const attempt = (async () => {
+            const results = await Promise.allSettled([...children].map((handle) => this.terminateHandle(handle, "runner manager stopped")));
             this.handles.clear();
             this.liveSessionKeys.clear();
             this.liveErrors.clear();
+            this.liveOptions.clear();
             this.mirrorListener = null;
             this.rotateListener = null;
             const errors = results
@@ -427,9 +833,19 @@ export class RunnerManager {
             }
             this.childHandles.clear();
         })();
-        return this.stopPromise;
+        this.stopPromise = attempt;
+        void attempt.catch(() => {
+            if (this.stopPromise === attempt)
+                this.stopPromise = undefined;
+        });
+        return attempt;
     }
     // ── internals ──────────────────────────────────────────────────────────────
+    handleForCleanup(localThreadId) {
+        return this.handles.get(localThreadId) ??
+            [...this.terminalInputHandoffs].find(([handle, handoffs]) => handle.key === localThreadId ||
+                handoffs.some((handoff) => handoff.sessionId === localThreadId))?.[0];
+    }
     /** Forward a capability to a runner child. Session-less caps (listModels/status)
      *  use the shared `CAP_KEY` child; per-thread caps pass the session's key so they
      *  run on that session's child (which owns its private CODEX_HOME). */
@@ -442,19 +858,255 @@ export class RunnerManager {
             handle.transport.send({ t: "cap", capId, name, args });
         });
     }
-    getOrSpawn(key) {
-        if (this.stopping) {
-            throw new AgentRuntimeError("runner manager is stopped", 503, "runner_stopped");
+    getOrSpawn(key, allowReservedForkTarget = false) {
+        const admission = this.reserveAdmission();
+        try {
+            if (this.stopping) {
+                throw new AgentRuntimeError("runner manager is stopped", 503, "runner_stopped");
+            }
+            if (key !== CAP_KEY &&
+                this.forkReservations.has(key) &&
+                !allowReservedForkTarget) {
+                throw new AgentRuntimeError("Session fork is still being committed", 409, "session_fork_pending");
+            }
+            this.reapIdle();
+            const existing = this.handles.get(key);
+            if (existing && !existing.dead) {
+                existing.lastUsedAt = this.now();
+                return existing;
+            }
+            const handle = this.spawnHandle(key);
+            this.handles.set(key, handle);
+            return handle;
         }
-        this.reapIdle();
-        const existing = this.handles.get(key);
-        if (existing && !existing.dead) {
-            existing.lastUsedAt = this.now();
-            return existing;
+        finally {
+            admission.release();
         }
-        const handle = this.spawnHandle(key);
-        this.handles.set(key, handle);
-        return handle;
+    }
+    assertAdmissionOpen() {
+        const reservation = this.admissionReserve?.();
+        if (reservation) {
+            reservation.release();
+            return;
+        }
+        if (!this.admissionReserve && this.admissionOpen())
+            return;
+        throw new AgentRuntimeError("daemon maintenance is in progress", 503, "daemon_maintenance");
+    }
+    reserveAdmission() {
+        const reservation = this.admissionReserve?.();
+        if (reservation)
+            return reservation;
+        if (!this.admissionReserve && this.admissionOpen()) {
+            return { release() { } };
+        }
+        throw new AgentRuntimeError("daemon maintenance is in progress", 503, "daemon_maintenance");
+    }
+    async performManagedFork(currentLocalThreadId, newLocalThreadId, options) {
+        const existingTarget = await this.sessionStore.get(newLocalThreadId);
+        if (existingTarget?.parentSessionId === currentLocalThreadId) {
+            return { ok: true, data: undefined };
+        }
+        if (existingTarget?.parentSessionId) {
+            return {
+                ok: false,
+                reason: "error",
+                message: "target Session already belongs to a different fork",
+            };
+        }
+        const targetHandle = this.handles.get(newLocalThreadId);
+        if (existingTarget) {
+            return {
+                ok: false,
+                reason: "error",
+                message: "target Session already has a Provider binding",
+            };
+        }
+        if (targetHandle && !targetHandle.dead) {
+            return {
+                ok: false,
+                reason: "error",
+                message: "target Session already has a runner",
+            };
+        }
+        if (options.execution.provider === "claude") {
+            return this.performClaudeManagedFork(currentLocalThreadId, newLocalThreadId, options);
+        }
+        // Runs on the SOURCE session's child (its home has the source rollout to
+        // fork). The Provider persists the native fork and target binding before
+        // returning. Only then is the target reservation released.
+        return this.forwardCap("forkSession", [
+            currentLocalThreadId,
+            newLocalThreadId,
+            {
+                workspace: structuredClone(options.workspace),
+                execution: structuredClone(options.execution),
+            },
+        ], currentLocalThreadId);
+    }
+    async performClaudeManagedFork(currentLocalThreadId, newLocalThreadId, options) {
+        const source = await this.sessionStore.get(currentLocalThreadId);
+        const setIntent = this.sessionStore.setClaudeForkIntent?.bind(this.sessionStore);
+        const deleteIntent = this.sessionStore.deleteClaudeForkIntent?.bind(this.sessionStore);
+        if (!source?.codexSessionId || !setIntent || !deleteIntent) {
+            return {
+                ok: false,
+                reason: "unsupported",
+                message: "Claude fork persistence is unavailable",
+            };
+        }
+        const targetClaudeSessionId = randomUUID();
+        try {
+            await setIntent({
+                targetSessionId: newLocalThreadId,
+                sourceSessionId: currentLocalThreadId,
+                sourceClaudeSessionId: source.codexSessionId,
+                targetClaudeSessionId,
+                updatedAt: new Date().toISOString(),
+            });
+            const ready = await this.requestLiveSession(newLocalThreadId, {
+                workspace: structuredClone(options.workspace),
+                execution: structuredClone(options.execution),
+            }, true, true);
+            const target = ready ? await this.sessionStore.get(newLocalThreadId) : null;
+            if (!target ||
+                target.parentSessionId !== currentLocalThreadId ||
+                target.codexSessionId !== targetClaudeSessionId) {
+                throw new Error(this.lastLiveSessionError(newLocalThreadId) ??
+                    "Claude did not materialize the requested fork");
+            }
+            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);
+            }
+            const handle = this.handles.get(newLocalThreadId);
+            if (handle && !handle.dead) {
+                await this.terminateHandle(handle, "Claude fork materialization failed").catch(() => undefined);
+            }
+            return {
+                ok: false,
+                reason: "error",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    bufferForkTargetMessage(handle, message) {
+        const directTarget = message.t === "mirror" ? message.sessionId : message.from;
+        const target = this.reservedForkTarget(handle, directTarget);
+        if (!target)
+            return false;
+        this.forkBufferedMessages.get(target)?.push({ handle, message });
+        return true;
+    }
+    reservedForkTarget(handle, directTarget) {
+        return this.forkReservations.has(directTarget)
+            ? directTarget
+            : [...this.forkReservations.keys()].find((candidate) => this.handles.get(candidate) === handle);
+    }
+    deliverForkBufferedMessage(handle, message) {
+        if (handle.dead)
+            return;
+        if (message.t === "mirror") {
+            this.mirrorListener?.(message.sessionId, message.event);
+            if (message.event.type === "response.created") {
+                this.settleTerminalInputHandoff(handle, message.sessionId, "turn");
+            }
+            return;
+        }
+        this.deliverRotateMessage(handle, message);
+    }
+    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);
+            });
+            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)
+                return;
+            this.handles.set(message.to, handle);
+            this.liveSessionKeys.add(message.to);
+            this.liveOptions.set(message.to, {
+                workspace: structuredClone(message.workspace),
+                execution: structuredClone(message.execution),
+            });
+            for (const entry of this.forkBufferedMessages.get(message.to) ?? []) {
+                this.deliverForkBufferedMessage(entry.handle, entry.message);
+            }
+            for (const entry of this.forkBufferedTerminalInputs.get(message.to) ?? []) {
+                if (!entry.handle.dead)
+                    entry.handle.transport.send(entry.message);
+            }
+        })
+            .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 (this.sourceForkReservations.get(message.from) === sourceReservation) {
+                this.sourceForkReservations.delete(message.from);
+            }
+            this.forkBufferedMessages.delete(message.to);
+            this.forkBufferedTerminalInputs.delete(message.to);
+            releaseTarget();
+            releaseSource();
+        });
     }
     spawnHandle(key) {
         const args = this.runnerEntry.endsWith(".ts")
@@ -463,10 +1115,12 @@ export class RunnerManager {
         const sessionContext = key === CAP_KEY
             ? undefined
             : this.openSessionContext(key);
+        const processGroup = process.platform !== "win32";
         let child;
         try {
             child = this.spawn(process.execPath, args, {
                 stdio: ["pipe", "pipe", "pipe"],
+                detached: processGroup,
                 // `RYNX_RUNNER_SESSION` = the child's session key (localThreadId, or `__cap__`
                 // for the shared capability child) so its LocalAgentHost scopes the private
                 // CODEX_HOME to this session. It is deliberately applied last.
@@ -492,6 +1146,8 @@ export class RunnerManager {
             lastUsedAt: this.now(),
             dead: false,
             completion,
+            terminalCleanupRetryFailures: 0,
+            processGroup,
             ...(sessionContext ? { sessionContext } : {}),
             caps: new Map(),
             terminals: new Map(),
@@ -550,37 +1206,24 @@ export class RunnerManager {
                 return;
             }
             case "mirror":
+                if (handle.dead)
+                    return;
+                if (this.bufferForkTargetMessage(handle, msg))
+                    return;
                 this.mirrorListener?.(msg.sessionId, msg.event);
+                if (msg.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, msg.sessionId, "turn");
+                }
                 return;
             case "rotate": {
                 if (handle.dead)
                     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(msg.to);
-                }
-                catch (error) {
-                    const reason = `runner Session context rotation failed: ${errorMessage(error)}`;
-                    void this.terminateHandle(handle, reason).catch((terminationError) => {
-                        logTerminationFailure(handle, terminationError);
-                    });
+                if (this.bufferForkTargetMessage(handle, msg))
                     return;
-                }
-                // Terminal transfer: alias the new session to THIS runner so its injection
-                // (and live/approval) route to the same child that still owns the pane.
-                this.handles.set(msg.to, handle);
-                this.liveSessionKeys.add(msg.to);
-                this.rotateListener?.({
-                    from: msg.from,
-                    to: msg.to,
-                    kind: msg.kind,
-                    ...(msg.agent ? { agent: msg.agent } : {}),
-                    ...(msg.model ? { model: msg.model } : {}),
-                    ...(msg.cwd ? { cwd: msg.cwd } : {}),
-                    ...(msg.parentSessionId ? { parentSessionId: msg.parentSessionId } : {}),
-                });
+                this.deliverRotateMessage(handle, msg);
                 return;
             }
             case "live.ready":
@@ -614,6 +1257,9 @@ export class RunnerManager {
             if (h === handle) {
                 this.handles.delete(key);
                 this.liveSessionKeys.delete(key);
+                if (!this.forkReservations.has(key)) {
+                    this.liveOptions.delete(key);
+                }
             }
         }
         const tail = handle.stderr.join("\n");
@@ -636,7 +1282,11 @@ export class RunnerManager {
     terminateHandle(handle, reason) {
         if (handle.termination)
             return handle.termination;
-        handle.termination = (async () => {
+        if (handle.terminalCleanupRetryTimer) {
+            clearTimeout(handle.terminalCleanupRetryTimer);
+            delete handle.terminalCleanupRetryTimer;
+        }
+        const attempt = (async () => {
             if (!handle.dead) {
                 try {
                     handle.transport.send({ t: "shutdown" });
@@ -646,16 +1296,37 @@ export class RunnerManager {
                 }
                 this.failHandle(handle, reason);
             }
-            signalChild(handle.child, "SIGTERM");
-            if (!(await waitForChildExit(handle.completion, this.shutdownGraceMs))) {
-                signalChild(handle.child, "SIGKILL");
-                if (!(await waitForChildExit(handle.completion, this.shutdownKillGraceMs))) {
-                    throw new Error(`runner child ${handle.child.pid ?? handle.key} did not exit after SIGKILL`);
-                }
+            this.signalChild(handle.child, "SIGTERM", handle.processGroup);
+            let childExited = await waitForChildExit(handle.completion, this.shutdownGraceMs);
+            if (!childExited) {
+                this.signalChild(handle.child, "SIGKILL", handle.processGroup);
+                childExited = await waitForChildExit(handle.completion, this.shutdownKillGraceMs);
+            }
+            const terminalStopped = handle.key === CAP_KEY
+                ? true
+                : await Promise.resolve(this.terminateTerminalServer(`${handle.key}-main`)).catch(() => false);
+            if (!childExited) {
+                throw new Error(`runner child ${handle.child.pid ?? handle.key} did not exit after SIGKILL`);
+            }
+            if (!terminalStopped) {
+                throw new Error(`runner terminal ${handle.key}-main remained live after child exit`);
             }
             this.childHandles.delete(handle);
         })();
-        return handle.termination;
+        handle.termination = attempt;
+        void attempt.then(() => {
+            this.finishAllTerminalInputHandoffs(handle);
+        }, () => {
+            if (handle.termination === attempt)
+                delete handle.termination;
+            handle.terminalCleanupRetryFailures += 1;
+            // A failed cleanup must not pin closeAndDrain forever. Keep the
+            // submission in the daemon activity snapshot, but release its gate
+            // reservation so maintenance returns a structured busy result.
+            this.preserveTerminalInputHandoffsAsActivity(handle);
+            this.scheduleTerminalInputCleanupRetry(handle);
+        });
+        return attempt;
     }
     reapIdle() {
         const now = this.now();
@@ -694,6 +1365,70 @@ export class RunnerManager {
         }
     }
 }
+function trackedTerminalSubmissions(tracker, data) {
+    const pasteStart = "\u001b[200~";
+    const pasteEnd = "\u001b[201~";
+    const input = tracker.pendingEscape + data;
+    tracker.pendingEscape = "";
+    const submissions = [];
+    for (let index = 0; index < input.length; index += 1) {
+        const character = input[index] ?? "";
+        if (character === "\u001b") {
+            const remaining = input.slice(index);
+            if (remaining.startsWith(pasteStart)) {
+                tracker.bracketedPaste = true;
+                tracker.previousWasCarriageReturn = false;
+                index += pasteStart.length - 1;
+                continue;
+            }
+            if (remaining.startsWith(pasteEnd)) {
+                tracker.bracketedPaste = false;
+                tracker.previousWasCarriageReturn = false;
+                index += pasteEnd.length - 1;
+                continue;
+            }
+            if (pasteStart.startsWith(remaining) || pasteEnd.startsWith(remaining)) {
+                tracker.pendingEscape = remaining;
+                break;
+            }
+        }
+        if (tracker.bracketedPaste) {
+            tracker.buffer += character;
+            tracker.previousWasCarriageReturn = false;
+            continue;
+        }
+        if (character === "\n" && tracker.previousWasCarriageReturn) {
+            tracker.previousWasCarriageReturn = false;
+            continue;
+        }
+        tracker.previousWasCarriageReturn = character === "\r";
+        if (character === "\r" || character === "\n") {
+            const command = tracker.buffer.trim();
+            tracker.buffer = "";
+            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");
+            }
+            continue;
+        }
+        if (character === "\b" || character === "\u007f") {
+            tracker.buffer = tracker.buffer.slice(0, -1);
+            continue;
+        }
+        if (character === "\u0015" || character === "\u0003") {
+            tracker.buffer = "";
+            continue;
+        }
+        // Printable text and tabs are enough to distinguish work-producing prompts
+        // from local TUI slash commands. Other control sequences are ignored.
+        if (character === "\u001b" || character === "\t" || character >= " ") {
+            tracker.buffer += character;
+        }
+    }
+    return submissions;
+}
 function validateSessionContext(context) {
     if (!context || typeof context !== "object") {
         throw new Error("Session context environment provider must return an object");
@@ -798,9 +1533,18 @@ function observeChildCompletion(child) {
         child.once("exit", onExit);
     });
 }
-function signalChild(child, signal) {
+function signalRunnerChild(child, signal, processGroup) {
     if (childHasExited(child))
         return;
+    if (processGroup && child.pid) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // The group may have exited between the completion check and the signal.
+        }
+    }
     try {
         child.kill(signal);
     }
@@ -836,3 +1580,14 @@ function logTerminationFailure(handle, error) {
         error: error instanceof Error ? error.message : String(error),
     }));
 }
+function capabilityForkResult(result) {
+    return result.ok
+        ? { ok: true }
+        : {
+            ok: false,
+            message: result.message ??
+                (result.reason === "unsupported"
+                    ? "Provider does not support Session fork"
+                    : "Provider Session is unavailable"),
+        };
+}