@cplieger/web-terminal-engine 2.7.0 → 3.0.0

package/src/connection.ts

@@ -6,9 +6,12 @@
 // backoff, and the resume/inputAck reliability layer.
 //
 // Protocol (resume / inputAck):
-//   - Client maintains a `sessionId` (UUID) for the page lifetime, an
-//     `outbox` of input bytes sent but not yet acknowledged, and a
-//     `bytesSent` counter.
+//   - Client maintains a resume key for the page lifetime, an `outbox` of
+//     input bytes sent but not yet acknowledged, and a `bytesSent` counter.
+//     Unmanaged mode: a per-tab UUID. Managed mode: `<serverSessionId>#<per-
+//     client instance id>`, so every device/tab attached to one session owns
+//     its OWN server-side input ledger (see resumeKey — shared ledgers acked
+//     other devices' bytes to this one and corrupted its outbox).
 //   - On WS open, client sends control: {type:"resume", sessionId, sentBytes}.
 //   - Server replies with {type:"resumeAck", received:M}; subsequent
 //     screen/scroll messages also carry inputAck = bytesReceived. Client
@@ -24,16 +27,39 @@
 import { wsURL } from "./wsurl.js";
 import { WS_PATH } from "./routes.js";
 import { controlFrame } from "./wire.js";
-import { decodeWireBinary, WIRE_PROTOCOL_VERSION } from "./wire-binary.js";
+import { decodeWireBinary } from "./wire-binary.js";
+import {
+  MIN_SUPPORTED_SERVER_WIRE_VERSION,
+  WIRE_INCOMPATIBLE_CLOSE_CODE,
+  WIRE_PROTOCOL_VERSION,
+  type WireIncompatibility,
+} from "./wire-compatibility.js";
 import * as modes from "./modes.js";
 import type { ControlMessage, ServerMessage } from "./types.js";
 import { INITIAL_DELAY_MS, nextBackoffDelay } from "./reconnect.js";
 
+/**
+ * First wire revision with typed client→server framing (text = control,
+ * binary = full-alphabet input). A resumeAck whose serverWireVersion is at
+ * least this triggers the per-socket upgrade (design §4 phase 3). Mirrors
+ * typedFramingMinVersion in the Go terminal package.
+ */
+const TYPED_FRAMING_MIN_VERSION = 4;
+
 type ConnState =
   | { status: "disconnected" }
   | { status: "connecting"; sock: WebSocket; abort: AbortController }
-  | { status: "connected"; sock: WebSocket; abort: AbortController }
-  | { status: "reconnecting"; timer: ReturnType<typeof setTimeout>; delayMs: number };
+  /**
+   * `upgraded` is the v4 typed-framing latch for THIS socket (per-socket by
+   * construction: the state object is replaced on every transition, so it can
+   * never leak across a reconnect). false = v3 mode: controls go as
+   * 0x00-sentinel binary frames and input is leading-NUL-split. true = the
+   * resumeAck proved a v4 server and the text `upgrade` transition was sent:
+   * controls go as text frames and input is raw full-alphabet binary.
+   */
+  | { status: "connected"; sock: WebSocket; abort: AbortController; upgraded: boolean }
+  | { status: "reconnecting"; timer: ReturnType<typeof setTimeout>; delayMs: number }
+  | { status: "incompatible" };
 
 // The server's application close code for "the session's child process has
 // exited" (terminal/terminal.go statusProcessExited). It marks a close as
@@ -42,6 +68,15 @@ type ConnState =
 // application range (4000-4999) per RFC 6455.
 const PROCESS_EXITED_CLOSE_CODE = 4001;
 
+// The server's application close code for "the manager does not know this
+// session id" (terminal/terminal.go statusUnknownSession): reaped, closed
+// elsewhere, or a restarted server. The server ACCEPTS the upgrade and closes
+// with this code precisely so the client can read it (a pre-upgrade 404 is an
+// opaque 1006 in browser JS). Like 4001 it is definitive — the session will
+// never produce output — so it routes to the same no-reconnect ended path
+// instead of an endless "Reconnecting…" flap.
+const SESSION_UNKNOWN_CLOSE_CODE = 4004;
+
 let connState: ConnState = { status: "disconnected" };
 let reconnectDelay = INITIAL_DELAY_MS;
 let lastSentCols = 0;
