@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/session-channel.js

@@ -0,0 +1,1756 @@
+/**
+ * OSS live channel — live session plane over WebSocket.
+ *
+ * The live channel is where the typed-channel contract is enforced on
+ * live traffic between the server and the user. It co-hosts on the
+ * same Express server as `/mcp` and reuses the same
+ * `@ggui-ai/mcp-server-handlers/session-mutations` helpers that the
+ * closed hosted server consumes.
+ *
+ * Scope:
+ *
+ *   - `subscribe` → auth, resolve-or-create session, register subscriber,
+ *     reply `ack` with the session's current stack + sequence.
+ *   - `action` → inbound user action carried as an {@link ActionEnvelope}.
+ *     Gated through `assertEventAllowed` (allowlist) +
+ *     `assertActionContract` (payload, for data:submit). Persisted to
+ *     SessionStore as a typed session event.
+ *   - `ping`/`pong` → heartbeat parity with hosted.
+ *   - `close`/socket-close → clean subscriber teardown.
+ *   - `sendToSession(sessionId, data)` → outbound fan-out API for
+ *     mutation handlers (ggui_emit / connector `ctx.send`). Validated
+ *     through `assertStreamContract` before delivery.
+ *
+ * `props_update`: mount handlers dispatched through the wired-action
+ * router can call `ctx.sendPropsUpdate(stackItemId, props)` to fan a
+ * `{type:'props_update'}` frame to live subscribers without going
+ * through a refresh-stream path. Reaches the renderer's existing
+ * `props_update` branch in `iframe-runtime` and applies new props
+ * in-place. This seam is scoped to mount tools; the agent-driven
+ * `ggui_update` path is handled separately.
+ *
+ * Not handled here:
+ *
+ *   - Pattern-B daemon-agent notification stream (GET /mcp SSE).
+ *   - Short-lived session-token mint/consume — that's ggui_push-gated.
+ *     Dev-mode auth (any bearer via existing AuthAdapter) matches the
+ *     `/mcp` endpoint's shape and is operator-replaceable.
+ */
+import { randomUUID } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { CONTRACT_ERROR_CHANNEL, ContractViolationError, EMPTY_REFRESH_INPUT, PROTOCOL_SCHEMA_VERSION, UPGRADE_REQUIRED, makeContractErrorPayload, sanitizeCausedBy as defaultSanitizeCausedBy, } from '@ggui-ai/protocol';
+import { InMemorySessionStreamBuffer, InProcessStreamFanout, NoopTelemetrySink, } from '@ggui-ai/mcp-server-core/in-memory';
+import { assertActionContract, assertEventAllowed, assertStreamContract, EventNotAllowedError, } from '@ggui-ai/mcp-server-handlers/session-mutations';
+import { resolveIdentityFromHeaders, UnauthenticatedError, } from './auth.js';
+/** Default URL path for the channel endpoint. Operators can override. */
+export const DEFAULT_SESSION_CHANNEL_PATH = '/ws';
+/**
+ * Default + boundary cadence for the channel-subscribe polling loop.
+ * Server-authoritative: clients propose `pollIntervalMs` on
+ * `channel_subscribe`, server clamps to [floorMs, ceilingMs] and
+ * defaults to `defaultMs` when absent. Conservative defaults — operators
+ * tune via {@link SessionChannelLocalToolsOptions.pollCadence}.
+ */
+const DEFAULT_CHANNEL_POLL_FLOOR_MS = 1_000;
+const DEFAULT_CHANNEL_POLL_CEILING_MS = 60_000;
+const DEFAULT_CHANNEL_POLL_DEFAULT_MS = 10_000;
+/**
+ * Default timeout for a single wired-tool invocation, in ms. Operators
+ * override via {@link SessionChannelOptions.wiredActionTimeoutMs}; the
+ * 30 s ceiling is a honest non-promise: long-running tools MUST design
+ * their own completion path (streaming, polling).
+ */
+export const DEFAULT_WIRED_TOOL_TIMEOUT_MS = 30_000;
+/**
+ * Raised by `invokeWithTimeout` when a wired-tool call exceeds its
+ * per-call budget. Internal — surfaces as a `TOOL_TIMEOUT` code on
+ * {@link ContractErrorPayload} before the caller sees any channel
+ * output.
+ */
+class WiredToolTimeoutError extends Error {
+    toolName;
+    timeoutMs;
+    constructor(toolName, timeoutMs) {
+        super(`Wired tool '${toolName}' did not complete within ${timeoutMs}ms`);
+        this.name = 'WiredToolTimeoutError';
+        this.toolName = toolName;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Build an OSS live-channel server. The returned object is designed to be
+ * composed into `createGguiServer` — see `server.ts` for the wire-up.
+ */
+export function createSessionChannelServer(opts) {
+    const path = opts.path ?? DEFAULT_SESSION_CHANNEL_PATH;
+    // Outbound stream buffer — owns seq assignment + bounded replay
+    // storage. Default is in-memory; operators swap via `opts.streamBuffer`.
+    const streamBuffer = opts.streamBuffer ?? new InMemorySessionStreamBuffer();
+    // Live-tail pub/sub. Default in-process; hosted binds RedisPubSubFanout.
+    const streamFanout = opts.streamFanout ?? new InProcessStreamFanout();
+    // `causedBy` sanitizer applied to every contract-error emission.
+    // Defaults to the protocol's pattern-based redactor (Bearer tokens,
+    // query-param secrets, env-var dumps, 2 KB truncation). Operators
+    // pass their own to tighten or broaden coverage.
+    const sanitize = opts.sanitizeCausedBy ?? defaultSanitizeCausedBy;
+    // Operational telemetry — default no-op. Fires `wired-tool.invoked`
+    // on every successful wired-action dispatch (C12); future sites
+    // (refresh-stream success / failure counts) reuse the same sink.
+    const telemetry = opts.telemetry ?? new NoopTelemetrySink();
+    // Channel-subscribe local-tool poll plumbing. Resolved once
+    // at composition so the `channel_subscribe` handler doesn't pay the
+    // option-spread cost per request. Absent ⇒ all channel subscribes
+    // reject with `CHANNEL_NOT_LOCAL`.
+    const localTools = opts.streamWebSocketLocalTools;
+    const localToolsAllowlist = localTools
+        ? new Set(localTools.allowlist)
+        : new Set();
+    const pollFloorMs = localTools?.pollCadence?.floorMs ?? DEFAULT_CHANNEL_POLL_FLOOR_MS;
+    const pollCeilingMs = localTools?.pollCadence?.ceilingMs ?? DEFAULT_CHANNEL_POLL_CEILING_MS;
+    const pollDefaultMs = localTools?.pollCadence?.defaultMs ?? DEFAULT_CHANNEL_POLL_DEFAULT_MS;
+    // `noServer: true` means we own the upgrade wiring (see handleUpgrade);
+    // ws won't try to bind its own port.
+    const wss = new WebSocketServer({ noServer: true });
+    /**
+     * Flat set of all live WS subscribers. Replaces the per-session
+     * `subscribersBySession` Map — routing is now StreamFanout's job;
+     * this set tracks WS-specific bookkeeping (stats, shutdown-broadcast)
+     * that the seam can't see (and shouldn't).
+     */
+    const wsSubscribers = new Set();
+    /** ws → subscriber reverse index so socket-close can look up cheaply. */
+    const subscribersByWs = new WeakMap();
+    /**
+     * Pump live frames from the StreamFanout iterator out to this
+     * subscriber's WS. Started fire-and-forget by `register`; ends when
+     * the iterator yields done (close() on the seam) OR `unregister`
+     * calls `iter.return()`. Per-subscriber seq filter applied here:
+     * frames with `seq <= replayCompletedSeq` were (or will be)
+     * delivered via the replay path on subscribe.
+     *
+     * The pump's first action is `await iter.next()`, which yields
+     * control back to the event loop. This is what preserves the
+     * subscribe-handler ordering invariant: ack → replay frames →
+     * live frames. The replay-frame send loop completes synchronously
+     * before the pump can ever send anything, regardless of fanout
+     * timing.
+     */
+    async function pumpSubscriber(sub) {
+        try {
+            for (;;) {
+                const { value, done } = await sub.iter.next();
+                if (done)
+                    return;
+                if (value.seq <= sub.replayCompletedSeq)
+                    continue;
+                if (sub.ws.readyState !== sub.ws.OPEN) {
+                    await sub.iter.return?.();
+                    return;
+                }
+                send(sub.ws, { type: 'data', payload: value });
+            }
+        }
+        catch (err) {
+            opts.logger.warn('session_channel_pump_failed', {
+                sessionId: sub.sessionId,
+                error: String(err),
+            });
+        }
+    }
+    function register(sub) {
+        wsSubscribers.add(sub);
+        subscribersByWs.set(sub.ws, sub);
+        // Start the pump loop. Fire-and-forget — pump errors are logged
+        // inside pumpSubscriber, never propagated.
+        void pumpSubscriber(sub);
+    }
+    function unregister(ws) {
+        const sub = subscribersByWs.get(ws);
+        if (!sub)
+            return;
+        subscribersByWs.delete(ws);
+        wsSubscribers.delete(sub);
+        // Ending the iter terminates pumpSubscriber AND unregisters this
+        // subscriber from the StreamFanout. Idempotent on the seam side
+        // (close-after-return is a no-op).
+        void sub.iter.return?.();
+        // Tear down every `channel_subscribe` polling loop owned
+        // by this subscriber. Symmetric with stream-iterator teardown
+        // above. clearInterval is idempotent on already-cleared handles,
+        // so a concurrent channel_unsubscribe + WS close is safe.
+        for (const state of sub.channelSubs.values()) {
+            clearInterval(state.timer);
+        }
+        sub.channelSubs.clear();
+    }
+    function send(ws, msg) {
+        if (ws.readyState !== ws.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify(msg));
+        }
+        catch (err) {
+            opts.logger.warn('session_channel_send_failed', { error: String(err) });
+        }
+    }
+    function sendError(ws, code, message, requestId, details) {
+        send(ws, {
+            type: 'error',
+            payload: { code, message, ...(details !== undefined ? { details } : {}) },
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    /**
+     * Shared tenancy guard for client-emitted observation messages
+     * (`host_context_observed`, `canvas_navigated`). Returns `false`
+     * AND emits the appropriate error frame when:
+     *
+     *   - the socket has no bound subscriber (NOT_SUBSCRIBED)
+     *   - payload.sessionId doesn't match the subscriber binding
+     *     (SESSION_MISMATCH)
+     *
+     * Subscriber binding is the authoritative tenancy scope. The wire
+     * payload's sessionId is belt-and-suspenders so the error message
+     * can be specific; appId narrows transparently via the binding.
+     */
+    function checkSubscriberTenancy(ws, sub, payload, messageType, requestId) {
+        if (!sub) {
+            sendError(ws, 'NOT_SUBSCRIBED', `Send a 'subscribe' message first before '${messageType}'`, requestId);
+            return false;
+        }
+        if (payload.sessionId !== sub.sessionId) {
+            sendError(ws, 'SESSION_MISMATCH', `${messageType} payload sessionId '${payload.sessionId}' does not match subscriber session '${sub.sessionId}'`, requestId);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Persist an observation-message-driven session patch. Fire-and-
+     * forget at the wire layer (no response frame); warn-logs persistence
+     * errors so transient store failures stay observable without
+     * disrupting the iframe. The iframe's local state is already in the
+     * new shape; the next round-trip re-emits whatever the persistence
+     * layer lost.
+     */
+    async function applySessionPatch(sessionId, appId, messageType, patch) {
+        try {
+            await opts.sessionStore.update(sessionId, patch);
+        }
+        catch (err) {
+            opts.logger.warn('session_channel_observation_persist_failed', {
+                messageType,
+                sessionId,
+                appId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Emit a `channel_error` frame to a specific subscriber. Used by the
+     * `channel_subscribe` handler for both subscribe-time rejections
+     * (`CHANNEL_UNKNOWN`, `CHANNEL_NOT_LOCAL`, `STACK_ITEM_NOT_FOUND`,
+     * `SUBSCRIBE_UNAUTHORIZED`) AND poll-time failures (`POLL_FAILED`).
+     *
+     * Direct-to-WS, not via fanOut — channel_error frames are
+     * per-subscriber and not stored in the replay buffer. A new
+     * subscriber on the same session will re-subscribe and discover the
+     * same error itself.
+     */
+    function sendChannelError(ws, sessionId, channelName, code, message, requestId, details) {
+        send(ws, {
+            type: 'channel_error',
+            payload: {
+                sessionId,
+                channelName,
+                code,
+                message,
+                ...(details !== undefined ? { details } : {}),
+            },
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    /**
+     * Clamp a client-supplied `pollIntervalMs` against the configured
+     * floor / ceiling. Absent (or non-finite) ⇒ default. Server is
+     * authoritative per the `ChannelSubscribePayload.pollIntervalMs`
+     * docstring — clients propose, server clamps.
+     */
+    function clampPollInterval(supplied) {
+        if (typeof supplied !== 'number' || !Number.isFinite(supplied)) {
+            return pollDefaultMs;
+        }
+        if (supplied < pollFloorMs)
+            return pollFloorMs;
+        if (supplied > pollCeilingMs)
+            return pollCeilingMs;
+        return supplied;
+    }
+    /**
+     * Run one poll of `state.toolName` and fan its result onto the
+     * subscriber's WS as a `channel_payload`. Throws never escape — a
+     * thrown invocation surfaces as a `channel_error{code:'POLL_FAILED'}`
+     * but the polling loop keeps running so transient tool failures are
+     * recoverable.
+     *
+     * Tool registry is guaranteed-present by the caller — channel
+     * subscribes whose `source.tool` isn't in `localTools.allowlist`
+     * never reach this function.
+     */
+    async function pollChannelOnce(sub, state) {
+        if (!localTools)
+            return;
+        if (sub.ws.readyState !== sub.ws.OPEN)
+            return;
+        try {
+            const output = await localTools.invoke(state.toolName, state.args);
+            // Skip emission if the socket closed during the poll — closing-
+            // raced timers fire at most once, and emitting onto a closing
+            // socket is a `send_failed` warning at best.
+            if (sub.ws.readyState !== sub.ws.OPEN)
+                return;
+            state.seq += 1;
+            send(sub.ws, {
+                type: 'channel_payload',
+                payload: {
+                    sessionId: sub.sessionId,
+                    appId: sub.appId,
+                    stackItemId: state.stackItemId,
+                    channelName: state.channelName,
+                    seq: state.seq,
+                    ts: new Date().toISOString(),
+                    // Default mode for source-fed channels is `replace` — each
+                    // poll is a fresh snapshot, not a delta. Channels that need
+                    // append semantics declare `mode: 'append'` on streamSpec;
+                    // honoring that is the iframe-runtime's concern at fold
+                    // time. See `ChannelPayloadFrame.mode`.
+                    mode: 'replace',
+                    payload: output,
+                },
+            });
+        }
+        catch (err) {
+            if (sub.ws.readyState !== sub.ws.OPEN)
+                return;
+            sendChannelError(sub.ws, sub.sessionId, state.channelName, 'POLL_FAILED', err instanceof Error ? err.message : String(err), undefined, 
+            // causedBy slot — sanitized for credential safety in the same
+            // posture as wired-tool's TOOL_THREW emission.
+            sanitize(err instanceof Error ? (err.stack ?? err.message) : String(err)));
+            opts.logger.warn('session_channel_channel_poll_failed', {
+                sessionId: sub.sessionId,
+                appId: sub.appId,
+                stackItemId: state.stackItemId,
+                channelName: state.channelName,
+                toolName: state.toolName,
+                error: String(err),
+            });
+        }
+    }
+    /**
+     * Handle a `channel_subscribe` message. Validates the request,
+     * resolves the channel's `source.tool` against the configured
+     * allowlist, and schedules a polling loop. Idempotent on
+     * `${stackItemId}:${channelName}` — a re-subscribe replaces any
+     * existing interval rather than running two in parallel.
+     */
+    async function handleChannelSubscribe(ws, sub, message) {
+        const payload = message.payload;
+        // sessionId match — the spoof guard at every wire-input boundary.
+        // A subscriber bound to session A can't drive a subscribe for
+        // session B even if they crafted the inbound payload.
+        if (payload.sessionId !== sub.sessionId) {
+            sendChannelError(ws, payload.sessionId, payload.channelName, 'SUBSCRIBE_UNAUTHORIZED', `Subscriber is bound to session '${sub.sessionId}' but channel_subscribe targets '${payload.sessionId}'`, message.requestId);
+            return;
+        }
+        // Without an `streamWebSocketLocalTools` allowlist, no channel
+        // can be subscribed locally. The iframe must fall back to direct
+        // polling via the MCP host proxy.
+        if (!localTools) {
+            sendChannelError(ws, payload.sessionId, payload.channelName, 'CHANNEL_NOT_LOCAL', 'This server has no streamWebSocketLocalTools allowlist; iframe must poll the source tool directly.', message.requestId);
+            return;
+        }
+        // Resolve `streamSpec[channelName].source.tool` against the active
+        // stack item. The reverse-index lookup is O(1); we then load the
+        // session + look up the stack entry by id.
+        const indexEntry = await opts.sessionStore.getSessionByStackItemId(payload.stackItemId);
+        if (!indexEntry || indexEntry.sessionId !== sub.sessionId) {
+            sendChannelError(ws, payload.sessionId, payload.channelName, 'STACK_ITEM_NOT_FOUND', `Stack item '${payload.stackItemId}' not found on session '${payload.sessionId}'`, message.requestId);
+            return;
+        }
+        const session = await opts.sessionStore.get(indexEntry.sessionId);
+        if (!session) {
+            sendChannelError(ws, payload.sessionId, payload.channelName, 'STACK_ITEM_NOT_FOUND', `Session '${indexEntry.sessionId}' no longer exists`, message.requestId);
+            return;
+        }
+        const stackItem = session.stack.find((it) => it.id === payload.stackItemId);
+        if (!stackItem) {
+            sendChannelError(ws, payload.sessionId, payload.channelName, 'STACK_ITEM_NOT_FOUND', `Stack item '${payload.stackItemId}' not found on session '${payload.sessionId}'`, message.requestId);
+            return;
+        }
+        // Channel entry resolution. mcpApps / system variants have no
+        // streamSpec so the field reads back as undefined — same code
+        // path as a component variant without the channel declared.
+        const streamSpec = stackItem.type === 'mcpApps' || stackItem.type === 'system'
+            ? undefined
+            : stackItem.streamSpec;
+        const channelEntry = streamSpec?.[payload.channelName];
+        if (!channelEntry || !channelEntry.source) {
+            sendChannelError(ws, payload.sessionId, payload.channelName, 'CHANNEL_UNKNOWN', `streamSpec['${payload.channelName}'] not declared OR has no source.tool on stack item '${payload.stackItemId}'`, message.requestId);
+            return;
+        }
+        const sourceTool = channelEntry.source.tool;
+        if (!localToolsAllowlist.has(sourceTool)) {
+            sendChannelError(ws, payload.sessionId, payload.channelName, 'CHANNEL_NOT_LOCAL', `source.tool '${sourceTool}' is not in streamWebSocketLocalTools; iframe must poll directly`, message.requestId);
+            return;
+        }
+        // Validation passed — schedule (or re-schedule) the polling loop.
+        const channelKey = `${payload.stackItemId}:${payload.channelName}`;
+        // Idempotent replace: a reconnect that re-subscribes the same
+        // (stackItem, channel) pair gets a fresh timer + zeroed seq. The
+        // client's gap-detection treats it as a new stream from the
+        // server's perspective; client-side reconnect logic owns
+        // continuity if the channel was declared `mode: 'append'`.
+        const existing = sub.channelSubs.get(channelKey);
+        if (existing) {
+            clearInterval(existing.timer);
+            sub.channelSubs.delete(channelKey);
+        }
+        const pollIntervalMs = clampPollInterval(payload.pollIntervalMs);
+        // Layered args: source.args defines defaults; client args override
+        // per ChannelSubscribePayload.args docstring.
+        const mergedArgs = {
+            ...(channelEntry.source.args ?? {}),
+            ...(payload.args ?? {}),
+        };
+        // Resolve the channelKey lookup at callback fire-time. The
+        // timer callback reads `sub.channelSubs.get(channelKey)` so
+        // `state` doesn't have to be referenced through a closure
+        // before it's actually inserted into the tracker. Also self-
+        // cleans on the zombie-timer path: if the subscription was
+        // already torn down (channel_unsubscribe / WS close / replace),
+        // the lookup returns undefined and we clearInterval ourselves.
+        const timer = setInterval(() => {
+            const live = sub.channelSubs.get(channelKey);
+            if (!live || !subscribersByWs.has(sub.ws)) {
+                clearInterval(timer);
+                return;
+            }
+            void pollChannelOnce(sub, live);
+        }, pollIntervalMs);
+        const state = {
+            pollIntervalMs,
+            toolName: sourceTool,
+            stackItemId: payload.stackItemId,
+            channelName: payload.channelName,
+            args: mergedArgs,
+            seq: 0,
+            timer,
+        };
+        sub.channelSubs.set(channelKey, state);
+        opts.logger.info('session_channel_channel_subscribe', {
+            sessionId: sub.sessionId,
+            appId: sub.appId,
+            stackItemId: payload.stackItemId,
+            channelName: payload.channelName,
+            toolName: sourceTool,
+            pollIntervalMs,
+        });
+        // Eager-poll — fire one invocation immediately so the iframe sees
+        // an initial value without waiting `pollIntervalMs`. Matches the
+        // user-expected "subscribe then see data" cadence; the interval
+        // takes over from there.
+        void pollChannelOnce(sub, state);
+    }
+    /**
+     * Handle a `channel_unsubscribe` message. Idempotent: a no-op
+     * unsubscribe on an unknown channelKey returns silently. WS close
+     * implicitly unsubscribes every channel; this message is for
+     * mid-session cancellation.
+     */
+    function handleChannelUnsubscribe(_ws, sub, message) {
+        const payload = message.payload;
+        if (payload.sessionId !== sub.sessionId) {
+            // No-op silently — the canonical "spoof guard" code path is in
+            // channel_subscribe; unsubscribe gets no error frame to avoid
+            // leaking cross-session existence.
+            return;
+        }
+        const channelKey = `${payload.stackItemId}:${payload.channelName}`;
+        const existing = sub.channelSubs.get(channelKey);
+        if (!existing)
+            return;
+        clearInterval(existing.timer);
+        sub.channelSubs.delete(channelKey);
+        opts.logger.info('session_channel_channel_unsubscribe', {
+            sessionId: sub.sessionId,
+            appId: sub.appId,
+            stackItemId: payload.stackItemId,
+            channelName: payload.channelName,
+        });
+    }
+    /**
+     * Stamp a delivery through the replay buffer and fan it out to every
+     * subscriber of the session, honoring the per-subscriber replay
+     * cursor. Shared by the public `sendToSession` entry point AND by
+     * the wiredActionRouter's refresh/error emissions — extracting this
+     * avoids duplicating the seq-stamp + subscriber-iteration logic in
+     * two places.
+     *
+     * Caller is responsible for validating `delivery.payload` against
+     * the active streamSpec BEFORE calling — the fan-out here trusts
+     * its input. Reserved-channel emissions (e.g. `_ggui:contract-
+     * error`) bypass the streamSpec check upstream via
+     * `assertStreamContract`.
+     */
+    async function fanOut(delivery, activeStreamSpec) {
+        const { envelope } = await streamBuffer.record(delivery, activeStreamSpec);
+        // Publish to the seam — InProcessStreamFanout walks its subscriber
+        // queues synchronously inside publish(), so no real async hop. The
+        // pump loop on each WS subscriber yields the envelope, applies the
+        // per-sub replay-cursor filter, and sends to the WS. Fire-and-forget
+        // because publish() never throws on the in-process impl, and a hosted
+        // RedisPubSubFanout failure here would already be persisted to the
+        // SessionStreamBuffer for replay-recovery on reconnect.
+        void streamFanout.publish({ sessionId: envelope.sessionId, envelope });
+        return { seq: envelope.seq };
+    }
+    /**
+     * Emit a canonical {@link ContractErrorPayload} on the reserved
+     * `_ggui:contract-error` channel. Never throws — the wiredActionRouter
+     * dispatch path calls this from `catch` branches; a second failure
+     * would be a footgun.
+     */
+    function emitContractError(sessionId, activeStreamSpec, payload) {
+        try {
+            // Central stamp — re-emit through makeContractErrorPayload so
+            // every contract-error envelope carries the current stamped
+            // schemaVersion regardless of which dispatch branch produced
+            // `payload`. Byte-equivalent to the pre-Item-1 inline stamp
+            // (`{...payload, schemaVersion: PROTOCOL_SCHEMA_VERSION}`) which
+            // also always clobbered to the current version — the local
+            // dispatch paths never forward pre-stamped payloads, so any
+            // incoming schemaVersion on `payload` is discarded by design.
+            const stamped = makeContractErrorPayload({
+                toolName: payload.toolName,
+                error: payload.error,
+                timestamp: payload.timestamp,
+                ...(payload.actionName !== undefined
+                    ? { actionName: payload.actionName }
+                    : {}),
+                ...(payload.sourceAction !== undefined
+                    ? { sourceAction: payload.sourceAction }
+                    : {}),
+            });
+            // Fire-and-forget: emitContractError is called from sync `catch`
+            // branches and a second async failure here would be a footgun.
+            // Promise rejection logs but doesn't propagate; the seam contract
+            // says publish never throws on InProcess impl, and a hosted
+            // RedisPubSubFanout failure is recoverable via replay-on-reconnect.
+            void fanOut({
+                sessionId,
+                channel: CONTRACT_ERROR_CHANNEL,
+                mode: 'append',
+                payload: stamped,
+            }, activeStreamSpec).catch((err) => {
+                opts.logger.error('session_channel_contract_error_emit_failed', {
+                    sessionId,
+                    toolName: payload.toolName,
+                    code: payload.error.code,
+                    error: String(err),
+                });
+            });
+        }
+        catch (err) {
+            opts.logger.error('session_channel_contract_error_emit_failed', {
+                sessionId,
+                toolName: payload.toolName,
+                code: payload.error.code,
+                error: String(err),
+            });
+        }
+    }
+    /**
+     * Race a wired-tool invocation against a timeout. On timeout, the
+     * underlying promise is abandoned (we do NOT cancel the tool —
+     * handlers are trusted to clean up their own resources) but the
+     * caller sees a {@link WiredToolTimeoutError} and emits
+     * `TOOL_TIMEOUT`.
+     */
+    async function invokeWithTimeout(router, toolName, 
+    // Accepts either a validated wired-action payload (Record) OR the
+    // typed empty refresh input ({@link RefreshInput} /
+    // {@link EMPTY_REFRESH_INPUT}). The two call sites upstream are
+    // the only producers; nothing else should widen this.
+    input, ctx, timeoutMs) {
+        let timer;
+        try {
+            return await Promise.race([
+                router.invoke(toolName, input, ctx),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        reject(new WiredToolTimeoutError(toolName, timeoutMs));
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Internal impl behind the public {@link SessionChannelServer.sendPropsUpdate}.
+     * Extracted as a closure-level function so the wired-action dispatcher
+     * can build a `WiredActionContext.sendPropsUpdate` that closes over the
+     * same logic without forward-referencing the returned object. Best-
+     * effort + orphan-tolerant per the docstring on the public method.
+     */
+    async function sendPropsUpdateImpl(sessionId, stackItemId, props) {
+        let session;
+        try {
+            session = await opts.sessionStore.get(sessionId);
+        }
+        catch (err) {
+            opts.logger.warn('session_channel_props_update_lookup_failed', {
+                sessionId,
+                stackItemId,
+                error: String(err),
+            });
+            return;
+        }
+        if (!session) {
+            opts.logger.warn('session_channel_props_update_orphan', {
+                sessionId,
+                stackItemId,
+            });
+            return;
+        }
+        const targetIndex = session.stack.findIndex((item) => item.id === stackItemId);
+        if (targetIndex < 0) {
+            opts.logger.warn('session_channel_props_update_pageid_unknown', {
+                sessionId,
+                stackItemId,
+                stackSize: session.stack.length,
+            });
+            return;
+        }
+        // Filter the flat WS-subscriber set by sessionId; same posture as
+        // `notifyStackPush`. `send()` already silently skips closed sockets
+        // and logs (but doesn't throw on) per-subscriber send failures, so
+        // the caller's mount-handler path can't be made to fail by a dead
+        // WebSocket.
+        for (const sub of wsSubscribers) {
+            if (sub.sessionId !== sessionId)
+                continue;
+            send(sub.ws, {
+                type: 'props_update',
+                payload: { stackItemId, props },
+            });
+        }
+    }
+    /**
+     * Dispatch a wired action after inbound validation has passed.
+     * Called synchronously inside `handleInboundAction` — the caller
+     * awaits so the UI's ack arrives AFTER any refresh-stream frames
+     * land (honest ordering: "when you see the ack, your action
+     * completed + the screen reflects it").
+     *
+     * No-ops when:
+     *   - no wiredActionRouter is configured on this channel
+     *   - the action didn't resolve to a tool name (plain agent-routed
+     *     action that we persist + forward as-is)
+     *   - the resolved tool isn't registered (emits `TOOL_NOT_FOUND`)
+     *
+     * On successful tool invocation, every declared channel on the
+     * active stack item's streamSpec with a `tool` refresh hint fires
+     * that tool + emits its return value on the channel. Refresh tools
+     * are invoked with an empty argument object (`{}`); authors who
+     * need filter args should inline the action + refresh into a single
+     * tool that returns the new state.
+     */
+    async function dispatchWiredAction(session, activeItem, envelope, dispatchedAt) {
+        const router = opts.wiredActionRouter;
+        if (!router || !activeItem || envelope.type !== 'data:submit')
+            return;
+        const payload = envelope.payload;
+        if (!payload || typeof payload.action !== 'string')
+            return;
+        // Disagreement policy — the server-side enforcement point for the
+        // `client wins` rule documented on `ActionEventValue.tool`. Prefer
+        // the envelope's client-populated `tool` (useAction fills it from
+        // the same contract lookup the server would redo). Fall back to the
+        // actionSpec declaration so a client that omits the wire hint still
+        // gets the expected routing. If the two disagree, client wins — the
+        // client is the source of truth for what the user actually saw.
+        // Cross-validation against the agent's tracked contract happens on
+        // the agent-SDK side, not here.
+        const actionEntry = activeItem.actionSpec?.[payload.action];
+        const serverDeclaredTool = actionEntry?.nextStep;
+        const declaredTool = (typeof payload.tool === 'string' && payload.tool.length > 0
+            ? payload.tool
+            : undefined) ?? serverDeclaredTool;
+        if (!declaredTool)
+            return;
+        const actionName = payload.action;
+        const input = payload.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
+            ? payload.data
+            : {};
+        const timeoutMs = opts.wiredActionTimeoutMs ?? DEFAULT_WIRED_TOOL_TIMEOUT_MS;
+        const streamSpec = activeItem.streamSpec;
+        if (!router.has(declaredTool)) {
+            emitContractError(session.id, streamSpec, {
+                toolName: declaredTool,
+                actionName,
+                sourceAction: { type: 'wired-action', dispatchedAt },
+                error: {
+                    code: 'TOOL_NOT_FOUND',
+                    message: `wiredActionRouter has no handler for tool '${declaredTool}'`,
+                },
+                timestamp: new Date().toISOString(),
+            });
+            opts.logger.warn('session_channel_wired_tool_not_found', {
+                sessionId: session.id,
+                toolName: declaredTool,
+                actionName,
+            });
+            return;
+        }
+        // Build the wired-action context the router hands the mount tool.
+        // `sendPropsUpdate` closes over the active
+        // `session.id` so a buggy mount can't accidentally cross-deliver to
+        // another session by passing a foreign sessionId. The same ctx is
+        // reused for the refresh-stream pass below — a refresh tool that
+        // wants to fire props_update can do so, though the canonical site
+        // is the action tool itself.
+        const wiredCtx = {
+            sessionId: session.id,
+            stackItemId: activeItem.id,
+            sendPropsUpdate(targetStackItemId, props) {
+                void sendPropsUpdateImpl(session.id, targetStackItemId, props);
+            },
+        };
+        const invokeStartedAt = Date.now();
+        try {
+            await invokeWithTimeout(router, declaredTool, input, wiredCtx, timeoutMs);
+        }
+        catch (err) {
+            const code = err instanceof WiredToolTimeoutError ? 'TOOL_TIMEOUT' : 'TOOL_THREW';
+            emitContractError(session.id, streamSpec, {
+                toolName: declaredTool,
+                actionName,
+                sourceAction: { type: 'wired-action', dispatchedAt },
+                error: {
+                    code,
+                    message: err instanceof Error ? err.message : String(err),
+                    ...(err instanceof Error && err.stack
+                        ? { causedBy: sanitize(err.stack) }
+                        : {}),
+                },
+                timestamp: new Date().toISOString(),
+            });
+            opts.logger.warn('session_channel_wired_tool_failed', {
+                sessionId: session.id,
+                toolName: declaredTool,
+                actionName,
+                code,
+                error: String(err),
+            });
+            return;
+        }
+        // Operational telemetry — record the successful dispatch. Lossy
+        // by contract (TelemetrySink.emit is sync + non-throwing); a bad
+        // sink MUST NOT block the refresh pass. Attribute set is kept
+        // flat + primitive-only per TelemetryEvent.attributes shape.
+        telemetry.emit({
+            name: 'wired-tool.invoked',
+            at: Date.now(),
+            attributes: {
+                toolName: declaredTool,
+                actionName,
+                sessionId: session.id,
+                latencyMs: Date.now() - invokeStartedAt,
+            },
+        });
+        // Refresh pass — every declared channel with a `tool` hint fires a
+        // fresh read and emits the result on that channel. Each refresh
+        // tool gets its own timeout + isolation: one broken refresh MUST
+        // NOT block others from completing.
+        if (!streamSpec)
+            return;
+        for (const [channelName, channelEntry] of Object.entries(streamSpec)) {
+            const refreshTool = channelEntry?.tool;
+            if (!refreshTool)
+                continue;
+            if (!router.has(refreshTool)) {
+                emitContractError(session.id, streamSpec, {
+                    toolName: refreshTool,
+                    actionName,
+                    sourceAction: { type: 'refresh-stream', dispatchedAt },
+                    error: {
+                        code: 'TOOL_NOT_FOUND',
+                        message: `wiredActionRouter has no handler for refresh tool '${refreshTool}' (channel '${channelName}')`,
+                    },
+                    timestamp: new Date().toISOString(),
+                });
+                continue;
+            }
+            let output;
+            try {
+                // Refresh input is v1-locked to the empty shape via
+                // EMPTY_REFRESH_INPUT. DO NOT replace with an inline `{}`
+                // literal — the named constant is what keeps this contract
+                // grep-able and future-proofs v2 evolution (see
+                // {@link RefreshInput}).
+                output = await invokeWithTimeout(router, refreshTool, EMPTY_REFRESH_INPUT, wiredCtx, timeoutMs);
+            }
+            catch (err) {
+                const code = err instanceof WiredToolTimeoutError ? 'TOOL_TIMEOUT' : 'TOOL_THREW';
+                emitContractError(session.id, streamSpec, {
+                    toolName: refreshTool,
+                    actionName,
+                    sourceAction: { type: 'refresh-stream', dispatchedAt },
+                    error: {
+                        code,
+                        message: err instanceof Error ? err.message : String(err),
+                        ...(err instanceof Error && err.stack
+                            ? { causedBy: sanitize(err.stack) }
+                            : {}),
+                    },
+                    timestamp: new Date().toISOString(),
+                });
+                opts.logger.warn('session_channel_refresh_tool_failed', {
+                    sessionId: session.id,
+                    toolName: refreshTool,
+                    channel: channelName,
+                    code,
+                    error: String(err),
+                });
+                continue;
+            }
+            try {
+                assertStreamContract(streamSpec, channelName, output, opts.extraReservedValidators);
+            }
+            catch (err) {
+                if (err instanceof ContractViolationError) {
+                    emitContractError(session.id, streamSpec, {
+                        toolName: refreshTool,
+                        actionName,
+                        sourceAction: { type: 'refresh-stream', dispatchedAt },
+                        error: {
+                            code: 'SCHEMA_VIOLATION',
+                            message: err.message,
+                        },
+                        timestamp: new Date().toISOString(),
+                    });
+                    opts.logger.warn('session_channel_refresh_schema_violation', {
+                        sessionId: session.id,
+                        toolName: refreshTool,
+                        channel: channelName,
+                        violations: err.violations,
+                    });
+                    continue;
+                }
+                throw err;
+            }
+            try {
+                await fanOut({
+                    sessionId: session.id,
+                    channel: channelName,
+                    mode: channelEntry?.mode ?? 'append',
+                    payload: output,
+                }, streamSpec);
+            }
+            catch (err) {
+                // fanOut swallows per-subscriber transport errors; a throw here
+                // is buffer-internal (e.g., record() invariant violation). Log
+                // but don't propagate — a single broken channel must not take
+                // down the session.
+                opts.logger.error('session_channel_refresh_emit_failed', {
+                    sessionId: session.id,
+                    toolName: refreshTool,
+                    channel: channelName,
+                    error: String(err),
+                });
+            }
+        }
+    }
+    async function resolveIdentityFromUpgrade(req) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        // Bootstrap gate: when `?bootstrap=` is present AND the channel is
+        // configured with bootstrap plumbing, skip the AuthAdapter entirely
+        // at upgrade. The real identity is established in handleSubscribe
+        // when the subscribe payload's `bootstrap` token is verified
+        // (single-use jti claimed there). This is how MCP Apps iframes
+        // connect — they can't set Authorization headers, and the token
+        // model is subscribe-scoped anyway.
+        //
+        // URL-gate here is NOT verification — it's a "don't reject the
+        // upgrade for missing bearer" signal. The real verify runs at
+        // subscribe time; an invalid token reaches that point and is
+        // rejected with BOOTSTRAP_INVALID.
+        if (opts.bootstrap && url.searchParams.has('bootstrap')) {
+            return {
+                identity: {
+                    kind: 'user',
+                    userId: '__bootstrap_pending__',
+                    workspaceId: '__bootstrap_pending__',
+                    roles: [],
+                },
+                source: 'apikey',
+            };
+        }
+        // Embedded-ui cookie gate. Consulted ONLY when the channel is
+        // configured with cookie-auth plumbing AND no bootstrap is in
+        // play. Unlike bootstrap, cookies ARE verified here: the single
+        // consumer (console SPA) sets the cookie out-of-band via
+        // `POST /ggui/console/session-cookie` and we do want to
+        // reject the upgrade cleanly (HTTP 401 → browser WS error) when
+        // the cookie is stale/missing, not carry a doomed handshake into
+        // subscribe where the error surface is worse.
+        //
+        // On success, we stash the bound `{sessionId, appId}` on the
+        // request so `handleSubscribe` can enforce that the subscribe
+        // payload targets exactly those values. No synthesis from the
+        // AuthAdapter — cookies ARE the auth signal.
+        if (opts.cookieAuth) {
+            const raw = opts.cookieAuth.readCookie(req.headers);
+            if (raw) {
+                const bound = opts.cookieAuth.verify(raw);
+                if (bound) {
+                    req.__gguiCookieBound = bound;
+                    return {
+                        identity: { kind: 'builder' },
+                        source: 'apikey',
+                    };
+                }
+                // Cookie present but invalid — do NOT fall through to the
+                // bearer path. An invalid cookie is a same-origin user error,
+                // not a pass-through condition.
+                throw new UnauthenticatedError('console cookie invalid');
+            }
+            // No cookie present → fall through to bearer path below. Mixed
+            // deployments (pairing-token bearer + same-origin cookie for
+            // viewer) are legal.
+        }
+        // Browsers can't set Authorization on native WebSocket. Fall back
+        // to `?token=<jwt>` for web clients, matching the convention most
+        // session-channel endpoints ship with. Server-side clients (Node
+        // `ws`, tests) continue to set the header directly.
+        if (!req.headers['authorization']) {
+            const token = url.searchParams.get('token');
+            if (token) {
+                req.headers['authorization'] = `Bearer ${token}`;
+            }
+        }
+        return resolveIdentityFromHeaders(opts.auth, req.headers, req.socket?.remoteAddress ?? undefined);
+    }
+    /**
+     * Resolve the stack item the event claims to originate from, using the
+     * SAME authoritative index as the hosted ingress (`gguiEvent.context
+     * .stackIndex`, falling back to `session.currentStackIndex`). If the
+     * session has popped forward between emit and ingress, validating
+     * against the newer stack item would reject legitimate in-flight
+     * actions — the doctrine pins context.stackIndex as the truth.
+     */
+    function resolveActiveStackItem(session, stackIndex) {
+        if (stackIndex < 0 || stackIndex >= session.stack.length)
+            return undefined;
+        const entry = session.stack[stackIndex];
+        // MCP Apps items don't participate in ggui's contract enforcement —
+        // they're embedded vendor iframes with their own contract. Return
+        // `undefined` so upstream enforcement skips (allowlist + actionSpec
+        // checks are no-ops when no ComponentStackItem is active).
+        if (entry.type === 'mcpApps' || entry.type === 'system')
+            return undefined;
+        return entry;
+    }
+    /**
+     * Handle an inbound `action` message — the canonical flat
+     * {@link ActionEnvelope} shape.
+     *
+     * Two-step enforcement: (1) allowlist via {@link assertEventAllowed}
+     * against the active stack item's `subscription.events`; (2)
+     * actionSpec payload check via {@link assertActionContract} for
+     * `data:submit` types. Both helpers are shared with the hosted
+     * `handle-action.ts` ingress.
+     */
+    async function handleInboundAction(ws, sub, message) {
+        const envelope = message.payload;
+        // Spoof guard — envelope.sessionId is REQUIRED on the wire and
+        // MUST match the subscriber's bound session.
+        if (envelope.sessionId !== sub.sessionId) {
+            sendError(ws, 'SESSION_MISMATCH', `Action targets session '${envelope.sessionId}' but this socket is subscribed to '${sub.sessionId}'`, message.requestId);
+            return;
+        }
+        const session = await opts.sessionStore.get(sub.sessionId);
+        if (!session) {
+            sendError(ws, 'SESSION_NOT_FOUND', `Session ${sub.sessionId} no longer exists`, message.requestId);
+            return;
+        }
+        // Stack routing: ActionEnvelope may carry stackIndex OR stackItemId.
+        // When both are present, stackItemId wins (doctrine-aligned — stable
+        // identity beats positional index). When neither is present, fall
+        // back to session.currentStackIndex.
+        let stackIndex = envelope.stackIndex ?? session.currentStackIndex;
+        if (envelope.stackItemId !== undefined) {
+            const byId = session.stack.findIndex((s) => s.id === envelope.stackItemId);
+            if (byId >= 0)
+                stackIndex = byId;
+        }
+        const activeItem = resolveActiveStackItem(session, stackIndex);
+        // ── Two-step enforcement ──
+        //   1. allowlist via assertEventAllowed
+        //   2. actionSpec payload check via assertActionContract (data:submit)
+        // Envelope.payload for data:submit carries the ActionEventValue
+        // shape (`{action, data?, tool?}`).
+        try {
+            assertEventAllowed(activeItem?.subscription, envelope.type);
+        }
+        catch (err) {
+            if (err instanceof EventNotAllowedError) {
+                opts.logger.warn('session_channel_event_not_allowed', {
+                    sessionId: sub.sessionId,
+                    eventType: err.eventType,
+                    allowedEvents: err.allowedEvents,
+                    envelope: 'action',
+                });
+                sendError(ws, 'EVENT_NOT_ALLOWED', err.message, message.requestId, err.toErrorData());
+                return;
+            }
+            throw err;
+        }
+        if (envelope.type === 'data:submit') {
+            try {
+                assertActionContract(activeItem?.actionSpec, envelope.payload);
+            }
+            catch (err) {
+                if (err instanceof ContractViolationError) {
+                    opts.logger.warn('session_channel_contract_violation', {
+                        sessionId: sub.sessionId,
+                        violations: err.violations,
+                        envelope: 'action',
+                    });
+                    sendError(ws, 'CONTRACT_VIOLATION', err.message, message.requestId, err.toErrorData());
+                    return;
+                }
+                throw err;
+            }
+        }
+        // Persist the envelope. SessionStore.appendEvent assigns a monotonic
+        // seq the client acks back with so reconnects can resume via `fromSeq`.
+        const dispatchedAt = new Date().toISOString();
+        let seq;
+        try {
+            seq = await opts.sessionStore.appendEvent({
+                sessionId: sub.sessionId,
+                type: 'user.submitted',
+                data: envelope,
+            });
+        }
+        catch (err) {
+            opts.logger.error('session_channel_append_failed', {
+                sessionId: sub.sessionId,
+                error: String(err),
+            });
+            sendError(ws, 'APPEND_FAILED', err instanceof Error ? err.message : String(err), message.requestId);
+            return;
+        }
+        // wiredActionRouter — fire any declared action-tool +
+        // stream-refresh tools BEFORE acking the user. Honest ordering:
+        // when the ack lands, any refresh frames the tool produced have
+        // already fanned out, so the client can treat "ack received" as
+        // "UI state reflects my action". No-op when no router is
+        // configured OR when the action didn't declare a tool.
+        //
+        // Awaited (not fire-and-forget): dispatchWiredAction internally
+        // catches every failure and emits contract-error envelopes; a
+        // throw out of this call would be a platform bug and we'd rather
+        // see it in tests than silently drop.
+        await dispatchWiredAction(session, activeItem, envelope, dispatchedAt);
+        // StreamFanout pump-drain: dispatchWiredAction's internal fanOut
+        // calls `streamFanout.publish()` which queues envelopes into the
+        // pump's async iterator. The pump's `await iter.next()` resolves
+        // on the microtask queue — without this drain, the synchronous
+        // `send(ws, ack)` below races ahead of the pump's `send(ws, data)`,
+        // and the data-before-ack invariant fails. `setImmediate` waits for
+        // the next macrotask, which is strictly after all pending
+        // microtasks (the pump iterations) drain. OSS-only invariant —
+        // hosted Path A's RedisPubSubFanout can't preserve cross-pod
+        // ordering by construction; clients on hosted treat data + ack as
+        // independent signals.
+        await new Promise((resolve) => setImmediate(resolve));
+        send(ws, {
+            type: 'ack',
+            payload: { sequence: seq, timestamp: Date.now() },
+            ...(message.requestId ? { requestId: message.requestId } : {}),
+        });
+    }
+    async function handleSubscribe(ws, identity, message) {
+        const payload = message.payload;
+        // Protocol-version handshake. Opt-in on the client side: absent
+        // `supportedVersions` is legacy-pass-through. When present,
+        // require the server's PROTOCOL_SCHEMA_VERSION to be in the
+        // declared set — otherwise emit UPGRADE_REQUIRED.
+        //
+        //   - 'reject' (default): emit + close the connection. Canonical
+        //     posture for first-party servers.
+        //   - 'advisory' (opt-out): emit + keep the connection
+        //     open (but stop the subscribe; no ack, no session work).
+        //     Clients that ignore the code continue exactly as
+        //     pre-handshake.
+        //
+        // Placed FIRST — before bootstrap verify (which consumes the
+        // single-use bootstrap token per the SessionChannelBootstrap
+        // docstring) and before session lookup/creation (DB work).
+        // Bootstrap iframes with a version mismatch must retry with a
+        // fresh bootstrap token; burning the token on a mismatch the
+        // client could detect by reading the version-negotiation spec
+        // would be a footgun.
+        if (Array.isArray(payload.supportedVersions) &&
+            payload.supportedVersions.length > 0 &&
+            !payload.supportedVersions.includes(PROTOCOL_SCHEMA_VERSION)) {
+            const policy = opts.versionPolicy ?? 'reject';
+            sendError(ws, UPGRADE_REQUIRED, `Server speaks ${PROTOCOL_SCHEMA_VERSION}; client declared ` +
+                `supportedVersions=[${payload.supportedVersions.join(', ')}].`, message.requestId, {
+                serverVersion: PROTOCOL_SCHEMA_VERSION,
+                clientSupportedVersions: payload.supportedVersions,
+                policy,
+            });
+            opts.logger.warn('session_channel_version_mismatch', {
+                sessionId: payload.sessionId,
+                appId: payload.appId,
+                serverVersion: PROTOCOL_SCHEMA_VERSION,
+                clientSupportedVersions: payload.supportedVersions,
+                policy,
+            });
+            if (policy === 'reject') {
+                try {
+                    ws.close();
+                }
+                catch {
+                    // best-effort — socket may already be closing
+                }
+            }
+            return;
+        }
+        // Bootstrap-auth path. When `payload.bootstrap` is present, the
+        // MCP Apps iframe is asking us to authenticate it via the
+        // short-lived token minted by `ggui_push`. This REPLACES the
+        // upgrade-time AuthAdapter identity — iframes don't carry bearer
+        // tokens. Mutually-exclusive on purpose.
+        let effectiveIdentity = identity;
+        let mintedSessionToken;
+        if (typeof payload.bootstrap === 'string' && payload.bootstrap.length > 0) {
+            if (!opts.bootstrap) {
+                sendError(ws, 'BOOTSTRAP_NOT_SUPPORTED', 'This server was not configured with bootstrap-auth plumbing', message.requestId);
+                return;
+            }
+            const verifyResult = opts.bootstrap.verify(payload.bootstrap);
+            if (!verifyResult.ok) {
+                opts.logger.warn('session_channel_bootstrap_rejected', {
+                    sessionId: payload.sessionId,
+                    appId: payload.appId,
+                    reason: verifyResult.reason,
+                });
+                // G14 (2026-05-23): distinguish `expired` from `invalid` so the
+                // iframe-side handler can branch on refresh-vs-rehandshake.
+                // Tamper / format / kind failures collapse into BOOTSTRAP_INVALID
+                // (no refresh path); expired-but-signed envelopes emit the
+                // dedicated BOOTSTRAP_EXPIRED so the client knows to call
+                // `ggui_runtime_refresh_bootstrap`.
+                if (verifyResult.reason === 'expired') {
+                    sendError(ws, 'BOOTSTRAP_EXPIRED', 'Bootstrap token expired — call ggui_runtime_refresh_bootstrap or re-handshake', message.requestId);
+                }
+                else {
+                    sendError(ws, 'BOOTSTRAP_INVALID', 'Bootstrap token invalid (bad signature, malformed, or wrong kind)', message.requestId);
+                }
+                return;
+            }
+            const bound = { sessionId: verifyResult.sessionId, appId: verifyResult.appId };
+            if (bound.sessionId !== payload.sessionId) {
+                sendError(ws, 'BOOTSTRAP_SESSION_MISMATCH', `Bootstrap token is bound to session '${bound.sessionId}' but subscribe targets '${payload.sessionId}'`, message.requestId);
+                return;
+            }
+            if (bound.appId !== payload.appId) {
+                sendError(ws, 'BOOTSTRAP_APP_MISMATCH', `Bootstrap token is bound to app '${bound.appId}' but subscribe targets '${payload.appId}'`, message.requestId);
+                return;
+            }
+            // Synthesize a minimal AuthResult from the bootstrap claims.
+            // The subscriber row needs an identity for logging and roster
+            // inspection; the bootstrap-derived identity is a first-class
+            // citizen for the lifetime of this subscription.
+            effectiveIdentity = {
+                identity: {
+                    kind: 'user',
+                    userId: bound.sessionId,
+                    workspaceId: bound.appId,
+                    roles: [],
+                },
+                source: 'apikey',
+            };
+            // Mint the reconnect credential now — before create/observe
+            // work — so a downstream failure doesn't leave the client with
+            // no way to resume.
+            mintedSessionToken = opts.bootstrap.issueSessionToken(bound.sessionId, bound.appId);
+            opts.logger.info('session_channel_bootstrap_accepted', {
+                sessionId: bound.sessionId,
+                appId: bound.appId,
+            });
+        }
+        // Dev-mode session provisioning: look up first; if not present,
+        // create with the client-provided id via the widened
+        // CreateSessionInput.id seam. Matches the hosted model's shape
+        // (agent creates via ggui_push → client subscribes) in a single
+        // step — production deployments tighten this by supplying an
+        // AuthAdapter that mints session-scoped tokens on push.
+        let session = await opts.sessionStore.get(payload.sessionId);
+        if (session) {
+            if (session.appId !== payload.appId) {
+                sendError(ws, 'APP_MISMATCH', `Session ${payload.sessionId} belongs to a different app`, message.requestId);
+                return;
+            }
+        }
+        else {
+            try {
+                session = await opts.sessionStore.create({
+                    id: payload.sessionId,
+                    appId: payload.appId,
+                });
+            }
+            catch (err) {
+                sendError(ws, 'SESSION_CREATE_FAILED', err instanceof Error ? err.message : String(err), message.requestId);
+                return;
+            }
+        }
+        // Canvas mode: flip `canvasLoaded`
+        // on the first session-wide subscribe so push.ts's resultMeta
+        // detects `canvasOwnsRender === true` for the next push. Until
+        // we flip this, push.ts falls back to the inline path (per-push
+        // resourceUri), which would defeat the canvas model.
+        //
+        // Idempotent — only writes when the flag isn't already true. The
+        // subscribe-ack semantics make this the canonical "canvas iframe
+        // is alive + subscribed" signal; a host that reconnects re-fires
+        // this no-op write.
+        if (session.mcpAppsMode === 'canvas' &&
+            session.canvasLoaded !== true) {
+            try {
+                session = await opts.sessionStore.update(session.id, {
+                    canvasLoaded: true,
+                });
+            }
+            catch (err) {
+                opts.logger.warn('session_channel_canvas_loaded_flip_failed', {
+                    sessionId: session.id,
+                    appId: session.appId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                // Degraded mode — canvasLoaded stays false; push.ts continues
+                // the inline path until a future subscribe succeeds. NOT a
+                // fatal error — the subscribe itself is unaffected.
+            }
+        }
+        // Snapshot the outbound-stream cursor BEFORE registering the
+        // subscriber. Any concurrent producer that calls sendToSession
+        // between here and registration gets seq > snapshotSeq, so the
+        // subscriber will receive it via live fan-out (not via replay).
+        //
+        // This is race-safe in single-threaded JS: the next few lines run
+        // synchronously up to `register(sub)`, and fan-out's per-subscriber
+        // `seq <= replayCompletedSeq` guard takes care of the window.
+        const snapshotSeq = await streamBuffer.currentSeq(session.id);
+        // Resolve active stack item's streamSpec for per-channel replay
+        // policy. If the stack is empty or the index is out of range, no
+        // spec is known — replay contributes nothing.
+        const activeIndex = session.currentStackIndex;
+        const activeItem = activeIndex >= 0 && activeIndex < session.stack.length
+            ? session.stack[activeIndex]
+            : undefined;
+        // Reconnect: `fromSeq` present → replay per policy on declared
+        // AND reserved channels. Fresh subscribe: `fromSeq` absent →
+        // call with `fromSeq=0` + NO spec, so the buffer's spec-channel
+        // walk contributes nothing (preserving the "initial state comes
+        // from ack.stack[].props; stream channels are for updates
+        // after" doctrine for agent-declared channels) but the
+        // reserved-channel walk still surfaces server-pushed state that
+        // landed before the subscriber attached. The provisional
+        // preview channel (`_ggui:preview`) is the load-bearing case:
+        // an agent's `ggui_push` kicks off preview emission BEFORE the
+        // user's browser navigates to the viewer, so without this the
+        // late subscriber sees no preview at all.
+        const activeStreamSpec = activeItem !== undefined &&
+            activeItem.type !== 'mcpApps' &&
+            activeItem.type !== 'system'
+            ? activeItem.streamSpec
+            : undefined;
+        const replay = payload.fromSeq !== undefined
+            ? await streamBuffer.replay(session.id, payload.fromSeq, activeStreamSpec)
+            : await streamBuffer.replay(session.id, 0, undefined);
+        // Subscribe to the StreamFanout BEFORE constructing the Subscriber:
+        // the seam returns an AsyncIterable whose iterator we hand off; the
+        // pump loop in `register` consumes it. Eager registration on the
+        // seam side means any concurrent `streamFanout.publish` from this
+        // point onward queues into our iterator — paired with the
+        // replayCompletedSeq cursor below, that's race-free.
+        const fanoutIter = streamFanout.subscribe(session.id)[Symbol.asyncIterator]();
+        const sub = {
+            ws,
+            sessionId: session.id,
+            appId: session.appId,
+            identity: effectiveIdentity,
+            connectedAt: Date.now(),
+            replayCompletedSeq: snapshotSeq,
+            iter: fanoutIter,
+            // Per-subscriber channel-subscribe tracker. Populated
+            // lazily by the `channel_subscribe` handler when the operator
+            // wired `streamWebSocketLocalTools`; stays empty otherwise.
+            channelSubs: new Map(),
+        };
+        register(sub);
+        opts.logger.info('session_channel_subscribed', {
+            sessionId: session.id,
+            appId: session.appId,
+            identityKind: effectiveIdentity.identity.kind,
+            fromSeq: payload.fromSeq,
+            snapshotSeq,
+            replayCount: replay?.envelopes.length ?? 0,
+            replayTruncated: replay?.truncated ?? false,
+            bootstrap: mintedSessionToken !== undefined,
+        });
+        const ackPayload = {
+            sequence: session.eventSequence,
+            timestamp: Date.now(),
+            stack: session.stack,
+            streamSeq: snapshotSeq,
+            // Advertise the server's protocol version on every successful
+            // subscribe ack (SPEC §11.2.2). Clients whose
+            // CLIENT_SUPPORTED_VERSIONS doesn't contain this string surface
+            // UpgradeRequiredError to their caller; clients that don't wire
+            // the handshake ignore the field (legacy-pass-through).
+            serverVersion: PROTOCOL_SCHEMA_VERSION,
+            ...(replay?.truncated ? { replayTruncated: true } : {}),
+            ...(mintedSessionToken !== undefined
+                ? { sessionToken: mintedSessionToken }
+                : {}),
+        };
+        send(ws, {
+            type: 'ack',
+            payload: ackPayload,
+            ...(message.requestId ? { requestId: message.requestId } : {}),
+        });
+        // Send replay frames AFTER the ack. Ordering by `seq` ASC — the
+        // buffer returns them pre-sorted. Client sees ack(streamSeq=N) →
+        // up to N replay `data` frames → live tail (seq > N). No explicit
+        // "replay end" marker is needed; the client uses envelope.seq as
+        // the single source of truth for ordering.
+        if (replay) {
+            for (const env of replay.envelopes) {
+                send(ws, { type: 'data', payload: env });
+            }
+        }
+    }
+    async function onMessage(ws, raw) {
+        const sub = subscribersByWs.get(ws);
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            sendError(ws, 'INVALID_JSON', 'Message is not valid JSON');
+            return;
+        }
+        if (!message || typeof message !== 'object' || typeof message.type !== 'string') {
+            sendError(ws, 'INVALID_MESSAGE', 'Message is missing a `type` discriminator');
+            return;
+        }
+        switch (message.type) {
+            case 'subscribe': {
+                // `subscribe` is the only message allowed before identity is
+                // bound to a session. Identity was already resolved at upgrade
+                // time; we just need to register the subscriber.
+                const identity = pendingIdentity.get(ws);
+                if (!identity) {
+                    sendError(ws, 'UNAUTHENTICATED', 'No identity bound to this socket', message.requestId);
+                    return;
+                }
+                // Cookie-scope enforcement: when the upgrade was authenticated
+                // via an console cookie, the subscribe payload MUST target
+                // the session the cookie was issued for. A valid cookie for
+                // session A can't be used to open session B.
+                const cookieBound = pendingCookieBinding.get(ws);
+                if (cookieBound) {
+                    if (message.payload.sessionId !== cookieBound.sessionId) {
+                        sendError(ws, 'DEVTOOL_COOKIE_SESSION_MISMATCH', `Embedded-ui cookie is bound to session '${cookieBound.sessionId}' but subscribe targets '${message.payload.sessionId}'`, message.requestId);
+                        return;
+                    }
+                    if (message.payload.appId !== cookieBound.appId) {
+                        sendError(ws, 'DEVTOOL_COOKIE_APP_MISMATCH', `Embedded-ui cookie is bound to app '${cookieBound.appId}' but subscribe targets '${message.payload.appId}'`, message.requestId);
+                        return;
+                    }
+                }
+                await handleSubscribe(ws, identity, message);
+                pendingIdentity.delete(ws);
+                pendingCookieBinding.delete(ws);
+                return;
+            }
+            case 'ping':
+                send(ws, {
+                    type: 'pong',
+                    payload: {},
+                    ...(message.requestId ? { requestId: message.requestId } : {}),
+                });
+                return;
+            case 'close':
+                // Explicit close from client — unregister + close the socket.
+                if (sub)
+                    unregister(ws);
+                ws.close(1000, 'client_close');
+                return;
+            case 'action':
+                if (!sub) {
+                    sendError(ws, 'NOT_SUBSCRIBED', "Send a 'subscribe' message first before 'action'", message.requestId);
+                    return;
+                }
+                await handleInboundAction(ws, sub, message);
+                return;
+            case 'channel_subscribe':
+                if (!sub) {
+                    sendError(ws, 'NOT_SUBSCRIBED', "Send a 'subscribe' message first before 'channel_subscribe'", message.requestId);
+                    return;
+                }
+                await handleChannelSubscribe(ws, sub, message);
+                return;
+            case 'channel_unsubscribe':
+                if (!sub) {
+                    // No subscriber → nothing was subscribed → no-op silently.
+                    // Returning an error would leak "is this socket subscribed"
+                    // state for unauthenticated clients.
+                    return;
+                }
+                handleChannelUnsubscribe(ws, sub, message);
+                return;
+            case 'host_context_observed':
+                // The iframe-runtime echoes its captured `McpUiHostContext`
+                // after `ui/initialize` resolves and on every
+                // `ui/notifications/host-context-changed` notification. Persist
+                // on `Session.hostContext` so `ggui_handshake` and
+                // `ggui_consume` can surface it to the agent on subsequent
+                // turns. Fire-and-forget on the client side; no response.
+                if (!checkSubscriberTenancy(ws, sub, message.payload, message.type, message.requestId)) {
+                    return;
+                }
+                await applySessionPatch(sub.sessionId, sub.appId, message.type, { hostContext: message.payload.hostContext, lastActivityAt: Date.now() });
+                return;
+            case 'canvas_navigated':
+                // The iframe-runtime's CanvasShell fires this when the user
+                // back-navigates in the canvas (popping a stack item from the
+                // local NavStackModel). The server updates
+                // `session.activeStackItemId` to the new top so
+                // `ggui_consume`'s active-pipe resolution stays in sync with
+                // what the user is looking at. AbortSignal wiring for in-
+                // flight cold-gen on the popped item is a follow-up — the
+                // server-side gen orchestrator (push.ts handler) doesn't yet
+                // expose a per-stack-item AbortController registry to this
+                // routing layer.
+                if (!checkSubscriberTenancy(ws, sub, message.payload, message.type, message.requestId)) {
+                    return;
+                }
+                await applySessionPatch(sub.sessionId, sub.appId, message.type, {
+                    activeStackItemId: message.payload.activeItemId,
+                    lastActivityAt: Date.now(),
+                });
+                return;
+            case 'pop':
+            case 'get_stack':
+            case 'generate':
+            case 'feedback':
+                // Require an active subscription for operational messages.
+                if (!sub) {
+                    sendError(ws, 'NOT_SUBSCRIBED', `Send a 'subscribe' message first before '${message.type}'`, message.requestId);
+                    return;
+                }
+                // These OSS channel handlers land incrementally once the
+                // matching shared handlers exist in @ggui-ai/mcp-server-handlers.
+                // For now the ingress point is documented but rejected with a
+                // clear code so clients don't assume silent success.
+                sendError(ws, 'NOT_IMPLEMENTED', `'${message.type}' not yet handled on the OSS channel server`, message.requestId);
+                return;
+            default:
+                sendError(ws, 'UNSUPPORTED_MESSAGE', `Unsupported message type: ${String(message.type)}`, message.requestId);
+        }
+    }
+    /**
+     * During the pre-subscribe window, a ws has a resolved identity but
+     * no session-bound subscriber yet. We hold the identity here until
+     * the first `subscribe` lands; once it does, the subscriber record
+     * owns the identity and this entry is cleared.
+     */
+    const pendingIdentity = new WeakMap();
+    /**
+     * Embedded-ui cookie binding established at upgrade. When present,
+     * `handleSubscribe` enforces `subscribe.sessionId === bound.sessionId`
+     * so a valid cookie can't be used to open a session it wasn't
+     * issued for. Parallel to {@link pendingIdentity} — same lifetime,
+     * same WeakMap rationale.
+     */
+    const pendingCookieBinding = new WeakMap();
+    wss.on('connection', (ws, req) => {
+        // Bind the resolved identity from the upgrade phase. It was
+        // attached to the request object in handleUpgrade.
+        const identity = req.__gguiIdentity;
+        if (identity)
+            pendingIdentity.set(ws, identity);
+        // Likewise for any cookie binding.
+        const cookieBound = req.__gguiCookieBound;
+        if (cookieBound)
+            pendingCookieBinding.set(ws, cookieBound);
+        ws.on('message', (raw) => {
+            // `ws.on('message')` delivers Buffer/ArrayBuffer/Buffer[] depending
+            // on frame type; normalize to string.
+            const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+            onMessage(ws, text).catch((err) => {
+                opts.logger.error('session_channel_message_failed', {
+                    error: String(err),
+                });
+            });
+        });
+        ws.on('close', () => {
+            unregister(ws);
+            pendingIdentity.delete(ws);
+        });
+        ws.on('error', (err) => {
+            opts.logger.warn('session_channel_socket_error', { error: String(err) });
+        });
+    });
+    return {
+        path,
+        handleUpgrade(req, socket, head) {
+            resolveIdentityFromUpgrade(req)
+                .then((identity) => {
+                // Stash identity on the request so the 'connection' handler
+                // can wire it onto the socket. This is the standard ws
+                // per-request piggyback pattern.
+                req.__gguiIdentity = identity;
+                wss.handleUpgrade(req, socket, head, (ws) => {
+                    // Expose `upgradeReq` for the connection handler.
+                    wss.emit('connection', ws, req);
+                });
+            })
+                .catch((err) => {
+                if (err instanceof UnauthenticatedError) {
+                    opts.logger.warn('session_channel_auth_failed', {
+                        reason: err.message,
+                    });
+                    socket.write('HTTP/1.1 401 Unauthorized\r\n' +
+                        'Connection: close\r\n' +
+                        'Content-Type: text/plain\r\n\r\n' +
+                        'Unauthorized: ' +
+                        err.message +
+                        '\r\n');
+                }
+                else {
+                    opts.logger.error('session_channel_upgrade_failed', {
+                        error: String(err),
+                    });
+                    socket.write('HTTP/1.1 500 Internal Server Error\r\n' +
+                        'Connection: close\r\n\r\n');
+                }
+                socket.destroy();
+            });
+        },
+        async sendToSession(delivery) {
+            // Outbound fan-out enforcement (defense-in-depth parity with
+            // hosted `handle-data.ts`). Re-validates the delivery's payload
+            // against the active stack item's streamSpec BEFORE delivery —
+            // so a future OSS mutation handler that bypasses the emit-side
+            // check can't fan out malformed data to subscribers. Throws
+            // ContractViolationError{tool:'ggui_emit'} on violation;
+            // caller decides what to do (log, rethrow, wrap).
+            const session = await opts.sessionStore.get(delivery.sessionId);
+            const activeIndex = session?.currentStackIndex ?? -1;
+            const activeEntry = session && activeIndex >= 0 && activeIndex < session.stack.length
+                ? session.stack[activeIndex]
+                : undefined;
+            const streamSpec = activeEntry !== undefined &&
+                activeEntry.type !== 'mcpApps' &&
+                activeEntry.type !== 'system'
+                ? activeEntry.streamSpec
+                : undefined;
+            assertStreamContract(streamSpec, delivery.channel, delivery.payload, opts.extraReservedValidators);
+            return fanOut(delivery, streamSpec);
+        },
+        notifyStackPush(sessionId, stackItem, matchType) {
+            // Best-effort fan-out to every live subscriber bound to this
+            // session. NOT routed through the replay buffer — see the
+            // `notifyStackPush` JSDoc on the interface for why fresh
+            // subscribers rely on `ack.stack` instead of a replay frame.
+            // NOT routed through StreamFanout either — `type: 'push'` is a
+            // distinct WebSocket message type, not a stream envelope, so it
+            // sits outside the seam's contract. Filter the flat WS-subscriber
+            // set by sessionId; N is typically 1-2 (multi-tab session sharing).
+            const payload = matchType !== undefined ? { stackItem, matchType } : { stackItem };
+            for (const sub of wsSubscribers) {
+                if (sub.sessionId !== sessionId)
+                    continue;
+                // `send()` already silently skips closed sockets and logs
+                // (but doesn't throw on) per-subscriber send failures, so the
+                // caller's `appendStackItem` path can't be made to fail by a
+                // dead WebSocket.
+                send(sub.ws, { type: 'push', payload });
+            }
+        },
+        async primeStreams(sessionId, stackItem) {
+            const router = opts.wiredActionRouter;
+            const streamSpec = 'streamSpec' in stackItem ? stackItem.streamSpec : undefined;
+            if (!router || !streamSpec)
+                return;
+            const timeoutMs = opts.wiredActionTimeoutMs ?? DEFAULT_WIRED_TOOL_TIMEOUT_MS;
+            // Build the same wired-action ctx the dispatcher uses.
+            // Prime-time invocations reuse the seam so a refresh
+            // tool that fires `sendPropsUpdate` on cold-start works the same
+            // way as one fired post-action. `stackItemId` is the primed stack
+            // item's id; closures lock to the caller-supplied sessionId.
+            const wiredCtx = {
+                sessionId,
+                stackItemId: stackItem.id,
+                sendPropsUpdate(targetStackItemId, props) {
+                    void sendPropsUpdateImpl(sessionId, targetStackItemId, props);
+                },
+            };
+            for (const [channelName, channelEntry] of Object.entries(streamSpec)) {
+                const refreshTool = channelEntry?.tool;
+                if (!refreshTool)
+                    continue;
+                if (!router.has(refreshTool)) {
+                    opts.logger.warn('session_channel_prime_tool_not_found', {
+                        sessionId,
+                        toolName: refreshTool,
+                        channel: channelName,
+                    });
+                    continue;
+                }
+                let output;
+                try {
+                    output = await invokeWithTimeout(router, refreshTool, EMPTY_REFRESH_INPUT, wiredCtx, timeoutMs);
+                }
+                catch (err) {
+                    opts.logger.warn('session_channel_prime_tool_failed', {
+                        sessionId,
+                        toolName: refreshTool,
+                        channel: channelName,
+                        error: String(err),
+                    });
+                    continue;
+                }
+                try {
+                    assertStreamContract(streamSpec, channelName, output, opts.extraReservedValidators);
+                }
+                catch (err) {
+                    opts.logger.warn('session_channel_prime_schema_violation', {
+                        sessionId,
+                        toolName: refreshTool,
+                        channel: channelName,
+                        error: String(err),
+                    });
+                    continue;
+                }
+                try {
+                    await fanOut({
+                        sessionId,
+                        channel: channelName,
+                        mode: channelEntry?.mode ?? 'append',
+                        payload: output,
+                    }, streamSpec);
+                }
+                catch (err) {
+                    opts.logger.error('session_channel_prime_emit_failed', {
+                        sessionId,
+                        toolName: refreshTool,
+                        channel: channelName,
+                        error: String(err),
+                    });
+                }
+            }
+        },
+        sendPropsUpdate(sessionId, stackItemId, props) {
+            // Public entry point — delegates to the closure-level impl that
+            // the wired-action dispatcher's `WiredActionContext.sendPropsUpdate`
+            // also calls. Returns the impl's promise so the caller can await
+            // session-store lookup completion if desired (the wiredCtx call
+            // site fire-and-forgets via `void`).
+            return sendPropsUpdateImpl(sessionId, stackItemId, props);
+        },
+        sendDrainAck({ sessionId, appId, stackItemId, eventId, drainedAt }) {
+            // Server-side fan-out for the action-drain ack.
+            // Filter the flat WS-subscriber set by sessionId (same posture
+            // as `sendPropsUpdate`). No persistence; subscribers that
+            // missed the frame fall back to their 10s claim timer, which
+            // the atomic pop resolves cleanly. `send()` already silently
+            // skips closed sockets and absorbs per-subscriber send
+            // failures.
+            for (const sub of wsSubscribers) {
+                if (sub.sessionId !== sessionId)
+                    continue;
+                send(sub.ws, {
+                    type: 'drain_ack',
+                    payload: { sessionId, appId, stackItemId, eventId, drainedAt },
+                });
+            }
+        },
+        get subscriberCount() {
+            return wsSubscribers.size;
+        },
+        get sessionCount() {
+            // Distinct session count across live WS subscribers. With
+            // multi-tab sessions, two subscribers may share a sessionId —
+            // dedupe before counting.
+            const sessions = new Set();
+            for (const sub of wsSubscribers)
+                sessions.add(sub.sessionId);
+            return sessions.size;
+        },
+        async close() {
+            // Close every open socket + drain its StreamFanout subscription.
+            // `wss.close` terminates the server but not in-flight sockets,
+            // so walk them explicitly. Each `iter.return()` unregisters
+            // the subscriber from the seam (idempotent on the in-process impl).
+            //
+            // Close code 1012 ("Service Restart", RFC 6455 + IANA registry)
+            // signals to clients that the server is restarting and they
+            // should reconnect immediately rather than treat the close as
+            // permanent. The pod's K8s rolling update fits this exactly:
+            // a new pod is already accepting connections behind the same
+            // load balancer; iframe-runtime + console viewer should
+            // reconnect on next message instead of blinking "disconnected".
+            // Code 1001 (used previously) means "endpoint going away" with
+            // no reconnect hint — semantically inaccurate for the pod-roll
+            // case and the wrong signal for client reconnect logic.
+            const sessions = new Set();
+            for (const sub of wsSubscribers) {
+                sessions.add(sub.sessionId);
+                try {
+                    sub.ws.close(1012, 'service_restart');
+                }
+                catch {
+                    /* best-effort */
+                }
+                void sub.iter.return?.();
+            }
+            wsSubscribers.clear();
+            // Defensive: also close any sessions on the seam that no longer
+            // have local WS subscribers (e.g. orphaned sessions from a partial
+            // unregister race). For InProcessStreamFanout this is a no-op
+            // when there are no subscribers; for hosted bindings it ensures
+            // the per-session pub/sub channel teardown fires.
+            await Promise.all(Array.from(sessions, (sessionId) => streamFanout.close(sessionId).catch(() => {
+                /* best-effort */
+            })));
+            await new Promise((resolve) => {
+                wss.close(() => resolve());
+            });
+        },
+    };
+}
+/** Fabricate a request id for live-channel ops so logs correlate. */
+export function newRequestId() {
+    return randomUUID();
+}