@rynx-ai/runtime 0.1.0

package/dist/runner/transport.d.ts

@@ -0,0 +1,36 @@
+import type { Readable, Writable } from "node:stream";
+import { type FromChild, type ToChild } from "./protocol.js";
+export interface RunnerTransport<TSend, TRecv> {
+    /** Send one message. Best-effort: a dead peer is surfaced via {@link onClose}. */
+    send(msg: TSend): void;
+    /** Register the single message handler. */
+    onMessage(cb: (msg: TRecv) => void): void;
+    /** Register a close/error handler (peer stream ended). */
+    onClose(cb: (error?: Error) => void): void;
+    /** Stop reading and release the readline interface. */
+    close(): void;
+}
+/** Parent-side transport: sends {@link ToChild}, receives {@link FromChild}. */
+export type ParentTransport = RunnerTransport<ToChild, FromChild>;
+/** Child-side transport: sends {@link FromChild}, receives {@link ToChild}. */
+export type ChildTransport = RunnerTransport<FromChild, ToChild>;
+/**
+ * NDJSON-over-streams transport. `input` is line-read for inbound messages;
+ * `output` receives one JSON line per {@link send}. Used on both ends:
+ * - parent: `input = child.stdout`, `output = child.stdin`
+ * - child:  `input = process.stdin`, `output = process.stdout`
+ */
+export declare class StdioRunnerTransport<TSend, TRecv> implements RunnerTransport<TSend, TRecv> {
+    private readonly input;
+    private readonly output;
+    private readonly rl;
+    private messageHandler;
+    private closeHandler;
+    private closed;
+    constructor(input: Readable, output: Writable);
+    send(msg: TSend): void;
+    onMessage(cb: (msg: TRecv) => void): void;
+    onClose(cb: (error?: Error) => void): void;
+    close(): void;
+    private handleClose;
+}

package/dist/runner/transport.js

@@ -0,0 +1,72 @@
+/**
+ * Duplex message transport between the parent and a runner child. Abstracted so
+ * the {@link import("./manager.js").RunnerManager} and
+ * {@link import("./child.js").RunnerSession} depend only on this seam: today the
+ * only implementation is {@link StdioRunnerTransport} (NDJSON over a pair of
+ * streams — child stdin/stdout locally), and a remote tunnel transport can drop
+ * in later without touching either side.
+ *
+ * The NDJSON-over-stream framing (readline per line, write a JSON line) mirrors
+ * the codex app-server transport (`codex-app-server/transport.ts`).
+ */
+import readline from "node:readline";
+import { decodeMessage, encodeMessage } from "./protocol.js";
+/**
+ * NDJSON-over-streams transport. `input` is line-read for inbound messages;
+ * `output` receives one JSON line per {@link send}. Used on both ends:
+ * - parent: `input = child.stdout`, `output = child.stdin`
+ * - child:  `input = process.stdin`, `output = process.stdout`
+ */
+export class StdioRunnerTransport {
+    input;
+    output;
+    rl;
+    messageHandler = null;
+    closeHandler = null;
+    closed = false;
+    constructor(input, output) {
+        this.input = input;
+        this.output = output;
+        // A broken pipe (peer died) must not throw on the writable — surface it as a
+        // close instead, so the manager/session can clean up the run.
+        this.output.on("error", (error) => {
+            if (error.code === "EPIPE") {
+                this.handleClose();
+                return;
+            }
+            this.handleClose(error);
+        });
+        this.rl = readline.createInterface({ input: this.input, crlfDelay: Infinity });
+        this.rl.on("line", (line) => {
+            const msg = decodeMessage(line);
+            if (msg && this.messageHandler) {
+                this.messageHandler(msg);
+            }
+        });
+        this.rl.on("close", () => this.handleClose());
+        this.input.on("error", (error) => this.handleClose(error));
+    }
+    send(msg) {
+        if (this.closed) {
+            return;
+        }
+        this.output.write(encodeMessage(msg));
+    }
+    onMessage(cb) {
+        this.messageHandler = cb;
+    }
+    onClose(cb) {
+        this.closeHandler = cb;
+    }
+    close() {
+        this.closed = true;
+        this.rl.close();
+    }
+    handleClose(error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.closeHandler?.(error);
+    }
+}

