livedesk 0.1.691 → 0.1.695

package/README.md

@@ -22,10 +22,14 @@ capture helpers, stale monitor generations, unbounded frame queues, or an
 unproven Direct/P2P/relay transition. Release builds run the same lifecycle,
 transport recovery, and browser H.264 population gates used by CI.
 
-## Unified launch
+## Unified launch
+
+The public command is `vuvodesk`. Its small npm entry package loads this exact
+`livedesk` runtime version in the same process. Existing `livedesk@latest`
+commands and update storage remain supported.
 
 ```powershell
-npx -y --prefer-online livedesk@latest
+npx -y --prefer-online vuvodesk@latest
 ```
 
 The first interactive launch asks whether this computer is a Hub or Client.
@@ -36,14 +40,14 @@ device role is available, it takes precedence over the offline cache.
 For development and migration checks, the role can be forced for one run:
 
 ```powershell
-npx -y --prefer-online livedesk@latest --force-role hub
-npx -y --prefer-online livedesk@latest --force-role client
+npx -y --prefer-online vuvodesk@latest --force-role hub
+npx -y --prefer-online vuvodesk@latest --force-role client
 ```
 
 ## Hub
 
 ```powershell
-npx -y --prefer-online livedesk@latest hub
+npx -y --prefer-online vuvodesk@latest hub
 ```
 
 This starts the VuvoDesk Hub, opens the local screen wall, accepts clients, and
@@ -67,7 +71,7 @@ and startup retry, then exits without looping.
 ## Client compatibility
 
 ```powershell
-npx -y --prefer-online livedesk@latest client 3
+npx -y --prefer-online vuvodesk@latest client 3
 ```
 
 The `client` form remains as a legacy compatibility alias. It records the
@@ -85,7 +89,7 @@ Screen Recording and Accessibility permissions, then explicitly confirm that
 the motion is already running:
 
 ```bash
-npx -y --prefer-online livedesk@latest diagnose mac-physical --confirm-active-motion
+npx -y --prefer-online vuvodesk@latest diagnose mac-physical --confirm-active-motion
 ```
 
 This command branches before role resolution, state migration, and the normal
@@ -105,7 +109,7 @@ result. It is written under `~/.livedesk/diagnostics`. To select a path relative
 to the directory where the command was invoked:
 
 ```bash
-npx -y --prefer-online livedesk@latest diagnose mac-physical --confirm-active-motion --report ./mac-result.json
+npx -y --prefer-online vuvodesk@latest diagnose mac-physical --confirm-active-motion --report ./mac-result.json
 ```
 
 Use `diagnose mac-physical --help` to inspect requirements without starting a
@@ -130,7 +134,7 @@ While the local Hub is running and at least one Client is sending a current
 Mode 3 H.264 stream, run:
 
 ```bash
-npx -y --prefer-online livedesk@latest diagnose transport-physical
+npx -y --prefer-online vuvodesk@latest diagnose transport-physical
 ```
 
 The diagnostic proves one unchanged stream identity through Direct TCP,

package/bin/livedesk.js

