@livedesk/hub 0.1.7 → 0.1.9

package/src/remote-hub.js

@@ -28,7 +28,13 @@ const LIVE_STREAM_REPLACEMENT_PENDING_MS = 7000;
 const LIVE_STREAM_MIN_FRESH_MS = 3000;
 const LIVE_STREAM_MAX_FRESH_MS = 12000;
 const DEFAULT_REMOTE_INPUT_ACK_TIMEOUT_MS = 5000;
-const REMOTE_PROTOCOL_VERSION = 2;
+const DEFAULT_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS = 8000;
+const REMOTE_POLICY_BYPASS_COMMANDS = new Set([
+    'ping',
+    'stream.stop',
+    'audio.stop'
+]);
+const REMOTE_PROTOCOL_VERSION = 2;
 const REMOTE_AGENT_PROTOCOL = 'mindexec.remote.agent';
 const REMOTE_FRAME_PROTOCOL = 'mindexec.remote.frame.v2';
 const REMOTE_FRAME_PROTOCOL_VERSION = 2;
@@ -154,7 +160,10 @@ const DUPLICATE_DEVICE_LOG_THROTTLE_MS = 60000;
 const DUPLICATE_DEVICE_RETRY_AFTER_MS = 30000;
 const AGENT_BINARY_INGRESS_QUEUE_PACKETS = 8;
 const MODE5_AGENT_BINARY_INGRESS_QUEUE_PACKETS = 2;
-const AGENT_BINARY_INGRESS_DRAIN_BUDGET_PACKETS = 64;
+// Native capture backends can emit short bursts (ScreenCaptureKit commonly
+// queues up to eight frames).  Drain one frame per event-loop turn so a burst
+// cannot immediately overflow the smaller Hub-to-browser send lanes.
+const AGENT_BINARY_INGRESS_DRAIN_BUDGET_PACKETS = 1;
 const SYNTHETIC_FRAME_DATA_URL = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC';
 const SYNTHETIC_FRAME_PAYLOAD = Buffer.from(SYNTHETIC_FRAME_DATA_URL.split(',')[1], 'base64');
 const SYNTHETIC_FRAME_HASH = crypto.createHash('sha256').update(SYNTHETIC_FRAME_PAYLOAD).digest('hex').slice(0, 16);