@@ -57,12 +92,18 @@ let wsPath: string = WS_PATH;
 // bytes onto it and without firing a false server-restart reset, because each
 // session's epoch is compared only against its own bootEpoch (design section 8).
 interface ResumeState {
-  id: string; // server session id: both the routing id (?session=) and the resume id
+  id: string; // server session id: the routing id (?session=); resumeKey derives the ledger key
   bytesSent: number; // total bytes ever passed to sendBinary for this session
   bytesAcked: number; // confirmed by server inputAck/resumeAck
   outbox: Uint8Array[]; // unacked chunks (sum of lengths = bytesSent - bytesAcked)
   outboxBytes: number; // running sum of outbox chunk lengths; keeps applyAck O(n) not O(n²)
   lastServerEpoch: number | null; // process-start nanos last seen for this session
+  /** The session's last-announced DEC-mode state (P3: per-session mode
+   *  mirror). Written on every inbound modes frame; restored synchronously
+   *  into the modes singleton by setSession, so a keystroke in the switch
+   *  window encodes under THIS session's modes, never the previous tab's.
+   *  Power-on defaults until the session announces modes. */
+  modes: modes.ModeSnapshot;
 }
 
 const sessions = new Map<string, ResumeState>();
@@ -81,8 +122,44 @@ let managed = false;
 
 const SESSION_ID_KEY = "vterm-session-id";
 