package/dist/runner-main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/runner-main.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Runner child entry point. The parent {@link import("./runner/manager.js").RunnerManager}
+ * spawns one of these per session (`localThreadId`) and talks to it over
+ * stdin/stdout (NDJSON protocol). This process owns the session's single
+ * execution backend (codex app-server / claude PTY) via {@link LocalAgentHost}.
+ *
+ * stdout is reserved for the protocol — every log MUST go to stderr (which the
+ * parent captures for the crash exit-report). We route `console.log/info/debug`
+ * to stderr up front so a stray log can't corrupt the NDJSON stream.
+ *
+ * CodexSessionStore note: this child reads/writes the same on-disk store as the
+ * parent (decision A). Because there is one runner per session, the child is the
+ * sole writer of its own session record (codexSessionId / fork), so cross-process
+ * lost-update risk is limited to the parent's read-only access (mirror index /
+ * active-session display, which tolerate atomic-rename reads). A parent-of-record
+ * design (ship-in / emit-out) is the remote-ready follow-up.
+ */
+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";
+// stdout is the protocol channel — keep all logging on stderr.
+console.log = console.error.bind(console);
+console.info = console.error.bind(console);
+console.debug = console.error.bind(console);
+// Under a parent pipe a broken stdout/stderr (parent gone) must not crash us
+// with an unhandled stream 'error'; we exit on transport close instead.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on("error", (err) => {
+        if (err.code === "EPIPE")
+            return;
+        throw err;
+    });
+}
+function main() {
+    const config = loadConfig();
+    const sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config));
+    const executor = new LocalAgentHost({
+        config,
+        sessionStore,
+        // The manager spawns one child per session and passes its key here so the
+        // host's private CODEX_HOME is scoped to this session (see manager.spawnHandle).
+        ...(process.env.RYNX_RUNNER_SESSION ? { sessionId: process.env.RYNX_RUNNER_SESSION } : {}),
+    });
+    const transport = new StdioRunnerTransport(process.stdin, process.stdout);
+    transport.onClose(() => process.exit(0));
+    // eslint-disable-next-line no-new -- the session wires itself to the transport.
+    new RunnerSession({
+        transport,
+        executor,
+        onShutdown: () => {
+            transport.close();
+            process.exit(0);
+        },
+    });
+    // A parent SIGTERM (idle reap / shutdown) ends the process; the OS tears down
+    // the child app-server / PTY with it.
+    process.on("SIGTERM", () => process.exit(0));
+}
+main();

package/dist/runtime-status.d.ts

