@rynx-ai/runtime 0.1.11-beta.32 → 0.1.11-beta.34

package/dist/runner-main.js

@@ -20,6 +20,8 @@ import { loadConfig } from "@rynx-ai/core";
 import { FileCodexSessionStore, LocalAgentHost, resolveCodexSessionStorePath, } from "./host.js";
 import { RunnerSession } from "./runner/child.js";
 import { StdioRunnerTransport } from "./runner/transport.js";
+import { reapOrphanedTerminals } from "./terminal/tmux.js";
+import { reconcileRuntimeProcesses } from "./codex-app-server/process-registry.js";
 // stdout is the protocol channel — keep all logging on stderr.
 console.log = console.error.bind(console);
 console.info = console.error.bind(console);
@@ -34,6 +36,8 @@ for (const stream of [process.stdout, process.stderr]) {
     });
 }
 async function main() {
+    reapOrphanedTerminals();
+    reconcileRuntimeProcesses();
     const config = loadConfig();
     const sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config));
     const sessionId = process.env.RYNX_RUNNER_SESSION;
@@ -51,8 +55,7 @@ async function main() {
     const transport = new StdioRunnerTransport(process.stdin, process.stdout);
     let runner;
     transport.onClose(() => {
-        runner?.shutdown();
-        process.exit(0);
+        void runner?.shutdown().finally(() => process.exit(0));
     });
     runner = new RunnerSession({
         transport,
@@ -64,7 +67,9 @@ async function main() {
     });
     // A parent SIGTERM (idle reap / shutdown) uses the same ordered cleanup path
     // as the protocol shutdown before ending the process.
-    process.on("SIGTERM", () => runner?.shutdown());
+    process.on("SIGTERM", () => {
+        void runner?.shutdown();
+    });
 }
 void main().catch((error) => {
     console.error(error);

package/dist/terminal/codex-tui.d.ts

@@ -49,6 +49,10 @@ export interface LaunchCodexTuiOptions extends CodexRemoteArgs {
     env?: Record<string, string>;
     cols?: number;
     rows?: number;
+    scrollback?: number;
+    tmuxAllowPassthrough?: boolean;
+    tmuxStartOnAttach?: boolean;
+    keepAliveAfterExit?: boolean;
 }
 /**
  * Create (idempotently) the codex TUI terminal in the registry, running the real

package/dist/terminal/codex-tui.js

@@ -25,11 +25,16 @@ export function buildCodexRemoteArgs({ remoteUrl, threadId, configOverrides = []
  */
 export function launchCodexTui(opts) {
     opts.registry.getOrCreate(opts.terminalId, {
+        lifecycle: "auxiliary",
         cwd: opts.cwd,
         command: opts.codexBin,
         args: buildCodexRemoteArgs(opts),
         env: opts.env,
         cols: opts.cols,
         rows: opts.rows,
+        scrollback: opts.scrollback ?? 100_000,
+        tmuxAllowPassthrough: opts.tmuxAllowPassthrough ?? true,
+        tmuxStartOnAttach: opts.tmuxStartOnAttach ?? false,
+        keepAliveAfterExit: opts.keepAliveAfterExit ?? false,
     });
 }

package/dist/terminal/control-parser.d.ts

@@ -0,0 +1,39 @@
+export declare class TmuxControlProtocolError extends Error {
+    readonly name = "TmuxControlProtocolError";
+}
+export interface TmuxControlParserOptions {
+    onOutput(chunk: Uint8Array): void;
+    onControlLine(line: Uint8Array): void;
+    outputChunkBytes?: number;
+    maxControlLineBytes?: number;
+}
+/** Incremental parser for tmux control mode.
+ *
+ * `%output` payloads are decoded directly into fixed-size output chunks. Only
+ * the possible tail of one `\ooo` escape survives between writes. Other
+ * control notifications stay line-oriented and are capped independently.
+ */
+export declare class TmuxControlParser {
+    private readonly onOutput;
+    private readonly onControlLine;
+    private readonly outputChunkBytes;
+    private readonly maxControlLineBytes;
+    private mode;
+    private line;
+    private pane;
+    private escape;
+    private output;
+    private outputLength;
+    private ended;
+    constructor(options: TmuxControlParserOptions);
+    get retainedBytes(): number;
+    write(input: Uint8Array): void;
+    end(): void;
+    private consume;
+    private consumeGeneric;
+    private finishControlLine;
+    private consumePayload;
+    private flushEscapeLiteral;
+    private pushOutput;
+    private flushOutput;
+}

package/dist/terminal/control-parser.js

@@ -0,0 +1,172 @@
+const OUTPUT_PREFIX = Buffer.from("%output ", "ascii");
+const DEFAULT_OUTPUT_CHUNK_BYTES = 64 * 1024;
+const DEFAULT_MAX_CONTROL_LINE_BYTES = 16 * 1024;
+const MAX_PANE_TOKEN_BYTES = 256;
+export class TmuxControlProtocolError extends Error {
+    name = "TmuxControlProtocolError";
+}
+/** Incremental parser for tmux control mode.
+ *
+ * `%output` payloads are decoded directly into fixed-size output chunks. Only
+ * the possible tail of one `\ooo` escape survives between writes. Other
+ * control notifications stay line-oriented and are capped independently.
+ */
+export class TmuxControlParser {
+    onOutput;
+    onControlLine;
+    outputChunkBytes;
+    maxControlLineBytes;
+    mode = "prefix";
+    line = [];
+    pane = [];
+    escape = [];
+    output;
+    outputLength = 0;
+    ended = false;
+    constructor(options) {
+        this.onOutput = options.onOutput;
+        this.onControlLine = options.onControlLine;
+        this.outputChunkBytes = positiveInteger(options.outputChunkBytes ?? DEFAULT_OUTPUT_CHUNK_BYTES, "outputChunkBytes");
+        this.maxControlLineBytes = positiveInteger(options.maxControlLineBytes ?? DEFAULT_MAX_CONTROL_LINE_BYTES, "maxControlLineBytes");
+        this.output = Buffer.allocUnsafe(this.outputChunkBytes);
+    }
+    get retainedBytes() {
+        return this.line.length + this.pane.length + this.escape.length + this.outputLength;
+    }
+    write(input) {
+        if (this.ended)
+            throw new TmuxControlProtocolError("tmux control parser has ended");
+        const bytes = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        for (const byte of bytes)
+            this.consume(byte);
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        if (this.mode === "payload") {
+            this.flushEscapeLiteral();
+            this.flushOutput();
+        }
+        this.line = [];
+        this.pane = [];
+        this.escape = [];
+    }
+    consume(byte) {
+        if (this.mode === "payload") {
+            this.consumePayload(byte);
+            return;
+        }
+        if (this.mode === "pane") {
+            if (byte === 0x20) {
+                if (this.pane.length === 0) {
+                    this.line = [...OUTPUT_PREFIX];
+                    this.consumeGeneric(byte);
+                }
+                else {
+                    this.mode = "payload";
+                    this.pane = [];
+                }
+                return;
+            }
+            if (byte === 0x0a) {
+                this.line = [...OUTPUT_PREFIX, ...this.pane];
+                this.pane = [];
+                this.finishControlLine();
+                return;
+            }
+            this.pane.push(byte);
+            if (this.pane.length > MAX_PANE_TOKEN_BYTES) {
+                throw new TmuxControlProtocolError("tmux output pane token exceeded its limit");
+            }
+            return;
+        }
+        this.consumeGeneric(byte);
+    }
+    consumeGeneric(byte) {
+        if (byte === 0x0a) {
+            this.finishControlLine();
+            return;
+        }
+        this.line.push(byte);
+        if (this.line.length > this.maxControlLineBytes) {
+            throw new TmuxControlProtocolError(`tmux control line exceeded ${this.maxControlLineBytes} bytes`);
+        }
+        if (this.line.length === OUTPUT_PREFIX.length) {
+            let outputPrefix = true;
+            for (let index = 0; index < OUTPUT_PREFIX.length; index += 1) {
+                if (this.line[index] !== OUTPUT_PREFIX[index]) {
+                    outputPrefix = false;
+                    break;
+                }
+            }
+            if (outputPrefix) {
+                this.line = [];
+                this.mode = "pane";
+            }
+        }
+    }
+    finishControlLine() {
+        if (this.line.at(-1) === 0x0d)
+            this.line.pop();
+        this.onControlLine(Uint8Array.from(this.line));
+        this.line = [];
+        this.pane = [];
+        this.mode = "prefix";
+    }
+    consumePayload(byte) {
+        if (byte === 0x0a) {
+            this.flushEscapeLiteral();
+            this.flushOutput();
+            this.mode = "prefix";
+            return;
+        }
+        if (this.escape.length > 0) {
+            this.escape.push(byte);
+            if (this.escape.length === 4) {
+                if (this.escape.slice(1).every(isOctalDigit)) {
+                    this.pushOutput((this.escape[1] - 0x30) * 64 +
+                        (this.escape[2] - 0x30) * 8 +
+                        (this.escape[3] - 0x30));
+                }
+                else {
+                    for (const escapedByte of this.escape)
+                        this.pushOutput(escapedByte);
+                }
+                this.escape = [];
+            }
+            return;
+        }
+        if (byte === 0x5c) {
+            this.escape = [byte];
+            return;
+        }
+        this.pushOutput(byte);
+    }
+    flushEscapeLiteral() {
+        for (const byte of this.escape)
+            this.pushOutput(byte);
+        this.escape = [];
+    }
+    pushOutput(byte) {
+        this.output[this.outputLength] = byte;
+        this.outputLength += 1;
+        if (this.outputLength === this.output.byteLength)
+            this.flushOutput();
+    }
+    flushOutput() {
+        if (this.outputLength === 0)
+            return;
+        this.onOutput(Uint8Array.from(this.output.subarray(0, this.outputLength)));
+        this.outputLength = 0;
+    }
+}
+function isOctalDigit(value) {
+    return value >= 0x30 && value <= 0x37;
+}
+function positiveInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${field} must be a positive integer`);
+    }
+    return value;
+}

package/dist/terminal/registry.d.ts

@@ -2,39 +2,41 @@
  * Per-runner registry of live {@link TmuxTerminal}s, keyed by terminal id.
  *
  * Owns terminal lifecycle. Read-only vs read-write is decided PURELY by the
- * requested role (the caller derives it from the viewer's permission level),
- * exactly like reference implementation's terminal attach (`terminal_attach.py`: `read_only`
- * from the URL → `-r`). There is deliberately NO stateful "first owner wins,
+ * requested role (the caller derives it from the viewer's permission level).
+ * There is deliberately NO stateful "first owner wins,
  * later owners downgraded" slot: that rynx-only mechanism leaked its owner slot
  * across a detach (the release ran on the attachment's `onExit`, which the
  * runner child's own `onExit` clobbered), so a tab switch away then back
  * re-attached read-only and silently dropped every keystroke. Multiple
  * read-write owners coexisting is fine — tmux merges their input.
  */
-import { TmuxTerminal, type TerminalAttachment, type TmuxTerminalOptions } from "./tmux.js";
+import { TmuxTerminal, type PreparedTerminalAttachment, type TmuxTerminalOptions } from "./tmux.js";
 export type TerminalRole = "owner" | "read-only";
-export interface AttachResult {
-    attachment: TerminalAttachment;
-    /** The granted role — always the requested role (no downgrade). */
+export type TerminalLifecycle = "required" | "auxiliary";
+export type TerminalLaunchOptions = Omit<TmuxTerminalOptions, "name"> & {
+    lifecycle: TerminalLifecycle;
+};
+export interface PrepareResult {
+    preparation: PreparedTerminalAttachment;
     role: TerminalRole;
 }
 export declare class TerminalRegistry {
     private readonly terminals;
     get(id: string): TmuxTerminal | undefined;
+    lifecycle(id: string): TerminalLifecycle | undefined;
     has(id: string): boolean;
     /** Create + start a terminal under `id`, reusing a LIVE existing one. If the
      *  existing terminal's tmux session died (its TUI process exited), drop it and
      *  relaunch — so a reconnect after the pane died restarts the terminal instead
      *  of attaching to a dead session. `name` is derived from the id so the tmux
      *  socket is unique per terminal. */
-    getOrCreate(id: string, opts: Omit<TmuxTerminalOptions, "name">): TmuxTerminal;
-    /** Attach a client at the requested role (`owner` → read-write, `read-only`
-     *  → `tmux attach -r`). Throws if the terminal id is unknown (create it
-     *  first). */
-    attach(id: string, requestedRole: TerminalRole, dims?: {
+    getOrCreate(id: string, opts: TerminalLaunchOptions): TmuxTerminal;
+    /** Move a live resource to a new logical id. Target collision is atomic. */
+    transfer(sourceId: string, targetId: string): void;
+    prepare(id: string, requestedRole: TerminalRole, dims?: {
         cols?: number;
         rows?: number;
-    }): Promise<AttachResult>;
+    }): Promise<PrepareResult>;
     /** Kill a terminal's tmux server and drop it. */
     close(id: string): void;
     /** Kill every terminal (runner shutdown). */

package/dist/terminal/registry.js

@@ -2,20 +2,22 @@
  * Per-runner registry of live {@link TmuxTerminal}s, keyed by terminal id.
  *
  * Owns terminal lifecycle. Read-only vs read-write is decided PURELY by the
- * requested role (the caller derives it from the viewer's permission level),
- * exactly like reference implementation's terminal attach (`terminal_attach.py`: `read_only`
- * from the URL → `-r`). There is deliberately NO stateful "first owner wins,
+ * requested role (the caller derives it from the viewer's permission level).
+ * There is deliberately NO stateful "first owner wins,
  * later owners downgraded" slot: that rynx-only mechanism leaked its owner slot
  * across a detach (the release ran on the attachment's `onExit`, which the
  * runner child's own `onExit` clobbered), so a tab switch away then back
  * re-attached read-only and silently dropped every keystroke. Multiple
  * read-write owners coexisting is fine — tmux merges their input.
  */
-import { TmuxTerminal } from "./tmux.js";
+import { TmuxTerminal, } from "./tmux.js";
 export class TerminalRegistry {
     terminals = new Map();
     get(id) {
-        return this.terminals.get(id);
+        return this.terminals.get(id)?.terminal;
+    }
+    lifecycle(id) {
+        return this.terminals.get(id)?.lifecycle;
     }
     has(id) {
         return this.terminals.has(id);
@@ -27,41 +29,57 @@ export class TerminalRegistry {
      *  socket is unique per terminal. */
     getOrCreate(id, opts) {
         const existing = this.terminals.get(id);
-        if (existing && existing.isAlive())
-            return existing;
+        if (existing && existing.terminal.isAlive()) {
+            if (existing.lifecycle !== opts.lifecycle) {
+                throw new Error(`terminal ${id} lifecycle does not match its live resource`);
+            }
+            return existing.terminal;
+        }
         if (existing) {
             // Dead pane (its TUI exited) — kill the husk + drop it before relaunching.
             this.terminals.delete(id);
             try {
-                existing.kill();
+                existing.terminal.kill();
             }
             catch {
                 // already gone — fine
             }
         }
-        const terminal = new TmuxTerminal({ ...opts, name: id });
+        const { lifecycle, ...terminalOptions } = opts;
+        const terminal = new TmuxTerminal({ ...terminalOptions, name: id });
         terminal.start();
-        this.terminals.set(id, terminal);
+        this.terminals.set(id, { terminal, lifecycle });
         return terminal;
     }
-    /** Attach a client at the requested role (`owner` → read-write, `read-only`
-     *  → `tmux attach -r`). Throws if the terminal id is unknown (create it
-     *  first). */
-    async attach(id, requestedRole, dims) {
+    /** Move a live resource to a new logical id. Target collision is atomic. */
+    transfer(sourceId, targetId) {
+        if (sourceId === targetId)
+            return;
+        if (this.terminals.has(targetId)) {
+            throw new Error(`terminal ${targetId} already exists`);
+        }
+        const source = this.terminals.get(sourceId);
+        if (!source)
+            throw new Error(`terminal ${sourceId} does not exist`);
+        this.terminals.delete(sourceId);
+        this.terminals.set(targetId, source);
+    }
+    async prepare(id, requestedRole, dims) {
         const terminal = this.terminals.get(id);
         if (!terminal)
             throw new Error(`terminal ${id} does not exist`);
-        const attachment = await terminal.attach(requestedRole, dims);
-        return { attachment, role: requestedRole };
+        const preparation = await terminal.terminal.prepare(requestedRole, dims);
+        return { preparation, role: requestedRole };
     }
     /** Kill a terminal's tmux server and drop it. */
     close(id) {
-        const terminal = this.terminals.get(id);
-        if (!terminal)
+        const entry = this.terminals.get(id);
+        if (!entry)
             return;
-        // reference implementation removes the resource from its registry before best-effort close.
+        // Remove the resource before best-effort close so a failed kill cannot
+        // leave a dead registry entry that later attaches will reuse.
         this.terminals.delete(id);
-        terminal.kill();
+        entry.terminal.kill();
     }
     /** Kill every terminal (runner shutdown). */
     closeAll() {

package/dist/terminal/spool.d.ts

@@ -0,0 +1,47 @@
+export interface TerminalSpoolRead {
+    data: Uint8Array;
+    nextOffset: number;
+    done: boolean;
+    finalOffset?: number;
+}
+export declare class TerminalSpoolCapacityError extends Error {
+    readonly name = "TerminalSpoolCapacityError";
+}
+export declare class TerminalSpoolProtocolError extends Error {
+    readonly name = "TerminalSpoolProtocolError";
+}
+/**
+ * A single-reader byte log backed by disposable fixed-size files. Producers
+ * append while the consumer pulls with an exact monotonic offset. Fully
+ * consumed segments are unlinked immediately, so retained disk is bounded by
+ * viewer lag rather than the lifetime output volume.
+ */
+export declare class SegmentedTerminalSpool {
+    readonly directory: string;
+    readonly segmentBytes: number;
+    readonly quotaBytes: number | undefined;
+    private readonly segments;
+    private writeOffset;
+    private readOffset;
+    private ended;
+    private closed;
+    private failure;
+    private pending;
+    constructor(options?: {
+        segmentBytes?: number;
+        quotaBytes?: number;
+        directory?: string;
+    });
+    get retainedBytes(): number;
+    get finalOffset(): number | undefined;
+    append(input: Uint8Array): void;
+    end(): void;
+    fail(error: Error): void;
+    read(offset: number, maxBytes: number): Promise<TerminalSpoolRead>;
+    close(): void;
+    private assertWritable;
+    private createSegment;
+    private settlePending;
+    private readNow;
+    private discardConsumedSegments;
+}