@rynx-ai/runtime 0.1.0

package/dist/host.js

@@ -0,0 +1,1323 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { resolveAgent, resolveAgentExecution, buildAgentSkillEnvironment, SessionNormalizer, } from "@rynx-ai/core";
+import { getRuntimeProfile, } from "@rynx-ai/core";
+import { resolveRuntimeBinary, resolveRuntimeModel, } from "@rynx-ai/core";
+import { createCodexChildEnv } from "./codex-child-env.js";
+import { prepareCodexHome, populateCodexSkills } from "./codex-home.js";
+import { materializeSkillPlugin } from "./claude/executor.js";
+import { listClaudeModels } from "./claude/models.js";
+import { CodexAppServerClient, buildTextUserInput, } from "./codex-app-server/client.js";
+import { buildAppServerBaseArgs } from "./codex-app-server/transport.js";
+import { WsRpcChannel, ExternalWsChannel } from "./codex-app-server/ws-channel.js";
+import { CodexSessionForwarder } from "./codex-app-server/forwarder.js";
+import { buildCodexRemoteArgs } from "./terminal/codex-tui.js";
+import { buildClaudeTuiArgs } from "./terminal/claude-tui.js";
+import { ensureProjectTrusted } from "./claude/trust.js";
+import { claudeTranscriptPath } from "./claude/transcript.js";
+import { claudeBridgeDir, prepareClaudeBridgeDir } from "./claude/native-bridge.js";
+import { ClaudeLiveSession, injectViaTerminal, } from "./claude/native-integration.js";
+import { buildClaudeHookSettings } from "./claude/native-hooks.js";
+import { FileCodexSessionStore, resolveCodexSessionStorePath, } from "./codex-session-store.js";
+import { AgentRuntimeError as CodexRuntimeError } from "@rynx-ai/core";
+import { newSessionId as makeSessionId } from "@rynx-ai/core";
+import { resolveAllowedRoots, } from "@rynx-ai/core";
+export { FileCodexSessionStore, resolveCodexSessionStorePath, };
+// The runtime error type lives in @rynx-ai/core (as AgentRuntimeError) so channels
+// can `instanceof`-check it without depending on this package. Imported above
+// under its legacy name and re-exported here for intra-package call sites.
+export { CodexRuntimeError };
+export class SpawnCodexCommandRunner {
+    cliPath;
+    killGraceMs;
+    constructor(cliPath, { killGraceMs = 5_000 } = {}) {
+        this.cliPath = cliPath;
+        this.killGraceMs = killGraceMs;
+    }
+    start({ args, cwd, signal, }) {
+        const child = spawn(this.cliPath, args, {
+            cwd,
+            env: createCodexChildEnv(process.env),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const queue = [];
+        let stdout = "";
+        let stderr = "";
+        let streamClosed = false;
+        let childError = null;
+        let notify = null;
+        let childClosed = false;
+        let killTimer;
+        const wake = () => {
+            notify?.();
+            notify = null;
+        };
+        const push = (chunk) => {
+            queue.push(chunk);
+            wake();
+        };
+        const bindLineReader = (kind, input) => {
+            if (!input) {
+                return;
+            }
+            const lineReader = readline.createInterface({
+                input,
+                crlfDelay: Infinity,
+            });
+            lineReader.on("line", (line) => {
+                if (kind === "stdout") {
+                    stdout += `${line}\n`;
+                }
+                else {
+                    stderr += `${line}\n`;
+                }
+                push({ stream: kind, line });
+            });
+        };
+        bindLineReader("stdout", child.stdout);
+        bindLineReader("stderr", child.stderr);
+        child.on("error", (error) => {
+            childError = error;
+            streamClosed = true;
+            wake();
+        });
+        const completion = new Promise((resolve, reject) => {
+            child.on("close", (code) => {
+                childClosed = true;
+                if (killTimer) {
+                    clearTimeout(killTimer);
+                }
+                streamClosed = true;
+                wake();
+                if (childError) {
+                    reject(childError);
+                    return;
+                }
+                resolve({
+                    exitCode: code ?? 1,
+                    stdout,
+                    stderr,
+                });
+            });
+        });
+        if (signal) {
+            const abortHandler = () => {
+                if (childClosed) {
+                    return;
+                }
+                child.kill("SIGTERM");
+                killTimer ??= setTimeout(() => {
+                    if (!childClosed) {
+                        child.kill("SIGKILL");
+                    }
+                }, this.killGraceMs);
+            };
+            if (signal.aborted) {
+                abortHandler();
+            }
+            else {
+                signal.addEventListener("abort", abortHandler, { once: true });
+                void completion
+                    .finally(() => {
+                    signal.removeEventListener("abort", abortHandler);
+                    if (killTimer) {
+                        clearTimeout(killTimer);
+                    }
+                })
+                    .catch(() => undefined);
+            }
+        }
+        const stream = (async function* streamLines() {
+            while (!streamClosed || queue.length > 0) {
+                if (queue.length === 0) {
+                    await new Promise((resolve) => {
+                        notify = resolve;
+                    });
+                    continue;
+                }
+                const next = queue.shift();
+                if (next) {
+                    yield next;
+                }
+            }
+            if (childError) {
+                throw childError;
+            }
+        })();
+        return {
+            stream,
+            completion,
+        };
+    }
+    async capture({ args, cwd = process.cwd(), }) {
+        const running = this.start({ args, cwd });
+        for await (const _ of running.stream) {
+            // Drain output so completion captures stdout/stderr for parsing.
+        }
+        return running.completion;
+    }
+}
+/** Fraction of an agent's `contextWindow` budget at which the orchestrator
+ *  emits a one-time `context.threshold` observability signal. Mirrors omnigent's
+ *  compaction `trigger_threshold` (0.8). codex self-compacts via its token
+ *  budget (set proactively); claude has no programmatic compaction, so this
+ *  signal is the lever consumers surface to the user. */
+const CONTEXT_WARN_RATIO = 0.8;
+/**
+ * The `OPENAI_*` retry env for a codex-lineage app-server spawn, or `undefined`
+ * when the budget declares no retry or the runtime is claude. claude applies
+ * its retry budget per-run in `buildOptions` (see the claude executor), so it
+ * never needs a dedicated app-server.
+ */
+export function codexRetryEnv(runtime, budget) {
+    if (runtime === "claude") {
+        return undefined;
+    }
+    const retry = budget?.retry;
+    if (!retry) {
+        return undefined;
+    }
+    const env = {};
+    if (retry.maxRetries != null) {
+        env.OPENAI_MAX_RETRIES = String(retry.maxRetries);
+    }
+    if (retry.timeoutPerRequestSeconds != null) {
+        env.OPENAI_TIMEOUT = String(Math.round(retry.timeoutPerRequestSeconds));
+    }
+    return Object.keys(env).length > 0 ? env : undefined;
+}
+/**
+ * The cache key for a runtime backend. A retry budget on a codex-lineage
+ * runtime forks a dedicated app-server (its own retry env) under a composite
+ * `${runtime}::${hash}` key; everything else shares the base `${runtime}`
+ * backend — so budget-less agents keep today's shared-process behaviour.
+ */
+function hashRetryEnv(env) {
+    return Object.keys(env)
+        .sort()
+        .map((key) => `${key}=${env[key]}`)
+        .join("&");
+}
+export function codexBackendKey(runtime, budget) {
+    const env = codexRetryEnv(runtime, budget);
+    return env ? `${runtime}::${hashRetryEnv(env)}` : runtime;
+}
+export class LocalAgentHost {
+    config;
+    sessionStore;
+    allowedRoots;
+    defaultRuntime;
+    // DI overrides applied to the *default* runtime backend only (used by tests).
+    // `injectedAppServerClient === null` forces exec mode; `undefined` means
+    // auto-create. The command runner override backs the status probe.
+    injectedCommandRunner;
+    injectedAppServerClient;
+    clock;
+    backendIdleTtlMs;
+    // Builds the SEPARATE forwarder connection for a live codex session (omnigent's
+    // multi-connection model). Defaults to an ExternalWsChannel client attached to
+    // the backend's app-server; tests inject a fake.
+    forwarderClientFactory;
+    // Keyed by `codexBackendKey` — the bare runtime id for budget-less agents, or
+    // a `${runtime}::${retryHash}` composite for a per-agent retry budget.
+    backends = new Map();
+    // The rynx session this host serves (set from `RYNX_RUNNER_SESSION`); the private
+    // CODEX_HOME is scoped to it so concurrent agents never share a `skills/` dir.
+    sessionId;
+    // Per-agent codex knobs resolved at live-session start, applied to this
+    // session's app-server (host is per-session, so the app-server is private to
+    // this agent). Absent ⇒ fall back to the daemon `config.*` default.
+    sessionSandbox;
+    sessionApprovalPolicy;
+    // A private CODEX_HOME (login symlinked, settings copied, update/NUX state NOT
+    // inherited) for this session's codex app-server + TUI — lazily prepared.
+    cachedCodexHome;
+    // Per-session codex-native live forwarders, keyed by localThreadId. The
+    // single-writer of the session's canonical events + the target of turn injection.
+    liveSessions = new Map();
+    // Per-session claude-native live forwarders (parallel to liveSessions; claude
+    // has no app-server, so it tails the bridge + transcript instead of RPC).
+    liveClaudeSessions = new Map();
+    // In-flight `ensureLiveCodexSession` calls, so concurrent triggers (a web
+    // `live.ensure` racing a `term.open`) share ONE forwarder — never two.
+    liveEnsuring = new Map();
+    constructor({ config, commandRunner, sessionStore = new FileCodexSessionStore(resolveCodexSessionStorePath(config)), allowedRoots = resolveAllowedRoots(config), appServerClient, now = () => Date.now(), backendIdleTtlMs = 300_000, forwarderClientFactory, sessionId, }) {
+        this.config = config;
+        this.sessionId = sessionId ?? "__default__";
+        this.sessionStore = sessionStore;
+        this.allowedRoots = allowedRoots;
+        this.defaultRuntime = config.AGENT_RUNTIME ?? "codex";
+        this.injectedCommandRunner = commandRunner;
+        this.injectedAppServerClient = appServerClient;
+        this.clock = now;
+        this.backendIdleTtlMs = backendIdleTtlMs;
+        this.forwarderClientFactory =
+            forwarderClientFactory ??
+                ((appServerUrl) => new CodexAppServerClient({ channel: new ExternalWsChannel(appServerUrl) }));
+    }
+    getBackend(runtime, budget) {
+        this.reapIdleBackends();
+        // In forced exec mode (the default runtime's injected app-server is null) a
+        // retry budget must NOT fork a composite backend: there is no app-server to
+        // carry the retry env, and forking one would spawn a real app-server and
+        // defeat the forced-exec override. Fall back to the base key — codex retry is
+        // then a no-op in exec mode (consistent with the broader codex-retry caveat).
+        const execMode = runtime === this.defaultRuntime && this.injectedAppServerClient === null;
+        const retryEnv = execMode ? undefined : codexRetryEnv(runtime, budget);
+        const key = retryEnv ? `${runtime}::${hashRetryEnv(retryEnv)}` : runtime;
+        const existing = this.backends.get(key);
+        if (existing) {
+            existing.lastUsedAt = this.clock();
+            return existing;
+        }
+        const backend = this.createBackend(runtime, retryEnv);
+        backend.lastUsedAt = this.clock();
+        this.backends.set(key, backend);
+        return backend;
+    }
+    /**
+     * Stop + drop per-budget composite backends that have been idle longer than
+     * the TTL and have no in-flight run. Base per-runtime backends (key === the
+     * bare runtime id) are never reaped — they live for the process lifetime, as
+     * before. There are no per-conversation close hooks, so this lazy sweep (run
+     * on every `getBackend`) is how dedicated app-servers get reclaimed.
+     */
+    reapIdleBackends() {
+        const now = this.clock();
+        for (const [key, backend] of this.backends) {
+            if (!key.includes("::")) {
+                continue;
+            }
+            if ((backend.inFlight ?? 0) > 0 || backend.lastUsedAt === undefined) {
+                continue;
+            }
+            if (now - backend.lastUsedAt < this.backendIdleTtlMs) {
+                continue;
+            }
+            void backend.appServerClient?.stop();
+            this.backends.delete(key);
+        }
+    }
+    createBackend(runtime, retryEnv) {
+        const profile = getRuntimeProfile(runtime);
+        // A composite (per-budget) backend is inherently non-default: it gets a
+        // fresh app-server with the retry env, never the test-injected default deps.
+        const isComposite = retryEnv !== undefined;
+        const isDefault = runtime === this.defaultRuntime && !isComposite;
+        const commandRunner = (isDefault && this.injectedCommandRunner) ||
+            new SpawnCodexCommandRunner(resolveRuntimeBinary(runtime));
+        // The claude runtime is not codex-lineage: it has no app-server (its live
+        // co-drive tails a tmux pane + transcript), so only the command runner backs
+        // its status probe.
+        if (runtime === "claude") {
+            return { runtime, profile, appServerClient: null, commandRunner };
+        }
+        // codex-lineage: the app-server connection backs live turn injection; a
+        // missing injected client (tests) forces null.
+        const appServerClient = isDefault
+            ? this.injectedAppServerClient === null
+                ? null
+                : this.injectedAppServerClient ?? this.createAppServerClient(runtime)
+            : this.createAppServerClient(runtime, retryEnv);
+        return { runtime, profile, appServerClient, commandRunner };
+    }
+    /** This session's private CODEX_HOME (prepared once), shared by its app-server + TUI. */
+    codexHome() {
+        return (this.cachedCodexHome ??= prepareCodexHome(this.sessionId));
+    }
+    createAppServerClient(runtime, extraEnv) {
+        const cliPath = resolveRuntimeBinary(runtime);
+        // Per-agent knobs (resolved at live-session start) win over the daemon
+        // default — the app-server is private to this session's agent.
+        const approvalPolicy = this.sessionApprovalPolicy ?? this.config.AGENT_APPROVAL_POLICY;
+        const sandbox = this.sessionSandbox ?? this.config.AGENT_SANDBOX;
+        const policy = approvalPolicy === "never" ? "auto-approve-session" : "auto-decline";
+        // Native co-drive: run the app-server on a loopback ws (multi-client) so a
+        // `codex --remote` TUI can attach to the same thread (stdio admits only one
+        // client). This is the sole transport — always native, aligning with omnigent.
+        // Point it at the private CODEX_HOME so it shares the TUI's login/settings and
+        // never trips the real home's update/NUX state.
+        const channel = new WsRpcChannel({
+            cliPath,
+            baseArgs: buildAppServerBaseArgs(sandbox),
+            extraEnv: { ...(extraEnv ?? {}), CODEX_HOME: this.codexHome() },
+        });
+        return new CodexAppServerClient({
+            channel,
+            approvalDecisionPolicy: policy,
+            interactiveApprovals: this.config.AGENT_INTERACTIVE_APPROVALS,
+        });
+    }
+    /**
+     * Deliver a user's decision for a pending interactive approval (Phase D).
+     * Routes to the codex app-server client for the thread's runtime. Returns
+     * false when no matching pending approval exists (unknown id / already
+     * resolved / claude runtime).
+     */
+    async resolveApproval(localThreadId, approvalId, decision) {
+        const record = await this.sessionStore.get(localThreadId);
+        const runtime = record?.runtime ?? this.defaultRuntime;
+        if (runtime === "claude") {
+            return false;
+        }
+        const client = this.getBackend(runtime).appServerClient;
+        return client ? client.resolveApproval(approvalId, decision) : false;
+    }
+    /**
+     * The command to run in a session's live terminal so it co-drives the codex
+     * app-server thread (Phase D). Returns `null` when live-terminal is off, the
+     * runtime is claude (not codex-lineage), or the app-server has no ws endpoint —
+     * the caller then falls back to a plain shell. Ensures the app-server is up so
+     * its ws url is available; `codex --remote resume <threadId>` attaches to the
+     * SAME thread the structured data channel drives.
+     */
+    async codexTerminalSpec(localThreadId) {
+        const record = await this.sessionStore.get(localThreadId);
+        // The live session (created by ensureLiveCodexSession with the agent-resolved
+        // runtime) is the source of truth for which runtime this session co-drives;
+        // fall back to the store record / default only when it isn't up yet.
+        if (this.liveClaudeSessions.has(localThreadId)) {
+            return this.claudeTerminalSpec(localThreadId, record);
+        }
+        const runtime = record?.runtime ?? this.defaultRuntime;
+        if (runtime === "claude") {
+            return this.claudeTerminalSpec(localThreadId, record);
+        }
+        const backend = this.getBackend(runtime);
+        const client = backend.appServerClient;
+        if (!client) {
+            throw new CodexRuntimeError(`no app-server for runtime ${runtime}`, 500, "app_server_unavailable");
+        }
+        // Native-only: an app-server failure surfaces as a terminal error, never a
+        // silent bash fallback (aligns with omnigent). ensureInitialized throws on its own.
+        await client.ensureInitialized();
+        const remoteUrl = client.terminalRemoteUrl();
+        if (!remoteUrl) {
+            throw new CodexRuntimeError("codex app-server has no remote url", 500, "app_server_unavailable");
+        }
+        // The TUI shares this session's app-server, so it inherits the per-agent
+        // sandbox already applied at boot; keep the network-access override aligned
+        // to the same effective sandbox.
+        const configOverrides = (this.sessionSandbox ?? this.config.AGENT_SANDBOX) === "workspace-write"
+            ? ["sandbox_workspace_write.network_access=true"]
+            : [];
+        // Apply the agent-spec model to the TUI (the private CODEX_HOME config.toml is
+        // shared per-runtime, so a per-session model rides a launch `-c model=` instead).
+        const launchModel = this.liveSessions.get(localThreadId)?.model;
+        if (launchModel)
+            configOverrides.push(`model=${JSON.stringify(launchModel)}`);
+        return {
+            command: resolveRuntimeBinary(runtime),
+            args: buildCodexRemoteArgs({
+                remoteUrl,
+                ...(record?.codexSessionId ? { threadId: record.codexSessionId } : {}),
+                configOverrides,
+            }),
+            cwd: record?.cwd ?? process.cwd(),
+            // Share the app-server's private CODEX_HOME so the TUI inherits the same
+            // login/settings and skips the real home's update/NUX prompt. RYNX_SESSION_ID
+            // scopes agent-run CLIs (rynx-emulator) to this session at the daemon.
+            env: {
+                ...createCodexChildEnv(process.env),
+                CODEX_HOME: this.codexHome(),
+                RYNX_SESSION_ID: localThreadId,
+            },
+        };
+    }
+    /**
+     * Bring up (idempotently) a session's persistent codex forwarder and emit its
+     * mirrored {@link SessionEvent}s. omnigent's codex-native single-writer model:
+     * this forwarder is the SOLE producer of the session's canonical events — every
+     * turn on the thread, web-composer-injected AND co-driving-`codex --remote`-TUI
+     * initiated. Each turn gets a {@link SessionNormalizer} whose `responseId` is
+     * DETERMINISTIC (`resp_codex_<turnId>`) so items converge across snapshot/live.
+     *
+     * Returns false for claude / no app-server (the caller falls back to the
+     * streaming run path). This client CREATES the codex thread (`threadStart`) so
+     * it owns the thread's item/turn notification stream — the app-server delivers
+     * items to the thread-creating connection, for turns started by ANY client (web
+     * inject AND the co-driving `codex --remote` TUI). The TUI pane (launched by the
+     * runner child, which owns the terminal registry) merely `resume`s this thread
+     * to display it. The thread id is persisted so `codexTerminalSpec` resumes it.
+     */
+    async ensureLiveCodexSession(localThreadId, emit, opts) {
+        if (this.liveSessions.has(localThreadId) || this.liveClaudeSessions.has(localThreadId))
+            return true;
+        // Dedupe concurrent triggers so only one forwarder is ever created per
+        // session (two would double-mirror every turn).
+        const inflight = this.liveEnsuring.get(localThreadId);
+        if (inflight)
+            return inflight;
+        const started = this.startLiveCodexSession(localThreadId, emit, opts);
+        this.liveEnsuring.set(localThreadId, started);
+        try {
+            return await started;
+        }
+        finally {
+            this.liveEnsuring.delete(localThreadId);
+        }
+    }
+    async startLiveCodexSession(localThreadId, emit, opts) {
+        // cancel-before-recreate (omnigent Layer 2, runner/app.py `_cancel_auto_forwarder_task`):
+        // never run a new forwarder alongside a stale one for this id. ensureLive's has()
+        // fast-path normally makes this a no-op; it closes the stop→re-ensure race that
+        // could otherwise leave a half-dead forwarder mirroring in parallel.
+        if (this.liveSessions.has(localThreadId) || this.liveClaudeSessions.has(localThreadId)) {
+            this.stopLiveCodexSession(localThreadId);
+        }
+        const record = await this.sessionStore.get(localThreadId);
+        // Runtime precedence: the thread's bound runtime, else the agent-resolved
+        // hint from the control plane, else the env default. This is what makes live
+        // co-drive follow the agent spec instead of the global default.
+        const runtime = record?.runtime ?? opts?.runtime ?? this.defaultRuntime;
+        if (runtime === "claude")
+            return this.startLiveClaudeSession(localThreadId, emit, record, opts);
+        const cwd = record?.cwd ?? process.cwd();
+        // Spec-load errors (a rejected legacy `skills` form, malformed JSON, …) are
+        // logged with the agent context and fail the live start loudly — never a
+        // bare mystery `false`.
+        let liveCfg;
+        try {
+            liveCfg = await this.resolveLiveAgentConfig(localThreadId, opts, runtime, cwd);
+        }
+        catch (err) {
+            console.error(`[agent-spec] session=${localThreadId} agent=${opts?.agentName ?? "-"} failed to resolve: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+        // Link this session's skills into its private CODEX_HOME's `skills/` BEFORE the
+        // app-server boots (and before the `--remote` TUI attaches) so the native Codex
+        // discovers them — omnigent's filesystem mechanism. The live thread is created by
+        // the TUI, not rynx, so skills can't ride `threadStart.developerInstructions` (as
+        // the non-live run did); `$CODEX_HOME/skills/` is the only channel that reaches it.
+        // The agent spec is the single skill source: its refs were replayed into a
+        // session-scoped dir (see resolveLiveAgentConfig); no spec / no `skills` means
+        // zero skills — the owner's catalog is never consulted.
+        const liveSkills = liveCfg.selectedSkills.map((s) => ({ name: s.name, dir: s.dir }));
+        populateCodexSkills(this.codexHome(), liveSkills);
+        // Apply this agent's sandbox / approval policy to the session's app-server
+        // BEFORE it boots (getBackend below lazily creates it). Host is per-session,
+        // so these knobs are the agent's own — no cross-session bleed. Set even when
+        // absent (undefined) so a re-used host doesn't inherit a prior agent's values.
+        this.sessionSandbox = liveCfg.sandbox;
+        this.sessionApprovalPolicy = liveCfg.approvalPolicy;
+        // Backend client owns the app-server + drives injection. Every failed-start
+        // path below removes the session skills dir it would otherwise leak.
+        const abandon = () => {
+            void liveCfg.skillsCleanup();
+            return false;
+        };
+        const injectClient = this.getBackend(runtime).appServerClient;
+        if (!injectClient)
+            return abandon();
+        try {
+            await injectClient.ensureInitialized();
+        }
+        catch {
+            return abandon();
+        }
+        const appServerUrl = injectClient.terminalRemoteUrl();
+        if (!appServerUrl)
+            return abandon(); // needs the ws app-server (live-terminal mode)
+        // omnigent multi-connection: a SEPARATE forwarder connection to the SAME
+        // app-server, which `thread/resume`s to subscribe to the thread's item/turn
+        // notifications (the backend client injects; this one only observes).
+        const forwarderClient = this.forwarderClientFactory(appServerUrl);
+        try {
+            await forwarderClient.ensureInitialized();
+        }
+        catch {
+            return abandon();
+        }
+        // Apply the agent-spec model (skills were applied above via `$CODEX_HOME/skills/`).
+        // A resumed thread keeps its stored model; otherwise use the agent-spec model (or
+        // the runtime default). The model rides a launch `-c model=` on the TUI (see
+        // `codexTerminalSpec`) / `turn/start` on injection, since rynx doesn't create the thread.
+        const model = getCodexModel(this.config, record?.model ?? liveCfg.model);
+        let markReady;
+        const ready = new Promise((resolve) => {
+            markReady = resolve;
+        });
+        const live = {
+            injectClient,
+            forwarderClient,
+            forwarder: null,
+            runtime,
+            cwd,
+            model,
+            threadId: record?.codexSessionId ?? null,
+            ready,
+            markReady,
+            injectLock: Promise.resolve(),
+            subscribing: false,
+            stopped: false,
+            skillsCleanup: liveCfg.skillsCleanup,
+        };
+        let normalizer = null;
+        const startNormalizer = (turnId) => {
+            normalizer = new SessionNormalizer({
+                sessionId: localThreadId,
+                // turnId unknown → fixed literal (NEVER random): items arriving before
+                // `turn/started` land on ONE response instead of splitting into random
+                // ids (the DB `resp_codex_<uuid>` doubling). Mirrors omnigent `_response_id`.
+                responseId: turnId ? `resp_codex_${turnId}` : "resp_codex_native",
+                model,
+            });
+            return normalizer;
+        };
+        const sink = {
+            onTurnStart: (turnId) => startNormalizer(turnId),
+            onUserMessage: (text) => {
+                const n = normalizer ?? startNormalizer();
+                for (const se of n.userInput(text))
+                    emit(se);
+            },
+            onEvent: (event) => {
+                const n = normalizer ?? startNormalizer();
+                for (const se of n.next(event))
+                    emit(se);
+            },
+            onTurnEnd: (usage) => {
+                if (!normalizer)
+                    return;
+                if (usage)
+                    for (const se of normalizer.next({ type: "turn_completed", usage }))
+                        emit(se);
+                for (const se of normalizer.next({ type: "done" }))
+                    emit(se);
+                normalizer = null;
+            },
+            onTurnError: (error) => {
+                if (!normalizer)
+                    return;
+                for (const se of normalizer.fail({ code: "codex_error", message: error.message, source: "execution" }))
+                    emit(se);
+                normalizer = null;
+            },
+            // The TUI creates the thread; the forwarder connection sees its broadcast
+            // `thread/started`. Persist the id, unblock injection, and start the
+            // resume-subscribe loop (which parks until the thread's first turn).
+            onThreadStarted: (threadId) => this.onLiveThreadStarted(live, localThreadId, opts?.agentName ?? record?.agent, threadId),
+            onThreadActive: () => live.releaseActive?.(),
+        };
+        const forwarder = new CodexSessionForwarder(forwarderClient, sink);
+        live.forwarder = forwarder;
+        this.liveSessions.set(localThreadId, live);
+        forwarder.start();
+        // A resumed session already has a thread id — bind immediately; a fresh
+        // session waits for the TUI's broadcast `thread/started` (via onThreadStarted).
+        if (record?.codexSessionId) {
+            this.onLiveThreadStarted(live, localThreadId, record.agent, record.codexSessionId);
+        }
+        return true;
+    }
+    /** Bind a session's codex thread id once known (TUI broadcast or store): persist
+     *  it, unblock injection, and kick off the resume-subscribe loop (once). */
+    onLiveThreadStarted(live, localThreadId, agent, threadId) {
+        if (live.subscribing)
+            return;
+        live.subscribing = true;
+        live.threadId = threadId;
+        void this.sessionStore
+            .set({
+            localThreadId,
+            codexSessionId: threadId,
+            cwd: live.cwd,
+            // Persist the agent-spec-resolved model (was the config default), so a
+            // resume/reconnect keeps running the agent's model, not the global one.
+            model: live.model,
+            runtime: live.runtime,
+            agent,
+            updatedAt: new Date().toISOString(),
+        })
+            .catch(() => undefined);
+        live.markReady(); // thread id known → injection can turn/start
+        void this.subscribeUntilReady(live, threadId);
+    }
+    /**
+     * Subscribe the forwarder connection to a thread (omnigent's
+     * `_subscribe_until_ready`). A fresh TUI thread has no rollout until its first
+     * turn, so `thread/resume` is retried: park until the forwarder observes the
+     * thread active, then retry WITHOUT `excludeTurns` so the response backfills the
+     * first turn's items (replayed, deduped against the live stream). Once resume
+     * succeeds, subsequent turns arrive as live notifications on this connection.
+     */
+    async subscribeUntilReady(live, threadId) {
+        let sawNotReady = false;
+        while (!live.stopped) {
+            try {
+                const resp = await live.forwarderClient.threadResume({
+                    threadId,
+                    cwd: live.cwd,
+                    excludeTurns: !sawNotReady,
+                });
+                if (sawNotReady && Array.isArray(resp.thread.turns) && resp.thread.turns.length > 0) {
+                    live.forwarder.replayBackfill(resp.thread.turns);
+                }
+                return; // subscribed — live item/turn notifications now flow to the forwarder
+            }
+            catch (error) {
+                if (!isThreadNotReadyError(error)) {
+                    return; // other failure — injection still works via the backend client
+                }
+                sawNotReady = true;
+                // Park until the thread goes active (its first turn materializes the
+                // rollout); a short poll covers the flush race after "active".
+                await new Promise((resolve) => {
+                    live.releaseActive = resolve;
+                    setTimeout(resolve, 1500);
+                });
+                live.releaseActive = undefined;
+            }
+        }
+    }
+    /** Await a live session's thread binding (bounded). Returns false on timeout /
+     *  no live session. Injection and the runner's `live.ready` gate on this. */
+    async waitLiveReady(localThreadId, timeoutMs = 20_000) {
+        const claude = this.liveClaudeSessions.get(localThreadId);
+        if (claude)
+            return raceReady(claude.ready, timeoutMs);
+        const live = this.liveSessions.get(localThreadId);
+        if (!live)
+            return false;
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), timeoutMs);
+        });
+        const ok = await Promise.race([live.ready.then(() => true), timeout]);
+        if (timer)
+            clearTimeout(timer);
+        return ok;
+    }
+    /**
+     * Inject a user turn into a session's live codex thread — omnigent's
+     * single-writer web send. `turn/steer` when a turn is open (mid-turn
+     * supplement), else `turn/start`. NEVER creates a thread (the TUI owns creation;
+     * this targets the id the forwarder captured). Serialized per session so two
+     * injects can't double-open a turn.
+     *
+     * Returns an {@link InjectOutcome}: `notLive` when this session has no live
+     * forwarder (caller may use the run path); `notReady`/`failed` are hard errors
+     * the caller reports WITHOUT re-running (re-running double-writes alongside the
+     * forwarder). Park-until-ready (~60s), aligning omnigent's executor waiting for
+     * the bridge instead of a short race that falls back to a second output path.
+     */
+    async injectMessage(localThreadId, text) {
+        const claude = this.liveClaudeSessions.get(localThreadId);
+        if (claude)
+            return this.injectClaude(claude, localThreadId, text);
+        const live = this.liveSessions.get(localThreadId);
+        if (!live)
+            return "notLive";
+        const run = live.injectLock.then(async () => {
+            // Park until the thread binds (~60s, omnigent codex_native_executor:177-186),
+            // not a 20s race that returns false and lets the caller re-run on a 2nd path.
+            const bound = await this.waitLiveReady(localThreadId, 60_000);
+            const threadId = live.threadId ?? live.forwarder.threadId();
+            if (!bound || !threadId)
+                return "notReady";
+            const input = buildTextUserInput(text);
+            try {
+                // Inject via the BACKEND client (the forwarder connection only observes).
+                if (live.forwarder.isTurnOpen()) {
+                    const turnId = live.forwarder.currentTurnId();
+                    if (turnId) {
+                        await live.injectClient.turnSteer({ threadId, expectedTurnId: turnId, input });
+                        return "injected";
+                    }
+                }
+                // Carry the agent-spec model on the turn so a web-injected turn runs the
+                // agent's model even if the TUI's config default differs.
+                await live.injectClient.turnStart({ threadId, input, cwd: live.cwd, model: live.model });
+                return "injected";
+            }
+            catch {
+                // RPC failed → hard error; caller reports it and does NOT re-run
+                // (omnigent: inject failure ⇒ response.failed, never local re-run).
+                return "failed";
+            }
+        });
+        live.injectLock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * Interrupt the session's active turn — the web Stop button. codex: the
+     * app-server `turn/interrupt` on the active `{threadId, turnId}` (exactly what
+     * codex's own TUI interrupt key sends — omnigent `_handle_codex_native_interrupt`).
+     * claude: an Escape keystroke into the pane (no app-server — omnigent
+     * `inject_interrupt`). Returns false as a no-op when there is no active turn.
+     */
+    async interruptLive(localThreadId) {
+        const claude = this.liveClaudeSessions.get(localThreadId);
+        if (claude) {
+            if (!claude.injector)
+                return false;
+            const turnOpen = claude.forwarder.isTurnOpen();
+            const injecting = claude.injectAbort !== undefined;
+            // Nothing to interrupt: idle pane, no turn, no in-flight injection. Do NOT
+            // send Escape — an Escape into idle claude submits an empty turn, which
+            // claude answers with a stray "No response requested." bubble.
+            if (!turnOpen && !injecting)
+                return false;
+            // Cancel an in-flight injection FIRST so its submit/verify loop can't re-send
+            // Enter after we clear the box, then clear any half-typed / re-populated draft.
+            claude.injectAbort?.abort();
+            claude.injector.clearInputLine();
+            // Only send Escape (+ close the turn UI-side) when a response is actually
+            // running — otherwise clearing the pending injection above is the whole job.
+            if (turnOpen) {
+                claude.injector.interrupt();
+                // An interrupt that cancels a response before it produced output (or before
+                // its Stop hook fires) would leave the spinner stuck until the 30s
+                // inactivity backstop — treat it like a Stop and close the turn now.
+                claude.forwarder.noteInterrupted();
+            }
+            return true;
+        }
+        const live = this.liveSessions.get(localThreadId);
+        if (!live)
+            return false;
+        // Only interrupt an OPEN turn — codex's app-server rejects a stale turnId, and
+        // omnigent no-ops (204) when no turn is active.
+        if (!live.forwarder.isTurnOpen())
+            return false;
+        const threadId = live.threadId ?? live.forwarder.threadId();
+        const turnId = live.forwarder.currentTurnId();
+        if (!threadId || !turnId)
+            return false;
+        try {
+            await live.injectClient.turnInterrupt({ threadId, turnId });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Stop + drop a session's live forwarder and its dedicated connection (session
+     *  close / runner shutdown). The backend inject client is shared — left running. */
+    stopLiveCodexSession(localThreadId) {
+        const claude = this.liveClaudeSessions.get(localThreadId);
+        if (claude) {
+            this.liveClaudeSessions.delete(localThreadId);
+            claude.stopped = true;
+            claude.forwarder.stop();
+            // Remove the throwaway skills --plugin-dir temp so it doesn't leak per launch.
+            void claude.skillCleanup?.();
+            return;
+        }
+        const live = this.liveSessions.get(localThreadId);
+        if (!live)
+            return;
+        this.liveSessions.delete(localThreadId);
+        live.stopped = true;
+        live.releaseActive?.();
+        live.forwarder.stop();
+        void live.forwarderClient.stop().catch(() => undefined);
+        // Remove the session-scoped skills dir — the machine keeps zero task residue.
+        void live.skillsCleanup?.();
+    }
+    // --- claude-native live session (parallel to the codex methods above) -----
+    /** The interactive `claude` TUI spec for a claude-native live session: the real
+     *  `claude` binary with rynx's hooks (`--settings`), resuming the bound session.
+     *  Trust is pre-seeded so the daemon-spawned TUI never blocks on a first-run
+     *  prompt. (PermissionRequest approvals land in Phase 6; until then the TUI
+     *  surfaces its own permission prompt in the co-driven pane.) */
+    claudeTerminalSpec(localThreadId, record) {
+        const cwd = record?.cwd ?? process.cwd();
+        try {
+            ensureProjectTrusted(cwd);
+        }
+        catch {
+            // A malformed ~/.claude.json shouldn't block launch; claude re-prompts.
+        }
+        const settings = buildClaudeHookSettings({
+            bridgeDir: claudeBridgeDir(localThreadId),
+            permission: Boolean(process.env.RYNX_CONTROL_URL?.trim()),
+            messageDisplay: true,
+            statusLine: true,
+        });
+        // The live session (created by startLiveClaudeSession before the pane launches)
+        // carries the agent-spec launch config: model + `--plugin-dir` (skills; no persona).
+        const live = this.liveClaudeSessions.get(localThreadId);
+        const args = buildClaudeTuiArgs({
+            settingsJson: JSON.stringify(settings),
+            model: live?.launchModel ?? resolveRuntimeModel(this.config, "claude", record?.model),
+            ...(record?.codexSessionId ? { resume: record.codexSessionId } : {}),
+            ...(live?.launchExtraArgs?.length ? { extraArgs: live.launchExtraArgs } : {}),
+        });
+        return {
+            command: resolveRuntimeBinary("claude"),
+            args,
+            cwd,
+            // Same env the pane would inherit by default, plus the session scope for
+            // agent-run CLIs (rynx-emulator resolves device-less commands via it).
+            env: { ...process.env, RYNX_SESSION_ID: localThreadId },
+        };
+    }
+    /** Bring up a claude-native live forwarder: prepare the bridge dir (the TUI's
+     *  hooks write into it), then tail bridge + transcript and drive a per-turn
+     *  {@link SessionNormalizer} → `emit` (the SAME sink shape the codex path uses). */
+    /** Resolve an agent spec's launch config — model + the session skill env —
+     *  for a LIVE native session, reusing the same core resolvers the non-live
+     *  run path uses ({@link resolveAgentExecution} for the model,
+     *  {@link resolveAgent} for skills). Instructions are intentionally NOT
+     *  returned: the co-driven TUI runs on vendor defaults (see
+     *  startLiveClaudeSession).
+     *
+     *  Skills are spec-rooted: each declared ref is replayed into a
+     *  SESSION-scoped temp dir (cache-accelerated); the owner's catalog plays no
+     *  role, and no spec / no `skills` means ZERO skills. The env-build report
+     *  (installs, failures, content drift) is logged — a declared skill that
+     *  can't be provisioned is loudly absent, never silent; the session still
+     *  starts. `skillsCleanup` removes the session dir (call on session stop). */
+    async resolveLiveAgentConfig(localThreadId, opts, runtime, cwd) {
+        // Inline spec needs an id only so a relative instructions-file path can
+        // resolve (mirrors runLocked); a preset agent loads by name.
+        const spec = opts?.agentSpec
+            ? { ...opts.agentSpec, id: opts.agentName ?? "inline" }
+            : undefined;
+        const exec = await resolveAgentExecution({
+            config: this.config,
+            ...(opts?.agentName ? { agentName: opts.agentName } : {}),
+            ...(opts?.agentSpec ? { spec: opts.agentSpec } : {}),
+            runtime,
+        });
+        const resolved = await resolveAgent({
+            config: this.config,
+            cwd,
+            ...(opts?.agentName ? { agentName: opts.agentName } : {}),
+            ...(spec ? { spec } : {}),
+        });
+        const sessionSkillsDir = await mkdtemp(path.join(tmpdir(), "rynx-session-skills-"));
+        const skillEnv = await buildAgentSkillEnvironment(resolved.skills, sessionSkillsDir);
+        const agent = opts?.agentName ?? resolved.name ?? "-";
+        const { report } = skillEnv;
+        if (report.errors.length > 0 || report.missing.length > 0) {
+            console.error(`[skills] session=${localThreadId} agent=${agent} missing=[${report.missing.join(", ")}] ${report.errors.join("; ")}`);
+        }
+        if (report.installed.length > 0) {
+            console.error(`[skills] session=${localThreadId} agent=${agent} installed=[${report.installed.join(", ")}]`);
+        }
+        for (const note of report.drift) {
+            console.error(`[skills] session=${localThreadId} agent=${agent} drift: ${note}`);
+        }
+        return {
+            model: exec.model,
+            selectedSkills: skillEnv.resolved,
+            skillsCleanup: () => rm(sessionSkillsDir, { recursive: true, force: true }),
+            ...(resolved.sandbox ? { sandbox: resolved.sandbox } : {}),
+            ...(resolved.approvalPolicy ? { approvalPolicy: resolved.approvalPolicy } : {}),
+            ...(resolved.permissionMode ? { permissionMode: resolved.permissionMode } : {}),
+        };
+    }
+    async startLiveClaudeSession(localThreadId, emit, record, opts) {
+        const retargetMirror = opts?.retargetMirror;
+        const bridgeDir = prepareClaudeBridgeDir(localThreadId, this.claudePermissionConfig(localThreadId));
+        const cwd = record?.cwd ?? process.cwd();
+        // Apply the agent spec (model / skills / instructions) to the live TUI launch —
+        // NOT just the config default. The stored record model wins if present (a
+        // resumed thread), else the agent-spec resolution. Spec-load errors are logged
+        // and fail the start loudly (mirrors the codex path).
+        let liveCfg;
+        try {
+            liveCfg = await this.resolveLiveAgentConfig(localThreadId, opts, "claude", cwd);
+        }
+        catch (err) {
+            console.error(`[agent-spec] session=${localThreadId} agent=${opts?.agentName ?? "-"} failed to resolve: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+        const model = resolveRuntimeModel(this.config, "claude", record?.model ?? liveCfg.model);
+        // Skills → throwaway `--plugin-dir`. Persona/instructions are deliberately NOT
+        // injected into the co-driven TUI: omnigent's claude-native and codex-native both
+        // leave the live thread on the vendor's built-in defaults (+ workspace AGENTS.md),
+        // so rynx matches (the non-live run path still injects persona for both runtimes).
+        // The plugin dir gets its own copy, so the session skills dir is disposable here.
+        const skillPlugin = await materializeSkillPlugin(liveCfg.selectedSkills);
+        void liveCfg.skillsCleanup();
+        // Agent-spec permission mode → claude's `--permission-mode` (claude-private
+        // approval axis). Unset sends no flag (claude's own default); any set value
+        // is passed through (`bypassPermissions` is how an agent opts out of the
+        // approval prompt). The shared `sandbox` axis is intentionally NOT applied
+        // here — the live co-drive TUI runs unsandboxed (matches omnigent's native).
+        const permissionMode = liveCfg.permissionMode;
+        const launchExtraArgs = [
+            ...(skillPlugin?.pluginDir ? ["--plugin-dir", skillPlugin.pluginDir] : []),
+            ...(permissionMode ? ["--permission-mode", permissionMode] : []),
+        ];
+        // The CURRENT rynx session this forwarder mirrors into — starts as the launch
+        // session, re-pointed on a `/clear`·`/fork` rotation (see onSessionRotated).
+        let currentSessionId = localThreadId;
+        let normalizer = null;
+        let currentResponseId;
+        const startNormalizer = (turnId) => {
+            // turnId unknown → fixed literal (never random), aligning omnigent `_response_id`.
+            currentResponseId = turnId ? `resp_claude_${turnId}` : "resp_claude_native";
+            normalizer = new SessionNormalizer({
+                sessionId: currentSessionId,
+                responseId: currentResponseId,
+                model,
+            });
+            return normalizer;
+        };
+        let markReady;
+        const ready = new Promise((resolve) => {
+            markReady = resolve;
+        });
+        const live = {
+            forwarder: null,
+            cwd,
+            bridgeDir,
+            injectLock: Promise.resolve(),
+            ready,
+            markReady,
+            discoveredReady: false,
+            stopped: false,
+            launchModel: model,
+            launchExtraArgs,
+            ...(skillPlugin?.cleanup ? { skillCleanup: skillPlugin.cleanup } : {}),
+        };
+        const sink = {
+            onTurnStart: (turnId) => startNormalizer(turnId),
+            onUserMessage: (text) => {
+                const n = normalizer ?? startNormalizer();
+                for (const se of n.userInput(text))
+                    emit(se);
+            },
+            onTerminalCommand: (cmd) => {
+                const n = normalizer ?? startNormalizer();
+                for (const se of n.terminalCommand(cmd))
+                    emit(se);
+            },
+            onTodos: (todos) => emit({ type: "session.todos", sessionId: currentSessionId, todos }),
+            onEvent: (event) => {
+                const n = normalizer ?? startNormalizer();
+                for (const se of n.next(event))
+                    emit(se);
+            },
+            onTurnEnd: (usage) => {
+                if (!normalizer)
+                    return;
+                const rid = currentResponseId;
+                // statusLine usage (context/cost) rides the turn's response.completed.
+                if (usage)
+                    for (const se of normalizer.next({ type: "turn_completed", usage }))
+                        emit(se);
+                for (const se of normalizer.next({ type: "done" }))
+                    emit(se);
+                normalizer = null;
+                // One-time context-window banner past CONTEXT_WARN_RATIO (a transient note,
+                // cleared by the next turn's first item). statusLine pre-computes the %.
+                const pct = usage && typeof usage.used_percentage === "number" ? usage.used_percentage : undefined;
+                if (rid && pct !== undefined && !live.contextWarned && pct >= CONTEXT_WARN_RATIO * 100) {
+                    live.contextWarned = true;
+                    emit({
+                        type: "session.status",
+                        sessionId: currentSessionId,
+                        responseId: rid,
+                        status: "idle",
+                        note: `context ${Math.round(pct)}% full — consider /compact`,
+                    });
+                }
+            },
+            onIdle: () => {
+                // Surface idle on the current turn WITHOUT finalizing it (see the sink's
+                // onIdle doc): a late assistant record still joins this response.
+                if (currentResponseId) {
+                    emit({
+                        type: "session.status",
+                        sessionId: currentSessionId,
+                        responseId: currentResponseId,
+                        status: "idle",
+                    });
+                }
+            },
+            onTurnError: (error) => {
+                if (!normalizer)
+                    return;
+                for (const se of normalizer.fail({ code: "claude_error", message: error.message, source: "execution" }))
+                    emit(se);
+                normalizer = null;
+            },
+            onSessionDiscovered: (claudeSessionId) => this.onClaudeDiscovered(live, localThreadId, opts?.agentName ?? record?.agent, claudeSessionId),
+            onSessionRotated: (kind, claudeSessionId) => {
+                // The forwarder already closed the old turn (onTurnEnd) + re-pointed to the
+                // new transcript. Rotate the rynx session: announce on the OLD session (the
+                // mirror still targets it), mint a fresh one, persist it, and re-target the
+                // mirror + terminal transfer so the new session is live AND injectable.
+                const previousSessionId = currentSessionId;
+                const newSessionId = makeSessionId();
+                emit({ type: "session.rotated", sessionId: previousSessionId, newSessionId, kind });
+                void this.sessionStore
+                    .set({
+                    localThreadId: newSessionId,
+                    codexSessionId: claudeSessionId,
+                    cwd: live.cwd,
+                    model,
+                    runtime: "claude",
+                    ...(record?.agent ? { agent: record.agent } : {}),
+                    ...(kind === "fork" ? { parentSessionId: previousSessionId } : {}),
+                    updatedAt: new Date().toISOString(),
+                })
+                    .catch(() => undefined);
+                currentSessionId = newSessionId;
+                normalizer = null;
+                live.contextWarned = false;
+                // Route the new session to THIS live session (host map) + this runner (daemon).
+                this.liveClaudeSessions.set(newSessionId, live);
+                retargetMirror?.(newSessionId, {
+                    kind,
+                    ...(record?.agent ? { agent: record.agent } : {}),
+                    model,
+                    cwd: live.cwd,
+                    parentSessionId: previousSessionId,
+                });
+            },
+        };
+        // Resume: a known claude session id → tail its transcript immediately.
+        const transcriptPath = record?.codexSessionId
+            ? claudeTranscriptPath(cwd, record.codexSessionId)
+            : undefined;
+        live.forwarder = new ClaudeLiveSession({
+            bridgeDir,
+            sink,
+            ...(transcriptPath ? { transcriptPath } : {}),
+            ...(record?.codexSessionId ? { claudeSessionId: record.codexSessionId } : {}),
+        });
+        this.liveClaudeSessions.set(localThreadId, live);
+        live.forwarder.start();
+        if (record?.codexSessionId) {
+            live.discoveredReady = true;
+            markReady(); // resumed → injection can proceed without awaiting discovery
+        }
+        return true;
+    }
+    /** Persist claude's discovered session id (reusing the `codexSessionId` store
+     *  field, as the claude executor already does) and release the readiness gate. */
+    onClaudeDiscovered(live, localThreadId, agent, claudeSessionId) {
+        if (live.discoveredReady)
+            return;
+        live.discoveredReady = true;
+        void this.sessionStore
+            .set({
+            localThreadId,
+            codexSessionId: claudeSessionId,
+            cwd: live.cwd,
+            // Persist the agent-spec-resolved launch model (was the config default).
+            model: live.launchModel,
+            runtime: "claude",
+            agent,
+            updatedAt: new Date().toISOString(),
+        })
+            .catch(() => undefined);
+        live.markReady();
+    }
+    /** Inject a web message into a claude-native pane via tmux (omnigent recipe),
+     *  serialized per session. Parks until the thread is ready AND the tmux injector
+     *  is (re)attached, then pastes; `injectViaTerminal` RAISES if the prompt never
+     *  appears (omnigent RAISE), so a not-ready pane is a hard error — NOT a
+     *  fall-through-to-run signal. Returns {@link InjectOutcome}. */
+    injectClaude(live, localThreadId, text) {
+        const run = live.injectLock.then(async () => {
+            const ready = await this.waitLiveReady(localThreadId, 60_000);
+            if (!ready)
+                return "notReady";
+            // Pane may have just relaunched — park until its injector re-attaches
+            // (attachTerminalInjector resets it) instead of returning false → fallback.
+            const injector = await this.waitInjector(live, 60_000);
+            if (!injector)
+                return "notReady";
+            // Abortable: the web Stop button cancels an in-flight paste/submit (before
+            // the message reaches claude) via interruptLive → injectAbort.abort().
+            const abort = new AbortController();
+            live.injectAbort = abort;
+            try {
+                const ok = await injectViaTerminal(injector, text, { signal: abort.signal });
+                return ok ? "injected" : "failed";
+            }
+            catch {
+                return "failed";
+            }
+            finally {
+                if (live.injectAbort === abort)
+                    live.injectAbort = undefined;
+            }
+        });
+        live.injectLock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Park until the claude session's tmux injector is (re)attached by the
+     *  runner-child, or the deadline passes. Pane relaunch re-attaches it via
+     *  {@link attachTerminalInjector}; without this a message during that window
+     *  would fail and (pre-omnigent) fall through to a second output path. */
+    async waitInjector(live, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (!live.injector && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 150));
+        }
+        return live.injector ?? null;
+    }
+    /** Attach a session's tmux pane injector (from the runner-child, which owns the
+     *  terminal registry — the host does not hold tmux). Ignored for codex sessions
+     *  (they inject via the app-server). Idempotent. */
+    attachTerminalInjector(localThreadId, injector) {
+        const live = this.liveClaudeSessions.get(localThreadId);
+        if (live)
+            live.injector = injector;
+    }
+    /** The PermissionRequest hook's server target from the runner-child env (the
+     *  daemon control URL + token), or undefined when unset — then no permission
+     *  hook is registered and claude surfaces its own TUI prompt in the pane. */
+    claudePermissionConfig(localThreadId) {
+        const serverUrl = process.env.RYNX_CONTROL_URL?.trim();
+        if (!serverUrl)
+            return undefined;
+        return { sessionId: localThreadId, serverUrl };
+    }
+    /** List the models a runtime exposes (App Server for codex/traex; static for claude). */
+    async listModels(runtime) {
+        const resolved = runtime ?? this.defaultRuntime;
+        if (resolved === "claude") {
+            // The Agent SDK has no per-install model-list RPC; serve the curated list.
+            return listClaudeModels();
+        }
+        const backend = this.getBackend(resolved);
+        if (!backend.appServerClient) {
+            return null;
+        }
+        return backend.appServerClient.modelList();
+    }
+    /**
+     * Run a per-thread capability against a session's active thread on whichever
+     * runtime it is bound to. Normalises the "no app-server backend" and "session
+     * has no thread yet" cases into a `CapabilityResult`.
+     */
+    async withCodexThread(localThreadId, fn) {
+        const record = await this.sessionStore.get(localThreadId);
+        if (!record?.codexSessionId) {
+            return { ok: false, reason: "no_active_thread" };
+        }
+        const backend = this.getBackend(record.runtime ?? "codex");
+        if (!backend.appServerClient) {
+            return { ok: false, reason: "unsupported" };
+        }
+        try {
+            return { ok: true, data: await fn(backend.appServerClient, record.codexSessionId) };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: "error",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async getGoal(localThreadId) {
+        return this.withCodexThread(localThreadId, async (client, threadId) => {
+            const response = await client.threadGoalGet({ threadId });
+            return response.goal ?? null;
+        });
+    }
+    async setGoal(localThreadId, objective) {
+        return this.withCodexThread(localThreadId, async (client, threadId) => {
+            await client.threadGoalSet({ threadId, objective });
+        });
+    }
+    async clearGoal(localThreadId) {
+        return this.withCodexThread(localThreadId, async (client, threadId) => {
+            await client.threadGoalClear({ threadId });
+        });
+    }
+    async forkSession(currentLocalThreadId, newLocalThreadId) {
+        const record = await this.sessionStore.get(currentLocalThreadId);
+        if (!record) {
+            return { ok: false, reason: "no_active_thread" };
+        }
+        const runtime = record.runtime ?? "codex";
+        const backend = this.getBackend(runtime);
+        if (!backend.appServerClient) {
+            return { ok: false, reason: "unsupported" };
+        }
+        try {
+            const forked = await backend.appServerClient.threadFork({
+                threadId: record.codexSessionId,
+                model: record.model,
+                cwd: record.cwd,
+            });
+            const forkedThreadId = forked.thread.id;
+            await this.sessionStore.set({
+                localThreadId: newLocalThreadId,
+                codexSessionId: forkedThreadId,
+                cwd: record.cwd,
+                model: record.model,
+                runtime,
+                updatedAt: new Date().toISOString(),
+            });
+            return { ok: true, data: undefined };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: "error",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+export function parseCodexLoginStatus(exitCode, output) {
+    const normalized = output.trim();
+    const match = normalized.match(/Logged in using (.+)$/im);
+    if (exitCode === 0 && match) {
+        return {
+            loggedIn: true,
+            authMode: match[1].trim(),
+            issues: [],
+        };
+    }
+    if (/not logged in|logged out/i.test(normalized)) {
+        return {
+            loggedIn: false,
+            authMode: null,
+            issues: [],
+        };
+    }
+    return {
+        loggedIn: exitCode === 0,
+        authMode: match?.[1]?.trim() ?? null,
+        issues: normalized ? [normalized] : [],
+    };
+}
+/** Race a live session's `ready` promise against a timeout → resolves boolean. */
+function raceReady(ready, timeoutMs) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+    });
+    return Promise.race([ready.then(() => true), timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+export function getCodexModel(config, override) {
+    return override?.trim() || config.CODEX_MODEL;
+}
+export { createCodexChildEnv };
+export function isUnsupportedMethodError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const code = error.code;
+    if (code === -32600 || code === -32601) {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return /unknown variant|method not found|unsupported method|not supported/i.test(message);
+}
+/** A `thread/resume` failure meaning the thread has no (or an empty) rollout yet
+ *  — a fresh TUI thread before its first turn. Retryable (park until active).
+ *  Mirrors omnigent's `_is_thread_not_ready_error`. */
+export function isThreadNotReadyError(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return message.includes("no rollout found") || (message.includes("rollout") && message.includes("empty"));
+}