ocuclaw 1.2.4 → 1.3.1

package/dist/runtime/downstream-server.js

@@ -1,1891 +0,0 @@
-import * as WebSocketModule from "ws";
-
-// `ws` exposes different server entrypoints across ESM/CJS consumers.
-const WebSocket =
-  WebSocketModule.default || WebSocketModule.WebSocket || WebSocketModule;
-const WebSocketServer =
-  WebSocketModule.WebSocketServer || WebSocketModule.Server || WebSocket.Server;
-
-function normalizeLogger(logger) {
-  if (!logger || typeof logger !== "object") {
-    return console;
-  }
-  return {
-    info: typeof logger.info === "function" ? logger.info.bind(logger) : console.log,
-    warn: typeof logger.warn === "function" ? logger.warn.bind(logger) : console.warn,
-    error: typeof logger.error === "function" ? logger.error.bind(logger) : console.error,
-    debug:
-      typeof logger.debug === "function" ? logger.debug.bind(logger) : console.debug,
-  };
-}
-
-// --- Factory ---
-
-/**
- * Create a downstream WebSocket server.
- *
- * Manages WebSocket transport for downstream clients (Even App,
- * commander.html). Handles token-based authentication, client tracking,
- * and message delegation to the downstream handler.
- *
- * @param {object} opts
- * @param {object} opts.handler
- *   Downstream handler instance (from createDownstreamHandler).
- * @param {() => string|null} opts.getCurrentPages
- *   Returns formatted pages JSON string, or null if no pages yet.
- * @param {() => string|null} opts.getCurrentStatus
- *   Returns formatted status JSON string, or null if no status yet.
- * @param {() => string|null} [opts.getCurrentDebugConfig]
- *   Returns formatted debug-config snapshot JSON string for app/WebUI clients.
- * @param {() => {pagesRevision?: number, statusRevision?: number}|null} [opts.getCurrentResumeState]
- *   Returns current server-side resume revisions for pages/status.
- * @param {number} opts.port
- *   WebSocket server port (0 for OS-assigned).
- * @param {string} opts.host
- *   WebSocket server bind address.
- * @param {string} opts.token
- *   Expected authentication token.
- * @param {(meta: object) => void} [opts.onClientConnected]
- *   Optional callback for client connection events.
- * @param {(meta: object) => void} [opts.onClientDisconnected]
- *   Optional callback for client disconnection events.
- * @param {(meta: object) => void} [opts.onTransportControl]
- *   Optional callback for transport control frames handled before app message routing.
- * @returns {object} Server instance with broadcast, unicast, getClientIds, close.
- */
-function createDownstreamServer(opts) {
-  const logger = normalizeLogger(opts.logger);
-  const handler = opts.handler;
-  const getCurrentPages = opts.getCurrentPages;
-  const getCurrentStatus = opts.getCurrentStatus;
-  const getCurrentDebugConfig = opts.getCurrentDebugConfig || null;
-  const getCurrentResumeState = opts.getCurrentResumeState || null;
-  const token = opts.token;
-  const onClientConnected = opts.onClientConnected || null;
-  const onClientDisconnected = opts.onClientDisconnected || null;
-  const onTransportControl = opts.onTransportControl || null;
-  const protocolHelloTimeoutMs = Number.isFinite(opts.protocolHelloTimeoutMs)
-    ? Math.max(0, Math.floor(opts.protocolHelloTimeoutMs))
-    : 120;
-  const externalDebugToolsEnabled = opts.externalDebugToolsEnabled !== false;
-  const resumeHandshakeTimeoutMs = Number.isFinite(opts.resumeHandshakeTimeoutMs)
-    ? Math.max(0, Math.floor(opts.resumeHandshakeTimeoutMs))
-    : 120;
-  const nudgeActiveIntervalMs = Number.isFinite(opts.nudgeActiveIntervalMs)
-    ? Math.max(1, Math.floor(opts.nudgeActiveIntervalMs))
-    : 150;
-  const nudgeSlowIntervalMs = Number.isFinite(opts.nudgeSlowIntervalMs)
-    ? Math.max(1, Math.floor(opts.nudgeSlowIntervalMs))
-    : 1000;
-  const nudgeIdleDeactivateMs = Number.isFinite(opts.nudgeIdleDeactivateMs)
-    ? Math.max(0, Math.floor(opts.nudgeIdleDeactivateMs))
-    : 5000;
-  const nudgeHeartbeatIntervalMs = Number.isFinite(opts.nudgeHeartbeatIntervalMs)
-    ? Math.max(1, Math.floor(opts.nudgeHeartbeatIntervalMs))
-    : 10000;
-  const nudgeHardTimeoutMs = Number.isFinite(opts.nudgeHardTimeoutMs)
-    ? Math.max(1, Math.floor(opts.nudgeHardTimeoutMs))
-    : 60000;
-  const nudgeStaleHeartbeatThresholdMs = nudgeHeartbeatIntervalMs * 2;
-  const RENDER_NUDGE_FRAME = JSON.stringify({ type: "render_nudge" });
-
-  /** @type {Map<string, WebSocket>} */
-  const clients = new Map();
-  /** @type {Map<string, {selectedVersion: "v2"|null, supportedProtocolVersions: string[], clientName: string|null, clientVersion: string|null, sessionKey: string|null, reason: string|null}>} */
-  const protocolState = new Map();
-  /** @type {Map<string, {pagesSynced: boolean, statusSynced: boolean, approvalsSynced: boolean, debugConfigSynced: boolean, resumeReceived: boolean, timer: any}>} */
-  const syncState = new Map();
-  /** @type {Map<string, {visibilityState: "hidden"|"visible"|"blurred"|null, streamChars: number|null, lastHeartbeatAtMs: number|null, lastRelayStreamingActivityAtMs: number|null, interactionStage: "idle"|"listening"|"voice_handoff"|"thinking"|"streaming"|"post_turn_drain", cadenceBucket: "idle"|"active_non_stream"|"active_stream", nudgeActive: boolean, nudgeIntervalMs: number|null, nudgeStartedAtMs: number|null, lastNudgeAtMs: number|null, stalledHeartbeatCount: number, nudgeTimer: any, idleDeactivateTimer: any, staleHeartbeatTimer: any, hardTimeoutTimer: any}>} */
-  const clientNudgeState = new Map();
-  /** @type {Map<string, {clientDebugEnabled: boolean|null, runtimeDiagnosticsVisible: boolean|null, perfNoisyDebugMuted: boolean|null, perfPayloadLiteMode: boolean|null, activeSessionKey: string|null, bundleIdentity: {kind: string|null, mode: string|null, host: string|null, port: number|null, servedDistPath: string|null}|null, emittedAtMs: number|null, updatedAtMs: number}>} */
-  const clientReadinessSnapshotState = new Map();
-  /** @type {Map<string, {requesterClientId: string, targetClientId: string, createdAtMs: number}>} */
-  const pendingReadinessProbeRequests = new Map();
-  /** @type {Map<string, string>} */
-  const unresolvedApprovals = new Map();
-  let nextClientId = 1;
-  const APP_PROTOCOL = {
-    approvalRequest: "ocuclaw.approval.request",
-    approvalResolved: "ocuclaw.approval.resolved",
-    debugConfigSnapshot: "ocuclaw.debug.config.snapshot",
-    pages: "ocuclaw.view.pages.snapshot",
-    readinessProbeAck: "ocuclaw.readiness.probe.ack",
-    readinessProbeRequest: "ocuclaw.readiness.probe.request",
-    readinessSnapshot: "ocuclaw.readiness.snapshot",
-    resume: "ocuclaw.sync.resume",
-    resumeAck: "ocuclaw.sync.resume.ack",
-    status: "ocuclaw.runtime.status",
-  };
-  const REMOVED_V1_APP_TYPES = new Set([
-    "approvalResponse",
-    "eventDebug",
-    "getEvenAiSettings",
-    "getOcuClawSettings",
-    "getModelsCatalog",
-    "getSkills",
-    "getSessionModelConfig",
-    "getSessions",
-    "newChat",
-    "newSession",
-    "resume",
-    "send",
-    "setEvenAiSettings",
-    "setOcuClawSettings",
-    "setSessionModelConfig",
-    "slashCommand",
-    "subscribeProtocol",
-    "switchSession",
-  ]);
-
-  function truncateForLog(value, maxChars = 120) {
-    if (typeof value !== "string") return "";
-    if (value.length <= maxChars) return value;
-    return `${value.slice(0, maxChars)}...`;
-  }
-
-  function updateClientRole(meta, messageType, clientKind = "unknown") {
-    if (!meta || typeof messageType !== "string") return;
-    if (!meta.firstMessageType) meta.firstMessageType = messageType;
-
-    if (clientKind === "debug") {
-      meta.role = "debug";
-      return;
-    }
-    if (meta.role === "debug") {
-      return;
-    }
-
-    const nextRole =
-      messageType === "remote-control" ? "control" : "app";
-    if (meta.role === "unknown") {
-      meta.role = nextRole;
-      return;
-    }
-    if (meta.role !== nextRole) {
-      meta.role = "mixed";
-    }
-  }
-
-  function parseRevision(value) {
-    if (!Number.isFinite(Number(value))) return null;
-    const num = Math.floor(Number(value));
-    if (num < 0) return null;
-    return num;
-  }
-
-  function parseBool(value) {
-    if (value === true || value === false) return value;
-    if (typeof value === "number") return value !== 0;
-    if (typeof value !== "string") return false;
-    const normalized = value.trim().toLowerCase();
-    return normalized === "true" || normalized === "1" || normalized === "yes";
-  }
-
-  function parseOptionalBoolean(value) {
-    if (value === true || value === false) return value;
-    if (typeof value === "number") return value !== 0;
-    if (typeof value !== "string") return null;
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "true" || normalized === "1" || normalized === "yes") {
-      return true;
-    }
-    if (normalized === "false" || normalized === "0" || normalized === "no") {
-      return false;
-    }
-    return null;
-  }
-
-  function parseOptionalTrimmedString(value) {
-    if (typeof value !== "string") return null;
-    const trimmed = value.trim();
-    return trimmed ? trimmed : null;
-  }
-
-  function parseVisibilityState(value) {
-    const normalized = parseOptionalTrimmedString(value);
-    if (!normalized) return null;
-    const lowered = normalized.toLowerCase();
-    return lowered === "hidden" || lowered === "visible" || lowered === "blurred"
-      ? lowered
-      : null;
-  }
-
-  function parseVisibilityControl(value) {
-    if (!value || value.type !== "visibility") {
-      return null;
-    }
-    const state = parseVisibilityState(value.state);
-    if (!state) {
-      return null;
-    }
-    return { type: "visibility", state };
-  }
-
-  function parseOptionalNonNegativeInt(value) {
-    if (value === null || value === undefined) return null;
-    if (!Number.isFinite(Number(value))) return null;
-    const num = Math.floor(Number(value));
-    return num >= 0 ? num : null;
-  }
-
-  function parseDrainCompleteControl(value) {
-    if (!value || value.type !== "drain_complete") {
-      return null;
-    }
-    return { type: "drain_complete" };
-  }
-
-  function parseEnrichedPing(value) {
-    if (!value || value.type !== "ping") {
-      return null;
-    }
-    return {
-      type: "ping",
-      ts: Number.isFinite(Number(value.ts)) ? Number(value.ts) : null,
-      streamChars: parseOptionalNonNegativeInt(value.streamChars),
-      visibilityState: parseVisibilityState(value.visibilityState),
-    };
-  }
-
-  function normalizeProtocolVersion(value) {
-    const normalized = parseOptionalTrimmedString(value);
-    if (!normalized) return null;
-    const lowered = normalized.toLowerCase();
-    return lowered === "v1" || lowered === "v2" ? lowered : null;
-  }
-
-  function parseSupportedProtocolVersions(value) {
-    if (!Array.isArray(value)) {
-      return [];
-    }
-    const versions = [];
-    for (const entry of value) {
-      const version = normalizeProtocolVersion(entry);
-      if (version && !versions.includes(version)) {
-        versions.push(version);
-      }
-    }
-    return versions;
-  }
-
-  function parseProtocolHello(value) {
-    if (!value || value.type !== "protocolHello") {
-      return null;
-    }
-    return {
-      supportedProtocolVersions: parseSupportedProtocolVersions(
-        value.supportedProtocolVersions || value.supportedVersions,
-      ),
-      preferredProtocolVersion:
-        normalizeProtocolVersion(value.preferredProtocolVersion) || "v2",
-      clientName:
-        parseOptionalTrimmedString(value.clientName) ||
-        parseOptionalTrimmedString(value.clientId),
-      clientVersion: parseOptionalTrimmedString(value.clientVersion),
-      sessionKey: parseOptionalTrimmedString(value.sessionKey),
-      readinessSnapshot: parseReadinessSnapshot(value.readinessSnapshot),
-    };
-  }
-
-  function parseReadinessBundleIdentity(value) {
-    if (!value || typeof value !== "object") {
-      return null;
-    }
-    const kind = parseOptionalTrimmedString(value.kind || value.lane);
-    const mode = parseOptionalTrimmedString(value.mode);
-    const host = parseOptionalTrimmedString(value.host);
-    const port = parseOptionalNonNegativeInt(value.port);
-    const servedDistPath =
-      parseOptionalTrimmedString(value.servedDistPath) ||
-      parseOptionalTrimmedString(value.staticDir);
-    if (!kind && !mode && !host && port === null && !servedDistPath) {
-      return null;
-    }
-    return {
-      kind: kind || null,
-      mode: mode || null,
-      host: host || null,
-      port,
-      servedDistPath: servedDistPath || null,
-    };
-  }
-
-  function parseReadinessSnapshot(value) {
-    if (!value || typeof value !== "object") {
-      return null;
-    }
-    const clientDebugEnabled = parseOptionalBoolean(value.clientDebugEnabled);
-    const runtimeDiagnosticsVisible = parseOptionalBoolean(
-      value.runtimeDiagnosticsVisible,
-    );
-    const perfNoisyDebugMuted = parseOptionalBoolean(value.perfNoisyDebugMuted);
-    const perfPayloadLiteMode = parseOptionalBoolean(value.perfPayloadLiteMode);
-    const activeSessionKey =
-      parseOptionalTrimmedString(value.activeSessionKey) ||
-      parseOptionalTrimmedString(value.sessionKey);
-    const bundleIdentity = parseReadinessBundleIdentity(
-      value.bundleIdentity || value.bundle,
-    );
-    const emittedAtMs = parseOptionalNonNegativeInt(value.emittedAtMs);
-    if (
-      clientDebugEnabled === null &&
-      runtimeDiagnosticsVisible === null &&
-      perfNoisyDebugMuted === null &&
-      perfPayloadLiteMode === null &&
-      !activeSessionKey &&
-      !bundleIdentity &&
-      emittedAtMs === null
-    ) {
-      return null;
-    }
-    return {
-      clientDebugEnabled,
-      runtimeDiagnosticsVisible,
-      perfNoisyDebugMuted,
-      perfPayloadLiteMode,
-      activeSessionKey: activeSessionKey || null,
-      bundleIdentity,
-      emittedAtMs,
-      updatedAtMs: Date.now(),
-    };
-  }
-
-  function parseReadinessProbeAck(value) {
-    if (!value || value.type !== APP_PROTOCOL.readinessProbeAck) {
-      return null;
-    }
-    const requestId = parseOptionalTrimmedString(value.requestId);
-    if (!requestId) {
-      return null;
-    }
-    return {
-      requestId,
-      ok: value.ok !== false,
-      reasonCode: parseOptionalTrimmedString(value.reasonCode),
-      message: parseOptionalTrimmedString(value.message),
-      activeSessionKey:
-        parseOptionalTrimmedString(value.activeSessionKey) ||
-        parseOptionalTrimmedString(value.sessionKey),
-      emittedAtMs: parseOptionalNonNegativeInt(value.emittedAtMs),
-    };
-  }
-
-  function describeProtocolClient(state) {
-    if (!state) return "unknown";
-    const clientName = parseOptionalTrimmedString(state.clientName);
-    const clientVersion = parseOptionalTrimmedString(state.clientVersion);
-    if (clientName && clientVersion) {
-      return `${clientName}/${clientVersion}`;
-    }
-    return clientName || "unknown";
-  }
-
-  function classifyClientKindFromName(clientName) {
-    const normalizedName = parseOptionalTrimmedString(clientName);
-    if (!normalizedName) return "unknown";
-    const normalized = normalizedName.toLowerCase();
-    if (normalized === "debugctl") {
-      return "debug";
-    }
-    return "app";
-  }
-
-  function classifyClientKind(state) {
-    if (!state) return "unknown";
-    const clientName = parseOptionalTrimmedString(state.clientName);
-    if (!clientName) return "unknown";
-    return classifyClientKindFromName(clientName);
-  }
-
-  function countConnectedAppClients(excludeClientId = null) {
-    let count = 0;
-    for (const [clientId, ws] of clients) {
-      if (excludeClientId && clientId === excludeClientId) {
-        continue;
-      }
-      if (!ws || ws.readyState !== WebSocket.OPEN) {
-        continue;
-      }
-      if (classifyClientKind(protocolState.get(clientId)) !== "app") {
-        continue;
-      }
-      count += 1;
-    }
-    return count;
-  }
-
-  function isAppClient(clientId) {
-    return classifyClientKind(protocolState.get(clientId)) === "app";
-  }
-
-  function closeConnectedAppClients(opts = {}) {
-    const excludeClientId = parseOptionalTrimmedString(opts.excludeClientId);
-    const requestedReason = parseOptionalTrimmedString(opts.reason);
-    const reason = requestedReason || "debug_injected_transport_loss";
-    const closedClientIds = [];
-    for (const [clientId, ws] of clients) {
-      if (excludeClientId && clientId === excludeClientId) {
-        continue;
-      }
-      if (!isAppClient(clientId)) {
-        continue;
-      }
-      if (
-        !ws ||
-        (ws.readyState !== WebSocket.OPEN && ws.readyState !== WebSocket.CONNECTING)
-      ) {
-        continue;
-      }
-      const protocol = protocolState.get(clientId);
-      logger.warn(
-        `[downstream] ${clientId} debug injected transport loss reason="${reason}" client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"}`,
-      );
-      if (typeof ws.terminate === "function") {
-        ws.terminate();
-      } else {
-        ws.close(1012, reason);
-      }
-      closedClientIds.push(clientId);
-    }
-    return {
-      closedCount: closedClientIds.length,
-      closedClientIds,
-      reason,
-    };
-  }
-
-  function interactionStageBucket(stage) {
-    switch (stage) {
-      case "listening":
-      case "voice_handoff":
-      case "thinking":
-        return "active_non_stream";
-      case "streaming":
-      case "post_turn_drain":
-        return "active_stream";
-      default:
-        return "idle";
-    }
-  }
-
-  function formatProtocolHelloAck(payload) {
-    return JSON.stringify({
-      type: "protocolHelloAck",
-      protocolVersion: payload.protocolVersion,
-      supportedProtocolVersions: payload.supportedProtocolVersions || ["v2"],
-      reason: payload.reason || null,
-      deprecatedV1: false,
-    });
-  }
-
-  function ensureProtocolState(clientId) {
-    let state = protocolState.get(clientId);
-    if (!state) {
-      state = {
-        selectedVersion: null,
-        supportedProtocolVersions: ["v2"],
-        clientName: null,
-        clientVersion: null,
-        sessionKey: null,
-        reason: null,
-      };
-      protocolState.set(clientId, state);
-    }
-    return state;
-  }
-
-  function createClientNudgeState() {
-    return {
-      visibilityState: null,
-      streamChars: null,
-      lastHeartbeatAtMs: null,
-      lastRelayStreamingActivityAtMs: null,
-      interactionStage: "idle",
-      cadenceBucket: "idle",
-      nudgeActive: false,
-      nudgeIntervalMs: null,
-      nudgeStartedAtMs: null,
-      lastNudgeAtMs: null,
-      stalledHeartbeatCount: 0,
-      nudgeTimer: null,
-      idleDeactivateTimer: null,
-      staleHeartbeatTimer: null,
-      hardTimeoutTimer: null,
-    };
-  }
-
-  function ensureClientNudgeState(clientId) {
-    let state = clientNudgeState.get(clientId);
-    if (!state) {
-      state = createClientNudgeState();
-      clientNudgeState.set(clientId, state);
-    }
-    return state;
-  }
-
-  function cloneClientNudgeState(state) {
-    if (!state) return null;
-    return {
-      visibilityState: state.visibilityState || null,
-      streamChars: Number.isFinite(state.streamChars) ? state.streamChars : null,
-      lastHeartbeatAtMs: Number.isFinite(state.lastHeartbeatAtMs)
-        ? state.lastHeartbeatAtMs
-        : null,
-      lastRelayStreamingActivityAtMs: Number.isFinite(
-        state.lastRelayStreamingActivityAtMs,
-      )
-        ? state.lastRelayStreamingActivityAtMs
-        : null,
-      interactionStage: state.interactionStage || "idle",
-      cadenceBucket: state.cadenceBucket || "idle",
-      nudgeActive: !!state.nudgeActive,
-      nudgeIntervalMs: Number.isFinite(state.nudgeIntervalMs)
-        ? state.nudgeIntervalMs
-        : null,
-      nudgeStartedAtMs: Number.isFinite(state.nudgeStartedAtMs)
-        ? state.nudgeStartedAtMs
-        : null,
-      lastNudgeAtMs: Number.isFinite(state.lastNudgeAtMs)
-        ? state.lastNudgeAtMs
-        : null,
-      stalledHeartbeatCount: Number.isFinite(state.stalledHeartbeatCount)
-        ? state.stalledHeartbeatCount
-        : 0,
-    };
-  }
-
-  function cloneReadinessBundleIdentity(value) {
-    if (!value) return null;
-    return {
-      kind: value.kind || null,
-      mode: value.mode || null,
-      host: value.host || null,
-      port: Number.isFinite(value.port) ? value.port : null,
-      servedDistPath: value.servedDistPath || null,
-    };
-  }
-
-  function cloneReadinessSnapshot(value) {
-    if (!value) return null;
-    return {
-      clientDebugEnabled:
-        value.clientDebugEnabled === true || value.clientDebugEnabled === false
-          ? value.clientDebugEnabled
-          : null,
-      runtimeDiagnosticsVisible:
-        value.runtimeDiagnosticsVisible === true ||
-        value.runtimeDiagnosticsVisible === false
-          ? value.runtimeDiagnosticsVisible
-          : null,
-      perfNoisyDebugMuted:
-        value.perfNoisyDebugMuted === true || value.perfNoisyDebugMuted === false
-          ? value.perfNoisyDebugMuted
-          : null,
-      perfPayloadLiteMode:
-        value.perfPayloadLiteMode === true || value.perfPayloadLiteMode === false
-          ? value.perfPayloadLiteMode
-          : null,
-      activeSessionKey: value.activeSessionKey || null,
-      bundleIdentity: cloneReadinessBundleIdentity(value.bundleIdentity),
-      emittedAtMs: Number.isFinite(value.emittedAtMs) ? value.emittedAtMs : null,
-      updatedAtMs: Number.isFinite(value.updatedAtMs) ? value.updatedAtMs : null,
-    };
-  }
-
-  function updateClientReadinessSnapshot(clientId, snapshot) {
-    if (!clientId || !snapshot) return null;
-    const next = cloneReadinessSnapshot({
-      ...snapshot,
-      updatedAtMs: Date.now(),
-    });
-    clientReadinessSnapshotState.set(clientId, next);
-    return next;
-  }
-
-  function clearPendingReadinessProbesForClient(clientId) {
-    if (!clientId) return;
-    for (const [requestId, pending] of pendingReadinessProbeRequests) {
-      if (!pending) continue;
-      if (
-        pending.requesterClientId === clientId ||
-        pending.targetClientId === clientId
-      ) {
-        pendingReadinessProbeRequests.delete(requestId);
-      }
-    }
-  }
-
-  function buildReadinessClientEntry(clientId) {
-    const protocol = protocolState.get(clientId);
-    return {
-      clientId,
-      clientKind: classifyClientKind(protocol),
-      clientName: protocol && protocol.clientName ? protocol.clientName : null,
-      clientVersion: protocol && protocol.clientVersion ? protocol.clientVersion : null,
-      protocolSessionKey: protocol && protocol.sessionKey ? protocol.sessionKey : null,
-      readinessSnapshot: cloneReadinessSnapshot(
-        clientReadinessSnapshotState.get(clientId) || null,
-      ),
-    };
-  }
-
-  function clearClientNudgeTimer(state, key, clearFn = clearTimeout) {
-    if (!state || !state[key]) return;
-    clearFn(state[key]);
-    state[key] = null;
-  }
-
-  function clearClientNudgeTimers(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    clearClientNudgeTimer(state, "staleHeartbeatTimer");
-    clearClientNudgeTimer(state, "hardTimeoutTimer");
-  }
-
-  function isStreamingBroadcastType(messageType) {
-    return (
-      messageType === "streaming" ||
-      messageType === "ocuclaw.message.stream.delta"
-    );
-  }
-
-  function isPagesBroadcastType(messageType) {
-    return messageType === "pages" || messageType === APP_PROTOCOL.pages;
-  }
-
-  function isActivityBroadcastType(messageType) {
-    return messageType === "activity" || messageType === "ocuclaw.activity.update";
-  }
-
-  function isListenCommittedBroadcastType(messageType) {
-    return messageType === "listen-committed";
-  }
-
-  function isListenEndedBroadcastType(messageType) {
-    return messageType === "listen-ended";
-  }
-
-  function resetClientStallTracking(state) {
-    if (!state) return;
-    state.stalledHeartbeatCount = 0;
-  }
-
-  function hasStaleHeartbeat(state, now = Date.now()) {
-    if (!state || !Number.isFinite(state.lastHeartbeatAtMs)) {
-      return false;
-    }
-    return now - state.lastHeartbeatAtMs >= nudgeStaleHeartbeatThresholdMs;
-  }
-
-  function isVisibilityDegraded(state) {
-    return (
-      !!state &&
-      (state.visibilityState === "hidden" || state.visibilityState === "blurred")
-    );
-  }
-
-  function sendRenderNudge(clientId) {
-    const ws = clients.get(clientId);
-    if (!ws || ws.readyState !== WebSocket.OPEN) {
-      stopClientNudges(clientId, "socket_unavailable");
-      return;
-    }
-    sendMessageToClient(clientId, ws, RENDER_NUDGE_FRAME);
-    ensureClientNudgeState(clientId).lastNudgeAtMs = Date.now();
-  }
-
-  function scheduleClientHardTimeout(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "hardTimeoutTimer");
-    if (!state.nudgeActive) return;
-    state.hardTimeoutTimer = setTimeout(() => {
-      state.hardTimeoutTimer = null;
-      setClientInteractionStage(clientId, "idle", {
-        reason: "nudge_hard_timeout",
-        deactivateImmediately: true,
-      });
-    }, nudgeHardTimeoutMs);
-  }
-
-  function startClientNudges(
-    clientId,
-    intervalMs,
-    reason = "nudge_start",
-    sendImmediately = false,
-  ) {
-    if (!isAppClient(clientId)) return;
-    const ws = clients.get(clientId);
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    const state = ensureClientNudgeState(clientId);
-    const nextIntervalMs = Math.max(1, Math.floor(intervalMs));
-    const wasActive = !!state.nudgeActive;
-    const intervalChanged = state.nudgeIntervalMs !== nextIntervalMs;
-    state.cadenceBucket = interactionStageBucket(state.interactionStage);
-    if (!wasActive) {
-      state.nudgeActive = true;
-      state.nudgeStartedAtMs = Date.now();
-    }
-    if (wasActive && !intervalChanged) {
-      return;
-    }
-    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
-    state.nudgeActive = true;
-    state.nudgeIntervalMs = nextIntervalMs;
-    state.nudgeTimer = setInterval(() => {
-      sendRenderNudge(clientId);
-    }, nextIntervalMs);
-    if (!wasActive) {
-      scheduleClientHardTimeout(clientId);
-      if (sendImmediately) {
-        sendRenderNudge(clientId);
-      }
-    }
-  }
-
-  function stopClientNudges(clientId, _reason = "nudge_stop") {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    clearClientNudgeTimer(state, "hardTimeoutTimer");
-    state.nudgeActive = false;
-    state.nudgeIntervalMs = null;
-    state.nudgeStartedAtMs = null;
-    resetClientStallTracking(state);
-    scheduleClientStaleHeartbeatCheck(clientId);
-  }
-
-  function scheduleClientIdleDeactivation(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    if (!state.nudgeActive || state.interactionStage !== "idle") {
-      return;
-    }
-    state.idleDeactivateTimer = setTimeout(() => {
-      state.idleDeactivateTimer = null;
-      const currentState = clientNudgeState.get(clientId);
-      if (!currentState || currentState.interactionStage !== "idle") {
-        return;
-      }
-      stopClientNudges(clientId, "idle_grace_elapsed");
-    }, nudgeIdleDeactivateMs);
-  }
-
-  function scheduleClientStaleHeartbeatCheck(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "staleHeartbeatTimer");
-    if (
-      state.nudgeActive ||
-      interactionStageBucket(state.interactionStage) === "idle" ||
-      !Number.isFinite(state.lastHeartbeatAtMs)
-    ) {
-      return;
-    }
-    const delayMs = Math.max(
-      0,
-      (state.lastHeartbeatAtMs + nudgeStaleHeartbeatThresholdMs) - Date.now(),
-    );
-    state.staleHeartbeatTimer = setTimeout(() => {
-      state.staleHeartbeatTimer = null;
-      const currentState = clientNudgeState.get(clientId);
-      if (
-        !currentState ||
-        currentState.nudgeActive ||
-        interactionStageBucket(currentState.interactionStage) === "idle"
-      ) {
-        return;
-      }
-      if (!hasStaleHeartbeat(currentState)) {
-        scheduleClientStaleHeartbeatCheck(clientId);
-        return;
-      }
-      startClientNudges(
-        clientId,
-        nudgeActiveIntervalMs,
-        "stale_heartbeat_fallback",
-        true,
-      );
-    }, delayMs);
-  }
-
-  function maybeActivateClientNudges(clientId, reason = "nudge_eval") {
-    const state = clientNudgeState.get(clientId);
-    if (!state || !isAppClient(clientId)) return;
-    state.cadenceBucket = interactionStageBucket(state.interactionStage);
-    if (state.cadenceBucket === "idle") {
-      clearClientNudgeTimer(state, "staleHeartbeatTimer");
-      return;
-    }
-    if (state.nudgeActive) {
-      return;
-    }
-    if (isVisibilityDegraded(state) || hasStaleHeartbeat(state)) {
-      startClientNudges(clientId, nudgeActiveIntervalMs, reason, true);
-      return;
-    }
-    scheduleClientStaleHeartbeatCheck(clientId);
-  }
-
-  function setClientInteractionStage(clientId, nextStage, options = {}) {
-    if (!isAppClient(clientId)) return;
-    const state = ensureClientNudgeState(clientId);
-    const reason = options.reason || "interaction_stage";
-    const deactivateImmediately = options.deactivateImmediately === true;
-    state.interactionStage = nextStage;
-    state.cadenceBucket = interactionStageBucket(nextStage);
-    if (state.cadenceBucket !== "active_stream") {
-      resetClientStallTracking(state);
-    }
-    if (state.cadenceBucket === "idle") {
-      clearClientNudgeTimer(state, "staleHeartbeatTimer");
-      if (deactivateImmediately) {
-        stopClientNudges(clientId, reason);
-      } else {
-        scheduleClientIdleDeactivation(clientId);
-      }
-      return;
-    }
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    if (
-      state.cadenceBucket === "active_non_stream" &&
-      state.nudgeActive &&
-      state.nudgeIntervalMs !== nudgeActiveIntervalMs
-    ) {
-      startClientNudges(clientId, nudgeActiveIntervalMs, reason, false);
-    }
-    maybeActivateClientNudges(clientId, reason);
-  }
-
-  function observeRelayStreamingActivity(clientId, atMs) {
-    if (!isAppClient(clientId)) return;
-    const state = ensureClientNudgeState(clientId);
-    state.lastRelayStreamingActivityAtMs = atMs;
-    resetClientStallTracking(state);
-    if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
-      startClientNudges(clientId, nudgeActiveIntervalMs, "relay_stream_progress");
-      return;
-    }
-    maybeActivateClientNudges(clientId, "relay_stream_activity");
-  }
-
-  function updateClientNudgeHeartbeat(clientId, ping) {
-    const state = ensureClientNudgeState(clientId);
-    const previousHeartbeatAtMs = Number.isFinite(state.lastHeartbeatAtMs)
-      ? state.lastHeartbeatAtMs
-      : null;
-    const previousStreamChars = Number.isFinite(state.streamChars)
-      ? state.streamChars
-      : null;
-    const nextStreamChars = Number.isFinite(ping.streamChars) ? ping.streamChars : null;
-    const streamAdvanced =
-      nextStreamChars !== null &&
-      (previousStreamChars === null || nextStreamChars > previousStreamChars);
-    const relayStreamAdvanced =
-      previousHeartbeatAtMs !== null &&
-      Number.isFinite(state.lastRelayStreamingActivityAtMs) &&
-      state.lastRelayStreamingActivityAtMs > previousHeartbeatAtMs;
-    state.streamChars = nextStreamChars;
-    if (ping.visibilityState) {
-      state.visibilityState = ping.visibilityState;
-    }
-    state.lastHeartbeatAtMs = Date.now();
-    state.cadenceBucket = interactionStageBucket(state.interactionStage);
-    if (state.visibilityState === "visible") {
-      stopClientNudges(clientId, "heartbeat_visible");
-    }
-    if (state.cadenceBucket === "active_stream") {
-      if (streamAdvanced || relayStreamAdvanced) {
-        resetClientStallTracking(state);
-        if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
-          startClientNudges(
-            clientId,
-            nudgeActiveIntervalMs,
-            streamAdvanced
-              ? "heartbeat_stream_progress"
-              : "relay_stream_progress",
-            false,
-          );
-        }
-      } else if (state.nudgeActive) {
-        state.stalledHeartbeatCount += 1;
-        if (
-          state.stalledHeartbeatCount >= 3 &&
-          state.nudgeIntervalMs !== nudgeSlowIntervalMs
-        ) {
-          startClientNudges(
-            clientId,
-            nudgeSlowIntervalMs,
-            "stream_stalled_decelerated",
-            false,
-          );
-        }
-      }
-    } else {
-      resetClientStallTracking(state);
-      if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
-        startClientNudges(clientId, nudgeActiveIntervalMs, "non_stream_fast", false);
-      }
-    }
-    maybeActivateClientNudges(clientId, "heartbeat_update");
-  }
-
-  function updateClientVisibilityState(clientId, visibilityState) {
-    const state = ensureClientNudgeState(clientId);
-    state.visibilityState = visibilityState;
-    if (visibilityState === "visible") {
-      stopClientNudges(clientId, "visibility_visible");
-      return;
-    }
-    maybeActivateClientNudges(clientId, "visibility_hidden");
-  }
-
-  function applyBroadcastInteractionStage(messageType, parsed, relayStreamingActivityAtMs) {
-    for (const [clientId] of clients) {
-      if (!isAppClient(clientId)) {
-        continue;
-      }
-      if (relayStreamingActivityAtMs !== null) {
-        setClientInteractionStage(clientId, "streaming", {
-          reason: "relay_streaming",
-        });
-        observeRelayStreamingActivity(clientId, relayStreamingActivityAtMs);
-        continue;
-      }
-      if (isListenCommittedBroadcastType(messageType)) {
-        setClientInteractionStage(clientId, "voice_handoff", {
-          reason: "listen_committed",
-        });
-        continue;
-      }
-      if (isListenEndedBroadcastType(messageType)) {
-        setClientInteractionStage(clientId, "idle", {
-          reason: "listen_ended",
-          deactivateImmediately: true,
-        });
-        continue;
-      }
-      if (isActivityBroadcastType(messageType)) {
-        const activityState = parseOptionalTrimmedString(parsed && parsed.state);
-        const normalizedActivity = activityState ? activityState.toLowerCase() : null;
-        const currentStage = ensureClientNudgeState(clientId).interactionStage;
-        if (normalizedActivity === "thinking") {
-          setClientInteractionStage(clientId, "thinking", {
-            reason: "activity_thinking",
-          });
-        } else if (normalizedActivity === "idle") {
-          if (currentStage === "streaming" || currentStage === "post_turn_drain") {
-            setClientInteractionStage(clientId, "post_turn_drain", {
-              reason: "activity_idle_stream_drain",
-            });
-          } else {
-            setClientInteractionStage(clientId, "idle", {
-              reason: "activity_idle",
-            });
-          }
-        }
-        continue;
-      }
-      if (isPagesBroadcastType(messageType)) {
-        const currentState = ensureClientNudgeState(clientId);
-        if (interactionStageBucket(currentState.interactionStage) !== "idle") {
-          setClientInteractionStage(clientId, "post_turn_drain", {
-            reason: "pages_snapshot",
-          });
-        }
-      }
-    }
-  }
-
-  function updateProtocolSessionKey(clientId, value) {
-    const sessionKey = parseOptionalTrimmedString(value);
-    if (!sessionKey) return;
-    ensureProtocolState(clientId).sessionKey = sessionKey;
-  }
-
-  function updateProtocolState(clientId, overrides = {}) {
-    const state = ensureProtocolState(clientId);
-    if (overrides.supportedProtocolVersions) {
-      state.supportedProtocolVersions = parseSupportedProtocolVersions(
-        overrides.supportedProtocolVersions,
-      );
-    }
-    if (overrides.clientName) {
-      state.clientName = parseOptionalTrimmedString(overrides.clientName);
-    }
-    if (overrides.clientVersion) {
-      state.clientVersion = parseOptionalTrimmedString(overrides.clientVersion);
-    }
-    if (overrides.sessionKey) {
-      state.sessionKey = parseOptionalTrimmedString(overrides.sessionKey);
-    }
-    if (overrides.selectedVersion !== undefined) {
-      state.selectedVersion = overrides.selectedVersion;
-    }
-    if (overrides.reason !== undefined) {
-      state.reason = overrides.reason || null;
-    }
-    return state;
-  }
-
-  function clearSyncTimer(clientId) {
-    const sync = syncState.get(clientId);
-    if (sync && sync.timer) {
-      clearTimeout(sync.timer);
-      sync.timer = null;
-    }
-  }
-
-  function closeForProtocolViolation(clientId, ws, reason, overrides = {}) {
-    updateProtocolState(clientId, { ...overrides, reason });
-    clearSyncTimer(clientId);
-    if (
-      ws &&
-      (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)
-    ) {
-      ws.close(1008, reason);
-    }
-  }
-
-  function armResumeHandshakeTimeout(clientId, ws) {
-    const sync = syncState.get(clientId);
-    if (!sync) return;
-    clearSyncTimer(clientId);
-    sync.timer = setTimeout(() => {
-      sync.timer = null;
-      syncSnapshotForClient(clientId, ws, "connect_timeout", null);
-    }, resumeHandshakeTimeoutMs);
-  }
-
-  function sendMessageToClient(clientId, ws, message) {
-    if (!ws || ws.readyState !== WebSocket.OPEN) {
-      return;
-    }
-    ws.send(message);
-  }
-
-  function forwardReadinessProbeAck(clientId, ack) {
-    if (!ack || !ack.requestId) {
-      return;
-    }
-    const pending = pendingReadinessProbeRequests.get(ack.requestId);
-    if (!pending || pending.targetClientId !== clientId) {
-      return;
-    }
-    pendingReadinessProbeRequests.delete(ack.requestId);
-    const requesterWs = clients.get(pending.requesterClientId);
-    if (!requesterWs || requesterWs.readyState !== WebSocket.OPEN) {
-      return;
-    }
-    const protocol = protocolState.get(clientId);
-    const message =
-      handler && typeof handler.formatReadinessProbeAck === "function"
-        ? handler.formatReadinessProbeAck({
-            ok: ack.ok !== false,
-            requestId: ack.requestId,
-            reasonCode: ack.reasonCode || null,
-            message: ack.message || null,
-            activeSessionKey: ack.activeSessionKey || null,
-            emittedAtMs: ack.emittedAtMs,
-            clientId,
-            clientName: protocol && protocol.clientName ? protocol.clientName : null,
-            clientVersion:
-              protocol && protocol.clientVersion ? protocol.clientVersion : null,
-          })
-        : JSON.stringify({
-            type: APP_PROTOCOL.readinessProbeAck,
-            ok: ack.ok !== false,
-            requestId: ack.requestId,
-            reasonCode: ack.reasonCode || null,
-            message: ack.message || null,
-            activeSessionKey: ack.activeSessionKey || null,
-            emittedAtMs: ack.emittedAtMs,
-            clientId,
-            clientName: protocol && protocol.clientName ? protocol.clientName : null,
-            clientVersion:
-              protocol && protocol.clientVersion ? protocol.clientVersion : null,
-          });
-    sendMessageToClient(pending.requesterClientId, requesterWs, message);
-  }
-
-  function getServerResumeState() {
-    if (!getCurrentResumeState) {
-      return { pagesRevision: null, statusRevision: null };
-    }
-    const state = getCurrentResumeState() || {};
-    return {
-      pagesRevision: parseRevision(state.pagesRevision),
-      statusRevision: parseRevision(state.statusRevision),
-    };
-  }
-
-  function formatResumeAck(payload) {
-    return JSON.stringify({
-      type: APP_PROTOCOL.resumeAck,
-      reason: payload.reason || null,
-      sentPages: !!payload.sentPages,
-      sentStatus: !!payload.sentStatus,
-      sentApprovals:
-        Number.isFinite(payload.sentApprovals) && payload.sentApprovals > 0
-          ? Math.floor(payload.sentApprovals)
-          : 0,
-      pagesRevision:
-        payload.pagesRevision === null || payload.pagesRevision === undefined
-          ? null
-          : payload.pagesRevision,
-      statusRevision:
-        payload.statusRevision === null || payload.statusRevision === undefined
-          ? null
-          : payload.statusRevision,
-    });
-  }
-
-  function isSnapshotSynced(sync) {
-    return (
-      !!sync &&
-      sync.pagesSynced &&
-      sync.statusSynced &&
-      sync.approvalsSynced &&
-      sync.debugConfigSynced
-    );
-  }
-
-  function markClientSyncedForType(clientId, messageType) {
-    const sync = syncState.get(clientId);
-    if (!sync) return;
-    if (messageType === "pages" || messageType === APP_PROTOCOL.pages) {
-      sync.pagesSynced = true;
-    }
-    if (messageType === "status" || messageType === APP_PROTOCOL.status) {
-      sync.statusSynced = true;
-    }
-    if (messageType === APP_PROTOCOL.debugConfigSnapshot) {
-      sync.debugConfigSynced = true;
-    }
-    if (isSnapshotSynced(sync) && sync.timer) {
-      clearTimeout(sync.timer);
-      sync.timer = null;
-    }
-  }
-
-  function syncSnapshotForClient(clientId, ws, reason, resumeRequest) {
-    const sync = syncState.get(clientId);
-    if (!sync || isSnapshotSynced(sync)) {
-      const state = getServerResumeState();
-      return {
-        reason,
-        sentPages: false,
-        sentStatus: false,
-        sentApprovals: 0,
-        pagesRevision: state.pagesRevision,
-        statusRevision: state.statusRevision,
-      };
-    }
-
-    if (sync.timer) {
-      clearTimeout(sync.timer);
-      sync.timer = null;
-    }
-
-    const pages = getCurrentPages();
-    const status = getCurrentStatus();
-    const debugConfig = getCurrentDebugConfig ? getCurrentDebugConfig() : null;
-    const state = getServerResumeState();
-    const clientPagesRevision = parseRevision(
-      resumeRequest && resumeRequest.pagesRevision,
-    );
-    const clientStatusRevision = parseRevision(
-      resumeRequest && resumeRequest.statusRevision,
-    );
-    const clientHasPagesState = parseBool(
-      resumeRequest && resumeRequest.hasPagesState,
-    );
-    const clientHasStatusState = parseBool(
-      resumeRequest && resumeRequest.hasStatusState,
-    );
-    const pagesInSync =
-      clientHasPagesState &&
-      state.pagesRevision !== null &&
-      clientPagesRevision !== null &&
-      state.pagesRevision === clientPagesRevision;
-    let sentPages = false;
-    let sentStatus = false;
-    let sentApprovals = 0;
-    let sentDebugConfig = false;
-    if (!sync.pagesSynced) {
-      if (pages === null || pagesInSync) {
-        sync.pagesSynced = true;
-      } else if (ws.readyState === WebSocket.OPEN) {
-        sendMessageToClient(clientId, ws, pages);
-        sentPages = true;
-        sync.pagesSynced = true;
-      }
-    }
-    if (!sync.statusSynced) {
-      // Always replay the current status once per downstream reconnect. The client
-      // uses that fresh status snapshot to clear reconnect UI even when revisions
-      // appear to match after a relay restart.
-      if (status === null) {
-        sync.statusSynced = true;
-      } else if (ws.readyState === WebSocket.OPEN) {
-        sendMessageToClient(clientId, ws, status);
-        sentStatus = true;
-        sync.statusSynced = true;
-      }
-    }
-    if (!sync.approvalsSynced) {
-      if (unresolvedApprovals.size === 0) {
-        sync.approvalsSynced = true;
-      } else {
-        for (const approvalMessage of unresolvedApprovals.values()) {
-          if (ws.readyState !== WebSocket.OPEN) {
-            break;
-          }
-          sendMessageToClient(clientId, ws, approvalMessage);
-          sentApprovals += 1;
-        }
-        sync.approvalsSynced = ws.readyState === WebSocket.OPEN;
-      }
-    }
-    if (!sync.debugConfigSynced) {
-      if (!isAppClient(clientId) || debugConfig === null) {
-        sync.debugConfigSynced = true;
-      } else if (ws.readyState === WebSocket.OPEN) {
-        sendMessageToClient(clientId, ws, debugConfig);
-        sentDebugConfig = true;
-        sync.debugConfigSynced = true;
-      }
-    }
-    if (isSnapshotSynced(sync) && sync.timer) {
-      clearTimeout(sync.timer);
-      sync.timer = null;
-    }
-
-    return {
-      reason,
-      sentPages,
-      sentStatus,
-      sentApprovals,
-      sentDebugConfig,
-      pagesRevision: state.pagesRevision,
-      statusRevision: state.statusRevision,
-    };
-  }
-
-  // When an httpServer is provided, attach to it via noServer mode so HTTP
-  // and WebSocket share a single port.  Otherwise listen on a standalone port
-  // (used when HTTP is disabled and in tests).
-  let wss;
-  if (opts.httpServer) {
-    wss = new WebSocketServer({ noServer: true });
-    opts.httpServer.on("upgrade", (req, socket, head) => {
-      const url = new URL(req.url, `http://${req.headers.host}`);
-      if (url.searchParams.get("token") !== token) {
-        socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
-        socket.destroy();
-        return;
-      }
-      wss.handleUpgrade(req, socket, head, (ws) => {
-        wss.emit("connection", ws, req);
-      });
-    });
-  } else {
-    wss = new WebSocketServer({
-      host: opts.host,
-      port: opts.port,
-      verifyClient: ({ req }) => {
-        const url = new URL(req.url, `http://${req.headers.host}`);
-        return url.searchParams.get("token") === token;
-      },
-    });
-  }
-
-  wss.on("connection", (ws, req) => {
-    const clientId = `client-${nextClientId++}`;
-    clients.set(clientId, ws);
-    const connectedAtMs = Date.now();
-    const remoteAddress =
-      (req && req.socket && req.socket.remoteAddress) || "unknown";
-    const userAgent =
-      (req && req.headers && req.headers["user-agent"]) || "unknown";
-    const clientMeta = {
-      role: "unknown",
-      firstMessageType: null,
-      textMessageCount: 0,
-      binaryMessageCount: 0,
-      remoteControlCount: 0,
-      connectedEventEmitted: false,
-    };
-    ensureProtocolState(clientId);
-    clientNudgeState.set(clientId, createClientNudgeState());
-    const currentPages = getCurrentPages();
-    const currentStatus = getCurrentStatus();
-    syncState.set(clientId, {
-      pagesSynced: currentPages === null,
-      statusSynced: currentStatus === null,
-      approvalsSynced: unresolvedApprovals.size === 0,
-      debugConfigSynced: !getCurrentDebugConfig,
-      resumeReceived: false,
-      timer: null,
-    });
-    const sync = syncState.get(clientId);
-    if (sync) {
-      sync.timer = setTimeout(() => {
-        sync.timer = null;
-        closeForProtocolViolation(clientId, ws, "protocol_hello_timeout");
-      }, protocolHelloTimeoutMs);
-    }
-    logger.info(
-      `[downstream] ${clientId} connected (${clients.size} total) ip=${remoteAddress} ua=${truncateForLog(String(userAgent), 100)}`,
-    );
-
-    ws.on("error", (err) => {
-      logger.error(`[downstream] ${clientId} error: ${err.message}`);
-    });
-
-    ws.on("message", (data, isBinary) => {
-      // Legacy downstream binary voice transport was removed. Ignore binary frames.
-      if (isBinary) {
-        clientMeta.binaryMessageCount += 1;
-        return;
-      }
-
-      clientMeta.textMessageCount += 1;
-      const raw = data.toString();
-      let parsed = null;
-      try {
-        parsed = JSON.parse(raw);
-      } catch (_) {
-        parsed = null;
-      }
-
-      const protocolHello = parseProtocolHello(parsed);
-
-      if (parsed && typeof parsed.type === "string") {
-        const clientKind = protocolHello
-          ? classifyClientKindFromName(protocolHello.clientName)
-          : "unknown";
-        updateClientRole(clientMeta, parsed.type, clientKind);
-        if (parsed.type === "remote-control") {
-          clientMeta.remoteControlCount += 1;
-        }
-        updateProtocolSessionKey(clientId, parsed.sessionKey);
-      }
-
-      const enrichedPing = parseEnrichedPing(parsed);
-
-      // Intercept application-level ping — respond with pong, skip handler
-      if (enrichedPing) {
-        updateClientNudgeHeartbeat(clientId, enrichedPing);
-        ws.send(JSON.stringify({ type: "pong", ts: parsed.ts }));
-        return;
-      }
-
-      if (protocolHello) {
-        if (!protocolHello.supportedProtocolVersions.includes("v2")) {
-          closeForProtocolViolation(clientId, ws, "protocol_v2_required", {
-            supportedProtocolVersions: protocolHello.supportedProtocolVersions,
-            clientName: protocolHello.clientName,
-            clientVersion: protocolHello.clientVersion,
-            sessionKey: protocolHello.sessionKey,
-          });
-          return;
-        }
-        const protocolClientKind = classifyClientKindFromName(
-          protocolHello.clientName,
-        );
-        if (!externalDebugToolsEnabled && protocolClientKind === "debug") {
-          closeForProtocolViolation(clientId, ws, "external_debug_tools_disabled", {
-            supportedProtocolVersions: protocolHello.supportedProtocolVersions,
-            clientName: protocolHello.clientName,
-            clientVersion: protocolHello.clientVersion,
-            sessionKey: protocolHello.sessionKey,
-          });
-          return;
-        }
-        const state = updateProtocolState(clientId, {
-          selectedVersion: "v2",
-          reason: "negotiated_v2",
-          supportedProtocolVersions: protocolHello.supportedProtocolVersions,
-          clientName: protocolHello.clientName,
-          clientVersion: protocolHello.clientVersion,
-          sessionKey: protocolHello.sessionKey,
-        });
-        if (protocolHello.readinessSnapshot) {
-          updateClientReadinessSnapshot(clientId, protocolHello.readinessSnapshot);
-        }
-        logger.info(
-          `[downstream] ${clientId} identified protocol=${state.selectedVersion || "n/a"} client=${describeProtocolClient(state)} kind=${classifyClientKind(state)} session=${state.sessionKey || "n/a"}`,
-        );
-        if (!clientMeta.connectedEventEmitted) {
-          clientMeta.connectedEventEmitted = true;
-          if (onClientConnected) {
-            onClientConnected({
-              clientId,
-              connectedCount: countConnectedAppClients(),
-              connectedAtMs,
-              remoteAddress,
-              userAgent: truncateForLog(String(userAgent), 180),
-              role: clientMeta.role,
-              protocolVersion: state.selectedVersion || null,
-              protocolReason: state.reason || null,
-              clientKind: classifyClientKind(state),
-              clientName: state.clientName || null,
-              clientVersion: state.clientVersion || null,
-              sessionKey: state.sessionKey || null,
-            });
-          }
-        }
-        armResumeHandshakeTimeout(clientId, ws);
-        if (ws.readyState === WebSocket.OPEN) {
-          ws.send(
-            formatProtocolHelloAck({
-              protocolVersion: state.selectedVersion || "v2",
-              supportedProtocolVersions: ["v2"],
-              reason: state.reason,
-            }),
-          );
-        }
-        return;
-      }
-
-      const state = ensureProtocolState(clientId);
-      if (!state.selectedVersion && parsed && typeof parsed.type === "string") {
-        closeForProtocolViolation(clientId, ws, "protocol_hello_required", {
-          clientName: parsed.clientName,
-          clientVersion: parsed.clientVersion,
-          sessionKey: parsed.sessionKey,
-        });
-        return;
-      }
-
-      if (
-        state.selectedVersion === "v2" &&
-        parsed &&
-        REMOVED_V1_APP_TYPES.has(parsed.type)
-      ) {
-        return;
-      }
-
-      if (parsed && parsed.type === APP_PROTOCOL.readinessSnapshot) {
-        if (classifyClientKind(state) === "app") {
-          updateClientReadinessSnapshot(clientId, parsed);
-        }
-        return;
-      }
-
-      const readinessProbeAck = parseReadinessProbeAck(parsed);
-      if (readinessProbeAck) {
-        if (classifyClientKind(state) === "app") {
-          forwardReadinessProbeAck(clientId, readinessProbeAck);
-        }
-        return;
-      }
-
-      if (parsed && parsed.type === APP_PROTOCOL.resume) {
-        const sync = syncState.get(clientId);
-        if (sync) sync.resumeReceived = true;
-        const ack = syncSnapshotForClient(clientId, ws, "resume", parsed);
-        if (ws.readyState === WebSocket.OPEN) {
-          sendMessageToClient(clientId, ws, formatResumeAck(ack));
-        }
-        return;
-      }
-
-      const visibilityControl = parseVisibilityControl(parsed);
-      const drainCompleteControl = parseDrainCompleteControl(parsed);
-      const transportControl = visibilityControl || drainCompleteControl;
-      if (transportControl) {
-        const protocol = protocolState.get(clientId);
-        if (transportControl.type === "visibility") {
-          updateClientVisibilityState(clientId, transportControl.state);
-        } else {
-          setClientInteractionStage(clientId, "idle", {
-            reason: "drain_complete",
-            deactivateImmediately: true,
-          });
-        }
-        const meta = {
-          clientId,
-          controlType: transportControl.type,
-          state: transportControl.type === "visibility" ? transportControl.state : null,
-          connectedCount: countConnectedAppClients(),
-          role: clientMeta.role,
-          clientKind: classifyClientKind(protocol),
-          clientName: protocol && protocol.clientName ? protocol.clientName : null,
-          clientVersion: protocol && protocol.clientVersion ? protocol.clientVersion : null,
-          protocolVersion:
-            protocol && protocol.selectedVersion ? protocol.selectedVersion : null,
-          sessionKey: protocol && protocol.sessionKey ? protocol.sessionKey : null,
-        };
-        if (transportControl.type === "visibility") {
-          logger.info(
-            `[downstream] ${clientId} transport visibility state=${transportControl.state} client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"}`,
-          );
-        } else {
-          logger.info(
-            `[downstream] ${clientId} transport control=${transportControl.type} client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"}`,
-          );
-        }
-        if (onTransportControl) {
-          onTransportControl(meta);
-        }
-        return;
-      }
-
-      const result = handler.handleMessage(clientId, raw);
-      processResult(clientId, result);
-    });
-
-    ws.on("close", (code, reasonBuffer) => {
-      const sync = syncState.get(clientId);
-      if (sync && sync.timer) {
-        clearTimeout(sync.timer);
-      }
-      const protocol = protocolState.get(clientId);
-      syncState.delete(clientId);
-      protocolState.delete(clientId);
-      clientReadinessSnapshotState.delete(clientId);
-      clearPendingReadinessProbesForClient(clientId);
-      clearClientNudgeTimers(clientId);
-      clientNudgeState.delete(clientId);
-      handler.removeClient(clientId);
-      clients.delete(clientId);
-      const lifetimeMs = Date.now() - connectedAtMs;
-      const reason =
-        reasonBuffer && reasonBuffer.length > 0
-          ? truncateForLog(reasonBuffer.toString("utf8").replace(/\s+/g, " "), 120)
-          : "";
-      logger.info(
-        `[downstream] ${clientId} disconnected (${clients.size} total) code=${code} reason="${reason}" lifetimeMs=${lifetimeMs} role=${clientMeta.role} client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} protocol=${protocol && protocol.selectedVersion ? protocol.selectedVersion : "n/a"} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"} firstType=${clientMeta.firstMessageType || "n/a"} textMsgs=${clientMeta.textMessageCount} binMsgs=${clientMeta.binaryMessageCount} remoteCtrlMsgs=${clientMeta.remoteControlCount}`,
-      );
-      if (onClientDisconnected && clientMeta.connectedEventEmitted) {
-        onClientDisconnected({
-          clientId,
-          connectedCount: countConnectedAppClients(),
-          connectedAtMs,
-          lifetimeMs,
-          closeCode: code,
-          closeReason: reason,
-          role: clientMeta.role,
-          protocolVersion:
-            protocol && protocol.selectedVersion ? protocol.selectedVersion : null,
-          protocolReason: protocol && protocol.reason ? protocol.reason : null,
-          clientKind: classifyClientKind(protocol),
-          clientName: protocol && protocol.clientName ? protocol.clientName : null,
-          clientVersion:
-            protocol && protocol.clientVersion ? protocol.clientVersion : null,
-          sessionKey: protocol && protocol.sessionKey ? protocol.sessionKey : null,
-          firstMessageType: clientMeta.firstMessageType || null,
-          textMessageCount: clientMeta.textMessageCount,
-          binaryMessageCount: clientMeta.binaryMessageCount,
-          remoteControlCount: clientMeta.remoteControlCount,
-        });
-      }
-    });
-  });
-
-  /**
-   * Process the result from handler.handleMessage.
-   *
-   * Handles both synchronous values and promises. Dispatches unicast
-   * or broadcast actions as appropriate.
-   *
-   * @param {string} senderId - Client ID that sent the original message
-   * @param {object|null|Promise} result - Handler return value
-   */
-  function processResult(senderId, result) {
-    if (result === null || result === undefined) {
-      return;
-    }
-
-    if (typeof result.then === "function") {
-      result.then(
-        (resolved) => processResult(senderId, resolved),
-        (err) => {
-          logger.error(
-            `[downstream] Error processing message from ${senderId}:`,
-            err,
-          );
-        },
-      );
-      return;
-    }
-
-    if (result.unicast) {
-      const ws = clients.get(senderId);
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        sendMessageToClient(senderId, ws, result.unicast);
-      }
-    }
-
-    if (result.readinessProbe) {
-      const requestId = parseOptionalTrimmedString(
-        result.readinessProbe.requestId,
-      );
-      const targetClientId = parseOptionalTrimmedString(
-        result.readinessProbe.targetClientId,
-      );
-      const message =
-        typeof result.readinessProbe.message === "string"
-          ? result.readinessProbe.message
-          : null;
-      const targetWs = targetClientId ? clients.get(targetClientId) : null;
-      if (
-        !requestId ||
-        !targetClientId ||
-        !message ||
-        !targetWs ||
-        targetWs.readyState !== WebSocket.OPEN ||
-        !isAppClient(targetClientId)
-      ) {
-        const requesterWs = clients.get(senderId);
-        if (
-          requesterWs &&
-          requesterWs.readyState === WebSocket.OPEN &&
-          handler &&
-          typeof handler.formatReadinessProbeAck === "function"
-        ) {
-          sendMessageToClient(
-            senderId,
-            requesterWs,
-            handler.formatReadinessProbeAck({
-              ok: false,
-              requestId,
-              reasonCode: "no_downstream_client",
-              message: "No downstream app client connected",
-            }),
-          );
-        }
-      } else {
-        pendingReadinessProbeRequests.set(requestId, {
-          requesterClientId: senderId,
-          targetClientId,
-          createdAtMs: Date.now(),
-        });
-        sendMessageToClient(targetClientId, targetWs, message);
-      }
-    }
-
-    if (result.broadcast) {
-      if (Array.isArray(result.broadcast)) {
-        for (const msg of result.broadcast) broadcast(msg);
-      } else {
-        broadcast(result.broadcast);
-      }
-    }
-
-    if (result.broadcastApp) {
-      if (Array.isArray(result.broadcastApp)) {
-        for (const msg of result.broadcastApp) broadcastApp(msg);
-      } else {
-        broadcastApp(result.broadcastApp);
-      }
-    }
-  }
-
-  /**
-   * Send a message to all connected clients.
-   *
-   * @param {string} message - JSON string to send
-   */
-  function broadcast(message) {
-    let messageType = null;
-    let parsed = null;
-    try {
-      parsed = JSON.parse(message);
-      if (parsed && typeof parsed.type === "string") {
-        messageType = parsed.type;
-      }
-    } catch (_) {
-      messageType = null;
-    }
-
-    if (
-      (messageType === "approval" || messageType === APP_PROTOCOL.approvalRequest) &&
-      parsed &&
-      typeof parsed.id === "string"
-    ) {
-      const approvalId = parsed.id.trim();
-      if (approvalId) {
-        unresolvedApprovals.set(approvalId, message);
-      }
-    } else if (
-      (messageType === "approvalResolved" ||
-        messageType === APP_PROTOCOL.approvalResolved) &&
-      parsed &&
-      typeof parsed.id === "string"
-    ) {
-      const approvalId = parsed.id.trim();
-      if (approvalId) {
-        unresolvedApprovals.delete(approvalId);
-      }
-    }
-
-    const relayStreamingActivityAtMs = isStreamingBroadcastType(messageType)
-      ? Date.now()
-      : null;
-    for (const [clientId, ws] of clients) {
-      if (ws.readyState === WebSocket.OPEN) {
-        sendMessageToClient(clientId, ws, message);
-        if (relayStreamingActivityAtMs !== null) {
-          ensureClientNudgeState(clientId).lastRelayStreamingActivityAtMs =
-            relayStreamingActivityAtMs;
-        }
-        if (
-          messageType === "pages" ||
-          messageType === "status" ||
-          messageType === APP_PROTOCOL.pages ||
-          messageType === APP_PROTOCOL.status
-        ) {
-          markClientSyncedForType(clientId, messageType);
-        }
-      }
-    }
-    applyBroadcastInteractionStage(messageType, parsed, relayStreamingActivityAtMs);
-  }
-
-  /**
-   * Send a message to all connected app/WebUI clients.
-   *
-   * @param {string} message - JSON string to send
-   */
-  function broadcastApp(message) {
-    let messageType = null;
-    try {
-      const parsed = JSON.parse(message);
-      if (parsed && typeof parsed.type === "string") {
-        messageType = parsed.type;
-      }
-    } catch (_) {
-      messageType = null;
-    }
-
-    for (const [clientId, ws] of clients) {
-      if (!isAppClient(clientId)) {
-        continue;
-      }
-      if (ws.readyState !== WebSocket.OPEN) {
-        continue;
-      }
-      sendMessageToClient(clientId, ws, message);
-      if (
-        messageType === "pages" ||
-        messageType === "status" ||
-        messageType === APP_PROTOCOL.pages ||
-        messageType === APP_PROTOCOL.status ||
-        messageType === APP_PROTOCOL.debugConfigSnapshot
-      ) {
-        markClientSyncedForType(clientId, messageType);
-      }
-    }
-  }
-
-  /**
-   * Send a message to a specific client.
-   *
-   * @param {string} clientId - Target client ID
-   * @param {string} message - JSON string to send
-   */
-  function unicast(clientId, message) {
-    const ws = clients.get(clientId);
-    if (ws && ws.readyState === WebSocket.OPEN) {
-      sendMessageToClient(clientId, ws, message);
-    }
-  }
-
-  /**
-   * Get all connected client IDs.
-   *
-   * @returns {string[]}
-   */
-  function getClientIds() {
-    return Array.from(clients.keys());
-  }
-
-  function getConnectedAppCount(excludeClientId = null) {
-    return countConnectedAppClients(excludeClientId);
-  }
-
-  function getReadinessSnapshot() {
-    const clientsOut = [];
-    let latestUpdatedAtMs = null;
-    for (const [clientId, ws] of clients) {
-      if (!ws || ws.readyState !== WebSocket.OPEN) {
-        continue;
-      }
-      if (!isAppClient(clientId)) {
-        continue;
-      }
-      const entry = buildReadinessClientEntry(clientId);
-      clientsOut.push(entry);
-      const updatedAtMs =
-        entry &&
-        entry.readinessSnapshot &&
-        Number.isFinite(entry.readinessSnapshot.updatedAtMs)
-          ? entry.readinessSnapshot.updatedAtMs
-          : null;
-      if (updatedAtMs !== null && (latestUpdatedAtMs === null || updatedAtMs > latestUpdatedAtMs)) {
-        latestUpdatedAtMs = updatedAtMs;
-      }
-    }
-    clientsOut.sort((left, right) => String(left.clientId).localeCompare(String(right.clientId)));
-    return {
-      connectedClientCount: clientsOut.length,
-      fanoutRecipientCount: clientsOut.length,
-      updatedAtMs: latestUpdatedAtMs,
-      clients: clientsOut,
-    };
-  }
-
-  /**
-   * Shut down the WebSocket server and disconnect all clients.
-   *
-   * @returns {Promise<void>}
-   */
-  function close() {
-    return new Promise((resolve) => {
-      for (const [, sync] of syncState) {
-        if (sync.timer) clearTimeout(sync.timer);
-      }
-      syncState.clear();
-      for (const [clientId] of clientNudgeState) {
-        clearClientNudgeTimers(clientId);
-      }
-      clientNudgeState.clear();
-      clientReadinessSnapshotState.clear();
-      pendingReadinessProbeRequests.clear();
-      for (const [, ws] of clients) {
-        ws.close();
-      }
-      clients.clear();
-      wss.close(() => resolve());
-    });
-  }
-
-  return {
-    broadcast,
-    unicast,
-    getClientIds,
-    getConnectedAppCount,
-    getReadinessSnapshot,
-    closeConnectedAppClients,
-    getClientNudgeState(clientId) {
-      return cloneClientNudgeState(clientNudgeState.get(clientId) || null);
-    },
-    close,
-    get httpServer() {
-      return opts.httpServer || null;
-    },
-    /** Underlying WebSocket.Server (for reading address, etc.) */
-    get wss() {
-      return wss;
-    },
-  };
-}
-
-export { createDownstreamServer };