@livedesk/hub 0.1.75 → 0.1.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "description": "VuvoDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/src/console-direct.js

@@ -481,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()}`;
@@ -520,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;
@@ -575,15 +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;
+    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.consoleId) === owner) peers.delete(owner.consoleId);
+    if (peers.get(owner.key) === owner) peers.delete(owner.key);
     clearTimeout(owner.iceTimer);
     owner.iceTimer = null;
     clearTimeout(owner.disconnectTimer);
@@ -609,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) });
     }
   };
 
@@ -631,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?.();
@@ -643,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 });
       }
@@ -690,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()]
@@ -743,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, {
@@ -776,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');
@@ -1105,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;
     }
@@ -1218,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;
@@ -1276,7 +1304,8 @@ export function createHubConsoleDirect(options = {}) {
         sendControl(owner, {
           type: 'direct-ready',
           connectionId: owner.connectionId,
-          hubEpoch: owner.hubEpoch
+          hubEpoch: owner.hubEpoch,
+          ...(!owner.parent ? { mediaPeerVersion: 1 } : {})
         });
       } else {
         consumePendingLogicalControl(owner, channelState);
@@ -1284,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
@@ -1298,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,
@@ -1309,7 +1342,7 @@ export function createHubConsoleDirect(options = {}) {
       return null;
     }
     if (memberIsFenced(workspaceAccess)) {
-      sendSignal({
+      reply({
         type: 'rtc-close',
         consoleId,
         connectionId,
@@ -1320,7 +1353,7 @@ export function createHubConsoleDirect(options = {}) {
     }
     if (candidateIsRelay(description.sdp)) {
       rejectedRelayCandidates += 1;
-      sendSignal({
+      reply({
         type: 'rtc-close',
         consoleId,
         connectionId,
@@ -1329,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?.();
       if (current?.type === 'answer' && typeof current.sdp === 'string') {
-        sendSignal({
+        reply({
           type: 'rtc-answer',
           ...ownerEnvelope(existing),
           description: { type: 'answer', sdp: current.sdp }
@@ -1344,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,
@@ -1357,6 +1398,9 @@ export function createHubConsoleDirect(options = {}) {
     if (existing) retirePeer(existing, 'console-direct-peer-replaced');
     let peer;
     const owner = {
+      key,
+      parent,
+      mediaPeers: new Map(),
       consoleId,
       connectionId,
       hubEpoch: ownerHubEpoch,
@@ -1367,7 +1411,7 @@ 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,
@@ -1380,11 +1424,12 @@ export function createHubConsoleDirect(options = {}) {
       retired: false,
       createdAt: Date.now()
     };
-    peers.set(consoleId, owner);
+    peers.set(key, owner);
+    if (parent) parent.mediaPeers.set(consoleId, owner);
     owner.routerMapping = routerMapping.createOwner(`${consoleId}:${connectionId}:${owner.generation}`,
-      { portRange: icePortRange });
+      { portRange: icePortRange, ...(parent ? { queue: true } : {}) });
     if (owner.routerMapping?.handoff) owner.iceSetupGate = createConsoleIceSetupGate();
-    armOwnerAccessDeadline(owner);
+    if (!parent) armOwnerAccessDeadline(owner);
     owner.iceTimer = setTimeout(() => {
       owner.iceTimer = null;
       if (isOwnerActive(owner)
@@ -1419,7 +1464,7 @@ export function createHubConsoleDirect(options = {}) {
           retirePeer(owner, 'console-direct-relay-candidate-rejected');
           return;
         }
-        const sent = sendSignal({
+        const sent = sendPeerSignal(owner, {
           type: 'rtc-answer',
           ...ownerEnvelope(owner),
           description: { type: 'answer', sdp: String(sdp) }
@@ -1444,7 +1489,7 @@ export function createHubConsoleDirect(options = {}) {
           retirePeer(owner, 'console-direct-relay-candidate-rejected');
           return;
         }
-        const sent = sendSignal({
+        const sent = sendPeerSignal(owner, {
           type: 'rtc-ice',
           ...ownerEnvelope(owner),
           candidate: candidateText,
@@ -1507,6 +1552,49 @@ export function createHubConsoleDirect(options = {}) {
     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 {
+      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;
+    }
+    const child = parent.mediaPeers.get(mediaId);
+    if (!child || child.connectionId !== payload.connectionId || !isOwnerActive(child)) return;
+    handlePeerSignal(child, payload);
+  };
+
   const handleSignalMessage = (raw, ownerSignalGeneration, socket) => {
     if (typeof raw !== 'string' && !Buffer.isBuffer(raw)) return;
     const text = Buffer.isBuffer(raw) ? raw.toString('utf8') : raw;
@@ -1560,6 +1648,7 @@ export function createHubConsoleDirect(options = {}) {
         return;
       }
       owner.workspaceAccess = refreshedAccess;
+      for (const child of owner.mediaPeers.values()) child.workspaceAccess = refreshedAccess;
       armOwnerAccessDeadline(owner);
       return;
     }
@@ -1630,32 +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) {
-          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');
-      }
-      return;
-    }
-    if (payload.type === 'rtc-close') {
-      retirePeer(owner, String(payload.reason || 'console-direct-remote-closed'), { notify: false });
-    }
+    handlePeerSignal(owner, payload);
   };
 
   const cancelAccessTokenAttempt = () => {
@@ -2033,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));
@@ -2067,10 +2132,13 @@ 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,
@@ -2106,6 +2174,8 @@ export function createHubConsoleDirect(options = {}) {
       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,

package/src/console-direct.test.mjs

@@ -298,6 +298,120 @@ function offer(signal, connectionId = CONNECTION_ONE, sdp = 'v=0\r\na=fake-offer
   return FakePeerConnection.instances.at(-1);
 }
 
+function openPeerControl(peer) {
+  const control = new FakeDataChannel('livedesk-control-v1');
+  peer.callbacks.dataChannel(control);
+  control.open();
+  return control;
+}
+
+function mediaSignal(control, mediaId, signal, parentConnectionId = CONNECTION_ONE) {
+  sendWire(control, { type: 'media-signal', connectionId: parentConnectionId,
+    hubEpoch: HUB_EPOCH, mediaId, signal: { hubEpoch: HUB_EPOCH, ...signal } });
+}
+
+test('dedicated media peers isolate congestion and retirement from HTTP, siblings and other Consoles', async () => {
+  const { direct, signal } = await connectedDirect();
+  try {
+    const root = offer(signal), control = openPeerControl(root);
+    const externalSignals = signal.sent.length;
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const first = FakePeerConnection.instances.at(-1), firstControl = openPeerControl(first);
+    mediaSignal(control, CHANNEL_ID_TWO, { type: 'rtc-offer', connectionId: REQUEST_ID,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const second = FakePeerConnection.instances.at(-1); openPeerControl(second);
+    assert.notEqual(first, root);
+    assert.notEqual(first, second);
+    assert.equal(signal.sent.length, externalSignals, 'media SDP/ICE never goes through the Worker');
+    assert.equal(direct.inspect().consoleConnections, 1);
+    assert.equal(direct.inspect().mediaPeerConnections, 2);
+    const replies = decodeWireMessages(control.sent).map(m => JSON.parse(m.data));
+    assert.ok(replies.some(m => m.type === 'media-signal' && m.mediaId === CHANNEL_ID
+      && m.signal.type === 'rtc-answer' && m.connectionId === CONNECTION_ONE));
+    firstControl.buffered = 900_000;
+    sendWire(control, { type: 'http-request', requestId: REQUEST_ID, method: 'GET', path: '/api/remote/status' });
+    await settle();
+    assert.ok(decodeWireMessages(control.sent).map(m => JSON.parse(m.data)).some(m => m.type === 'http-response'));
+    first.emitState('failed');
+    assert.equal(first.closed, true);
+    assert.equal(root.closed, false);
+    assert.equal(second.closed, false);
+    assert.equal(direct.inspect().mediaPeerConnections, 1);
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_ONE,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const replacement = FakePeerConnection.instances.at(-1); openPeerControl(replacement);
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-close', connectionId: CONNECTION_TWO });
+    assert.equal(replacement.closed, false, 'old media close cannot retire a replacement');
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    assert.equal(replacement.closed, false, 'an older offer cannot replace the active media owner');
+    assert.equal(FakePeerConnection.instances.at(-1), replacement);
+    root.emitState('closed');
+    assert.equal(second.closed, true);
+    assert.equal(replacement.closed, true);
+    assert.equal(direct.inspect().peerConnections, 0);
+    assert.equal(direct.inspect().retainedAssemblyBytes, 0);
+    assert.equal(direct.inspect().wireBudgetCleanupFailures, 0);
+  } finally { direct.close(); }
+});
+
+test('media offers cannot cross parent authority, nest children or consume the four Console slots', async () => {
+  const { direct, signal } = await connectedDirect();
+  try {
+    const root = offer(signal), control = openPeerControl(root);
+    const description = { type: 'offer', sdp: 'v=0\r\n' };
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO, description }, CONNECTION_TWO);
+    assert.equal(direct.inspect().peerConnections, 1, 'stale parent rejected');
+    let childControl;
+    for (let n = 0; n < 16; n++) {
+      const id = `bbbbbbbb-bbbb-4bbb-8bbb-${String(n).padStart(12, '0')}`;
+      mediaSignal(control, id, { type: 'rtc-offer', connectionId: CONNECTION_TWO, description });
+      childControl = openPeerControl(FakePeerConnection.instances.at(-1));
+    }
+    const child = FakePeerConnection.instances.at(-1);
+    mediaSignal(childControl, CHANNEL_ID, { type: 'rtc-offer', connectionId: REQUEST_ID, description }, CONNECTION_TWO);
+    assert.equal(direct.inspect().mediaPeerConnections, 16, 'child cannot create a grandchild');
+    const forbiddenInput = new FakeDataChannel(`livedesk-ws-v1:${CHANNEL_ID}:input`);
+    child.callbacks.dataChannel(forbiddenInput);
+    assert.equal(forbiddenInput.closed, true, 'media child cannot acquire input');
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO, description });
+    assert.equal(direct.inspect().mediaPeerConnections, 16);
+    for (let n = 1; n <= 3; n++) {
+      offer(signal, CONNECTION_TWO, 'v=0\r\n', { consoleId: `aaaaaaaa-aaaa-4aaa-8aaa-${String(n).padStart(12, '0')}` });
+    }
+    assert.equal(direct.inspect().consoleConnections, 4);
+    assert.equal(direct.inspect().peerConnections, 20);
+    offer(signal, CONNECTION_TWO, 'v=0\r\n', { consoleId: CHANNEL_ID });
+    assert.equal(direct.inspect().consoleConnections, 4);
+  } finally { direct.close(); }
+  assert.equal(direct.inspect().peerConnections, 0);
+});
+
+test('media assembly shares one Console budget and closing a child releases only its reservations', async () => {
+  const { direct, signal } = await connectedDirect();
+  try {
+    const root = offer(signal), control = openPeerControl(root);
+    mediaSignal(control, CHANNEL_ID, { type: 'rtc-offer', connectionId: CONNECTION_TWO,
+      description: { type: 'offer', sdp: 'v=0\r\n' } });
+    const child = FakePeerConnection.instances.at(-1), childControl = openPeerControl(child);
+    const partial = encodeDirectConsoleWireMessage('x'.repeat(40_000), { messageId: 77, kind: 'control' })[0];
+    childControl.receive(partial);
+    const childBytes = direct.inspect().retainedAssemblyBytes;
+    assert.ok(childBytes > 0);
+    control.receive(partial);
+    assert.equal(direct.inspect().retainedAssemblyBytes, childBytes * 2,
+      'a shared budget is counted once, not once per transport');
+    child.emitState('failed');
+    assert.equal(direct.inspect().retainedAssemblyBytes, childBytes);
+    assert.equal(direct.inspect().wireBudgetCleanupFailures, 0);
+    assert.equal(root.closed, false);
+  } finally { direct.close(); }
+  assert.equal(direct.inspect().retainedAssemblyBytes, 0);
+  assert.equal(direct.inspect().resourceTimers, 0);
+  assert.equal(direct.inspect().wireBudgetCleanupFailures, 0);
+});
+
 test('native buffered sends complete each media message without closing input or control', async () => {
   const { direct, signal } = await connectedDirect();
   try {
@@ -792,7 +906,8 @@ test('reliable control channel bridges bounded HTTP over fragmented wire message
   assert.deepEqual(JSON.parse(messages[0].data), {
     type: 'direct-ready',
     connectionId: CONNECTION_ONE,
-    hubEpoch: HUB_EPOCH
+    hubEpoch: HUB_EPOCH,
+    mediaPeerVersion: 1
   });
 
   sendWire(control, {

package/src/console-router-mapping.mjs

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { discoverConsoleUpnpGateway, reserveConsoleIceSocket, isPrivateRouterIPv4, isPublicRouterIPv4 } from './console-upnp-gateway.mjs';
 
 export const CONSOLE_ROUTER_MAPPING_BOUNDS = Object.freeze({
-  owners: 4, candidates: 8, setupMs: 8000, cleanupMs: 1800, leaseSeconds: 120, history: 8
+  owners: 4, queuedOwners: 64, candidates: 8, setupMs: 8000, cleanupMs: 1800, leaseSeconds: 120, history: 8
 });
 
 export function parseRouterMappingCandidate(value) {
@@ -34,6 +34,7 @@ export function createConsoleRouterMapping(options = {}) {
   const setupMs = Math.min(bounds.setupMs, Math.max(1, Number(options.setupMs) || bounds.setupMs));
   const cleanupMs = Math.min(bounds.cleanupMs, Math.max(1, Number(options.cleanupMs) || bounds.cleanupMs));
   const owners = new Set();
+  const waiting = new Set();
   const reservedPorts = new Map();
   const history = [];
   let historyEpoch = 0;
@@ -48,6 +49,19 @@ export function createConsoleRouterMapping(options = {}) {
     owner.gateway = null;
     owner.candidates.length = 0;
     owner.finished = true;
+    owner.resolveDone();
+    for (const next of waiting) {
+      if (owners.size >= bounds.owners) break;
+      waiting.delete(next);
+      if (!next.controller.signal.aborted && enabled()) start(next);
+      else next.release();
+    }
+  }
+
+  function start(owner) {
+    owner.state = 'discovering';
+    owners.add(owner);
+    void run(owner);
   }
 
   const own = (entry, owner) => entry && entry.localAddress === owner.gateway.localAddress
@@ -128,25 +142,26 @@ export function createConsoleRouterMapping(options = {}) {
     }
   }
 
-  function createOwner(key, { portRange } = {}) {
-    if (!enabled() || owners.size >= bounds.owners || typeof key !== 'string'
+  function createOwner(key, { portRange, queue = false } = {}) {
+    if (!enabled() || (owners.size >= bounds.owners && (!queue || waiting.size >= bounds.queuedOwners)) || typeof key !== 'string'
       || !/^[a-f0-9-]{36}:[a-f0-9-]{36}:\d{1,12}$/i.test(key)) return null;
     const owner = { key, historyEpoch, portRange, socket: null, state: 'discovering', cleanup: 'not-needed', finished: false,
       controller: new AbortController(), description: `VuvoDesk-ICE-${randomUUID()}`,
       candidates: [], gateway: null, port: 0, reservation: '', attempted: false,
       setupTimer: null, cleanupTimer: null, promise: null, startedAt: Date.now() };
     const ready = new Promise(resolve => { owner.resolveReady = resolve; });
-    owners.add(owner);
+    owner.promise = new Promise(resolve => { owner.resolveDone = resolve; });
     const release = () => {
       if (owner.finished) return owner.promise || Promise.resolve();
       owner.state = 'released';
       owner.controller.abort();
       owner.resolveReady();
-      if (!owner.promise) finish(owner);
+      if (!owners.has(owner)) { waiting.delete(owner); finish(owner); }
       return owner.promise || Promise.resolve();
     };
     owner.release = release;
-    owner.promise = run(owner);
+    if (owners.size < bounds.owners) start(owner);
+    else { owner.state = 'queued'; waiting.add(owner); }
     return Object.freeze({
       ready,
       async handoff() {
@@ -175,9 +190,13 @@ export function createConsoleRouterMapping(options = {}) {
     createOwner,
     releaseAll: ({ forgetHistory = false } = {}) => {
       if (forgetHistory) { historyEpoch += 1; history.length = 0; }
-      return Promise.all([...owners].map(owner => owner.release()));
+      // Remove waiting owners before releasing active slots: a shutdown must
+      // never start a queued router operation while draining the active ones.
+      const pending = [...waiting];
+      waiting.clear();
+      return Promise.all([...pending, ...owners].map(owner => owner.release()));
     },
-    inspect: () => ({ enabled: Boolean(enabled()), activeOwners: owners.size,
+    inspect: () => ({ enabled: Boolean(enabled()), activeOwners: owners.size, queuedOwners: waiting.size,
       activeMappings: [...owners].filter(owner => owner.state === 'mapped').length,
       pendingOperations: [...owners].filter(owner => owner.promise).length,
       resourceTimers: [...owners].reduce((n, owner) => n + Number(!!owner.setupTimer) + Number(!!owner.cleanupTimer), 0),

package/src/console-router-mapping.test.mjs

@@ -63,6 +63,42 @@ test('exact concurrent owners release only their own actual candidate ports, wit
   assert.doesNotMatch(JSON.stringify(manager.inspect()), /192\.168|VuvoDesk-ICE-/);
 });
 
+test('media setup waits for one of four router slots and cancellation cannot start stale work', async () => {
+  const { manager, calls } = fixture();
+  const active = Array.from({length:4}, (_,n)=>manager.createOwner(key(n+1)));
+  try {
+    await Promise.all(active.map(owner=>owner.ready));
+    const queued = manager.createOwner(key(5), {queue:true});
+    const cancelled = manager.createOwner(key(6), {queue:true});
+    assert.equal(manager.inspect().activeOwners,4);
+    assert.equal(manager.inspect().queuedOwners,2);
+    assert.equal(manager.inspect().resourceSockets,4);
+    assert.equal(manager.createOwner(key(7)),null, 'legacy caller still has four immediate slots');
+    await cancelled.release();
+    await active[0].release();
+    await queued.ready;
+    assert.equal(manager.inspect().activeOwners,4);
+    assert.equal(manager.inspect().queuedOwners,0);
+    assert.equal(calls.filter(call=>call[0]==='add').length,5);
+  } finally { await manager.releaseAll(); }
+  assert.equal(manager.inspect().activeOwners,0);
+  assert.equal(manager.inspect().resourceSockets,0);
+  assert.equal(manager.inspect().resourceTimers,0);
+});
+
+test('queued setup is bounded and closing the family starts no queued router operations', async () => {
+  const { manager, calls } = fixture();
+  const active=Array.from({length:4},(_,n)=>manager.createOwner(key(n+1)));
+  await Promise.all(active.map(owner=>owner.ready));
+  for(let n=0;n<64;n++) assert.ok(manager.createOwner(key(n+5),{queue:true}));
+  assert.equal(manager.createOwner(key(100),{queue:true}),null);
+  await manager.releaseAll();
+  assert.equal(calls.filter(call=>call[0]==='add').length,4);
+  assert.equal(manager.inspect().queuedOwners,0);
+  assert.equal(manager.inspect().activeOwners,0);
+  assert.equal(manager.inspect().resourceTimers,0);
+});
+
 test('existing mappings and changed ownership are never overwritten or deleted', async () => {
   const { entries, calls, manager } = fixture();
   const foreign = { port: 54443, localAddress: '192.168.0.9', description: 'another-program', leaseSeconds: 0 };