tmux-ide 2.7.0 → 2.9.0-beta.11

package/packages/daemon/dist/terminal/pane-stream/pane-stream-websocket.js

@@ -0,0 +1,2067 @@
+import { z } from "zod";
+import { PANE_STREAM_MAX_HELD_DELTAS, PANE_STREAM_MAX_OUTPUT_BYTES, PANE_STREAM_MAX_PANES, PANE_STREAM_MAX_SEED_BYTES, PANE_STREAM_PROTOCOL_VERSION, PANE_STREAM_REDEEM_PATH, PANE_STREAM_WEBSOCKET_SUBPROTOCOL, PaneStreamClientFrameSchemaZ, PaneStreamLoopbackWebSocketUrlSchemaZ, PaneStreamRedeemFrameSchemaZ, PaneStreamServerFrameSchemaZ, sharedMonotonicMicros, } from "@tmux-ide/contracts";
+import { canonicalOriginOrNull, digestSecret, digestsEqual, rawDataByteLength, rawDataToBuffer, safeCloseSocket, strictJsonParse, } from "../attachments/admission-util.js";
+import { SessionRuntimeControllerLeaseError } from "../session-runtime/registry.js";
+import { terminalDeliveryObservationOrdinal } from "../session-runtime/terminal-delivery-observation-identity.js";
+import { PaneStreamLeaseError, } from "./lease-manager.js";
+import { DEFAULT_PANE_STREAM_FLOW_BUDGETS, PaneStreamWireLedger, } from "./wire-ledger.js";
+/**
+ * The pane-stream WebSocket endpoint (m43 card 2): redeems a one-time `ps1_`
+ * ticket and bridges MirrorService subscriptions to wire frames. Admission is
+ * the direct-websocket discipline verbatim — Origin-gated upgrade reservation,
+ * digest-only pending tickets, one text redemption frame, delivery-bound TTL —
+ * applied to a session-scoped lease whose pane set was enumerated at issue.
+ *
+ * Flow control at the wire is a LEDGER per (client x pane x owner): a stalled
+ * client freezes ONLY its own MirrorService subscription for the exhausted
+ * pane (siblings and other clients keep flowing; the upstream control-mode
+ * pause engages only when every subscriber of a pane is parked, which the
+ * session channel already models), tickets force-return on WS close within
+ * one tick, and thaw rides the service's atomic reseed.
+ */
+export { PANE_STREAM_REDEEM_PATH, PANE_STREAM_WEBSOCKET_SUBPROTOCOL };
+export const PANE_STREAM_MAX_REDEMPTION_BYTES = 4 * 1024;
+export const PANE_STREAM_MAX_CONTROL_BYTES = 4 * 1024;
+export const PANE_STREAM_MAX_REDEMPTION_MS = 1_000;
+const WS_OPEN = 1;
+const CANONICAL_KEY_INPUT_FRAME_PREFIX = Buffer.from('{"kind":"key",', "utf8");
+const CANONICAL_TEXT_INPUT_FRAME_PREFIX = Buffer.from('{"kind":"text",', "utf8");
+const SEMANTIC_BACKEND_REFUSALS = new Set([
+    "pane_inventory_not_ready",
+    "pane_identity_changed_before_select",
+    "pane_not_active",
+]);
+function semanticBackendRefusal(error) {
+    let candidate = error;
+    for (let depth = 0; depth < 3; depth += 1) {
+        if (!candidate || typeof candidate !== "object")
+            return null;
+        const context = "context" in candidate ? candidate.context : null;
+        const reason = context && typeof context === "object" && "reason" in context ? context.reason : null;
+        if (typeof reason === "string" && SEMANTIC_BACKEND_REFUSALS.has(reason))
+            return reason;
+        candidate = "cause" in candidate ? candidate.cause : null;
+    }
+    return null;
+}
+const TYPE_FIRST_INPUT_FRAME_PREFIX = Buffer.from('{"type":"input",', "utf8");
+function startsWithBuffer(raw, prefix) {
+    return (raw.length >= prefix.length && raw.compare(prefix, 0, prefix.length, 0, prefix.length) === 0);
+}
+function hasCanonicalInputFramePrefix(raw) {
+    return (startsWithBuffer(raw, CANONICAL_KEY_INPUT_FRAME_PREFIX) ||
+        startsWithBuffer(raw, CANONICAL_TEXT_INPUT_FRAME_PREFIX) ||
+        startsWithBuffer(raw, TYPE_FIRST_INPUT_FRAME_PREFIX));
+}
+const TicketPattern = /^ps1_[A-Za-z0-9_-]{43}$/u;
+const BindingIdSchemaZ = z
+    .string()
+    .min(1)
+    .max(4096)
+    .refine((value) => !value.includes("\0"));
+export class PaneStreamAdmissionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PaneStreamAdmissionError";
+        this.code = code;
+    }
+}
+function defaultSchedule(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+function boundedInteger(value, fallback, maximum) {
+    const selected = value ?? fallback;
+    if (!Number.isSafeInteger(selected) || selected <= 0 || selected > maximum) {
+        throw new TypeError("Pane-stream admission limit is invalid.");
+    }
+    return selected;
+}
+function sendControl(socket, frame) {
+    if (socket.readyState !== WS_OPEN)
+        return;
+    const encoded = JSON.stringify(frame);
+    if (Buffer.byteLength(encoded, "utf8") > PANE_STREAM_MAX_CONTROL_BYTES) {
+        throw new TypeError("Pane-stream control frame exceeded its bound.");
+    }
+    socket.send(encoded, { binary: false });
+}
+function errorFrameCode(error) {
+    if (error instanceof PaneStreamLeaseError && error.code === "ticket-expired") {
+        return "ticket-expired";
+    }
+    if (error instanceof PaneStreamAdmissionError) {
+        switch (error.code) {
+            case "live-capacity-exhausted":
+                return "live-capacity-exhausted";
+            case "pane-not-found":
+            case "stream-unavailable":
+                return "stream-unavailable";
+            default:
+                return "redemption-rejected";
+        }
+    }
+    return "stream-unavailable";
+}
+/**
+ * In-memory admission authority for one daemon instance. It retains only
+ * ticket digests; a daemon restart makes every prior descriptor inert.
+ */
+export class PaneStreamAdmissionCoordinator {
+    #instanceId;
+    #webSocketUrl;
+    #leaseManager;
+    #mirror;
+    #bindSessionRuntime;
+    #maxPending;
+    #maxPreAuth;
+    #maxLive;
+    #redemptionTimeoutMs;
+    #flowBudgets;
+    #drainTickMs;
+    #maxSocketBufferedBytes;
+    #maxInputFrames;
+    #maxInputBytes;
+    #inputRateWindowMs;
+    #now;
+    #schedule;
+    #observability;
+    #diagnosticSharedNowMicros;
+    #diagnosticAfterFrameParse;
+    #ledger;
+    #pending = new Map();
+    #preAuth = new Set();
+    #live = new Set();
+    #retiringReleases = new Set();
+    #clientCounter = 0;
+    #operationTail = Promise.resolve();
+    #shuttingDown = false;
+    #shutdownPromise = null;
+    constructor(options) {
+        this.#instanceId = BindingIdSchemaZ.parse(options.daemonInstanceId);
+        this.#webSocketUrl = PaneStreamLoopbackWebSocketUrlSchemaZ.parse(options.webSocketUrl);
+        this.#leaseManager = options.leaseManager;
+        this.#mirror = options.mirror;
+        this.#bindSessionRuntime = options.bindSessionRuntime;
+        this.#maxPending = boundedInteger(options.maxPendingTickets, 32, 1_024);
+        this.#maxPreAuth = boundedInteger(options.maxPreAuthSockets, 16, 1_024);
+        this.#maxLive = boundedInteger(options.maxLiveConnections, 16, 1_024);
+        this.#redemptionTimeoutMs = boundedInteger(options.redemptionTimeoutMs, PANE_STREAM_MAX_REDEMPTION_MS, PANE_STREAM_MAX_REDEMPTION_MS);
+        this.#flowBudgets = options.flowBudgets ?? DEFAULT_PANE_STREAM_FLOW_BUDGETS;
+        this.#ledger = new PaneStreamWireLedger(this.#flowBudgets);
+        this.#drainTickMs = boundedInteger(options.drainTickMs, 15, 1_000);
+        this.#maxSocketBufferedBytes = boundedInteger(options.maxSocketBufferedBytes, 32 << 20, 256 << 20);
+        this.#maxInputFrames = boundedInteger(options.maxInputFramesPerWindow, 16_384, 1 << 20);
+        this.#maxInputBytes = boundedInteger(options.maxInputBytesPerWindow, 4 << 20, 64 << 20);
+        this.#inputRateWindowMs = boundedInteger(options.inputRateWindowMs, 1_000, 60_000);
+        this.#now = options.now ?? Date.now;
+        this.#schedule = options.schedule ?? defaultSchedule;
+        this.#observability = options.observability;
+        this.#diagnosticSharedNowMicros = options.diagnosticSharedNowMicros;
+        this.#diagnosticAfterFrameParse = options.diagnosticAfterFrameParse;
+    }
+    issue(request, context) {
+        const trace = this.#observability?.beginTrace("pane-stream-connect", { generation: this.#instanceId, incarnation: null }, context.requestId);
+        const queuedAtMicros = trace ? this.#observability.nowMicros() : 0;
+        return this.#exclusive(async () => {
+            const admittedAtMicros = trace ? this.#observability.nowMicros() : 0;
+            if (trace)
+                this.#observability.recordSpan("transport", "pane-stream-issue-queue", queuedAtMicros, admittedAtMicros, trace);
+            if (this.#shuttingDown) {
+                throw new PaneStreamAdmissionError("daemon-shutting-down", "Pane-stream admission is shutting down.");
+            }
+            const origin = canonicalOriginOrNull(context.rendererOrigin);
+            if (origin === null) {
+                throw new PaneStreamAdmissionError("invalid-origin", "Renderer Origin is invalid.");
+            }
+            const requestId = z.uuid().parse(context.requestId);
+            const projectIdentity = BindingIdSchemaZ.parse(context.projectIdentity);
+            if (this.#pending.size >= this.#maxPending) {
+                throw new PaneStreamAdmissionError("pending-capacity-exhausted", "Pane-stream ticket capacity is exhausted.");
+            }
+            // The pane set is enumerated at issue: every requested pane must exist
+            // under verified semantic identity NOW. A describe failure is a probe
+            // failure and never reads as absence.
+            let described;
+            let runtimeSessionId = null;
+            try {
+                const describeStartedAtMicros = trace ? this.#observability.nowMicros() : 0;
+                if (this.#mirror.describeSessionAuthority) {
+                    const authority = await this.#mirror.describeSessionAuthority(context.sessionName);
+                    described = authority.description;
+                    runtimeSessionId = authority.runtimeSessionId;
+                }
+                else {
+                    described = await this.#mirror.describeSession(context.sessionName);
+                }
+                if (trace)
+                    this.#observability.recordSpan("transport", "pane-stream-describe-session", describeStartedAtMicros, this.#observability.nowMicros(), trace);
+            }
+            catch {
+                throw new PaneStreamAdmissionError("stream-unavailable", "The workspace session could not be described.");
+            }
+            const known = new Set(described.panes.map((pane) => pane.semanticPaneId));
+            for (const pane of request.panes) {
+                if (!known.has(pane)) {
+                    throw new PaneStreamAdmissionError("pane-not-found", `The pane ${pane} is not present in the workspace session.`);
+                }
+            }
+            const issued = await this.#leaseManager.issue(request, {
+                requestId,
+                projectIdentity,
+                sessionName: context.sessionName,
+                ...(runtimeSessionId ? { runtimeSessionId } : {}),
+                ...(context.hostClientId ? { hostClientId: context.hostClientId } : {}),
+            });
+            const descriptor = issued.descriptor;
+            const ticket = issued.redemptionTicket;
+            const valid = TicketPattern.test(ticket) &&
+                z.uuid().safeParse(descriptor.leaseId).success &&
+                descriptor.requestId === requestId &&
+                (this.#mirror.describeSessionAuthority === undefined ||
+                    descriptor.runtimeSessionId === runtimeSessionId) &&
+                descriptor.status === "awaiting-redemption" &&
+                descriptor.viewerMode === request.viewerMode &&
+                descriptor.workspaceName === request.workspaceName &&
+                descriptor.panes.length === request.panes.length &&
+                descriptor.panes.every((pane, index) => pane === request.panes[index]) &&
+                descriptor.expiresAt > this.#now();
+            const ticketDigest = digestSecret(ticket);
+            const duplicate = [...this.#pending.values()].some((pending) => digestsEqual(pending.ticketDigest, ticketDigest));
+            if (!valid || duplicate) {
+                ticketDigest.fill(0);
+                await this.#releaseLease(descriptor.leaseId, {
+                    daemonInstanceId: this.#instanceId,
+                    requestId,
+                    projectIdentity,
+                });
+                throw new PaneStreamAdmissionError("stream-unavailable", "Pane-stream ticket generation failed.");
+            }
+            const pending = {
+                leaseId: descriptor.leaseId,
+                requestId,
+                projectIdentity,
+                origin,
+                ticketDigest,
+                descriptor: structuredClone(descriptor),
+                cancelExpiry: null,
+            };
+            pending.cancelExpiry = this.#schedule(() => {
+                void this.#exclusive(() => this.#retirePending(pending));
+            }, Math.max(1, descriptor.expiresAt - this.#now()));
+            this.#pending.set(pending.leaseId, pending);
+            if (trace)
+                this.#observability.recordSpan("transport", "pane-stream-issue-total", admittedAtMicros, this.#observability.nowMicros(), trace);
+            return Object.freeze({
+                protocolVersion: PANE_STREAM_PROTOCOL_VERSION,
+                webSocketUrl: this.#webSocketUrl,
+                redemptionTicket: ticket,
+                daemonInstanceId: this.#instanceId,
+                requestId,
+                expiresAt: descriptor.expiresAt,
+                panes: [...descriptor.panes],
+                effectiveViewerMode: descriptor.viewerMode,
+            });
+        });
+    }
+    reserveUpgrade(input) {
+        if (this.#shuttingDown) {
+            return { accepted: false, code: "daemon-shutting-down", httpStatus: 503 };
+        }
+        if (input.path !== PANE_STREAM_REDEEM_PATH) {
+            return { accepted: false, code: "invalid-path", httpStatus: 404 };
+        }
+        if (input.protocols.length !== 1 || input.protocols[0] !== PANE_STREAM_WEBSOCKET_SUBPROTOCOL) {
+            return { accepted: false, code: "invalid-subprotocol", httpStatus: 426 };
+        }
+        const origin = canonicalOriginOrNull(input.origin ?? "");
+        if (origin === null) {
+            return { accepted: false, code: "invalid-origin", httpStatus: 403 };
+        }
+        const hostClientId = input.hostClientId
+            ? BindingIdSchemaZ.safeParse(input.hostClientId).data
+            : undefined;
+        if (input.hostClientId && !hostClientId) {
+            return { accepted: false, code: "origin-rejected", httpStatus: 403 };
+        }
+        const requestId = input.requestId ? z.uuid().safeParse(input.requestId).data : undefined;
+        if (input.requestId && !requestId) {
+            return { accepted: false, code: "origin-rejected", httpStatus: 403 };
+        }
+        if (![...this.#pending.values()].some((pending) => pending.origin === origin &&
+            (!requestId || pending.requestId === requestId) &&
+            (!hostClientId || pending.descriptor.hostClientId === hostClientId))) {
+            return { accepted: false, code: "origin-rejected", httpStatus: 403 };
+        }
+        if (requestId && this.#observability?.enabled) {
+            const trace = this.#observability.beginTrace("pane-stream-connect", { generation: this.#instanceId, incarnation: null }, requestId);
+            const atMicros = this.#observability.nowMicros();
+            this.#observability.recordSpan("transport", "pane-stream-upgrade-arrival", atMicros, atMicros, trace);
+        }
+        if (this.#preAuth.size >= this.#maxPreAuth) {
+            return { accepted: false, code: "preauth-capacity-exhausted", httpStatus: 503 };
+        }
+        const admission = new PreAuthAdmission({
+            origin,
+            hostClientId: hostClientId ?? null,
+            timeoutMs: this.#redemptionTimeoutMs,
+            schedule: this.#schedule,
+            onRelease: (released) => this.#preAuth.delete(released),
+            onRedeem: (active, frame, socket) => this.#redeem(active, frame, socket),
+        });
+        this.#preAuth.add(admission);
+        return { accepted: true, admission };
+    }
+    snapshot() {
+        return Object.freeze({
+            pendingTickets: this.#pending.size,
+            preAuthSockets: this.#preAuth.size,
+            liveConnections: this.#live.size,
+            shuttingDown: this.#shuttingDown,
+        });
+    }
+    /** Detached (client x pane x owner) outstanding-ticket snapshot. */
+    flowSnapshot() {
+        return this.#ledger.snapshot();
+    }
+    shutdown() {
+        if (this.#shutdownPromise)
+            return this.#shutdownPromise;
+        this.#shuttingDown = true;
+        this.#shutdownPromise = this.#finishShutdown();
+        return this.#shutdownPromise;
+    }
+    async #finishShutdown() {
+        for (const admission of [...this.#preAuth])
+            admission.close(1001, "daemon-shutdown");
+        await this.#exclusive(async () => {
+            for (const connection of [...this.#live])
+                connection.close(1001, "daemon-shutdown");
+            for (const pending of [...this.#pending.values()])
+                await this.#retirePending(pending);
+        });
+        await Promise.all([...this.#retiringReleases]);
+    }
+    #redeem(admission, frame, socket) {
+        // Stamp authenticated frame arrival BEFORE queueing: a queue wait must not
+        // consume the ticket's delivery TTL (execution has its own budget).
+        const receivedAt = this.#now();
+        return this.#exclusive(async () => {
+            if (this.#shuttingDown || frame.daemonInstanceId !== this.#instanceId) {
+                throw new PaneStreamAdmissionError("redemption-rejected", "Pane-stream redemption was rejected.");
+            }
+            const candidateDigest = digestSecret(frame.ticket);
+            let pending;
+            for (const entry of this.#pending.values()) {
+                if (digestsEqual(entry.ticketDigest, candidateDigest))
+                    pending = entry;
+            }
+            candidateDigest.fill(0);
+            if (!pending ||
+                pending.origin !== admission.origin ||
+                (admission.hostClientId !== null &&
+                    pending.descriptor.hostClientId !== admission.hostClientId) ||
+                pending.requestId !== frame.requestId) {
+                throw new PaneStreamAdmissionError("redemption-rejected", "Pane-stream redemption was rejected.");
+            }
+            const binding = {
+                daemonInstanceId: this.#instanceId,
+                requestId: pending.requestId,
+                projectIdentity: pending.projectIdentity,
+            };
+            if (!admission.isOpen()) {
+                this.#removePending(pending);
+                await this.#releaseLease(pending.leaseId, binding);
+                throw new PaneStreamAdmissionError("redemption-rejected", "Pane-stream redemption was rejected.");
+            }
+            this.#removePending(pending);
+            if (this.#live.size >= this.#maxLive) {
+                await this.#releaseLease(pending.leaseId, binding);
+                throw new PaneStreamAdmissionError("live-capacity-exhausted", "Pane-stream live capacity is exhausted.");
+            }
+            try {
+                const redeemed = await this.#leaseManager.redeem(frame.ticket, binding, receivedAt);
+                const descriptor = redeemed.descriptor;
+                if (descriptor.terminalDelivery && frame.deliveryAcks === true) {
+                    throw new PaneStreamAdmissionError("stream-unavailable", "Semantic terminal delivery owns its ACK lifecycle; legacy renderer ACKs are invalid.");
+                }
+                if (descriptor.leaseId !== pending.leaseId ||
+                    descriptor.requestId !== pending.requestId ||
+                    descriptor.status !== "active" ||
+                    descriptor.viewerMode !== pending.descriptor.viewerMode ||
+                    descriptor.panes.length !== pending.descriptor.panes.length) {
+                    throw new PaneStreamAdmissionError("stream-unavailable", "Pane-stream lease identity was unavailable.");
+                }
+                if (!admission.isOpen()) {
+                    throw new PaneStreamAdmissionError("redemption-rejected", "Pane-stream redemption was rejected.");
+                }
+                this.#clientCounter += 1;
+                const sessionRuntimeBinding = this.#bindSessionRuntime?.(descriptor) ?? null;
+                let live;
+                try {
+                    live = new PaneStreamLiveConnection({
+                        clientId: `psc-${this.#clientCounter}`,
+                        socket,
+                        descriptor: structuredClone(descriptor),
+                        sessionRuntimeBinding,
+                        binding,
+                        deliveryAcks: frame.deliveryAcks === true,
+                        diagnosticCapabilities: frame.diagnosticCapabilities ?? [],
+                        causalCellCapability: descriptor.terminalDelivery !== null &&
+                            descriptor.viewerMode === "interactive" &&
+                            frame.diagnosticCapabilities?.includes("causal-cell-v1") === true,
+                        mirror: this.#mirror,
+                        leaseManager: this.#leaseManager,
+                        ledger: this.#ledger,
+                        drainTickMs: this.#drainTickMs,
+                        maxSocketBufferedBytes: this.#maxSocketBufferedBytes,
+                        maxInputFrames: this.#maxInputFrames,
+                        maxInputBytes: this.#maxInputBytes,
+                        inputRateWindowMs: this.#inputRateWindowMs,
+                        now: this.#now,
+                        schedule: this.#schedule,
+                        observability: this.#observability,
+                        diagnosticSharedNowMicros: this.#diagnosticSharedNowMicros,
+                        diagnosticAfterFrameParse: this.#diagnosticAfterFrameParse,
+                        onRetire: (connection) => this.#trackRetiringRelease(connection),
+                    });
+                }
+                catch (error) {
+                    await sessionRuntimeBinding?.close();
+                    throw error;
+                }
+                this.#live.add(live);
+                admission.promote();
+                live.start();
+                return live;
+            }
+            catch (error) {
+                await this.#releaseLease(pending.leaseId, binding);
+                throw error;
+            }
+        });
+    }
+    #removePending(pending) {
+        if (this.#pending.get(pending.leaseId) !== pending)
+            return;
+        this.#pending.delete(pending.leaseId);
+        pending.cancelExpiry?.();
+        pending.cancelExpiry = null;
+        pending.ticketDigest.fill(0);
+    }
+    async #retirePending(pending) {
+        if (this.#pending.get(pending.leaseId) !== pending)
+            return;
+        const binding = {
+            daemonInstanceId: this.#instanceId,
+            requestId: pending.requestId,
+            projectIdentity: pending.projectIdentity,
+        };
+        this.#removePending(pending);
+        await this.#releaseLease(pending.leaseId, binding);
+    }
+    async #releaseLease(leaseId, binding) {
+        try {
+            await this.#leaseManager.release(leaseId, binding);
+        }
+        catch {
+            // The lease manager may already have retired the one-use lease.
+        }
+    }
+    #trackRetiringRelease(connection) {
+        this.#live.delete(connection);
+        const release = connection.waitForRelease();
+        this.#retiringReleases.add(release);
+        void release.then(() => this.#retiringReleases.delete(release), () => this.#retiringReleases.delete(release));
+    }
+    #exclusive(operation) {
+        const run = this.#operationTail.then(operation, operation);
+        this.#operationTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+class PreAuthAdmission {
+    origin;
+    hostClientId;
+    #onRelease;
+    #onRedeem;
+    #cancelDeadline;
+    #socket = null;
+    #frameReceived = false;
+    #open = true;
+    #promoted = false;
+    constructor(options) {
+        this.origin = options.origin;
+        this.hostClientId = options.hostClientId;
+        this.#onRelease = options.onRelease;
+        this.#onRedeem = options.onRedeem;
+        this.#cancelDeadline = options.schedule(() => this.close(1008, "redemption-timeout"), options.timeoutMs);
+    }
+    isOpen() {
+        return this.#open && !this.#promoted;
+    }
+    bind(socket) {
+        if (!this.#open || this.#socket) {
+            safeCloseSocket(socket, 1008, "redemption-rejected");
+            return;
+        }
+        this.#socket = socket;
+        socket.on("message", this.#onMessage);
+        socket.on("close", this.#onClose);
+        socket.on("error", this.#onClose);
+    }
+    cancelBeforeBind() {
+        this.close(1008, "upgrade-rejected");
+    }
+    promote() {
+        if (!this.#open)
+            return;
+        this.#promoted = true;
+        this.#open = false;
+        this.#cancelDeadline();
+        this.#detach();
+        this.#onRelease(this);
+    }
+    close(code = 1008, reason = "redemption-rejected") {
+        if (!this.#open)
+            return;
+        this.#open = false;
+        this.#cancelDeadline();
+        const socket = this.#socket;
+        this.#detach();
+        this.#onRelease(this);
+        if (socket)
+            safeCloseSocket(socket, code, reason);
+    }
+    #onMessage = (data, isBinary) => {
+        if (!this.#open || this.#frameReceived) {
+            this.close(1008, "redemption-frame-rejected");
+            return;
+        }
+        this.#frameReceived = true;
+        const byteLength = rawDataByteLength(data, PANE_STREAM_MAX_REDEMPTION_BYTES);
+        if (isBinary || byteLength === 0 || byteLength > PANE_STREAM_MAX_REDEMPTION_BYTES) {
+            this.close(1009, "redemption-frame-rejected");
+            return;
+        }
+        let frame;
+        try {
+            frame = PaneStreamRedeemFrameSchemaZ.parse(strictJsonParse(rawDataToBuffer(data)));
+        }
+        catch {
+            this.close(1008, "redemption-frame-rejected");
+            return;
+        }
+        const socket = this.#socket;
+        if (!socket) {
+            this.close(1008, "redemption-rejected");
+            return;
+        }
+        this.#cancelDeadline();
+        void this.#onRedeem(this, frame, socket).catch((error) => {
+            if (!this.#open)
+                return;
+            const code = errorFrameCode(error);
+            try {
+                sendControl(socket, {
+                    type: "error",
+                    protocolVersion: PANE_STREAM_PROTOCOL_VERSION,
+                    code,
+                    retryable: code === "live-capacity-exhausted" || code === "ticket-expired",
+                });
+            }
+            catch {
+                // Closing below is the fail-closed response.
+            }
+            this.close(code === "live-capacity-exhausted" ? 1013 : 1008, "redemption-rejected");
+        });
+    };
+    #onClose = () => this.close(1008, "redemption-rejected");
+    #detach() {
+        const socket = this.#socket;
+        this.#socket = null;
+        if (!socket)
+            return;
+        socket.off("message", this.#onMessage);
+        socket.off("close", this.#onClose);
+        socket.off("error", this.#onClose);
+    }
+}
+export class PaneStreamLiveConnection {
+    #clientId;
+    #socket;
+    #descriptor;
+    #binding;
+    #sessionRuntimeBinding;
+    #deliveryAcks;
+    #causalCellCapability;
+    #diagnosticCapabilities;
+    #mirror;
+    #leaseManager;
+    #ledger;
+    #drainTickMs;
+    #maxSocketBufferedBytes;
+    #maxInputFrames;
+    #maxInputBytes;
+    #inputRateWindowMs;
+    #now;
+    #schedule;
+    #observability;
+    #diagnosticSharedRawMicros;
+    #diagnosticAfterFrameParse;
+    #onRetire;
+    #panes = new Map();
+    #semanticLayouts = new Map();
+    #semanticExpectedPaneIds = null;
+    #semanticRuntimeSessionId = null;
+    #semanticTopologyEpoch = -1;
+    #sendQueue = [];
+    #semanticDrainWaiters = new Map();
+    #layoutSubscription = null;
+    #sentBytesTotal = 0;
+    #drainedBytesTotal = 0;
+    #cancelDrainTick = null;
+    #inputWindowStartedAt;
+    #inputWindowFrames = 0;
+    #inputWindowBytes = 0;
+    #nextViewportSeq = 1;
+    #nextClockProbe = 1;
+    #requestedAuthorities = new Set();
+    #usesExplicitAuthority = false;
+    #legacyInputActivated = false;
+    #legacyGeometryActivated = false;
+    #closed = false;
+    #releasePromise = null;
+    #stopAuthoritySnapshots = null;
+    #sharedClockOriginMicros = null;
+    #diagnosticFirstSeedObserved = false;
+    #diagnosticLifecycleStages;
+    #recordDiagnosticLifecycle(operation, closeCode, closeReason) {
+        if (!this.#observability?.enabled || !this.#diagnosticLifecycleStages)
+            return;
+        if (this.#diagnosticLifecycleStages.has(operation))
+            return;
+        this.#diagnosticLifecycleStages.add(operation);
+        const trace = this.#observability.beginTrace("pane-stream-connect", { generation: this.#binding.daemonInstanceId, incarnation: null }, this.#binding.requestId);
+        const atMicros = this.#observability.nowMicros();
+        const legalReason = (new Set([
+            "stream-retired",
+            "stream-unavailable",
+            "stream-closed",
+            "topology-changed",
+            "output-backpressure",
+            "panes-closed",
+            "peer-closed",
+            "daemon-shutdown",
+            "redemption-rejected",
+            "unknown",
+        ]).has(closeReason ?? "")
+            ? closeReason
+            : closeReason
+                ? "unknown"
+                : "none");
+        this.#observability.recordSpan("transport", operation, atMicros, atMicros, trace, undefined, Object.freeze({
+            paneStreamCloseCode: Number.isInteger(closeCode) && closeCode >= 1000 && closeCode <= 4999 ? closeCode : 0,
+            paneStreamCloseReason: legalReason,
+        }));
+    }
+    #sharedMicros() {
+        const raw = this.#diagnosticSharedRawMicros();
+        this.#sharedClockOriginMicros ??= raw;
+        const elapsed = raw - this.#sharedClockOriginMicros;
+        if (!Number.isSafeInteger(elapsed) || elapsed < 0)
+            throw new Error("Daemon shared monotonic clock regressed");
+        return elapsed;
+    }
+    constructor(options) {
+        this.#clientId = options.clientId;
+        this.#socket = options.socket;
+        this.#descriptor = options.descriptor;
+        this.#binding = options.binding;
+        this.#sessionRuntimeBinding = options.sessionRuntimeBinding;
+        this.#usesExplicitAuthority = options.sessionRuntimeBinding?.explicitAuthority === true;
+        if (this.#descriptor.viewerMode === "interactive" && !this.#sessionRuntimeBinding) {
+            throw new Error("Interactive pane stream requires SessionRuntime authority");
+        }
+        this.#deliveryAcks = options.deliveryAcks;
+        this.#causalCellCapability = options.causalCellCapability;
+        this.#diagnosticCapabilities = options.diagnosticCapabilities;
+        this.#mirror = options.mirror;
+        this.#leaseManager = options.leaseManager;
+        this.#ledger = options.ledger;
+        this.#drainTickMs = options.drainTickMs;
+        this.#maxSocketBufferedBytes = options.maxSocketBufferedBytes;
+        this.#maxInputFrames = options.maxInputFrames;
+        this.#maxInputBytes = options.maxInputBytes;
+        this.#inputRateWindowMs = options.inputRateWindowMs;
+        this.#now = options.now;
+        this.#inputWindowStartedAt = this.#now();
+        this.#schedule = options.schedule;
+        this.#observability = options.observability;
+        this.#diagnosticLifecycleStages = options.observability?.enabled ? new Set() : null;
+        this.#diagnosticSharedRawMicros = this.#diagnosticCapabilities.includes("clock-bounds-v1")
+            ? (options.diagnosticSharedNowMicros ?? sharedMonotonicMicros)
+            : undefined;
+        this.#diagnosticAfterFrameParse = options.diagnosticAfterFrameParse;
+        this.#onRetire = options.onRetire;
+        for (const pane of options.descriptor.panes) {
+            this.#panes.set(pane, {
+                semanticPaneId: pane,
+                sub: null,
+                delivery: null,
+                deliveryAddress: null,
+                serverSeq: 0,
+                sentPaneFrames: 0,
+                consumedSeq: 0,
+                nextInputSeq: 1,
+                frozenByWire: false,
+                closed: false,
+                batch: null,
+            });
+        }
+    }
+    get clientId() {
+        return this.#clientId;
+    }
+    start() {
+        if (this.#closed || this.#socket.readyState !== WS_OPEN) {
+            this.close(1008, "stream-retired");
+            return;
+        }
+        this.#socket.on("message", this.#onMessage);
+        this.#socket.on("close", this.#onSocketClose);
+        this.#socket.on("error", this.#onSocketClose);
+        try {
+            sendControl(this.#socket, {
+                type: "ready",
+                protocolVersion: PANE_STREAM_PROTOCOL_VERSION,
+                daemonInstanceId: this.#binding.daemonInstanceId,
+                requestId: this.#binding.requestId,
+                ...(this.#sessionRuntimeBinding
+                    ? { connectionClientId: this.#sessionRuntimeBinding.clientId }
+                    : {}),
+                panes: [...this.#descriptor.panes],
+                effectiveViewerMode: this.#descriptor.viewerMode,
+                ...(this.#diagnosticCapabilities.length > 0
+                    ? { diagnosticCapabilities: [...this.#diagnosticCapabilities] }
+                    : {}),
+            });
+            this.#recordDiagnosticLifecycle("pane-stream-server-ready");
+        }
+        catch {
+            this.close(1011, "stream-unavailable-describe");
+            return;
+        }
+        this.#stopAuthoritySnapshots =
+            this.#sessionRuntimeBinding?.onAuthoritySnapshot?.((snapshot) => this.#usesExplicitAuthority ? this.#sendAuthoritySnapshot(snapshot) : undefined) ?? null;
+        void this.#subscribeAll();
+    }
+    close(code = 1000, reason = "stream-closed") {
+        if (this.#closed)
+            return;
+        this.#recordDiagnosticLifecycle("pane-stream-terminal", code, reason);
+        this.#closed = true;
+        this.#cancelDrainTick?.();
+        this.#cancelDrainTick = null;
+        // Departure force-returns every ticket within this same tick.
+        this.#ledger.forceReturnClient(this.#clientId);
+        this.#sendQueue.length = 0;
+        for (const waiters of this.#semanticDrainWaiters.values())
+            for (const resolve of waiters)
+                resolve();
+        this.#semanticDrainWaiters.clear();
+        this.#socket.off("message", this.#onMessage);
+        this.#socket.off("close", this.#onSocketClose);
+        this.#socket.off("error", this.#onSocketClose);
+        this.#stopAuthoritySnapshots?.();
+        this.#stopAuthoritySnapshots = null;
+        const closures = [];
+        const layoutSubscription = this.#layoutSubscription;
+        this.#layoutSubscription = null;
+        if (layoutSubscription)
+            closures.push(layoutSubscription.close().catch(() => undefined));
+        for (const channel of this.#panes.values()) {
+            const sub = channel.sub;
+            channel.sub = null;
+            const delivery = channel.delivery;
+            channel.delivery = null;
+            channel.closed = true;
+            if (sub)
+                closures.push(sub.close().catch(() => undefined));
+            if (delivery)
+                closures.push(delivery.close().catch(() => undefined));
+        }
+        this.#releasePromise = Promise.allSettled([
+            ...closures,
+            this.#leaseManager.release(this.#descriptor.leaseId, this.#binding).catch(() => undefined),
+            this.#sessionRuntimeBinding?.close() ?? Promise.resolve(),
+        ]);
+        this.#onRetire(this);
+        safeCloseSocket(this.#socket, code, reason);
+    }
+    async waitForRelease() {
+        await this.#releasePromise;
+    }
+    /** TESTS ONLY — run one drain evaluation without waiting for the tick. */
+    drainNowForTest() {
+        this.#drainNow();
+    }
+    async #subscribeAll() {
+        // Fresh truth once for the whole set: a pane listed at issue but gone by
+        // redeem gets an honest `closed` frame (a successful describe omitting it
+        // is absence; a describe FAILURE is not and fails the connection).
+        let described;
+        try {
+            described = await this.#mirror.describeSession(this.#descriptor.sessionName);
+        }
+        catch {
+            this.close(1011, "stream-unavailable");
+            return;
+        }
+        if (this.#closed)
+            return;
+        const known = new Set(described.panes.map((pane) => pane.semanticPaneId));
+        if (this.#descriptor.terminalDelivery) {
+            await this.#subscribeSemantic(known);
+            return;
+        }
+        if (this.#mirror.subscribeLayout) {
+            try {
+                const layoutSubscription = await this.#mirror.subscribeLayout(this.#descriptor.sessionName, (event) => this.#onLayout(event));
+                if (this.#closed) {
+                    await layoutSubscription.close().catch(() => undefined);
+                    return;
+                }
+                this.#layoutSubscription = layoutSubscription;
+            }
+            catch {
+                this.close(1011, "stream-unavailable");
+                return;
+            }
+        }
+        let layoutAttached = this.#layoutSubscription !== null;
+        for (const channel of this.#panes.values()) {
+            if (this.#closed)
+                return;
+            if (!known.has(channel.semanticPaneId)) {
+                this.#emitClosed(channel);
+                continue;
+            }
+            try {
+                const sub = await this.#mirror.subscribe({
+                    session: this.#descriptor.sessionName,
+                    semanticPaneId: channel.semanticPaneId,
+                    onEvent: (event) => this.#onPaneEvent(channel, event),
+                    ...(layoutAttached ? {} : { onLayout: (event) => this.#onLayout(event) }),
+                });
+                layoutAttached = true;
+                if (this.#closed || channel.closed) {
+                    void sub.close().catch(() => undefined);
+                    continue;
+                }
+                channel.sub = sub;
+            }
+            catch {
+                this.close(1011, "stream-unavailable");
+                return;
+            }
+        }
+        this.#closeIfAllPanesGone();
+    }
+    async #subscribeSemantic(known) {
+        const binding = this.#sessionRuntimeBinding;
+        const offer = this.#descriptor.terminalDelivery;
+        if (!binding || !offer) {
+            this.close(1011, "stream-unavailable");
+            return;
+        }
+        const expectedPaneIds = [...this.#descriptor.panes].sort();
+        if (expectedPaneIds.some((pane) => !known.has(pane))) {
+            this.#failTopologyChanged();
+            return;
+        }
+        const channels = [...this.#panes.values()];
+        if (this.#closed || channels.length === 0)
+            return;
+        let stagedAuthority = null;
+        let authorityMalformed = false;
+        let layoutActivated = false;
+        // Establish the single session layout observer first. MirrorService owns
+        // this lifecycle and may share native control state with delivery setup;
+        // only the independent pane delivery opens below are parallelized.
+        try {
+            if (!this.#mirror.subscribeLayout)
+                throw new Error("authoritative layout is unavailable");
+            const subscription = await this.#mirror.subscribeLayout(this.#descriptor.sessionName, () => undefined, {
+                expectedSemanticPaneIds: expectedPaneIds,
+                expectedRuntimeSessionId: this.#descriptor.runtimeSessionId,
+                onAuthority: (snapshot) => {
+                    this.#recordDiagnosticLifecycle("pane-stream-layout-staged");
+                    if (snapshot.layouts.length > PANE_STREAM_MAX_PANES)
+                        authorityMalformed = true;
+                    else if (!layoutActivated)
+                        stagedAuthority = snapshot;
+                    else
+                        this.#onLayoutAuthority(snapshot);
+                },
+            });
+            if (this.#closed) {
+                await subscription.close().catch(() => undefined);
+                return;
+            }
+            const authority = stagedAuthority;
+            const stagedInitialFrames = authorityMalformed ||
+                authority === null ||
+                authority.session !== this.#descriptor.sessionName ||
+                this.#descriptor.runtimeSessionId === null ||
+                authority.runtimeSessionId !== this.#descriptor.runtimeSessionId ||
+                authority.topologyEpoch < 0
+                ? null
+                : this.#validateInitialLayout(authority.layouts, expectedPaneIds);
+            if (!stagedInitialFrames) {
+                await subscription.close().catch(() => undefined);
+                this.#failTopologyChanged();
+                return;
+            }
+            this.#layoutSubscription = subscription;
+        }
+        catch (cause) {
+            if (cause instanceof Error && cause.name === "MirrorTopologyChangedError") {
+                this.#failTopologyChanged();
+                return;
+            }
+            this.close(1011, "stream-unavailable");
+            return;
+        }
+        // Delivery owners are pane-scoped and independent. Open them concurrently,
+        // then publish in descriptor order only after every pane is coherent. This
+        // removes N x attachment latency without allowing a fast pane to make the
+        // session look ready while a sibling is still missing. allSettled is
+        // deliberate: partial success is always closed before the socket retires.
+        const openings = channels.map(async (channel) => {
+            const pending = [];
+            let ready = false;
+            const delivery = await binding.openTerminalDelivery(channel.semanticPaneId, offer, (message) => {
+                if (!ready)
+                    pending.push(message);
+                else
+                    return this.#sendTerminalDelivery(channel.semanticPaneId, message);
+            });
+            return {
+                channel,
+                delivery,
+                pending,
+                markReady: () => {
+                    ready = true;
+                },
+            };
+        });
+        const settled = await Promise.allSettled(openings);
+        const opened = settled.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
+        if (this.#closed ||
+            settled.some((result) => result.status === "rejected" || !result.value.delivery.negotiation.accepted)) {
+            await Promise.all(opened.map(({ delivery }) => delivery.close().catch(() => undefined)));
+            if (!this.#closed)
+                this.close(1011, "stream-unavailable");
+            return;
+        }
+        const deliveryIdentityChanged = opened.some(({ channel, delivery, pending }) => {
+            if (!delivery.negotiation.accepted)
+                return true;
+            const negotiated = delivery.negotiation.negotiated;
+            if (negotiated.generation !== this.#binding.daemonInstanceId)
+                return true;
+            let incarnation = null;
+            for (const message of pending) {
+                if (message.type !== "terminal.delivery")
+                    continue;
+                if (message.workspaceName !== this.#descriptor.sessionName ||
+                    message.semanticPaneId !== channel.semanticPaneId ||
+                    message.generation !== negotiated.generation ||
+                    message.deliveryNonce !== negotiated.deliveryNonce ||
+                    (incarnation !== null && message.incarnation !== incarnation))
+                    return true;
+                incarnation = message.incarnation;
+            }
+            return false;
+        });
+        if (deliveryIdentityChanged) {
+            await Promise.all(opened.map(({ delivery }) => delivery.close().catch(() => undefined)));
+            this.#failTopologyChanged();
+            return;
+        }
+        const authority = stagedAuthority;
+        const initialFrames = authorityMalformed ||
+            authority === null ||
+            authority.session !== this.#descriptor.sessionName ||
+            this.#descriptor.runtimeSessionId === null ||
+            authority.runtimeSessionId !== this.#descriptor.runtimeSessionId ||
+            authority.topologyEpoch < 0
+            ? null
+            : this.#validateInitialLayout(authority.layouts, expectedPaneIds);
+        if (!initialFrames) {
+            await Promise.all(opened.map(({ delivery }) => delivery.close().catch(() => undefined)));
+            this.#failTopologyChanged();
+            return;
+        }
+        this.#recordDiagnosticLifecycle("pane-stream-layout-validated");
+        this.#semanticExpectedPaneIds = expectedPaneIds;
+        this.#semanticRuntimeSessionId = authority.runtimeSessionId;
+        this.#semanticTopologyEpoch = authority.topologyEpoch;
+        this.#semanticLayouts.clear();
+        for (const event of authority.layouts)
+            this.#semanticLayouts.set(event.semanticWindowId, event);
+        this.#sendFrame(null, {
+            type: "layout-snapshot",
+            topologyEpoch: authority.topologyEpoch,
+            layouts: initialFrames,
+        });
+        layoutActivated = true;
+        this.#recordDiagnosticLifecycle("pane-stream-delivery-open");
+        for (const { channel, delivery, pending, markReady } of opened) {
+            if (this.#closed || channel.closed) {
+                await delivery.close();
+                continue;
+            }
+            // The rejected case was eliminated above; retain this narrowing at the
+            // publication boundary so an invalid negotiation cannot leak a nonce.
+            if (!delivery.negotiation.accepted)
+                continue;
+            channel.delivery = delivery;
+            void delivery.closed?.then((reason) => {
+                if (reason === "sink-failed" &&
+                    !this.#closed &&
+                    !channel.closed &&
+                    channel.delivery === delivery)
+                    this.close(1013, "output-backpressure");
+            });
+            channel.deliveryAddress = {
+                workspaceName: this.#descriptor.workspaceName,
+                generation: delivery.negotiation.negotiated.generation,
+                incarnation: null,
+                deliveryNonce: delivery.negotiation.negotiated.deliveryNonce,
+            };
+            this.#sendFrame(null, {
+                type: "terminal-delivery-ready",
+                pane: channel.semanticPaneId,
+                negotiation: delivery.negotiation,
+            });
+            markReady();
+            for (const message of pending)
+                await this.#sendTerminalDelivery(channel.semanticPaneId, message);
+        }
+        this.#closeIfAllPanesGone();
+    }
+    async #sendTerminalDelivery(pane, message) {
+        if (message.type === "terminal.delivery") {
+            if (!this.#diagnosticFirstSeedObserved) {
+                this.#diagnosticFirstSeedObserved = true;
+                this.#recordDiagnosticLifecycle("pane-stream-first-seed");
+            }
+            const channel = this.#panes.get(pane);
+            if (channel?.deliveryAddress)
+                channel.deliveryAddress.incarnation = message.incarnation;
+            // SessionRuntime keys canonical replicas by the tmux session, while the
+            // public pane-stream lease is keyed by its workspace identity. Translate
+            // at this boundary so the renderer has one coherent address vocabulary.
+            const detailedDeliveryObservation = this.#observability?.enabled === true;
+            const trace = message.performanceTraceId && detailedDeliveryObservation
+                ? this.#observability.beginTrace("terminal-input-to-paint", { generation: message.generation, incarnation: message.incarnation }, message.performanceTraceId)
+                : null;
+            let startedAtMicros = null;
+            if (detailedDeliveryObservation)
+                try {
+                    startedAtMicros = this.#observability.nowMicros();
+                }
+                catch {
+                    // Detailed delivery timing cannot alter socket delivery.
+                }
+            let startedAtSharedMicros = null;
+            if (startedAtMicros !== null && this.#diagnosticSharedRawMicros) {
+                try {
+                    startedAtSharedMicros = this.#sharedMicros();
+                }
+                catch {
+                    // Shared-clock diagnostics cannot alter terminal delivery.
+                }
+            }
+            this.#sendFrame(pane, {
+                type: "terminal-delivery-envelope",
+                pane,
+                envelope: { ...message, workspaceName: this.#descriptor.workspaceName },
+            });
+            if (startedAtMicros !== null) {
+                let endedAtMicros;
+                try {
+                    endedAtMicros = this.#observability.nowMicros();
+                }
+                catch {
+                    return;
+                }
+                let endedAtSharedMicros = null;
+                if (startedAtSharedMicros !== null) {
+                    try {
+                        endedAtSharedMicros = this.#sharedMicros();
+                    }
+                    catch {
+                        // Preserve the process-local span when shared sampling fails.
+                    }
+                }
+                try {
+                    this.#observability.recordSpan("transport", "pane-stream-socket-send", startedAtMicros, endedAtMicros, trace, startedAtSharedMicros === null || endedAtSharedMicros === null
+                        ? undefined
+                        : {
+                            startedAtMicros: startedAtSharedMicros,
+                            endedAtMicros: endedAtSharedMicros,
+                        }, Object.freeze({
+                        workspaceName: message.workspaceName,
+                        semanticPaneId: message.semanticPaneId,
+                        canonicalGeneration: message.generation,
+                        canonicalIncarnation: message.incarnation,
+                        canonicalRevision: message.canonicalRevision,
+                        canonicalStateHash: message.canonicalStateHash,
+                        transactionId: message.transactionId,
+                        ...(terminalDeliveryObservationOrdinal(message) === null
+                            ? {}
+                            : { deliveryOrdinal: terminalDeliveryObservationOrdinal(message) }),
+                        deliveryClientId: this.#sessionRuntimeBinding?.clientId ?? this.#clientId,
+                        deliverySurface: this.#sessionRuntimeBinding?.surface ?? "unknown",
+                        deliveryLaneId: this.#sessionRuntimeBinding?.deliveryLaneId ?? this.#clientId,
+                        deliveryRequestId: this.#sessionRuntimeBinding?.deliveryRequestId ?? this.#clientId,
+                        deliveryNonce: message.deliveryNonce,
+                    }));
+                }
+                catch {
+                    // Diagnostics cannot alter terminal delivery.
+                }
+            }
+        }
+        else if (message.type === "terminal.delivery.chunk") {
+            this.#sendFrame(pane, {
+                type: "terminal-delivery-chunk",
+                pane,
+                transactionId: message.transactionId,
+                index: message.index,
+                data: Buffer.from(message.bytes).toString("base64"),
+            });
+        }
+        else {
+            this.#sendFrame(pane, { type: "terminal-delivery-fault", pane, fault: message });
+            // Lifecycle/control truth must never queue behind bulk terminal bytes.
+            // The hard socket-wide ceiling still closes a genuinely wedged client in
+            // #drainNow; a source-close frame itself is small and immediately useful.
+            return;
+        }
+        await this.#awaitSemanticCredit(pane);
+    }
+    #awaitSemanticCredit(pane) {
+        // Backpressure is pane-local. Aggregate pressure is guarded by the hard
+        // socket ceiling in #drainNow, but must not let a noisy sibling prevent a
+        // pane-close (or any other pane's next semantic delivery) from surfacing.
+        if (!this.#ledger.isStalled(this.#clientId, pane))
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const waiters = this.#semanticDrainWaiters.get(pane) ?? [];
+            waiters.push(resolve);
+            this.#semanticDrainWaiters.set(pane, waiters);
+            this.#ensureDrainTick();
+        });
+    }
+    // ── Mirror events → frames ────────────────────────────────────────────────
+    #onPaneEvent(channel, event) {
+        if (this.#closed || channel.closed)
+            return;
+        switch (event.type) {
+            case "reset": {
+                channel.batch = {
+                    reset: { cols: event.cols, rows: event.rows },
+                    seed: null,
+                    held: [],
+                    guardArmed: false,
+                };
+                this.#armBatchGuard(channel);
+                return;
+            }
+            case "seed": {
+                if (channel.batch)
+                    channel.batch.seed = event.data;
+                else {
+                    channel.batch = { reset: null, seed: event.data, held: [], guardArmed: false };
+                    this.#armBatchGuard(channel);
+                }
+                return;
+            }
+            case "delta": {
+                const batch = channel.batch;
+                if (batch && batch.seed !== null) {
+                    batch.held.push(event.data);
+                    return;
+                }
+                if (batch) {
+                    // A delta cannot precede the capture of an armed reseed (the feed
+                    // discards those); treat an impossible ordering as live output.
+                    this.#flushBatch(channel, null);
+                }
+                this.#emitOutput(channel, event.data);
+                return;
+            }
+            case "cursor": {
+                if (channel.batch) {
+                    this.#flushBatch(channel, { x: event.x, y: event.y });
+                    return;
+                }
+                this.#sendPaneFrame(channel, {
+                    type: "cursor",
+                    pane: channel.semanticPaneId,
+                    seq: this.#nextSeq(channel),
+                    x: event.x,
+                    y: event.y,
+                });
+                return;
+            }
+            case "flow": {
+                if (channel.batch)
+                    this.#flushBatch(channel, null);
+                this.#sendPaneFrame(channel, {
+                    type: "flow",
+                    pane: channel.semanticPaneId,
+                    seq: this.#nextSeq(channel),
+                    state: event.state,
+                    reason: event.reason,
+                });
+                return;
+            }
+            case "closed": {
+                if (channel.batch)
+                    this.#flushBatch(channel, null);
+                this.#emitClosed(channel);
+                this.#closeIfAllPanesGone();
+                return;
+            }
+        }
+    }
+    /** The atomic batch arrives in ONE synchronous callback burst; a microtask
+     *  guard flushes the degraded no-cursor path without reordering anything. */
+    #armBatchGuard(channel) {
+        const batch = channel.batch;
+        if (!batch || batch.guardArmed)
+            return;
+        batch.guardArmed = true;
+        queueMicrotask(() => {
+            if (channel.batch === batch)
+                this.#flushBatch(channel, null);
+        });
+    }
+    #flushBatch(channel, cursor) {
+        const batch = channel.batch;
+        channel.batch = null;
+        if (!batch || this.#closed || channel.closed)
+            return;
+        let seed = batch.seed ?? new Uint8Array(0);
+        if (seed.byteLength > PANE_STREAM_MAX_SEED_BYTES) {
+            // Pathological guard: keep the tail, resynchronizing at a line seam.
+            let start = seed.byteLength - PANE_STREAM_MAX_SEED_BYTES;
+            while (start < seed.byteLength && seed[start] !== 0x0a)
+                start += 1;
+            seed = seed.subarray(Math.min(start + 1, seed.byteLength));
+        }
+        const held = chunkBytes(concatBytes(batch.held), PANE_STREAM_MAX_OUTPUT_BYTES).slice(0, PANE_STREAM_MAX_HELD_DELTAS);
+        this.#sendPaneFrame(channel, {
+            type: "seed-batch",
+            pane: channel.semanticPaneId,
+            seq: this.#nextSeq(channel),
+            reset: batch.reset,
+            seed: Buffer.from(seed).toString("base64"),
+            held: held.map((chunk) => Buffer.from(chunk).toString("base64")),
+            cursor,
+        });
+    }
+    #emitOutput(channel, data) {
+        for (const chunk of chunkBytes(data, PANE_STREAM_MAX_OUTPUT_BYTES)) {
+            this.#sendPaneFrame(channel, {
+                type: "output",
+                pane: channel.semanticPaneId,
+                seq: this.#nextSeq(channel),
+                data: Buffer.from(chunk).toString("base64"),
+            });
+        }
+    }
+    #emitClosed(channel) {
+        if (channel.closed)
+            return;
+        channel.closed = true;
+        const sub = channel.sub;
+        channel.sub = null;
+        if (sub)
+            void sub.close().catch(() => undefined);
+        this.#sendPaneFrame(channel, {
+            type: "closed",
+            pane: channel.semanticPaneId,
+            seq: this.#nextSeq(channel),
+        });
+        this.#ledger.forgetPane(this.#clientId, channel.semanticPaneId);
+    }
+    #onLayoutAuthority(snapshot) {
+        if (this.#closed || !this.#semanticExpectedPaneIds || !this.#semanticRuntimeSessionId)
+            return;
+        if (snapshot.session !== this.#descriptor.sessionName ||
+            snapshot.runtimeSessionId !== this.#semanticRuntimeSessionId ||
+            snapshot.topologyEpoch <= this.#semanticTopologyEpoch ||
+            snapshot.layouts.length > PANE_STREAM_MAX_PANES) {
+            this.#failTopologyChanged();
+            return;
+        }
+        const frames = this.#validateInitialLayout(snapshot.layouts, this.#semanticExpectedPaneIds);
+        if (!frames) {
+            this.#failTopologyChanged();
+            return;
+        }
+        this.#semanticTopologyEpoch = snapshot.topologyEpoch;
+        this.#semanticLayouts.clear();
+        for (const event of snapshot.layouts)
+            this.#semanticLayouts.set(event.semanticWindowId, event);
+        this.#sendFrame(null, {
+            type: "layout-snapshot",
+            topologyEpoch: snapshot.topologyEpoch,
+            layouts: frames,
+        });
+    }
+    #onLayout(event) {
+        if (this.#closed)
+            return;
+        /*
+         * Every window of the session, not only the leased panes' own.
+         *
+         * The lease is SESSION-scoped by design — one socket for one workspace —
+         * and layout is that session's geometry rather than a per-pane stream. A
+         * client that saw only its leased window could not render a window LIST at
+         * all, which is what the layout-faithful view is built from (m50), and it
+         * would have to lease every pane in the session to get one.
+         *
+         * Nothing new crosses the boundary: the frame carries semantic pane ids and
+         * cell rectangles, and the same renderer is already told every pane's
+         * semantic identity by the application-shell inventory. No runtime tmux id,
+         * command, cwd or credential appears here.
+         */
+        const frame = this.#layoutFrame(event);
+        if (!frame) {
+            this.#failTopologyChanged();
+            return;
+        }
+        this.#sendFrame(null, frame);
+    }
+    #layoutFrame(event) {
+        const frame = {
+            type: "layout",
+            semanticWindowId: event.semanticWindowId,
+            windowName: event.windowName === null ? null : event.windowName.slice(0, 256),
+            currentWindow: event.currentWindow,
+            cols: event.cols,
+            rows: event.rows,
+            zoomed: event.zoomed,
+            paneBorderStatus: event.paneBorderStatus,
+            modeKeys: event.modeKeys,
+            panes: event.panes.map((pane) => ({
+                pane: pane.semanticPaneId,
+                displayName: pane.displayName,
+                displayNameSource: pane.displayNameSource,
+                left: pane.left,
+                top: pane.top,
+                width: pane.width,
+                height: pane.height,
+                active: pane.active,
+            })),
+        };
+        // Layout carries user-authored names and unbounded tmux geometry; gate it
+        // through the schema and skip rather than ever sending an invalid frame.
+        const parsed = PaneStreamServerFrameSchemaZ.safeParse(frame);
+        return parsed.success ? parsed.data : null;
+    }
+    #validateInitialLayout(events, expectedPaneIds) {
+        if (events.length === 0)
+            return null;
+        const windows = new Set();
+        const panes = [];
+        const frames = [];
+        let currentWindows = 0;
+        for (const event of events) {
+            if (event.session !== this.#descriptor.sessionName ||
+                typeof event.semanticWindowId !== "string" ||
+                windows.has(event.semanticWindowId))
+                return null;
+            windows.add(event.semanticWindowId);
+            if (event.currentWindow)
+                currentWindows += 1;
+            const frame = this.#layoutFrame(event);
+            if (!frame || frame.type !== "layout")
+                return null;
+            frames.push(frame);
+            for (const pane of event.panes) {
+                if (typeof pane.semanticPaneId !== "string")
+                    return null;
+                panes.push(pane.semanticPaneId);
+            }
+        }
+        panes.sort();
+        if (currentWindows !== 1 ||
+            new Set(panes).size !== panes.length ||
+            events.some((event) => event.zoomed && event.panes.length !== 1) ||
+            (panes.length !== expectedPaneIds.length && !events.some((event) => event.zoomed)) ||
+            panes.some((pane) => !expectedPaneIds.includes(pane)))
+            return null;
+        return frames;
+    }
+    #failTopologyChanged() {
+        if (this.#closed)
+            return;
+        this.#sendFrame(null, {
+            type: "error",
+            protocolVersion: PANE_STREAM_PROTOCOL_VERSION,
+            code: "topology-changed",
+            retryable: true,
+        });
+        this.close(1012, "topology-changed");
+    }
+    // ── Send path + flow ledger ───────────────────────────────────────────────
+    #nextSeq(channel) {
+        channel.serverSeq += 1;
+        return channel.serverSeq;
+    }
+    #sendPaneFrame(channel, frame) {
+        channel.sentPaneFrames += 1;
+        this.#sendFrame(channel.semanticPaneId, frame);
+    }
+    #sendFrame(pane, frame) {
+        if (this.#closed || this.#socket.readyState !== WS_OPEN)
+            return;
+        const encoded = JSON.stringify(frame);
+        const bytes = Buffer.byteLength(encoded, "utf8");
+        if (pane !== null) {
+            this.#ledger.take(this.#clientId, pane, "ws-send-buffer", bytes);
+            if (this.#deliveryAcks)
+                this.#ledger.take(this.#clientId, pane, "renderer-backlog", 1);
+        }
+        this.#sendQueue.push({ pane, remaining: bytes });
+        this.#sentBytesTotal += bytes;
+        try {
+            this.#socket.send(encoded, { binary: false });
+        }
+        catch {
+            this.close(1011, "stream-unavailable");
+            return;
+        }
+        // Stall is judged on the drain tick, never synchronously at send: the
+        // socket must get its chance to drain first, or a single seed batch
+        // larger than the budget would park even a healthy client.
+        this.#ensureDrainTick();
+    }
+    #evaluateStall(pane) {
+        const channel = this.#panes.get(pane);
+        if (!channel || channel.closed || channel.frozenByWire || !channel.sub)
+            return;
+        if (this.#ledger.isStalled(this.#clientId, pane)) {
+            // Park exactly this subscriber: siblings and other clients keep flowing;
+            // upstream %pause only engages when every subscriber of the pane parks.
+            channel.frozenByWire = true;
+            channel.sub.freeze();
+        }
+    }
+    #evaluateResume(pane) {
+        const channel = this.#panes.get(pane);
+        if (!channel || channel.closed || !channel.frozenByWire || !channel.sub)
+            return;
+        if (this.#ledger.shouldResume(this.#clientId, pane)) {
+            channel.frozenByWire = false;
+            channel.sub.thaw();
+        }
+    }
+    #ensureDrainTick() {
+        if (this.#cancelDrainTick || this.#closed || this.#sendQueue.length === 0)
+            return;
+        this.#cancelDrainTick = this.#schedule(() => {
+            this.#cancelDrainTick = null;
+            this.#drainNow();
+            this.#ensureDrainTick();
+        }, this.#drainTickMs);
+    }
+    #drainNow() {
+        if (this.#closed)
+            return;
+        const buffered = this.#socket.bufferedAmount ?? 0;
+        if (!Number.isSafeInteger(buffered) || buffered < 0) {
+            this.close(1011, "stream-unavailable");
+            return;
+        }
+        if (buffered > this.#maxSocketBufferedBytes) {
+            this.close(1013, "output-backpressure");
+            return;
+        }
+        let newlyDrained = this.#sentBytesTotal - buffered - this.#drainedBytesTotal;
+        while (newlyDrained > 0 && this.#sendQueue.length > 0) {
+            const head = this.#sendQueue[0];
+            const applied = Math.min(newlyDrained, head.remaining);
+            head.remaining -= applied;
+            newlyDrained -= applied;
+            this.#drainedBytesTotal += applied;
+            if (head.pane !== null) {
+                this.#ledger.give(this.#clientId, head.pane, "ws-send-buffer", applied);
+            }
+            if (head.remaining === 0)
+                this.#sendQueue.shift();
+        }
+        for (const [pane, channel] of this.#panes) {
+            if (channel.frozenByWire)
+                this.#evaluateResume(pane);
+            else
+                this.#evaluateStall(pane);
+            const waiters = this.#semanticDrainWaiters.get(pane);
+            if (waiters && this.#ledger.shouldResume(this.#clientId, pane)) {
+                this.#semanticDrainWaiters.delete(pane);
+                for (const resolve of waiters)
+                    resolve();
+            }
+        }
+    }
+    // ── Client frames ─────────────────────────────────────────────────────────
+    #onMessage = (data, isBinary) => {
+        if (this.#closed)
+            return;
+        let callbackAtSharedMicros = null;
+        let ingressAtSharedMicros = null;
+        let ingressAtMicros = null;
+        if (this.#observability?.enabled) {
+            try {
+                ingressAtMicros = this.#observability.nowMicros();
+            }
+            catch {
+                // Diagnostics cannot alter protocol truth.
+            }
+        }
+        const byteLength = rawDataByteLength(data, PANE_STREAM_MAX_CONTROL_BYTES);
+        if (isBinary || byteLength === 0 || byteLength > PANE_STREAM_MAX_CONTROL_BYTES) {
+            this.#failProtocol("protocol-error");
+            return;
+        }
+        const raw = rawDataToBuffer(data);
+        if (this.#diagnosticSharedRawMicros && hasCanonicalInputFramePrefix(raw)) {
+            try {
+                callbackAtSharedMicros = this.#sharedMicros();
+            }
+            catch {
+                // Preserve the process-local callback timestamp and product traffic.
+            }
+        }
+        let frame;
+        try {
+            frame = PaneStreamClientFrameSchemaZ.parse(strictJsonParse(raw));
+        }
+        catch {
+            this.#failProtocol("protocol-error");
+            return;
+        }
+        if (this.#diagnosticSharedRawMicros) {
+            try {
+                this.#diagnosticAfterFrameParse?.();
+            }
+            catch {
+                // Test-only diagnostics cannot alter protocol truth.
+            }
+            if (frame.type === "input") {
+                try {
+                    ingressAtSharedMicros = this.#sharedMicros();
+                }
+                catch {
+                    // Preserve callback timing and product traffic without a parse-complete sample.
+                }
+            }
+        }
+        if (frame.type === "clock-probe") {
+            if (!this.#diagnosticCapabilities.includes("clock-bounds-v1") ||
+                frame.requestId !== this.#binding.requestId ||
+                frame.probe !== this.#nextClockProbe)
+                return this.#failProtocol("protocol-error");
+            this.#nextClockProbe += 1;
+            try {
+                ingressAtSharedMicros = this.#sharedMicros();
+            }
+            catch {
+                return;
+            }
+            try {
+                const daemonSendMicros = this.#sharedMicros();
+                this.#sendFrame(null, {
+                    type: "clock-probe-ack",
+                    requestId: this.#binding.requestId,
+                    daemonInstanceId: this.#binding.daemonInstanceId,
+                    probe: frame.probe,
+                    clientSendMicros: frame.clientSendMicros,
+                    daemonReceiveMicros: ingressAtSharedMicros,
+                    daemonSendMicros,
+                });
+            }
+            catch {
+                // Client timeout reports calibration unavailable; product traffic continues.
+            }
+            return;
+        }
+        if (frame.type === "consumed") {
+            this.#acceptConsumed(frame.pane, frame.seq);
+            return;
+        }
+        if (frame.type === "presence") {
+            if (!this.#acceptAuthorityGeneration(frame.generation))
+                return;
+            this.#usesExplicitAuthority = true;
+            if (!this.#sessionRuntimeBinding?.updatePresence)
+                return this.#failProtocol("protocol-error");
+            const snapshot = this.#sessionRuntimeBinding.updatePresence(frame.state);
+            if (!this.#sessionRuntimeBinding.onAuthoritySnapshot)
+                this.#sendAuthoritySnapshot(snapshot);
+            return;
+        }
+        if (frame.type === "activity") {
+            if (!this.#acceptAuthorityGeneration(frame.generation))
+                return;
+            this.#usesExplicitAuthority = true;
+            if (!this.#sessionRuntimeBinding?.noteActivity)
+                return this.#failProtocol("protocol-error");
+            const snapshot = this.#sessionRuntimeBinding.noteActivity(frame.activity);
+            if (!this.#sessionRuntimeBinding.onAuthoritySnapshot)
+                this.#sendAuthoritySnapshot(snapshot);
+            return;
+        }
+        if (frame.type === "authority-request") {
+            if (!this.#acceptAuthorityGeneration(frame.generation))
+                return;
+            this.#usesExplicitAuthority = true;
+            if (!this.#sessionRuntimeBinding?.requestAuthority ||
+                !this.#sessionRuntimeBinding.authoritySnapshot)
+                return this.#failProtocol("protocol-error");
+            const lease = this.#sessionRuntimeBinding.requestAuthority(frame.authority);
+            if (lease)
+                this.#requestedAuthorities.add(frame.authority);
+            this.#sendFrame(null, {
+                type: "authority-receipt",
+                requestId: frame.requestId,
+                authority: frame.authority,
+                status: lease ? "granted" : "rejected",
+                lease,
+                snapshot: this.#sessionRuntimeBinding.authoritySnapshot(),
+            });
+            return;
+        }
+        if (frame.type === "authority-release") {
+            if (!this.#acceptAuthorityGeneration(frame.generation))
+                return;
+            this.#usesExplicitAuthority = true;
+            this.#requestedAuthorities.delete(frame.authority);
+            if (!this.#sessionRuntimeBinding?.releaseAuthority)
+                return this.#failProtocol("protocol-error");
+            const snapshot = this.#sessionRuntimeBinding.releaseAuthority(frame.authority);
+            this.#sendFrame(null, {
+                type: "authority-receipt",
+                requestId: frame.requestId,
+                authority: frame.authority,
+                status: "released",
+                lease: null,
+                snapshot,
+            });
+            return;
+        }
+        if (frame.type === "terminal-delivery-ack") {
+            const channel = this.#deliveryChannel(frame.ack);
+            if (!channel)
+                return;
+            channel.delivery.ack({ ...frame.ack, workspaceName: this.#descriptor.sessionName });
+            return;
+        }
+        if (frame.type === "terminal-delivery-nack") {
+            const channel = this.#deliveryChannel(frame.nack);
+            if (!channel)
+                return;
+            channel.delivery.nack({ ...frame.nack, workspaceName: this.#descriptor.sessionName });
+            return;
+        }
+        if (frame.type === "terminal-delivery-visibility") {
+            const channel = this.#deliveryChannel({
+                workspaceName: frame.workspaceName,
+                semanticPaneId: frame.pane,
+                generation: frame.generation,
+                incarnation: frame.incarnation,
+                deliveryNonce: frame.deliveryNonce,
+            });
+            if (!channel)
+                return;
+            channel.delivery.setVisibility(frame.visibility);
+            return;
+        }
+        if (frame.type === "semantic-intent") {
+            this.#acceptSemanticIntent(frame.operationId, frame.intent);
+            return;
+        }
+        if (frame.type === "viewport") {
+            if (!this.#descriptor.terminalDelivery ||
+                this.#descriptor.viewerMode !== "interactive" ||
+                frame.seq !== this.#nextViewportSeq ||
+                (this.#usesExplicitAuthority && !this.#requestedAuthorities.has("geometry"))) {
+                this.#failProtocol("input-rejected");
+                return;
+            }
+            if (!this.#prepareInputAuthority(true))
+                return;
+            this.#nextViewportSeq += 1;
+            try {
+                this.#sessionRuntimeBinding.fitViewport(frame.authorityLease, frame.cols, frame.rows);
+                this.#sendFrame(null, {
+                    type: "viewport-ack",
+                    seq: frame.seq,
+                    cols: frame.cols,
+                    rows: frame.rows,
+                    outcome: "ok",
+                    authorityLease: frame.authorityLease,
+                });
+            }
+            catch (error) {
+                if (error instanceof SessionRuntimeControllerLeaseError &&
+                    (error.code === "invalid-client-capability" || error.code === "stale-controller-lease")) {
+                    this.#sendFrame(null, {
+                        type: "viewport-ack",
+                        seq: frame.seq,
+                        cols: frame.cols,
+                        rows: frame.rows,
+                        outcome: "geometry-authority-conflict",
+                        authorityLease: frame.authorityLease,
+                    });
+                    return;
+                }
+                this.#failProtocol("input-rejected");
+            }
+            return;
+        }
+        this.#acceptInput(frame.pane, frame.seq, frame.kind, frame.data, byteLength, frame.performanceTraceId, frame.causalProbe, ingressAtMicros, callbackAtSharedMicros, ingressAtSharedMicros);
+    };
+    #acceptAuthorityGeneration(generation) {
+        if (!this.#sessionRuntimeBinding || generation !== this.#sessionRuntimeBinding.generation) {
+            this.#failProtocol("protocol-error");
+            return false;
+        }
+        return true;
+    }
+    #sendAuthoritySnapshot(snapshot) {
+        this.#sendFrame(null, { type: "authority-snapshot", snapshot });
+    }
+    #prepareInputAuthority(geometry) {
+        if (this.#usesExplicitAuthority) {
+            const required = geometry ? "geometry" : "input";
+            if (!this.#requestedAuthorities.has(required)) {
+                this.#failProtocol("input-rejected");
+                return false;
+            }
+            return true;
+        }
+        if (this.#legacyInputActivated && (!geometry || this.#legacyGeometryActivated))
+            return true;
+        try {
+            // A genuine old binding acquired at admission and has no adapter method.
+            // New deferred bindings activate only here, before explicit mode exists.
+            this.#sessionRuntimeBinding?.activateLegacyAuthority?.(geometry);
+            this.#legacyInputActivated = true;
+            if (geometry)
+                this.#legacyGeometryActivated = true;
+            return true;
+        }
+        catch {
+            this.#failProtocol("input-rejected");
+            return false;
+        }
+    }
+    #deliveryChannel(address) {
+        const channel = this.#panes.get(address.semanticPaneId);
+        const expected = channel?.deliveryAddress;
+        if (!channel?.delivery ||
+            !expected ||
+            expected.workspaceName !== address.workspaceName ||
+            expected.generation !== address.generation ||
+            expected.deliveryNonce !== address.deliveryNonce ||
+            expected.incarnation === null) {
+            this.#failProtocol("protocol-error");
+            return null;
+        }
+        // More than one canonical delivery can legitimately be in flight. The
+        // cached address records only the newest incarnation, so comparing an ACK
+        // against that single value rejects an earlier valid delivery during a
+        // reseed/reconnect burst. Generation + one-use delivery nonce identify the
+        // channel here; the retained delivery owner validates incarnation,
+        // transaction and revision ordering authoritatively below.
+        return channel;
+    }
+    #acceptSemanticIntent(operationId, intent) {
+        if (!this.#descriptor.terminalDelivery || this.#descriptor.viewerMode !== "interactive") {
+            this.#failProtocol("input-rejected");
+            return;
+        }
+        if (!this.#prepareInputAuthority(false))
+            return;
+        void this.#sessionRuntimeBinding.submitIntent(operationId, intent)
+            .then((result) => {
+            this.#sendFrame(null, {
+                type: "semantic-intent-ack",
+                operationId,
+                outcome: { status: "applied", result: result ?? null },
+            });
+        })
+            .catch((error) => {
+            const backendRefusal = semanticBackendRefusal(error);
+            const rawCode = backendRefusal ??
+                (error && typeof error === "object" && "code" in error
+                    ? String(error.code)
+                    : error && typeof error === "object" && "outcome" in error
+                        ? `intent-${String(error.outcome)}`
+                        : "stream-unavailable");
+            const code = [
+                "controller-conflict",
+                "controller-target-unavailable",
+                "stale-controller-lease",
+                "invalid-client-capability",
+                "invalid-source-pane-binding",
+                "intent-session-mismatch",
+                "intent-rejected",
+                "intent-timed-out",
+                "pane_inventory_not_ready",
+                "pane_identity_changed_before_select",
+                "pane_not_active",
+            ].includes(rawCode)
+                ? rawCode
+                : "stream-unavailable";
+            this.#sendFrame(null, {
+                type: "semantic-intent-ack",
+                operationId,
+                outcome: {
+                    status: "rejected",
+                    code,
+                    message: error instanceof Error ? error.message.slice(0, 512) : "Semantic intent failed",
+                },
+            });
+        });
+    }
+    #acceptConsumed(pane, seq) {
+        const channel = this.#panes.get(pane);
+        if (!this.#deliveryAcks ||
+            !channel ||
+            seq <= channel.consumedSeq ||
+            seq > channel.sentPaneFrames) {
+            this.#failProtocol("protocol-error");
+            return;
+        }
+        const returned = seq - channel.consumedSeq;
+        channel.consumedSeq = seq;
+        this.#ledger.give(this.#clientId, pane, "renderer-backlog", returned);
+        this.#evaluateResume(pane);
+    }
+    #acceptInput(pane, seq, kind, data, frameBytes, performanceTraceId, causalProbe, ingressAtMicros = null, callbackAtSharedMicros = null, ingressAtSharedMicros = null) {
+        if (this.#descriptor.viewerMode !== "interactive") {
+            this.#failProtocol("input-rejected");
+            return;
+        }
+        const channel = this.#panes.get(pane);
+        const semanticDelivery = this.#descriptor.terminalDelivery !== null;
+        if (!channel ||
+            channel.closed ||
+            (semanticDelivery ? !channel.delivery : !channel.sub) ||
+            seq !== channel.nextInputSeq) {
+            this.#failProtocol("input-rejected");
+            return;
+        }
+        if (causalProbe) {
+            const address = channel.deliveryAddress;
+            if (!this.#causalCellCapability ||
+                !address ||
+                causalProbe.clientId !== this.#sessionRuntimeBinding?.clientId ||
+                causalProbe.transportNonce !== this.#binding.requestId ||
+                causalProbe.deliveryNonce !== address.deliveryNonce ||
+                causalProbe.inputSequence !== seq ||
+                causalProbe.semanticPaneId !== pane ||
+                causalProbe.generation !== address.generation ||
+                causalProbe.incarnation !== address.incarnation) {
+                this.#failProtocol("input-rejected");
+                return;
+            }
+        }
+        const now = this.#now();
+        if (now < this.#inputWindowStartedAt ||
+            now - this.#inputWindowStartedAt >= this.#inputRateWindowMs) {
+            this.#inputWindowStartedAt = now;
+            this.#inputWindowFrames = 0;
+            this.#inputWindowBytes = 0;
+        }
+        if (this.#inputWindowFrames + 1 > this.#maxInputFrames ||
+            this.#inputWindowBytes + frameBytes > this.#maxInputBytes) {
+            this.#failProtocol("input-rejected");
+            return;
+        }
+        if (!this.#prepareInputAuthority(false))
+            return;
+        let trace = null;
+        if (performanceTraceId && this.#observability?.enabled) {
+            try {
+                trace = this.#observability.beginTrace("terminal-input-to-paint", {
+                    generation: this.#sessionRuntimeBinding.generation,
+                    incarnation: causalProbe?.incarnation ?? channel.deliveryAddress?.incarnation ?? null,
+                }, performanceTraceId);
+                if (trace && ingressAtMicros !== null) {
+                    this.#observability.recordSpan("transport", "pane-stream-socket-message-callback-entry", ingressAtMicros, ingressAtMicros, trace, callbackAtSharedMicros === null
+                        ? undefined
+                        : {
+                            startedAtMicros: callbackAtSharedMicros,
+                            endedAtMicros: callbackAtSharedMicros,
+                        });
+                    this.#observability.recordSpan("transport", "pane-stream-input-frame-ingress", ingressAtMicros, ingressAtMicros, trace, ingressAtSharedMicros === null
+                        ? undefined
+                        : { startedAtMicros: ingressAtSharedMicros, endedAtMicros: ingressAtSharedMicros });
+                }
+            }
+            catch {
+                trace = null;
+            }
+        }
+        this.#inputWindowFrames += 1;
+        this.#inputWindowBytes += frameBytes;
+        channel.nextInputSeq += 1;
+        try {
+            this.#sessionRuntimeBinding.assertController(pane);
+            if (semanticDelivery)
+                this.#sessionRuntimeBinding.sendInput(pane, { kind, data }, performanceTraceId, causalProbe, causalProbe
+                    ? (result) => {
+                        if (this.#closed)
+                            return;
+                        if (result.status === "proved") {
+                            this.#sendFrame(null, { type: "causal-cell-proof", proof: result.proof });
+                        }
+                        else {
+                            this.#sendFrame(null, {
+                                type: "causal-cell-failure",
+                                failure: {
+                                    version: 1,
+                                    capability: "causal-cell-v1",
+                                    traceId: result.traceId,
+                                    reason: result.reason,
+                                    ...(result.diagnostic ? { diagnostic: result.diagnostic } : {}),
+                                },
+                            });
+                        }
+                    }
+                    : undefined);
+            else if (kind === "text")
+                channel.sub.sendText(data);
+            else
+                channel.sub.sendKey(data);
+            let ackStartedAtMicros = null;
+            let ackStartedAtSharedMicros = null;
+            if (trace) {
+                try {
+                    ackStartedAtMicros = this.#observability.nowMicros();
+                }
+                catch {
+                    // Diagnostics cannot alter protocol truth.
+                }
+                if (this.#diagnosticSharedRawMicros) {
+                    try {
+                        ackStartedAtSharedMicros = this.#sharedMicros();
+                    }
+                    catch {
+                        // Preserve process-local ACK diagnostics.
+                    }
+                }
+            }
+            sendControl(this.#socket, { type: "input-ack", pane, seq });
+            if (trace && ackStartedAtMicros !== null) {
+                let ackEndedAtMicros = null;
+                try {
+                    ackEndedAtMicros = this.#observability.nowMicros();
+                }
+                catch {
+                    // Diagnostics cannot alter protocol truth.
+                }
+                let ackEndedAtSharedMicros = null;
+                if (ackStartedAtSharedMicros !== null) {
+                    try {
+                        ackEndedAtSharedMicros = this.#sharedMicros();
+                    }
+                    catch {
+                        // Preserve process-local ACK diagnostics.
+                    }
+                }
+                if (ackEndedAtMicros !== null) {
+                    try {
+                        this.#observability.recordSpan("transport", "pane-stream-input-ack-socket-send", ackStartedAtMicros, ackEndedAtMicros, trace, ackStartedAtSharedMicros === null || ackEndedAtSharedMicros === null
+                            ? undefined
+                            : {
+                                startedAtMicros: ackStartedAtSharedMicros,
+                                endedAtMicros: ackEndedAtSharedMicros,
+                            });
+                    }
+                    catch {
+                        // Diagnostics cannot alter protocol truth.
+                    }
+                }
+            }
+        }
+        catch {
+            this.close(1011, "stream-unavailable");
+        }
+    }
+    #failProtocol(code) {
+        try {
+            sendControl(this.#socket, {
+                type: "error",
+                protocolVersion: PANE_STREAM_PROTOCOL_VERSION,
+                code,
+                retryable: false,
+            });
+        }
+        catch {
+            this.close(1011, "stream-unavailable");
+            return;
+        }
+        this.close(1008, code);
+    }
+    #closeIfAllPanesGone() {
+        if (this.#closed)
+            return;
+        for (const channel of this.#panes.values()) {
+            if (!channel.closed)
+                return;
+        }
+        this.close(1000, "panes-closed");
+    }
+    #onSocketClose = () => this.close(1000, "peer-closed");
+}
+function concatBytes(chunks) {
+    if (chunks.length === 0)
+        return new Uint8Array(0);
+    if (chunks.length === 1)
+        return chunks[0];
+    let total = 0;
+    for (const chunk of chunks)
+        total += chunk.byteLength;
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return merged;
+}
+function chunkBytes(data, maxChunk) {
+    if (data.byteLength === 0)
+        return [];
+    if (data.byteLength <= maxChunk)
+        return [data];
+    const chunks = [];
+    for (let offset = 0; offset < data.byteLength; offset += maxChunk) {
+        chunks.push(data.subarray(offset, Math.min(offset + maxChunk, data.byteLength)));
+    }
+    return chunks;
+}