@rynx-ai/runtime 0.1.0 → 0.1.10-beta.2

package/dist/index.d.ts

@@ -8,9 +8,10 @@ export { LocalAgentHost, CodexRuntimeError, SpawnCodexCommandRunner, FileCodexSe
 export type { CodexCapabilities, CapabilityResult, CodexRuntimeStatus, } from "./host.js";
 export type { CodexSessionStore, CodexSessionRecord } from "./codex-session-store.js";
 export { ensureCodexResumeRollout } from "./codex/rollout-synth.js";
-export { RunnerManager } from "./runner/manager.js";
-export type { RunnerManagerOptions, OpenTerminalOptions, ParentTerminal, } from "./runner/manager.js";
-export type { InjectOutcome, TerminalRole } from "./runner/protocol.js";
+export { RunnerManager, TerminalOpenError } from "./runner/manager.js";
+export type { RunnerManagerOptions, RunnerSessionContext, RunnerSessionContextProvider, OpenTerminalOptions, ParentTerminal, } from "./runner/manager.js";
+export type { InjectOutcome, TerminalOpenErrorCode, TerminalRole } from "./runner/protocol.js";
+export type { ResolveInteractionResult, RuntimeInteractionEvent, RuntimeInteractionListener, } from "./interactions.js";
 export { probeRuntimeStatus } from "./runtime-status.js";
 export { listRuntimeModels } from "./models-catalog.js";
 export { TmuxTerminal, isTmuxAvailable } from "./terminal/tmux.js";

package/dist/index.js

@@ -9,7 +9,7 @@ export { ensureCodexResumeRollout } from "./codex/rollout-synth.js";
 // Runner subprocess layer: the parent-side manager (an `AgentExecutor` +
 // `AgentCapabilities` that spawns per-session runner children) plus the wire
 // types. The composition root uses `RunnerManager` in place of `LocalAgentHost`.
-export { RunnerManager } from "./runner/manager.js";
+export { RunnerManager, TerminalOpenError } from "./runner/manager.js";
 export { probeRuntimeStatus } from "./runtime-status.js";
 export { listRuntimeModels } from "./models-catalog.js";
 // Live-terminal subsystem (Phase C): tmux-backed terminals + per-runner registry.

package/dist/input-resources.d.ts

@@ -0,0 +1,13 @@
+import type { InputImageContentPart, RuntimeUserInput, UserContentPart } from "@rynx-ai/core";
+import type { UserInput } from "./codex-app-server/protocol.js";
+/** Convert the provider-native user echo back to resource references. Unknown
+ * local paths and remote URLs are deliberately omitted rather than exposed. */
+export declare function codexUserContent(input: readonly UserInput[]): UserContentPart[];
+/** Claude's native TUI has no structured image RPC. The target daemon supplies
+ * only managed local paths and the marker makes the transcript echo reversible. */
+export declare function claudeInputText(input: RuntimeUserInput, attachmentToken?: string): string;
+/** Extract only the one-time token. The host resolves it through its in-memory
+ * pending-injection map; user-authored lookalikes have no entry and remain text. */
+export declare function claudeAttachmentToken(text: string): string | undefined;
+export declare function runtimeUserContent(input: RuntimeUserInput): UserContentPart[];
+export declare function managedImagePart(path: string): InputImageContentPart | undefined;

package/dist/input-resources.js

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import { basename, extname } from "node:path";
+const CLAUDE_ATTACHMENT_TOKEN = "RYNX_ATTACHMENT_SET";
+const CLAUDE_ATTACHMENT_TOKEN_RE = /^\[RYNX_ATTACHMENT_SET (att_[0-9a-f-]{36}): inspect each RYNX_IMAGE_RESOURCE path with the Read tool before answering\.\]$/m;
+/** Convert the provider-native user echo back to resource references. Unknown
+ * local paths and remote URLs are deliberately omitted rather than exposed. */
+export function codexUserContent(input) {
+    const parts = [];
+    for (const part of input) {
+        if (part.type === "text") {
+            if (part.text)
+                parts.push({ type: "input_text", text: part.text });
+            continue;
+        }
+        if (part.type === "localImage") {
+            const image = managedImagePart(part.path);
+            if (image)
+                parts.push(image);
+        }
+    }
+    return parts;
+}
+/** Claude's native TUI has no structured image RPC. The target daemon supplies
+ * only managed local paths and the marker makes the transcript echo reversible. */
+export function claudeInputText(input, attachmentToken = `att_${randomUUID()}`) {
+    const images = input.content.filter((part) => part.type === "local_image");
+    const text = input.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+    if (images.length === 0)
+        return text;
+    if (!/^att_[0-9a-f-]{36}$/.test(attachmentToken)) {
+        throw new Error("Claude attachment token is invalid");
+    }
+    const preamble = `[${CLAUDE_ATTACHMENT_TOKEN} ${attachmentToken}: inspect each RYNX_IMAGE_RESOURCE path with the Read tool before answering.]`;
+    const markers = images.map((part) => `[[RYNX_IMAGE_RESOURCE ${JSON.stringify({ path: part.path })}]]`);
+    return [preamble, ...markers, text]
+        .filter((part, index) => index <= markers.length || part.length > 0)
+        .join("\n");
+}
+/** Extract only the one-time token. The host resolves it through its in-memory
+ * pending-injection map; user-authored lookalikes have no entry and remain text. */
+export function claudeAttachmentToken(text) {
+    return text.match(CLAUDE_ATTACHMENT_TOKEN_RE)?.[1];
+}
+export function runtimeUserContent(input) {
+    return input.content.map((part) => part.type === "text"
+        ? { type: "input_text", text: part.text }
+        : { ...part.resource });
+}
+export function managedImagePart(path) {
+    const extension = extname(path).toLowerCase();
+    const mediaType = extension === ".png"
+        ? "image/png"
+        : extension === ".jpg" || extension === ".jpeg"
+            ? "image/jpeg"
+            : extension === ".webp"
+                ? "image/webp"
+                : undefined;
+    if (!mediaType)
+        return undefined;
+    const resourceId = basename(path, extension);
+    if (!/^res_[0-9a-f-]{36}$/i.test(resourceId))
+        return undefined;
+    return { type: "input_image", resourceId, mediaType };
+}

package/dist/interactions.d.ts

@@ -0,0 +1,61 @@
+import { type SessionInteractionRequest, type SessionInteractionResolution } from "@rynx-ai/core";
+/** Provider-neutral lifecycle emitted by a native runtime adapter. */
+export type RuntimeInteractionEvent = {
+    type: "requested";
+    request: SessionInteractionRequest;
+    /** Native Turn correlation, when the provider exposes it. */
+    turnId?: string;
+} | {
+    type: "resolved";
+    interactionId: string;
+    resolution: SessionInteractionResolution;
+    turnId?: string;
+} | {
+    type: "cancelled";
+    interactionId: string;
+    reason?: string;
+    turnId?: string;
+};
+export type RuntimeInteractionListener = (event: RuntimeInteractionEvent) => void;
+/** Result of attempting to answer a pending native interaction. */
+export type ResolveInteractionResult = {
+    disposition: "applied";
+} | {
+    disposition: "already_resolved";
+} | {
+    disposition: "not_found";
+} | {
+    disposition: "invalid";
+    message: string;
+};
+export type InteractionResolution = SessionInteractionResolution;
+export declare const INTERACTION_LIMITS: {
+    readonly idBytes: 256;
+    readonly titleBytes: 1024;
+    readonly labelBytes: 1024;
+    readonly descriptionBytes: number;
+    readonly contextBytes: number;
+    readonly requestBytes: number;
+    readonly fields: 64;
+    readonly optionsPerField: 128;
+    readonly actions: 16;
+    readonly routingSkeletonBytes: number;
+};
+export type BoundInteractionRequestResult = {
+    ok: true;
+    request: SessionInteractionRequest;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Bound an untrusted provider request before it enters the canonical event
+ * stream. Lists that affect native answer routing are rejected when oversized;
+ * option lists may be truncated to a still-answerable subset. */
+export declare function boundInteractionRequest(request: SessionInteractionRequest): BoundInteractionRequestResult;
+/** Validate a provider-neutral resolution against the exact advertised form.
+ * Unknown keys and wrong answer shapes are rejected even for deny/cancel; the
+ * selected action's `requiresAnswers` controls only whether required fields may
+ * be omitted. */
+export declare function validateInteractionResolution(request: SessionInteractionRequest, resolution: SessionInteractionResolution): string | undefined;
+/** Secret values reach the native runtime but never enter canonical history. */
+export declare function redactInteractionResolution(request: SessionInteractionRequest, resolution: SessionInteractionResolution): SessionInteractionResolution;

package/dist/interactions.js

@@ -0,0 +1,236 @@
+import { boundSessionInteractionRouting, sessionInteractionRoutingSkeletonBytes, SESSION_INTERACTION_STRUCTURAL_LIMITS, } from "@rynx-ai/core";
+export const INTERACTION_LIMITS = {
+    ...SESSION_INTERACTION_STRUCTURAL_LIMITS,
+    idBytes: 256,
+    titleBytes: 1024,
+    labelBytes: 1024,
+    descriptionBytes: 8 * 1024,
+    contextBytes: 64 * 1024,
+    // SessionNormalizer carries the request twice (event + durable item). 240 KiB
+    // leaves 32 KiB for both wrappers under the daemon's 512 KiB event limit.
+    requestBytes: 240 * 1024,
+};
+/** UTF-8 byte-safe truncation: iteration is by Unicode code point, so neither a
+ * surrogate pair nor a multi-byte sequence is split. */
+function truncateUtf8(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    const suffix = "…";
+    const budget = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
+    let result = "";
+    let bytes = 0;
+    for (const char of value) {
+        const width = Buffer.byteLength(char, "utf8");
+        if (bytes + width > budget)
+            break;
+        result += char;
+        bytes += width;
+    }
+    return `${result}${suffix}`;
+}
+function validId(id) {
+    return id.length > 0 && Buffer.byteLength(id, "utf8") <= INTERACTION_LIMITS.idBytes;
+}
+/** Bound an untrusted provider request before it enters the canonical event
+ * stream. Lists that affect native answer routing are rejected when oversized;
+ * option lists may be truncated to a still-answerable subset. */
+export function boundInteractionRequest(request) {
+    if (!validId(request.interactionId)) {
+        return { ok: false, reason: "interaction id exceeds the canonical limit" };
+    }
+    if (request.fields.length > INTERACTION_LIMITS.fields) {
+        return { ok: false, reason: "interaction has too many fields" };
+    }
+    if (request.actions.length === 0 || request.actions.length > INTERACTION_LIMITS.actions) {
+        return { ok: false, reason: "interaction has an invalid number of actions" };
+    }
+    const seenFields = new Set();
+    const fields = [];
+    for (const field of request.fields) {
+        if (!validId(field.id) || seenFields.has(field.id)) {
+            return { ok: false, reason: "interaction has an invalid or duplicate field id" };
+        }
+        seenFields.add(field.id);
+        const label = truncateUtf8(field.label, INTERACTION_LIMITS.labelBytes);
+        const description = field.description !== undefined
+            ? truncateUtf8(field.description, INTERACTION_LIMITS.descriptionBytes)
+            : undefined;
+        if (field.type === "text") {
+            fields.push({
+                id: field.id,
+                type: "text",
+                label,
+                ...(description !== undefined ? { description } : {}),
+                ...(field.required !== undefined ? { required: field.required } : {}),
+                ...(field.secret !== undefined ? { secret: field.secret } : {}),
+                ...(field.multiline !== undefined ? { multiline: field.multiline } : {}),
+                ...(field.placeholder !== undefined
+                    ? { placeholder: truncateUtf8(field.placeholder, INTERACTION_LIMITS.labelBytes) }
+                    : {}),
+            });
+            continue;
+        }
+        const options = [];
+        const seenOptions = new Set();
+        for (const option of field.options.slice(0, INTERACTION_LIMITS.optionsPerField)) {
+            if (!validId(option.value) || seenOptions.has(option.value)) {
+                return { ok: false, reason: `interaction field has an invalid option id: ${field.id}` };
+            }
+            seenOptions.add(option.value);
+            options.push({
+                ...option,
+                label: truncateUtf8(option.label, INTERACTION_LIMITS.labelBytes),
+                ...(option.description !== undefined
+                    ? { description: truncateUtf8(option.description, INTERACTION_LIMITS.descriptionBytes) }
+                    : {}),
+            });
+        }
+        fields.push({
+            id: field.id,
+            type: "select",
+            label,
+            ...(description !== undefined ? { description } : {}),
+            ...(field.required !== undefined ? { required: field.required } : {}),
+            ...(field.multiple !== undefined ? { multiple: field.multiple } : {}),
+            ...(field.allowOther !== undefined ? { allowOther: field.allowOther } : {}),
+            options,
+        });
+    }
+    const seenActions = new Set();
+    const actions = [];
+    for (const action of request.actions) {
+        if (!validId(action.id) || seenActions.has(action.id)) {
+            return { ok: false, reason: "interaction has an invalid or duplicate action id" };
+        }
+        seenActions.add(action.id);
+        actions.push({
+            ...action,
+            label: truncateUtf8(action.label, INTERACTION_LIMITS.labelBytes),
+            ...(action.description !== undefined
+                ? { description: truncateUtf8(action.description, INTERACTION_LIMITS.descriptionBytes) }
+                : {}),
+        });
+    }
+    const context = request.context
+        ? {
+            ...(request.context.summary !== undefined
+                ? { summary: truncateUtf8(request.context.summary, INTERACTION_LIMITS.descriptionBytes) }
+                : {}),
+            ...(request.context.toolName !== undefined
+                ? { toolName: truncateUtf8(request.context.toolName, INTERACTION_LIMITS.labelBytes) }
+                : {}),
+            ...(request.context.command !== undefined
+                ? { command: truncateUtf8(request.context.command, INTERACTION_LIMITS.contextBytes) }
+                : {}),
+            ...(request.context.cwd !== undefined
+                ? { cwd: truncateUtf8(request.context.cwd, INTERACTION_LIMITS.contextBytes) }
+                : {}),
+            ...(request.context.diff !== undefined
+                ? { diff: truncateUtf8(request.context.diff, INTERACTION_LIMITS.contextBytes) }
+                : {}),
+        }
+        : undefined;
+    const boundedPresentation = {
+        ...request,
+        title: truncateUtf8(request.title, INTERACTION_LIMITS.titleBytes),
+        ...(request.description !== undefined
+            ? { description: truncateUtf8(request.description, INTERACTION_LIMITS.descriptionBytes) }
+            : {}),
+        fields,
+        actions,
+        ...(context ? { context } : {}),
+    };
+    const bounded = boundSessionInteractionRouting(boundedPresentation);
+    const lostOptionCoverage = boundedPresentation.fields.some((source, index) => source.type === "select" &&
+        source.options.length > 0 &&
+        bounded.fields[index]?.type === "select" &&
+        bounded.fields[index].options.length === 0);
+    if (lostOptionCoverage) {
+        return { ok: false, reason: "interaction routing minimum coverage exceeds the canonical budget" };
+    }
+    if (sessionInteractionRoutingSkeletonBytes(bounded) > INTERACTION_LIMITS.routingSkeletonBytes) {
+        return { ok: false, reason: "interaction routing structure exceeds the canonical budget" };
+    }
+    if (Buffer.byteLength(JSON.stringify(bounded), "utf8") > INTERACTION_LIMITS.requestBytes) {
+        return { ok: false, reason: "interaction exceeds the canonical request budget" };
+    }
+    return { ok: true, request: bounded };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Validate a provider-neutral resolution against the exact advertised form.
+ * Unknown keys and wrong answer shapes are rejected even for deny/cancel; the
+ * selected action's `requiresAnswers` controls only whether required fields may
+ * be omitted. */
+export function validateInteractionResolution(request, resolution) {
+    const action = request.actions.find((candidate) => candidate.id === resolution.actionId);
+    if (!action)
+        return `unknown interaction action: ${resolution.actionId}`;
+    const rawAnswers = resolution.answers;
+    if (rawAnswers !== undefined && !isRecord(rawAnswers)) {
+        return "interaction answers must be an object";
+    }
+    const answers = rawAnswers ?? {};
+    const fields = new Map(request.fields.map((field) => [field.id, field]));
+    for (const [id, answer] of Object.entries(answers)) {
+        const field = fields.get(id);
+        if (!field)
+            return `unknown interaction answer: ${id}`;
+        if (field.type === "text") {
+            if (typeof answer !== "string")
+                return `answer must be a string: ${id}`;
+            continue;
+        }
+        const values = field.multiple
+            ? Array.isArray(answer) && answer.every((value) => typeof value === "string")
+                ? answer
+                : null
+            : typeof answer === "string"
+                ? [answer]
+                : null;
+        if (!values) {
+            return field.multiple
+                ? `answer must be a string array: ${id}`
+                : `answer must be a string: ${id}`;
+        }
+        const allowed = new Set(field.options.map((option) => option.value));
+        for (const value of values) {
+            if (allowed.has(value))
+                continue;
+            if (field.allowOther && value.trim().length > 0)
+                continue;
+            return `answer is not an allowed option: ${id}`;
+        }
+    }
+    if (!action.requiresAnswers)
+        return undefined;
+    for (const field of request.fields) {
+        if (!field.required)
+            continue;
+        const answer = answers[field.id];
+        const empty = answer === undefined ||
+            (typeof answer === "string" && answer.trim().length === 0) ||
+            (Array.isArray(answer) &&
+                (answer.length === 0 || answer.some((value) => value.trim().length === 0)));
+        if (empty)
+            return `answer is required: ${field.id}`;
+    }
+    return undefined;
+}
+/** Secret values reach the native runtime but never enter canonical history. */
+export function redactInteractionResolution(request, resolution) {
+    if (!resolution.answers)
+        return resolution;
+    const secretIds = new Set(request.fields
+        .filter((field) => field.type === "text" && field.secret)
+        .map((field) => field.id));
+    if (secretIds.size === 0)
+        return resolution;
+    const answers = { ...resolution.answers };
+    for (const id of secretIds) {
+        if (answers[id] !== undefined)
+            answers[id] = "[redacted]";
+    }
+    return { ...resolution, answers };
+}

package/dist/models-catalog.d.ts

@@ -1,18 +1,10 @@
-/**
- * Backend-free model listing for codex/traex.
- *
- * The parent control plane no longer holds an app-server, so `/models` can't be
- * a live `model/list` RPC anymore. Following omnigent's static-catalog model, we
- * serve a config-derived list: the runtime's configured default model (the one
- * `resolveRuntimeModel` would pick), marked `isDefault`. This is intentionally
- * minimal — a fuller curated catalogue can be added here later without touching
- * any caller. claude already has its own static list ({@link listClaudeModels}).
- */
 import { type AgentRuntimeId, type AppConfig } from "@rynx-ai/core";
 import type { ModelListResponse } from "./codex-app-server/protocol.js";
+export interface RuntimeModelCatalogDeps {
+    readTraexModels?: () => Promise<unknown>;
+}
 /**
  * The model list for a runtime, without an execution backend.
- * Returns `null` when the runtime exposes no resolvable model (e.g. traex with
- * no `TRAEX_MODEL`), matching the prior "unsupported" semantics of `listModels`.
+ * Falls back to the configured model if live Traex discovery is unavailable.
  */
-export declare function listRuntimeModels(config: AppConfig, runtime: AgentRuntimeId): ModelListResponse | null;
+export declare function listRuntimeModels(config: AppConfig, runtime: AgentRuntimeId, deps?: RuntimeModelCatalogDeps): Promise<ModelListResponse | null>;

package/dist/models-catalog.js

@@ -2,26 +2,77 @@
  * Backend-free model listing for codex/traex.
  *
  * The parent control plane no longer holds an app-server, so `/models` can't be
- * a live `model/list` RPC anymore. Following omnigent's static-catalog model, we
- * serve a config-derived list: the runtime's configured default model (the one
- * `resolveRuntimeModel` would pick), marked `isDefault`. This is intentionally
- * minimal — a fuller curated catalogue can be added here later without touching
- * any caller. claude already has its own static list ({@link listClaudeModels}).
+ * a live `model/list` RPC anymore. Following reference implementation's static-catalog model, we
+ * serve a config-derived Codex list and Traex's native `models --json` catalog.
+ * claude already has its own static list ({@link listClaudeModels}).
  */
-import { resolveRuntimeModel, } from "@rynx-ai/core";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { resolveRuntimeBinary, resolveRuntimeModel, } from "@rynx-ai/core";
 import { listClaudeModels } from "./claude/models.js";
+const execFileAsync = promisify(execFile);
+const TRAEX_MODELS_TIMEOUT_MS = 8_000;
+const TRAEX_MODELS_MAX_BYTES = 2 * 1024 * 1024;
 /**
  * The model list for a runtime, without an execution backend.
- * Returns `null` when the runtime exposes no resolvable model (e.g. traex with
- * no `TRAEX_MODEL`), matching the prior "unsupported" semantics of `listModels`.
+ * Falls back to the configured model if live Traex discovery is unavailable.
  */
-export function listRuntimeModels(config, runtime) {
+export async function listRuntimeModels(config, runtime, deps = {}) {
     if (runtime === "claude") {
         return listClaudeModels();
     }
+    if (runtime === "traex") {
+        try {
+            const value = await (deps.readTraexModels ?? readTraexModels)();
+            const models = normalizeTraexModels(value, resolveRuntimeModel(config, runtime).trim());
+            if (models.length > 0)
+                return { data: models };
+        }
+        catch {
+            // Keep the configured fallback usable when Traex is missing/logged out.
+        }
+    }
     const model = resolveRuntimeModel(config, runtime).trim();
     if (!model) {
         return null;
     }
     return { data: [{ id: model, model, isDefault: true }] };
 }
+async function readTraexModels() {
+    const { stdout } = await execFileAsync(resolveRuntimeBinary("traex"), ["models", "--json"], {
+        encoding: "utf8",
+        timeout: TRAEX_MODELS_TIMEOUT_MS,
+        maxBuffer: TRAEX_MODELS_MAX_BYTES,
+    });
+    return JSON.parse(stdout);
+}
+function normalizeTraexModels(value, configuredDefault) {
+    if (!Array.isArray(value))
+        return [];
+    const models = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const record = item;
+        const id = typeof record.name === "string" ? record.name.trim() : "";
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        models.push({
+            id,
+            model: id,
+            ...(typeof record.description === "string" ? { description: record.description } : {}),
+            isDefault: configuredDefault ? id === configuredDefault : models.length === 0,
+            ...(typeof record.context_window === "number" ? { contextWindow: record.context_window } : {}),
+            ...(Array.isArray(record.supported_mime_types)
+                ? { supportedMimeTypes: record.supported_mime_types }
+                : {}),
+            ...(record._meta && typeof record._meta === "object" ? { _meta: record._meta } : {}),
+        });
+    }
+    if (configuredDefault && !seen.has(configuredDefault)) {
+        models.unshift({ id: configuredDefault, model: configuredDefault, isDefault: true });
+    }
+    return models;
+}

package/dist/runner/child.d.ts

@@ -23,11 +23,16 @@ export declare class RunnerSession {
     /** Live terminals hosted by this session, and per-attach client handles. */
     private readonly terminals;
     private readonly attachments;
+    /** Opens are async; a close received before attach resolves tombstones the id. */
+    private readonly pendingTerminalOpens;
+    private readonly cancelledTerminalOpens;
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     private readonly liveIds;
+    private shuttingDown;
     constructor({ transport, executor, onShutdown }: RunnerSessionDeps);
     private handle;
     private get liveProvider();
+    private resolveInteraction;
     /** The mirror channel for a session: an `emit` that forwards every canonical
      *  event to the parent under the CURRENT session id (mutable), plus a `retarget`
      *  the host calls on a `/clear`·`/fork` rotation — it re-points the mirror to the
@@ -40,7 +45,7 @@ export declare class RunnerSession {
      * launch the detached `codex --remote` TUI, which CREATES the codex thread. The
      * forwarder's connection sees the TUI's broadcast `thread/started`, binds, and
      * subscribes — so the TUI is usable immediately (a fresh `--remote` needs no
-     * rollout) and its turns mirror to chat (omnigent's model).
+     * rollout) and its turns mirror to chat (reference implementation's model).
      */
     private ensureLive;
     private inject;
@@ -50,6 +55,9 @@ export declare class RunnerSession {
      *  so the web attach reuses the same detached pane. */
     private launchCodexPane;
     private stopLive;
+    /** Stop event forwarding, kill native terminals/hooks, then synchronously
+     * scrub provider handoff files before the child process is allowed to exit. */
+    shutdown(): void;
     private openTerminal;
     /** Attach an already-created terminal and forward its data/exit to the parent. */
     private attachExisting;