@rynx-ai/server 0.1.11-beta.4 → 0.1.11-beta.41

package/dist/session-runtime-index.d.ts

@@ -13,12 +13,6 @@ export interface SessionRuntimeActivitySnapshot {
  */
 export declare class SessionRuntimeIndex {
     private readonly sessions;
-    /**
-     * Make an accepted Turn visible before the request admission reservation is
-     * released. The returned callback only abandons the pre-created handoff; once
-     * response.created arrives, the native response remains authoritative.
-     */
-    beginResponseHandoff(sessionId: string, responseId: string): () => void;
     observe(sessionId: string, event: SessionEvent): void;
     snapshot(sessionId: string): SessionRuntimeSnapshot;
     /** Aggregate only process-live work; durable Session history is not activity. */
@@ -27,4 +21,7 @@ export declare class SessionRuntimeIndex {
     private state;
     private removeResponseInteractions;
     private hasRunningTurn;
+    private statusAfterResponseTerminal;
+    private retireStatusResponses;
+    private markResponseTerminal;
 }

package/dist/session-runtime-index.js

@@ -1,3 +1,4 @@
+const MAX_TERMINAL_RESPONSE_IDS = 2_000;
 /**
  * Process-local index of live Session state. Durable transcript items explain
  * history; this index says which historical requests still have a real runtime
@@ -6,57 +7,81 @@
  */
 export class SessionRuntimeIndex {
     sessions = new Map();
-    /**
-     * Make an accepted Turn visible before the request admission reservation is
-     * released. The returned callback only abandons the pre-created handoff; once
-     * response.created arrives, the native response remains authoritative.
-     */
-    beginResponseHandoff(sessionId, responseId) {
-        const state = this.state(sessionId);
-        state.pendingResponseIds.add(responseId);
-        state.status = "running";
-        state.statusKind = "startup";
-        let pending = true;
-        return () => {
-            if (!pending)
-                return;
-            pending = false;
-            state.pendingResponseIds.delete(responseId);
-        };
-    }
     observe(sessionId, event) {
         const state = this.state(sessionId);
         switch (event.type) {
             case "response.created":
-                state.pendingResponseIds.delete(event.responseId);
+                if (state.terminalResponseIds.has(event.responseId))
+                    return;
                 state.activeResponseIds.add(event.responseId);
                 state.status = "running";
                 state.statusKind = undefined;
+                state.backgroundTaskCount = undefined;
                 return;
             case "response.completed":
-                state.pendingResponseIds.delete(event.responseId);
+                this.markResponseTerminal(state, event.responseId);
                 state.activeResponseIds.delete(event.responseId);
                 this.removeResponseInteractions(state, event.responseId);
-                state.status = this.hasRunningTurn(state) ? "running" : "idle";
+                state.status = this.statusAfterResponseTerminal(state);
                 state.statusKind = undefined;
                 return;
             case "response.failed":
-                state.pendingResponseIds.delete(event.responseId);
+                this.markResponseTerminal(state, event.responseId);
                 state.activeResponseIds.delete(event.responseId);
                 this.removeResponseInteractions(state, event.responseId);
                 // Response failure is Turn-local. It must not poison a reusable Session.
-                state.status = this.hasRunningTurn(state) ? "running" : "idle";
+                state.status = this.statusAfterResponseTerminal(state);
+                state.statusKind = undefined;
+                return;
+            case "session.interrupted":
+                this.markResponseTerminal(state, event.responseId);
+                state.activeResponseIds.delete(event.responseId);
+                this.removeResponseInteractions(state, event.responseId);
+                state.status = this.statusAfterResponseTerminal(state);
                 state.statusKind = undefined;
                 return;
-            case "session.status":
-                state.status =
-                    state.pendingInteractions.size > 0 || this.hasRunningTurn(state)
-                        ? "running"
-                        : event.status;
-                state.statusKind = event.statusKind;
+            case "session.status": {
+                if (event.backgroundTaskCount !== undefined) {
+                    state.backgroundTaskCount = event.backgroundTaskCount > 0
+                        ? event.backgroundTaskCount
+                        : undefined;
+                }
+                else if (event.status === "running" || event.status === "failed") {
+                    state.backgroundTaskCount = undefined;
+                }
+                if (event.status === "running") {
+                    if (event.responseId && state.terminalResponseIds.has(event.responseId))
+                        return;
+                    if (event.responseId)
+                        state.activeResponseIds.add(event.responseId);
+                    state.status = "running";
+                    state.statusKind = event.statusKind;
+                    return;
+                }
+                // A provider interaction is a stronger in-flight fact than a quiet-pane
+                // idle observation. Claude's status-file path reports waiting as running;
+                // this guard preserves the same truth on its legacy PTY fallback.
+                if (event.status === "idle" && state.pendingInteractions.size > 0) {
+                    state.status = "running";
+                    state.statusKind = undefined;
+                    return;
+                }
+                this.retireStatusResponses(state, event.responseId);
+                if (event.status === "failed") {
+                    state.status = "failed";
+                }
+                else if (state.status !== "failed") {
+                    // Provider idle is authoritative even when final transcript records
+                    // arrive later. Response identity remains on those events themselves;
+                    // it must not keep Session activity/loading alive.
+                    state.status = this.hasRunningTurn(state) ? "running" : "idle";
+                }
+                state.statusKind = undefined;
                 return;
+            }
             case "session.interaction.requested":
-                state.pendingResponseIds.delete(event.responseId);
+                if (state.terminalResponseIds.has(event.responseId))
+                    return;
                 state.pendingInteractions.set(event.interaction.interactionId, {
                     responseId: event.responseId,
                     interaction: event.interaction,
@@ -68,14 +93,15 @@ export class SessionRuntimeIndex {
             case "session.interaction.resolved":
             case "session.interaction.cancelled":
                 state.pendingInteractions.delete(event.interactionId);
-                state.status = this.hasRunningTurn(state) ? "running" : state.status;
+                if (this.hasRunningTurn(state))
+                    state.status = "running";
                 return;
             case "session.rotated":
-                state.pendingResponseIds.clear();
                 state.activeResponseIds.clear();
                 state.pendingInteractions.clear();
                 state.status = "idle";
                 state.statusKind = undefined;
+                state.backgroundTaskCount = undefined;
                 return;
             default:
                 return;
@@ -86,10 +112,11 @@ export class SessionRuntimeIndex {
         if (!state)
             return { status: "idle", activeResponseIds: [], pendingInteractions: [] };
         return {
-            status: state.pendingInteractions.size > 0 || this.hasRunningTurn(state)
-                ? "running"
-                : state.status,
+            status: state.pendingInteractions.size > 0 ? "running" : state.status,
             ...(state.statusKind === undefined ? {} : { statusKind: state.statusKind }),
+            ...(state.backgroundTaskCount === undefined
+                ? {}
+                : { backgroundTaskCount: state.backgroundTaskCount }),
             activeResponseIds: [...state.activeResponseIds],
             pendingInteractions: [...state.pendingInteractions.values()],
         };
@@ -99,7 +126,9 @@ export class SessionRuntimeIndex {
         let runningTurns = 0;
         let pendingInteractions = 0;
         for (const state of this.sessions.values()) {
-            runningTurns += state.pendingResponseIds.size + state.activeResponseIds.size;
+            if (state.status === "running" || state.pendingInteractions.size > 0) {
+                runningTurns += Math.max(1, state.activeResponseIds.size);
+            }
             pendingInteractions += state.pendingInteractions.size;
         }
         return { runningTurns, pendingInteractions };
@@ -112,8 +141,8 @@ export class SessionRuntimeIndex {
         if (!state) {
             state = {
                 status: "idle",
-                pendingResponseIds: new Set(),
                 activeResponseIds: new Set(),
+                terminalResponseIds: new Set(),
                 pendingInteractions: new Map(),
             };
             this.sessions.set(sessionId, state);
@@ -127,6 +156,35 @@ export class SessionRuntimeIndex {
         }
     }
     hasRunningTurn(state) {
-        return state.pendingResponseIds.size > 0 || state.activeResponseIds.size > 0;
+        return state.activeResponseIds.size > 0;
+    }
+    statusAfterResponseTerminal(state) {
+        if (state.pendingInteractions.size > 0 || this.hasRunningTurn(state))
+            return "running";
+        return state.status === "failed" ? "failed" : "idle";
+    }
+    retireStatusResponses(state, responseId) {
+        // session.status is Session-wide. Match reference implementation's
+        // _session_active_response_cache: every idle/failed edge closes the one
+        // in-flight native response projection, even when the edge happens to be
+        // stamped with that response id. A late transcript event may still carry
+        // the old id for grouping, but it cannot keep activity alive.
+        for (const activeResponseId of state.activeResponseIds) {
+            this.markResponseTerminal(state, activeResponseId);
+        }
+        if (responseId)
+            this.markResponseTerminal(state, responseId);
+        state.activeResponseIds.clear();
+        state.pendingInteractions.clear();
+    }
+    markResponseTerminal(state, responseId) {
+        state.terminalResponseIds.delete(responseId);
+        state.terminalResponseIds.add(responseId);
+        while (state.terminalResponseIds.size > MAX_TERMINAL_RESPONSE_IDS) {
+            const oldest = state.terminalResponseIds.values().next().value;
+            if (oldest === undefined)
+                break;
+            state.terminalResponseIds.delete(oldest);
+        }
     }
 }

package/dist/session-terminal-host.d.ts

@@ -11,12 +11,32 @@ export type SessionTerminalCloseReason = "client_closed" | "terminal_exited" | "
 export interface SessionTerminalCloseInfo {
     reason: SessionTerminalCloseReason;
     exitCode?: number;
+    finalOffset?: number;
 }
-/** One attachment; close detaches this client and never kills the tmux pane. */
-export interface SessionTerminalAttachment extends AsyncIterable<Uint8Array> {
+export interface SessionTerminalRead {
+    data: Uint8Array;
+    nextOffset: number;
+    done: boolean;
+    finalOffset?: number;
+}
+/** One demand-driven attachment; close detaches only this viewer. */
+export interface SessionTerminalAttachment {
     readonly sessionId: string;
     readonly role: SessionTerminalRole;
+    readonly seedBytes: number;
+    /** Actual tmux pane size captured with the seed. */
+    readonly dimensions?: {
+        cols: number;
+        rows: number;
+    };
     readonly closed: Promise<SessionTerminalCloseInfo>;
+    readSeed(offset: number, maxBytes: number): Promise<SessionTerminalRead>;
+    start(): Promise<void>;
+    read(offset: number, maxBytes: number): Promise<SessionTerminalRead>;
+    onResize?(listener: (dimensions: {
+        cols: number;
+        rows: number;
+    }) => void): void;
     write(data: Uint8Array): void | Promise<void>;
     resize(cols: number, rows: number): void | Promise<void>;
     close(): Promise<void>;

package/dist/session-terminal-host.js

@@ -1,6 +1,4 @@
 import { TerminalOpenError } from "@rynx-ai/runtime";
-const MAX_QUEUED_OUTPUT_FRAMES = 128;
-const MAX_QUEUED_OUTPUT_BYTES = 512 * 1024;
 const MAX_TERMINAL_DIMENSION = 1_000;
 export class SessionTerminalOpenError extends Error {
     code;
@@ -55,7 +53,7 @@ export function createRunnerSessionTerminalHost(options) {
                 void attachment.closed.then(releaseActivity, releaseActivity);
                 try {
                     const opened = await waitFor(parent.ready, openOptions.signal);
-                    attachment.opened(opened.role);
+                    attachment.opened(opened.role, opened.dimensions, opened.seedBytes);
                     attachment.throwIfOpeningFailed();
                     return attachment;
                 }
@@ -107,13 +105,13 @@ class RunnerSessionTerminalAttachment {
     sessionId;
     parent;
     signal;
-    queue = [];
-    queuedBytes = 0;
-    waiter;
-    ended = false;
-    terminalError;
-    openingFailure;
+    detached = false;
+    readerFinished = false;
+    closeSettled = false;
     currentRole;
+    currentDimensions;
+    currentSeedBytes = 0;
+    resizeListener;
     resolveClosed;
     closed;
     onAbort;
@@ -128,8 +126,18 @@ class RunnerSessionTerminalAttachment {
         this.onAbort = () => {
             void this.close().catch(() => undefined);
         };
-        parent.onData((chunk) => this.push(Uint8Array.from(Buffer.from(chunk, "utf8"))));
-        parent.onExit((info) => this.finish({ reason: "terminal_exited", exitCode: info.exitCode }));
+        parent.onResize?.((dimensions) => {
+            this.currentDimensions = dimensions;
+            this.resizeListener?.(dimensions);
+        });
+        void parent.readerDone.then((info) => {
+            this.readerFinished = true;
+            this.settleClosed({
+                reason: info.reason,
+                exitCode: info.exitCode,
+                finalOffset: info.finalOffset,
+            });
+        });
         if (signal?.aborted)
             this.onAbort();
         else
@@ -138,97 +146,72 @@ class RunnerSessionTerminalAttachment {
     get role() {
         return this.currentRole;
     }
-    opened(role) {
+    get dimensions() {
+        return this.currentDimensions;
+    }
+    get seedBytes() {
+        return this.currentSeedBytes;
+    }
+    onResize(listener) {
+        this.resizeListener = listener;
+        if (this.currentDimensions)
+            queueMicrotask(() => listener(this.currentDimensions));
+    }
+    opened(role, dimensions, seedBytes = 0) {
         this.currentRole = role;
+        this.currentDimensions = dimensions;
+        this.currentSeedBytes = seedBytes;
     }
     throwIfOpeningFailed() {
-        if (this.openingFailure)
-            throw this.openingFailure;
-        if (this.ended) {
+        if (this.detached || this.readerFinished) {
             throw new SessionTerminalOpenError("internal", "Session terminal closed while opening");
         }
     }
-    [Symbol.asyncIterator]() {
-        return this;
-    }
-    next() {
-        const queued = this.queue.shift();
-        if (queued) {
-            this.queuedBytes -= queued.bytes;
-            return Promise.resolve({ done: false, value: queued.data });
-        }
-        if (this.terminalError !== undefined)
-            return Promise.reject(this.terminalError);
-        if (this.ended)
-            return Promise.resolve({ done: true, value: undefined });
-        if (this.waiter) {
-            return Promise.reject(new SessionTerminalStreamError("internal", "Concurrent reads from one Session terminal are not allowed"));
+    readSeed(offset, maxBytes) {
+        if (this.detached || this.readerFinished) {
+            return Promise.reject(new Error("Session terminal is closed"));
         }
-        return new Promise((resolve, reject) => {
-            this.waiter = { resolve, reject };
-        });
+        return this.parent.readSeed(offset, maxBytes);
+    }
+    async start() {
+        if (this.detached || this.readerFinished)
+            throw new Error("Session terminal is closed");
+        await this.parent.start();
     }
-    async return() {
-        await this.close();
-        return { done: true, value: undefined };
+    read(offset, maxBytes) {
+        // Reader completion publishes the final offset before the consumer has
+        // necessarily pulled the final bytes. Only detaching makes that tail
+        // unreadable.
+        if (this.detached)
+            return Promise.reject(new Error("Session terminal is closed"));
+        return this.parent.read(offset, maxBytes);
     }
-    write(data) {
-        if (this.ended || this.currentRole !== "owner" || data.byteLength === 0)
+    async write(data) {
+        if (this.detached ||
+            this.readerFinished ||
+            this.currentRole !== "owner" ||
+            data.byteLength === 0)
             return;
-        this.parent.write(Buffer.from(data).toString("utf8"));
+        await this.parent.write(data);
     }
-    resize(cols, rows) {
+    async resize(cols, rows) {
         validateDimensions(cols, rows);
-        if (!this.ended)
-            this.parent.resize(cols, rows);
+        if (!this.detached && !this.readerFinished) {
+            await this.parent.resize(cols, rows);
+        }
     }
     async close() {
-        if (this.ended)
+        if (this.detached)
             return;
+        this.detached = true;
         this.parent.close();
-        this.finish({ reason: "client_closed" }, undefined, true);
-    }
-    push(data) {
-        if (this.ended || data.byteLength === 0)
-            return;
-        if (this.waiter) {
-            const waiter = this.waiter;
-            this.waiter = undefined;
-            waiter.resolve({ done: false, value: data });
-            return;
-        }
-        if (this.queue.length >= MAX_QUEUED_OUTPUT_FRAMES ||
-            this.queuedBytes + data.byteLength > MAX_QUEUED_OUTPUT_BYTES) {
-            const error = new SessionTerminalStreamError("backpressure", "Session terminal output exceeded its bounded queue");
-            this.openingFailure = new SessionTerminalOpenError("capacity", error.message, {
-                cause: error,
-            });
-            this.parent.close();
-            this.finish({ reason: "backpressure" }, error, true);
-            return;
-        }
-        const copy = Uint8Array.from(data);
-        this.queue.push({ data: copy, bytes: copy.byteLength });
-        this.queuedBytes += copy.byteLength;
+        this.settleClosed({ reason: "client_closed" });
     }
-    finish(info, error, discardQueue = false) {
-        if (this.ended)
+    settleClosed(info) {
+        if (this.closeSettled)
             return;
-        this.ended = true;
-        this.terminalError = error;
+        this.closeSettled = true;
         this.signal?.removeEventListener("abort", this.onAbort);
-        if (discardQueue) {
-            this.queue.length = 0;
-            this.queuedBytes = 0;
-        }
-        const waiter = this.waiter;
-        this.waiter = undefined;
-        if (waiter) {
-            if (error === undefined)
-                waiter.resolve({ done: true, value: undefined });
-            else
-                waiter.reject(error);
-        }
         this.resolveClosed(info);
     }
 }

package/dist/terminal-ws.d.ts

@@ -1,5 +1,5 @@
 import type { Server } from "node:http";
-import { WebSocketServer } from "ws";
+import { WebSocketServer, type RawData } from "ws";
 import { type RuntimeWebAccessPolicy } from "./runtime-web-auth.js";
 import { type SessionTerminalHost } from "./session-terminal-host.js";
 import type { RuntimeConnectionResolverHost } from "./server.js";
@@ -15,3 +15,6 @@ export interface TerminalWsDeps {
 }
 /** Attach the authenticated Runtime-scoped terminal bridge to an HTTP server. */
 export declare function attachTerminalWs(server: Server, deps: TerminalWsDeps): WebSocketServer;
+/** Reuse the terminal protocol's canonical parser at proxy boundaries that
+ * must admit resize controls while rejecting every form of terminal input. */
+export declare function isBrowserTerminalResizeFrame(data: RawData, isBinary: boolean): boolean;

package/dist/terminal-ws.js

@@ -8,10 +8,10 @@ const MAX_DIMENSION = 1_000;
 const MAX_BROWSER_MESSAGE_BYTES = 64 * 1024;
 const MAX_PENDING_BROWSER_MESSAGES = 32;
 const MAX_PENDING_BROWSER_BYTES = 128 * 1024;
-const MAX_BROWSER_BUFFERED_BYTES = 1024 * 1024;
 const INTERACTIVE_OUTPUT_CHUNK_BYTES = 2 * 1024;
-const NORMAL_OUTPUT_CHUNK_BYTES = 16 * 1024;
+const NORMAL_OUTPUT_CHUNK_BYTES = 64 * 1024;
 const INTERACTIVE_ECHO_WINDOW_MS = 750;
+const TERMINAL_OUTPUT_DRAIN_TIMEOUT_MS = 5_000;
 const WS_CLOSE_BAD_REQUEST = 4400;
 const WS_CLOSE_UNAUTHORIZED = 4403;
 /** Reserved exclusively for an attachment that was not live at open time. */
@@ -76,7 +76,7 @@ async function handleConnection(ws, url, route, deps) {
     let terminal;
     let browserClosed = false;
     let cleanupPromise;
-    let lastClientInputAt = 0;
+    let lastAcknowledgedInputAt = Number.NEGATIVE_INFINITY;
     let liveInputTail = Promise.resolve();
     let liveInputFrames = 0;
     let liveInputBytes = 0;
@@ -95,6 +95,7 @@ async function handleConnection(ws, url, route, deps) {
         cleanupPromise = (async () => {
             try {
                 await opened?.close();
+                await liveInputTail.catch(() => undefined);
             }
             finally {
                 acquired?.release();
@@ -122,8 +123,6 @@ async function handleConnection(ws, url, route, deps) {
             void cleanup();
             return;
         }
-        if (input.type === "input")
-            lastClientInputAt = Date.now();
         const bytes = input.type === "input" ? input.data.byteLength : 16;
         const opened = terminal;
         if (opened && inputReady) {
@@ -135,7 +134,11 @@ async function handleConnection(ws, url, route, deps) {
             }
             liveInputFrames += 1;
             liveInputBytes += bytes;
-            const operation = liveInputTail.then(() => applyBrowserInput(opened, input));
+            const operation = liveInputTail.then(async () => {
+                const acknowledgedInput = await applyBrowserInput(opened, input);
+                if (acknowledgedInput)
+                    lastAcknowledgedInputAt = performance.now();
+            });
             liveInputTail = operation
                 .catch((error) => {
                 closeForError(ws, error);
@@ -205,26 +208,42 @@ async function handleConnection(ws, url, route, deps) {
             return;
         }
         terminal = opened;
-        sendText(ws, { t: "opened", role: opened.role });
+        sendText(ws, {
+            t: "opened",
+            role: opened.role,
+            ...(opened.dimensions ?? {}),
+        });
+        opened.onResize?.(({ cols, rows }) => {
+            if (!browserClosed)
+                sendText(ws, { t: "dimensions", cols, rows });
+        });
+        let seedOffset = 0;
+        while (seedOffset < opened.seedBytes) {
+            const seed = await opened.readSeed(seedOffset, NORMAL_OUTPUT_CHUNK_BYTES);
+            if (seed.data.byteLength > 0)
+                await sendBinary(ws, seed.data);
+            seedOffset = seed.nextOffset;
+            if (seed.done)
+                break;
+        }
+        if (seedOffset !== opened.seedBytes) {
+            throw new Error(`Terminal history ended at ${seedOffset}, expected ${opened.seedBytes}`);
+        }
+        await opened.start();
         while (pendingInputs.length > 0) {
             const batch = pendingInputs.splice(0);
             for (const queued of batch) {
                 pendingInputBytes -= queued.bytes;
-                await applyBrowserInput(opened, queued.input);
+                const acknowledgedInput = await applyBrowserInput(opened, queued.input);
+                if (acknowledgedInput)
+                    lastAcknowledgedInputAt = performance.now();
             }
         }
         pendingInputBytes = 0;
         inputReady = true;
-        for await (const output of opened) {
-            if (browserClosed)
-                return;
-            const chunkSize = Date.now() - lastClientInputAt < INTERACTIVE_ECHO_WINDOW_MS
-                ? INTERACTIVE_OUTPUT_CHUNK_BYTES
-                : NORMAL_OUTPUT_CHUNK_BYTES;
-            for (let offset = 0; offset < output.byteLength; offset += chunkSize) {
-                await sendBinary(ws, output.subarray(offset, Math.min(offset + chunkSize, output.byteLength)));
-            }
-        }
+        await forwardTerminalOutput(ws, opened, () => (performance.now() - lastAcknowledgedInputAt < INTERACTIVE_ECHO_WINDOW_MS
+            ? INTERACTIVE_OUTPUT_CHUNK_BYTES
+            : NORMAL_OUTPUT_CHUNK_BYTES));
         if (browserClosed)
             return;
         const closed = await opened.closed;
@@ -297,23 +316,34 @@ function parseBrowserInput(data, isBinary) {
     }
     throw new Error("Unknown or invalid terminal control frame");
 }
+/** Reuse the terminal protocol's canonical parser at proxy boundaries that
+ * must admit resize controls while rejecting every form of terminal input. */
+export function isBrowserTerminalResizeFrame(data, isBinary) {
+    try {
+        return parseBrowserInput(data, isBinary).type === "resize";
+    }
+    catch {
+        return false;
+    }
+}
 async function applyBrowserInput(terminal, input) {
     if (input.type === "input") {
-        // Defense in depth: tmux -r also blocks writes, but bytes never reach it.
-        if (terminal.role === "owner")
-            await terminal.write(input.data);
-        return;
+        if (terminal.role !== "owner")
+            return false;
+        await terminal.write(input.data);
+        return true;
     }
     await terminal.resize(input.cols, input.rows);
+    return false;
 }
 async function sendBinary(ws, data) {
     if (ws.readyState !== WebSocket.OPEN)
         throw transportError("Browser terminal is closed");
-    if (ws.bufferedAmount + data.byteLength > MAX_BROWSER_BUFFERED_BYTES) {
-        const error = new Error("Browser terminal output exceeded its bounded buffer");
-        error.name = "BackpressureError";
-        throw error;
-    }
+    // Await every send and admit only one frame at a time. Terminal output may
+    // legitimately arrive in multi-megabyte bursts; a fixed bufferedAmount
+    // cutoff turns a temporarily slow browser into a detached healthy pane.
+    // The terminal forwarder coalesces normal output to 64 KiB frames and uses
+    // 2 KiB frames in the interactive echo window.
     await new Promise((resolve, reject) => {
         ws.send(data, { binary: true, compress: false }, (error) => {
             if (error)
@@ -323,6 +353,42 @@ async function sendBinary(ws, data) {
         });
     });
 }
+async function forwardTerminalOutput(ws, terminal, frameLimit) {
+    let drainTimer;
+    const drainDeadline = terminal.closed.then((closed) => new Promise((_, reject) => {
+        if (closed.reason !== "terminal_exited")
+            return;
+        drainTimer = setTimeout(() => {
+            const error = new Error(`Terminal output did not drain within ${TERMINAL_OUTPUT_DRAIN_TIMEOUT_MS}ms after exit`);
+            error.name = "BackpressureError";
+            // A pending ws send has no cancellation primitive. Terminating the
+            // transport is the only way to guarantee teardown after the deadline.
+            if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CLOSING) {
+                ws.terminate();
+            }
+            reject(error);
+        }, TERMINAL_OUTPUT_DRAIN_TIMEOUT_MS);
+        drainTimer.unref?.();
+    }));
+    const forwarding = (async () => {
+        let offset = 0;
+        for (;;) {
+            const next = await terminal.read(offset, frameLimit());
+            if (next.data.byteLength > 0)
+                await sendBinary(ws, next.data);
+            offset = next.nextOffset;
+            if (next.done)
+                return;
+        }
+    })();
+    try {
+        await Promise.race([forwarding, drainDeadline]);
+    }
+    finally {
+        if (drainTimer)
+            clearTimeout(drainTimer);
+    }
+}
 function sendText(ws, value) {
     if (ws.readyState === WebSocket.OPEN) {
         ws.send(JSON.stringify(value), { binary: false, compress: false });