+// --- Per-client-instance resume key (P1: per-sender input-ack scoping) ---
+//
+// In managed mode the routing id (?session=) is SHARED by every device/tab
+// attached to that session, but the server-side input ledger (bytesReceived,
+// keyed by the resume frame's sessionId) must be PER SENDER: with a shared
+// key, device B's input advances the one ledger and the server acks that
+// total to device A, whose applyAck then trims bytes the server never
+// received from A — silent input loss on A's next resume (the cross-device
+// outbox corruption class). So the resume frame carries
+// `<serverSessionId>#<clientInstanceId>` — the URL keeps the bare routing id
+// (the server routes on it), while the registry keys A's and B's ledgers
+// separately. The unmanaged path already has per-sender semantics (its
+// sessionStorage id is per tab) and is unchanged.
+//
+// The instance id is crypto-random and page-lifetime (NOT persisted): a
+// reload is a fresh sender whose ledger starts at zero, which matches its
+// empty outbox. Lazy so a cryptoless environment throws on first CONNECT
+// (as before), not at module import.
+let clientInstanceId: string | null = null;
+
+function resumeKey(st: ResumeState): string {
+  if (!managed) {
+    return st.id;
+  }
+  clientInstanceId ??= generateSessionId();
+  return `${st.id}#${clientInstanceId}`;
+}
+
 function newResumeState(id: string): ResumeState {
-  return { id, bytesSent: 0, bytesAcked: 0, outbox: [], outboxBytes: 0, lastServerEpoch: null };
+  return {
+    id,
+    bytesSent: 0,
+    bytesAcked: 0,
+    outbox: [],
+    outboxBytes: 0,
+    lastServerEpoch: null,
+    modes: { ...modes.POWER_ON_MODES },
+  };
 }
 
 function ensureState(id: string): ResumeState {
@@ -187,17 +264,19 @@ export interface Callbacks {
   onClose(): void;
   onConnecting?(): void;
   onOutboxFull?(): void;
-  /** Fired instead of onClose when the server closes with the
-   *  process-exited application close code (4001): the session's child
-   *  process has ended, so the close is DEFINITIVE, not a transient drop.
-   *  When this callback is wired, the module does NOT auto-reconnect that
-   *  socket — reconnecting a dead session just replays its final screen and
-   *  earns another 4001 (the endless "Reconnecting…" flash) — and does not
-   *  call onClose for it. The consumer decides what "ended" looks like
-   *  (banner, tab state) and may still reconnect explicitly (setSession /
-   *  reconnectNow) to re-view the final screen. When absent, every close
-   *  keeps the legacy transient treatment (onClose + backoff reconnect), so
-   *  existing consumers are unaffected until they opt in. */
+  /** Fired instead of onClose when the server closes with a DEFINITIVE
+   *  application close code — process-exited (4001: the session's child
+   *  process has ended) or unknown-session (4004: the server does not know
+   *  the id at all — reaped, closed elsewhere, or a restarted server). In
+   *  both cases the session will never produce output again, so a transient
+   *  treatment could only earn the same close code forever (the endless
+   *  "Reconnecting…" flash). When this callback is wired, the module does
+   *  NOT auto-reconnect that socket and does not call onClose for it. The
+   *  consumer decides what "ended" looks like (banner, tab state) and may
+   *  still reconnect explicitly (setSession / reconnectNow) to re-view a
+   *  dead session's final screen. When absent, every close keeps the legacy
+   *  transient treatment (onClose + backoff reconnect), so existing
+   *  consumers are unaffected until they opt in. */
   onProcessExit?(): void;
   /** Fired when the server's boot-epoch in resumeAck differs from the
    *  one observed on a previous connection — i.e. the server has
@@ -206,6 +285,19 @@ export interface Callbacks {
    *  starts from zero. UI should clear scrollback and surface a
    *  banner so the user knows old input may have been lost. */
   onServerRestart?(): void;
+  /** Fired when a resumeAck carries an explicit server revision outside
+   *  [MIN_SUPPORTED_SERVER_WIRE_VERSION, WIRE_PROTOCOL_VERSION]. A newer
+   *  server warns but continues because it may retain this client's baseline.
+   *  A below-floor server also fires onWireIncompatible and stops the socket.
+   *  Version-silent servers never fire either callback. */
+  onWireVersionMismatch?(server: number, client: number): void;
+  /** Fired when the module definitively stops a socket for an incompatible
+   *  declared wire revision, either from resumeAck metadata or close code
+   *  4002. Automatic and wake-triggered reconnects remain blocked until an
+   *  explicit disconnect clears the terminal state (normally a page reload).
+   *  The callback is optional; refusal is enforced even when no UI consumes
+   *  it. */
+  onWireIncompatible?(details: WireIncompatibility): void;
   computeSize(): { cols: number; rows: number };
   /** Returns the highest absolute line index the client currently holds, or
    *  -1 if it holds nothing. Sent as `haveThrough` on resume so the server
@@ -237,6 +329,13 @@ export function init(callbacks: Callbacks): void {
  * if the outbox is full (caller should surface a UI signal that input
  * was dropped). Always copies the input to defend against caller-side
  * buffer reuse.
+ *
+ * Input alphabet: any byte sequence is deliverable, including leading NULs.
+ * On a v4-upgraded socket the bytes go out verbatim in one binary message;
+ * on a v3-mode socket each leading 0x00 is emitted as its own solitary
+ * 1-byte frame (see sendInputFrames) so nothing this module sends can be
+ * misread as a control frame — byte order and count are preserved either
+ * way, and servers with the parse-fallback deliver every byte to the PTY.
  */
 export function sendBinary(data: Uint8Array): boolean {
   const st = activeState();
@@ -252,15 +351,54 @@ export function sendBinary(data: Uint8Array): boolean {
   st.outboxBytes += copy.length;
   st.bytesSent += copy.length;
   if (connState.status === "connected") {
-    connState.sock.send(copy.buffer.slice(copy.byteOffset, copy.byteOffset + copy.byteLength));
+    sendInputFrames(connState.sock, connState.upgraded, copy);
   }
   return true;
 }
 
+/**
+ * sendInputFrames is the ONE encoder for PTY input bytes — both the live
+ * sendBinary path and retransmitOutbox route through it so the two can never
+ * disagree on framing (design §6). On a v4-upgraded socket the bytes go out
+ * verbatim as a single binary message (full alphabet — the server never
+ * inspects a sentinel after the latch). On a v3-mode socket (old server, or
+ * the pre-upgrade window of any socket), each leading 0x00 byte is emitted as
+ * its own solitary 1-byte message so no frame the client sends can ever be
+ * misread as a control frame; servers with the parse-fallback deliver the
+ * solitary NUL to the PTY, and byte accounting is unchanged either way
+ * (splitting alters message count, never byte count or order).
+ */
+function sendInputFrames(sock: WebSocket, upgraded: boolean, chunk: Uint8Array): void {
+  let rest = chunk;
+  if (!upgraded) {
+    while (rest.length > 0 && rest[0] === 0x00) {
+      sock.send(new Uint8Array([0x00]).buffer);
+      rest = rest.subarray(1);
+    }
+  }
+  if (rest.length > 0) {
+    sock.send(rest.buffer.slice(rest.byteOffset, rest.byteOffset + rest.byteLength) as ArrayBuffer);
+  }
+}
+
+/**
+ * textControl encodes a control message for a v4-upgraded socket: bare JSON in
+ * a WebSocket TEXT frame (the transport's message type is the discriminator;
+ * no sentinel byte). The binary 0x00-sentinel form (controlFrame) remains the
+ * bootstrap/fallback encoding for v3-mode sockets.
+ */
+function textControl(msg: ControlMessage): string {
+  return JSON.stringify(msg);
+}
+
 function sendControl(msg: ControlMessage): void {
   if (connState.status !== "connected") {
     return;
   }
+  if (connState.upgraded) {
+    connState.sock.send(textControl(msg));
+    return;
+  }
   connState.sock.send(controlFrame(msg));
 }
 
@@ -316,12 +454,12 @@ function applyAck(st: ResumeState, received: number): void {
 
 // On reconnect, after sending the resume control message and getting resumeAck,
 // replay anything still in the session's outbox over its (now open) socket. The
-// server has adjusted bytesAcked already — only unacked bytes remain.
-function retransmitOutbox(sock: WebSocket, st: ResumeState): void {
+// server has adjusted bytesAcked already — only unacked bytes remain. Routed
+// through sendInputFrames so replay framing always matches live-send framing
+// (v3-mode leading-NUL split vs v4 verbatim — design §6).
+function retransmitOutbox(sock: WebSocket, upgraded: boolean, st: ResumeState): void {
   for (const chunk of st.outbox) {
-    sock.send(
-      chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength) as ArrayBuffer,
-    );
+    sendInputFrames(sock, upgraded, chunk);
   }
 }
 
@@ -420,6 +558,9 @@ function teardown(): void {
 }
 
 export function reconnectNow(): void {
+  if (connState.status === "incompatible") {
+    return;
+  }
   // Unconditional teardown. On iOS wake (visibilitychange + pageshow), the
   // socket frequently reads OPEN/"connected" for a while but is actually a
   // zombie — the OS froze it during sleep and frames printed meanwhile never
@@ -445,11 +586,19 @@ export function reconnectNow(): void {
  */
 export function setSession(id: string): void {
   managed = true;
-  ensureState(id);
+  const target = ensureState(id);
   if (id === activeId && (connState.status === "connected" || connState.status === "connecting")) {
     return; // already serving this session
   }
   activeId = id;
+  // Restore the target session's DEC-mode mirror SYNCHRONOUSLY (P3): a
+  // keystroke fired in the switch window — after this call returns, before
+  // the new session's modes frame arrives — must encode under the target's
+  // last-known modes (power-on defaults for a session never seen), never
+  // under the previous tab's. The kernel already disarms every other latched
+  // input class on switch (composition, sticky-Ctrl); this was the one it
+  // could not reach.
+  modes.applySnapshot(target.modes);
   reconnectNow();
 }
 
@@ -476,6 +625,9 @@ export function disconnect(): void {
 }
 
 export function connect(): void {
+  if (connState.status === "incompatible") {
+    return;
+  }
   // Guard against double-call: a stray invocation while a previous
   // socket is still CONNECTING/OPEN would orphan it (its handlers
   // remain bound but the new sock assignment makes it unreachable).
@@ -555,19 +707,18 @@ export function connect(): void {
     "open",
     () => {
       clearTimeout(timeoutId);
-      connState = { status: "connected", sock, abort: connectAbort };
-      reconnectDelay = INITIAL_DELAY_MS;
-      lastSentCols = 0;
-      lastSentRows = 0;
-      cb?.onOpen();
-
-      // Send resume immediately so server can respond with its current
-      // bytesReceived for this session — we trim/retransmit the outbox
-      // when that resumeAck arrives (handled in the message listener).
+      // Bootstrap resume FIRST, on the captured socket, before consumer
+      // callbacks can run: it must be message one on every socket (the v4
+      // negotiation bootstrap, design §4 — always binary-sentinel encoded,
+      // understood by every server revision). An onOpen callback that calls
+      // sendResize()/sendBinary() therefore always queues AFTER it.
       sock.send(
         controlFrame({
           type: "resume",
-          sessionId: st.id,
+          // Managed mode: the per-sender resume key (routing id + "#" +
+          // instance id), so each device/tab owns its server-side input
+          // ledger. Unmanaged: the per-tab sessionStorage id as-is.
+          sessionId: resumeKey(st),
           sentBytes: st.bytesSent,
           // Highest absolute line index the client holds (-1 if none). The
           // server replays everything after it, so lines printed while the
@@ -578,10 +729,18 @@ export function connect(): void {
           haveThrough: cb?.getHaveThrough?.() ?? -1,
           // Lets the server detect a client built against a different wire
           // revision (e.g. a stale cached bundle) and warn rather than
-          // silently mis-decode.
+          // silently mis-decode; >= 4 also ARMS the connection for the
+          // typed-framing upgrade (design §4 phase 1).
           protocolVersion: WIRE_PROTOCOL_VERSION,
         }),
       );
+      // Every socket starts in v3 mode; the resumeAck's serverWireVersion
+      // decides whether the typed-framing upgrade happens (design §4).
+      connState = { status: "connected", sock, abort: connectAbort, upgraded: false };
+      reconnectDelay = INITIAL_DELAY_MS;
+      lastSentCols = 0;
+      lastSentRows = 0;
+      cb?.onOpen();
 
       // Begin client-side liveness probing for this socket. Idempotent
       // (clears any prior timer) and resets the activity clock to now.
@@ -621,6 +780,19 @@ export function connect(): void {
         blobChain = blobChain
           .then(() => blob.arrayBuffer())
           .then((ab) => {
+            // Stale-socket guard (design §4, review F2): the async
+            // blob.arrayBuffer() hop can outlive this socket — teardown
+            // aborts the listeners, but a conversion already queued still
+            // resolves. A frame from a superseded socket must not reach
+            // handleDecoded, where its resumeAck could upgrade/reset/
+            // retransmit against the REPLACEMENT socket's server.
+            if (
+              connectAbort.signal.aborted ||
+              connState.status !== "connected" ||
+              connState.sock !== sock
+            ) {
+              return;
+            }
             handleDecoded(decodeWireBinary(ab));
           })
           .catch((err: unknown) => {
@@ -635,13 +807,10 @@ export function connect(): void {
           });
         return;
       }
-      if (typeof ev.data === "string") {
-        try {
-          handleDecoded(JSON.parse(ev.data) as ServerMessage);
-        } catch {
-          // ignore malformed text frames
-        }
-      }
+      // Text frames from the server are undefined in the protocol (the server
+      // sends only binary frames; wire v4 made text a CLIENT->server control
+      // channel). The old dormant JSON.parse branch that accepted them as
+      // unvalidated ServerMessages was removed 2026-07 (judgement finding).
     },
     { signal: connectAbort.signal },
   );
@@ -651,6 +820,63 @@ export function connect(): void {
       return;
     }
     if (msg.type === "resumeAck") {
+      // An explicit below-floor revision is definitive: this decoder cannot
+      // safely consume that server's frames. Stop the socket before invoking
+      // consumer callbacks, latch the no-reconnect state, and require an
+      // explicit disconnect/page reload before another attempt. A missing
+      // tail remains the version-silent compatibility path.
+      if (
+        msg.serverWireVersion !== undefined &&
+        msg.serverWireVersion < MIN_SUPPORTED_SERVER_WIRE_VERSION
+      ) {
+        const reason = `server wire protocol ${msg.serverWireVersion} is below client minimum ${MIN_SUPPORTED_SERVER_WIRE_VERSION}; upgrade the server`;
+        console.warn("vterm: refusing incompatible server wire protocol", reason);
+        stopHeartbeat();
+        connState = { status: "incompatible" };
+        try {
+          sock.close(WIRE_INCOMPATIBLE_CLOSE_CODE, reason);
+        } finally {
+          connectAbort.abort();
+        }
+        cb?.onWireVersionMismatch?.(msg.serverWireVersion, WIRE_PROTOCOL_VERSION);
+        cb?.onWireIncompatible?.({
+          source: "server-version",
+          serverVersion: msg.serverWireVersion,
+          clientVersion: WIRE_PROTOCOL_VERSION,
+          minimumServerVersion: MIN_SUPPORTED_SERVER_WIRE_VERSION,
+          reason,
+        });
+        return;
+      }
+      // Higher revisions may retain this client's compatible baseline. Keep
+      // the socket running and surface the skew as a warning only.
+      if (msg.serverWireVersion !== undefined && msg.serverWireVersion > WIRE_PROTOCOL_VERSION) {
+        console.warn(
+          "vterm: server wire-protocol version is newer than client",
+          "server",
+          msg.serverWireVersion,
+          "client",
+          WIRE_PROTOCOL_VERSION,
+          "- upgrade the client if terminal behavior is incorrect",
+        );
+        cb?.onWireVersionMismatch?.(msg.serverWireVersion, WIRE_PROTOCOL_VERSION);
+      }
+      // Typed-framing upgrade (design §4 phase 3): on proof of a v4+ server,
+      // send the text transition FIRST — WebSocket ordering then guarantees
+      // the server latches before any unsplit binary input that follows —
+      // and only then flip the socket's mode. This must precede the
+      // ledger-lost/ack/retransmit handling below so the retransmit already
+      // uses the upgraded framing.
+      if (
+        msg.serverWireVersion !== undefined &&
+        msg.serverWireVersion >= TYPED_FRAMING_MIN_VERSION &&
+        connState.status === "connected" &&
+        connState.sock === sock &&
+        !connState.upgraded
+      ) {
+        sock.send(textControl({ type: "upgrade" }));
+        connState.upgraded = true;
+      }
       // Server-restart detection. The first resumeAck we see records
       // the epoch; subsequent ones compare to it. A mismatch means the
       // server's process has restarted, which invalidates our local
@@ -665,41 +891,71 @@ export function connect(): void {
       }
       // Resync guard 8.2.2: hand the server's retained-history bounds to the
       // consumer so it can surface a trim marker when history the client was
-      // missing is gone for good. (If the session-forgotten path below resets
-      // state, a fresh server's oldest=0 simply reads as "no trim".)
+      // missing is gone for good. (If the ledger-lost / session-forgotten
+      // paths below reset state, a fresh server's oldest=0 simply reads as
+      // "no trim".)
       if (typeof msg.committed === "number" && typeof msg.oldestIndex === "number") {
         cb?.onResumeBounds?.(msg.committed, msg.oldestIndex);
       }
-      // Server-doesn't-recognize-this-session safeguard: if the server
-      // returns received=0 but the client already had bytesAcked > 0,
-      // the server has forgotten our session (idle GC kicked in, or
-      // sessionId persistence failed and a reload created a new one).
-      // Replaying the outbox would deliver every queued chunk again,
-      // causing the iOS tab-suspend duplicate-resend bug. Drop the
-      // outbox and notify the UI as if the server restarted — input
-      // since the last successful ack is irrecoverable but at least
-      // not duplicated. Skip this branch when bytesSent = 0 (genuine
-      // first-connect; received=0 is correct).
+      // Explicit ledger-loss signal (servers with the >= 35-byte resumeAck
+      // tail): the resume key missed the server's registry while we claimed
+      // sent bytes — our ledger was reclaimed (idle GC / cap eviction). The
+      // server cannot vouch for ANY previously sent input, so replaying the
+      // outbox risks duplicate execution. Deterministic drop-and-notify,
+      // covering the bytesAcked === 0 case the heuristic below cannot see
+      // (acks that never reached us before the disconnect).
+      if (msg.ledgerLost) {
+        resetSessionAfterRestart(st);
+        return;
+      }
+      // Server-doesn't-recognize-this-session safeguard (old-server
+      // fallback, pre-ledgerLost tail): if the server returns received=0
+      // but the client already had bytesAcked > 0, the server has forgotten
+      // our session (idle GC kicked in, or sessionId persistence failed and
+      // a reload created a new one). Replaying the outbox would deliver
+      // every queued chunk again, causing the iOS tab-suspend
+      // duplicate-resend bug. Drop the outbox and notify the UI as if the
+      // server restarted — input since the last successful ack is
+      // irrecoverable but at least not duplicated. Skip this branch when
+      // bytesSent = 0 (genuine first-connect; received=0 is correct).
       if (msg.received === 0 && st.bytesAcked > 0) {
         resetSessionAfterRestart(st);
         return;
       }
       applyAck(st, msg.received);
-      retransmitOutbox(sock, st);
+      retransmitOutbox(
+        sock,
+        connState.status === "connected" && connState.sock === sock && connState.upgraded,
+        st,
+      );
+      return;
+    }
+    if (msg.type === "ackOnly") {
+      // Bare ack from the flush tick's sweep: input was applied but no
+      // content frame carried the new count (silent app — e.g. `read -s`).
+      // Trim the outbox and stop; transport-internal, never forwarded to
+      // onMessage.
+      applyAck(st, msg.inputAck);
       return;
     }
     if (msg.type === "modes") {
-      modes.setModes(
-        msg.bracketedPaste,
-        msg.applicationCursor,
-        msg.mouseSGR,
-        msg.focusReporting,
-        msg.mouseMode,
-        msg.applicationKeypad,
-        msg.reverseVideo,
-        msg.mousePixels,
-        msg.keyboardFlags,
-      );
+      // Single mirror writer (P3): cache the snapshot on the session this
+      // socket serves AND apply it to the active-session singleton. The two
+      // targets are the same session by construction — a superseded socket's
+      // listeners are aborted, so only the active session's socket delivers.
+      const snap: modes.ModeSnapshot = {
+        bracketedPaste: msg.bracketedPaste,
+        applicationCursor: msg.applicationCursor,
+        mouseSGR: msg.mouseSGR,
+        focusReporting: msg.focusReporting,
+        mouseMode: msg.mouseMode,
+        applicationKeypad: msg.applicationKeypad,
+        reverseVideo: msg.reverseVideo,
+        mousePixels: msg.mousePixels,
+        keyboardFlags: msg.keyboardFlags,
+      };
+      st.modes = snap;
+      modes.applySnapshot(snap);
       if (typeof msg.inputAck === "number") {
         applyAck(st, msg.inputAck);
       }
@@ -728,14 +984,33 @@ export function connect(): void {
         return;
       }
       stopHeartbeat();
+      if (ev.code === WIRE_INCOMPATIBLE_CLOSE_CODE) {
+        const reason =
+          ev.reason ||
+          "server rejected this client wire protocol; reload or upgrade the client/server";
+        connState = { status: "incompatible" };
+        cb?.onWireIncompatible?.({
+          source: "server-close",
+          clientVersion: WIRE_PROTOCOL_VERSION,
+          minimumServerVersion: MIN_SUPPORTED_SERVER_WIRE_VERSION,
+          reason,
+        });
+        return;
+      }
       connState = { status: "disconnected" };
       // A process-exited close (4001) is definitive: the child is gone, so a
       // backoff reconnect can only replay the final screen and collect another
       // 4001 — an endless, pointless churn that reads as a flapping
-      // "Reconnecting…" banner. Route it to onProcessExit (no reconnect, no
-      // onClose) when the consumer wired it; without the callback, keep the
-      // legacy transient treatment so existing consumers see no change.
-      if (ev.code === PROCESS_EXITED_CLOSE_CODE && cb?.onProcessExit) {
+      // "Reconnecting…" banner. An unknown-session close (4004) is equally
+      // definitive: the server does not know the id at all (reaped, closed
+      // elsewhere, restarted server), so reconnecting can only collect another
+      // 4004. Route both to onProcessExit (no reconnect, no onClose) when the
+      // consumer wired it; without the callback, keep the legacy transient
+      // treatment so existing consumers see no change.
+      if (
+        (ev.code === PROCESS_EXITED_CLOSE_CODE || ev.code === SESSION_UNKNOWN_CLOSE_CODE) &&
+        cb?.onProcessExit
+      ) {
         cb.onProcessExit();
         return;
       }

package/src/index.ts

@@ -3,16 +3,25 @@ export { LineStore } from "./store.js";
 export type { WindowState, StoreChanges } from "./store.js";
 export * as render from "./render.js";
 export * as keyboard from "./keyboard.js";
+export * as toolbar from "./toolbar.js";
 export * as scroll from "./scroll.js";
 export * as modes from "./modes.js";
 export * as mouse from "./mouse.js";
 export * as connection from "./connection.js";
 export { decodeWireBinary } from "./wire-binary.js";
+export {
+  MIN_SUPPORTED_SERVER_WIRE_VERSION,
+  WIRE_COMPATIBILITY,
+  WIRE_INCOMPATIBLE_CLOSE_CODE,
+  WIRE_PROTOCOL_VERSION,
+} from "./wire-compatibility.js";
+export type { WireIncompatibility } from "./wire-compatibility.js";
 export { controlFrame, CONTROL_FRAME_PREFIX } from "./wire.js";
 export { wsURL } from "./wsurl.js";
 export { WS_PATH, SESSIONS_PATH, SESSION_EVENTS_PATH } from "./routes.js";
 export { connectStatusStream } from "./status-stream.js";
 export type {
+  SessionInfo,
   SessionStatus,
   StatusStream,
   StatusStreamCallbacks,