@@ -343,11 +343,11 @@ function printHelp() {
 VuvoDesk
 
 Usage:
-  npx -y --prefer-online livedesk@latest
-  npx -y --prefer-online livedesk@latest --force-role hub
-  npx -y --prefer-online livedesk@latest --force-role client
-  npx -y --prefer-online livedesk@latest diagnose mac-physical --confirm-active-motion
-  npx -y --prefer-online livedesk@latest diagnose transport-physical
+  npx -y --prefer-online vuvodesk@latest
+  npx -y --prefer-online vuvodesk@latest --force-role hub
+  npx -y --prefer-online vuvodesk@latest --force-role client
+  npx -y --prefer-online vuvodesk@latest diagnose mac-physical --confirm-active-motion
+  npx -y --prefer-online vuvodesk@latest diagnose transport-physical
 
 Commands:
   No command     Resolve the signed-in device role and start the matching runtime.
@@ -386,8 +386,8 @@ function printMacPhysicalDiagnosticHelp() {
 VuvoDesk macOS physical diagnostic
 
 Usage:
-  npx -y --prefer-online livedesk@latest diagnose mac-physical --confirm-active-motion
-  npx -y --prefer-online livedesk@latest diagnose mac-physical --confirm-active-motion --report ./mac-result.json
+  npx -y --prefer-online vuvodesk@latest diagnose mac-physical --confirm-active-motion
+  npx -y --prefer-online vuvodesk@latest diagnose mac-physical --confirm-active-motion --report ./mac-result.json
 
 Requirements:
   macOS with two connected displays showing visibly different, continuously moving content.
@@ -455,8 +455,8 @@ function printClientHelp() {
 VuvoDesk Client
 
 Usage:
-  npx -y --prefer-online livedesk@latest client
-  npx -y --prefer-online livedesk@latest client 3
+  npx -y --prefer-online vuvodesk@latest client
+  npx -y --prefer-online vuvodesk@latest client 3
 
 Default flow:
   Opens a VuvoDesk connection page with Google sign-in or a 6-digit PIN.
@@ -3270,7 +3270,7 @@ async function main() {
     const commandArgs = args.slice(1).map(value => String(value || '').trim().toLowerCase());
     if (commandArgs.some(value => value === '--help' || value === '-h' || value === 'help')) {
       if (command === 'client') {
-        console.warn('[VuvoDesk] Legacy client command detected. Use `npx -y --prefer-online livedesk@latest` for automatic role selection.');
+        console.warn('[VuvoDesk] Legacy client command detected. Use `npx -y --prefer-online vuvodesk@latest` for automatic role selection.');
         printClientHelp();
       } else {
         printHelp();
@@ -3279,7 +3279,7 @@ async function main() {
     }
     if (commandArgs.some(value => value === '--version' || value === '-v' || value === 'version')) {
       if (command === 'client') {
-        console.warn('[VuvoDesk] Legacy client command detected. Use `npx -y --prefer-online livedesk@latest` for automatic role selection.');
+        console.warn('[VuvoDesk] Legacy client command detected. Use `npx -y --prefer-online vuvodesk@latest` for automatic role selection.');
       }
       console.log(readVersion());
       return;
@@ -3302,7 +3302,7 @@ async function main() {
     writeRoleCache({ ...resolvedRole, source: 'local-cache', isOfflineFallback: false }, roleStateOptions);
     runtimeArgs = args.slice(1);
     if (command === 'client') {
-      console.warn('[VuvoDesk] Legacy client command detected. Use `npx -y --prefer-online livedesk@latest` for automatic role selection.');
+      console.warn('[VuvoDesk] Legacy client command detected. Use `npx -y --prefer-online vuvodesk@latest` for automatic role selection.');
     }
   } else {
     const forceDesktopBootstrap = process.env.LIVEDESK_DESKTOP_HOST === '1'

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.275",
+  "version": "0.1.276",
   "description": "VuvoDesk local remote client",
   "type": "module",
   "bin": {
@@ -42,10 +42,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.470",
-    "@livedesk/fast-osx-arm64": "0.1.470",
-    "@livedesk/fast-osx-x64": "0.1.470",
-    "@livedesk/fast-win-x64": "0.1.470"
+    "@livedesk/fast-linux-x64": "0.1.471",
+    "@livedesk/fast-osx-arm64": "0.1.471",
+    "@livedesk/fast-osx-x64": "0.1.471",
+    "@livedesk/fast-win-x64": "0.1.471"
   },
   "publishConfig": {
     "access": "public"

package/electron/electron-builder.linux-x64.yml

@@ -26,10 +26,11 @@ asarUnpack:
   - node_modules/node-datachannel/**
   - node_modules/@node-datachannel/linux-x64-gnu/**
 linux:
-  icon: packages/vuvodesk/electron/icon.png
+  icon: packages/vuvodesk/electron/linux-icons
   category: Utility
   executableName: livedesk
   maintainer: "lovecrdm <lovecrdm@gmail.com>"
+  synopsis: VuvoDesk remote desktop and screen wall
   target:
     - target: AppImage
       arch:
@@ -37,6 +38,21 @@ linux:
     - target: deb
       arch:
         - x64
+deb:
+  packageName: vuvodesk
+  packageCategory: utils
+  description: >-
+    View your computers together and control a selected screen with VuvoDesk.
+    Updates are checked and downloaded inside VuvoDesk. Installing a deb update
+    may require your administrator password.
+  fpm:
+    - --replaces
+    - livedesk
+    - --conflicts
+    - livedesk
+    - --provides
+    - livedesk
+    - packages/vuvodesk/electron/vuvodesk.metainfo.xml=/usr/share/metainfo/com.livedesk.desktop.metainfo.xml
 extraMetadata:
   homepage: https://vuvodesk.com
 publish:

package/electron/vuvodesk.metainfo.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="desktop-application">
+  <id>com.livedesk.desktop</id>
+  <metadata_license>MIT</metadata_license>
+  <project_license>MIT</project_license>
+  <name>VuvoDesk</name>
+  <summary>View and control your computers from one screen</summary>
+  <developer id="com.vuvodesk">
+    <name>VuvoDesk</name>
+  </developer>
+  <description>
+    <p>VuvoDesk brings your computers into a screen wall and lets you control a selected screen.</p>
+    <p>Connect with the desktop application or the mobile web app. Updates are checked inside VuvoDesk; installing a deb update may require your administrator password.</p>
+  </description>
+  <launchable type="desktop-id">livedesk.desktop</launchable>
+  <icon type="stock">livedesk</icon>
+  <url type="homepage">https://www.vuvodesk.com</url>
+  <url type="help">https://www.vuvodesk.com/support</url>
+  <categories>
+    <category>Utility</category>
+  </categories>
+  <provides>
+    <binary>livedesk</binary>
+  </provides>
+</component>

package/hub/package.json

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

package/hub/src/monitor-capture-ownership.mjs

@@ -0,0 +1,15 @@
+// Capture sharing is scoped to one physical monitor. Capability negotiation
+// keeps old Clients on their existing exclusive-capture protocol.
+export function supportsMonitorCapture(device) {
+  return device?.capabilities?.liveCaptureConcurrency === 'per-monitor';
+}
+
+export function captureOwnersCompete(existing, requested, perMonitor) {
+  if (!perMonitor) return true;
+  const existingMonitor = existing?.monitorIndex;
+  const requestedMonitor = requested?.monitorIndex;
+  if (!Number.isInteger(existingMonitor) || !Number.isInteger(requestedMonitor)) return true;
+  // Input ownership remains exclusive per computer, even on different screens.
+  return existingMonitor === requestedMonitor
+    || (existing.streamPurpose === 'control' && requested.streamPurpose === 'control');
+}

package/hub/src/monitor-capture-ownership.test.mjs

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { captureOwnersCompete, supportsMonitorCapture } from './monitor-capture-ownership.mjs';
+
+test('different monitors keep independent capture but the same monitor shares one owner', () => {
+  const wall = { monitorIndex: 0, streamPurpose: 'wall' };
+  assert.equal(captureOwnersCompete(wall, { ...wall, monitorIndex: 1 }, true), false);
+  assert.equal(captureOwnersCompete(wall, { ...wall, streamPurpose: 'control' }, true), true);
+  assert.equal(captureOwnersCompete(wall, { monitorIndex: 1, streamPurpose: 'control' }, true), false);
+  assert.equal(captureOwnersCompete({ ...wall, streamPurpose: 'control' },
+    { monitorIndex: 1, streamPurpose: 'control' }, true), true);
+  assert.equal(captureOwnersCompete(wall, { ...wall, monitorIndex: 1 }, false), true);
+  assert.equal(captureOwnersCompete(wall, { streamPurpose: 'wall' }, true), true);
+  assert.equal(supportsMonitorCapture({ capabilities: { liveCaptureConcurrency: 'per-monitor' } }), true);
+  assert.equal(supportsMonitorCapture({ capabilities: { liveCaptureConcurrency: 'exclusive' } }), false);
+});

package/hub/src/monitor-capture-runtime.test.mjs

@@ -0,0 +1,121 @@
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import { once } from 'node:events';
+import test from 'node:test';
+import { createRemoteHub } from './remote-hub.js';
+
+const keyFrame = Buffer.from([
+  0, 0, 0, 1, 0x67, 0x42, 0, 0x1f,
+  0, 0, 0, 1, 0x68, 0xce, 6, 0xe2,
+  0, 0, 0, 1, 0x65, 0x88, 0x84
+]).toString('base64');
+
+test('two monitor viewers and a Control handoff cannot replace or stop the other monitor', async () => {
+  const hub = createRemoteHub({
+    env: { ...process.env, LIVEDESK_REMOTE_HUB: '1', REMOTE_HUB_HOST: '127.0.0.1', REMOTE_HUB_PORT: '0' },
+    pairToken: 'monitor-owner-fixture'
+  });
+  let socket;
+  const commands = [];
+  const active = new Map();
+  const waitUntil = async predicate => {
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline) {
+      if (predicate()) return;
+      await new Promise(resolve => setTimeout(resolve, 5));
+    }
+    throw new Error('monitor owner fixture deadline');
+  };
+  try {
+    const status = await hub.start();
+    socket = net.createConnection({ host: '127.0.0.1', port: status.port });
+    await once(socket, 'connect');
+    const send = message => socket.write(`${JSON.stringify(message)}\n`);
+    let welcomed = false;
+    let input = '';
+    let frameSeq = 0;
+    const publishFrame = (streamId, payload, commandId) => {
+      send({ type: 'stream.open', ...payload, streamId, commandId, width: 960, height: 540 });
+      send({ type: 'stream.frame', ...payload, streamId, commandId, frameSeq: ++frameSeq,
+        width: 960, height: 540, mimeType: 'video/h264', isKeyFrame: true, chunkType: 'key', data: keyFrame });
+    };
+    socket.on('data', chunk => {
+      input += chunk.toString('utf8');
+      let newline;
+      while ((newline = input.indexOf('\n')) >= 0) {
+        const line = input.slice(0, newline); input = input.slice(newline + 1);
+        if (!line.trim()) continue;
+        const message = JSON.parse(line);
+        if (message.type === 'welcome') welcomed = true;
+        if (message.type !== 'command') continue;
+        commands.push(message);
+        if (message.command === 'stream.start') {
+          const p = message.payload;
+          for (const [id, owner] of active) {
+            assert.ok(id === p.streamId || owner.monitorIndex !== p.monitorIndex,
+              'same monitor cannot overlap a second native owner');
+          }
+          active.set(p.streamId, { ...p, commandId: message.commandId });
+          send({ type: 'command.result', commandId: message.commandId, result: {
+            stream: true, started: true, ...p, width: 960, height: 540
+          } });
+          publishFrame(p.streamId, p, message.commandId);
+        } else if (message.command === 'stream.stop') {
+          const streamId = message.payload.streamId;
+          if (streamId) active.delete(streamId); else active.clear();
+          send({ type: 'command.result', commandId: message.commandId,
+            result: { stream: true, stopped: true, streamId, stoppedCount: 1 } });
+        }
+      }
+    });
+    send({ type: 'hello', pairToken: 'monitor-owner-fixture', deviceId: 'monitor-device',
+      deviceName: 'Monitor fixture', hostname: 'monitor-fixture', platform: 'darwin', arch: 'arm64',
+      protocol: 'mindexec.remote.agent', protocolVersion: 2,
+      capabilities: { liveStream: true, liveCaptureConcurrency: 'per-monitor', frameProtocol: {}, frameModes: [] } });
+    await waitUntil(() => welcomed);
+    const options = { streamPurpose: 'wall', mode: 'mode3-h264-hw', frameMode: 'mode3-h264-hw',
+      fps: 30, maxWidth: 960, maxHeight: 540, quality: 68, reuseExisting: true, reuseSharedExisting: true };
+    const first = hub.startLiveStream('monitor-device', { ...options, monitorIndex: 0 });
+    assert.equal(first.ok, true);
+    await waitUntil(() => hub.getDeviceLiveFrame('monitor-device', { streamId: first.streamId })?.currentGenerationVerified);
+    const second = hub.startLiveStream('monitor-device', { ...options, monitorIndex: 1 });
+    assert.equal(second.ok, true);
+    assert.notEqual(second.streamId, first.streamId, 'Wall stream ids must include monitor ownership');
+    await waitUntil(() => hub.getDeviceLiveFrame('monitor-device', { streamId: second.streamId })?.currentGenerationVerified);
+    assert.equal(active.size, 2);
+    for (let i = 0; i < 10; i++) {
+      const monitorIndex = i % 2;
+      const original = monitorIndex ? second : first;
+      const reused = hub.startLiveStream('monitor-device', { ...options, monitorIndex, fps: 20 });
+      assert.equal(reused.reused, true);
+      assert.equal(reused.commandId, original.commandId);
+      assert.equal(reused.captureGeneration, original.captureGeneration);
+    }
+    assert.equal(commands.filter(c => c.command === 'stream.start').length, 2);
+    assert.equal(hub.getDeviceLiveFrame('monitor-device', { streamId: first.streamId }).monitorIndex, 0);
+    const controlOptions = { ...options, streamPurpose: 'control', monitorIndex: 1 };
+    const transition = hub.startLiveStream('monitor-device', controlOptions);
+    assert.equal(transition.error, 'CAPTURE_TRANSITION_IN_PROGRESS');
+    await transition.transitionPromise;
+    const control = hub.startLiveStream('monitor-device', controlOptions);
+    assert.equal(control.ok, true);
+    await waitUntil(() => active.has(control.streamId));
+    assert.ok(active.has(first.streamId));
+    assert.ok(!active.has(second.streamId));
+    assert.equal(active.size, 2);
+    const wallWhileOtherControl = hub.startLiveStream('monitor-device', { ...options, monitorIndex: 0 });
+    assert.equal(wallWhileOtherControl.commandId, first.commandId);
+    assert.equal(wallWhileOtherControl.captureGeneration, first.captureGeneration);
+    const selectedStop = hub.stopLiveStream('monitor-device', { streamPurpose: 'wall', monitorIndex: 0 });
+    assert.equal((await selectedStop.stopPromise).captureStopConfirmed, true);
+    assert.ok(active.has(control.streamId));
+    assert.ok(!active.has(first.streamId));
+    const controlStop = hub.stopLiveStream('monitor-device', { streamId: control.streamId, streamPurpose: 'control' });
+    assert.equal((await controlStop.stopPromise).captureStopConfirmed, true);
+    assert.equal(active.size, 0);
+    assert.equal(hub.getLiveCaptureResourceSnapshot('monitor-device').terminal, true);
+  } finally {
+    socket?.destroy();
+    await hub.close();
+  }
+});

package/hub/src/monitor-capture-viewers.test.mjs

@@ -0,0 +1,229 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp } from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import WebSocket from 'ws';
+
+async function freePort() {
+  const server = net.createServer();
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const port = server.address().port;
+  await new Promise(resolve => server.close(resolve));
+  return port;
+}
+
+async function until(predicate, label, timeout = 6000) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    if (await predicate()) return;
+    await new Promise(resolve => setTimeout(resolve, 15));
+  }
+  throw new Error(`Monitor viewers: ${label}`);
+}
+
+test('real frame sockets keep different monitor bindings and release only the last viewer of each monitor', {
+  timeout: 25000
+}, async () => {
+  const httpPort = await freePort();
+  let agentPort = await freePort();
+  while (agentPort === httpPort) agentPort = await freePort();
+  const dataDir = await mkdtemp(path.join(os.tmpdir(), 'vuvodesk-monitor-viewers-'));
+  const base = `http://127.0.0.1:${httpPort}`;
+  const deviceId = 'two-monitor-agent';
+  const pairToken = 'two-monitor-fixture';
+  const root = fileURLToPath(new URL('../../../', import.meta.url));
+  const child = spawn(process.execPath, [fileURLToPath(new URL('./server.js', import.meta.url))], {
+    cwd: root, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, LIVEDESK_DATA_DIR: dataDir,
+      LIVEDESK_HUB_HTTP_HOST: '127.0.0.1', LIVEDESK_HUB_HTTP_PORT: String(httpPort),
+      REMOTE_HUB_HOST: '127.0.0.1', REMOTE_HUB_PORT: String(agentPort),
+      REMOTE_HUB_PAIR_TOKEN: pairToken, REMOTE_HUB_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS: '750',
+      LIVEDESK_FRAME_STREAM_STOP_GRACE_MS: '25', LIVEDESK_PUBLIC_IP_DISCOVERY_DISABLED: '1',
+      REMOTE_HUB_PUBLIC_IP_DISCOVERY_DISABLED: '1', LIVEDESK_TEST_MODE: '1',
+      LIVEDESK_TEST_LICENSE_PLAN: 'pro', LIVEDESK_UDP_ENABLED: '0' }
+  });
+  const output = [];
+  for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => {
+    output.push(String(chunk)); while (output.length > 40) output.shift();
+  });
+  const sockets = [];
+  const commands = [];
+  const active = new Map();
+  const media = new Map();
+  const mediaSockets = [];
+  let agent, welcomed = false, sessionId = '', timer, sequence = 0;
+  const send = message => agent.write(`${JSON.stringify(message)}\n`);
+  const frameMessage = owner => ({ type: 'stream.frame', ...owner, frameSeq: ++sequence,
+    width: 960, height: 540, codec: 'h264', mimeType: 'video/h264',
+    isKeyFrame: true, chunkType: 'key', data: Buffer.from([
+      0, 0, 0, 1, 0x67, 0x42, 0, 0x1f, 0, 0, 0, 1, 0x68, 0xce, 6, 0xe2,
+      0, 0, 0, 1, 0x65, 0x88, 0x84
+    ]).toString('base64') });
+  const frame = owner => {
+    const socket = media.get(owner.streamId);
+    if (socket && !socket.destroyed && socket.readyForFrames)
+      socket.write(`${JSON.stringify(frameMessage(owner))}\n`);
+  };
+  async function connectMedia(owner, expectAccepted = true) {
+    const socket = net.createConnection({ host: '127.0.0.1', port: agentPort });
+    mediaSockets.push(socket);
+    const received = [];
+    let pending = '';
+    socket.on('data', data => {
+      pending += String(data);
+      let newline;
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        const raw = pending.slice(0, newline); pending = pending.slice(newline + 1);
+        if (raw.trim()) received.push(JSON.parse(raw));
+      }
+    });
+    await once(socket, 'connect');
+    socket.write(`${JSON.stringify({ type: 'hello', channel: 'frame', deviceId, pairToken,
+      parentSessionId: sessionId, frameOwner: { streamId: owner.streamId, commandId: owner.commandId,
+        captureGeneration: owner.captureGeneration, monitorIndex: owner.monitorIndex } })}\n`);
+    await until(() => received.length > 0, 'monitor channel welcome');
+    if (expectAccepted) {
+      assert.equal(received[0].type, 'welcome');
+      assert.equal(received[0].frameOwner.monitorIndex, owner.monitorIndex);
+      socket.readyForFrames = true;
+      media.set(owner.streamId, socket);
+    } else {
+      assert.equal(received[0].error, 'frame-channel-owner-stale');
+      await until(() => socket.destroyed, 'stale channel rejection');
+    }
+    return socket;
+  }
+  async function connectViewer(monitorIndex, streamPurpose = 'wall') {
+    const ws = new WebSocket(`ws://127.0.0.1:${httpPort}/api/remote/frames/ws?devices=${deviceId}`,
+      { headers: { Origin: base }, perMessageDeflate: false });
+    sockets.push(ws);
+    const messages = [], frames = [];
+    ws.on('message', (data, binary) => {
+      if (binary) {
+        const length = data.readUInt32BE(0);
+        frames.push(JSON.parse(data.subarray(4, 4 + length).toString()));
+      } else messages.push(JSON.parse(String(data)));
+    });
+    await once(ws, 'open');
+    await until(() => messages.some(m => m.type === 'RemoteFrameSocketReady'), 'socket ready');
+    ws.send(JSON.stringify({ type: 'subscribe', deviceIds: [deviceId], autoStartLive: true,
+      allowReadOnlyControlBorrow: true, streamPurpose, monitorIndex,
+      mode: 'mode3-h264-hw', frameMode: 'mode3-h264-hw', fps: 30,
+      maxWidth: 960, maxHeight: 540, quality: 68 }));
+    await until(() => frames.length > 0, `monitor ${monitorIndex} first frame`);
+    return { ws, messages, frames, monitorIndex };
+  }
+  const starts = () => commands.filter(c => c.command === 'stream.start');
+  const close = async viewer => { viewer.ws.close(); await once(viewer.ws, 'close'); };
+  try {
+    await until(async () => {
+      if (child.exitCode !== null) throw new Error(`Hub exited: ${output.join('')}`);
+      try { return (await fetch(`${base}/api/health`)).ok; } catch { return false; }
+    }, 'isolated Hub health', 10000);
+    agent = net.createConnection({ host: '127.0.0.1', port: agentPort });
+    await once(agent, 'connect');
+    let input = '';
+    agent.on('data', chunk => {
+      input += String(chunk);
+      let newline;
+      while ((newline = input.indexOf('\n')) >= 0) {
+        const raw = input.slice(0, newline); input = input.slice(newline + 1);
+        if (!raw.trim()) continue;
+        const message = JSON.parse(raw);
+        if (message.type === 'welcome') { welcomed = true; sessionId = message.sessionId; }
+        if (message.type !== 'command') continue;
+        commands.push(message);
+        if (message.command === 'stream.start') {
+          const owner = { ...message.payload, commandId: message.commandId };
+          active.set(owner.streamId, owner);
+          send({ type: 'command.result', commandId: message.commandId,
+            result: { ...owner, stream: true, started: true } });
+          send({ type: 'stream.open', ...owner, width: 960, height: 540 });
+          void connectMedia(owner).then(() => frame(owner));
+        } else if (message.command === 'stream.stop') {
+          if (message.payload.streamId) {
+            media.get(message.payload.streamId)?.destroy();
+            media.delete(message.payload.streamId);
+            active.delete(message.payload.streamId);
+          } else {
+            for (const socket of media.values()) socket.destroy();
+            media.clear(); active.clear();
+          }
+          send({ type: 'command.result', commandId: message.commandId,
+            result: { stream: true, stopped: true, streamId: message.payload.streamId } });
+        }
+      }
+    });
+    send({ type: 'hello', pairToken, deviceId, deviceName: 'Two monitor fixture', platform: 'darwin',
+      arch: 'arm64', protocol: 'mindexec.remote.agent', protocolVersion: 2,
+      capabilities: { liveStream: true, liveCaptureConcurrency: 'per-monitor', frameProtocol: {}, frameModes: [] } });
+    await until(() => welcomed, 'Agent welcome');
+    timer = setInterval(() => { for (const owner of active.values()) frame(owner); }, 40);
+    const hub = await connectViewer(0);
+    const pwa = await connectViewer(1);
+    const phone = await connectViewer(0);
+    await until(() => hub.frames.length >= 4 && pwa.frames.length >= 4 && phone.frames.length >= 4,
+      'all three viewers receive frames');
+    assert.equal(starts().length, 2, 'same monitor viewer created duplicate capture');
+    const original = [hub.frames[0], pwa.frames[0]];
+    for (const viewer of [hub, pwa, phone]) {
+      assert.ok(viewer.frames.every(f => f.monitorIndex === viewer.monitorIndex), 'cross-monitor frame delivery');
+      assert.ok(viewer.frames.every(f => f.commandId === original[viewer.monitorIndex].commandId), 'capture churn');
+    }
+    const zero = [...active.values()].find(o => o.monitorIndex === 0);
+    const one = [...active.values()].find(o => o.monitorIndex === 1);
+    await connectMedia({ ...zero, captureGeneration: zero.captureGeneration + 100 }, false);
+    assert.equal(media.get(zero.streamId).destroyed, false, 'stale hello replaced current monitor channel');
+    const wrongChannel = media.get(zero.streamId);
+    wrongChannel.write(`${JSON.stringify(frameMessage(one))}\n`);
+    await until(() => wrongChannel.destroyed, 'cross-monitor packet closes only its channel');
+    const otherCount = pwa.frames.length;
+    await until(() => pwa.frames.length >= otherCount + 3, 'healthy monitor survives peer channel failure');
+    await connectMedia(zero);
+    const resumedCount = hub.frames.length;
+    await until(() => hub.frames.length >= resumedCount + 3, 'exact monitor channel reconnects');
+    assert.equal(starts().length, 2, 'transport reconnect restarted native capture');
+    await close(hub);
+    const phoneCount = phone.frames.length;
+    await until(() => phone.frames.length >= phoneCount + 3, 'same-monitor peer continues after close');
+    assert.equal(active.size, 2);
+    await close(pwa);
+    await until(() => active.size === 1, 'last monitor-one viewer stops capture');
+    assert.equal([...active.values()][0].monitorIndex, 0);
+    assert.equal([...active.values()][0].commandId, original[0].commandId);
+    const rejoined = await connectViewer(1);
+    assert.equal(starts().length, 3);
+    assert.notEqual(rejoined.frames[0].captureGeneration, original[1].captureGeneration);
+    assert.equal([...active.values()].find(o => o.monitorIndex === 0).commandId, original[0].commandId);
+    const controller = await connectViewer(1, 'control');
+    await until(() => rejoined.frames.some(f => f.streamPurpose === 'control'), 'same-monitor Wall borrows Control');
+    assert.equal(starts().length, 4);
+    assert.equal([...active.values()].find(o => o.monitorIndex === 0).commandId, original[0].commandId);
+    const borrowedIndex = rejoined.frames.length;
+    await close(controller);
+    await until(() => rejoined.frames.slice(borrowedIndex).some(f => f.streamPurpose === 'wall'),
+      'Control exit restores only its monitor Wall');
+    assert.equal(starts().length, 5);
+    assert.equal([...active.values()].find(o => o.monitorIndex === 0).commandId, original[0].commandId);
+    await close(rejoined);
+    await close(phone);
+    await until(() => active.size === 0, 'final viewer cleanup');
+    assert.equal(commands.filter(c => c.command === 'stream.stop').length, 5);
+  } catch (error) {
+    error.message += `\nIsolated Hub tail: ${output.join('').slice(-2500)}`;
+    throw error;
+  } finally {
+    clearInterval(timer);
+    for (const socket of sockets) socket.terminate();
+    for (const socket of mediaSockets) socket.destroy();
+    agent?.destroy();
+    child.kill();
+    if (child.exitCode === null) await once(child, 'exit');
+  }
+});