@livedesk/hub 0.1.59 → 0.1.61

package/src/server.js

@@ -30,7 +30,10 @@ import {
   observeRemoteAudioStopConfirmation,
   remoteAudioSubscriberOwns
 } from './remote-audio-subscription-contract.mjs';
-import { isReusedLiveStreamFrameReady } from './live-stream-monitor-contract.js';
+import {
+  createReadOnlyControlPresentationReconcileCoordinator,
+  isReusedLiveStreamFrameReady
+} from './live-stream-monitor-contract.js';
 import { createLiveCaptureTransitionRetryCoordinator } from './live-capture-transition-retry.mjs';
 import { buildMode4AtlasSessionKey, Mode4AtlasPool, planMode4AtlasInputTransitions } from './mode4-atlas-pool.js';
 import { resolveMode4AtlasTileSize } from './mode4-atlas-sizing.js';
@@ -309,6 +312,52 @@ function broadcastRemoteInputRouteState(deviceId, reason = '') {
   }
 }
 
+function reconcileReadOnlyControlPresentationSubscribers(deviceId) {
+  const normalizedDeviceId = String(deviceId || '').trim();
+  if (!normalizedDeviceId) return;
+  const clients = new Set([
+    ...(frameClientsByDeviceId.get(normalizedDeviceId) || []),
+    ...frameWildcardClients
+  ]);
+  for (const ws of clients) {
+    const liveOptions = ws.liveDeskLiveOptions;
+    if (ws.readyState !== 1
+      || ws.liveDeskAutoStart !== true
+      || !(ws.liveDeskDeviceIds instanceof Set)
+      || !ws.liveDeskDeviceIds.has(normalizedDeviceId)
+      || liveOptions?.allowReadOnlyControlBorrow !== true
+      || String(liveOptions?.streamPurpose || '').trim().toLowerCase() !== 'wall') {
+      continue;
+    }
+    startFrameSubscriptionLive(ws, 'control-borrow-reconcile', normalizedDeviceId, {
+      ...liveOptions,
+      forceRestart: false,
+      reuseExisting: true
+    });
+  }
+}
+
+const readOnlyControlPresentationReconcileCoordinator =
+  createReadOnlyControlPresentationReconcileCoordinator({
+    onReconcile: reconcileReadOnlyControlPresentationSubscribers
+  });
+
+function readRemoteLiveStreamEventPurpose(event) {
+  const explicitPurpose = String(event?.streamPurpose || '').trim().toLowerCase();
+  if (explicitPurpose) return explicitPurpose;
+  const commandId = String(event?.commandId || '').trim();
+  const activeStream = event?.device?.activeLiveStream;
+  if (!commandId || !activeStream) return '';
+  const pendingDescriptor = activeStream.pendingDescriptor;
+  if (String(pendingDescriptor?.commandId || '').trim() === commandId) {
+    return String(pendingDescriptor?.streamPurpose || '').trim().toLowerCase();
+  }
+  if (String(activeStream.commandId || '').trim() === commandId) {
+    return String(activeStream.streamPurpose || '').trim().toLowerCase();
+  }
+  return '';
+}
+
 function handleRemoteHubEvent(type, event) {
   liveDeskUpdateManager?.handleRemoteEvent(type, event);
   hubTransferJobs?.handleRemoteEvent(type, event);
@@ -363,9 +412,32 @@ function handleRemoteHubEvent(type, event) {
     broadcastRemoteInputRouteState(deviceId, event?.reason || type);
     return;
   }
+  if (type === 'RemoteLiveStreamStarted'
+    || type === 'RemoteLiveStreamOpened'
+    || type === 'RemoteLiveStreamReady'
+    || type === 'RemoteLiveStreamStopped') {
+    const liveStreamEventDeviceId = String(event?.deviceId || event?.device?.deviceId || '').trim();
+    const liveStreamEventPurpose = readRemoteLiveStreamEventPurpose(event);
+    if ((type === 'RemoteLiveStreamStarted' || type === 'RemoteLiveStreamOpened')
+      && liveStreamEventPurpose === 'control') {
+      readOnlyControlPresentationReconcileCoordinator
+        .cancelForControlTransition(liveStreamEventDeviceId);
+    } else if (type === 'RemoteLiveStreamReady' && liveStreamEventPurpose === 'control') {
+      readOnlyControlPresentationReconcileCoordinator
+        .reconcileReadyControl(liveStreamEventDeviceId);
+    } else if (type === 'RemoteLiveStreamStopped'
+      && liveStreamEventPurpose === 'control'
+      && event?.captureStopConfirmed === true) {
+      readOnlyControlPresentationReconcileCoordinator
+        .scheduleAfterConfirmedStop(liveStreamEventDeviceId);
+    }
+  }
   if (type === 'RemoteDeviceConnected' || type === 'RemoteDeviceDisconnected') {
     connectedDeviceCount = Number(remoteHub.getStatus({ includeSecrets: false }).connectedDeviceCount || 0);
     const deviceId = String(event?.deviceId || event?.device?.deviceId || '').trim();
+    if (type === 'RemoteDeviceDisconnected') {
+      readOnlyControlPresentationReconcileCoordinator.cancelForControlTransition(deviceId);
+    }
     broadcastRemoteInputRouteState(deviceId, event?.reason || type);
   }
   if (type !== 'RemoteDeviceConnected') {
@@ -2212,7 +2284,7 @@ function normalizeTransferChunk(body = {}) {
   };
 }
 
-function normalizeLiveOptions(payload = {}) {
+function normalizeLiveOptions(payload = {}) {
   const mode = String(payload.frameMode || payload.mode || 'mode3-h264-hw').trim() || 'mode3-h264-hw';
   const streamPurpose = String(payload.streamPurpose || payload.purpose || 'wall').trim().slice(0, 24) || 'wall';
   const maxFps = streamPurpose === 'control' ? 60 : 30;
@@ -2222,10 +2294,11 @@ function normalizeLiveOptions(payload = {}) {
     maxHeight: clampNumber(payload.maxHeight, 180, 2160, 360),
     quality: clampNumber(payload.quality, 20, 95, 45),
     monitorIndex: normalizeMonitorIndex(payload.monitorIndex ?? payload.screenIndex ?? payload.displayIndex),
-    monitorSelections: normalizeMonitorSelections(payload.monitorSelections),
-    forceRestart: /^(1|true|yes|on)$/i.test(String(payload.forceRestart ?? '')),
-    reuseExisting: /^(1|true|yes|on)$/i.test(String(payload.reuseExisting ?? '')),
-    streamPurpose,
+    monitorSelections: normalizeMonitorSelections(payload.monitorSelections),
+    forceRestart: /^(1|true|yes|on)$/i.test(String(payload.forceRestart ?? '')),
+    reuseExisting: /^(1|true|yes|on)$/i.test(String(payload.reuseExisting ?? '')),
+    allowReadOnlyControlBorrow: /^(1|true|yes|on)$/i.test(String(payload.allowReadOnlyControlBorrow ?? '')),
+    streamPurpose,
     mode,
     frameMode: mode
   };
@@ -2326,15 +2399,23 @@ function unregisterFrameClient(ws) {
   retireFrameClientSendLane(ws);
 }
 
-function hasOtherFrameStreamOwner(ws, deviceId, streamId, streamPurpose = '') {
+function hasOtherFrameStreamOwner(ws, deviceId, streamId, streamPurpose = '') {
   if (!streamId) {
     return false;
   }
-  for (const candidate of frameClients) {
-    if (candidate === ws || candidate.readyState !== candidate.OPEN) {
-      continue;
-    }
-    if (candidate.liveDeskStreamIdsByDeviceId instanceof Map
+  for (const candidate of frameClients) {
+    if (candidate === ws || candidate.readyState !== candidate.OPEN) {
+      continue;
+    }
+    const expectedBinding = candidate.liveDeskExpectedStreamBindingsByDeviceId instanceof Map
+      ? candidate.liveDeskExpectedStreamBindingsByDeviceId.get(deviceId)
+      : null;
+    if (expectedBinding?.readOnlyControlBorrow === true) {
+      // A presentation observer can share immutable packets, but it must never
+      // keep the native Control owner alive after the real controller leaves.
+      continue;
+    }
+    if (candidate.liveDeskStreamIdsByDeviceId instanceof Map
       && candidate.liveDeskStreamIdsByDeviceId.get(deviceId) === streamId) {
       return true;
     }
@@ -2425,17 +2506,28 @@ function scheduleFrameStreamStop(deviceId, streamId, streamPurpose) {
   pendingFrameStreamStops.set(key, { timer });
 }
 
-function stopFrameClientStreams(ws) {
+function stopFrameClientStreams(ws) {
   const streams = ws.liveDeskStreamIdsByDeviceId instanceof Map
     ? ws.liveDeskStreamIdsByDeviceId
     : null;
   if (!streams) {
     return;
   }
-  const streamPurpose = String(ws.liveDeskLiveOptions?.streamPurpose || 'wall');
-  for (const [deviceId, streamId] of streams.entries()) {
-    if (!streamId || hasOtherFrameStreamOwner(ws, deviceId, streamId, streamPurpose)) {
-      continue;
+  const requestedStreamPurpose = String(ws.liveDeskLiveOptions?.streamPurpose || 'wall');
+  for (const [deviceId, streamId] of streams.entries()) {
+    const expectedBinding = ws.liveDeskExpectedStreamBindingsByDeviceId instanceof Map
+      ? ws.liveDeskExpectedStreamBindingsByDeviceId.get(deviceId)
+      : null;
+    if (expectedBinding?.readOnlyControlBorrow === true) {
+      // Borrowers own only browser presentation resources. The real Control
+      // subscriber remains the sole native stop owner.
+      continue;
+    }
+    const streamPurpose = expectedBinding?.streamId === streamId
+      ? String(expectedBinding.streamPurpose || requestedStreamPurpose)
+      : requestedStreamPurpose;
+    if (!streamId || hasOtherFrameStreamOwner(ws, deviceId, streamId, streamPurpose)) {
+      continue;
     }
     scheduleFrameStreamStop(deviceId, streamId, streamPurpose);
   }
@@ -3468,21 +3560,21 @@ function startFrameSubscriptionLive(
     const monitorIndex = Object.prototype.hasOwnProperty.call(liveOptions.monitorSelections || {}, deviceId)
       ? liveOptions.monitorSelections[deviceId]
       : liveOptions.monitorIndex;
-    const result = remoteHub.startLiveStream(deviceId, {
-      ...liveOptions,
-      monitorIndex,
-      reuseExisting: liveOptions.forceRestart !== true
-        && (liveOptions.reuseExisting === true || reason === 'subscribe' || reason === 'watchdog'),
-      // Wall capture is one shared native encoder per device. Two open browser
-      // views may ask for different soft profiles (for example mobile 5 fps at
-      // 1080p and desktop 20 fps at 540p). Once a healthy shared owner exists,
-      // those preferences must bind to that owner instead of replacing it back
-      // and forth every time either view refreshes its subscription.
-      reuseSharedExisting: liveOptions.forceRestart !== true
-        && String(liveOptions.streamPurpose || '').trim().toLowerCase() === 'wall'
-        && hasOtherFrameStreamDemand(ws, deviceId, 'wall'),
-      silentReuse: reason === 'watchdog' && liveOptions.forceRestart !== true
-    });
+    const result = remoteHub.startLiveStream(deviceId, {
+      ...liveOptions,
+      monitorIndex,
+      reuseExisting: liveOptions.forceRestart !== true
+        && (liveOptions.reuseExisting === true || reason === 'subscribe' || reason === 'watchdog'),
+      // Wall capture is one shared native encoder per device. Two open browser
+      // views may ask for different soft profiles (for example mobile 5 fps at
+      // 1080p and desktop 20 fps at 540p). Once a healthy shared owner exists,
+      // those preferences must bind to that owner instead of replacing it back
+      // and forth every time either view refreshes its subscription.
+      reuseSharedExisting: liveOptions.forceRestart !== true
+        && String(liveOptions.streamPurpose || '').trim().toLowerCase() === 'wall'
+        && hasOtherFrameStreamDemand(ws, deviceId, 'wall'),
+      silentReuse: reason === 'watchdog' && liveOptions.forceRestart !== true
+    });
     if (result?.ok) {
       if (result.sharedProfileReused === true) {
         ws.liveDeskSharedProfileReuseCount = Math.max(
@@ -3491,18 +3583,25 @@ function startFrameSubscriptionLive(
         ) + 1;
       }
       frameCaptureTransitionRetries.complete(ws, deviceId, intentGeneration, 'capture-started');
-      const expectedBinding = {
+      const expectedBinding = {
         deviceId,
         sessionId: String(result.sessionId || device.sessionId || ''),
         streamId: String(result.streamId || ''),
         streamPurpose: String(result.streamPurpose || liveOptions.streamPurpose || 'wall'),
         commandId: String(result.commandId || ''),
-        captureGeneration: Number(result.captureGeneration || 0),
-        monitorIndex: Number(result.monitorIndex || 0),
-        readySent: false
+        captureGeneration: Number(result.captureGeneration || 0),
+        monitorIndex: Number(result.monitorIndex || 0),
+        readOnlyControlBorrow: result.readOnlyControlBorrow === true,
+        presentationPurpose: result.presentationPurpose === 'wall' ? 'wall' : '',
+        effectiveProfile: result.effectiveProfile || null,
+        readySent: false
       };
       const activeStream = device?.activeLiveStream;
-      const reusedFrameReady = isReusedLiveStreamFrameReady(result, activeStream, expectedBinding);
+      // A new read-only browser presentation has no decoder history from the
+      // already-running Control stream. It must enter through the next exact
+      // key frame even when the native owner itself is already ready.
+      const reusedFrameReady = expectedBinding.readOnlyControlBorrow !== true
+        && isReusedLiveStreamFrameReady(result, activeStream, expectedBinding);
       expectedBinding.readySent = reusedFrameReady;
       ws.liveDeskStreamIdsByDeviceId.set(deviceId, result.streamId);
       const installedBindingIdentity = replaceExpectedFrameBindingForClient(
@@ -3514,19 +3613,24 @@ function startFrameSubscriptionLive(
         skipped.push({ deviceId, reason: 'invalid-live-stream-binding' });
         continue;
       }
-      cancelPendingFrameStreamStop(deviceId, result.streamId, String(liveOptions.streamPurpose || 'wall'));
-      started.push({
+      if (expectedBinding.readOnlyControlBorrow !== true) {
+        cancelPendingFrameStreamStop(deviceId, result.streamId, expectedBinding.streamPurpose);
+      }
+      started.push({
         deviceId: expectedBinding.deviceId,
         sessionId: expectedBinding.sessionId,
         streamId: expectedBinding.streamId,
         streamPurpose: expectedBinding.streamPurpose,
         commandId: expectedBinding.commandId,
         captureGeneration: expectedBinding.captureGeneration,
-        monitorIndex: expectedBinding.monitorIndex,
-        ready: reusedFrameReady,
-        fps: result.fps,
-        reused: result.reused === true
-      });
+        monitorIndex: expectedBinding.monitorIndex,
+        readOnlyControlBorrow: expectedBinding.readOnlyControlBorrow,
+        presentationPurpose: expectedBinding.presentationPurpose,
+        effectiveProfile: expectedBinding.effectiveProfile,
+        ready: reusedFrameReady,
+        fps: result.fps,
+        reused: result.reused === true
+      });
     } else {
       ws.liveDeskStreamIdsByDeviceId.delete(deviceId);
       replaceExpectedFrameBindingForClient(ws, deviceId, null);
@@ -3598,9 +3702,10 @@ function startFrameSubscriptionLive(
       }
     }
   }
-  if (reason === 'watchdog' && !started.some(item => item.reused !== true)) {
-    return;
-  }
+  if ((reason === 'watchdog' && !started.some(item => item.reused !== true))
+    || (reason === 'control-borrow-reconcile' && started.length === 0)) {
+    return;
+  }
   sendJson(ws, {
     type: 'RemoteFrameLiveAutoStart',
     timestamp: new Date().toISOString(),
@@ -3877,21 +3982,30 @@ function broadcastRemoteBinaryFrame(frameEvent) {
       continue;
     }
     const requiresReadyKeyFrame = String(expectedBinding.streamPurpose || '').toLowerCase() === 'control' && isH264;
-    if (!expectedBinding.readySent && (!requiresReadyKeyFrame || isKeyFrame)) {
-      expectedBinding.readySent = sendJson(client, {
-        type: 'RemoteFrameStreamReady',
-        deviceId,
-        sessionId: expectedBinding.sessionId,
-        streamId: expectedBinding.streamId,
-        streamPurpose: expectedBinding.streamPurpose,
-        commandId: expectedBinding.commandId,
-        captureGeneration: expectedBinding.captureGeneration,
-        monitorIndex: expectedBinding.monitorIndex
-      });
-      if (!expectedBinding.readySent) {
-        continue;
-      }
-    }
+    if (!expectedBinding.readySent) {
+      // A fresh H.264 decoder cannot consume dependent Control deltas. Keep
+      // the browser lane closed until the first exact key frame; otherwise a
+      // newly attached PWA can remain on "Preparing video" until a later IDR.
+      if (requiresReadyKeyFrame && !isKeyFrame) {
+        continue;
+      }
+      expectedBinding.readySent = sendJson(client, {
+        type: 'RemoteFrameStreamReady',
+        deviceId,
+        sessionId: expectedBinding.sessionId,
+        streamId: expectedBinding.streamId,
+        streamPurpose: expectedBinding.streamPurpose,
+        commandId: expectedBinding.commandId,
+        captureGeneration: expectedBinding.captureGeneration,
+        monitorIndex: expectedBinding.monitorIndex,
+        readOnlyControlBorrow: expectedBinding.readOnlyControlBorrow === true,
+        presentationPurpose: expectedBinding.presentationPurpose || '',
+        effectiveProfile: expectedBinding.effectiveProfile || null
+      });
+      if (!expectedBinding.readySent) {
+        continue;
+      }
+    }
     const lane = ensureFrameClientSendLane(client);
     if (client.liveDeskFrameBackpressured
       && lane.backpressuredDeviceIds.has(deviceId)
@@ -4728,9 +4842,9 @@ app.post('/api/settings/agent/run', async (req, res) => {
     return;
   }
   try {
-    if (!(await synchronizeAgentEnablement())) {
-      throw new AgentRuntimeError('agent-disabled', 'Enable Codex Agent in Settings before running commands.', { status: 409 });
-    }
+    if (!(await synchronizeAgentEnablement())) {
+      throw new AgentRuntimeError('agent-disabled', 'Codex Agent was explicitly turned off in Settings.', { status: 409 });
+    }
     const instruction = typeof req.body?.instruction === 'string' ? req.body.instruction.slice(0, 4000) : '';
     const deviceIds = normalizeDeviceIds(req.body?.deviceIds).slice(0, 500);
     const connectedDeviceIds = new Set(connectedAgentDeviceIds());
@@ -6916,9 +7030,10 @@ function shutdownHub(signal) {
   hubShutdownPromise = (async () => {
     const startedAt = Date.now();
     console.log(`[VuvoDesk Hub] Shutdown started signal=${signal} grace=${hubShutdownGraceMs}ms timeout=${hubShutdownTimeoutMs}ms.`);
-    if (roleWatchTimer) clearInterval(roleWatchTimer);
-    clearInterval(browserWebSocketHeartbeatTimer);
-    runSynchronousShutdownStep('update manager close', () => liveDeskUpdateManager?.close());
+    if (roleWatchTimer) clearInterval(roleWatchTimer);
+    clearInterval(browserWebSocketHeartbeatTimer);
+    runSynchronousShutdownStep('control presentation reconcile close', () => readOnlyControlPresentationReconcileCoordinator.close());
+    runSynchronousShutdownStep('update manager close', () => liveDeskUpdateManager?.close());
     runSynchronousShutdownStep('mobile console direct close', () => hubConsoleDirect?.close());
     atlasClients.clear();
     runSynchronousShutdownStep('shared folder close', () => hubSharedFolders.close());

package/src/settings/settings-schema.js

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 
-export const SETTINGS_SCHEMA_VERSION = 1;
+export const SETTINGS_SCHEMA_VERSION = 2;
 
 export const DEFAULT_LIVEDESK_SETTINGS = Object.freeze({
   settingsSchemaVersion: SETTINGS_SCHEMA_VERSION,
@@ -80,9 +80,9 @@ export const DEFAULT_LIVEDESK_SETTINGS = Object.freeze({
     includeRemoteCursor: true,
     captureSaveLocation: 'VuvoDesk Captures',
     captureAutoDelete: 'never'
-  },
-  agent: {
-    enabled: false,
+  },
+  agent: {
+    enabled: true,
     defaultPermissionMode: 'safe-auto',
     askBeforeDestructive: true,
     allowProcessManagement: true,
@@ -156,8 +156,27 @@ function normalizeSection(source, defaults, rules = {}) {
   return result;
 }
 
-const bools = keys => Object.fromEntries(keys.map(key => [key, { type: 'boolean' }]));
-const numbers = (entries) => Object.fromEntries(entries.map(([key, min, max]) => [key, { type: 'number', min, max }]));
+const bools = keys => Object.fromEntries(keys.map(key => [key, { type: 'boolean' }]));
+const numbers = (entries) => Object.fromEntries(entries.map(([key, min, max]) => [key, { type: 'number', min, max }]));
+
+export function migrateLiveDeskSettings(value = {}) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const storedVersion = Math.max(0, Math.trunc(Number(source.settingsSchemaVersion) || 0));
+  if (storedVersion >= SETTINGS_SCHEMA_VERSION) return source;
+  const agent = source.agent && typeof source.agent === 'object' && !Array.isArray(source.agent)
+    ? source.agent
+    : {};
+  return {
+    ...source,
+    settingsSchemaVersion: SETTINGS_SCHEMA_VERSION,
+    agent: {
+      ...agent,
+      // Schema 1 shipped disabled-by-default. Schema 2 treats that old value
+      // as the retired default; a later explicit opt-out is stored as schema 2.
+      enabled: true
+    }
+  };
+}
 
 const RULES = {
   connection: {

package/src/settings/settings-store.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { DEFAULT_LIVEDESK_SETTINGS, defaultSettingsPath, normalizeLiveDeskSettings, publicSettings } from './settings-schema.js';
+import { DEFAULT_LIVEDESK_SETTINGS, defaultSettingsPath, migrateLiveDeskSettings, normalizeLiveDeskSettings, publicSettings } from './settings-schema.js';
 
 export class SettingsConflictError extends Error {
   constructor(settings) {
@@ -27,13 +27,14 @@ export class LiveDeskSettingsStore {
 
   async getRecord() {
     if (this.record) return structuredClone(this.record);
-    try {
-      const raw = JSON.parse(await readFile(this.filePath, 'utf8'));
-      this.record = {
-        revision: Math.max(0, Number(raw?.revision) || 0),
-        updatedAt: String(raw?.updatedAt || ''),
-        settings: normalizeLiveDeskSettings(raw?.settings || raw)
-      };
+    try {
+      const raw = JSON.parse(await readFile(this.filePath, 'utf8'));
+      const migratedSettings = migrateLiveDeskSettings(raw?.settings || raw);
+      this.record = {
+        revision: Math.max(0, Number(raw?.revision) || 0),
+        updatedAt: String(raw?.updatedAt || ''),
+        settings: normalizeLiveDeskSettings(migratedSettings)
+      };
     } catch {
       this.record = { revision: 0, updatedAt: '', settings: normalizeLiveDeskSettings(DEFAULT_LIVEDESK_SETTINGS) };
     }

package/src/wall-source-restart-contract.test.mjs

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+
+const [remoteHubSource, serverSource] = await Promise.all([
+  readFile(new URL('./remote-hub.js', import.meta.url), 'utf8'),
+  readFile(new URL('./server.js', import.meta.url), 'utf8')
+]);
+
+function sourceSlice(source, startMarker, endMarker) {
+  const start = source.indexOf(startMarker);
+  const end = source.indexOf(endMarker, start + startMarker.length);
+  assert.ok(start >= 0 && end > start, `missing source slice: ${startMarker}`);
+  return source.slice(start, end);
+}
+
+test('a recovered frame subscription asks the Hub to reuse its healthy source', () => {
+  const subscriptionStart = sourceSlice(
+    serverSource,
+    'function startFrameSubscriptionLive(',
+    'function restartFrameSubscriptionLive('
+  );
+  assert.match(
+    subscriptionStart,
+    /reuseExisting: liveOptions\.forceRestart !== true[\s\S]{0,180}reason === 'subscribe' \|\| reason === 'watchdog'/
+  );
+});
+
+test('the atomic Hub start decision reuses only a matching live source', () => {
+  const liveStart = sourceSlice(
+    remoteHubSource,
+    'function startLiveStream(deviceId, options = {})',
+    'function stopLiveStream('
+  );
+  assert.match(
+    liveStart,
+    /options\.reuseExisting === true[\s\S]{0,160}liveStreamMatchesOptions\(activeLiveStream, normalized\)[\s\S]{0,160}liveStreamIsReusable\(activeLiveStream\)[\s\S]{0,900}reused: true/
+  );
+  assert.match(
+    liveStart,
+    /!liveStreamIsReusable\(activeLiveStream\)[\s\S]{0,900}RemoteLiveStreamStaleRestart[\s\S]{0,900}const captureGeneration = nextCaptureGeneration\(device\)/
+  );
+});
+
+test('Wall lane recovery has no special native-restart wire option', () => {
+  assert.doesNotMatch(serverSource, /restartIfSourceStale|sourceFreshRestartSuppressed/);
+  assert.doesNotMatch(remoteHubSource, /restartIfSourceStale|sourceFreshRestartSuppressed/);
+});

package/src/wall-source-restart-runtime.test.mjs

@@ -0,0 +1,146 @@
+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';
+
+test('a new Wall frame lane reuses a healthy exact capture', async () => {
+  const hub = createRemoteHub({
+    env: {
+      ...process.env,
+      LIVEDESK_REMOTE_HUB: '1',
+      REMOTE_HUB_HOST: '127.0.0.1',
+      REMOTE_HUB_PORT: '0'
+    },
+    pairToken: 'wall-source-reuse-token'
+  });
+  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 buffer = '';
+    socket.on('data', chunk => {
+      buffer += chunk.toString('utf8');
+      let newline = buffer.indexOf('\n');
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) messages.push(JSON.parse(line));
+        newline = buffer.indexOf('\n');
+      }
+    });
+    const waitUntil = async predicate => {
+      const deadline = Date.now() + 2_000;
+      while (Date.now() < deadline) {
+        if (predicate()) return;
+        await new Promise(resolve => setTimeout(resolve, 10));
+      }
+      throw new Error('timed out waiting for Wall source reuse fixture');
+    };
+    const send = message => socket.write(`${JSON.stringify(message)}\n`);
+
+    send({
+      type: 'hello',
+      pairToken: 'wall-source-reuse-token',
+      deviceId: 'wall-source-device',
+      deviceName: 'Wall source reuse fixture',
+      hostname: 'wall-source-reuse',
+      platform: 'darwin',
+      arch: 'arm64',
+      protocol: 'mindexec.remote.agent',
+      protocolVersion: 2,
+      capabilities: { liveStream: true, frameProtocol: {}, frameModes: [] }
+    });
+    await waitUntil(() => messages.some(message => message.type === 'welcome'));
+
+    const streamId = 'wall-wall-source-device';
+    const options = {
+      streamId,
+      streamPurpose: 'wall',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      fps: 30,
+      maxWidth: 960,
+      maxHeight: 540,
+      quality: 68,
+      monitorIndex: 0
+    };
+    const first = hub.startLiveStream('wall-source-device', {
+      ...options,
+      commandId: 'wall-command-1',
+      forceRestart: true,
+      restartToken: 'initial-wall-start'
+    });
+    assert.equal(first.ok, true);
+    await waitUntil(() => messages.some(message => (
+      message.type === 'command'
+      && message.command === 'stream.start'
+      && message.commandId === 'wall-command-1'
+    )));
+
+    send({
+      type: 'stream.open',
+      streamId,
+      commandId: 'wall-command-1',
+      captureGeneration: first.captureGeneration,
+      monitorIndex: 0,
+      streamPurpose: 'wall',
+      mode: 'mode3-h264-hw',
+      frameMode: 'mode3-h264-hw',
+      width: 960,
+      height: 540
+    });
+    send({
+      type: 'stream.frame',
+      streamId,
+      commandId: 'wall-command-1',
+      captureGeneration: first.captureGeneration,
+      monitorIndex: 0,
+      streamPurpose: 'wall',
+      frameSeq: 1,
+      frameMode: 'mode3-h264-hw',
+      mimeType: 'video/h264',
+      isKeyFrame: true,
+      chunkType: 'key',
+      width: 960,
+      height: 540,
+      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('wall-source-device')?.currentGenerationVerified === true);
+
+    const commandCountBeforeReuse = messages.filter(message => message.command === 'stream.start').length;
+    const reused = hub.startLiveStream('wall-source-device', {
+      ...options,
+      reuseExisting: true
+    });
+    assert.equal(reused.ok, true);
+    assert.equal(reused.reused, true);
+    assert.equal(reused.commandId, first.commandId);
+    assert.equal(reused.captureGeneration, first.captureGeneration);
+    await new Promise(resolve => setTimeout(resolve, 20));
+    assert.equal(
+      messages.filter(message => message.command === 'stream.start').length,
+      commandCountBeforeReuse,
+      'a replacement browser lane must not restart a healthy shared capture'
+    );
+
+    const hardRestart = hub.startLiveStream('wall-source-device', {
+      ...options,
+      commandId: 'wall-command-hard-restart',
+      forceRestart: true,
+      restartToken: 'explicit-owner-restart'
+    });
+    assert.equal(hardRestart.ok, true);
+    assert.ok(hardRestart.captureGeneration > first.captureGeneration);
+  } finally {
+    socket?.destroy();
+    await hub.close();
+  }
+});