@livedesk/hub 0.1.59 → 0.1.61

package/src/control-presentation-borrow-contract.test.mjs

@@ -0,0 +1,999 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import net from 'node:net';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import WebSocket from 'ws';
+
+import { createRemoteHub } from './remote-hub.js';
+import {
+  READ_ONLY_CONTROL_PRESENTATION_MAX_IDLE_MS,
+  READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS,
+  createReadOnlyControlPresentationReconcileCoordinator,
+  resolveReadOnlyControlPresentationBorrow
+} from './live-stream-monitor-contract.js';
+
+const NOW_EPOCH_MS = Date.parse('2026-08-29T12:00:00.000Z');
+
+function createHealthyDevice() {
+  return {
+    sessionId: 'session-current',
+    activeLiveStream: {
+      active: true,
+      open: true,
+      stopPending: false,
+      stopCommandId: '',
+      pendingDescriptor: null,
+      sessionId: 'session-current',
+      streamId: 'control-stream-current',
+      commandId: 'control-command-current',
+      captureGeneration: 7,
+      monitorIndex: 1,
+      streamPurpose: 'control',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      readyFrameReceived: true,
+      framesReceived: 120,
+      lastFrameAt: new Date(NOW_EPOCH_MS - 250).toISOString(),
+      fps: 30,
+      maxWidth: 1920,
+      maxHeight: 1080,
+      quality: 72,
+      latestFrame: {
+        currentGenerationVerified: true,
+        sessionId: 'session-current',
+        streamId: 'control-stream-current',
+        commandId: 'control-command-current',
+        captureGeneration: 7,
+        monitorIndex: 1,
+        streamPurpose: 'control'
+      }
+    }
+  };
+}
+
+function createWallOptions(overrides = {}) {
+  return {
+    allowReadOnlyControlBorrow: true,
+    streamPurpose: 'wall',
+    frameMode: 'mode3-h264-hw',
+    fps: 12,
+    maxWidth: 960,
+    maxHeight: 540,
+    quality: 55,
+    ...overrides
+  };
+}
+
+function resolve(device = createHealthyDevice(), liveOptions = createWallOptions(), monitorIndex = 1) {
+  return resolveReadOnlyControlPresentationBorrow({
+    device,
+    liveOptions,
+    monitorIndex,
+    nowEpochMs: NOW_EPOCH_MS
+  });
+}
+
+test('a Wall observer borrows only the exact healthy Control H.264 binding', () => {
+  assert.deepEqual(resolve(), {
+    ok: true,
+    commandId: 'control-command-current',
+    sessionId: 'session-current',
+    streamId: 'control-stream-current',
+    streamPurpose: 'control',
+    fps: 30,
+    mode: 'mode3-h264-hw',
+    frameMode: 'mode3-h264-hw',
+    monitorIndex: 1,
+    captureGeneration: 7,
+    ready: true,
+    reused: true,
+    readOnlyControlBorrow: true,
+    presentationPurpose: 'wall',
+    requestedProfile: {
+      fps: 12,
+      maxWidth: 960,
+      maxHeight: 540,
+      quality: 55
+    },
+    effectiveProfile: {
+      fps: 30,
+      maxWidth: 1920,
+      maxHeight: 1080,
+      quality: 72
+    }
+  });
+});
+
+test('borrowing requires an explicit Wall observer request', () => {
+  assert.equal(resolve(createHealthyDevice(), createWallOptions({
+    allowReadOnlyControlBorrow: false
+  })), null);
+  assert.equal(resolve(createHealthyDevice(), createWallOptions({
+    streamPurpose: 'control'
+  })), null);
+});
+
+test('borrowing rejects a different monitor and an idle Control frame', () => {
+  assert.equal(resolve(createHealthyDevice(), createWallOptions(), 0), null);
+
+  const staleDevice = createHealthyDevice();
+  staleDevice.activeLiveStream.lastFrameAt = new Date(
+    NOW_EPOCH_MS - READ_ONLY_CONTROL_PRESENTATION_MAX_IDLE_MS - 1
+  ).toISOString();
+  assert.equal(resolve(staleDevice), null);
+});
+
+test('borrowing rejects a stopping or replacement-pending Control stream', () => {
+  for (const activePatch of [
+    { stopPending: true },
+    { stopCommandId: 'stop-command-current' },
+    { pendingDescriptor: { commandId: 'replacement-command' } }
+  ]) {
+    const device = createHealthyDevice();
+    Object.assign(device.activeLiveStream, activePatch);
+    assert.equal(resolve(device), null);
+  }
+});
+
+test('borrowing rejects non-Control purpose and non-hardware-H.264 modes', () => {
+  const wrongPurpose = createHealthyDevice();
+  wrongPurpose.activeLiveStream.streamPurpose = 'wall';
+  assert.equal(resolve(wrongPurpose), null);
+
+  const wrongActiveMode = createHealthyDevice();
+  wrongActiveMode.activeLiveStream.frameMode = 'mode2-jpeg';
+  wrongActiveMode.activeLiveStream.mode = 'mode2-jpeg';
+  assert.equal(resolve(wrongActiveMode), null);
+
+  assert.equal(resolve(createHealthyDevice(), createWallOptions({
+    frameMode: 'mode2-jpeg'
+  })), null);
+});
+
+test('borrowing rejects a latest frame owned by another exact binding', () => {
+  for (const [field, value] of [
+    ['sessionId', 'session-old'],
+    ['streamId', 'control-stream-old'],
+    ['commandId', 'control-command-old'],
+    ['captureGeneration', 6],
+    ['monitorIndex', 0],
+    ['streamPurpose', 'wall']
+  ]) {
+    const device = createHealthyDevice();
+    device.activeLiveStream.latestFrame[field] = value;
+    assert.equal(resolve(device), null, `latest frame ${field} mismatch must be rejected`);
+  }
+});
+
+function createFakeReconcileTimers() {
+  const owners = [];
+  return {
+    owners,
+    setTimeoutFn(callback, delayMs) {
+      const owner = {
+        callback,
+        delayMs,
+        cleared: false,
+        unrefCalls: 0,
+        unref() {
+          owner.unrefCalls += 1;
+        }
+      };
+      owners.push(owner);
+      return owner;
+    },
+    clearTimeoutFn(owner) {
+      owner.cleared = true;
+    },
+    fire(owner) {
+      if (!owner.cleared) owner.callback();
+    }
+  };
+}
+
+test('a replacement Control cancels the one deferred stop reconcile and Ready rebinds immediately', () => {
+  const timers = createFakeReconcileTimers();
+  const reconciledDeviceIds = [];
+  const coordinator = createReadOnlyControlPresentationReconcileCoordinator({
+    onReconcile: deviceId => reconciledDeviceIds.push(deviceId),
+    setTimeoutFn: timers.setTimeoutFn,
+    clearTimeoutFn: timers.clearTimeoutFn
+  });
+
+  assert.equal(coordinator.scheduleAfterConfirmedStop(' mac-current '), true);
+  assert.equal(coordinator.scheduleAfterConfirmedStop('mac-current'), false);
+  assert.equal(coordinator.getPendingCount(), 1);
+  assert.equal(timers.owners.length, 1);
+  assert.equal(timers.owners[0].delayMs, READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS);
+  assert.equal(timers.owners[0].unrefCalls, 1);
+
+  assert.equal(coordinator.cancelForControlTransition('mac-current'), true);
+  assert.equal(coordinator.getPendingCount(), 0);
+  assert.equal(timers.owners[0].cleared, true);
+  timers.fire(timers.owners[0]);
+  assert.deepEqual(reconciledDeviceIds, []);
+
+  assert.equal(coordinator.scheduleAfterConfirmedStop('mac-current'), true);
+  assert.equal(coordinator.reconcileReadyControl('mac-current'), true);
+  assert.equal(timers.owners[1].cleared, true);
+  assert.equal(coordinator.getPendingCount(), 0);
+  assert.deepEqual(reconciledDeviceIds, ['mac-current']);
+  timers.fire(timers.owners[1]);
+  assert.deepEqual(reconciledDeviceIds, ['mac-current']);
+});
+
+test('closing the reconcile coordinator releases every timer and rejects later work', () => {
+  const timers = createFakeReconcileTimers();
+  const reconciledDeviceIds = [];
+  const coordinator = createReadOnlyControlPresentationReconcileCoordinator({
+    onReconcile: deviceId => reconciledDeviceIds.push(deviceId),
+    setTimeoutFn: timers.setTimeoutFn,
+    clearTimeoutFn: timers.clearTimeoutFn
+  });
+
+  coordinator.scheduleAfterConfirmedStop('mac-a');
+  coordinator.scheduleAfterConfirmedStop('mac-b');
+  assert.equal(coordinator.getPendingCount(), 2);
+  coordinator.close();
+  assert.equal(coordinator.getPendingCount(), 0);
+  assert.deepEqual(timers.owners.map(owner => owner.cleared), [true, true]);
+  assert.equal(coordinator.scheduleAfterConfirmedStop('mac-c'), false);
+  assert.equal(coordinator.reconcileReadyControl('mac-c'), false);
+  for (const owner of timers.owners) timers.fire(owner);
+  assert.deepEqual(reconciledDeviceIds, []);
+});
+
+test('the authoritative Hub borrows without stream.start and still enforces current policy', async () => {
+  let remoteAccessBlocked = false;
+  const hub = createRemoteHub({
+    env: {
+      ...process.env,
+      LIVEDESK_REMOTE_HUB: '1',
+      REMOTE_HUB_HOST: '127.0.0.1',
+      REMOTE_HUB_PORT: '0'
+    },
+    pairToken: 'control-presentation-borrow-token',
+    getEffectiveDevicePolicy: () => remoteAccessBlocked
+      ? { accessMode: 'block-remote-access' }
+      : {}
+  });
+  let socket;
+  try {
+    const status = await hub.start();
+    socket = net.createConnection({ host: '127.0.0.1', port: status.port });
+    await once(socket, 'connect');
+
+    const messages = [];
+    let incoming = '';
+    socket.on('data', chunk => {
+      incoming += chunk.toString('utf8');
+      let newline = incoming.indexOf('\n');
+      while (newline >= 0) {
+        const line = incoming.slice(0, newline).trim();
+        incoming = incoming.slice(newline + 1);
+        if (line) messages.push(JSON.parse(line));
+        newline = incoming.indexOf('\n');
+      }
+    });
+    const waitUntil = async predicate => {
+      const deadline = Date.now() + 2_000;
+      while (Date.now() < deadline) {
+        if (predicate()) return;
+        await new Promise(resolveWait => setTimeout(resolveWait, 10));
+      }
+      throw new Error('timed out waiting for authoritative Control borrow fixture');
+    };
+    const send = message => socket.write(`${JSON.stringify(message)}\n`);
+
+    send({
+      type: 'hello',
+      pairToken: 'control-presentation-borrow-token',
+      deviceId: 'control-presentation-device',
+      deviceName: 'Control presentation fixture',
+      hostname: 'control-presentation-fixture',
+      platform: 'darwin',
+      arch: 'arm64',
+      protocol: 'mindexec.remote.agent',
+      protocolVersion: 2,
+      capabilities: { liveStream: true, frameProtocol: {}, frameModes: [] }
+    });
+    await waitUntil(() => messages.some(message => message.type === 'welcome'));
+
+    const controlOptions = {
+      streamId: 'control-control-presentation-device',
+      streamPurpose: 'control',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      fps: 30,
+      maxWidth: 1920,
+      maxHeight: 1080,
+      quality: 72,
+      monitorIndex: 0
+    };
+    const control = hub.startLiveStream('control-presentation-device', {
+      ...controlOptions,
+      commandId: 'control-presentation-command'
+    });
+    assert.equal(control.ok, true);
+    await waitUntil(() => messages.some(message => (
+      message.type === 'command'
+      && message.command === 'stream.start'
+      && message.commandId === control.commandId
+    )));
+
+    send({
+      type: 'stream.open',
+      streamId: control.streamId,
+      commandId: control.commandId,
+      captureGeneration: control.captureGeneration,
+      monitorIndex: 0,
+      streamPurpose: 'control',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      codec: 'h264',
+      width: 1920,
+      height: 1080
+    });
+    send({
+      type: 'stream.frame',
+      streamId: control.streamId,
+      commandId: control.commandId,
+      captureGeneration: control.captureGeneration,
+      monitorIndex: 0,
+      streamPurpose: 'control',
+      frameSeq: 1,
+      frameMode: 'mode3-h264-hw',
+      codec: 'h264',
+      mimeType: 'video/h264',
+      isKeyFrame: true,
+      chunkType: 'key',
+      width: 1920,
+      height: 1080,
+      data: Buffer.from([
+        0x00, 0x00, 0x00, 0x01, 0x67, 0x42, 0x00, 0x1f,
+        0x00, 0x00, 0x00, 0x01, 0x68, 0xce, 0x06, 0xe2,
+        0x00, 0x00, 0x00, 0x01, 0x65, 0x88, 0x84
+      ]).toString('base64')
+    });
+    await waitUntil(() => hub.getDeviceLiveFrame('control-presentation-device')?.currentGenerationVerified === true);
+
+    const streamStartCount = messages.filter(message => message.command === 'stream.start').length;
+    const wallRequest = {
+      streamPurpose: 'wall',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      fps: 5,
+      maxWidth: 960,
+      maxHeight: 540,
+      quality: 55,
+      monitorIndex: 0
+    };
+    const borrowed = hub.startLiveStream('control-presentation-device', {
+      ...wallRequest,
+      allowReadOnlyControlBorrow: true,
+      reuseExisting: true
+    });
+    assert.equal(borrowed.ok, true);
+    assert.equal(borrowed.readOnlyControlBorrow, true);
+    assert.equal(borrowed.presentationPurpose, 'wall');
+    assert.equal(borrowed.streamPurpose, 'control');
+    assert.equal(borrowed.streamId, control.streamId);
+    assert.equal(borrowed.commandId, control.commandId);
+    assert.equal(borrowed.captureGeneration, control.captureGeneration);
+    assert.deepEqual(borrowed.effectiveProfile, {
+      fps: 30,
+      maxWidth: 1920,
+      maxHeight: 1080,
+      quality: 72
+    });
+    await new Promise(resolveWait => setTimeout(resolveWait, 20));
+    assert.equal(messages.filter(message => message.command === 'stream.start').length, streamStartCount);
+
+    const unflagged = hub.startLiveStream('control-presentation-device', wallRequest);
+    assert.equal(unflagged.ok, false);
+    assert.equal(unflagged.error, 'CONTROL_CAPTURE_OWNS_DEVICE');
+
+    remoteAccessBlocked = true;
+    const blocked = hub.startLiveStream('control-presentation-device', {
+      ...wallRequest,
+      allowReadOnlyControlBorrow: true
+    });
+    assert.equal(blocked.ok, false);
+    assert.equal(blocked.error, 'remote-access-blocked-by-settings');
+    assert.equal(messages.filter(message => message.command === 'stream.start').length, streamStartCount);
+  } finally {
+    socket?.destroy();
+    await hub.close();
+  }
+});
+
+async function reserveBorrowLifecyclePort(excluded = new Set()) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const server = net.createServer();
+    await new Promise((resolveListen, rejectListen) => {
+      server.once('error', rejectListen);
+      server.listen(0, '127.0.0.1', resolveListen);
+    });
+    const port = Number(server.address()?.port || 0);
+    await new Promise(resolveClose => server.close(resolveClose));
+    if (port > 0 && !excluded.has(port)) return port;
+  }
+  throw new Error('Could not reserve an isolated Control borrow lifecycle port.');
+}
+
+async function waitForBorrowLifecycle(read, label, timeoutMs = 4_000, intervalMs = 10) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      const value = await read();
+      if (value) return value;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise(resolveWait => setTimeout(resolveWait, intervalMs));
+  }
+  throw new Error(
+    `Timed out waiting for ${label}.`
+    + (lastError ? ` Last error: ${lastError.message}` : '')
+  );
+}
+
+function collectBorrowLifecycleProcessOutput(child, limit = 100) {
+  const lines = [];
+  const collect = chunk => {
+    lines.push(...String(chunk || '').split(/\r?\n/).filter(Boolean));
+    while (lines.length > limit) lines.shift();
+  };
+  child.stdout?.on('data', collect);
+  child.stderr?.on('data', collect);
+  return lines;
+}
+
+async function terminateBorrowLifecycleProcess(child) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  child.kill();
+  const exited = await Promise.race([
+    once(child, 'exit').then(() => true),
+    new Promise(resolveWait => setTimeout(() => resolveWait(false), 3_000))
+  ]);
+  if (!exited && child.exitCode === null && child.signalCode === null) {
+    child.kill('SIGKILL');
+    await Promise.race([
+      once(child, 'exit'),
+      new Promise(resolveWait => setTimeout(resolveWait, 1_000))
+    ]);
+  }
+}
+
+function parseBorrowLifecycleFramePacket(data) {
+  if (!Buffer.isBuffer(data) || data.length < 5) return null;
+  const metadataLength = data.readUInt32BE(0);
+  if (metadataLength <= 0 || metadataLength > data.length - 4) return null;
+  try {
+    return JSON.parse(data.subarray(4, 4 + metadataLength).toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+test('the browser Wall borrower follows exact Control key frames without owning native capture', {
+  timeout: 20_000
+}, async () => {
+  const {
+    READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS
+  } = await import('./live-stream-monitor-contract.js');
+  const usedPorts = new Set();
+  const httpPort = await reserveBorrowLifecyclePort(usedPorts);
+  usedPorts.add(httpPort);
+  const remotePort = await reserveBorrowLifecyclePort(usedPorts);
+  const pairToken = `control-borrow-ws-${process.pid}-${Date.now().toString(36)}`;
+  const deviceId = `control-borrow-ws-device-${process.pid}`;
+  const baseUrl = `http://127.0.0.1:${httpPort}`;
+  const hubServerPath = fileURLToPath(new URL('./server.js', import.meta.url));
+  const rootDir = fileURLToPath(new URL('../../../', import.meta.url));
+  let hubProcess = null;
+  let agentSocket = null;
+  const browserSockets = [];
+  const agentMessages = [];
+  const stopAcknowledgedAtByCommandId = new Map();
+  let hubOutput = [];
+
+  const postJson = async (path, body) => {
+    const response = await fetch(`${baseUrl}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    });
+    const payload = await response.json();
+    assert.equal(response.ok, true, `${path} HTTP request failed: ${JSON.stringify(payload)}`);
+    return payload;
+  };
+
+  const sendAgent = payload => {
+    assert.equal(agentSocket?.destroyed, false, 'The fake macOS Agent socket must still be open.');
+    agentSocket.write(`${JSON.stringify(payload)}\n`);
+  };
+
+  const waitForAgentCommand = (predicate, label, fromIndex = 0) => waitForBorrowLifecycle(
+    () => agentMessages.slice(fromIndex).find(record => (
+      record.message?.type === 'command' && predicate(record.message)
+    )),
+    label
+  );
+
+  const sendOpen = binding => sendAgent({
+    type: 'stream.open',
+    streamId: binding.streamId,
+    commandId: binding.commandId,
+    captureGeneration: binding.captureGeneration,
+    monitorIndex: 0,
+    streamPurpose: 'control',
+    mode: 'mode3-h264-hw',
+    frameMode: 'mode3-h264-hw',
+    codec: 'h264',
+    width: 1920,
+    height: 1080
+  });
+
+  const sendControlFrame = (binding, frameSeq, isKeyFrame) => sendAgent({
+    type: 'stream.frame',
+    streamId: binding.streamId,
+    commandId: binding.commandId,
+    captureGeneration: binding.captureGeneration,
+    monitorIndex: 0,
+    streamPurpose: 'control',
+    frameSeq,
+    frameMode: 'mode3-h264-hw',
+    codec: 'h264',
+    mimeType: 'video/h264',
+    isKeyFrame,
+    chunkType: isKeyFrame ? 'key' : 'delta',
+    width: 1920,
+    height: 1080,
+    data: Buffer.from(isKeyFrame
+      ? [
+          0x00, 0x00, 0x00, 0x01, 0x67, 0x42, 0x00, 0x1f,
+          0x00, 0x00, 0x00, 0x01, 0x68, 0xce, 0x06, 0xe2,
+          0x00, 0x00, 0x00, 0x01, 0x65, frameSeq & 0xff, 0x84
+        ]
+      : [0x00, 0x00, 0x00, 0x01, 0x41, frameSeq & 0xff, 0x11]
+    ).toString('base64')
+  });
+
+  const connectBorrower = async label => {
+    const socket = new WebSocket(
+      `ws://127.0.0.1:${httpPort}/api/remote/frames/ws?devices=${encodeURIComponent(deviceId)}`,
+      { headers: { Origin: baseUrl }, perMessageDeflate: false }
+    );
+    const observed = { json: [], frames: [] };
+    socket.on('message', (data, isBinary) => {
+      if (isBinary) {
+        const metadata = parseBorrowLifecycleFramePacket(data);
+        if (metadata) observed.frames.push(metadata);
+        return;
+      }
+      try {
+        observed.json.push(JSON.parse(Buffer.isBuffer(data) ? data.toString('utf8') : String(data)));
+      } catch {
+        // This isolated contract records only valid Hub JSON control messages.
+      }
+    });
+    browserSockets.push(socket);
+    await Promise.race([
+      once(socket, 'open'),
+      once(socket, 'error').then(([error]) => Promise.reject(error))
+    ]);
+    await waitForBorrowLifecycle(
+      () => observed.json.find(message => message.type === 'RemoteFrameSocketReady'),
+      `${label} frame socket ready`
+    );
+    const subscribeJsonIndex = observed.json.length;
+    socket.send(JSON.stringify({
+      type: 'subscribe',
+      deviceIds: [deviceId],
+      autoStartLive: true,
+      allowReadOnlyControlBorrow: true,
+      streamPurpose: 'wall',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      fps: 5,
+      maxWidth: 960,
+      maxHeight: 540,
+      quality: 55,
+      monitorIndex: 0
+    }));
+    return { socket, observed, subscribeJsonIndex };
+  };
+
+  const waitForBorrowStart = (observed, commandId, fromIndex, label) => waitForBorrowLifecycle(
+    () => observed.json.slice(fromIndex).find(message => (
+      message.type === 'RemoteFrameLiveAutoStart'
+      && message.started?.some(item => (
+        item.deviceId === deviceId
+        && item.commandId === commandId
+        && item.streamPurpose === 'control'
+        && item.readOnlyControlBorrow === true
+        && item.presentationPurpose === 'wall'
+      ))
+    )),
+    label
+  );
+
+  const waitForExactReady = (observed, binding, fromIndex, label) => waitForBorrowLifecycle(
+    () => observed.json.slice(fromIndex).find(message => (
+      message.type === 'RemoteFrameStreamReady'
+      && message.deviceId === deviceId
+      && message.sessionId === binding.sessionId
+      && message.streamId === binding.streamId
+      && message.commandId === binding.commandId
+      && message.captureGeneration === binding.captureGeneration
+      && message.streamPurpose === 'control'
+      && message.monitorIndex === 0
+      && message.readOnlyControlBorrow === true
+      && message.presentationPurpose === 'wall'
+    )),
+    label
+  );
+
+  try {
+    hubProcess = spawn(process.execPath, [hubServerPath], {
+      cwd: rootDir,
+      env: {
+        ...process.env,
+        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(remotePort),
+        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'
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true
+    });
+    hubOutput = collectBorrowLifecycleProcessOutput(hubProcess);
+    await waitForBorrowLifecycle(async () => {
+      if (hubProcess.exitCode !== null) {
+        throw new Error(`isolated Hub exited ${hubProcess.exitCode}: ${hubOutput.join('\n')}`);
+      }
+      const response = await fetch(`${baseUrl}/api/health`, { cache: 'no-store' });
+      return response.ok;
+    }, 'isolated Hub health', 10_000, 50);
+
+    agentSocket = net.createConnection({ host: '127.0.0.1', port: remotePort });
+    await once(agentSocket, 'connect');
+    let incoming = '';
+    agentSocket.on('data', chunk => {
+      incoming += chunk.toString('utf8');
+      let newlineIndex = incoming.indexOf('\n');
+      while (newlineIndex >= 0) {
+        const line = incoming.slice(0, newlineIndex).trim();
+        incoming = incoming.slice(newlineIndex + 1);
+        newlineIndex = incoming.indexOf('\n');
+        if (!line) continue;
+        const message = JSON.parse(line);
+        const record = { message, at: Date.now() };
+        agentMessages.push(record);
+        if (message.type === 'command' && message.command === 'stream.stop') {
+          setTimeout(() => {
+            if (agentSocket?.destroyed) return;
+            stopAcknowledgedAtByCommandId.set(message.commandId, Date.now());
+            sendAgent({
+              type: 'command.result',
+              commandId: message.commandId,
+              result: {
+                stream: true,
+                stopped: true,
+                streamId: String(message.payload?.streamId || '')
+              }
+            });
+          }, 5);
+        }
+      }
+    });
+    sendAgent({
+      type: 'hello',
+      pairToken,
+      deviceId,
+      deviceName: 'Control borrow browser fixture',
+      hostname: 'control-borrow-browser-fixture',
+      platform: 'darwin',
+      arch: 'arm64',
+      protocol: 'mindexec.remote.agent',
+      protocolVersion: 2,
+      capabilities: {
+        liveStream: true,
+        liveCaptureConcurrency: 'exclusive',
+        frameProtocol: {},
+        frameModes: []
+      }
+    });
+    await waitForBorrowLifecycle(
+      () => agentMessages.find(record => record.message?.type === 'welcome'),
+      'fake macOS Agent welcome'
+    );
+    await waitForBorrowLifecycle(async () => {
+      const response = await fetch(`${baseUrl}/api/remote/devices`, { cache: 'no-store' });
+      const payload = await response.json();
+      return payload.devices?.find(device => device.deviceId === deviceId && device.connected);
+    }, 'fake macOS Agent registration');
+
+    const controlOptions = {
+      streamPurpose: 'control',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      fps: 30,
+      maxWidth: 1920,
+      maxHeight: 1080,
+      quality: 72,
+      monitorIndex: 0
+    };
+    const initialControl = await postJson(
+      `/api/remote/devices/${encodeURIComponent(deviceId)}/live/start`,
+      controlOptions
+    );
+    assert.equal(initialControl.ok, true);
+    const initialStartCommand = await waitForAgentCommand(
+      message => message.command === 'stream.start' && message.commandId === initialControl.commandId,
+      'initial Control start command'
+    );
+    assert.equal(initialStartCommand.message.payload.streamPurpose, 'control');
+    sendOpen(initialControl);
+    sendControlFrame(initialControl, 1, true);
+    await waitForBorrowLifecycle(async () => {
+      const response = await fetch(`${baseUrl}/api/remote/devices`, { cache: 'no-store' });
+      const payload = await response.json();
+      const device = payload.devices?.find(item => item.deviceId === deviceId);
+      return device?.activeLiveStream?.commandId === initialControl.commandId
+        && device.activeLiveStream.readyFrameReceived === true;
+    }, 'initial exact Control readiness');
+
+    const firstBorrower = await connectBorrower('first borrower');
+    const firstBorrowStart = await waitForBorrowStart(
+      firstBorrower.observed,
+      initialControl.commandId,
+      firstBorrower.subscribeJsonIndex,
+      'first read-only Control binding'
+    );
+    const firstBorrowBinding = firstBorrowStart.started.find(item => item.commandId === initialControl.commandId);
+    assert.equal(firstBorrowBinding.ready, false, 'A new borrower must wait for its own exact key frame.');
+    assert.equal(firstBorrowBinding.captureGeneration, initialControl.captureGeneration);
+    assert.equal(firstBorrowBinding.effectiveProfile?.fps, 30);
+    const firstReadyIndex = firstBorrower.observed.json.length;
+    const firstFrameIndex = firstBorrower.observed.frames.length;
+    sendControlFrame(initialControl, 2, false);
+    await new Promise(resolveWait => setTimeout(resolveWait, 60));
+    assert.equal(
+      firstBorrower.observed.json.slice(firstReadyIndex).some(message => message.type === 'RemoteFrameStreamReady'),
+      false,
+      'A dependent delta must not declare a new borrower ready.'
+    );
+    assert.equal(
+      firstBorrower.observed.frames.length,
+      firstFrameIndex,
+      'A dependent delta must not cross the new borrower frame lane before a key frame.'
+    );
+    sendControlFrame(initialControl, 3, true);
+    await waitForExactReady(
+      firstBorrower.observed,
+      initialControl,
+      firstReadyIndex,
+      'first borrower exact Control key readiness'
+    );
+    const firstFrame = await waitForBorrowLifecycle(
+      () => firstBorrower.observed.frames.slice(firstFrameIndex).find(frame => (
+        frame.commandId === initialControl.commandId
+        && frame.captureGeneration === initialControl.captureGeneration
+        && frame.frameSeq === 3
+      )),
+      'first borrower exact Control key packet'
+    );
+    assert.equal(firstFrame.streamPurpose, 'control');
+    assert.equal(firstFrame.monitorIndex, 0);
+
+    const firstStopCommandIndex = agentMessages.length;
+    const stopInitialPromise = postJson(
+      `/api/remote/devices/${encodeURIComponent(deviceId)}/live/stop`,
+      {
+        streamId: initialControl.streamId,
+        streamPurpose: 'control',
+        reason: 'replace-control-generation'
+      }
+    );
+    const firstStopCommand = await waitForAgentCommand(
+      message => message.command === 'stream.stop' && message.payload?.streamId === initialControl.streamId,
+      'initial Control confirmed stop',
+      firstStopCommandIndex
+    );
+    const initialStop = await stopInitialPromise;
+    assert.equal(initialStop.captureStopConfirmed, true);
+    assert.ok(stopAcknowledgedAtByCommandId.has(firstStopCommand.message.commandId));
+
+    const replacementControl = await postJson(
+      `/api/remote/devices/${encodeURIComponent(deviceId)}/live/start`,
+      controlOptions
+    );
+    assert.equal(replacementControl.ok, true);
+    assert.ok(replacementControl.captureGeneration > initialControl.captureGeneration);
+    const replacementStartCommand = await waitForAgentCommand(
+      message => message.command === 'stream.start' && message.commandId === replacementControl.commandId,
+      'replacement Control start command',
+      firstStopCommandIndex
+    );
+    assert.equal(replacementStartCommand.message.payload.streamPurpose, 'control');
+    const replacementJsonIndex = firstBorrower.observed.json.length;
+    await new Promise(resolveWait => setTimeout(
+      resolveWait,
+      READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS + 40
+    ));
+    assert.equal(
+      agentMessages.slice(firstStopCommandIndex).some(record => (
+        record.message?.type === 'command'
+        && record.message.command === 'stream.start'
+        && record.message.payload?.streamPurpose === 'wall'
+      )),
+      false,
+      'The stopped-Control grace must not let Wall steal a prompt replacement Control claim.'
+    );
+    assert.equal(
+      firstBorrower.observed.json.slice(replacementJsonIndex).some(message => (
+        message.type === 'RemoteFrameLiveAutoStart'
+        && message.started?.some(item => item.commandId === replacementControl.commandId)
+      )),
+      false,
+      'A borrower must not rebind to a replacement Control before that generation is ready.'
+    );
+
+    const replacementFrameIndex = firstBorrower.observed.frames.length;
+    sendOpen(replacementControl);
+    sendControlFrame(replacementControl, 1, true);
+    const replacementBorrowStart = await waitForBorrowStart(
+      firstBorrower.observed,
+      replacementControl.commandId,
+      replacementJsonIndex,
+      'replacement Control borrower reconciliation'
+    );
+    assert.equal(replacementBorrowStart.reason, 'control-borrow-reconcile');
+    assert.equal(
+      replacementBorrowStart.started.find(item => item.commandId === replacementControl.commandId)?.ready,
+      false
+    );
+    assert.equal(
+      firstBorrower.observed.frames.slice(replacementFrameIndex).some(frame => (
+        frame.commandId === replacementControl.commandId
+      )),
+      false,
+      'The key that precedes replacement binding installation must not leak into the new lane.'
+    );
+    const replacementReadyIndex = firstBorrower.observed.json.length;
+    sendControlFrame(replacementControl, 2, false);
+    await new Promise(resolveWait => setTimeout(resolveWait, 60));
+    assert.equal(firstBorrower.observed.frames.length, replacementFrameIndex);
+    sendControlFrame(replacementControl, 3, true);
+    await waitForExactReady(
+      firstBorrower.observed,
+      replacementControl,
+      replacementReadyIndex,
+      'replacement borrower exact Control key readiness'
+    );
+    await waitForBorrowLifecycle(
+      () => firstBorrower.observed.frames.slice(replacementFrameIndex).find(frame => (
+        frame.commandId === replacementControl.commandId
+        && frame.captureGeneration === replacementControl.captureGeneration
+        && frame.frameSeq === 3
+      )),
+      'replacement borrower exact Control key packet'
+    );
+    assert.equal(
+      firstBorrower.observed.frames.slice(replacementFrameIndex).some(frame => (
+        frame.commandId === initialControl.commandId
+        || frame.captureGeneration === initialControl.captureGeneration
+      )),
+      false,
+      'A replacement binding must reject every stale Control generation.'
+    );
+
+    const stopCountBeforeBorrowerClose = agentMessages.filter(record => (
+      record.message?.type === 'command' && record.message.command === 'stream.stop'
+    )).length;
+    const firstBorrowerClosed = once(firstBorrower.socket, 'close');
+    firstBorrower.socket.close(1000, 'borrower-release-regression');
+    await firstBorrowerClosed;
+    await new Promise(resolveWait => setTimeout(resolveWait, 90));
+    assert.equal(
+      agentMessages.filter(record => (
+        record.message?.type === 'command' && record.message.command === 'stream.stop'
+      )).length,
+      stopCountBeforeBorrowerClose,
+      'Closing a read-only borrower must never stop the native Control owner.'
+    );
+
+    const fallbackBorrower = await connectBorrower('fallback borrower');
+    await waitForBorrowStart(
+      fallbackBorrower.observed,
+      replacementControl.commandId,
+      fallbackBorrower.subscribeJsonIndex,
+      'fallback borrower Control binding'
+    );
+    const fallbackReadyIndex = fallbackBorrower.observed.json.length;
+    sendControlFrame(replacementControl, 4, true);
+    await waitForExactReady(
+      fallbackBorrower.observed,
+      replacementControl,
+      fallbackReadyIndex,
+      'fallback borrower exact Control key readiness'
+    );
+
+    const finalStopCommandIndex = agentMessages.length;
+    const stopReplacementPromise = postJson(
+      `/api/remote/devices/${encodeURIComponent(deviceId)}/live/stop`,
+      {
+        streamId: replacementControl.streamId,
+        streamPurpose: 'control',
+        reason: 'confirmed-control-stop-wall-fallback'
+      }
+    );
+    const finalStopCommand = await waitForAgentCommand(
+      message => message.command === 'stream.stop' && message.payload?.streamId === replacementControl.streamId,
+      'replacement Control confirmed stop',
+      finalStopCommandIndex
+    );
+    const replacementStop = await stopReplacementPromise;
+    assert.equal(replacementStop.captureStopConfirmed, true);
+    const finalStopAcknowledgedAt = stopAcknowledgedAtByCommandId.get(finalStopCommand.message.commandId);
+    assert.ok(finalStopAcknowledgedAt > 0);
+    assert.equal(
+      agentMessages.slice(finalStopCommandIndex).some(record => (
+        record.message?.type === 'command'
+        && record.message.command === 'stream.start'
+        && record.message.payload?.streamPurpose === 'wall'
+      )),
+      false,
+      'Confirmed Control stop must not reacquire Wall synchronously.'
+    );
+
+    const fallbackWallCommand = await waitForAgentCommand(
+      message => message.command === 'stream.start' && message.payload?.streamPurpose === 'wall',
+      'deferred ordinary Wall fallback',
+      finalStopCommandIndex
+    );
+    assert.ok(
+      fallbackWallCommand.at - finalStopAcknowledgedAt
+        >= READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS - 40,
+      `Wall fallback started before the ${READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS}ms Control replacement grace.`
+    );
+    const fallbackWallStart = await waitForBorrowLifecycle(
+      () => fallbackBorrower.observed.json.find(message => (
+        message.type === 'RemoteFrameLiveAutoStart'
+        && message.reason === 'control-borrow-reconcile'
+        && message.started?.some(item => (
+          item.deviceId === deviceId
+          && item.commandId === fallbackWallCommand.message.commandId
+          && item.streamPurpose === 'wall'
+          && item.readOnlyControlBorrow !== true
+        ))
+      )),
+      'ordinary Wall browser binding after confirmed Control stop'
+    );
+    assert.equal(fallbackWallStart.started[0].presentationPurpose, '');
+  } catch (error) {
+    error.message += hubOutput.length > 0
+      ? `\nIsolated Hub output:\n${hubOutput.join('\n')}`
+      : '';
+    throw error;
+  } finally {
+    for (const socket of browserSockets) {
+      try { socket.terminate(); } catch { /* already closed */ }
+    }
+    agentSocket?.destroy();
+    await terminateBorrowLifecycleProcess(hubProcess);
+  }
+});