@@ -0,0 +1,16 @@
+import { type AgentRuntimeId, type AppConfig } from "@rynx-ai/core";
+import { type CodexCommandRunner, type CodexRuntimeStatus } from "./host.js";
+import { type CodexSessionStore } from "./codex-session-store.js";
+export interface ProbeRuntimeStatusDeps {
+    /** Override the codex/traex command runner (tests inject a fake). */
+    commandRunner?: CodexCommandRunner;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Probe a runtime's readiness without instantiating an execution backend.
+ *
+ * @param runtime which local runtime to probe
+ * @param config app config (for binary resolution)
+ * @param sessionStore the shared session store (writability check)
+ */
+export declare function probeRuntimeStatus(runtime: AgentRuntimeId, config: AppConfig, sessionStore: CodexSessionStore, deps?: ProbeRuntimeStatusDeps): Promise<CodexRuntimeStatus>;

package/dist/runtime-status.js

@@ -0,0 +1,80 @@
+/**
+ * Backend-free runtime readiness probe.
+ *
+ * The parent control plane no longer holds an execution backend (runners own
+ * the codex app-server / claude PTY), so it must answer "is this runtime usable
+ * on this machine?" without spinning one up. This mirrors omnigent's model,
+ * where readiness is `which(binary) + a usable credential` rather than a live
+ * app-server. For codex/traex that is a one-shot `<bin> login status` (no
+ * app-server); for claude it reuses {@link readClaudeStatus} (SDK + credentials).
+ *
+ * It returns the same {@link CodexRuntimeStatus} shape the host's status probe
+ * produces, so a future control console renders one status regardless of where
+ * execution happens.
+ */
+import { access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { getRuntimeProfile, resolveRuntimeBinary, resolveRuntimeHome, resolveRuntimeSessionsRoot, toErrorMessage, } from "@rynx-ai/core";
+import { readClaudeStatus } from "./claude/status.js";
+import { SpawnCodexCommandRunner, parseCodexLoginStatus, } from "./host.js";
+/**
+ * Probe a runtime's readiness without instantiating an execution backend.
+ *
+ * @param runtime which local runtime to probe
+ * @param config app config (for binary resolution)
+ * @param sessionStore the shared session store (writability check)
+ */
+export async function probeRuntimeStatus(runtime, config, sessionStore, deps = {}) {
+    if (runtime === "claude") {
+        return readClaudeStatus({ sessionStore, env: deps.env });
+    }
+    const profile = getRuntimeProfile(runtime);
+    const name = profile.displayName;
+    const issues = [];
+    let codexAvailable = true;
+    let loggedIn = false;
+    let authMode = null;
+    const commandRunner = deps.commandRunner ?? new SpawnCodexCommandRunner(resolveRuntimeBinary(runtime));
+    try {
+        const result = await commandRunner.capture({ args: ["login", "status"] });
+        const parsed = parseCodexLoginStatus(result.exitCode, `${result.stdout}\n${result.stderr}`.trim());
+        loggedIn = parsed.loggedIn;
+        authMode = parsed.authMode;
+        issues.push(...parsed.issues);
+    }
+    catch (error) {
+        codexAvailable = false;
+        issues.push(`${name} CLI is unavailable: ${toErrorMessage(error)}`);
+    }
+    const sessionStoreWritable = await sessionStore.isWritable();
+    if (!sessionStoreWritable) {
+        issues.push(`Session store is not writable: ${sessionStore.filePath}`);
+    }
+    const sessionsAccessible = await checkRuntimeSessionsAccessible(profile);
+    if (!sessionsAccessible) {
+        issues.push(`${name} session directory ${resolveRuntimeSessionsRoot(profile)} is not accessible to this process.`);
+    }
+    return {
+        codex_available: codexAvailable,
+        logged_in: loggedIn,
+        auth_mode: authMode,
+        session_store_writable: sessionStoreWritable,
+        codex_sessions_accessible: sessionsAccessible,
+        issues,
+    };
+}
+/** The runtime's rollout `sessions/` dir (or its home) must be read+write accessible. */
+async function checkRuntimeSessionsAccessible(profile) {
+    const sessionsPath = resolveRuntimeSessionsRoot(profile);
+    const runtimeHome = resolveRuntimeHome(profile);
+    for (const target of [sessionsPath, runtimeHome]) {
+        try {
+            await access(target, fsConstants.R_OK | fsConstants.W_OK);
+            return true;
+        }
+        catch {
+            // Try the next candidate (sessions dir may not exist yet; home is enough).
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * claude-native interactive TUI launcher — the claude analogue of
+ * {@link ./codex-tui.ts}. This launches the real interactive `claude` TUI in the
+ * session's tmux pane so it can be co-driven: the web injects via tmux send-keys
+ * and its transcript mirrors back to chat.
+ *
+ * The `--settings` flag carries rynx's claude-native hooks (see
+ * {@link ../claude/native-hooks.ts}); approvals flow through the PermissionRequest
+ * hook, so NO `--dangerously-skip-permissions` is passed (unlike a blind headless
+ * run). Trust pre-seeding (`ensureProjectTrusted`) is done by the caller before
+ * launch so the daemon-spawned TUI never blocks on a first-run prompt.
+ */
+export interface ClaudeTuiArgs {
+    /** The claude `--settings` JSON (hook registration). */
+    settingsJson: string;
+    /** Launch model (`--model`); omit to use claude's default. */
+    model?: string;
+    /** Resume a specific prior claude session (`--resume <id>`). */
+    resume?: string;
+    /** Extra claude args placed before the injected flags (rarely needed). */
+    extraArgs?: string[];
+}
+/**
+ * Build the `claude` argv for an interactive, co-drivable TUI:
+ * `[..extra] [--resume <id>] [--model <m>] --settings <json>`.
+ */
+export declare function buildClaudeTuiArgs({ settingsJson, model, resume, extraArgs, }: ClaudeTuiArgs): string[];

package/dist/terminal/claude-tui.js

@@ -0,0 +1,13 @@
+/**
+ * Build the `claude` argv for an interactive, co-drivable TUI:
+ * `[..extra] [--resume <id>] [--model <m>] --settings <json>`.
+ */
+export function buildClaudeTuiArgs({ settingsJson, model, resume, extraArgs = [], }) {
+    const args = [...extraArgs];
+    if (resume)
+        args.push("--resume", resume);
+    if (model)
+        args.push("--model", model);
+    args.push("--settings", settingsJson);
+    return args;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * codex-native live-terminal launcher (Phase D). Encodes omnigent's verified
+ * co-drive recipe: a separate `codex` TUI process attaches to the session's
+ * already-running app-server over `--remote` and resumes the SAME thread, so the
+ * TUI, the structured data channel, and the web bridge all drive one thread.
+ *
+ * Two facts carried over from omnigent's working implementation
+ * (`codex_native_app_server.build_codex_remote_args`):
+ *  - the app-server must listen on a multi-client transport (`ws://IP:PORT` or
+ *    `unix://PATH`) — stdio only admits the one client that spawned it, so it
+ *    cannot be co-driven;
+ *  - the `--remote` TUI is a separate process that loads its OWN config and does
+ *    NOT inherit the app-server's `-c` flags. Without the same provider overrides
+ *    it falls back to the built-in OpenAI provider and renders the "Sign in with
+ *    ChatGPT" onboarding, never starting a thread. So the provider `-c` overrides
+ *    are passed through, and global `-c` flags must precede the `resume`
+ *    subcommand. (Ambient `codex login` state is codex's own concern — a logged-in
+ *    CLI just works; a logged-out one shows codex's own onboarding.)
+ */
+import type { TerminalRegistry } from "./registry.js";
+export interface CodexRemoteArgs {
+    /** App-server endpoint the TUI attaches to, e.g. `ws://127.0.0.1:9876` or
+     *  `unix:///tmp/rynx/app-server.sock`. */
+    remoteUrl: string;
+    /** Codex thread id to resume; omit to start a fresh remote thread. */
+    threadId?: string;
+    /** Codex `-c key=value` provider/model overrides (same set the app-server was
+     *  launched with) so the TUI resolves the same provider and skips onboarding. */
+    configOverrides?: string[];
+    /** Extra codex args that precede the attach flags (e.g. `["--model", "..."]`). */
+    codexArgs?: string[];
+}
+/**
+ * Build the `codex` argv tail for an app-server-backed TUI. Mirrors omnigent's
+ * `build_codex_remote_args` exactly: overrides → codexArgs → (resume) → --remote.
+ */
+export declare function buildCodexRemoteArgs({ remoteUrl, threadId, configOverrides, codexArgs, }: CodexRemoteArgs): string[];
+export interface LaunchCodexTuiOptions extends CodexRemoteArgs {
+    registry: TerminalRegistry;
+    /** Terminal id (one codex TUI per session — `terminal_codex_main`). */
+    terminalId: string;
+    cwd: string;
+    /** codex executable (runtime-resolved binary path). */
+    codexBin: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+}
+/**
+ * Create (idempotently) the codex TUI terminal in the registry, running the real
+ * `codex` CLI attached to the session's app-server. The Phase-C WS bridge then
+ * displays and co-drives it like any other terminal.
+ */
+export declare function launchCodexTui(opts: LaunchCodexTuiOptions): void;

package/dist/terminal/codex-tui.js

@@ -0,0 +1,26 @@
+/**
+ * Build the `codex` argv tail for an app-server-backed TUI. Mirrors omnigent's
+ * `build_codex_remote_args` exactly: overrides → codexArgs → (resume) → --remote.
+ */
+export function buildCodexRemoteArgs({ remoteUrl, threadId, configOverrides = [], codexArgs = [], }) {
+    const overrideArgs = configOverrides.flatMap((override) => ["-c", override]);
+    if (threadId === undefined) {
+        return [...overrideArgs, ...codexArgs, "--remote", remoteUrl];
+    }
+    return [...overrideArgs, ...codexArgs, "resume", "--remote", remoteUrl, threadId];
+}
+/**
+ * Create (idempotently) the codex TUI terminal in the registry, running the real
+ * `codex` CLI attached to the session's app-server. The Phase-C WS bridge then
+ * displays and co-drives it like any other terminal.
+ */
+export function launchCodexTui(opts) {
+    opts.registry.getOrCreate(opts.terminalId, {
+        cwd: opts.cwd,
+        command: opts.codexBin,
+        args: buildCodexRemoteArgs(opts),
+        env: opts.env,
+        cols: opts.cols,
+        rows: opts.rows,
+    });
+}

package/dist/terminal/registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 omnigent's terminal attach (`terminal_attach.py`: `read_only`
+ * from the URL → `-r`). 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";
+export type TerminalRole = "owner" | "read-only";
+export interface AttachResult {
+    attachment: TerminalAttachment;
+    /** The granted role — always the requested role (no downgrade). */
+    role: TerminalRole;
+}
+export declare class TerminalRegistry {
+    private readonly terminals;
+    get(id: string): TmuxTerminal | 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?: {
+        cols?: number;
+        rows?: number;
+    }): Promise<AttachResult>;
+    /** Kill a terminal's tmux server and drop it. */
+    close(id: string): void;
+    /** Kill every terminal (runner shutdown). */
+    closeAll(): void;
+}

package/dist/terminal/registry.js

@@ -0,0 +1,70 @@
+/**
+ * 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 omnigent's terminal attach (`terminal_attach.py`: `read_only`
+ * from the URL → `-r`). 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";
+export class TerminalRegistry {
+    terminals = new Map();
+    get(id) {
+        return this.terminals.get(id);
+    }
+    has(id) {
+        return this.terminals.has(id);
+    }
+    /** 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, opts) {
+        const existing = this.terminals.get(id);
+        if (existing && existing.isAlive())
+            return existing;
+        if (existing) {
+            // Dead pane (its TUI exited) — kill the husk + drop it before relaunching.
+            try {
+                existing.kill();
+            }
+            catch {
+                // already gone — fine
+            }
+            this.terminals.delete(id);
+        }
+        const terminal = new TmuxTerminal({ ...opts, name: id });
+        terminal.start();
+        this.terminals.set(id, terminal);
+        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) {
+        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 };
+    }
+    /** Kill a terminal's tmux server and drop it. */
+    close(id) {
+        const terminal = this.terminals.get(id);
+        if (!terminal)
+            return;
+        terminal.kill();
+        this.terminals.delete(id);
+    }
+    /** Kill every terminal (runner shutdown). */
+    closeAll() {
+        for (const id of [...this.terminals.keys()])
+            this.close(id);
+    }
+}

package/dist/terminal/tmux.d.ts

@@ -0,0 +1,150 @@
+/** A live attach handle: the pane's bytes flow through `onData`; caller input
+ *  goes through `write`; `resize` reflows the pane; `kill` ends this client
+ *  (not the server). Shape mirrors the node-pty surface the WS bridge needs. */
+export interface TerminalAttachment {
+    onData(listener: (chunk: string) => void): void;
+    onExit(listener: (info: {
+        exitCode: number;
+    }) => void): void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    /** Detach this client. The tmux server + pane keep running. */
+    kill(): void;
+}
+/** Minimal node-pty surface (kept local so this module has no type dep on it). */
+interface PtyProcess {
+    onData(cb: (data: string) => void): void;
+    onExit(cb: (e: {
+        exitCode: number;
+    }) => void): void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+}
+type PtySpawn = (file: string, args: string[], opts: {
+    name: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: Record<string, string>;
+}) => PtyProcess;
+export interface TmuxTerminalOptions {
+    /** Unique name for the tmux session + socket, e.g. `rynx-<sessionId>-<termId>`. */
+    name: string;
+    cwd: string;
+    /** Inner command to run in the pane. Defaults to the login shell. */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    /** Injectable for tests; defaults to the real node-pty spawn. */
+    ptySpawn?: PtySpawn;
+    /** Injectable for tests; defaults to the real `tmux` binary path. */
+    tmuxBin?: string;
+}
+/** Is a usable `tmux` on PATH? Cheap probe for the capability gate. */
+export declare function isTmuxAvailable(tmuxBin?: string): boolean;
+export declare class TmuxTerminal {
+    readonly name: string;
+    readonly socketPath: string;
+    private readonly cwd;
+    private readonly command;
+    private readonly args;
+    private readonly env;
+    private readonly cols;
+    private readonly rows;
+    private readonly tmuxBin;
+    private readonly injectedSpawn?;
+    private started;
+    constructor(opts: TmuxTerminalOptions);
+    /** tmux argv prefix targeting this terminal's private server. */
+    private base;
+    /** Create the private tmux server + detached session running the inner
+     *  command. Idempotent: a second call is a no-op once the session exists. */
+    start(): void;
+    /**
+     * Apply omnigent's tmux option suite to the private server (inner/terminal.py).
+     * These are NOT cosmetic — several fix real co-drive behavior that the tmux
+     * defaults break:
+     *  - `mouse on`: the web terminal's wheel scrolls the pane's scrollback (and
+     *    mouse events reach a TUI that requests them). Without it, no scrolling.
+     *  - `extended-keys on` + `csi-u`: tmux forwards Kitty Keyboard Protocol / CSI-u
+     *    keys (Ctrl+C, Shift+Enter, modified keys) that codex/claude TUIs request —
+     *    without it tmux downgrades them and the vendor TUI mis-reads modifiers.
+     *  - `escape-time 0`: kills tmux's default 500 ms wait after ESC, which otherwise
+     *    makes arrow keys / Alt-combos / pasted CSI feel laggy or mis-parse.
+     *  - `prefix None` + `prefix2 None` + unbind the prefix table: the user's
+     *    keystrokes (notably C-b) go to the pane, never tmux — a co-drive terminal
+     *    must not intercept a prefix.
+     *  - `focus-events on`, `allow-passthrough on`, `history-limit`: focus reporting,
+     *    passthrough sequences, scrollback depth.
+     *  - `remain-on-exit on` + `exit-empty off`: keep the dead pane + server after the
+     *    inner CLI exits so its last output stays capturable and `#{pane_dead}` reads
+     *    the exit (liveness probe), instead of the server vanishing.
+     *  - `MouseDown3*` unbinds: no right-click menu to spawn extra panes/windows.
+     *  - `status off`: hide tmux chrome. omnigent keeps the status line only to show
+     *    a conversation link; rynx has none, so the whole line (and its
+     *    `[main] 0:node*` window list) is hidden.
+     * `-q`/`-gq`/`-sq` keep an older tmux that lacks an option from failing launch.
+     * Batched into one invocation with `;` command separators (one spawn).
+     */
+    private configureSession;
+    /** Whether the terminal's INNER PROCESS is still running. Probes the pane's
+     *  `#{pane_dead}` flag rather than mere session existence: with
+     *  `remain-on-exit on` the session/server deliberately outlive the inner CLI's
+     *  exit (a dead pane shows tmux's "Pane is dead"), so `has-session` succeeding
+     *  no longer implies a live process. Alive only when the session exists AND its
+     *  pane process has not exited. Mirrors omnigent's `_terminal.is_alive`. */
+    isAlive(): boolean;
+    /** Async pane-liveness probe — MUST NOT block the event loop. The attach
+     *  pane-death watcher polls this on an interval; a synchronous `execFileSync`
+     *  there stalls the runner child's event loop (freezing the PTY stream → the
+     *  terminal appears "stuck"). omnigent's `_tmux_session_alive` uses an async
+     *  subprocess + timeout for exactly this reason. */
+    private isAliveAsync;
+    /** Type literal text into the pane (agent injection / co-drive from a
+     *  non-PTY caller). `-l` sends the text literally rather than as key names. */
+    sendKeys(text: string): void;
+    /**
+     * The visible pane text (synchronous). Used by the claude-native injection
+     * path as a ready-gate (poll for the `❯` prompt glyph before typing) and to
+     * verify a pasted draft landed / left the input box. Returns "" on failure so
+     * a dead pane just reads as empty rather than throwing mid-poll.
+     */
+    capturePane(): string;
+    /** Send a submit Enter as a KEY NAME (no `-l`), committing the input line.
+     *  Kept separate from the paste so a multi-line paste isn't folded into a
+     *  single submit (claude coalesces a rapid stdin burst into a paste). */
+    sendEnter(): void;
+    /** Interrupt the pane's running TUI turn with an Escape key — codex/claude both
+     *  cancel an in-flight response on a single Esc ("esc to interrupt"). A key NAME
+     *  (no `-l`) so tmux interprets it. Mirrors omnigent's `inject_interrupt`. */
+    interrupt(): void;
+    /** Clear the current input line before an injection so leftover keystrokes
+     *  can't prepend to the pasted draft. `C-a` (Home) + `C-k` (kill-to-end) is
+     *  the safe pair — `C-u` only clears backwards from the cursor (omnigent). */
+    clearInputLine(): void;
+    /** Send one or more tmux key NAMES (e.g. `Enter`, `C-a`) to the pane. */
+    private sendKeyNames;
+    /**
+     * Deliver `text` into the pane as a bracketed paste — `load-buffer` (from
+     * stdin, no temp file) then `paste-buffer -p` (bracketed markers keep newlines
+     * as data, so claude treats it as one pasted draft, not N submits) and `-d`
+     * (drop the buffer after). This is the injection body; the caller sends a
+     * separate {@link sendEnter} to submit. Handles multi-line + large messages
+     * that would overflow a `send-keys` argv.
+     */
+    paste(text: string, bufferName?: string): void;
+    /**
+     * Attach a client. `role: "read-only"` passes tmux `-r` so the viewer cannot
+     * type (defense-in-depth on top of the WS bridge dropping input frames).
+     */
+    attach(role: "owner" | "read-only", dims?: {
+        cols?: number;
+        rows?: number;
+    }): Promise<TerminalAttachment>;
+    /** Kill the tmux server (ends the session and all attaches). */
+    kill(): void;
+}
+export {};