@@ -683,9 +692,18 @@ function normalizeRemoteInputEvent(value = {}) {
     const issuedAtEpochMs = Number(input.issuedAtEpochMs ?? input.IssuedAtEpochMs);
     const hubReceivedAtEpochMs = Number(input.hubReceivedAtEpochMs ?? input.HubReceivedAtEpochMs);
     const captureGeneration = Number(input.captureGeneration ?? input.CaptureGeneration);
+    const rawPressedCodes = input.pressedCodes ?? input.PressedCodes;
+    const pressedCodes = Array.isArray(rawPressedCodes)
+        ? [...new Set(rawPressedCodes
+            .map(code => safeString(code, 80))
+            .filter(Boolean))]
+            .slice(0, 64)
+        : null;
     return {
         type,
-        monitorIndex: Number.isFinite(monitorIndex) ? normalizeMonitorIndex(monitorIndex) : 0,
+        // A missing monitor is not equivalent to the primary display. Control
+        // input must prove the exact monitor owned by its capture generation.
+        monitorIndex: Number.isFinite(monitorIndex) ? normalizeMonitorIndex(monitorIndex) : null,
         normalizedX: Number.isFinite(normalizedX) ? Math.max(0, Math.min(1, normalizedX)) : undefined,
         normalizedY: Number.isFinite(normalizedY) ? Math.max(0, Math.min(1, normalizedY)) : undefined,
         button: safeString(input.button || input.Button, 24),
@@ -695,8 +713,9 @@ function normalizeRemoteInputEvent(value = {}) {
         code: safeString(input.code || input.Code, 80),
         keyCode: Number.isFinite(keyCode) ? Math.max(0, Math.min(65535, Math.trunc(keyCode))) : 0,
         location: Number.isFinite(location) ? Math.max(0, Math.min(255, Math.trunc(location))) : 0,
-        text: safeText(input.text || input.Text, 256),
-        repeat: input.repeat === true || input.Repeat === true,
+        text: safeText(input.text || input.Text, 256),
+        repeat: input.repeat === true || input.Repeat === true,
+        pressedCodes,
         shiftKey: input.shiftKey === true || input.ShiftKey === true,
         ctrlKey: input.ctrlKey === true || input.ControlKey === true || input.CtrlKey === true,
         altKey: input.altKey === true || input.AltKey === true,
@@ -708,8 +727,9 @@ function normalizeRemoteInputEvent(value = {}) {
         hubConnectionId: safeString(input.hubConnectionId || input.HubConnectionId, 128),
         inputEventId: safeString(input.inputEventId || input.InputEventId, 128) || crypto.randomUUID(),
         inputSeq: Number.isSafeInteger(inputSeq) && inputSeq > 0 ? inputSeq : 0,
-        requestAck: input.requestAck !== false && input.RequestAck !== false,
-        issuedAtEpochMs: Number.isFinite(issuedAtEpochMs) ? issuedAtEpochMs : 0,
+        requestAck: input.requestAck !== false && input.RequestAck !== false,
+        reason: safeString(input.reason || input.Reason, 120),
+        issuedAtEpochMs: Number.isFinite(issuedAtEpochMs) ? issuedAtEpochMs : 0,
         hubReceivedAtEpochMs: Number.isFinite(hubReceivedAtEpochMs) ? hubReceivedAtEpochMs : 0,
         issuedAt: safeString(input.issuedAt || input.IssuedAt, 80)
     };
@@ -1014,10 +1034,26 @@ function serializeDevice(device, options = {}) {
             audio: !!device.audioSocket && !device.audioSocket.destroyed,
             file: !!device.fileSocket && !device.fileSocket.destroyed
         },
-        latestThumbnail: serializeRemoteFrame(device.latestThumbnail, device.deviceId, 'thumbnail', options),
-        latestLiveFrame: serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', options),
-        activeLiveStream: device.activeLiveStream ? { ...device.activeLiveStream } : null,
-        activeAudioStream: device.activeAudioStream ? { ...device.activeAudioStream } : null,
+        latestThumbnail: serializeRemoteFrame(device.latestThumbnail, device.deviceId, 'thumbnail', options),
+        latestLiveFrame: serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', options),
+        activeLiveStream: device.activeLiveStream ? { ...device.activeLiveStream } : null,
+        liveCapturePause: device.liveCapturePause
+            ? {
+                token: device.liveCapturePause.token,
+                pausedAt: device.liveCapturePause.pausedAt,
+                reason: device.liveCapturePause.reason,
+                streamId: device.liveCapturePause.streamId,
+                streamPurpose: device.liveCapturePause.streamPurpose,
+                monitorIndex: device.liveCapturePause.monitorIndex,
+                phase: device.liveCapturePause.phase,
+                captureStopConfirmed: device.liveCapturePause.captureStopConfirmed === true,
+                captureStopConfirmedAt: device.liveCapturePause.captureStopConfirmedAt || '',
+                stopCommandId: device.liveCapturePause.stopCommandId || '',
+                stopError: device.liveCapturePause.stopError || '',
+                stopAttemptCount: Math.max(0, Number(device.liveCapturePause.stopAttemptCount) || 0)
+            }
+            : null,
+        activeAudioStream: device.activeAudioStream ? { ...device.activeAudioStream } : null,
         latestAudioFrame: device.latestAudioFrame
             ? {
                 streamId: device.latestAudioFrame.streamId,
@@ -1454,7 +1490,9 @@ class RemoteHubWebSocketAgentSocket {
 }
 
 export function createRemoteHub(options = {}) {
-    const env = options.env || process.env;
+    const env = options.env || process.env;
+    const rejectFrameChannelForTest = isEnabledValue(env.LIVEDESK_TEST_MODE, false)
+        && isEnabledValue(env.LIVEDESK_TEST_REJECT_FRAME_CHANNEL, false);
     const logEvent = options.logEvent || (() => {});
     const logWarn = options.logWarn || (() => {});
     const emitEvent = options.emitEvent || (() => {});
@@ -1482,12 +1520,16 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function policyError(device, permission = '') {
-        const policy = getDevicePolicy(device);
-        if (policy.accessMode === 'block-remote-access') return 'remote-access-blocked-by-settings';
-        if (permission && policy[permission] === false) {
-            return `${permission}-blocked-by-settings`;
-        }
+    function policyError(device, permission = '', command = '') {
+        const policy = getDevicePolicy(device);
+        const commandName = safeString(command, 80);
+        if (policy.accessMode === 'block-remote-access'
+            && !REMOTE_POLICY_BYPASS_COMMANDS.has(commandName)) {
+            return 'remote-access-blocked-by-settings';
+        }
+        if (permission && policy[permission] === false) {
+            return `${permission}-blocked-by-settings`;
+        }
         return '';
     }
 
@@ -1506,6 +1548,11 @@ export function createRemoteHub(options = {}) {
         250,
         30000,
         DEFAULT_REMOTE_INPUT_ACK_TIMEOUT_MS);
+    const liveCaptureStopAckTimeoutMs = clampNumber(
+        options.liveCaptureStopAckTimeoutMs ?? env.REMOTE_HUB_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS,
+        250,
+        30000,
+        DEFAULT_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS);
     const managerPackage = safeString(options.managerPackage ?? env.LIVEDESK_MANAGER_PACKAGE ?? env.MINDEXEC_MANAGER_PACKAGE ?? '@livedesk/hub', 128);
     const managerVersion = safeString(options.managerVersion ?? env.LIVEDESK_MANAGER_VERSION ?? env.MINDEXEC_MANAGER_VERSION ?? '', 64);
     const hostInstanceId = safeString(options.hostInstanceId ?? env.LIVEDESK_HUB_INSTANCE_ID ?? env.MINDEXEC_BRIDGE_INSTANCE_ID ?? crypto.randomUUID(), 128) || crypto.randomUUID();
@@ -1534,9 +1581,10 @@ export function createRemoteHub(options = {}) {
     const sockets = new Map();
     const inputSockets = new Map();
     const frameSockets = new Map();
-    const audioSockets = new Map();
-    const fileSockets = new Map();
-    const allSockets = new Set();
+    const audioSockets = new Map();
+    const fileSockets = new Map();
+    const allSockets = new Set();
+    const pendingCommandResultWaiters = new Map();
     const duplicateDeviceLogAt = new Map();
     let server = null;
     let started = false;
@@ -2044,15 +2092,109 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    function emitRemoteEvent(type, device = null, extra = {}) {
-        emitEvent(type, {
-            ...extra,
-            remoteHub: getStatus({ includeSecrets: false }),
-            device: serializeDevice(device)
-        });
-    }
-
-    function makeSyntheticFrame(device, streamId, mode = 'thumbnail', options = {}) {
+    function emitRemoteEvent(type, device = null, extra = {}) {
+        emitEvent(type, {
+            ...extra,
+            remoteHub: getStatus({ includeSecrets: false }),
+            device: serializeDevice(device)
+        });
+    }
+
+    function settlePendingCommandResult(device, message = {}) {
+        const commandId = safeString(message.commandId, 128);
+        const waiter = pendingCommandResultWaiters.get(commandId);
+        if (!waiter
+            || waiter.deviceId !== device?.deviceId
+            || waiter.sessionId !== device?.sessionId) {
+            return false;
+        }
+
+        pendingCommandResultWaiters.delete(commandId);
+        clearTimeout(waiter.timer);
+        const result = message.result ?? null;
+        const error = safeString(
+            message.error
+            || result?.error
+            || (message.type === 'command.error' ? 'command-failed' : ''),
+            500);
+        waiter.resolve({
+            ok: !error
+                && result?.ok !== false
+                && result?.status !== 'failed'
+                && result?.status !== 'rejected',
+            commandId,
+            result,
+            error
+        });
+        return true;
+    }
+
+    function failPendingCommandResultWaiters(device, error = 'device-disconnected') {
+        if (!device?.deviceId) {
+            return;
+        }
+        for (const [commandId, waiter] of pendingCommandResultWaiters) {
+            if (waiter.deviceId !== device.deviceId
+                || (waiter.sessionId && waiter.sessionId !== device.sessionId)) {
+                continue;
+            }
+            pendingCommandResultWaiters.delete(commandId);
+            clearTimeout(waiter.timer);
+            waiter.resolve({
+                ok: false,
+                commandId,
+                result: null,
+                error: safeString(error, 500) || 'command-result-unavailable'
+            });
+        }
+    }
+
+    function waitForCommandResult(device, commandId, timeoutMs = liveCaptureStopAckTimeoutMs) {
+        const key = safeString(commandId, 128);
+        if (!device?.deviceId || !device?.sessionId || !key) {
+            return Promise.resolve({
+                ok: false,
+                commandId: key,
+                result: null,
+                error: 'command-result-wait-invalid'
+            });
+        }
+
+        return new Promise(resolve => {
+            const previous = pendingCommandResultWaiters.get(key);
+            if (previous) {
+                clearTimeout(previous.timer);
+                previous.resolve({
+                    ok: false,
+                    commandId: key,
+                    result: null,
+                    error: 'command-result-wait-replaced'
+                });
+            }
+            const timer = setTimeout(() => {
+                const waiter = pendingCommandResultWaiters.get(key);
+                if (!waiter || waiter.deviceId !== device.deviceId || waiter.sessionId !== device.sessionId) {
+                    return;
+                }
+                pendingCommandResultWaiters.delete(key);
+                resolve({
+                    ok: false,
+                    commandId: key,
+                    result: null,
+                    error: 'command-result-timeout'
+                });
+            }, timeoutMs);
+            timer.unref?.();
+            pendingCommandResultWaiters.set(key, {
+                deviceId: device.deviceId,
+                sessionId: device.sessionId,
+                timer,
+                resolve
+            });
+        });
+    }
+
+    function makeSyntheticFrame(device, streamId, mode = 'thumbnail', options = {}) {
         const now = new Date().toISOString();
         const descriptor = buildRemoteFrameTransferDescriptor(mode, mode === 'thumbnail' ? 'thumbnail' : DEFAULT_REMOTE_FRAME_MODE);
         const frameSeq = Number(device?.counters?.thumbnailFramesReceived || 0)
@@ -2144,9 +2286,12 @@ export function createRemoteHub(options = {}) {
             byteLength: frame.byteLength
         });
         streamState.latestFrame = frame;
-        streamState.lastFrameAt = frame.receivedAt;
-        streamState.lastFrameSeq = frame.frameSeq;
-        streamState.framesReceived = (streamState.framesReceived || 0) + 1;
+        streamState.lastFrameAt = frame.receivedAt;
+        streamState.lastFrameSeq = frame.frameSeq;
+        streamState.framesReceived = (streamState.framesReceived || 0) + 1;
+        // A synthetic PNG is a complete independently decodable surface and
+        // therefore key-frame equivalent for Control readiness.
+        streamState.readyFrameReceived = true;
         device.lastSeenAt = frame.receivedAt;
         device.counters.liveFramesReceived += 1;
         emitRemoteEvent('RemoteFrameReceived', device, {
@@ -2170,6 +2315,7 @@ export function createRemoteHub(options = {}) {
         existing.lastDisconnectReason = 'replaced-by-new-session';
         failAllPendingTasks(existing, 'replaced-by-new-session');
         failAllPendingInputFallbacks(existing, 'replaced-by-new-session');
+        failPendingCommandResultWaiters(existing, 'replaced-by-new-session');
         writeJsonLine(existing.socket, {
             type: 'disconnect',
             reason: 'replaced-by-new-session',
@@ -2709,9 +2855,11 @@ export function createRemoteHub(options = {}) {
                 : getSupportedRemoteFrameModeProfiles();
         }
 
-        const device = {
-            socket,
-            inputSocket: null,
+        const device = {
+            socket,
+            inputSocket: null,
+            inputOwnerConnectionId: '',
+            inputOwnerBindingKey: '',
             frameSocket: null,
             audioSocket: null,
             fileSocket: null,
@@ -2752,9 +2900,13 @@ export function createRemoteHub(options = {}) {
             recentFramePayloads: {
                 thumbnail: [],
                 live: []
-            },
-            activeLiveStream: null,
-            activeAudioStream: null,
+            },
+            activeLiveStream: null,
+            // A manual pause is a Hub-owned capture gate, not an Agent-session
+            // detail. Preserve the same lease across a transient Client
+            // reconnect so no subscriber or watchdog can reacquire FFmpeg.
+            liveCapturePause: existing?.liveCapturePause || null,
+            activeAudioStream: null,
             latestAudioFrame: null,
             latestAudioStatus: null,
             udp: {
@@ -2943,10 +3095,11 @@ export function createRemoteHub(options = {}) {
         closeInputSocket(device, reason);
         closeFrameSocket(device, reason);
         device.disconnectedAt = new Date().toISOString();
-        device.lastDisconnectReason = reason;
+        device.lastDisconnectReason = reason;
         deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
         failAllPendingTasks(device, 'device-disconnected');
         failAllPendingInputFallbacks(device, 'device-disconnected');
+        failPendingCommandResultWaiters(device, 'device-disconnected');
         logWarn('remote', `device disconnected ${device.deviceName} (${deviceId}): ${reason}`);
         emitRemoteEvent('RemoteDeviceDisconnected', device, { reason });
     }
@@ -3329,6 +3482,20 @@ export function createRemoteHub(options = {}) {
         return {
             deviceId: device.deviceId,
             commandId: safeString(message.commandId || message.CommandId || pending?.commandId, 128),
+            hubConnectionId: safeString(
+                message.hubConnectionId
+                || message.HubConnectionId
+                || result.hubConnectionId
+                || result.HubConnectionId
+                || pending?.hubConnectionId,
+                128),
+            inputEventId: safeString(
+                message.inputEventId
+                || message.InputEventId
+                || result.inputEventId
+                || result.InputEventId
+                || pending?.inputEventId,
+                128),
             inputSeq,
             inputType: safeString(
                 message.inputType
@@ -3337,6 +3504,13 @@ export function createRemoteHub(options = {}) {
                 || result.InputType
                 || pending?.inputType,
                 48),
+            monitorIndex: Number(
+                message.monitorIndex
+                ?? message.MonitorIndex
+                ?? result.monitorIndex
+                ?? result.MonitorIndex
+                ?? pending?.monitorIndex
+                ?? 0) || 0,
             issuedAtEpochMs: Number(
                 message.issuedAtEpochMs
                 ?? message.IssuedAtEpochMs
@@ -3602,13 +3776,35 @@ export function createRemoteHub(options = {}) {
             : 0;
     }
 
-    function readFrameStageMs(message, property) {
-        const value = Number(message?.[property]);
-        return Number.isFinite(value) && value >= 0
-            ? Math.round(value)
-            : 0;
-    }
-
+    function readFrameStageMs(message, property) {
+        const value = Number(message?.[property]);
+        return Number.isFinite(value) && value >= 0
+            ? Math.round(value)
+            : 0;
+    }
+
+    function readOptionalFrameStageMs(message, property) {
+        const rawValue = message?.[property];
+        if (rawValue === undefined || rawValue === null || rawValue === '') {
+            return undefined;
+        }
+        const value = Number(rawValue);
+        return Number.isFinite(value) && value >= 0
+            ? Math.round(value)
+            : undefined;
+    }
+
+    function hasFrameCaptureTiming(message) {
+        if (message?.captureTimingAvailable === false) {
+            return false;
+        }
+        if (message?.captureTimingAvailable === true) {
+            return true;
+        }
+        return ['captureP95Ms', 'captureAverageMs', 'captureStageMs']
+            .some(property => readOptionalFrameStageMs(message, property) !== undefined);
+    }
+
     function computeSameContentStreak(previousFrame, contentHash) {
         if (!contentHash || !previousFrame?.contentHash || previousFrame.contentHash !== contentHash) {
             return 0;
@@ -3682,7 +3878,7 @@ export function createRemoteHub(options = {}) {
             byteLength,
             transport,
             contentHash,
-            captureMs: readFrameCaptureMs(message),
+            captureMs: readFrameCaptureMs(message),
             captureStageMs: readFrameStageMs(message, 'captureStageMs'),
             convertMs: readFrameStageMs(message, 'convertMs'),
             compressMs: readFrameStageMs(message, 'compressMs'),
@@ -3774,6 +3970,7 @@ export function createRemoteHub(options = {}) {
             lastFrameAt: '',
             lastFrameSeq: 0,
             framesReceived: 0,
+            readyFrameReceived: false,
             latestFrame: null,
             stoppedAt: '',
             stopReason: ''
@@ -3991,6 +4188,13 @@ export function createRemoteHub(options = {}) {
             && (activeCaptureGeneration <= 0
                 || (frameCaptureGeneration > 0
                     && frameCaptureGeneration === activeCaptureGeneration));
+        const readyFrameReceivedBeforeFrame = streamState.readyFrameReceived === true;
+        const captureTimingAvailable = hasFrameCaptureTiming(message);
+        const videoTransport = transport === 'udp-p2p'
+            ? 'p2p-udp'
+            : transport === 'ws-binary'
+                ? 'direct-ws'
+                : 'direct-tcp';
         device.latestLiveFrame = {
             streamId,
             frameSeq,
@@ -4027,9 +4231,10 @@ export function createRemoteHub(options = {}) {
             agentPaceMs: Number.isFinite(Number(message.agentPaceMs)) ? Number(message.agentPaceMs) : 0,
             agentQueueBeforePaceMs: Number.isFinite(Number(message.agentQueueBeforePaceMs)) ? Number(message.agentQueueBeforePaceMs) : 0,
             agentFrameAgeMs: Number.isFinite(Number(message.agentFrameAgeMs)) ? Number(message.agentFrameAgeMs) : 0,
-            droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
-            hubIngressDropped: Number.isFinite(Number(message.hubIngressDropped)) ? Number(message.hubIngressDropped) : 0,
-            hardwareEncoder: safeString(message.hardwareEncoder, 80),
+            droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
+            hubIngressDropped: Number.isFinite(Number(message.hubIngressDropped)) ? Number(message.hubIngressDropped) : 0,
+            udpIncompleteFrames: Number.isFinite(Number(message.udpIncompleteFrames)) ? Number(message.udpIncompleteFrames) : 0,
+            hardwareEncoder: safeString(message.hardwareEncoder, 80),
             platformProfile: safeString(message.platformProfile, 80),
             monitorIndex: Number.isFinite(Number(message.monitorIndex)) ? normalizeMonitorIndex(message.monitorIndex) : Number(streamState.monitorIndex || 0),
             monitorCount: Number.isFinite(Number(message.monitorCount)) ? clampNumber(message.monitorCount, 1, 64, 1) : Number(streamState.monitorCount || 1),
@@ -4037,29 +4242,40 @@ export function createRemoteHub(options = {}) {
             transferProtocolVersion: transfer.transferProtocolVersion,
             handshake: transfer.handshake,
             fps: Number.isFinite(Number(message.fps)) ? Number(message.fps) : streamState.fps,
-            requestedFps: Number.isFinite(Number(message.requestedFps)) ? Number(message.requestedFps) : Number(streamState.fps || 0),
-            effectiveFps: Number.isFinite(Number(message.effectiveFps)) ? Number(message.effectiveFps) : Number(message.fps || streamState.fps || 0),
-            captureAverageMs: readFrameStageMs(message, 'captureAverageMs'),
-            captureP95Ms: readFrameStageMs(message, 'captureP95Ms'),
+            requestedFps: Number.isFinite(Number(message.requestedFps)) ? Number(message.requestedFps) : Number(streamState.fps || 0),
+            effectiveFps: Number.isFinite(Number(message.effectiveFps)) ? Number(message.effectiveFps) : Number(message.fps || streamState.fps || 0),
+            captureTimingAvailable,
+            captureAverageMs: captureTimingAvailable ? readOptionalFrameStageMs(message, 'captureAverageMs') : undefined,
+            captureP95Ms: captureTimingAvailable ? readOptionalFrameStageMs(message, 'captureP95Ms') : undefined,
             slowFrameCount: Number.isFinite(Number(message.slowFrameCount)) ? Number(message.slowFrameCount) : 0,
-            captureHelperRestarts: Number.isFinite(Number(message.captureHelperRestarts)) ? Number(message.captureHelperRestarts) : 0,
-            capturedAt,
-            receivedAt: device.lastSeenAt,
-            byteLength,
-            transport,
-            contentHash,
-            captureMs: readFrameCaptureMs(message),
-            captureStageMs: readFrameStageMs(message, 'captureStageMs'),
+            captureHelperRestarts: Number.isFinite(Number(message.captureHelperRestarts)) ? Number(message.captureHelperRestarts) : 0,
+            capturedAt,
+            receivedAt: device.lastSeenAt,
+            byteLength,
+            transport,
+            contentHash,
+            captureMs: captureTimingAvailable ? readOptionalFrameStageMs(message, 'captureMs') : undefined,
+            captureStageMs: captureTimingAvailable ? readOptionalFrameStageMs(message, 'captureStageMs') : undefined,
             convertMs: readFrameStageMs(message, 'convertMs'),
             compressMs: readFrameStageMs(message, 'compressMs'),
             captureSourceSerial: Number.isFinite(Number(message.captureSourceSerial)) ? Number(message.captureSourceSerial) : 0,
             captureSourceSkipped: Number.isFinite(Number(message.captureSourceSkipped)) ? Number(message.captureSourceSkipped) : 0,
             deltaTileSize: Number.isFinite(Number(message.deltaTileSize)) ? Number(message.deltaTileSize) : 0,
             deltaTileCount: Number.isFinite(Number(message.deltaTileCount)) ? Number(message.deltaTileCount) : 0,
-            deltaVisualTileCount: Number.isFinite(Number(message.deltaVisualTileCount)) ? Number(message.deltaVisualTileCount) : 0,
-            deltaRefreshTileCount: Number.isFinite(Number(message.deltaRefreshTileCount)) ? Number(message.deltaRefreshTileCount) : 0,
-            deltaTotalTiles: Number.isFinite(Number(message.deltaTotalTiles)) ? Number(message.deltaTotalTiles) : 0,
-            sameContentStreak,
+            deltaVisualTileCount: Number.isFinite(Number(message.deltaVisualTileCount)) ? Number(message.deltaVisualTileCount) : 0,
+            deltaRefreshTileCount: Number.isFinite(Number(message.deltaRefreshTileCount)) ? Number(message.deltaRefreshTileCount) : 0,
+            deltaTotalTiles: Number.isFinite(Number(message.deltaTotalTiles)) ? Number(message.deltaTotalTiles) : 0,
+            videoTransport,
+            frameTransportActive: safeString(message.frameTransportActive, 20) || (videoTransport === 'p2p-udp' ? 'p2p' : 'direct'),
+            frameTransportProtocol: safeString(message.frameTransportProtocol, 20)
+                || (videoTransport === 'p2p-udp' ? 'udp' : videoTransport === 'direct-ws' ? 'ws' : 'tcp'),
+            frameTransportState: safeString(message.frameTransportState, 20) || 'active',
+            frameTransportP2pReady: message.frameTransportP2pReady === true,
+            frameTransportReason: safeString(message.frameTransportReason, 240),
+            frameTransportChangedAt: safeString(message.frameTransportChangedAt, 80),
+            frameTransportSwitchCount: Number.isFinite(Number(message.frameTransportSwitchCount)) ? Number(message.frameTransportSwitchCount) : 0,
+            frameTransportTcpFailureCount: Number.isFinite(Number(message.frameTransportTcpFailureCount)) ? Number(message.frameTransportTcpFailureCount) : 0,
+            sameContentStreak,
             payload,
             accessToken: createFrameAccessToken()
         };
@@ -4073,9 +4289,12 @@ export function createRemoteHub(options = {}) {
             mimeType: device.latestLiveFrame.mimeType,
             byteLength: device.latestLiveFrame.byteLength
         });
-        streamState.lastFrameAt = device.lastSeenAt;
-        streamState.lastFrameSeq = frameSeq;
-        streamState.framesReceived = (streamState.framesReceived || 0) + 1;
+        streamState.lastFrameAt = device.lastSeenAt;
+        streamState.lastFrameSeq = frameSeq;
+        streamState.framesReceived = (streamState.framesReceived || 0) + 1;
+        streamState.readyFrameReceived = readyFrameReceivedBeforeFrame
+            || (currentGenerationVerified
+                && liveFrameSatisfiesReadiness(streamState, device.latestLiveFrame));
         streamState.mode = transfer.mode;
         streamState.frameMode = transfer.frameMode;
         streamState.frameProfile = transfer.frameProfile;
@@ -4093,7 +4312,9 @@ export function createRemoteHub(options = {}) {
         streamState.monitorCount = device.latestLiveFrame.monitorCount;
         ensureDeviceLiveStreams(device).set(streamId, streamState);
         device.counters.liveFramesReceived += 1;
-        if (streamState.framesReceived === 1 && liveStreamHasCurrentFrame(streamState)) {
+        if (!readyFrameReceivedBeforeFrame
+            && streamState.readyFrameReceived === true
+            && liveStreamHasCurrentFrame(streamState)) {
             emitRemoteEvent('RemoteLiveStreamReady', device, {
                 streamId,
                 commandId: streamState.commandId,
@@ -4217,7 +4438,7 @@ export function createRemoteHub(options = {}) {
         return true;
     }
 
-    function handleAgentBinaryFrame(socket, state, header, framePayload) {
+    function handleAgentBinaryFrame(socket, state, header, framePayload) {
         if (!state.authenticated || !state.device) {
             writeJsonLine(socket, { type: 'error', error: 'hello-required' });
             socket.destroy();
@@ -4241,28 +4462,29 @@ export function createRemoteHub(options = {}) {
         }
 
         const frameKind = safeString(header.frameKind || header.kind || header.frameType || '', 40).toLowerCase();
-        if (frameKind === 'thumbnail' || header.type === 'thumbnail.binary') {
-            applyThumbnailFrame(device, header, framePayload, 'binary');
-            return;
-        }
-
-        if (frameKind === 'stream' || frameKind === 'live' || header.type === 'stream.binary') {
-            applyLiveFrame(device, {
-                ...header,
-                hubIngressDropped: Number(state.binaryQueueDrops || 0)
-            }, framePayload, 'binary');
-            return;
-        }
-
-        if (frameKind === 'audio' || header.type === 'audio.binary') {
-            applyAudioFrame(device, header, framePayload, 'binary');
-            return;
-        }
-
-        if (frameKind === 'audio-status' || header.type === 'audio.status.binary') {
-            applyAudioStatus(device, header, framePayload, 'binary');
-            return;
-        }
+        const binaryTransport = state.binaryTransport === 'ws-binary' ? 'ws-binary' : 'binary';
+        if (frameKind === 'thumbnail' || header.type === 'thumbnail.binary') {
+            applyThumbnailFrame(device, header, framePayload, binaryTransport);
+            return;
+        }
+
+        if (frameKind === 'stream' || frameKind === 'live' || header.type === 'stream.binary') {
+            applyLiveFrame(device, {
+                ...header,
+                hubIngressDropped: Number(state.binaryQueueDrops || 0)
+            }, framePayload, binaryTransport);
+            return;
+        }
+
+        if (frameKind === 'audio' || header.type === 'audio.binary') {
+            applyAudioFrame(device, header, framePayload, binaryTransport);
+            return;
+        }
+
+        if (frameKind === 'audio-status' || header.type === 'audio.status.binary') {
+            applyAudioStatus(device, header, framePayload, binaryTransport);
+            return;
+        }
 
         emitRemoteEvent('RemoteAgentMessageIgnored', device, {
             messageType: safeString(header.type, 80),
@@ -4440,9 +4662,14 @@ export function createRemoteHub(options = {}) {
                 state.device = device;
                 state.inputOnly = true;
                 return;
-            }
-            if (channel === 'frame') {
-                const device = attachFrameSocket(socket, message);
+            }
+            if (channel === 'frame') {
+                if (rejectFrameChannelForTest) {
+                    writeJsonLine(socket, { type: 'error', error: 'test-frame-channel-unavailable' });
+                    socket.end();
+                    return;
+                }
+                const device = attachFrameSocket(socket, message);
                 if (!device) {
                     return;
                 }
@@ -4493,23 +4720,12 @@ export function createRemoteHub(options = {}) {
 
         if (state.inputOnly) {
             device.inputLastSeenAt = new Date().toISOString();
-            if (message.type === 'input.applied') {
+            if (message.type === 'input.applied' || message.type === 'input.error') {
                 handleRemoteInputOutcome(device, {
                     ...message,
                     agentApplyMs: Number(message.agentApplyMs || 0) || 0
                 }, 'input');
             }
-            if (message.type === 'input.error') {
-                const pending = takePendingInputFallback(
-                    device,
-                    message.commandId || message.CommandId,
-                    message.inputSeq ?? message.InputSeq);
-                emitEvent('RemoteInputError', {
-                    ...buildRemoteInputOutcome(device, message, pending),
-                    error: safeString(message.error || message.Error, 600) || 'remote-input-failed',
-                    failedAtEpochMs: Number(message.failedAtEpochMs ?? message.FailedAtEpochMs ?? 0) || 0
-                });
-            }
             return;
         }
         if (state.frameOnly) {
@@ -4553,6 +4769,7 @@ export function createRemoteHub(options = {}) {
                         message.error || (message.type === 'command.error' ? 'command-failed' : ''),
                         500);
                     const result = message.result ?? null;
+                    settlePendingCommandResult(device, message);
                     handleInputFallbackCommandResult(device, message);
                     if (error || result?.ok === false || result?.status === 'failed') {
                         failPendingLiveStream(device, commandId, error || result?.error || 'stream-start-failed');
@@ -4606,10 +4823,11 @@ export function createRemoteHub(options = {}) {
         socket.setNoDelay(true);
         socket.setKeepAlive(true, heartbeatMs);
 
-        const state = {
-            authenticated: false,
-            device: null,
-            inputOnly: false,
+        const state = {
+            authenticated: false,
+            device: null,
+            binaryTransport: 'ws-binary',
+            inputOnly: false,
             frameOnly: false,
             audioOnly: false,
             fileOnly: false,
@@ -4763,10 +4981,11 @@ export function createRemoteHub(options = {}) {
         socket.setNoDelay(true);
         socket.setKeepAlive(true, heartbeatMs);
 
-        const state = {
-            authenticated: false,
-            device: null,
-            inputOnly: false,
+        const state = {
+            authenticated: false,
+            device: null,
+            binaryTransport: 'binary',
+            inputOnly: false,
             frameOnly: false,
             audioOnly: false,
             fileOnly: false,
@@ -5000,6 +5219,7 @@ export function createRemoteHub(options = {}) {
         for (const device of devices.values()) {
             failAllPendingTasks(device, 'hub-shutdown');
             failAllPendingInputFallbacks(device, 'hub-shutdown');
+            failPendingCommandResultWaiters(device, 'hub-shutdown');
             if (device.socket && !device.socket.destroyed) {
                 writeJsonLine(device.socket, { type: 'disconnect', reason: 'hub-shutdown' });
                 device.socket.destroy();
@@ -5137,7 +5357,7 @@ export function createRemoteHub(options = {}) {
                     : commandName.startsWith('agent.')
                         ? 'allowAgent'
                         : '';
-        const denied = policyError(device, requiredPermission);
+        const denied = policyError(device, requiredPermission, commandName);
         if (denied) return { ok: false, error: denied };
         if (device?.synthetic === true && device.connected) {
             const commandId = safeString(command?.commandId, 128) || crypto.randomUUID();
@@ -5240,10 +5460,58 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'device-not-found' };
         }
 
-        if (!device.connected) {
-            return { ok: false, error: 'device-not-connected' };
-        }
-
+        if (!device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const normalized = normalizeRemoteInputEvent(input);
+        if (!normalized.type) {
+            return { ok: false, error: 'missing-input-type' };
+        }
+
+        // A reset only releases native key state. The current browser input
+        // owner must be able to send it even when its former Control binding
+        // has just become stale during a monitor/capture-generation switch.
+        const currentInputOwner = safeString(device.inputOwnerConnectionId, 128);
+        const isCurrentOwnerKeyboardReset = normalized.type.toLowerCase() === 'keyboard.reset'
+            && normalized.hubConnectionId
+            && normalized.hubConnectionId === currentInputOwner;
+        if (isCurrentOwnerKeyboardReset) {
+            const inputSocket = device.inputSocket;
+            if (inputSocket && !inputSocket.destroyed) {
+                const sent = writeJsonLine(inputSocket, {
+                    type: 'input.control',
+                    payload: {
+                        ...normalized,
+                        reason: normalized.reason || 'control-keyboard-owner-changed',
+                        pressedCodes: [],
+                        shiftKey: false,
+                        ctrlKey: false,
+                        altKey: false,
+                        metaKey: false,
+                        repeat: false,
+                        hubForwardedAtEpochMs: Date.now(),
+                        issuedAt: normalized.issuedAt || new Date().toISOString()
+                    }
+                });
+                if (sent) {
+                    device.inputOwnerBindingKey = '';
+                    device.counters.commandsSent += 1;
+                    device.inputLastSeenAt = new Date().toISOString();
+                    return {
+                        ok: true,
+                        inputSocket: true,
+                        releaseOnly: true,
+                        staleBindingAccepted: true
+                    };
+                }
+                detachInputSocket(inputSocket, 'input-owner-reset-write-failed');
+            }
+            if (readCapabilityFlag(device.capabilities, 'dedicatedInputChannel')) {
+                return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+            }
+        }
+
         const denied = policyError(device, 'allowControl');
         if (denied) return { ok: false, error: denied };
 
@@ -5255,10 +5523,6 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'device-input-control-unavailable' };
         }
 
-        const normalized = normalizeRemoteInputEvent(input);
-        if (!normalized.type) {
-            return { ok: false, error: 'missing-input-type' };
-        }
         const controlStream = getActiveControlStream(device);
         if (!controlStream
             || !liveStreamHasCurrentFrame(controlStream)
@@ -5292,18 +5556,74 @@ export function createRemoteHub(options = {}) {
                 activeCaptureGeneration: Number(controlStream.captureGeneration || 0)
             };
         }
+        const activeMonitorIndex = normalizeMonitorIndex(controlStream.monitorIndex);
+        if (!Number.isInteger(normalized.monitorIndex)
+            || normalized.monitorIndex !== activeMonitorIndex) {
+            return {
+                ok: false,
+                error: 'STALE_CONTROL_MONITOR',
+                activeMonitorIndex
+            };
+        }
 
         const inputSocket = device.inputSocket;
         if (inputSocket && !inputSocket.destroyed) {
-            const sent = writeJsonLine(inputSocket, {
+            const previousOwnerConnectionId = safeString(device.inputOwnerConnectionId, 128);
+            const activeInputBindingKey = [
+                safeString(device.sessionId, 160),
+                safeString(controlStream.commandId, 128),
+                Number(controlStream.captureGeneration || 0),
+                activeMonitorIndex
+            ].join(':');
+            const previousInputBindingKey = safeString(device.inputOwnerBindingKey, 512);
+            const ownerChanged = normalized.hubConnectionId
+                && previousOwnerConnectionId
+                && normalized.hubConnectionId !== previousOwnerConnectionId;
+            const bindingChanged = previousInputBindingKey
+                && previousInputBindingKey !== activeInputBindingKey;
+            if (ownerChanged || bindingChanged) {
+                const resetSent = writeJsonLine(inputSocket, {
+                    type: 'input.control',
+                    payload: {
+                        type: 'keyboard.reset',
+                        reason: ownerChanged
+                            ? 'browser-input-owner-changed'
+                            : 'control-input-binding-changed',
+                        pressedCodes: [],
+                        shiftKey: false,
+                        ctrlKey: false,
+                        altKey: false,
+                        metaKey: false,
+                        repeat: false,
+                        requestAck: false,
+                        inputSeq: 0,
+                        hubConnectionId: previousOwnerConnectionId,
+                        monitorIndex: activeMonitorIndex,
+                        controlSessionId: safeString(device.sessionId, 160),
+                        controlCommandId: safeString(controlStream.commandId, 128),
+                        captureGeneration: Number(controlStream.captureGeneration || 0),
+                        hubForwardedAtEpochMs: Date.now(),
+                        issuedAt: new Date().toISOString()
+                    }
+                });
+                if (!resetSent) {
+                    detachInputSocket(inputSocket, 'input-owner-reset-write-failed');
+                    return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+                }
+            }
+            const sent = writeJsonLine(inputSocket, {
                 type: 'input.control',
                 payload: {
                     ...normalized,
                     hubForwardedAtEpochMs: Date.now(),
                     issuedAt: normalized.issuedAt || new Date().toISOString()
                 }
-            });
-            if (sent) {
+            });
+            if (sent) {
+                if (normalized.hubConnectionId) {
+                    device.inputOwnerConnectionId = normalized.hubConnectionId;
+                }
+                device.inputOwnerBindingKey = activeInputBindingKey;
                 device.counters.commandsSent += 1;
                 device.inputLastSeenAt = new Date().toISOString();
                 return {
@@ -5311,13 +5631,21 @@ export function createRemoteHub(options = {}) {
                     inputSocket: true,
                     sessionId: device.sessionId,
                     commandId: controlStream.commandId,
-                    captureGeneration: controlStream.captureGeneration
+                    captureGeneration: controlStream.captureGeneration,
+                    monitorIndex: activeMonitorIndex
                 };
             }
 
-            detachInputSocket(inputSocket, 'input-socket-write-failed');
-        }
-
+            detachInputSocket(inputSocket, 'input-socket-write-failed');
+        }
+
+        // Current Agents advertise this ordered side channel. Crossing to the
+        // concurrent main command socket during a reconnect can invert
+        // keydown/keyup, so only legacy Agents use the compatibility fallback.
+        if (readCapabilityFlag(device.capabilities, 'dedicatedInputChannel')) {
+            return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+        }
+
         const hubForwardedAtEpochMs = Date.now();
         const fallback = sendCommand(deviceId, {
             command: 'input.control',
@@ -5332,6 +5660,9 @@ export function createRemoteHub(options = {}) {
                 commandId: fallback.commandId,
                 inputSeq: normalized.inputSeq,
                 inputType: normalized.type,
+                monitorIndex: normalized.monitorIndex,
+                hubConnectionId: normalized.hubConnectionId,
+                inputEventId: normalized.inputEventId,
                 issuedAtEpochMs: normalized.issuedAtEpochMs,
                 hubReceivedAtEpochMs: normalized.hubReceivedAtEpochMs,
                 hubForwardedAtEpochMs,
@@ -5348,6 +5679,7 @@ export function createRemoteHub(options = {}) {
                 deliveryCommandId: fallback.commandId,
                 commandId: controlStream.commandId,
                 captureGeneration: controlStream.captureGeneration,
+                monitorIndex: activeMonitorIndex,
                 inputSeq: normalized.inputSeq
             }
             : {
@@ -5357,6 +5689,49 @@ export function createRemoteHub(options = {}) {
             };
     }
 
+    function releaseInputOwner(deviceId, ownerConnectionId, reason = 'browser-input-owner-closed') {
+        const device = devices.get(String(deviceId || ''));
+        const owner = safeString(ownerConnectionId, 128);
+        if (!device || !owner || safeString(device.inputOwnerConnectionId, 128) !== owner) {
+            return { ok: false, error: 'input-owner-not-current' };
+        }
+
+        device.inputOwnerConnectionId = '';
+        device.inputOwnerBindingKey = '';
+        const inputSocket = device.inputSocket;
+        if (!inputSocket || inputSocket.destroyed) {
+            return { ok: true, queued: false };
+        }
+        const controlStream = getActiveControlStream(device);
+        const sent = writeJsonLine(inputSocket, {
+            type: 'input.control',
+            payload: {
+                type: 'keyboard.reset',
+                reason: safeString(reason, 120) || 'browser-input-owner-closed',
+                pressedCodes: [],
+                shiftKey: false,
+                ctrlKey: false,
+                altKey: false,
+                metaKey: false,
+                repeat: false,
+                requestAck: false,
+                inputSeq: 0,
+                hubConnectionId: owner,
+                monitorIndex: normalizeMonitorIndex(controlStream?.monitorIndex),
+                controlSessionId: safeString(device.sessionId, 160),
+                controlCommandId: safeString(controlStream?.commandId, 128),
+                captureGeneration: Number(controlStream?.captureGeneration || 0),
+                hubForwardedAtEpochMs: Date.now(),
+                issuedAt: new Date().toISOString()
+            }
+        });
+        if (!sent) {
+            detachInputSocket(inputSocket, 'input-owner-release-write-failed');
+            return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+        }
+        return { ok: true, queued: true };
+    }
+
     function notifyAgentProgress(deviceIds, progress = {}) {
         const targets = [...new Set((deviceIds || [])
             .map(deviceId => safeString(deviceId, 128))
@@ -5762,24 +6137,42 @@ export function createRemoteHub(options = {}) {
                 streamId: stream.streamId,
                 commandId: key,
                 error: safeString(error, 500) || 'stream-start-failed'
-            });
-            return true;
-        }
-        return false;
-    }
+            });
+            return true;
+        }
+        for (const stream of streams.values()) {
+            if (safeString(stream?.commandId, 128) !== key || stream?.active !== true) {
+                continue;
+            }
+            clearPendingLiveStreamDescriptor(device, stream);
+            stream.active = false;
+            stream.open = false;
+            stream.stoppedAt = new Date().toISOString();
+            stream.stopReason = safeString(error, 500) || 'stream-start-failed';
+            emitRemoteEvent('RemoteLiveStreamStartFailed', device, {
+                streamId: stream.streamId,
+                commandId: key,
+                error: stream.stopReason
+            });
+            return true;
+        }
+        return false;
+    }
 
     function deactivateDeviceLiveStreams(device, reason, stoppedAt = new Date().toISOString()) {
         const streams = ensureDeviceLiveStreams(device);
         for (const stream of streams.values()) {
             clearPendingLiveStreamDescriptor(device, stream);
             stream.active = false;
+            stream.open = false;
             stream.stoppedAt = stoppedAt;
             stream.stopReason = reason;
-        }
-        if (device?.activeLiveStream) {
-            device.activeLiveStream.active = false;
-            device.activeLiveStream.stoppedAt = stoppedAt;
-            device.activeLiveStream.stopReason = reason;
+        }
+        if (device?.activeLiveStream) {
+            device.activeLiveStream.active = false;
+            device.activeLiveStream.open = false;
+            device.activeLiveStream.stoppedAt = stoppedAt;
+            device.activeLiveStream.stopReason = reason;
         }
     }
 
@@ -5801,6 +6194,48 @@ export function createRemoteHub(options = {}) {
             safeString(stream?.streamPurpose, 24).toLowerCase() === 'control') || null;
     }
 
+    function claimSingleLiveCapture(deviceId, device, streamId, streamPurpose) {
+        const purpose = safeString(streamPurpose, 24).toLowerCase() || 'wall';
+        const activeControlStream = getActiveControlStream(device);
+        if (purpose !== 'control'
+            && activeControlStream
+            && activeControlStream.streamId !== streamId) {
+            return {
+                ok: false,
+                error: 'CONTROL_CAPTURE_OWNS_DEVICE',
+                activeStreamId: activeControlStream.streamId,
+                activeStreamPurpose: 'control',
+                activeCommandId: safeString(activeControlStream.commandId, 128),
+                captureGeneration: Number(activeControlStream.captureGeneration || 0)
+            };
+        }
+
+        const competingStreams = getActiveLiveStreams(device)
+            .filter(stream => stream.streamId !== streamId);
+        for (const competingStream of competingStreams) {
+            const result = stopLiveStream(deviceId, {
+                streamId: competingStream.streamId,
+                streamPurpose: competingStream.streamPurpose,
+                reason: `${purpose}-capture-handoff`
+            });
+            if (result?.ok !== true) {
+                return {
+                    ok: false,
+                    error: result?.error || 'capture-handoff-stop-failed',
+                    activeStreamId: competingStream.streamId,
+                    activeStreamPurpose: safeString(competingStream.streamPurpose, 24)
+                };
+            }
+            emitRemoteEvent('RemoteLiveStreamCapturePreempted', device, {
+                streamId: competingStream.streamId,
+                streamPurpose: safeString(competingStream.streamPurpose, 24) || 'wall',
+                replacementStreamId: streamId,
+                replacementStreamPurpose: purpose
+            });
+        }
+        return { ok: true };
+    }
+
     function nextCaptureGeneration(device) {
         const current = Number(device?.captureGenerationCounter || 0);
         const next = Number.isSafeInteger(current) && current > 0 ? current + 1 : 1;
@@ -5855,12 +6290,31 @@ export function createRemoteHub(options = {}) {
         return Number.isFinite(startedAt) && Date.now() - startedAt < LIVE_STREAM_REPLACEMENT_PENDING_MS;
     }
 
+    function liveStreamRequiresReadyKeyFrame(activeLiveStream) {
+        if (safeString(activeLiveStream?.streamPurpose, 24).toLowerCase() !== 'control') {
+            return false;
+        }
+        const codec = safeString(activeLiveStream?.codec, 80).toLowerCase();
+        const mode = safeString(activeLiveStream?.frameMode || activeLiveStream?.mode, 80).toLowerCase();
+        return codec.includes('h264') || mode === 'mode3-h264-hw';
+    }
+
+    function liveFrameSatisfiesReadiness(activeLiveStream, frame) {
+        return !liveStreamRequiresReadyKeyFrame(activeLiveStream)
+            || frame?.isKeyFrame === true
+            || safeString(frame?.chunkType, 20).toLowerCase() === 'key';
+    }
+
     function liveStreamHasCurrentFrame(activeLiveStream) {
         if (!activeLiveStream?.active
             || activeLiveStream.open !== true
             || Number(activeLiveStream.framesReceived || 0) < 1) {
             return false;
         }
+        if (liveStreamRequiresReadyKeyFrame(activeLiveStream)
+            && activeLiveStream.readyFrameReceived !== true) {
+            return false;
+        }
         const latestFrame = activeLiveStream.latestFrame;
         if (!latestFrame || latestFrame.currentGenerationVerified !== true) {
             return false;
@@ -5918,11 +6372,19 @@ export function createRemoteHub(options = {}) {
             && Number(activeLiveStream.monitorIndex || 0) === normalized.monitorIndex;
     }
 
-    function startLiveStream(deviceId, options = {}) {
-        const device = devices.get(String(deviceId || ''));
-        const denied = policyError(device);
-        if (denied) return { ok: false, error: denied };
-        if (device?.synthetic === true && device.connected) {
+    function startLiveStream(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        const denied = policyError(device);
+        if (denied) return { ok: false, error: denied };
+        if (device?.liveCapturePause?.token) {
+            return {
+                ok: false,
+                error: 'LIVE_CAPTURE_PAUSED',
+                pauseToken: device.liveCapturePause.token,
+                pausedAt: device.liveCapturePause.pausedAt
+            };
+        }
+        if (device?.synthetic === true && device.connected) {
             if (!readCapabilityFlag(device.capabilities, 'liveStream')) {
                 return { ok: false, error: 'device-live-stream-unavailable' };
             }
@@ -5933,6 +6395,8 @@ export function createRemoteHub(options = {}) {
             if (modePolicyError) return { ok: false, error: modePolicyError };
             const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
             const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
+            const captureClaim = claimSingleLiveCapture(deviceId, device, streamId, streamPurpose);
+            if (!captureClaim.ok) return captureClaim;
             const activeLiveStream = getDeviceLiveStream(device, streamId);
             const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
             if (activeLiveStream
@@ -5984,6 +6448,7 @@ export function createRemoteHub(options = {}) {
                 lastFrameAt: '',
                 lastFrameSeq: 0,
                 framesReceived: 0,
+                readyFrameReceived: false,
                 streamPurpose,
                 captureGeneration
             });
@@ -6031,6 +6496,8 @@ export function createRemoteHub(options = {}) {
         if (modePolicyError) return { ok: false, error: modePolicyError };
         const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
         const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
+        const captureClaim = claimSingleLiveCapture(deviceId, device, streamId, streamPurpose);
+        if (!captureClaim.ok) return captureClaim;
         const activeLiveStream = getDeviceLiveStream(device, streamId);
         const pendingDescriptor = getPendingLiveStreamDescriptor(activeLiveStream);
         if (pendingDescriptor?.commandId) {
@@ -6201,8 +6668,9 @@ export function createRemoteHub(options = {}) {
             stoppedAt: '',
             stopReason: '',
             lastFrameAt: '',
-            lastFrameSeq: 0,
+            lastFrameSeq: 0,
             framesReceived: 0,
+            readyFrameReceived: false,
             streamPurpose,
             captureGeneration,
             latestFrame: null,
@@ -6247,14 +6715,16 @@ export function createRemoteHub(options = {}) {
         };
     }
 
-    function stopLiveStream(deviceId, options = {}) {
+    function stopLiveStream(deviceId, options = {}) {
         const device = devices.get(String(deviceId || ''));
-        const streamPurpose = safeString(options.streamPurpose || options.purpose, 24);
-        const requestedStreamId = safeString(options.streamId, 128);
-        const purposeStreamId = streamPurpose ? makeStableLiveStreamId(deviceId, streamPurpose) : '';
-        const streamId = requestedStreamId || purposeStreamId || device?.activeLiveStream?.streamId || '';
+        const streamPurpose = safeString(options.streamPurpose || options.purpose, 24);
+        const requestedStreamId = safeString(options.streamId, 128);
+        const purposeStreamId = streamPurpose ? makeStableLiveStreamId(deviceId, streamPurpose) : '';
+        const streamId = options.stopAll === true
+            ? ''
+            : requestedStreamId || purposeStreamId || device?.activeLiveStream?.streamId || '';
         const streamState = getDeviceLiveStream(device, streamId);
-        if (streamState && streamState.active !== true) {
+        if (streamState && streamState.active !== true && options.forceCommand !== true) {
             clearPendingLiveStreamDescriptor(device, streamState);
             return {
                 ok: true,
@@ -6271,9 +6741,10 @@ export function createRemoteHub(options = {}) {
             device.counters.commandsSent += 1;
             if (streamState) {
                 streamState.active = false;
+                streamState.open = false;
                 streamState.stoppedAt = new Date().toISOString();
-                streamState.stopReason = 'manager-request';
-            }
+                streamState.stopReason = safeString(options.reason, 128) || 'manager-request';
+            }
             device.counters.liveStreamsStopped += 1;
             emitRemoteEvent('RemoteLiveStreamStopped', device, {
                 streamId,
@@ -6303,17 +6774,230 @@ export function createRemoteHub(options = {}) {
 
         if (streamState) {
             streamState.active = false;
+            streamState.open = false;
             streamState.stoppedAt = new Date().toISOString();
-            streamState.stopReason = 'manager-request';
-        }
+            streamState.stopReason = safeString(options.reason, 128) || 'manager-request';
+        }
         device.counters.liveStreamsStopped += 1;
         emitRemoteEvent('RemoteLiveStreamStopped', device, {
             streamId,
             commandId
         });
 
-        return { ok: true, commandId, streamId };
-    }
+        return { ok: true, commandId, streamId };
+    }
+
+    function buildLiveCapturePauseResult(pause, extra = {}) {
+        return {
+            paused: true,
+            pauseToken: pause.token,
+            pausedAt: pause.pausedAt,
+            streamId: pause.streamId,
+            streamPurpose: pause.streamPurpose,
+            monitorIndex: pause.monitorIndex,
+            phase: pause.phase,
+            captureStopConfirmed: pause.captureStopConfirmed === true,
+            captureStopConfirmedAt: pause.captureStopConfirmedAt || '',
+            stopCommandId: pause.stopCommandId || '',
+            stopError: pause.stopError || '',
+            stopAttemptCount: Math.max(0, Number(pause.stopAttemptCount) || 0),
+            ...extra
+        };
+    }
+
+    async function confirmLiveCaptureStopped(deviceId, pause) {
+        let device = devices.get(String(deviceId || ''));
+        if (!device || device.liveCapturePause?.token !== pause.token) {
+            return buildLiveCapturePauseResult(pause, {
+                ok: false,
+                error: 'LIVE_CAPTURE_PAUSE_LEASE_STALE'
+            });
+        }
+
+        pause.phase = 'pausing';
+        pause.captureStopConfirmed = false;
+        pause.captureStopConfirmedAt = '';
+        pause.stopError = '';
+        pause.stopAttemptCount = Math.max(0, Number(pause.stopAttemptCount) || 0) + 1;
+
+        let stopResult = { ok: true, alreadyStopped: true, streamId: pause.streamId };
+        if (device.synthetic !== true) {
+            stopResult = stopLiveStream(deviceId, {
+                reason: pause.reason,
+                // Empty streamId is an intentional Agent contract: stop every
+                // active/quarantined capture, including a native helper that
+                // outlived the Hub's last stream descriptor.
+                stopAll: true,
+                forceCommand: true
+            });
+        }
+
+        if (stopResult?.ok === false) {
+            pause.phase = 'stop-unconfirmed';
+            pause.stopError = safeString(stopResult.error, 500) || 'stream-stop-command-failed';
+            emitRemoteEvent('RemoteLiveCapturePauseFailed', device, {
+                pauseToken: pause.token,
+                streamId: pause.streamId,
+                stopError: pause.stopError
+            });
+            return buildLiveCapturePauseResult(pause, {
+                ok: false,
+                error: 'LIVE_CAPTURE_STOP_UNCONFIRMED'
+            });
+        }
+
+        pause.stopCommandId = safeString(stopResult.commandId, 128);
+        if (pause.stopCommandId
+            && stopResult.alreadyStopped !== true
+            && stopResult.synthetic !== true) {
+            const acknowledgement = await waitForCommandResult(
+                device,
+                pause.stopCommandId,
+                liveCaptureStopAckTimeoutMs);
+            device = devices.get(String(deviceId || '')) || device;
+            if (device.liveCapturePause?.token !== pause.token) {
+                return buildLiveCapturePauseResult(pause, {
+                    ok: false,
+                    error: 'LIVE_CAPTURE_PAUSE_LEASE_STALE'
+                });
+            }
+            if (!acknowledgement.ok
+                || acknowledgement.result?.stream !== true
+                || acknowledgement.result?.stopped !== true) {
+                pause.phase = 'stop-unconfirmed';
+                pause.stopError = safeString(
+                    acknowledgement.error
+                    || acknowledgement.result?.error
+                    || 'stream-stop-not-confirmed',
+                    500);
+                emitRemoteEvent('RemoteLiveCapturePauseFailed', device, {
+                    pauseToken: pause.token,
+                    streamId: pause.streamId,
+                    stopCommandId: pause.stopCommandId,
+                    stopError: pause.stopError
+                });
+                return buildLiveCapturePauseResult(pause, {
+                    ok: false,
+                    error: 'LIVE_CAPTURE_STOP_UNCONFIRMED'
+                });
+            }
+        }
+
+        pause.phase = 'paused';
+        pause.captureStopConfirmed = true;
+        pause.captureStopConfirmedAt = new Date().toISOString();
+        pause.stopError = '';
+        deactivateDeviceLiveStreams(device, pause.reason, pause.captureStopConfirmedAt);
+        emitRemoteEvent('RemoteLiveCapturePaused', device, {
+            pauseToken: pause.token,
+            pausedAt: pause.pausedAt,
+            streamId: pause.streamId,
+            streamPurpose: pause.streamPurpose,
+            monitorIndex: pause.monitorIndex,
+            stopCommandId: pause.stopCommandId,
+            captureStopConfirmedAt: pause.captureStopConfirmedAt
+        });
+        return buildLiveCapturePauseResult(pause, {
+            ok: true,
+            alreadyStopped: stopResult.alreadyStopped === true
+        });
+    }
+
+    async function pauseLiveCapture(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device) {
+            return { ok: false, paused: false, error: 'device-not-found' };
+        }
+        const denied = policyError(device, '', 'stream.stop');
+        if (denied) return { ok: false, paused: false, error: denied };
+
+        let pause = device.liveCapturePause;
+        if (pause?.token && pause.captureStopConfirmed === true) {
+            return buildLiveCapturePauseResult(pause, {
+                ok: true,
+                alreadyPaused: true
+            });
+        }
+        if (pause?.stopPromise) {
+            return pause.stopPromise;
+        }
+
+        if (!pause?.token) {
+            const activeLiveStream = device.activeLiveStream?.active === true
+                ? device.activeLiveStream
+                : null;
+            pause = {
+                token: crypto.randomUUID(),
+                pausedAt: new Date().toISOString(),
+                reason: safeString(options.reason, 128) || 'user-video-pause',
+                streamId: safeString(activeLiveStream?.streamId, 128),
+                streamPurpose: safeString(activeLiveStream?.streamPurpose, 24),
+                monitorIndex: Math.max(0, Math.floor(Number(activeLiveStream?.monitorIndex) || 0)),
+                phase: 'pausing',
+                captureStopConfirmed: false,
+                captureStopConfirmedAt: '',
+                stopCommandId: '',
+                stopError: '',
+                stopAttemptCount: 0
+            };
+            // Install the authoritative gate before asking the Agent to stop.
+            // A late subscriber or watchdog therefore cannot reacquire FFmpeg
+            // in the pause transition window.
+            device.liveCapturePause = pause;
+        }
+
+        const operation = confirmLiveCaptureStopped(deviceId, pause);
+        pause.stopPromise = operation;
+        try {
+            return await operation;
+        } finally {
+            if (pause.stopPromise === operation) {
+                delete pause.stopPromise;
+            }
+        }
+    }
+
+    function resumeLiveCapture(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        const denied = policyError(device);
+        if (denied) return { ok: false, error: denied };
+        const pause = device?.liveCapturePause;
+        if (!pause?.token) {
+            return { ok: true, paused: false, alreadyResumed: true };
+        }
+        if (pause.phase === 'pausing') {
+            return {
+                ok: false,
+                paused: true,
+                error: 'LIVE_CAPTURE_STOP_IN_PROGRESS',
+                pauseToken: pause.token
+            };
+        }
+        const pauseToken = safeString(options.pauseToken, 128);
+        if (!pauseToken || pauseToken !== pause.token) {
+            return {
+                ok: false,
+                error: 'LIVE_CAPTURE_PAUSE_TOKEN_MISMATCH'
+            };
+        }
+
+        device.liveCapturePause = null;
+        emitRemoteEvent('RemoteLiveCaptureResumed', device, {
+            pauseToken,
+            resumedAt: new Date().toISOString(),
+            streamId: pause.streamId,
+            streamPurpose: pause.streamPurpose,
+            monitorIndex: pause.monitorIndex
+        });
+        return {
+            ok: true,
+            paused: false,
+            resumed: true,
+            streamId: pause.streamId,
+            streamPurpose: pause.streamPurpose,
+            monitorIndex: pause.monitorIndex
+        };
+    }
 
     function startAudioStream(deviceId, options = {}) {
         const device = devices.get(String(deviceId || ''));
@@ -6475,15 +7159,18 @@ export function createRemoteHub(options = {}) {
         sendCommand,
         sendLegacyClientUpdate,
         sendInputControl,
+        releaseInputOwner,
         notifyAgentProgress,
         requestAgentTask,
         requestAgentTaskBatch,
         setHostTarget,
         rotatePairingPin,
-        requestThumbnail,
-        startLiveStream,
-        stopLiveStream,
-        startAudioStream,
+        requestThumbnail,
+        startLiveStream,
+        stopLiveStream,
+        pauseLiveCapture,
+        resumeLiveCapture,
+        startAudioStream,
         stopAudioStream,
         getDeviceLiveFrame,
         getDeviceThumbnail,