@cjhyy/code-shell-server 0.9.44 → 0.9.47

package/dist/links/types.d.ts

@@ -1,6 +1,26 @@
-export type { LinkAuthorization, LinkAuthMode, LinkAuthorizationInput, LinkAuthorizationResponse, LinkAuthorizationStep, LinkConnectionInput, LinkErrorCode, LinkSnapshot, MaskedLinkConnection, TokenConnectionInput, } from "@cjhyy/code-shell-link";
+export type { LinkAuthorization, LinkAuthorizationFailure, LinkAuthMode, LinkAuthorizationInput, LinkAuthorizationResponse, LinkAuthorizationStep, LinkConnectionInput, LinkErrorCode, LinkSnapshot, MaskedLinkConnection, TokenConnectionInput, } from "@cjhyy/code-shell-link";
 export interface LinkOperationContext {
     ownerId: string;
     /** Rechecked after every external await and immediately before persistence. */
     authorize: () => boolean | Promise<boolean>;
+    /** Native Host request lifetime; never accepted from the remote request body. */
+    signal?: AbortSignal;
+}
+/** Trusted Host integration. Secrets and registration settings never enter browser inputs. */
+export interface HostLinkOAuthAdapter {
+    providerId: string;
+    methodId: string;
+    authModeId: string;
+    label: string;
+    authorize(input: {
+        id: string;
+        label: string;
+        previous: import("@cjhyy/code-shell-core").Credential | null;
+        signal: AbortSignal;
+        onAuthorizationUrl(url: string, expiresAt: string): Promise<void>;
+    }): Promise<import("@cjhyy/code-shell-core").Credential>;
+    /** The adapter owns its callback listener; the native browser must not bind it again. */
+    openAuthorizationUrl(url: string): Promise<void>;
+    /** Called after local authority is removed; must not delete a subsequently reconnected record. */
+    disconnect?(credential: import("@cjhyy/code-shell-core").Credential): Promise<void>;
 }

package/dist/mobile-remote/codex-parse.d.ts

@@ -14,8 +14,10 @@ import type { ResidentAgentEvent } from "./resident-agent.js";
  *       item.type "reasoning"         → []      (thinking noise)
  *       item.type "command_execution" → tool(Bash) on start, tool_result on complete
  *       item.type "mcp_tool_call"     → tool(server__tool) on start, tool_result on complete
+ *                                        (result.content text blocks, or error.message on failure)
  *       item.type "web_search"        → tool(WebSearch) on start
- *       item.type "file_change"       → tool(Edit) on start
+ *       item.type "file_change"       → tool(Edit) + tool_result on complete (only the
+ *                                        completion carries `changes[]` {path, kind})
  *   {type:"turn.completed", usage}                           → turn_end
  *   {type:"turn.failed", error}                              → error
  *   {type:"error", message}                                  → error

package/dist/mobile-remote/codex-parse.js

@@ -13,8 +13,10 @@
  *       item.type "reasoning"         → []      (thinking noise)
  *       item.type "command_execution" → tool(Bash) on start, tool_result on complete
  *       item.type "mcp_tool_call"     → tool(server__tool) on start, tool_result on complete
+ *                                        (result.content text blocks, or error.message on failure)
  *       item.type "web_search"        → tool(WebSearch) on start
- *       item.type "file_change"       → tool(Edit) on start
+ *       item.type "file_change"       → tool(Edit) + tool_result on complete (only the
+ *                                        completion carries `changes[]` {path, kind})
  *   {type:"turn.completed", usage}                           → turn_end
  *   {type:"turn.failed", error}                              → error
  *   {type:"error", message}                                  → error
