@rynx-ai/runtime 0.1.10 → 0.1.11-beta.10

package/dist/runner/child.js

@@ -1,5 +1,18 @@
 import { TerminalRegistry } from "../terminal/registry.js";
 import { toWireError } from "./protocol.js";
+const TRAEX_STARTUP_WATCH_MS = 20_000;
+const TRAEX_STARTUP_POLL_MS = 100;
+const TRAEX_PROMPT_RETRY_MS = 500;
+function normalizeTraexPane(pane) {
+    return pane.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function isTerminalProtocolResponse(input) {
+    // xterm answers terminal queries through the same onData channel as real
+    // keystrokes. CSI carries device/focus/position reports; OSC carries color
+    // query replies such as `OSC 10;rgb:... ST` and `OSC 11;rgb:... ST`.
+    // Neither is evidence that the user has taken over startup prompt handling.
+    return /^(?:\x1b\[(?:(?:\?|>)[0-9;]*c|[0-9;]*(?:n|R|t)|[IO])|\x1b\][0-9]+;[^\x07\x1b]*(?:\x07|\x1b\\))+$/.test(input);
+}
 export class RunnerSession {
     transport;
     executor;
@@ -7,6 +20,8 @@ export class RunnerSession {
     /** Live terminals hosted by this session, and per-attach client handles. */
     terminals = new TerminalRegistry();
     attachments = new Map();
+    attachmentThreadIds = new Map();
+    traexStartupWatchers = new Map();
     /** Opens are async; a close received before attach resolves tombstones the id. */
     pendingTerminalOpens = new Set();
     cancelledTerminalOpens = new Set();
@@ -46,7 +61,17 @@ export class RunnerSession {
                 });
                 return;
             case "term.input":
-                this.attachments.get(msg.attachId)?.write(Buffer.from(msg.dataB64, "base64").toString("utf8"));
+                {
+                    const localThreadId = this.attachmentThreadIds.get(msg.attachId);
+                    const input = Buffer.from(msg.dataB64, "base64").toString("utf8");
+                    // xterm sends device/focus reports through the same onData channel as
+                    // keystrokes. They must reach the TUI without pretending the user has
+                    // taken over startup prompt handling.
+                    if (!isTerminalProtocolResponse(input)) {
+                        this.cancelTraexStartupWatcher(localThreadId);
+                    }
+                    this.attachments.get(msg.attachId)?.write(input);
+                }
                 return;
             case "term.resize":
                 this.attachments.get(msg.attachId)?.resize(msg.cols, msg.rows);
@@ -57,6 +82,7 @@ export class RunnerSession {
                 }
                 const attachment = this.attachments.get(msg.attachId);
                 this.attachments.delete(msg.attachId);
+                this.attachmentThreadIds.delete(msg.attachId);
                 attachment?.kill();
                 return;
             }
@@ -114,9 +140,8 @@ export class RunnerSession {
                 from: localThreadId,
                 to: newId,
                 kind: meta.kind,
-                ...(meta.agent ? { agent: meta.agent } : {}),
-                ...(meta.model ? { model: meta.model } : {}),
-                ...(meta.cwd ? { cwd: meta.cwd } : {}),
+                workspace: meta.workspace,
+                execution: meta.execution,
                 ...(meta.parentSessionId ? { parentSessionId: meta.parentSessionId } : {}),
             });
         };
