@rynx-ai/runtime 0.1.0 → 0.1.9

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/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

@@ -2,7 +2,7 @@
  * 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
+ * a live `model/list` RPC anymore. Following reference implementation'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

package/dist/models-catalog.js

@@ -2,7 +2,7 @@
  * 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
+ * a live `model/list` RPC anymore. Following reference implementation'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

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;

package/dist/runner/child.js

@@ -7,15 +7,18 @@ export class RunnerSession {
     /** Live terminals hosted by this session, and per-attach client handles. */
     terminals = new TerminalRegistry();
     attachments = new Map();
+    /** Opens are async; a close received before attach resolves tombstones the id. */
+    pendingTerminalOpens = new Set();
+    cancelledTerminalOpens = new Set();
     /** Session ids with a live codex forwarder started here (stopped on shutdown). */
     liveIds = new Set();
+    shuttingDown = false;
     constructor({ transport, executor, onShutdown }) {
         this.transport = transport;
         this.executor = executor;
         this.onShutdown =
             onShutdown ??
                 (() => {
-                    this.terminals.closeAll();
                     transport.close();
                 });
         this.transport.onMessage((msg) => this.handle(msg));
@@ -27,7 +30,20 @@ export class RunnerSession {
                 void this.runCap(msg.capId, msg.name, msg.args);
                 return;
             case "term.open":
-                void this.openTerminal(msg);
+                if (this.pendingTerminalOpens.has(msg.attachId) || this.attachments.has(msg.attachId)) {
+                    this.transport.send({
+                        t: "term.error",
+                        attachId: msg.attachId,
+                        code: "terminal_open_failed",
+                        message: "terminal attachment id is already active",
+                    });
+                    return;
+                }
+                this.pendingTerminalOpens.add(msg.attachId);
+                void this.openTerminal(msg).finally(() => {
+                    this.pendingTerminalOpens.delete(msg.attachId);
+                    this.cancelledTerminalOpens.delete(msg.attachId);
+                });
                 return;
             case "term.input":
                 this.attachments.get(msg.attachId)?.write(Buffer.from(msg.dataB64, "base64").toString("utf8"));
@@ -36,14 +52,16 @@ export class RunnerSession {
                 this.attachments.get(msg.attachId)?.resize(msg.cols, msg.rows);
                 return;
             case "term.close": {
+                if (this.pendingTerminalOpens.has(msg.attachId)) {
+                    this.cancelledTerminalOpens.add(msg.attachId);
+                }
                 const attachment = this.attachments.get(msg.attachId);
                 this.attachments.delete(msg.attachId);
                 attachment?.kill();
                 return;
             }
-            case "approval.resolve": {
-                const provider = this.executor;
-                void provider.resolveApproval?.(msg.localThreadId, msg.approvalId, msg.decision);
+            case "interaction.resolve": {
+                void this.resolveInteraction(msg);
                 return;
             }
             case "live.ensure":
@@ -56,15 +74,31 @@ export class RunnerSession {
                 void this.interruptLive(msg);
                 return;
             case "shutdown":
-                this.stopLive();
-                this.terminals.closeAll();
-                this.onShutdown();
+                this.shutdown();
                 return;
         }
     }
     get liveProvider() {
         return this.executor;
     }
+    async resolveInteraction(msg) {
+        let result;
+        try {
+            result = await this.liveProvider.resolveInteraction?.(msg.localThreadId, msg.interactionId, msg.resolution) ?? { disposition: "not_found" };
+        }
+        catch (error) {
+            result = {
+                disposition: "invalid",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        this.transport.send({
+            t: "interaction.resolved",
+            reqId: msg.reqId,
+            localThreadId: msg.localThreadId,
+            result,
+        });
+    }
     /** 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
@@ -94,20 +128,28 @@ export 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).
      */
     async ensureLive(msg) {
         const provider = this.liveProvider;
         try {
             const { emit, retarget } = this.mirrorChannel(msg.localThreadId);
             const started = await provider.ensureLiveCodexSession?.(msg.localThreadId, emit, {
+                ...(msg.cwd ? { cwd: msg.cwd } : {}),
                 ...(msg.runtime ? { runtime: msg.runtime } : {}),
+                ...(msg.reasoningEffort ? { reasoningEffort: msg.reasoningEffort } : {}),
                 ...(msg.agentName ? { agentName: msg.agentName } : {}),
                 ...(msg.agentSpec ? { agentSpec: msg.agentSpec } : {}),
                 retargetMirror: retarget,
             });
             if (!started) {
-                this.transport.send({ t: "live.ready", reqId: msg.reqId, localThreadId: msg.localThreadId, ok: false });
+                this.transport.send({
+                    t: "live.ready",
+                    reqId: msg.reqId,
+                    localThreadId: msg.localThreadId,
+                    ok: false,
+                    error: "live provider did not start",
+                });
                 return;
             }
             this.liveIds.add(msg.localThreadId);
@@ -122,7 +164,13 @@ export class RunnerSession {
             const ready = provider.waitLiveReady
                 ? await provider.waitLiveReady(msg.localThreadId)
                 : true;
-            this.transport.send({ t: "live.ready", reqId: msg.reqId, localThreadId: msg.localThreadId, ok: ready });
+            this.transport.send({
+                t: "live.ready",
+                reqId: msg.reqId,
+                localThreadId: msg.localThreadId,
+                ok: ready,
+                ...(ready ? {} : { error: "live session was not ready before timeout" }),
+            });
         }
         catch (error) {
             this.transport.send({
@@ -186,13 +234,27 @@ export class RunnerSession {
         this.liveProvider.attachTerminalInjector?.(localThreadId, term);
     }
     stopLive() {
-        for (const id of this.liveIds)
-            this.liveProvider.stopLiveCodexSession?.(id);
+        for (const id of this.liveIds) {
+            this.liveProvider.stopLiveCodexSession?.(id, {
+                deferClaudeInteractionCleanup: true,
+            });
+        }
         this.liveIds.clear();
     }
+    /** Stop event forwarding, kill native terminals/hooks, then synchronously
+     * scrub provider handoff files before the child process is allowed to exit. */
+    shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.stopLive();
+        this.terminals.closeAll();
+        this.liveProvider.finalizeStoppedLiveSessions?.();
+        this.onShutdown();
+    }
     async openTerminal(msg) {
         try {
-            // codex/claude-native session (no explicit command): DUMB ATTACH — omnigent's
+            // codex/claude-native session (no explicit command): DUMB ATTACH — reference implementation's
             // reattach (codex_native.py:905-942, `app_server=None`). A tab switch ONLY
             // attaches an already-live pane; it NEVER ensures the forwarder or relaunches a
             // dead pane. Creation/relaunch happens on message-send (`live.ensure`) or an
@@ -202,7 +264,12 @@ export class RunnerSession {
             if (!msg.command && msg.localThreadId) {
                 const existing = this.terminals.get(msg.terminalId);
                 if (!existing || !existing.isAlive()) {
-                    this.transport.send({ t: "term.error", attachId: msg.attachId, message: "terminal not live" });
+                    this.transport.send({
+                        t: "term.error",
+                        attachId: msg.attachId,
+                        code: "terminal_not_live",
+                        message: "terminal not live",
+                    });
                     return;
                 }
                 await this.attachExisting(msg);
@@ -222,6 +289,7 @@ export class RunnerSession {
             this.transport.send({
                 t: "term.error",
                 attachId: msg.attachId,
+                code: "terminal_open_failed",
                 message: error instanceof Error ? error.message : String(error),
             });
         }
@@ -232,6 +300,16 @@ export class RunnerSession {
             cols: msg.cols,
             rows: msg.rows,
         });
+        if (this.cancelledTerminalOpens.has(msg.attachId)) {
+            attachment.kill();
+            this.transport.send({
+                t: "term.error",
+                attachId: msg.attachId,
+                code: "terminal_open_failed",
+                message: "terminal attachment was cancelled while opening",
+            });
+            return;
+        }
         this.attachments.set(msg.attachId, attachment);
         attachment.onData((chunk) => this.transport.send({
             t: "term.data",