cc-viewer 1.9.4 → 1.9.5

package/server/lib/v2/live-feed.js

@@ -27,6 +27,7 @@ import { join } from 'node:path';
 import { reportSwallowed } from '@ccv/core/error-report';
 import { createIncrementalReconstructor } from '@ccv/core/delta-reconstructor';
 import { processWatchedEntry, sendEventToClients, sendEventRawToClients } from '../log-watcher.js';
+import { filterClientsByInstance } from './view-router.js';
 import { SessionSynthesizer } from './adapter.js';
 import { isDiscardableSession } from './session-select.js';
 import { isForeignLiveOwned } from './session-owner.js';
@@ -214,14 +215,14 @@ export class V2LiveFeed {
    * Backward compatible: a client with NO `_ccvViewInstance` stamp (the default / legacy /
    * single-instance view) sees every session regardless of `sessionInstance`; a session with
    * no stamped instance (legacy/external) is likewise visible to all.
+   *
+   * The project half keeps going through `_clientsFor()` (the server's filter
+   * closure — not necessarily the pure predicate); only the instance narrowing
+   * is delegated to the shared rule (view-router.filterClientsByInstance) so it
+   * can never drift from the server-side scoped broadcasts.
    */
   _clientsForInstance(sessionInstance) {
-    const base = this._clientsFor();
-    if (!sessionInstance) return base; // session carries no instance → visible to all viewers
-    let anyInstanceViewer = false;
-    for (const c of base) { if (c && c._ccvViewInstance) { anyInstanceViewer = true; break; } }
-    if (!anyInstanceViewer) return base; // nobody is instance-scoped → keep legacy broadcast
-    return base.filter((c) => !c || !c._ccvViewInstance || c._ccvViewInstance === sessionInstance);
+    return filterClientsByInstance(this._clientsFor(), sessionInstance || null);
   }
 
   /** Begin (or switch to) live-following a project's sessions/ root. */

package/server/lib/v2/view-router.js

@@ -38,6 +38,54 @@ export function filterClientsByViewProject(clientList, project, boundProject) {
   return clientList.filter((c) => c && ((c._ccvViewProject || bound) === project));
 }
 
+/**
+ * Instance-narrowed variant of filterClientsByViewProject (multi-instance,
+ * 2026-10-06 rule lifted from live-feed._clientsForInstance): a frame stamped
+ * with an instance is visible to every viewer of the project EXCEPT clients
+ * stamped with a DIFFERENT instance. Unset on either side ⇒ visible (a client
+ * with no `_ccvViewInstance` stamp sees every instance; a frame with no
+ * instance reaches all of the project's viewers).
+ *
+ * @param {Array} clientList - SSE response objects.
+ * @param {string} project - the frame's project ('' ⇒ bound).
+ * @param {string|null} instance - the frame's instance, when known.
+ * @param {string} boundProject - the server's bound project.
+ * @returns {Array} the subset of clients that should receive the frame.
+ */
+export function filterClientsByScope(clientList, project, instance, boundProject) {
+  // Composition over duplication: project half, then the shared instance rule —
+  // the two can never drift apart.
+  return filterClientsByInstance(filterClientsByViewProject(clientList, project, boundProject), instance);
+}
+
+/**
+ * Instance-only narrowing over an ALREADY project-filtered client list — the
+ * live-feed composes its own project filter (`opts.clientFilter`, which may be
+ * a server-supplied closure rather than the pure predicate) with this rule.
+ * Same semantics as the instance half of filterClientsByScope: unset on either
+ * side ⇒ visible; nobody instance-stamped ⇒ the input array (same reference).
+ *
+ * @param {Array} clientList - already project-filtered SSE responses.
+ * @param {string|null} instance - the frame's instance, when known.
+ * @returns {Array}
+ */
+export function filterClientsByInstance(clientList, instance) {
+  if (!instance) return clientList;
+  // Exclude ONLY clients explicitly stamped with a DIFFERENT instance. An
+  // UNSTAMPED (project-level) viewer of the same project must also receive the
+  // frame: if an earlier `active:true` frame reached it while no instance viewer
+  // was online, the matching `active:false` must reach it too or its spinner
+  // never clears (the clear would be narrowed away the moment a parallel
+  // instance chip connects). Keeping active/clear on the SAME recipient set
+  // avoids that split delivery.
+  // Fast path: nobody is excluded (no differently-stamped client) ⇒ return the
+  // SAME array reference (no filter alloc), preserving legacy identity.
+  let anyExcluded = false;
+  for (const c of clientList) { if (c && c._ccvViewInstance && c._ccvViewInstance !== instance) { anyExcluded = true; break; } }
+  if (!anyExcluded) return clientList;
+  return clientList.filter((c) => !c || !c._ccvViewInstance || c._ccvViewInstance === instance);
+}
+
 /**
  * Extract the owning project dir name from a session dir path of the form
  * `<LOG_DIR>/<projectSan>/sessions/<dirName>`. Returns the on-disk `<projectSan>`

package/server/lib/workflow-watcher.js

@@ -39,7 +39,7 @@ function _signature(p) {
 function _isJournalFile(f) { return f.startsWith('wf_') && f.endsWith('.json'); }
 
 function _scan(state) {
-  const { workflowsDir, sessionId, project, clients, seen } = state;
+  const { workflowsDir, sessionId, project, clients, clientFilter, seen } = state;
   let files;
   try { files = readdirSync(workflowsDir); } catch { return; }
   for (const f of files) {
@@ -51,7 +51,11 @@ function _scan(state) {
     seen.set(f, sig);
     const data = readNormalizedJournal(p);
     if (!data) continue;
-    sendEventToClients(clients, 'workflow_update', {
+    // Per-workspace: a journal belongs to one project; when a client filter is
+    // installed the frame reaches only that project's viewers (legacy default:
+    // broadcast to all).
+    const target = typeof clientFilter === 'function' ? clientFilter(clients, project) : clients;
+    sendEventToClients(target, 'workflow_update', {
       sessionId,
       project: project || null,
       runId: data.runId,
@@ -99,7 +103,7 @@ function _baseline(state) {
  * 武装对某 workflows 目录的监视。同目录重复调用只刷新 clients 引用。
  * @param {{ workflowsDir: string, sessionId?: string, project?: string, clients: Array }} opts
  */
-export function armWorkflowWatch({ workflowsDir, sessionId, project, clients } = {}) {
+export function armWorkflowWatch({ workflowsDir, sessionId, project, clients, clientFilter } = {}) {
   if (!workflowsDir || !Array.isArray(clients)) return null;
 
   const existing = _armed.get(workflowsDir);
@@ -107,6 +111,7 @@ export function armWorkflowWatch({ workflowsDir, sessionId, project, clients } =
 
   const state = {
     workflowsDir, sessionId, project, clients,
+    clientFilter: typeof clientFilter === 'function' ? clientFilter : null,
     seen: new Map(), watcher: null,
     debounceTimer: null, safetyTimer: null, presenceTimer: null,
   };
@@ -177,13 +182,14 @@ function _authoritativeJournalExists(runDir, runId) {
 }
 
 function _scanLive(state) {
-  const { runDir, runId, sessionId, project, clients } = state;
+  const { runDir, runId, sessionId, project, clients, clientFilter } = state;
   const data = deriveLiveJournal(runDir, runId);
   if (data) {
     const sig = _liveSignature(data);
     if (sig !== state.lastSig) {  // 有实质变化才广播
       state.lastSig = sig;
-      sendEventToClients(clients, 'workflow_update', {
+      const target = typeof clientFilter === 'function' ? clientFilter(clients, project) : clients;
+      sendEventToClients(target, 'workflow_update', {
         sessionId,
         project: project || null,
         runId: data.runId,
@@ -228,7 +234,7 @@ function _startLiveWatch(state) {
  * 同 runDir 重复调用只刷新 clients。arm 时立即广播一次当前推导态（闭合 REST/arm 竞态）。
  * @param {{ runDir: string, runId: string, sessionId?: string, project?: string, clients: Array }} opts
  */
-export function armWorkflowLiveWatch({ runDir, runId, sessionId, project, clients } = {}) {
+export function armWorkflowLiveWatch({ runDir, runId, sessionId, project, clients, clientFilter } = {}) {
   if (!runDir || !runId || !Array.isArray(clients)) return null;
 
   const existing = _armedLive.get(runDir);
@@ -236,6 +242,7 @@ export function armWorkflowLiveWatch({ runDir, runId, sessionId, project, client
 
   const state = {
     runDir, runId, sessionId, project, clients,
+    clientFilter: typeof clientFilter === 'function' ? clientFilter : null,
     lastSig: null, watcher: null,
     debounceTimer: null, safetyTimer: null, presenceTimer: null,
   };

package/server/lib/ws-mux.js

@@ -0,0 +1,473 @@
+/**
+ * WebSocket stream mux for the dialogue channel (`/ws/mux`).
+ *
+ * Carries N logical /events streams over ONE shared WebSocket, so the browser's
+ * HTTP/1.1 ~6-connections-per-origin ceiling (which pins SSE to maxChannels=3)
+ * no longer bounds how many workspaces stream live concurrently. The SSE path
+ * is kept intact as the automatic fallback: when the mux cannot serve (no
+ * route, handshake refused, capability absent) the client reopens the SAME
+ * scope URL over a native EventSource with its since/cc cursor — no data loss.
+ *
+ * Frame protocol (text JSON, graphql-ws style envelope):
+ *   c→s  { type:'open', streamId, qs }        qs = the RAW ?query string a native
+ *                                             EventSource URL would carry (passthrough;
+ *                                             we never re-derive scope field-by-field,
+ *                                             so `?limit` absence≠0 and sid/instance
+ *                                             regexes stay byte-identical to /events)
+ *   c→s  { type:'close', streamId }
+ *   c→s  { type:'pong', ts }
+ *   s→c  { type:'open-ack', streamId, epoch, seq }   ack precedes every frame of the stream
+ *   s→c  { type:'frame', streamId, seq, name, data } name:null ⇔ bare `data:`; data is the
+ *                                                    verbatim JSON string (never re-stringified)
+ *   s→c  { type:'error', streamId, code, message }   per-stream; terminates only that stream
+ *   s→c  { type:'ping', ts }                  25s app-level keepalive (browsers cannot send
+ *                                             WS control-frame pings, so liveness is app-level)
+ *
+ * Reliability: a stream's lifetime == its socket's lifetime (mirrors SSE: one
+ * EventSource ⇔ one connection, reconnect = new connection + since/cc). There is
+ * NO server-side frame replay across sockets; resume semantics live entirely in
+ * the existing since/cc cursor. seq is per-stream monotonic, epoch is per-process;
+ * the client dedups on the per-stream seq alone (streamId is re-minted on every reconnect, so a
+ * replayed frame from a prior incarnation can never collide); epoch is diagnostic only.
+ *
+ * The KEY design move is the sink shim: each logical stream masquerades as an SSE
+ * `res` inside the shared `clients` array, so the broadcast hot path
+ * (log-watcher's send*ToClients / _safeSseWrite / filterClientsByScope) needs ZERO
+ * changes. The shim is a real EventEmitter because `awaitWireDrain`/`_safeSseWrite`
+ * use on/once/off('drain'|'close'|'error') on it.
+ *
+ * Pure logic: no `ws` module dependency (the WebSocketServer class is injected) and no
+ * routes/ dependency (serveStream is injected by server.js), so this stays L1 and
+ * unit-testable with fakes — same house style as lib/ws-backpressure.js.
+ */
+import { randomBytes } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { reportSwallowed as defaultReport } from '@ccv/core/error-report';
+import { createBackpressureGate } from './ws-backpressure.js';
+
+const STREAM_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const HEARTBEAT_SEND_MS = 25_000;   // app-level ping cadence (chisel: proxies kill idle conns)
+const HEARTBEAT_REAP_MS = 60_000;   // no inbound frame for this long → terminate the socket
+const MAX_STREAMS_PER_SOCKET = 8;
+// Per-socket queue is a pure MEMORY SAFETY NET (the primary slow-consumer eviction is the
+// per-stream 30s backpressure rule inherited from _safeSseWrite). Sized well above any
+// legitimate burst so it only trips on a wedged socket, never on a fast-producer burst.
+const QUEUE_MAX_BYTES = 8 * 1024 * 1024;
+const HIGH_WATER = 1024 * 1024;     // mirrors terminal's hysteresis band
+const LOW_WATER = 256 * 1024;
+
+/** Per-stream application error codes (WS close-code range, graphql-ws 44xx semantics). */
+export const MUX_CODES = {
+  BAD_REQUEST: 4400,        // open frame failed validation
+  DUPLICATE_STREAM: 4409,   // streamId already live on this socket
+  TOO_MANY_STREAMS: 4429,   // socket stream cap reached
+  SCOPE_UNAVAILABLE: 4503,  // this scope cannot be served over mux → client falls back (this stream only)
+};
+
+export function encodeFrame(obj) {
+  return JSON.stringify(obj);
+}
+
+/** Parse one inbound text frame. Returns null on anything that is not a {type:string} object. */
+export function decodeFrame(raw) {
+  try {
+    const o = JSON.parse(typeof raw === 'string' ? raw : String(raw));
+    return (o && typeof o === 'object' && typeof o.type === 'string') ? o : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse ONE complete SSE frame body (no trailing blank line) into {name, data}.
+ * Implements the SSE field rules rather than assuming a single data line: strip one
+ * leading space after the colon, join multiple `data:` lines with '\n', drop unknown
+ * field lines. `name` is null for a bare `data:` frame. Returns null when there is no
+ * data field at all (a frame this codebase never legitimately emits).
+ *
+ * NOTE: only the two shapes this codebase emits are exercised in production —
+ * `data: <json>` and `event: <name>\ndata: <json>` (JSON.stringify escapes newlines,
+ * so data is always single-line). The multi-line tolerance is forward defense; an
+ * unexpected non-data/event field line is reported as a protocol-drift signal.
+ */
+export function parseSseFrame(body, report = defaultReport) {
+  const lines = body.split('\n');
+  let name = null;
+  const dataLines = [];
+  for (const line of lines) {
+    if (line.startsWith('data:')) {
+      dataLines.push(line.startsWith('data: ') ? line.slice(6) : line.slice(5));
+    } else if (line.startsWith('event:')) {
+      name = line.startsWith('event: ') ? line.slice(7) : line.slice(6);
+    } else if (line === '' || line.startsWith(':')) {
+      // blank / comment line — ignore
+    } else {
+      report('ws.mux.parse', new Error('unexpected SSE field line'), { line: line.slice(0, 16) });
+    }
+  }
+  if (dataLines.length === 0) return null;
+  return { name, data: dataLines.join('\n') };
+}
+
+/**
+ * Validate an inbound `open` frame. Returns { ok:true, streamId, qs } or
+ * { ok:false, code, message }. qs is passed through verbatim (only shape-checked to be
+ * a string without a leading '?'); the scope/since/cc/limit semantics are re-parsed by
+ * the SAME paramsFromParsedUrl the SSE route uses, so the two transports never drift.
+ */
+export function validateOpenParams(msg) {
+  const streamId = msg.streamId;
+  if (typeof streamId !== 'string' || !STREAM_ID_RE.test(streamId)) {
+    return { ok: false, code: MUX_CODES.BAD_REQUEST, message: 'invalid streamId' };
+  }
+  const qs = msg.qs;
+  if (qs !== null && qs !== undefined && (typeof qs !== 'string' || qs.startsWith('?') || qs.length > 4096)) {
+    return { ok: false, code: MUX_CODES.BAD_REQUEST, message: 'invalid qs' };
+  }
+  return { ok: true, streamId, qs: qs || '' };
+}
+
+/**
+ * The sink shim: one logical stream presented to the broadcast hot path as an SSE `res`.
+ * A REAL EventEmitter because _safeSseWrite / awaitWireDrain attach on/once/off('drain'|
+ * 'close'|'error') to it; a hand-rolled once() would TypeError inside awaitWireDrain and
+ * (with no unhandledRejection backstop in the dispatcher) kill the process.
+ */
+class MuxSink extends EventEmitter {
+  constructor(st, streamId) {
+    super();
+    this.streamId = streamId;
+    this._st = st;
+    // The registrable IS the shim itself (it is the object pushed into deps.clients, so the
+    // per-stream _ccvView* stamps land on it — never on the shared socket).
+    this.registrable = this;
+    // SSE-res surface the hot path reads (see log-watcher._safeSseWrite / wire-compress):
+    this.destroyed = false;      // flipped only when THIS stream ends (never by socket congestion)
+    this.writable = true;
+    this._wireEnc = undefined;   // MUST stay falsy: sseWrite/awaitWireDrain branch on it
+    this._sseBackpressureSince = 0;
+    this._ccvViewProject = undefined;   // stamped by the serve core at push time (per-stream)
+    this._ccvViewInstance = undefined;
+    this.writableNeedDrain = false;
+    this._buf = '';              // cross-call SSE byte reassembly buffer
+    this._seq = 0;               // per-stream monotonic frame sequence
+    this._drainWaiters = [];
+    // EventEmitter throws on an unlistened 'error'; the shim only ever reports transport
+    // death via 'close', but keep a noop so a stray emit('error') can never crash the process.
+    this.on('error', () => {});
+    // The serve core registers its dispose hook here at entry.
+    this.once('close', () => { this._disposed?.(); });
+  }
+
+  /** serve core entry hook: register the dispose callback (idempotent by the core). */
+  onClose(fn) { this._disposed = fn; }
+
+  alive() { return !this.destroyed && !this._st.closed; }
+  needsDrain() { return this._st.behind(); }
+
+  /** Mirrors wire-compress.awaitWireDrain: resolve on drain / close / 30s timeout. The SAME
+   *  `done` reference is registered and removed (the previous version off()'d a different
+   *  identity, leaking one stale listener per backpressure wait → MaxListenersExceededWarning). */
+  awaitDrain() {
+    return new Promise((resolve) => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(t);
+        this.off('drain', done);
+        this.off('close', done);
+        resolve();
+      };
+      const t = setTimeout(done, 30000);
+      this.once('drain', done);
+      this.once('close', done);
+    });
+  }
+
+  /**
+   * Opaque byte-append (the serve core splits one load_chunk across 3 write() calls).
+   * Reassembles complete SSE frames across calls and forwards each as a {type:'frame'}.
+   * Returns false to signal per-stream backpressure (frames are QUEUED, never dropped) —
+   * the same threshold semantics _safeSseWrite applies to an SSE res. Never throws.
+   */
+  write(text) {
+    if (this.destroyed) return false;
+    this._buf += text;
+    let start = 0;
+    let idx;
+    let ok = true;
+    while ((idx = this._buf.indexOf('\n\n', start)) !== -1) {
+      const body = this._buf.slice(start, idx);
+      start = idx + 2;
+      const parsed = parseSseFrame(body, this._st.report);
+      if (!parsed) continue;
+      this._seq += 1;
+      if (!this._st.send({ type: 'frame', streamId: this.streamId, seq: this._seq, name: parsed.name, data: parsed.data })) {
+        ok = false;
+      }
+    }
+    if (start > 0) this._buf = this._buf.slice(start);
+    this.writableNeedDrain = this._st.behind();
+    return ok;
+  }
+
+  /**
+   * End THIS logical stream only — never the socket (one socket carries N streams; a single
+   * slow stream's 30s eviction must not take its siblings down, unlike SSE where end() closed
+   * exactly one EventSource). Emits 'close' asynchronously to mirror Node res semantics (so a
+   * `for (const c of clients) c.end()` loop does not skip siblings mid-iteration).
+   */
+  end() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.writable = false;
+    this.writableNeedDrain = false;
+    queueMicrotask(() => {
+      this.emit('close');
+      this._st.closeStream(this.streamId, 'sink-end');
+    });
+  }
+}
+
+export function createStreamMuxServer({
+  WebSocketServer,
+  serveStream,
+  reportSwallowed = defaultReport,
+  epoch = randomBytes(6).toString('hex'),
+  setInterval: setI = setInterval,
+  clearInterval: clearI = clearInterval,
+  setTimeout: setT = setTimeout,
+  clearTimeout: clearT = clearTimeout,
+  now = Date.now,
+} = {}) {
+  // perMessageDeflate: the dialogue channel carries the app's largest transfers (cold-load
+  // windows); without it the mux would send verbatim JSON where the SSE path gets per-connection
+  // brotli (measured 21-88x on real sessions). ws's built-in permessage-deflate (zlib) recovers
+  // most of that with no new dependency. (SSE keeps its stronger brotli; this closes the gap.)
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024, perMessageDeflate: true });
+  const sockets = new Set();
+  wss.on('error', (err) => reportSwallowed('ws.mux.server', err));
+  wss.on('connection', (ws) => handleConnection(ws));
+
+  function handleConnection(ws) {
+    const st = {
+      ws,
+      streams: new Map(),          // streamId -> { sink, handle, disposed }
+      lastInboundAt: now(),
+      closed: false,
+      queue: [],                   // FIFO of encoded frames held while behind
+      queuedBytes: 0,
+      _behind: false,
+      gate: null,
+      pingTimer: null,
+      flushTimer: null,
+      report: reportSwallowed,
+      send: null, behind: null, closeStream: null,
+    };
+    sockets.add(st);
+
+    // Drain the queue as a BOUNDED trickle, not a single-tick flood: after each frame, re-check
+    // bufferedAmount and stop the moment it climbs back over highWater (a slow consumer's socket
+    // buffer would otherwise spike to many times the high-water mark in one resume tick). The
+    // trickle self-reschedules (the gate's poll stops once it fires onResume, so we can't rely on
+    // it to drive the next trickle); teardown clears the timer.
+    const flushQueue = () => {
+      if (st.flushTimer) { clearT(st.flushTimer); st.flushTimer = null; }
+      while (st.queue.length && !st.closed && st.ws.readyState === 1) {
+        if ((st.ws.bufferedAmount || 0) > HIGH_WATER) {
+          st._behind = true;
+          st.flushTimer = setT(flushQueue, 100);
+          st.flushTimer.unref?.();
+          return;
+        }
+        const text = st.queue[0];
+        try { st.ws.send(text); } catch (err) {
+          reportSwallowed('ws.mux.send', err);
+          closeSocket(st, 1011, 'send-failed');
+          return;
+        }
+        st.queue.shift();
+        st.queuedBytes -= text.length;
+      }
+    };
+    const fireAllDrain = () => {
+      for (const rec of st.streams.values()) rec.sink.emit('drain');
+    };
+    st.gate = createBackpressureGate({
+      getBufferedAmount: () => st.ws.bufferedAmount || 0,
+      onResume: () => { st._behind = false; flushQueue(); fireAllDrain(); },
+      onBehind: () => { st._behind = true; },
+      onTimeout: () => {
+        reportSwallowed('ws.mux.backpressure', new Error('timeout'));
+        closeSocket(st, 1011, 'backpressure-timeout');
+      },
+      highWater: HIGH_WATER,
+      lowWater: LOW_WATER,
+      timeoutMs: 30000,
+    });
+    st.behind = () => st._behind || st.queuedBytes > 0;
+
+    // Send-or-enqueue. NEVER drops: while behind, frames accumulate in the bounded queue
+    // (order preserved). A wedged client dies by the 30s gate timeout / queue cap, then the
+    // client reconnects and resumes via its since/cc cursor. The gate's offer() return is
+    // ONLY a signal (its native contract is "skip this send" — the terminal path compensates
+    // with data-resync; mux must NOT skip, so we ignore the return for the send decision).
+    st.send = (msg) => {
+      if (st.closed || st.ws.readyState !== 1) return false;
+      const text = encodeFrame(msg);
+      st.gate.offer();                       // signal only; result deliberately unused
+      if (st._behind) {
+        if (st.queuedBytes + text.length > QUEUE_MAX_BYTES) {
+          closeSocket(st, 1011, 'queue-overflow');
+          return false;
+        }
+        st.queue.push(text);
+        st.queuedBytes += text.length;
+        return false;
+      }
+      try { st.ws.send(text); } catch (err) {
+        reportSwallowed('ws.mux.send', err);
+        closeSocket(st, 1011, 'send-failed');
+        return false;
+      }
+      return true;
+    };
+
+    st.closeStream = (streamId, reason) => {
+      const rec = st.streams.get(streamId);
+      if (!rec || rec.disposed) return;
+      rec.disposed = true;
+      st.streams.delete(streamId);
+      // Wake any in-flight sink.awaitDrain() waiters (SSE's awaitWireDrain wakes on res
+      // 'close'; a mux stream must too, or a serve coroutine hangs the full 30s timeout).
+      // end() is the idempotent public path that emits 'close' + notifies us back (guarded
+      // by rec.disposed above, so the re-entry is a no-op).
+      try { rec.sink.end(); } catch (err) { reportSwallowed('ws.mux.dispose', err); }
+      try { rec.handle?.dispose?.(); } catch (err) { reportSwallowed('ws.mux.dispose', err); }
+      // Make a server-initiated stream close VISIBLE to the client (a SSE res.end() makes the
+      // browser EventSource error+reconnect; a silent mux close would leave the facade OPEN and
+      // the channel frozen until its heartbeat). Only when the socket is up and the close did
+      // not originate from the client's own close frame.
+      if (reason !== 'client-close' && reason !== 'socket-close' && reason !== 'server-stopping' && !st.closed) {
+        st.send({ type: 'close', streamId });
+      }
+    };
+
+    st.pingTimer = setI(() => {
+      if (st.closed) return;
+      if (now() - st.lastInboundAt > HEARTBEAT_REAP_MS) {
+        closeSocket(st, 1001, 'heartbeat-reap');
+        return;
+      }
+      st.send({ type: 'ping', ts: now() });
+    }, HEARTBEAT_SEND_MS);
+    st.pingTimer.unref?.();
+
+    ws.on('message', (raw) => { st.lastInboundAt = now(); onMessage(st, raw); });
+    ws.on('close', () => teardown(st, 'socket-close'));
+    ws.on('error', (err) => { reportSwallowed('ws.mux.socket', err); teardown(st, 'socket-error'); });
+  }
+
+  function onMessage(st, raw) {
+    const msg = decodeFrame(raw);
+    if (!msg) {
+      st.send({ type: 'error', streamId: null, code: MUX_CODES.BAD_REQUEST, message: 'malformed frame' });
+      return;
+    }
+    if (msg.type === 'pong') return;
+    if (msg.type === 'ping') { st.send({ type: 'pong', ts: now() }); return; }
+    if (msg.type === 'close') {
+      st.closeStream(msg.streamId, 'client-close');   // unknown id: ignore (graphql-ws)
+      return;
+    }
+    if (msg.type === 'open') onOpen(st, msg);
+  }
+
+  function onOpen(st, msg) {
+    const v = validateOpenParams(msg);
+    if (!v.ok) {
+      st.send({ type: 'error', streamId: typeof msg.streamId === 'string' ? msg.streamId : null, code: v.code, message: v.message });
+      return;
+    }
+    if (st.streams.has(v.streamId)) {
+      st.send({ type: 'error', streamId: v.streamId, code: MUX_CODES.DUPLICATE_STREAM, message: 'duplicate streamId' });
+      return;
+    }
+    if (st.streams.size >= MAX_STREAMS_PER_SOCKET) {
+      st.send({ type: 'error', streamId: v.streamId, code: MUX_CODES.TOO_MANY_STREAMS, message: 'too many streams' });
+      return;
+    }
+    const sink = new MuxSink(st, v.streamId);
+    const rec = { sink, handle: null, disposed: false };
+    st.streams.set(v.streamId, rec);
+    sink.on('close', () => st.closeStream(v.streamId, 'sink-close'));
+    // ack precedes every frame of this stream (history frames included).
+    st.send({ type: 'open-ack', streamId: v.streamId, epoch, seq: 0 });
+    let handleP;
+    try {
+      handleP = serveStream(sink, v.qs);
+    } catch (err) {
+      reportSwallowed('ws.mux.serve', err);
+      st.send({ type: 'error', streamId: v.streamId, code: MUX_CODES.SCOPE_UNAVAILABLE, message: 'serve failed' });
+      st.closeStream(v.streamId, 'serve-throw');
+      return;
+    }
+    // serveStream may return a handle synchronously or a Promise of one (the SSE serve core
+    // resolves after the history push). Capture a sync (non-thenable) handle IMMEDIATELY so a
+    // close arriving in the same tick still disposes it; a Promise handle lands in the microtask.
+    if (handleP && typeof handleP.then !== 'function') {
+      rec.handle = handleP;
+      if (rec.disposed) { try { handleP?.dispose?.(); } catch (err) { reportSwallowed('ws.mux.dispose', err); } }
+    } else {
+      Promise.resolve(handleP).then((resolved) => {
+        rec.handle = resolved;
+        if (rec.disposed) {                        // socket/stream died while history was streaming
+          try { resolved?.dispose?.(); } catch (err) { reportSwallowed('ws.mux.dispose', err); }
+        }
+      }).catch((err) => {
+        reportSwallowed('ws.mux.serve', err);
+        st.send({ type: 'error', streamId: v.streamId, code: MUX_CODES.SCOPE_UNAVAILABLE, message: 'serve failed' });
+        st.closeStream(v.streamId, 'serve-failed');
+      });
+    }
+  }
+
+  function closeSocket(st, code, reason) {
+    if (st.closed) return;
+    for (const streamId of [...st.streams.keys()]) st.closeStream(streamId, 'socket-close');
+    try { st.ws.close(code, reason); } catch { /* already gone */ }
+    teardown(st, reason);
+  }
+
+  function teardown(st, _reason) {
+    if (st.closed) return;
+    st.closed = true;
+    for (const streamId of [...st.streams.keys()]) st.closeStream(streamId, _reason);
+    try { st.gate.dispose(); } catch { /* best-effort */ }
+    if (st.pingTimer) { clearI(st.pingTimer); st.pingTimer = null; }
+    if (st.flushTimer) { clearT(st.flushTimer); st.flushTimer = null; }
+    sockets.delete(st);
+  }
+
+  return {
+    handleUpgrade(req, socket, head) {
+      try {
+        wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+      } catch (err) {
+        reportSwallowed('ws.mux.upgrade', err);
+        try { socket.destroy(); } catch { /* raced */ }
+      }
+    },
+    /** Terminate every socket (server.close() does NOT reach upgraded sockets) + close wss. */
+    close() {
+      for (const st of [...sockets]) {
+        try { closeSocket(st, 1001, 'server-stopping'); } catch { /* best-effort */ }
+        try { st.ws.terminate?.(); } catch { /* already gone */ }
+      }
+      try { wss.close(); } catch { /* stop/start cycles */ }
+    },
+    _sockets: sockets,
+    _server: wss,
+  };
+}