@@ -125,21 +150,17 @@ export class RunnerSession {
     /**
      * Eagerly bring up a session's codex-native live view: start the persistent
      * forwarder connection (which resume-subscribes to mirror every turn) and
-     * launch the detached `codex --remote` TUI, which CREATES the codex thread. The
-     * forwarder's connection sees the TUI's broadcast `thread/started`, binds, and
-     * subscribes — so the TUI is usable immediately (a fresh `--remote` needs no
-     * rollout) and its turns mirror to chat (reference implementation's model).
+     * launch the detached `codex --remote resume` TUI against the thread the
+     * structured runtime created. The forwarder subscribes to that same thread,
+     * so the TUI is usable immediately and its turns mirror to chat.
      */
     async ensureLive(msg) {
         const provider = this.liveProvider;
         try {
             const { emit, retarget } = this.mirrorChannel(msg.localThreadId);
             const started = await provider.ensureLiveCodexSession?.(msg.localThreadId, emit, {
-                ...(msg.cwd ? { cwd: msg.cwd } : {}),
-                ...(msg.runtime ? { runtime: msg.runtime } : {}),
-                ...(msg.reasoningEffort ? { reasoningEffort: msg.reasoningEffort } : {}),
-                ...(msg.agentName ? { agentName: msg.agentName } : {}),
-                ...(msg.agentSpec ? { agentSpec: msg.agentSpec } : {}),
+                workspace: msg.workspace,
+                execution: msg.execution,
                 retargetMirror: retarget,
             });
             if (!started) {
@@ -153,12 +174,24 @@ export class RunnerSession {
                 return;
             }
             this.liveIds.add(msg.localThreadId);
-            // Launch the TUI (fresh `--remote` → it creates the thread) so the forwarder
-            // captures the broadcast `thread/started` and binds. Re-launch when the pane
-            // is absent OR its process has died (`isAlive` probes `#{pane_dead}`) — so a
+            // Launch the TUI attached to the already-bound thread. Re-launch when the
+            // pane is absent OR its process has died (`isAlive` probes `#{pane_dead}`) — so a
             // reconnect after the TUI exited restarts it instead of skipping (a
             // launched-once guard would leave a dead "Pane is dead" husk forever).
             if (!this.terminals.get(`${msg.localThreadId}-main`)?.isAlive()) {
+                const terminalReady = provider.waitTerminalReady
+                    ? await provider.waitTerminalReady(msg.localThreadId)
+                    : true;
+                if (!terminalReady) {
+                    this.transport.send({
+                        t: "live.ready",
+                        reqId: msg.reqId,
+                        localThreadId: msg.localThreadId,
+                        ok: false,
+                        error: "Provider thread was not ready for Terminal resume",
+                    });
+                    return;
+                }
                 await this.launchCodexPane(msg.localThreadId, msg.cols, msg.rows);
             }
             const ready = msg.waitForReady === false
@@ -166,12 +199,27 @@ export class RunnerSession {
                 : provider.waitLiveReady
                     ? await provider.waitLiveReady(msg.localThreadId)
                     : true;
+            const terminal = this.terminals.get(`${msg.localThreadId}-main`);
+            const paneFailure = !ready && terminal && !terminal.isAlive()
+                ? terminal
+                    .capturePane()
+                    .split("\n")
+                    .map((line) => line.trim())
+                    .filter(Boolean)
+                    .slice(-6)
+                    .join(" ")
+                    .slice(-1_000)
+                : "";
+            const readinessError = provider.liveSessionError?.(msg.localThreadId)
+                ?? (paneFailure
+                    ? `Provider terminal exited before session discovery: ${paneFailure}`
+                    : "live session was not ready before timeout");
             this.transport.send({
                 t: "live.ready",
                 reqId: msg.reqId,
                 localThreadId: msg.localThreadId,
                 ok: ready,
-                ...(ready ? {} : { error: "live session was not ready before timeout" }),
+                ...(ready ? {} : { error: readinessError }),
             });
         }
         catch (error) {
@@ -189,6 +237,8 @@ export class RunnerSession {
         try {
             const input = msg.input ?? msg.text;
             const outcome = (await provider.injectMessage?.(msg.localThreadId, input)) ?? "notLive";
+            // App-server injection is independent of the Terminal TUI startup, so it
+            // must not cancel prompt handling for the pane that is still starting.
             this.transport.send({ t: "injected", reqId: msg.reqId, localThreadId: msg.localThreadId, outcome });
         }
         catch (error) {
@@ -226,7 +276,8 @@ export class RunnerSession {
         const spec = await this.liveProvider.codexTerminalSpec?.(localThreadId);
         if (!spec)
             return;
-        const term = this.terminals.getOrCreate(`${localThreadId}-main`, {
+        const terminalId = `${localThreadId}-main`;
+        const term = this.terminals.getOrCreate(terminalId, {
             cwd: spec.cwd,
             command: spec.command,
             args: spec.args,
@@ -234,8 +285,70 @@ export class RunnerSession {
             rows: rows ?? 40,
             ...(spec.env ? { env: spec.env } : {}),
         });
+        if (spec.skipTraexStartupPrompts) {
+            const watcher = Symbol(localThreadId);
+            this.traexStartupWatchers.set(localThreadId, watcher);
+            void this.skipTraexStartupPrompts(localThreadId, term, watcher);
+        }
         this.liveProvider.attachTerminalInjector?.(localThreadId, term);
     }
+    cancelTraexStartupWatcher(localThreadId) {
+        if (localThreadId)
+            this.traexStartupWatchers.delete(localThreadId);
+    }
+    async skipTraexStartupPrompts(localThreadId, terminal, watcher) {
+        const prompts = [
+            {
+                id: "welcome",
+                matches: (pane) => pane.includes("welcome to trae cli") && pane.includes("press enter to continue"),
+                dismiss: () => terminal.sendEnter(),
+            },
+            {
+                id: "migration",
+                matches: (pane) => pane.includes("legacy trae cli data detected") &&
+                    pane.includes("select what to import") &&
+                    (pane.includes("skip for now") || pane.includes("don't ask again")),
+                dismiss: () => terminal.interrupt(),
+            },
+            {
+                id: "hooks",
+                matches: (pane) => pane.includes("hooks need review") &&
+                    pane.includes("trust all and continue") &&
+                    pane.includes("continue without trusting"),
+                dismiss: () => terminal.interrupt(),
+            },
+        ];
+        let activePromptId;
+        let lastDismissedAt = 0;
+        const deadline = Date.now() + TRAEX_STARTUP_WATCH_MS;
+        const terminalId = `${localThreadId}-main`;
+        while (!this.shuttingDown &&
+            Date.now() < deadline &&
+            this.traexStartupWatchers.get(localThreadId) === watcher &&
+            this.terminals.get(terminalId) === terminal) {
+            // Do not treat a composer frame as completion: Traex can render it before
+            // the startup modals arrive. The bounded deadline stops this watcher.
+            const pane = normalizeTraexPane(terminal.capturePane());
+            const prompt = prompts.find((candidate) => candidate.matches(pane));
+            const now = Date.now();
+            if (!prompt) {
+                activePromptId = undefined;
+            }
+            else if (prompt.id !== activePromptId ||
+                now - lastDismissedAt >= TRAEX_PROMPT_RETRY_MS) {
+                prompt.dismiss();
+                activePromptId = prompt.id;
+                lastDismissedAt = now;
+            }
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, TRAEX_STARTUP_POLL_MS);
+                timer.unref();
+            });
+        }
+        if (this.traexStartupWatchers.get(localThreadId) === watcher) {
+            this.traexStartupWatchers.delete(localThreadId);
+        }
+    }
     stopLive() {
         for (const id of this.liveIds) {
             this.liveProvider.stopLiveCodexSession?.(id, {
@@ -314,6 +427,8 @@ export class RunnerSession {
             return;
         }
         this.attachments.set(msg.attachId, attachment);
+        if (msg.localThreadId)
+            this.attachmentThreadIds.set(msg.attachId, msg.localThreadId);
         attachment.onData((chunk) => this.transport.send({
             t: "term.data",
             attachId: msg.attachId,
@@ -321,6 +436,7 @@ export class RunnerSession {
         }));
         attachment.onExit((info) => {
             this.attachments.delete(msg.attachId);
+            this.attachmentThreadIds.delete(msg.attachId);
             this.transport.send({ t: "term.exit", attachId: msg.attachId, exitCode: info.exitCode });
         });
         this.transport.send({ t: "term.opened", attachId: msg.attachId, role });
@@ -343,7 +459,10 @@ export class RunnerSession {
             case "clearGoal":
                 return this.executor.clearGoal(args[0]);
             case "forkSession":
-                return this.executor.forkSession(args[0], args[1]);
+                if (!this.executor.forkSession) {
+                    throw new Error("Provider fork is unavailable");
+                }
+                return this.executor.forkSession(args[0], args[1], args[2]);
         }
     }
 }

package/dist/runner/manager.d.ts

@@ -15,8 +15,8 @@
  * transport drops in here later without touching `ConversationRuntime` or any
  * channel.
  */
-import { spawn as nodeSpawn } from "node:child_process";
-import { type AgentCapabilities, type AgentRuntimeId, type AgentSpec, type AppConfig, type CapabilityResult, type ModelListResponse, type ReasoningEffort, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type ThreadGoal } from "@rynx-ai/core";
+import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
+import { type AdmissionReservation, type AgentCapabilities, type AgentRuntimeId, type AppConfig, type CapabilityResult, type ModelListResponse, type ResolvedExecutionSnapshot, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent, type SessionWorkspaceSnapshot, type ThreadGoal } from "@rynx-ai/core";
 import { type CodexSessionStore } from "../host.js";
 import type { ResolveInteractionResult } from "../interactions.js";
 import { type InjectOutcome, type TerminalOpenErrorCode, type TerminalRole } from "./protocol.js";
@@ -43,6 +43,9 @@ export interface RunnerManagerOptions {
     runnerEntry?: string;
     /** Idle TTL (ms) after which an unused runner is reaped. */
     idleTtlMs?: number;
+    /** Maximum time without user/control activity that an active response may
+     * protect a detached runner from idle reaping. */
+    staleActiveTtlMs?: number;
     /** Background reap sweep interval (ms); `0` disables the timer (tests). */
     reapIntervalMs?: number;
     /** Grace period between SIGTERM and SIGKILL during runner shutdown. */
@@ -53,8 +56,22 @@ export interface RunnerManagerOptions {
     liveStartTimeoutMs?: number;
     /** Max wait for a Provider-native thread to become ready. */
     liveReadyTimeoutMs?: number;
+    /** Max wait for a native interrupt acknowledgement before reporting it
+     * unproven. Callers may then use the explicit force-stop path. */
+    liveInterruptTimeoutMs?: number;
+    /** Max wait for an accepted owner TUI submission to become observable as a
+     * mirrored response or a published native rotation. */
+    terminalInputHandoffTimeoutMs?: number;
+    /** Initial exponential backoff for retrying unproven terminal cleanup. */
+    terminalInputCleanupRetryMs?: number;
     /** Injected for tests. */
     spawn?: typeof nodeSpawn;
+    /** Injected for tests. Defaults to signaling the whole POSIX process group
+     * created for the runner child, with direct-child fallback. */
+    signalChild?: (child: ChildProcess, signal: NodeJS.Signals, processGroup: boolean) => void;
+    /** Injected for tests. Kills and verifies the deterministic private tmux
+     * server owned by a Session runner. */
+    terminateTerminalServer?: (terminalName: string) => boolean | Promise<boolean>;
     now?: () => number;
     /** Extra env merged into every spawned runner child — e.g. the control-plane
      *  URL + token so a claude-native PermissionRequest hook can POST back. */
@@ -62,6 +79,13 @@ export interface RunnerManagerOptions {
     /** Optional lifecycle context for Session runners. The shared `__cap__`
      * runner never opens one. */
     sessionContextProvider?: RunnerSessionContextProvider;
+    /** Dynamic process-wide admission fence. Existing cancellation and read-only
+     * inspection remain available; every path that may spawn or attach execution
+     * checks this immediately before admission. */
+    admissionOpen?: () => boolean;
+    /** Atomically reserves one work-producing admission while it crosses the
+     * asynchronous boundary into an observable live runner/turn. */
+    admissionReserve?: () => AdmissionReservation | undefined;
 }
 /** A session rotation reported by a runner child (claude `/clear`·`/fork`): the
  *  new session `to` is now aliased to `from`'s runner; carries meta to carry over. */
@@ -69,9 +93,8 @@ export interface RotateInfo {
     from: string;
     to: string;
     kind: "clear" | "fork";
-    agent?: string;
-    model?: string;
-    cwd?: string;
+    workspace: SessionWorkspaceSnapshot;
+    execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
 }
 /** Options for {@link RunnerManager.openTerminal}. */
@@ -116,9 +139,12 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly sessionStore;
     private readonly runnerEntry;
     private readonly idleTtlMs;
+    private readonly staleActiveTtlMs;
     private readonly spawn;
     private readonly childEnv;
     private readonly sessionContextProvider;
+    private readonly admissionOpen;
+    private readonly admissionReserve;
     private readonly now;
     private readonly defaultRuntime;
     private readonly handles;
@@ -128,8 +154,13 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly reapTimer;
     private readonly shutdownGraceMs;
     private readonly shutdownKillGraceMs;
+    private readonly signalChild;
+    private readonly terminateTerminalServer;
     private readonly liveStartTimeoutMs;
     private readonly liveReadyTimeoutMs;
+    private readonly liveInterruptTimeoutMs;
+    private readonly terminalInputHandoffTimeoutMs;
+    private readonly terminalInputCleanupRetryMs;
     private stopping;
     private stopPromise;
     /** Sink for mirrored {@link SessionEvent}s from every session's forwarder. */
@@ -140,6 +171,24 @@ export declare class RunnerManager implements AgentCapabilities {
     private readonly liveSessionKeys;
     /** Last live-start error per local session, surfaced by the control API. */
     private readonly liveErrors;
+    /** Last immutable launch snapshots seen for a Session. Used only to restore a
+     * target request that crossed a fork reservation boundary. */
+    private readonly liveOptions;
+    /** 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. */
+    private readonly forkReservations;
+    /** A native fork temporarily makes the source read-only so its canonical
+     * snapshot and Provider context are captured at the same boundary. */
+    private readonly sourceForkReservations;
+    /** Manager-wide fork de-duplication. LocalAgentHost only sees one source
+     * runner, so the fence must live here to cover concurrent source runners. */
+    private readonly forkOperations;
+    private readonly forkBufferedMessages;
+    private readonly forkBufferedTerminalInputs;
+    /** Owner TUI submissions accepted by the parent but not yet represented by a
+     * mirrored response or a durably published native rotation. */
+    private readonly terminalInputHandoffs;
     constructor(opts: RunnerManagerOptions);
     /**
      * Open a live terminal on the session's runner child (spawning it if needed).
@@ -166,33 +215,39 @@ export declare class RunnerManager implements AgentCapabilities {
     onMirror(listener: (sessionId: string, event: SessionEvent) => void): void;
     /** Register the sink for session rotations (claude `/clear`·`/fork`): the server
      *  records the new session's meta (carry-over agent/model/title). */
-    onRotate(listener: (rotation: RotateInfo) => void): void;
+    onRotate(listener: (rotation: RotateInfo) => void | Promise<void>): void;
+    /** Accepted TUI submissions that have not crossed into an observable runtime
+     * state. The daemon folds this into runningTurns after closing admission. */
+    pendingTerminalInputCount(): number;
+    private beginTerminalInputHandoffs;
+    private settleTerminalInputHandoff;
+    private settleTerminalRotationHandoff;
+    private currentTerminalSessionId;
+    private finishTerminalInputHandoff;
+    private finishAllTerminalInputHandoffs;
+    private preserveTerminalInputHandoffsAsActivity;
+    private scheduleTerminalInputCleanupRetry;
+    private expireTerminalInputHandoffs;
     /**
      * Eagerly bring up a session's codex-native live view (persistent forwarder +
      * detached `codex --remote` TUI) in its runner child, spawning the runner if
      * needed. Idempotent. Resolves true once the codex thread is bound; false for a
      * non-codex / non-live session (the caller then uses the normal run path).
      */
-    ensureLiveSession(localThreadId: string, opts?: {
-        cwd?: string;
+    ensureLiveSession(localThreadId: string, opts: {
+        workspace: SessionWorkspaceSnapshot;
+        execution: ResolvedExecutionSnapshot;
         cols?: number;
         rows?: number;
-        runtime?: AgentRuntimeId;
-        reasoningEffort?: ReasoningEffort;
-        agentName?: string;
-        agentSpec?: AgentSpec;
     }): Promise<boolean>;
     /** 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: string, opts?: {
-        cwd?: string;
+    startLiveSession(localThreadId: string, opts: {
+        workspace: SessionWorkspaceSnapshot;
+        execution: ResolvedExecutionSnapshot;
         cols?: number;
         rows?: number;
-        runtime?: AgentRuntimeId;
-        reasoningEffort?: ReasoningEffort;
-        agentName?: string;
-        agentSpec?: AgentSpec;
     }): Promise<boolean>;
     private requestLiveSession;
     lastLiveSessionError(localThreadId: string): string | undefined;
@@ -203,6 +258,7 @@ export declare class RunnerManager implements AgentCapabilities {
      * the session has no live forwarder (caller falls back to the run path).
      */
     injectMessage(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
+    private injectMessageAdmitted;
     /**
      * Interrupt a session's active live turn — the web Stop button (codex
      * `turn/interrupt`, claude Escape). Best-effort: resolves false with NO spawn
@@ -215,7 +271,16 @@ export declare class RunnerManager implements AgentCapabilities {
     getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
     setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
     clearGoal(localThreadId: string): Promise<CapabilityResult>;
-    forkSession(currentLocalThreadId: string, newLocalThreadId: string): Promise<CapabilityResult>;
+    forkSession(currentLocalThreadId: string, newLocalThreadId: string, options: {
+        workspace: SessionWorkspaceSnapshot;
+        execution: ResolvedExecutionSnapshot;
+        beforeProviderFork: () => Promise<void>;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    }>;
     /**
      * Backend-free runtime readiness (not part of `AgentCapabilities`; surfaced for
      * the control console). Never spawns a runner.
@@ -226,18 +291,38 @@ export declare class RunnerManager implements AgentCapabilities {
     }): Promise<import("../host.js").CodexRuntimeStatus>;
     /** Stop the runner bound to one session (if any), rejecting its in-flight work. */
     stopRunner(localThreadId: string): void;
+    /** Force-stop and join the runner bound to one Session. Unlike stopRunner,
+     * completion proves that the child process has exited. */
+    terminateLiveSession(localThreadId: string): Promise<boolean>;
     /** Stop every runner and join all child exits. Idempotent across concurrent calls. */
     stop(): Promise<void>;
+    private handleForCleanup;
     /** 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). */
     private forwardCap;
     private getOrSpawn;
+    private assertAdmissionOpen;
+    private reserveAdmission;
+    private performManagedFork;
+    private performClaudeManagedFork;
+    private bufferForkTargetMessage;
+    private reservedForkTarget;
+    private deliverForkBufferedMessage;
+    private deliverRotateMessage;
     private spawnHandle;
     private onChildMessage;
     /** Mark a handle dead and reject every pending run/cap with the exit reason. */
     private failHandle;
     private terminateHandle;
     private reapIdle;
+    /** Close server-side runtime state before fencing a Provider that stayed
+     * active past its hard inactivity deadline. The child transport is closed by
+     * terminateHandle immediately afterwards, so these are the final events for
+     * the abandoned responses. */
+    private failStaleActiveResponses;
+    /** Track only response lifecycle, not output volume. Output deltas from a
+     * runaway TUI/Provider must not refresh the stale-active deadline. */
+    private observeHandleRuntimeEvent;
     private openSessionContext;
 }