@@ -33,6 +35,9 @@ export function parseCodexJsonLine(line) {
     catch {
         return [];
     }
+    // A valid JSON scalar (e.g. `null`) is not an event; ignore it like noise.
+    if (!msg || typeof msg !== "object")
+        return [];
     if (msg.type === "turn.completed")
         return [{ type: "turn_end", reason: "completed" }];
     if (msg.type === "turn.failed") {
@@ -71,7 +76,7 @@ export function parseCodexJsonLine(line) {
                 return [{
                         type: "tool_result",
                         id,
-                        summary: String(item.result ?? item.output ?? "").slice(0, 400),
+                        summary: mcpResultText(item).slice(0, 400),
                         isError: item.status === "failed" || Boolean(item.is_error),
                     }];
             }
@@ -88,16 +93,24 @@ export function parseCodexJsonLine(line) {
             return phase === "started"
                 ? [{ type: "tool", id, tool: "WebSearch", summary: String(item.query ?? ""), input: { query: String(item.query ?? "") } }]
                 : [];
-        case "file_change":
-            return phase === "started"
-                ? [{
-                        type: "tool",
-                        id,
-                        tool: "Edit",
-                        summary: String(item.path ?? ""),
-                        input: item.kind !== undefined ? { path: String(item.path ?? ""), kind: item.kind } : { path: String(item.path ?? "") },
-                    }]
+        case "file_change": {
+            if (phase !== "completed")
+                return [];
+            const changes = Array.isArray(item.changes)
+                ? item.changes
+                    .filter((c) => c && typeof c === "object" && typeof c.path === "string")
+                    .map((c) => ({ path: c.path, kind: c.kind }))
                 : [];
+            return [
+                { type: "tool", id, tool: "Edit", summary: changes.map((c) => c.path).join(", "), input: { changes } },
+                {
+                    type: "tool_result",
+                    id,
+                    summary: changes.map((c) => `${typeof c.kind === "string" ? c.kind : "update"} ${c.path}`).join("\n").slice(0, 400),
+                    isError: item.status === "failed",
+                },
+            ];
+        }
         default:
             return [];
     }
@@ -122,6 +135,27 @@ export function extractThreadId(line) {
     }
     return msg.type === "thread.started" && typeof msg.thread_id === "string" ? msg.thread_id : undefined;
 }
+/** Readable MCP outcome: the failure message, else the result's text content
+ *  blocks, else its structured content (an older plain-string result passes). */
+function mcpResultText(item) {
+    const failure = errText(item.error);
+    if (failure)
+        return failure;
+    const result = item.result ?? item.output;
+    if (result === undefined || result === null)
+        return "";
+    if (typeof result !== "object")
+        return String(result);
+    if (Array.isArray(result.content)) {
+        const text = result.content
+            .map((block) => (block?.type === "text" && typeof block.text === "string" ? block.text : ""))
+            .filter(Boolean)
+            .join("\n");
+        if (text)
+            return text;
+    }
+    return JSON.stringify(result.structured_content ?? result) ?? "";
+}
 function errText(e) {
     if (typeof e === "string")
         return e;

package/dist/mobile-remote/codex-room-agent.d.ts

@@ -76,12 +76,6 @@ export declare class CodexRoomAgent implements RoomAgent {
     private child?;
     private threadId?;
     private started;
-    /** True once the CURRENT turn emitted a sealing event (turn_end via
-     *  turn.completed, or an error). Reset at the start of each send(). */
-    private turnSealed;
-    /** True while stop() is tearing the room down, so the exit handler doesn't
-     *  mistake an intentional SIGTERM for a crash. */
-    private stopping;
     constructor(opts: CodexRoomAgentOptions);
     /** No persistent process to launch; a turn's process is spawned on send(). */
     start(): void;

package/dist/mobile-remote/codex-room-agent.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { stopRoomProcess } from "./room-process-stop.js";
 import { createInterface } from "node:readline";
 import { pathWithCommonBins } from "./path-bins.js";
 import { parseCodexJsonLine, extractThreadId } from "./codex-parse.js";
@@ -86,12 +87,6 @@ export class CodexRoomAgent {
     child;
     threadId;
     started = false;
-    /** True once the CURRENT turn emitted a sealing event (turn_end via
-     *  turn.completed, or an error). Reset at the start of each send(). */
-    turnSealed = false;
-    /** True while stop() is tearing the room down, so the exit handler doesn't
-     *  mistake an intentional SIGTERM for a crash. */
-    stopping = false;
     constructor(opts) {
         this.opts = opts;
         this.threadId = opts.resumeThreadId;
@@ -105,7 +100,7 @@ export class CodexRoomAgent {
             return false;
         if (this.child)
             return false; // a turn is already running; one turn at a time
-        this.turnSealed = false; // fresh turn — not yet sealed
+        let turnSealed = false; // This child owns only its own turn and callbacks.
         const args = codexArgsForTurn({ mode: this.opts.permissionMode, threadId: this.threadId });
         const child = spawn(this.opts.command, args, {
             cwd: this.opts.cwd,
@@ -114,11 +109,11 @@ export class CodexRoomAgent {
             stdio: ["pipe", "pipe", "pipe"],
         });
         this.child = child;
-        // Feed the user's prompt over stdin (codex exec reads it because argv ends `-`).
-        child.stdin?.end(text);
         if (child.stdout) {
             const rl = createInterface({ input: child.stdout });
             rl.on("line", (line) => {
+                if (this.child !== child)
+                    return;
                 // Capture the thread id (parseCodexJsonLine intentionally drops
                 // thread.started — it's resume-control info, not a render event) so we
                 // can resume on the next turn and persist it across restarts.
@@ -131,7 +126,7 @@ export class CodexRoomAgent {
                     // turn_end / error are the reducer's sealing events — once one fires
                     // for this turn, the exit handler need not synthesize a fallback.
                     if (ev.type === "turn_end" || ev.type === "error")
-                        this.turnSealed = true;
+                        turnSealed = true;
                     this.opts.onEvent(ev);
                 }
             });
@@ -146,17 +141,32 @@ export class CodexRoomAgent {
             errRl.on("line", (line) => stderrLines.push(line));
         }
         child.on("error", (err) => {
+            if (this.child !== child)
+                return;
+            this.child = undefined;
             const isMissing = err.code === "ENOENT";
-            this.turnSealed = true; // this error seals the run in the reducer
+            turnSealed = true; // this error seals the run in the reducer
             this.opts.onEvent({
                 type: "error",
                 error: isMissing
                     ? `未找到命令 "${this.opts.command}"。请先安装 Codex CLI 并确保它在 PATH 中。`
                     : err.message,
             });
+        });
+        child.stdin?.on("error", (error) => {
+            if (this.child !== child)
+                return;
             this.child = undefined;
+            stopRoomProcess(child);
+            this.opts.onEvent({
+                type: "error",
+                error: `Codex input pipe closed${error.code ? ` (${error.code})` : ""}`,
+            });
         });
-        child.on("exit", (code, signal) => {
+        child.on("close", (code, signal) => {
+            if (this.child !== child)
+                return;
+            this.child = undefined;
             // The turn's process is done; the room stays "running" (ready for the next
             // turn). We do NOT emit `exit` here — that would tear the room down in the
             // UI after every turn. turn.completed already produced a `turn_end`.
@@ -164,7 +174,7 @@ export class CodexRoomAgent {
             // is surfaced now so the room shows *why* it failed.
             const stderrErr = codexStderrError(stderrLines, code);
             if (stderrErr) {
-                this.turnSealed = true;
+                turnSealed = true;
                 this.opts.onEvent({ type: "error", error: stderrErr });
             }
             // FALLBACK SEAL (#6): if the process died without ever sealing the turn
@@ -174,14 +184,16 @@ export class CodexRoomAgent {
             const seal = sealEventOnExit({
                 code,
                 signal,
-                turnSealed: this.turnSealed,
-                stopping: this.stopping,
+                turnSealed,
+                stopping: false,
                 hasStderrError: stderrErr != null,
             });
             if (seal)
                 this.opts.onEvent(seal);
-            this.child = undefined;
         });
+        // Register stdin's error owner before writing: early CLI exits fail writes
+        // asynchronously even when end() itself returns successfully.
+        child.stdin?.end(text);
         return true;
     }
     /** The room is "running" once started — independent of whether a turn's
@@ -191,23 +203,9 @@ export class CodexRoomAgent {
     }
     stop() {
         this.started = false;
-        this.stopping = true; // the upcoming SIGTERM exit is intentional, not a crash
         const child = this.child;
         this.child = undefined;
-        if (!child?.pid || child.pid <= 1) {
-            child?.kill("SIGTERM");
-            return;
-        }
-        try {
-            process.kill(-child.pid, "SIGTERM");
-        }
-        catch {
-            try {
-                child.kill("SIGTERM");
-            }
-            catch {
-                /* already gone */
-            }
-        }
+        if (child)
+            stopRoomProcess(child);
     }
 }

package/dist/mobile-remote/mobile-chat-turn.d.ts

@@ -13,6 +13,7 @@ export interface DispatchMobileChatTurnInput {
     text: string;
     attachments?: MobileImageAttachment[];
     clientMessageId?: string;
+    modelTraceSource?: string;
     permissionMode?: PermissionMode;
     runId: string;
     bridge: MobileRunBridge;

package/dist/mobile-remote/mobile-chat-turn.js

@@ -44,6 +44,9 @@ export async function dispatchMobileChatTurn(input) {
         id: input.runId,
         params: {
             task: text,
+            ...(input.modelTraceSource && /^panel:[a-z][a-z0-9-]{0,63}$/.test(input.modelTraceSource)
+                ? { modelTraceSource: input.modelTraceSource }
+                : {}),
             cwd,
             sessionId: input.sessionId,
             ...(input.projectId ? { projectId: input.projectId } : {}),

package/dist/mobile-remote/mobile-client-event-validator.js

@@ -9,6 +9,7 @@ const MAX_NAME_LENGTH = 512;
 const MAX_PATH_LENGTH = 32_768;
 const MAX_MESSAGE_LENGTH = 512 * 1024;
 const MAX_HISTORY_LIMIT = 500;
+const MAX_ASK_USER_ANSWERS = 32;
 /** Runtime validation at the WebSocket boundary; TypeScript types do not validate JSON. */
 export function parseMobileClientEvent(value) {
     if (!isRecord(value) || typeof value.type !== "string")
@@ -29,6 +30,9 @@ export function parseMobileClientEvent(value) {
             valid =
                 boundedOptionalEmptyString(event.text, MAX_MESSAGE_LENGTH) &&
                     optionalBoundedString(event.sessionId, MAX_ID_LENGTH) &&
+                    (event.modelTraceSource === undefined ||
+                        (typeof event.modelTraceSource === "string" &&
+                            /^panel:[a-z][a-z0-9-]{0,63}$/.test(event.modelTraceSource))) &&
                     optionalBoundedString(event.clientMessageId, MAX_ID_LENGTH) &&
                     optionalAttachments(event.attachments);
             break;
@@ -48,6 +52,14 @@ export function parseMobileClientEvent(value) {
         case "session.recovery.cancel":
             valid = true;
             break;
+        case "session.legacyBase":
+            valid =
+                boundedString(event.sessionId, 128) &&
+                    boundedString(event.recoveryId, 128) &&
+                    boundedString(event.requestId, 128) &&
+                    ((boundedString(event.throughEventId, 512) && event.cursor === undefined) ||
+                        (boundedString(event.cursor, 2048) && event.throughEventId === undefined));
+            break;
         case "session.outputJournal":
             valid =
                 boundedString(event.sessionId, 128) &&
@@ -246,12 +258,21 @@ function isAttachment(value) {
         ? boundedString(value.dataUrl, MAX_MESSAGE_LENGTH)
         : value.transport === "upload" && boundedString(value.uploadId, MAX_ID_LENGTH);
 }
+function isAnswerRecord(value) {
+    if (!isRecord(value))
+        return false;
+    const entries = Object.entries(value);
+    return (entries.length <= MAX_ASK_USER_ANSWERS &&
+        entries.every(([question, answer]) => question.length <= MAX_MESSAGE_LENGTH &&
+            boundedOptionalEmptyString(answer, MAX_MESSAGE_LENGTH)));
+}
 function isApprovalDecision(value) {
     if (!isRecord(value))
         return false;
     if (value.behavior === "allow") {
         return ((value.answer === undefined ||
             boundedOptionalEmptyString(value.answer, MAX_MESSAGE_LENGTH)) &&
+            (value.answers === undefined || isAnswerRecord(value.answers)) &&
             (value.updatedInput === undefined || isRecord(value.updatedInput)));
     }
     return value.behavior === "deny" && boundedOptionalEmptyString(value.message, MAX_MESSAGE_LENGTH);

package/dist/mobile-remote/mobile-history.d.ts

@@ -16,7 +16,16 @@
 export interface TranscriptHistoryItem {
     kind: string;
     text?: unknown;
+    /** Image blocks of a raw model-facing user input (it has no displayText). */
+    images?: unknown;
     event?: unknown;
 }
 export type SessionTranscriptReader = (sessionId: string) => Promise<readonly TranscriptHistoryItem[]>;
-export declare function buildSessionHistory(sessionId: string, getTranscript: SessionTranscriptReader): Promise<unknown[]>;
+/** The client's user-input display projection (Web transcriptUserDisplay), injected. */
+export type UserInputDisplay = (data: {
+    content: unknown;
+}) => {
+    text: string;
+    attachments: readonly unknown[];
+};
+export declare function buildSessionHistory(sessionId: string, getTranscript: SessionTranscriptReader, displayUserInput?: UserInputDisplay): Promise<unknown[]>;

package/dist/mobile-remote/mobile-history.js

@@ -1,23 +1,9 @@
-/**
- * Build a session's history as a flat list of events the phone's streamReducer
- * understands. We REUSE the desktop's transcript reader (transcriptToFoldItems
- * via its getSessionTranscript) so there is one transcript parser, then project
- * its FoldItems into reducer events:
- *   - { kind: "stream", event }  → the raw StreamEvent (reducer eats it directly)
- *   - { kind: "user", text }     → a synthetic { type: "user_message", text }
- *
- * The phone feeds these through the SAME reducer used for the live stream, so
- * replay and live are identical (design §4).
- *
- * The transcript reader itself stays in the desktop package (it depends on
- * renderer FoldItem types), so it is injected here instead of imported.
- */
-export async function buildSessionHistory(sessionId, getTranscript) {
+export async function buildSessionHistory(sessionId, getTranscript, displayUserInput) {
     const items = await getTranscript(sessionId);
     const events = [];
     for (const item of items) {
         if (item.kind === "user") {
-            events.push({ type: "user_message", text: item.text });
+            events.push(userHistoryEvent(item, displayUserInput));
         }
         else if (item.kind === "stream") {
             events.push(item.event);
@@ -25,3 +11,25 @@ export async function buildSessionHistory(sessionId, getTranscript) {
     }
     return events;
 }
+/**
+ * A user input with image blocks but no displayText (e.g. an old paired
+ * chat.send) persisted the engine's model-facing text, including the
+ * attached-image path envelope and tool hint. Project it through the client's
+ * durable-replay display rules instead of showing that as the user's text.
+ */
+function userHistoryEvent(item, displayUserInput) {
+    const images = typeof item.images === "number" && item.images > 0 ? item.images : 0;
+    if (!images || typeof item.text !== "string" || !displayUserInput)
+        return { type: "user_message", text: item.text };
+    const display = displayUserInput({
+        content: [
+            { type: "text", text: item.text },
+            ...Array.from({ length: images }, () => ({ type: "image", source: {} })),
+        ],
+    });
+    return {
+        type: "user_message",
+        text: display.text,
+        ...(display.attachments.length ? { attachments: display.attachments } : {}),
+    };
+}

package/dist/mobile-remote/remote-host-manager.d.ts

@@ -37,6 +37,8 @@ export interface RemoteHostStarted {
 export interface RemoteHostManagerOptions {
     devices: TrustedDeviceStore;
     outputJournal?: boolean;
+    /** Enable only when the attached selected-session host implements legacy base pages. */
+    legacyBasePages?: boolean;
     onClientEvent: (event: unknown, ws: WebSocket) => void | Promise<void>;
     /**
      * Absolute path to the built mobile app (out/mobile). Defaults to the
@@ -126,6 +128,14 @@ export declare class RemoteHostManager extends EventEmitter {
      *  every authenticated mobile socket. Unauthenticated sockets are skipped so
      *  a half-paired client never sees session output. */
     broadcastRaw(payload: string): void;
+    /**
+     * Queue one frame unless the peer already stopped reading. A paused tab or
+     * stalled network keeps its socket OPEN while ws buffers every live frame in
+     * Host memory; retire that socket instead so the client reconnects and
+     * recovers through its normal resume path. One large frame on a drained
+     * socket is still delivered. Returns false when retired.
+     */
+    private sendBounded;
     private releaseSocket;
     private bindSocketDevice;
     /** Call after revoking/removing a trusted device to release both transports immediately. */

package/dist/mobile-remote/remote-host-manager.js

@@ -8,6 +8,8 @@ import { serveMobile } from "./mobile-static.js";
 import { PairingTokenManager } from "./pairing.js";
 import { parseMobileClientEvent } from "./mobile-client-event-validator.js";
 import { isRelayOrigin } from "../remote-relay/protocol.js";
+/** Outbound bytes one paired socket may leave unread before it is retired. */
+const MAX_SOCKET_BACKLOG_BYTES = 4 * 1024 * 1024;
 /**
  * Pick the Mac's real LAN IPv4 so a phone on the same Wi-Fi can reach the
  * remote host. We bind to a concrete LAN address (NOT 0.0.0.0) per the design's
@@ -124,6 +126,16 @@ export class RemoteHostManager extends EventEmitter {
         const gate = this.passcode;
         this.opts.webApi?.start();
         const server = createServer((req, res) => {
+            let pathname;
+            try {
+                pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+            }
+            catch {
+                res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+                res.end("invalid request target");
+                req.resume();
+                return;
+            }
             // Tunnel mode: a passcode gate sits in front of EVERY route. The gate
             // either allows (returns true) or writes its own 401/403 challenge.
             if (gate && !gate.gate(req, res))
@@ -156,9 +168,7 @@ export class RemoteHostManager extends EventEmitter {
                 });
                 return;
             }
-            const uploadPath = req.url
-                ? new URL(req.url, "http://localhost").pathname.match(/^\/api\/mobile\/uploads\/([A-Za-z0-9_-]+)$/)
-                : null;
+            const uploadPath = pathname.match(/^\/api\/mobile\/uploads\/([A-Za-z0-9_-]+)$/);
             if (uploadPath && this.opts.uploads) {
                 void this.opts.uploads.acceptPut(uploadPath[1], req, res);
                 return;
@@ -409,7 +419,14 @@ export class RemoteHostManager extends EventEmitter {
             return {
                 type: "pair.ok",
                 device,
-                ...(this.opts.outputJournal ? { capabilities: { outputJournal: 1 } } : {}),
+                ...(this.opts.outputJournal
+                    ? {
+                        capabilities: {
+                            outputJournal: 1,
+                            ...(this.opts.legacyBasePages ? { legacyBasePages: 1 } : {}),
+                        },
+                    }
+                    : {}),
             };
         }
         if (event.type === "auth.device") {
@@ -425,7 +442,14 @@ export class RemoteHostManager extends EventEmitter {
             return {
                 type: "auth.ok",
                 device,
-                ...(this.opts.outputJournal ? { capabilities: { outputJournal: 1 } } : {}),
+                ...(this.opts.outputJournal
+                    ? {
+                        capabilities: {
+                            outputJournal: 1,
+                            ...(this.opts.legacyBasePages ? { legacyBasePages: 1 } : {}),
+                        },
+                    }
+                    : {}),
             };
         }
         return undefined;
@@ -442,7 +466,7 @@ export class RemoteHostManager extends EventEmitter {
         const payload = JSON.stringify(event);
         for (const client of this.wss?.clients ?? []) {
             if (client.readyState === client.OPEN && this.authed.get(client) === deviceId) {
-                client.send(payload);
+                this.sendBounded(client, payload);
             }
         }
     }
@@ -464,12 +488,8 @@ export class RemoteHostManager extends EventEmitter {
                 this.viewers.get(client) === viewerId) {
                 // A selected viewer cannot accumulate an unbounded outbound page queue
                 // by issuing new reads while refusing to consume prior replies.
-                if (client.bufferedAmount + Buffer.byteLength(payload) > 4 * 1024 * 1024) {
-                    this.releaseSocket(client);
-                    client.terminate();
+                if (!this.sendBounded(client, payload))
                     return;
-                }
-                client.send(payload);
             }
         }
     }
@@ -477,7 +497,7 @@ export class RemoteHostManager extends EventEmitter {
     sendRawToDevice(deviceId, payload) {
         for (const client of this.wss?.clients ?? []) {
             if (client.readyState === client.OPEN && this.authed.get(client) === deviceId) {
-                client.send(payload);
+                this.sendBounded(client, payload);
             }
         }
     }
@@ -487,10 +507,27 @@ export class RemoteHostManager extends EventEmitter {
     broadcastRaw(payload) {
         for (const client of this.wss?.clients ?? []) {
             if (client.readyState === client.OPEN && this.authed.has(client)) {
-                client.send(payload);
+                this.sendBounded(client, payload);
             }
         }
     }
+    /**
+     * Queue one frame unless the peer already stopped reading. A paused tab or
+     * stalled network keeps its socket OPEN while ws buffers every live frame in
+     * Host memory; retire that socket instead so the client reconnects and
+     * recovers through its normal resume path. One large frame on a drained
+     * socket is still delivered. Returns false when retired.
+     */
+    sendBounded(client, payload) {
+        if (client.bufferedAmount > 0 &&
+            client.bufferedAmount + Buffer.byteLength(payload) > MAX_SOCKET_BACKLOG_BYTES) {
+            this.releaseSocket(client);
+            client.terminate();
+            return false;
+        }
+        client.send(payload);
+        return true;
+    }
     releaseSocket(ws) {
         const deviceId = this.authed.get(ws);
         const viewerId = this.viewers.get(ws);