@livedesk/hub 0.1.74 → 0.1.76

package/src/console-direct.js

@@ -10,6 +10,12 @@ import {
 } from '../../runtime-core/src/console-direct-wire.js';
 import { workspaceRoleCanControl, workspaceRoleCanRequest } from './auth/workspace-access.js';
 import { createConsoleFrameAdmission } from './console-direct-frame-admission.mjs';
+import { createConsoleRouterMapping } from './console-router-mapping.mjs';
+import { createConsoleIceSetupGate } from './console-ice-setup-gate.mjs';
+import {
+  createConsoleIceEvidence, normalizeConsoleIcePortRange, recordConsoleIceCandidate, recordConsoleIceDescription,
+  retainConsoleIceRetirement, safeIceState, snapshotConsoleIceEvidence
+} from './console-direct-ice-evidence.mjs';
 
 const DEFAULT_SIGNAL_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
 const DEFAULT_STUN_URLS = Object.freeze(['stun:stun.cloudflare.com:3478']);
@@ -328,6 +334,10 @@ export function createHubConsoleDirect(options = {}) {
   const httpBaseUrl = String(options.httpBaseUrl || '').replace(/\/+$/, '');
   const canonicalHttpBaseUrl = normalizeHttpBaseUrl(httpBaseUrl);
   const stunUrls = normalizeStunUrls(options.stunUrls);
+  const icePortRange = normalizeConsoleIcePortRange(options.icePortRange);
+  const routerMapping = options.routerMapping || createConsoleRouterMapping({
+    isEnabled: options.isRouterMappingEnabled
+  });
   const SignalingWebSocketImpl = options.SignalingWebSocketImpl || options.WebSocketImpl || WebSocket;
   const LocalWebSocketImpl = options.LocalWebSocketImpl || options.WebSocketImpl || WebSocket;
   const fetchImpl = options.fetchImpl || globalThis.fetch;
@@ -380,6 +390,7 @@ export function createHubConsoleDirect(options = {}) {
     Number(options.logicalBindTimeoutMs) || LOGICAL_BIND_TIMEOUT_MS
   );
   const peers = new Map();
+  const recentPeerConnections = [];
   const revokedMembers = new Map();
   let signalSocket = null;
   let signalGeneration = 0;
@@ -470,8 +481,9 @@ export function createHubConsoleDirect(options = {}) {
 
   const isOwnerActive = owner => !owner.retired
     && owner.hubEpoch === hubEpoch
-    && peers.get(owner.consoleId) === owner
+    && peers.get(owner.key) === owner
     && owner.generation > 0
+    && (!owner.parent || isOwnerActive(owner.parent))
     && ownerWorkspaceAccessCurrent(owner);
 
   const memberFenceKey = (workspaceId, userId) => `${String(workspaceId || '').trim()}:${String(userId || '').trim()}`;
@@ -509,6 +521,12 @@ export function createHubConsoleDirect(options = {}) {
     hubEpoch: owner.hubEpoch
   });
 
+  const sendMediaSignal = (parent, mediaId, signal) => isOwnerActive(parent)
+    && sendControl(parent, { type: 'media-signal', connectionId: parent.connectionId,
+      hubEpoch: parent.hubEpoch, mediaId, signal });
+  const sendPeerSignal = (owner, signal) => owner.parent
+    ? sendMediaSignal(owner.parent, owner.consoleId, signal) : sendSignal(signal);
+
   const disposeAssemblerTimer = channelState => {
     if (channelState.assemblyTimer) clearTimeout(channelState.assemblyTimer);
     channelState.assemblyTimer = null;
@@ -564,12 +582,21 @@ export function createHubConsoleDirect(options = {}) {
       String(options.reason || 'console-direct-channel-closed').slice(0, 120)
     );
     try { channelState.channel.close(); } catch { /* exact channel is already closed */ }
+    if (owner.parent && !owner.retired && owner.channels.size === 0) {
+      retirePeer(owner, String(options.reason || 'console-direct-media-lane-idle'));
+    }
   };
 
   const retirePeer = (owner, reason = 'console-direct-peer-closed', options = {}) => {
     if (!owner || owner.retired) return;
     owner.retired = true;
-    if (peers.get(owner.consoleId) === owner) peers.delete(owner.consoleId);
+    for (const child of [...owner.mediaPeers.values()]) retirePeer(child, reason, { notify: false });
+    owner.mediaPeers.clear();
+    if (owner.parent?.mediaPeers.get(owner.consoleId) === owner) owner.parent.mediaPeers.delete(owner.consoleId);
+    owner.iceSetupGate?.close();
+    void owner.routerMapping?.release();
+    retainConsoleIceRetirement(recentPeerConnections, owner, reason);
+    if (peers.get(owner.key) === owner) peers.delete(owner.key);
     clearTimeout(owner.iceTimer);
     owner.iceTimer = null;
     clearTimeout(owner.disconnectTimer);
@@ -595,13 +622,13 @@ export function createHubConsoleDirect(options = {}) {
       owner.control = null;
     }
     const terminalBudget = owner.wireBudget.inspect();
-    if (terminalBudget.retainedBytes !== 0 || terminalBudget.reservationCount !== 0) {
+    if (!owner.parent && (terminalBudget.retainedBytes !== 0 || terminalBudget.reservationCount !== 0)) {
       wireBudgetCleanupFailures += 1;
       lastError = 'console-direct-wire-budget-not-zero-after-peer-close';
     }
     try { owner.peer.close(); } catch { /* exact peer is already closed */ }
     if (options.notify !== false) {
-      sendSignal({ type: 'rtc-close', ...ownerEnvelope(owner), reason: String(reason).slice(0, 120) });
+      sendPeerSignal(owner, { type: 'rtc-close', ...ownerEnvelope(owner), reason: String(reason).slice(0, 120) });
     }
   };
 
@@ -617,7 +644,7 @@ export function createHubConsoleDirect(options = {}) {
     const generation = owner.generation;
     owner.accessTimer = setTimeout(() => {
       owner.accessTimer = null;
-      if (peers.get(owner.consoleId) !== owner || owner.generation !== generation || owner.retired) return;
+      if (peers.get(owner.key) !== owner || owner.generation !== generation || owner.retired) return;
       retirePeer(owner, 'console-workspace-access-expired');
     }, delay);
     owner.accessTimer.unref?.();
@@ -629,6 +656,7 @@ export function createHubConsoleDirect(options = {}) {
 
   const retireNegotiatingPeers = reason => {
     for (const owner of [...peers.values()]) {
+      if (owner.parent) continue; // Child negotiation uses the healthy direct parent, not the Worker.
       if (!owner.control || !channelIsOpen(owner.control.channel)) {
         retirePeer(owner, reason, { notify: false });
       }
@@ -676,6 +704,13 @@ export function createHubConsoleDirect(options = {}) {
     }
   };
 
+  const familyBufferedAmount = owner => {
+    const root = owner.parent || owner;
+    let total = ownerBufferedAmount(root);
+    for (const child of root.mediaPeers.values()) total += ownerBufferedAmount(child);
+    return total;
+  };
+
   const releaseLogicalBacklogForControl = (owner, requiredBytes) => {
     const purposePriority = { frame: 0, atlas: 1, audio: 2, input: 3 };
     const candidates = [...owner.channels.values()]
@@ -729,7 +764,7 @@ export function createHubConsoleDirect(options = {}) {
     const partialMedia = channelState.purpose === 'frame' || channelState.purpose === 'atlas';
     if (partialMedia
       && (wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES
-        || ownerBufferedAmount(owner) + wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES)) {
+        || familyBufferedAmount(owner) + wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES)) {
       dataChannelBackpressureCloses += 1;
       if (options.closeOnFailure !== false) {
         closeLogicalChannel(owner, channelState, {
@@ -762,7 +797,7 @@ export function createHubConsoleDirect(options = {}) {
       releaseLogicalBacklogForControl(owner, wireBytes);
     }
     if (wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES
-      || ownerBufferedAmount(owner) + wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES) {
+      || familyBufferedAmount(owner) + wireBytes > MAX_DATA_CHANNEL_BUFFERED_BYTES) {
       dataChannelBackpressureCloses += 1;
       if (options.closeOnFailure !== false) {
         if (channelState === owner.control) retirePeer(owner, 'console-direct-control-backpressure');
@@ -774,6 +809,7 @@ export function createHubConsoleDirect(options = {}) {
       }
       return false;
     }
+    const sendStartedAt = performance.now();
     for (const [chunkIndex, chunk] of chunks.entries()) {
       if (!isOwnerActive(owner) || channelState.closed || !channelIsOpen(channelState.channel)) return false;
       try {
@@ -810,6 +846,8 @@ export function createHubConsoleDirect(options = {}) {
         return false;
       }
     }
+    if (!isOwnerActive(owner) || channelState.closed) return false;
+    channelState.frameAdmission?.sent(wireBytes, sendStartedAt);
     return true;
   }
 
@@ -1088,7 +1126,12 @@ export function createHubConsoleDirect(options = {}) {
   const handleControlPayload = (owner, text) => {
     const payload = parseJson(text);
     if (!payload?.type) throw new Error('console-direct-control-invalid');
+    if (payload.type === 'media-signal') {
+      handleMediaSignal(owner, payload);
+      return;
+    }
     if (payload.type === 'http-request') {
+      if (owner.parent) throw new Error('console-direct-media-http-forbidden');
       void handleHttpRequest(owner, payload);
       return;
     }
@@ -1201,7 +1244,9 @@ export function createHubConsoleDirect(options = {}) {
     } else {
       const identity = parseLogicalWebSocketLabel(label);
       if (!identity
-        || owner.channels.size >= MAX_LOGICAL_CHANNELS_PER_PEER
+        || owner.channels.size + owner.mediaPeers.size >= MAX_LOGICAL_CHANNELS_PER_PEER
+        || (owner.parent && (identity.channelId !== owner.consoleId
+          || !['frame', 'atlas'].includes(identity.purpose)))
         || owner.channels.has(identity?.channelId)) {
         try { channel.close(); } catch {}
         return;
@@ -1252,12 +1297,15 @@ export function createHubConsoleDirect(options = {}) {
     channel.onOpen(() => {
       if (!isOwnerActive(owner) || channelState.closed) return;
       if (channelState === owner.control) {
+        owner.controlOpened = true;
+        void owner.routerMapping?.release();
         clearTimeout(owner.iceTimer);
         owner.iceTimer = null;
         sendControl(owner, {
           type: 'direct-ready',
           connectionId: owner.connectionId,
-          hubEpoch: owner.hubEpoch
+          hubEpoch: owner.hubEpoch,
+          ...(!owner.parent ? { mediaPeerVersion: 1 } : {})
         });
       } else {
         consumePendingLogicalControl(owner, channelState);
@@ -1265,12 +1313,16 @@ export function createHubConsoleDirect(options = {}) {
     });
   };
 
-  const createPeerOwner = payload => {
+  const createPeerOwner = (payload, parent = null) => {
     const consoleId = String(payload?.consoleId || '');
     const connectionId = String(payload?.connectionId || '');
     const ownerHubEpoch = String(payload?.hubEpoch || '');
     const description = payload?.description;
-    const workspaceAccess = consoleWorkspaceAccess(payload);
+    // A child receives authority only from the exact authenticated parent.
+    // Browser-supplied workspace/member fields can never elevate it.
+    const workspaceAccess = parent ? parent.workspaceAccess : consoleWorkspaceAccess(payload);
+    const reply = message => parent ? sendMediaSignal(parent, consoleId, message) : sendSignal(message);
+    const key = parent ? `${parent.key}/${consoleId}` : consoleId;
     if (!UUID_PATTERN.test(consoleId)
       || !UUID_PATTERN.test(connectionId)
       || ownerHubEpoch !== hubEpoch
@@ -1279,7 +1331,7 @@ export function createHubConsoleDirect(options = {}) {
       || typeof description.sdp !== 'string'
       || byteLength(description.sdp) > SDP_MAX_BYTES) {
       if (UUID_PATTERN.test(consoleId) && UUID_PATTERN.test(connectionId)) {
-        sendSignal({
+        reply({
           type: 'rtc-close',
           consoleId,
           connectionId,
@@ -1290,7 +1342,7 @@ export function createHubConsoleDirect(options = {}) {
       return null;
     }
     if (memberIsFenced(workspaceAccess)) {
-      sendSignal({
+      reply({
         type: 'rtc-close',
         consoleId,
         connectionId,
@@ -1301,7 +1353,7 @@ export function createHubConsoleDirect(options = {}) {
     }
     if (candidateIsRelay(description.sdp)) {
       rejectedRelayCandidates += 1;
-      sendSignal({
+      reply({
         type: 'rtc-close',
         consoleId,
         connectionId,
@@ -1310,14 +1362,14 @@ export function createHubConsoleDirect(options = {}) {
       });
       return null;
     }
-    const existing = peers.get(consoleId);
+    const existing = peers.get(key);
     if (existing
       && existing.connectionId === connectionId
       && existing.hubEpoch === ownerHubEpoch
       && !existing.retired) {
-      const current = existing.peer.localDescription?.();
+      const current = existing.peer?.localDescription?.();
       if (current?.type === 'answer' && typeof current.sdp === 'string') {
-        sendSignal({
+        reply({
           type: 'rtc-answer',
           ...ownerEnvelope(existing),
           description: { type: 'answer', sdp: current.sdp }
@@ -1325,8 +1377,16 @@ export function createHubConsoleDirect(options = {}) {
       }
       return existing;
     }
-    if (!existing && peers.size >= MAX_PEERS) {
-      sendSignal({
+    if (parent && existing) {
+      reply({ type: 'rtc-close', consoleId, connectionId, hubEpoch: ownerHubEpoch,
+        reason: 'console-direct-media-owner-already-current' });
+      return null;
+    }
+    const rootPeerCount = [...peers.values()].filter(entry => !entry.parent).length;
+    if (!existing && (parent
+      ? parent.channels.size + parent.mediaPeers.size >= MAX_LOGICAL_CHANNELS_PER_PEER
+      : rootPeerCount >= MAX_PEERS)) {
+      reply({
         type: 'rtc-close',
         consoleId,
         connectionId,
@@ -1337,30 +1397,10 @@ export function createHubConsoleDirect(options = {}) {
     }
     if (existing) retirePeer(existing, 'console-direct-peer-replaced');
     let peer;
-    try {
-      peer = createPeerConnection(`console-${consoleId}`, {
-        iceServers: [...stunUrls],
-        iceTransportPolicy: 'all',
-        disableAutoNegotiation: false,
-        disableFingerprintVerification: false,
-        // Each native send is one wire chunk. libdatachannel also uses this
-        // setting as the minimum SCTP socket buffer size, below bufferedAmount.
-        // A whole-frame limit here hides megabytes from our admission gate.
-        // Complete frame/HTTP limits remain enforced by the wire assemblers.
-        maxMessageSize: DIRECT_CONSOLE_WIRE_CHUNK_BYTES
-      });
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-      sendSignal({
-        type: 'rtc-close',
-        consoleId,
-        connectionId,
-        hubEpoch: ownerHubEpoch,
-        reason: 'console-direct-peer-create-failed'
-      });
-      return null;
-    }
     const owner = {
+      key,
+      parent,
+      mediaPeers: new Map(),
       consoleId,
       connectionId,
       hubEpoch: ownerHubEpoch,
@@ -1371,76 +1411,25 @@ export function createHubConsoleDirect(options = {}) {
       channels: new Map(),
       pendingLogicalControl: new Map(),
       pendingHttp: new Map(),
-      wireBudget: createDirectConsoleWireBudget({ maxBytes: MAX_SHARED_ASSEMBLY_BYTES }),
+      wireBudget: parent?.wireBudget || createDirectConsoleWireBudget({ maxBytes: MAX_SHARED_ASSEMBLY_BYTES }),
       iceTimer: null,
       disconnectTimer: null,
       accessTimer: null,
       peerState: 'new',
       iceState: 'new',
+      controlOpened: false,
+      routerMapping: null,
+      iceSetupGate: null,
+      iceEvidence: createConsoleIceEvidence(),
       retired: false,
       createdAt: Date.now()
     };
-    peers.set(consoleId, owner);
-    armOwnerAccessDeadline(owner);
-    peer.onLocalDescription((sdp, type) => {
-      if (!isOwnerActive(owner) || String(type).toLowerCase() !== 'answer' || byteLength(sdp) > SDP_MAX_BYTES) return;
-      if (candidateIsRelay(sdp)) {
-        rejectedRelayCandidates += 1;
-        retirePeer(owner, 'console-direct-relay-candidate-rejected');
-        return;
-      }
-      sendSignal({
-        type: 'rtc-answer',
-        ...ownerEnvelope(owner),
-        description: { type: 'answer', sdp: String(sdp) }
-      });
-    });
-    peer.onLocalCandidate((candidate, sdpMid) => {
-      if (!isOwnerActive(owner)) return;
-      const candidateText = String(candidate || '');
-      if (byteLength(candidateText) > ICE_CANDIDATE_MAX_BYTES) {
-        retirePeer(owner, 'console-direct-candidate-invalid');
-        return;
-      }
-      if (candidateIsRelay(candidateText)) {
-        rejectedRelayCandidates += 1;
-        retirePeer(owner, 'console-direct-relay-candidate-rejected');
-        return;
-      }
-      sendSignal({
-        type: 'rtc-ice',
-        ...ownerEnvelope(owner),
-        candidate: candidateText,
-        sdpMid: sdpMid === undefined || sdpMid === null ? null : String(sdpMid).slice(0, 256)
-      });
-    });
-    peer.onDataChannel(channel => bindDataChannel(owner, channel));
-    peer.onStateChange(nextState => {
-      if (!isOwnerActive(owner)) return;
-      const normalized = String(nextState || '').toLowerCase();
-      owner.peerState = normalized;
-      if (normalized === 'connected') {
-        if (peerSelectedRelay(peer)) {
-          rejectedRelayCandidates += 1;
-          retirePeer(owner, 'console-direct-relay-pair-rejected');
-          return;
-        }
-      } else if (normalized === 'failed' || normalized === 'closed') {
-        retirePeer(owner, `console-direct-peer-${normalized}`);
-        return;
-      }
-      refreshPeerDisconnectDeadline(owner);
-    });
-    peer.onIceStateChange?.(nextState => {
-      if (!isOwnerActive(owner)) return;
-      const normalized = String(nextState || '').toLowerCase();
-      owner.iceState = normalized;
-      if (normalized === 'failed' || normalized === 'closed') {
-        retirePeer(owner, `console-direct-ice-${normalized}`);
-        return;
-      }
-      refreshPeerDisconnectDeadline(owner);
-    });
+    peers.set(key, owner);
+    if (parent) parent.mediaPeers.set(consoleId, owner);
+    owner.routerMapping = routerMapping.createOwner(`${consoleId}:${connectionId}:${owner.generation}`,
+      { portRange: icePortRange, ...(parent ? { queue: true } : {}) });
+    if (owner.routerMapping?.handoff) owner.iceSetupGate = createConsoleIceSetupGate();
+    if (!parent) armOwnerAccessDeadline(owner);
     owner.iceTimer = setTimeout(() => {
       owner.iceTimer = null;
       if (isOwnerActive(owner)
@@ -1449,14 +1438,161 @@ export function createHubConsoleDirect(options = {}) {
       }
     }, iceConnectTimeoutMs);
     owner.iceTimer.unref?.();
+    const initializePeer = reservedPort => {
+      if (!isOwnerActive(owner)) return null;
+      try {
+        peer = createPeerConnection(`console-${consoleId}`, {
+          iceServers: [...stunUrls],
+          iceTransportPolicy: 'all',
+          ...icePortRange,
+          ...(reservedPort ? { portRangeBegin: reservedPort, portRangeEnd: reservedPort } : {}),
+          disableAutoNegotiation: false,
+          disableFingerprintVerification: false,
+          // Keep the native SCTP socket's hidden buffer at the wire chunk bound.
+          maxMessageSize: DIRECT_CONSOLE_WIRE_CHUNK_BYTES
+        });
+        owner.peer = peer;
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+        retirePeer(owner, 'console-direct-peer-create-failed');
+        return null;
+      }
+      peer.onLocalDescription((sdp, type) => {
+        if (!isOwnerActive(owner) || String(type).toLowerCase() !== 'answer' || byteLength(sdp) > SDP_MAX_BYTES) return;
+        if (candidateIsRelay(sdp)) {
+          rejectedRelayCandidates += 1;
+          retirePeer(owner, 'console-direct-relay-candidate-rejected');
+          return;
+        }
+        const sent = sendPeerSignal(owner, {
+          type: 'rtc-answer',
+          ...ownerEnvelope(owner),
+          description: { type: 'answer', sdp: String(sdp) }
+        });
+        owner.iceEvidence.localDescriptionSent = sent;
+        recordConsoleIceDescription(owner.iceEvidence.local, sdp);
+        if (!owner.controlOpened) {
+          for (const line of sdp.split(/\r?\n/)) {
+            if (line.startsWith('a=candidate:')) owner.routerMapping?.observe(line);
+          }
+        }
+      });
+      peer.onLocalCandidate((candidate, sdpMid) => {
+        if (!isOwnerActive(owner)) return;
+        const candidateText = String(candidate || '');
+        if (byteLength(candidateText) > ICE_CANDIDATE_MAX_BYTES) {
+          retirePeer(owner, 'console-direct-candidate-invalid');
+          return;
+        }
+        if (candidateIsRelay(candidateText)) {
+          rejectedRelayCandidates += 1;
+          retirePeer(owner, 'console-direct-relay-candidate-rejected');
+          return;
+        }
+        const sent = sendPeerSignal(owner, {
+          type: 'rtc-ice',
+          ...ownerEnvelope(owner),
+          candidate: candidateText,
+          sdpMid: sdpMid === undefined || sdpMid === null ? null : String(sdpMid).slice(0, 256)
+        });
+        recordConsoleIceCandidate(owner.iceEvidence.local, candidateText);
+        if (!owner.controlOpened) owner.routerMapping?.observe(candidateText);
+        if (!sent) owner.iceEvidence.localCandidateSendFailures = Math.min(65_535,
+          owner.iceEvidence.localCandidateSendFailures + 1);
+      });
+      peer.onGatheringStateChange?.(nextState => {
+        if (isOwnerActive(owner)) owner.iceEvidence.gatheringState = safeIceState(String(nextState).toLowerCase());
+      });
+      peer.onDataChannel(channel => bindDataChannel(owner, channel));
+      peer.onStateChange(nextState => {
+        if (!isOwnerActive(owner)) return;
+        const normalized = String(nextState || '').toLowerCase();
+        owner.peerState = normalized;
+        if (normalized === 'connected') {
+          if (peerSelectedRelay(peer)) {
+            rejectedRelayCandidates += 1;
+            retirePeer(owner, 'console-direct-relay-pair-rejected');
+            return;
+          }
+        } else if (normalized === 'failed' || normalized === 'closed') {
+          retirePeer(owner, `console-direct-peer-${normalized}`);
+          return;
+        }
+        refreshPeerDisconnectDeadline(owner);
+      });
+      peer.onIceStateChange?.(nextState => {
+        if (!isOwnerActive(owner)) return;
+        const normalized = String(nextState || '').toLowerCase();
+        owner.iceState = normalized;
+        if (normalized === 'failed' || normalized === 'closed') {
+          retirePeer(owner, `console-direct-ice-${normalized}`);
+          return;
+        }
+        refreshPeerDisconnectDeadline(owner);
+      });
+      try {
+        peer.setRemoteDescription(description.sdp, 'offer');
+        owner.iceEvidence.remoteDescriptionApplied = true;
+        recordConsoleIceDescription(owner.iceEvidence.remote, description.sdp);
+        owner.iceSetupGate?.flush((candidate, mid) => peer.addRemoteCandidate(candidate, mid),
+          () => isOwnerActive(owner));
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+        retirePeer(owner, 'console-direct-description-failed');
+        return null;
+      }
+      return owner;
+    };
+    if (owner.routerMapping?.handoff) {
+      void owner.routerMapping.ready.then(async () => {
+        const reservation = await owner.routerMapping.handoff();
+        if (isOwnerActive(owner)) initializePeer(reservation?.port);
+      }).catch(() => retirePeer(owner, 'console-direct-peer-create-failed'));
+    } else initializePeer();
+    return owner;
+  };
+
+  const handlePeerSignal = (owner, payload) => {
+    if (payload.type === 'rtc-close') {
+      retirePeer(owner, String(payload.reason || 'console-direct-remote-closed').slice(0, 120), { notify: false });
+      return;
+    }
+    if (payload.type !== 'rtc-ice') return;
+    const candidate = String(payload.candidate || '');
+    if (byteLength(candidate) > ICE_CANDIDATE_MAX_BYTES || String(payload.sdpMid || '').length > 256) {
+      retirePeer(owner, 'console-direct-candidate-invalid');
+      return;
+    }
+    if (candidateIsRelay(candidate)) {
+      rejectedRelayCandidates += 1;
+      retirePeer(owner, 'console-direct-relay-candidate-rejected');
+      return;
+    }
     try {
-      peer.setRemoteDescription(description.sdp, 'offer');
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-      retirePeer(owner, 'console-direct-description-failed');
-      return null;
+      if (candidate) {
+        recordConsoleIceCandidate(owner.iceEvidence.remote, candidate);
+        if (!owner.iceSetupGate?.defer(candidate, String(payload.sdpMid || ''))) {
+          owner.peer.addRemoteCandidate(candidate, String(payload.sdpMid || ''));
+        }
+      }
+    } catch { retirePeer(owner, 'console-direct-candidate-failed'); }
+  };
+
+  const handleMediaSignal = (parent, envelope) => {
+    if (parent.parent || !isOwnerActive(parent) || !lifecycleOwnerMatches(parent, envelope)) return;
+    const mediaId = String(envelope.mediaId || '');
+    const payload = envelope.signal;
+    if (!UUID_PATTERN.test(mediaId) || !payload || byteLength(JSON.stringify(payload)) > SIGNAL_MESSAGE_MAX_BYTES
+      || !UUID_PATTERN.test(String(payload.connectionId || '')) || payload.hubEpoch !== parent.hubEpoch) return;
+    if (payload.type === 'rtc-offer') {
+      // Only the media lane ID and the validated RTC fields cross this boundary.
+      createPeerOwner({ consoleId: mediaId, connectionId: payload.connectionId,
+        hubEpoch: parent.hubEpoch, description: payload.description }, parent);
+      return;
     }
-    return owner;
+    const child = parent.mediaPeers.get(mediaId);
+    if (!child || child.connectionId !== payload.connectionId || !isOwnerActive(child)) return;
+    handlePeerSignal(child, payload);
   };
 
   const handleSignalMessage = (raw, ownerSignalGeneration, socket) => {
@@ -1512,6 +1648,7 @@ export function createHubConsoleDirect(options = {}) {
         return;
       }
       owner.workspaceAccess = refreshedAccess;
+      for (const child of owner.mediaPeers.values()) child.workspaceAccess = refreshedAccess;
       armOwnerAccessDeadline(owner);
       return;
     }
@@ -1582,27 +1719,7 @@ export function createHubConsoleDirect(options = {}) {
       || owner.connectionId !== connectionId
       || owner.hubEpoch !== ownerHubEpoch
       || !isOwnerActive(owner)) return;
-    if (payload.type === 'rtc-ice') {
-      const candidate = String(payload.candidate || '');
-      if (byteLength(candidate) > ICE_CANDIDATE_MAX_BYTES) {
-        retirePeer(owner, 'console-direct-candidate-invalid');
-        return;
-      }
-      if (candidateIsRelay(candidate)) {
-        rejectedRelayCandidates += 1;
-        retirePeer(owner, 'console-direct-relay-candidate-rejected');
-        return;
-      }
-      try {
-        if (candidate) owner.peer.addRemoteCandidate(candidate, String(payload.sdpMid || ''));
-      } catch {
-        retirePeer(owner, 'console-direct-candidate-failed');
-      }
-      return;
-    }
-    if (payload.type === 'rtc-close') {
-      retirePeer(owner, String(payload.reason || 'console-direct-remote-closed'), { notify: false });
-    }
+    handlePeerSignal(owner, payload);
   };
 
   const cancelAccessTokenAttempt = () => {
@@ -1951,6 +2068,8 @@ export function createHubConsoleDirect(options = {}) {
     retryTimer = null;
     nextRetryAt = '';
     retireAllPeers('hub-shutdown');
+    void routerMapping.releaseAll({ forgetHistory: true });
+    recentPeerConnections.length = 0;
     hubEpoch = '';
     const socket = signalSocket;
     signalSocket = null;
@@ -1961,6 +2080,8 @@ export function createHubConsoleDirect(options = {}) {
 
   const invalidateWorkspaceAccess = (reason = 'console-workspace-access-invalidated') => {
     retireAllPeers(String(reason || 'console-workspace-access-invalidated').slice(0, 120));
+    void routerMapping.releaseAll({ forgetHistory: true });
+    recentPeerConnections.length = 0;
     refresh();
   };
 
@@ -1976,6 +2097,7 @@ export function createHubConsoleDirect(options = {}) {
     pruneRevokedMembers();
     let retired = 0;
     for (const owner of [...peers.values()]) {
+      if (owner.retired) continue;
       if (owner.workspaceAccess?.workspaceId !== normalizedWorkspaceId
         || owner.workspaceAccess?.userId !== normalizedUserId) continue;
       retirePeer(owner, String(reason || 'workspace-member-revoked').slice(0, 120));
@@ -2010,14 +2132,18 @@ export function createHubConsoleDirect(options = {}) {
         if (channelState.localSocket) localWebSocketChannels += 1;
         if (channelState.assemblyTimer) assemblyDeadlineTimers += 1;
       }
-      retainedAssemblyBytes += Number(owner.wireBudget.inspect().retainedBytes || 0);
+      if (!owner.parent) retainedAssemblyBytes += Number(owner.wireBudget.inspect().retainedBytes || 0);
       bufferedSendBytes += ownerBufferedAmount(owner);
       peerDiagnostics.push({
         consoleId: owner.consoleId,
+        transportRole: owner.parent ? 'media' : 'control',
+        parentConsoleId: owner.parent?.consoleId || null,
+        parentConnectionId: owner.parent?.connectionId || null,
         connectionId: owner.connectionId,
         generation: owner.generation,
         peerState: owner.peerState,
         iceState: owner.iceState,
+        iceEvidence: snapshotConsoleIceEvidence(owner.iceEvidence),
         rttMs: optionalPeerMetric(owner.peer, 'rtt'),
         bytesSent: optionalPeerMetric(owner.peer, 'bytesSent'),
         bytesReceived: optionalPeerMetric(owner.peer, 'bytesReceived'),
@@ -2041,12 +2167,15 @@ export function createHubConsoleDirect(options = {}) {
     const accessTokenDeadlineActive = Boolean(accessTokenAttempt);
     const signalReadyDeadlineActive = Boolean(signalReadyDeadline);
     const signalHeartbeatTimerActive = Boolean(signalHeartbeat?.timer);
+    const routerResources = routerMapping.inspect();
     return Object.freeze({
       enabled: signalUrl instanceof URL && Boolean(deviceId),
       state,
       connected: state === 'connected',
       hubEpoch,
       peerConnections: peers.size,
+      consoleConnections: [...peers.values()].filter(owner => !owner.parent).length,
+      mediaPeerConnections: [...peers.values()].filter(owner => owner.parent).length,
       controlChannels,
       logicalWebSocketChannels,
       localWebSocketChannels,
@@ -2055,6 +2184,8 @@ export function createHubConsoleDirect(options = {}) {
       retainedAssemblyBytes,
       bufferedSendBytes,
       peerDiagnostics,
+      routerMapping: routerResources,
+      recentPeerConnections: recentPeerConnections.map(entry => snapshotConsoleIceEvidence(entry)),
       iceConnectTimers,
       peerDisconnectTimers,
       assemblyDeadlineTimers,
@@ -2075,7 +2206,8 @@ export function createHubConsoleDirect(options = {}) {
         + workspaceAccessTimers
         + Number(Boolean(workspaceReauthAttempt?.timer))
         + Number(signalReadyDeadlineActive)
-        + Number(signalHeartbeatTimerActive),
+        + Number(signalHeartbeatTimerActive)
+        + Number(routerResources.resourceTimers || 0),
       rejectedRelayCandidates,
       dataChannelBackpressureCloses,
       dataChannelSendFailures,
@@ -2096,7 +2228,8 @@ export function createHubConsoleDirect(options = {}) {
     close,
     invalidateWorkspaceAccess,
     revokeWorkspaceMember,
-    inspect
+    inspect,
+    releaseRouterMappings: () => routerMapping.releaseAll()
   });
 }