livedesk 0.1.367 → 0.1.369

package/hub/src/remote-hub.js

@@ -24,9 +24,10 @@ const RECENT_LIVE_FRAME_CACHE_LIMIT = 1;
 const RECENT_THUMBNAIL_FRAME_CACHE_MAX_BYTES = 2 * 1024 * 1024;
 const RECENT_LIVE_FRAME_CACHE_MAX_BYTES = 8 * 1024 * 1024;
 const LIVE_STREAM_PENDING_REUSE_MS = 5000;
-const LIVE_STREAM_REPLACEMENT_PENDING_MS = 7000;
-const LIVE_STREAM_MIN_FRESH_MS = 3000;
-const LIVE_STREAM_MAX_FRESH_MS = 12000;
+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 REMOTE_AGENT_PROTOCOL = 'mindexec.remote.agent';
 const REMOTE_FRAME_PROTOCOL = 'mindexec.remote.frame.v2';
@@ -643,6 +644,7 @@ function normalizeRemoteInputEvent(value = {}) {
         controlCommandId: safeString(input.controlCommandId || input.commandId || input.ControlCommandId || input.CommandId, 128),
         captureGeneration: Number.isSafeInteger(captureGeneration) && captureGeneration > 0 ? captureGeneration : 0,
         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,
@@ -1430,11 +1432,16 @@ export function createRemoteHub(options = {}) {
     const host = safeString(env.REMOTE_HUB_HOST || DEFAULT_REMOTE_HUB_HOST, 128);
     const requestedPort = normalizePort(env.REMOTE_HUB_PORT || DEFAULT_REMOTE_HUB_PORT);
     const heartbeatMs = clampNumber(env.REMOTE_HUB_HEARTBEAT_MS, 1000, 60000, DEFAULT_HEARTBEAT_MS);
-    const taskTimeoutMs = clampNumber(
-        options.taskTimeoutMs ?? env.REMOTE_HUB_TASK_TIMEOUT_MS,
-        50,
-        30 * 60 * 1000,
-        DEFAULT_AGENT_TASK_TIMEOUT_MS);
+    const taskTimeoutMs = clampNumber(
+        options.taskTimeoutMs ?? env.REMOTE_HUB_TASK_TIMEOUT_MS,
+        50,
+        30 * 60 * 1000,
+        DEFAULT_AGENT_TASK_TIMEOUT_MS);
+    const inputAckTimeoutMs = clampNumber(
+        options.inputAckTimeoutMs ?? env.REMOTE_HUB_INPUT_ACK_TIMEOUT_MS,
+        250,
+        30000,
+        DEFAULT_REMOTE_INPUT_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();
@@ -1976,9 +1983,11 @@ export function createRemoteHub(options = {}) {
             + Number(device?.counters?.liveFramesReceived || 0)
             + 1;
         return {
-            streamId: safeString(streamId, 128) || `${mode}-${Date.now()}`,
-            frameSeq,
-            commandId: safeString(options.commandId, 128),
+            streamId: safeString(streamId, 128) || `${mode}-${Date.now()}`,
+            frameSeq,
+            commandId: safeString(options.commandId, 128),
+            captureGeneration: Number(options.captureGeneration || 0),
+            currentGenerationVerified: true,
             width: clampNumber(options.width, 2, 3840, mode === 'thumbnail' ? 360 : 640),
             height: clampNumber(options.height, 1, 2160, mode === 'thumbnail' ? 220 : 360),
             mimeType: 'image/png',
@@ -2043,10 +2052,11 @@ export function createRemoteHub(options = {}) {
             commandId: options.commandId || streamState.commandId,
             width: options.maxWidth || 960,
             height: options.maxHeight || 540,
-            monitorIndex: options.monitorIndex ?? streamState.monitorIndex ?? 0,
-            monitorCount: options.monitorCount ?? streamState.monitorCount ?? 1,
-            fps: options.fps || streamState.fps
-        });
+            monitorIndex: options.monitorIndex ?? streamState.monitorIndex ?? 0,
+            monitorCount: options.monitorCount ?? streamState.monitorCount ?? 1,
+            fps: options.fps || streamState.fps,
+            captureGeneration: streamState.captureGeneration
+        });
         device.latestLiveFrame = frame;
         rememberRecentFramePayload(device, 'live', frame);
         emitFrame({
@@ -2081,9 +2091,10 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        existing.lastDisconnectReason = 'replaced-by-new-session';
-        failAllPendingTasks(existing, 'replaced-by-new-session');
-        writeJsonLine(existing.socket, {
+        existing.lastDisconnectReason = 'replaced-by-new-session';
+        failAllPendingTasks(existing, 'replaced-by-new-session');
+        failAllPendingInputFallbacks(existing, 'replaced-by-new-session');
+        writeJsonLine(existing.socket, {
             type: 'disconnect',
             reason: 'replaced-by-new-session',
             nextSessionId
@@ -2856,9 +2867,10 @@ export function createRemoteHub(options = {}) {
         closeFrameSocket(device, reason);
         device.disconnectedAt = new Date().toISOString();
         device.lastDisconnectReason = reason;
-        deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
-        failAllPendingTasks(device, 'device-disconnected');
-        logWarn('remote', `device disconnected ${device.deviceName} (${deviceId}): ${reason}`);
+        deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
+        failAllPendingTasks(device, 'device-disconnected');
+        failAllPendingInputFallbacks(device, 'device-disconnected');
+        logWarn('remote', `device disconnected ${device.deviceName} (${deviceId}): ${reason}`);
         emitRemoteEvent('RemoteDeviceDisconnected', device, { reason });
     }
 
@@ -3116,10 +3128,10 @@ export function createRemoteHub(options = {}) {
         return task;
     }
 
-    function failAllPendingTasks(device, error = 'device-disconnected') {
-        if (!device?.pendingTaskCommands) {
-            return 0;
-        }
+    function failAllPendingTasks(device, error = 'device-disconnected') {
+        if (!device?.pendingTaskCommands) {
+            return 0;
+        }
 
         const commandIds = [...device.pendingTaskCommands.keys()];
         let failed = 0;
@@ -3127,11 +3139,263 @@ export function createRemoteHub(options = {}) {
             if (failPendingTask(device, commandId, error)) {
                 failed += 1;
             }
-        }
-        return failed;
-    }
-
-    function scheduleTaskTimeout(device, task) {
+        }
+        return failed;
+    }
+
+    function ensurePendingInputFallbacks(device) {
+        if (!(device?.pendingInputFallbacks instanceof Map)) {
+            Object.defineProperty(device, 'pendingInputFallbacks', {
+                value: new Map(),
+                enumerable: false,
+                configurable: true,
+                writable: true
+            });
+        }
+        if (!(device?.completedInputFallbacks instanceof Map)) {
+            Object.defineProperty(device, 'completedInputFallbacks', {
+                value: new Map(),
+                enumerable: false,
+                configurable: true,
+                writable: true
+            });
+        }
+        return device.pendingInputFallbacks;
+    }
+
+    function pruneCompletedInputFallbacks(device, now = Date.now()) {
+        ensurePendingInputFallbacks(device);
+        for (const [key, expiresAt] of device.completedInputFallbacks.entries()) {
+            if (!Number.isFinite(expiresAt) || expiresAt <= now) {
+                device.completedInputFallbacks.delete(key);
+            }
+        }
+    }
+
+    function getInputFallbackCompletionKeys(commandId, inputSeq) {
+        const keys = [];
+        const normalizedCommandId = safeString(commandId, 128);
+        const normalizedInputSeq = Number(inputSeq || 0);
+        if (normalizedCommandId) {
+            keys.push(`command:${normalizedCommandId}`);
+        }
+        if (Number.isSafeInteger(normalizedInputSeq) && normalizedInputSeq > 0) {
+            keys.push(`seq:${normalizedInputSeq}`);
+        }
+        return keys;
+    }
+
+    function rememberCompletedInputFallback(device, pending) {
+        pruneCompletedInputFallbacks(device);
+        const expiresAt = Date.now() + Math.max(inputAckTimeoutMs * 2, 10000);
+        for (const key of getInputFallbackCompletionKeys(pending?.commandId, pending?.inputSeq)) {
+            device.completedInputFallbacks.set(key, expiresAt);
+        }
+        while (device.completedInputFallbacks.size > 256) {
+            const oldestKey = device.completedInputFallbacks.keys().next().value;
+            if (!oldestKey) {
+                break;
+            }
+            device.completedInputFallbacks.delete(oldestKey);
+        }
+    }
+
+    function wasInputFallbackCompleted(device, commandId, inputSeq) {
+        pruneCompletedInputFallbacks(device);
+        return getInputFallbackCompletionKeys(commandId, inputSeq)
+            .some(key => device.completedInputFallbacks.has(key));
+    }
+
+    function findPendingInputFallback(device, commandId, inputSeq) {
+        const pendingFallbacks = ensurePendingInputFallbacks(device);
+        const key = safeString(commandId, 128);
+        if (key && pendingFallbacks.has(key)) {
+            return pendingFallbacks.get(key);
+        }
+        const sequence = Number(inputSeq || 0);
+        if (!Number.isSafeInteger(sequence) || sequence <= 0) {
+            return null;
+        }
+        for (const pending of pendingFallbacks.values()) {
+            if (Number(pending?.inputSeq || 0) === sequence) {
+                return pending;
+            }
+        }
+        return null;
+    }
+
+    function takePendingInputFallback(device, commandId, inputSeq) {
+        const pending = findPendingInputFallback(device, commandId, inputSeq);
+        if (!pending) {
+            return null;
+        }
+        if (pending.timeoutTimer) {
+            clearTimeout(pending.timeoutTimer);
+            pending.timeoutTimer = null;
+        }
+        ensurePendingInputFallbacks(device).delete(pending.commandId);
+        rememberCompletedInputFallback(device, pending);
+        return pending;
+    }
+
+    function buildRemoteInputOutcome(device, message = {}, pending = null) {
+        const result = message?.result && typeof message.result === 'object'
+            ? message.result
+            : {};
+        const inputSeq = Number(
+            message.inputSeq
+            ?? message.InputSeq
+            ?? result.inputSeq
+            ?? result.InputSeq
+            ?? pending?.inputSeq
+            ?? 0) || 0;
+        return {
+            deviceId: device.deviceId,
+            commandId: safeString(message.commandId || message.CommandId || pending?.commandId, 128),
+            inputSeq,
+            inputType: safeString(
+                message.inputType
+                || message.InputType
+                || result.inputType
+                || result.InputType
+                || pending?.inputType,
+                48),
+            issuedAtEpochMs: Number(
+                message.issuedAtEpochMs
+                ?? message.IssuedAtEpochMs
+                ?? result.issuedAtEpochMs
+                ?? result.IssuedAtEpochMs
+                ?? pending?.issuedAtEpochMs
+                ?? 0) || 0,
+            hubReceivedAtEpochMs: Number(
+                message.hubReceivedAtEpochMs
+                ?? message.HubReceivedAtEpochMs
+                ?? result.hubReceivedAtEpochMs
+                ?? result.HubReceivedAtEpochMs
+                ?? pending?.hubReceivedAtEpochMs
+                ?? 0) || 0,
+            hubForwardedAtEpochMs: Number(
+                message.hubForwardedAtEpochMs
+                ?? message.HubForwardedAtEpochMs
+                ?? result.hubForwardedAtEpochMs
+                ?? result.HubForwardedAtEpochMs
+                ?? pending?.hubForwardedAtEpochMs
+                ?? 0) || 0,
+            fallback: pending?.fallback === true,
+            hubAcknowledgedAtEpochMs: Date.now()
+        };
+    }
+
+    function emitRemoteInputApplied(device, message = {}, pending = null) {
+        const outcome = buildRemoteInputOutcome(device, message, pending);
+        emitEvent('RemoteInputApplied', {
+            ...outcome,
+            agentApplyMs: Number(
+                message.agentApplyMs
+                ?? message.AgentApplyMs
+                ?? message.result?.agentApplyMs
+                ?? message.result?.AgentApplyMs
+                ?? 0) || 0
+        });
+    }
+
+    function emitRemoteInputError(device, message = {}, pending = null, fallbackError = 'remote-input-failed') {
+        const outcome = buildRemoteInputOutcome(device, message, pending);
+        emitEvent('RemoteInputError', {
+            ...outcome,
+            error: safeString(
+                message.error
+                || message.Error
+                || message.result?.error
+                || message.result?.Error
+                || fallbackError,
+                600) || fallbackError,
+            failedAtEpochMs: Number(
+                message.failedAtEpochMs
+                ?? message.FailedAtEpochMs
+                ?? message.result?.failedAtEpochMs
+                ?? message.result?.FailedAtEpochMs
+                ?? 0) || 0
+        });
+    }
+
+    function handleRemoteInputOutcome(device, message = {}, source = 'input') {
+        const commandId = safeString(message.commandId || message.CommandId, 128);
+        const inputSeq = Number(message.inputSeq ?? message.InputSeq ?? 0) || 0;
+        const pending = takePendingInputFallback(device, commandId, inputSeq);
+        if (!pending
+            && source === 'main'
+            && wasInputFallbackCompleted(device, commandId, inputSeq)) {
+            return false;
+        }
+        // Main-channel input acknowledgements only exist for a tracked
+        // compatibility fallback. Ignore stale/unmatched messages so an old
+        // session cannot acknowledge input from the current control session.
+        if (!pending && source === 'main') {
+            return false;
+        }
+        if (message.type === 'input.error') {
+            emitRemoteInputError(device, message, pending);
+        } else {
+            emitRemoteInputApplied(device, message, pending);
+        }
+        return true;
+    }
+
+    function handleInputFallbackCommandResult(device, message = {}) {
+        const commandId = safeString(message.commandId || message.CommandId, 128);
+        const pending = findPendingInputFallback(device, commandId, 0);
+        if (!pending) {
+            return false;
+        }
+        const completed = takePendingInputFallback(device, commandId, pending.inputSeq);
+        const result = message.result && typeof message.result === 'object' ? message.result : {};
+        const error = safeString(message.error || message.Error || result.error || result.Error, 600);
+        const failed = message.type === 'command.error'
+            || !!error
+            || result.ok === false
+            || safeString(result.status, 40).toLowerCase() === 'failed';
+        if (failed) {
+            emitRemoteInputError(device, { ...message, error: error || 'remote-input-failed' }, completed);
+        } else {
+            emitRemoteInputApplied(device, message, completed);
+        }
+        return true;
+    }
+
+    function schedulePendingInputFallback(device, pending) {
+        const pendingFallbacks = ensurePendingInputFallbacks(device);
+        const existing = pendingFallbacks.get(pending.commandId);
+        if (existing?.timeoutTimer) {
+            clearTimeout(existing.timeoutTimer);
+        }
+        pendingFallbacks.set(pending.commandId, pending);
+        pending.timeoutTimer = setTimeout(() => {
+            const timedOut = takePendingInputFallback(device, pending.commandId, pending.inputSeq);
+            if (timedOut) {
+                emitRemoteInputError(device, { error: 'remote-input-timeout' }, timedOut, 'remote-input-timeout');
+            }
+        }, inputAckTimeoutMs);
+        pending.timeoutTimer.unref?.();
+    }
+
+    function failAllPendingInputFallbacks(device, error = 'device-disconnected') {
+        if (!device || typeof device !== 'object') {
+            return 0;
+        }
+        const pendingFallbacks = ensurePendingInputFallbacks(device);
+        const pending = [...pendingFallbacks.values()];
+        for (const item of pending) {
+            const failed = takePendingInputFallback(device, item.commandId, item.inputSeq);
+            if (failed) {
+                emitRemoteInputError(device, { error }, failed, error);
+            }
+        }
+        device.completedInputFallbacks.clear();
+        return pending.length;
+    }
+
+    function scheduleTaskTimeout(device, task) {
         const commandId = safeString(task?.commandId, 128);
         if (!device?.pendingTaskTimers || !commandId) {
             return;
@@ -3370,10 +3634,108 @@ export function createRemoteHub(options = {}) {
         return true;
     }
 
-    function applyLiveStreamOpen(device, message, transport = 'json') {
-        const streamId = safeString(message.streamId, 128) || 'live';
-        const streamState = getDeviceLiveStream(device, streamId);
-        if (!streamState?.active) {
+    function promotePendingLiveStream(device, streamState, message, transport) {
+        const pending = getPendingLiveStreamDescriptor(streamState);
+        const commandId = safeString(message.commandId, 128);
+        if (!pending || !commandId || commandId !== safeString(pending.commandId, 128)) {
+            return null;
+        }
+        const messageCaptureGeneration = Number(message.captureGeneration || 0);
+        const pendingCaptureGeneration = Number(pending.captureGeneration || 0);
+        if (messageCaptureGeneration > 0
+            && pendingCaptureGeneration > 0
+            && messageCaptureGeneration !== pendingCaptureGeneration) {
+            emitRemoteEvent('RemoteLiveStreamOpenIgnored', device, {
+                reason: 'stale-pending-capture-generation',
+                streamId: streamState.streamId,
+                commandId,
+                captureGeneration: messageCaptureGeneration,
+                pendingCaptureGeneration,
+                transport
+            });
+            return null;
+        }
+
+        const previousCommandId = safeString(streamState.commandId, 128);
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(
+            message,
+            pending.mode || pending.frameMode || DEFAULT_REMOTE_FRAME_MODE);
+        const openedAt = safeString(message.openedAt, 80) || device.lastSeenAt || new Date().toISOString();
+        const nextStreamState = {
+            ...streamState,
+            ...pending,
+            streamId: streamState.streamId,
+            commandId,
+            active: true,
+            open: true,
+            openedAt,
+            openTransport: transport,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            codec: transfer.codec,
+            compression: transfer.compression,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
+            width: Number.isFinite(Number(message.width)) ? Number(message.width) : Number(pending.width || 0),
+            height: Number.isFinite(Number(message.height)) ? Number(message.height) : Number(pending.height || 0),
+            sourceWidth: Number.isFinite(Number(message.sourceWidth)) ? Number(message.sourceWidth) : Number(pending.sourceWidth || 0),
+            sourceHeight: Number.isFinite(Number(message.sourceHeight)) ? Number(message.sourceHeight) : Number(pending.sourceHeight || 0),
+            monitorIndex: Number.isFinite(Number(message.monitorIndex))
+                ? normalizeMonitorIndex(message.monitorIndex)
+                : Number(pending.monitorIndex || 0),
+            monitorCount: Number.isFinite(Number(message.monitorCount))
+                ? clampNumber(message.monitorCount, 1, 64, 1)
+                : Number(pending.monitorCount || 1),
+            streamPurpose: safeString(message.streamPurpose || pending.streamPurpose, 24) || 'wall',
+            captureGeneration: messageCaptureGeneration > 0
+                ? messageCaptureGeneration
+                : pendingCaptureGeneration,
+            openedFrameSeq: Number.isFinite(Number(message.frameSeq)) ? Number(message.frameSeq) : 0,
+            lastFrameAt: '',
+            lastFrameSeq: 0,
+            framesReceived: 0,
+            latestFrame: null,
+            stoppedAt: '',
+            stopReason: ''
+        };
+        clearPendingLiveStreamDescriptor(device, streamState);
+        setPendingLiveStreamDescriptor(nextStreamState, null);
+        if (device.latestLiveFrame?.streamId === streamState.streamId
+            && safeString(device.latestLiveFrame.commandId, 128) === previousCommandId) {
+            device.latestLiveFrame = null;
+        }
+        setDeviceLiveStream(device, nextStreamState);
+        return {
+            streamState: nextStreamState,
+            transfer,
+            previousCommandId
+        };
+    }
+
+    function emitLiveStreamOpened(device, streamState, transfer, transport, previousCommandId = '') {
+        emitRemoteEvent('RemoteLiveStreamOpened', device, {
+            streamId: streamState.streamId,
+            commandId: streamState.commandId,
+            previousCommandId,
+            handoff: !!previousCommandId,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            compression: transfer.compression,
+            transport,
+            captureGeneration: Number(streamState.captureGeneration || 0),
+            streamPurpose: safeString(streamState.streamPurpose, 24) || 'wall'
+        });
+    }
+
+    function applyLiveStreamOpen(device, message, transport = 'json') {
+        const streamId = safeString(message.streamId, 128) || 'live';
+        const streamState = getDeviceLiveStream(device, streamId);
+        if (!streamState?.active) {
             emitRemoteEvent('RemoteLiveStreamOpenIgnored', device, {
                 reason: 'stale-live-stream-open',
                 streamId,
@@ -3381,12 +3743,13 @@ export function createRemoteHub(options = {}) {
             });
             return false;
         }
-
-        const commandId = safeString(message.commandId, 128);
-        const activeCommandId = safeString(streamState.commandId, 128);
-        const pendingCommandId = safeString(streamState.pendingCommandId, 128);
-        const isActiveGeneration = !commandId || !activeCommandId || commandId === activeCommandId;
-        const isPendingGeneration = !!pendingCommandId && commandId === pendingCommandId;
+
+        const commandId = safeString(message.commandId, 128);
+        const activeCommandId = safeString(streamState.commandId, 128);
+        const pendingDescriptor = getPendingLiveStreamDescriptor(streamState);
+        const pendingCommandId = safeString(pendingDescriptor?.commandId, 128);
+        const isActiveGeneration = !commandId || !activeCommandId || commandId === activeCommandId;
+        const isPendingGeneration = !!pendingCommandId && commandId === pendingCommandId;
         if (!isActiveGeneration && !isPendingGeneration) {
             emitRemoteEvent('RemoteLiveStreamOpenIgnored', device, {
                 reason: 'stale-live-stream-generation',
@@ -3396,21 +3759,31 @@ export function createRemoteHub(options = {}) {
                 pendingCommandId,
                 transport
             });
-            return false;
-        }
-
-        const activatingPendingGeneration = isPendingGeneration && commandId !== activeCommandId;
-        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, streamState.mode || DEFAULT_REMOTE_FRAME_MODE);
-        const openedAt = safeString(message.openedAt, 80) || device.lastSeenAt || new Date().toISOString();
+            return false;
+        }
+
+        const activatingPendingGeneration = isPendingGeneration && commandId !== activeCommandId;
+        if (activatingPendingGeneration) {
+            const promoted = promotePendingLiveStream(device, streamState, message, transport);
+            if (!promoted) {
+                return false;
+            }
+            emitLiveStreamOpened(
+                device,
+                promoted.streamState,
+                promoted.transfer,
+                transport,
+                promoted.previousCommandId);
+            return true;
+        }
+
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, streamState.mode || DEFAULT_REMOTE_FRAME_MODE);
+        const openedAt = safeString(message.openedAt, 80) || device.lastSeenAt || new Date().toISOString();
         const nextStreamState = {
             ...streamState,
-            commandId: activatingPendingGeneration ? commandId : streamState.commandId,
-            pendingCommandId: activatingPendingGeneration ? '' : streamState.pendingCommandId,
-            pendingStartedAt: activatingPendingGeneration ? '' : streamState.pendingStartedAt,
-            pendingRestartToken: activatingPendingGeneration ? '' : streamState.pendingRestartToken,
-            open: true,
-            openedAt,
-            openTransport: transport,
+            open: true,
+            openedAt,
+            openTransport: transport,
             mode: transfer.mode,
             frameMode: transfer.frameMode,
             frameProfile: transfer.frameProfile,
@@ -3432,42 +3805,45 @@ export function createRemoteHub(options = {}) {
                 : Number(streamState.captureGeneration || 0),
             openedFrameSeq: Number.isFinite(Number(message.frameSeq)) ? Number(message.frameSeq) : Number(streamState.openedFrameSeq || 0)
         };
-        setDeviceLiveStream(device, nextStreamState);
-        emitRemoteEvent('RemoteLiveStreamOpened', device, {
-            streamId,
-            commandId: nextStreamState.commandId,
-            previousCommandId: activatingPendingGeneration ? activeCommandId : '',
-            handoff: activatingPendingGeneration,
-            mode: transfer.mode,
-            frameMode: transfer.frameMode,
-            frameProfile: transfer.frameProfile,
-            encoding: transfer.encoding,
-            compression: transfer.compression,
-            transport
-        });
-        return true;
-    }
+        setDeviceLiveStream(device, nextStreamState);
+        emitLiveStreamOpened(device, nextStreamState, transfer, transport);
+        return true;
+    }
 
     function applyLiveFrame(device, message, framePayload, transport = 'json-base64') {
         const frameData = Buffer.isBuffer(framePayload)
             ? ''
             : safeString(framePayload, MAX_STREAM_BASE64_CHARS + 1);
-        const frameSeq = Number(message.frameSeq);
-        const streamId = safeString(message.streamId, 128) || 'live';
-        const commandId = safeString(message.commandId, 128);
-        const streamState = getDeviceLiveStream(device, streamId);
-        if (!streamState?.active) {
+        const frameSeq = Number(message.frameSeq);
+        const streamId = safeString(message.streamId, 128) || 'live';
+        const commandId = safeString(message.commandId, 128);
+        let streamState = getDeviceLiveStream(device, streamId);
+        if (!streamState?.active) {
             device.counters.liveFramesDropped += 1;
             emitRemoteEvent('RemoteFrameDropped', device, {
                 reason: 'stale-live-stream-frame',
                 streamId,
                 frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
                 transport
-            });
-            return false;
-        }
-        const activeCommandId = safeString(streamState.commandId, 128);
-        const pendingCommandId = safeString(streamState.pendingCommandId, 128);
+            });
+            return false;
+        }
+        let activeCommandId = safeString(streamState.commandId, 128);
+        let pendingCommandId = safeString(getPendingLiveStreamDescriptor(streamState)?.commandId, 128);
+        if (pendingCommandId && commandId === pendingCommandId && commandId !== activeCommandId) {
+            const promoted = promotePendingLiveStream(device, streamState, message, `${transport}-implicit`);
+            if (promoted) {
+                streamState = promoted.streamState;
+                activeCommandId = safeString(streamState.commandId, 128);
+                pendingCommandId = '';
+                emitLiveStreamOpened(
+                    device,
+                    streamState,
+                    promoted.transfer,
+                    `${transport}-implicit`,
+                    promoted.previousCommandId);
+            }
+        }
         const isActiveGeneration = !commandId || !activeCommandId || commandId === activeCommandId;
         if (!isActiveGeneration) {
             device.counters.liveFramesDropped += 1;
@@ -3520,7 +3896,7 @@ export function createRemoteHub(options = {}) {
         const contentHash = buildFrameContentHash(message, payload);
         const sameContentStreak = computeSameContentStreak(streamState.latestFrame, contentHash);
         const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, streamState.mode || DEFAULT_REMOTE_FRAME_MODE);
-        if (streamState.open !== true) {
+        if (streamState.open !== true) {
             streamState.open = true;
             streamState.openedAt = device.lastSeenAt;
             streamState.openTransport = `${transport}-implicit`;
@@ -3532,15 +3908,20 @@ export function createRemoteHub(options = {}) {
             streamState.compression = transfer.compression;
             streamState.transferProtocol = transfer.transferProtocol;
             streamState.transferProtocolVersion = transfer.transferProtocolVersion;
-            streamState.handshake = transfer.handshake;
-        }
-        device.latestLiveFrame = {
-            streamId,
-            frameSeq,
+            streamState.handshake = transfer.handshake;
+        }
+        const currentGenerationVerified = (!activeCommandId || commandId === activeCommandId)
+            && (activeCaptureGeneration <= 0
+                || (frameCaptureGeneration > 0
+                    && frameCaptureGeneration === activeCaptureGeneration));
+        device.latestLiveFrame = {
+            streamId,
+            frameSeq,
             streamFrameSeq: Number.isFinite(Number(message.streamFrameSeq)) ? Number(message.streamFrameSeq) : frameSeq,
-            commandId,
+            commandId: commandId || activeCommandId,
             sessionId: device.sessionId,
             captureGeneration: activeCaptureGeneration || frameCaptureGeneration,
+            currentGenerationVerified,
             streamPurpose: safeString(message.streamPurpose || streamState.streamPurpose, 24) || 'wall',
             width: Number.isFinite(Number(message.width)) ? Number(message.width) : 0,
             height: Number.isFinite(Number(message.height)) ? Number(message.height) : 0,
@@ -3632,11 +4013,21 @@ export function createRemoteHub(options = {}) {
         streamState.sourceWidth = device.latestLiveFrame.sourceWidth;
         streamState.sourceHeight = device.latestLiveFrame.sourceHeight;
         streamState.monitorIndex = device.latestLiveFrame.monitorIndex;
-        streamState.monitorCount = device.latestLiveFrame.monitorCount;
-        ensureDeviceLiveStreams(device).set(streamId, streamState);
-        device.counters.liveFramesReceived += 1;
-        return true;
-    }
+        streamState.monitorCount = device.latestLiveFrame.monitorCount;
+        ensureDeviceLiveStreams(device).set(streamId, streamState);
+        device.counters.liveFramesReceived += 1;
+        if (streamState.framesReceived === 1 && liveStreamHasCurrentFrame(streamState)) {
+            emitRemoteEvent('RemoteLiveStreamReady', device, {
+                streamId,
+                commandId: streamState.commandId,
+                captureGeneration: Number(streamState.captureGeneration || 0),
+                streamPurpose: safeString(streamState.streamPurpose, 24) || 'wall',
+                monitorIndex: Number(streamState.monitorIndex || 0),
+                frameSeq
+            });
+        }
+        return true;
+    }
 
     function applyAudioFrame(device, message, framePayload, transport = 'json-base64') {
         const audioData = Buffer.isBuffer(framePayload)
@@ -4010,32 +4401,27 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        if (state.inputOnly) {
-            device.inputLastSeenAt = new Date().toISOString();
-            if (message.type === 'input.applied') {
-                emitEvent('RemoteInputApplied', {
-                    deviceId: device.deviceId,
-                    inputSeq: Number(message.inputSeq || 0) || 0,
-                    inputType: safeString(message.inputType, 48),
-                    issuedAtEpochMs: Number(message.issuedAtEpochMs || 0) || 0,
-                    hubReceivedAtEpochMs: Number(message.hubReceivedAtEpochMs || 0) || 0,
-                    hubForwardedAtEpochMs: Number(message.hubForwardedAtEpochMs || 0) || 0,
-                    agentApplyMs: Number(message.agentApplyMs || 0) || 0,
-                    hubAcknowledgedAtEpochMs: Date.now()
-                });
-            }
-            if (message.type === 'input.error') {
-                emitEvent('RemoteInputError', {
-                    deviceId: device.deviceId,
-                    inputSeq: Number(message.inputSeq || 0) || 0,
-                    inputType: safeString(message.inputType, 48),
-                    error: safeString(message.error, 600) || 'remote-input-failed',
-                    failedAtEpochMs: Number(message.failedAtEpochMs || 0) || 0,
-                    hubAcknowledgedAtEpochMs: Date.now()
-                });
-            }
-            return;
-        }
+        if (state.inputOnly) {
+            device.inputLastSeenAt = new Date().toISOString();
+            if (message.type === 'input.applied') {
+                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) {
             device.frameLastSeenAt = new Date().toISOString();
             return;
@@ -4067,15 +4453,19 @@ export function createRemoteHub(options = {}) {
                 device.counters.statusReceived += 1;
                 emitRemoteEvent('RemoteDeviceStatus', device);
                 break;
-            case 'command.result':
-                device.counters.commandResultsReceived += 1;
-                {
-                    const commandId = safeString(message.commandId, 128);
-                    const error = safeString(message.error, 500);
-                    const result = message.result ?? null;
-                    if (error || result?.ok === false || result?.status === 'failed') {
-                        failPendingLiveStream(device, commandId, error || result?.error || 'stream-start-failed');
-                    }
+            case 'command.result':
+            case 'command.error':
+                device.counters.commandResultsReceived += 1;
+                {
+                    const commandId = safeString(message.commandId, 128);
+                    const error = safeString(
+                        message.error || (message.type === 'command.error' ? 'command-failed' : ''),
+                        500);
+                    const result = message.result ?? null;
+                    handleInputFallbackCommandResult(device, message);
+                    if (error || result?.ok === false || result?.status === 'failed') {
+                        failPendingLiveStream(device, commandId, error || result?.error || 'stream-start-failed');
+                    }
                     const task = applyTaskResult(device, commandId, result, error);
                     if (task) {
                         emitRemoteEvent('RemoteTaskResult', device, {
@@ -4090,8 +4480,12 @@ export function createRemoteHub(options = {}) {
                     commandId: safeString(message.commandId, 128),
                     result: message.result ?? null,
                     error: safeString(message.error, 500)
-                });
-                break;
+                });
+                break;
+            case 'input.applied':
+            case 'input.error':
+                handleRemoteInputOutcome(device, message, 'main');
+                break;
             case 'thumbnail.frame': {
                 applyThumbnailFrame(device, message, message.data, 'json-base64');
                 break;
@@ -4512,9 +4906,10 @@ export function createRemoteHub(options = {}) {
     }
 
     async function close() {
-        for (const device of devices.values()) {
-            failAllPendingTasks(device, 'hub-shutdown');
-            if (device.socket && !device.socket.destroyed) {
+        for (const device of devices.values()) {
+            failAllPendingTasks(device, 'hub-shutdown');
+            failAllPendingInputFallbacks(device, 'hub-shutdown');
+            if (device.socket && !device.socket.destroyed) {
                 writeJsonLine(device.socket, { type: 'disconnect', reason: 'hub-shutdown' });
                 device.socket.destroy();
             }
@@ -4565,9 +4960,10 @@ export function createRemoteHub(options = {}) {
             device.connected = false;
             device.disconnectedAt = new Date().toISOString();
             device.lastDisconnectReason = reason;
-            deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
-            failAllPendingTasks(device, 'device-disconnected');
-            emitRemoteEvent('RemoteDeviceDisconnected', device, { reason, synthetic: true });
+            deactivateDeviceLiveStreams(device, reason, device.disconnectedAt);
+            failAllPendingTasks(device, 'device-disconnected');
+            failAllPendingInputFallbacks(device, 'device-disconnected');
+            emitRemoteEvent('RemoteDeviceDisconnected', device, { reason, synthetic: true });
             return true;
         }
 
@@ -4693,13 +5089,15 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'device-not-connected' };
         }
 
-        const denied = policyError(device, 'allowControl');
-        if (denied) return { ok: false, error: denied };
-
+        const denied = policyError(device, 'allowControl');
+        if (denied) return { ok: false, error: denied };
+
+        if (device.capabilities?.controlPermission === false
+            || device.capabilities?.accessibilityPermission === false) {
+            return { ok: false, error: 'INPUT_PERMISSION_DENIED' };
+        }
         if (!readCapabilityFlag(device.capabilities, 'control')) {
-            const permissionMissing = device.capabilities?.controlPermission === false
-                || device.capabilities?.accessibilityPermission === false;
-            return { ok: false, error: permissionMissing ? 'INPUT_PERMISSION_DENIED' : 'device-input-control-unavailable' };
+            return { ok: false, error: 'device-input-control-unavailable' };
         }
 
         const normalized = normalizeRemoteInputEvent(input);
@@ -4708,11 +5106,14 @@ export function createRemoteHub(options = {}) {
         }
         const controlStream = getActiveControlStream(device);
         if (!controlStream
-            || controlStream.open !== true
+            || !liveStreamHasCurrentFrame(controlStream)
             || !safeString(controlStream.commandId, 128)
             || Number(controlStream.captureGeneration || 0) <= 0) {
             return { ok: false, error: 'CONTROL_NOT_READY' };
         }
+        if (getPendingLiveStreamDescriptor(controlStream)) {
+            return { ok: false, error: 'CAPTURE_TRANSITION_IN_PROGRESS' };
+        }
         if (!normalized.controlSessionId
             || normalized.controlSessionId !== safeString(device.sessionId, 160)) {
             return {
@@ -4762,7 +5163,43 @@ export function createRemoteHub(options = {}) {
             detachInputSocket(inputSocket, 'input-socket-write-failed');
         }
 
-        return { ok: false, error: 'CONTROL_NOT_READY', detail: 'input-channel-not-connected' };
+        const hubForwardedAtEpochMs = Date.now();
+        const fallback = sendCommand(deviceId, {
+            command: 'input.control',
+            payload: {
+                ...normalized,
+                hubForwardedAtEpochMs,
+                issuedAt: normalized.issuedAt || new Date().toISOString()
+            }
+        });
+        if (fallback.ok && normalized.requestAck && normalized.inputSeq > 0) {
+            schedulePendingInputFallback(device, {
+                commandId: fallback.commandId,
+                inputSeq: normalized.inputSeq,
+                inputType: normalized.type,
+                issuedAtEpochMs: normalized.issuedAtEpochMs,
+                hubReceivedAtEpochMs: normalized.hubReceivedAtEpochMs,
+                hubForwardedAtEpochMs,
+                fallback: true,
+                timeoutTimer: null
+            });
+        }
+        return fallback.ok
+            ? {
+                ...fallback,
+                inputSocket: false,
+                fallback: true,
+                sessionId: device.sessionId,
+                deliveryCommandId: fallback.commandId,
+                commandId: controlStream.commandId,
+                captureGeneration: controlStream.captureGeneration,
+                inputSeq: normalized.inputSeq
+            }
+            : {
+                ...fallback,
+                error: fallback.error || 'CONTROL_NOT_READY',
+                detail: 'input-channel-not-connected'
+            };
     }
 
     function notifyAgentProgress(deviceIds, progress = {}) {
@@ -5075,31 +5512,100 @@ export function createRemoteHub(options = {}) {
             || (device?.activeLiveStream?.streamId === id ? device.activeLiveStream : null);
     }
 
-    function setDeviceLiveStream(device, stream) {
-        if (!device || !stream?.streamId) {
-            return stream;
-        }
-        ensureDeviceLiveStreams(device).set(stream.streamId, stream);
-        device.activeLiveStream = stream;
-        return stream;
-    }
-
-    function failPendingLiveStream(device, commandId, error = 'stream-start-failed') {
-        const key = safeString(commandId, 128);
-        if (!device || !key) {
-            return false;
-        }
-        const streams = ensureDeviceLiveStreams(device);
-        for (const stream of streams.values()) {
-            if (safeString(stream?.pendingCommandId, 128) !== key) {
-                continue;
-            }
-            stream.pendingCommandId = '';
-            stream.pendingStartedAt = '';
-            stream.pendingRestartToken = '';
-            emitRemoteEvent('RemoteLiveStreamRestartFailed', device, {
-                streamId: stream.streamId,
-                commandId: key,
+    function setDeviceLiveStream(device, stream) {
+        if (!device || !stream?.streamId) {
+            return stream;
+        }
+        ensureDeviceLiveStreams(device).set(stream.streamId, stream);
+        device.activeLiveStream = stream;
+        return stream;
+    }
+
+    function ensureLiveStreamReplacementTimers(device) {
+        if (!(device?.liveStreamReplacementTimers instanceof Map)) {
+            Object.defineProperty(device, 'liveStreamReplacementTimers', {
+                value: new Map(),
+                enumerable: false,
+                configurable: true,
+                writable: true
+            });
+        }
+        return device.liveStreamReplacementTimers;
+    }
+
+    function getPendingLiveStreamDescriptor(stream) {
+        return stream?.pendingDescriptor && typeof stream.pendingDescriptor === 'object'
+            ? stream.pendingDescriptor
+            : null;
+    }
+
+    function setPendingLiveStreamDescriptor(stream, descriptor) {
+        const pending = descriptor && typeof descriptor === 'object'
+            ? { ...descriptor }
+            : null;
+        stream.pendingDescriptor = pending;
+        // Keep the scalar fields for older status consumers while the
+        // descriptor remains the canonical pending-generation state.
+        stream.pendingCommandId = safeString(pending?.commandId, 128);
+        stream.pendingCaptureGeneration = Number(pending?.captureGeneration || 0);
+        stream.pendingStartedAt = safeString(pending?.startedAt, 80);
+        stream.pendingRestartToken = safeString(pending?.restartToken, 128);
+        return pending;
+    }
+
+    function clearLiveStreamReplacementTimer(device, streamId) {
+        const timers = ensureLiveStreamReplacementTimers(device);
+        const key = safeString(streamId, 128);
+        const timer = timers.get(key);
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timers.delete(key);
+    }
+
+    function clearPendingLiveStreamDescriptor(device, stream) {
+        if (!stream) {
+            return null;
+        }
+        const pending = getPendingLiveStreamDescriptor(stream);
+        clearLiveStreamReplacementTimer(device, stream.streamId);
+        setPendingLiveStreamDescriptor(stream, null);
+        return pending;
+    }
+
+    function scheduleLiveStreamReplacementTimeout(device, stream) {
+        const pending = getPendingLiveStreamDescriptor(stream);
+        if (!pending?.commandId) {
+            clearLiveStreamReplacementTimer(device, stream?.streamId);
+            return;
+        }
+        clearLiveStreamReplacementTimer(device, stream.streamId);
+        const timer = setTimeout(() => {
+            const current = getDeviceLiveStream(device, stream.streamId);
+            const currentPending = getPendingLiveStreamDescriptor(current);
+            if (currentPending?.commandId === pending.commandId) {
+                failPendingLiveStream(device, pending.commandId, 'stream-start-timeout');
+            }
+        }, LIVE_STREAM_REPLACEMENT_PENDING_MS);
+        timer.unref?.();
+        ensureLiveStreamReplacementTimers(device).set(stream.streamId, timer);
+    }
+
+    function failPendingLiveStream(device, commandId, error = 'stream-start-failed') {
+        const key = safeString(commandId, 128);
+        if (!device || !key) {
+            return false;
+        }
+        const streams = ensureDeviceLiveStreams(device);
+        for (const stream of streams.values()) {
+            const pending = getPendingLiveStreamDescriptor(stream);
+            if (safeString(pending?.commandId, 128) !== key) {
+                continue;
+            }
+            clearPendingLiveStreamDescriptor(device, stream);
+            emitRemoteEvent('RemoteLiveStreamRestartFailed', device, {
+                streamId: stream.streamId,
+                commandId: key,
                 error: safeString(error, 500) || 'stream-start-failed'
             });
             return true;
@@ -5107,12 +5613,13 @@ export function createRemoteHub(options = {}) {
         return false;
     }
 
-    function deactivateDeviceLiveStreams(device, reason, stoppedAt = new Date().toISOString()) {
-        const streams = ensureDeviceLiveStreams(device);
-        for (const stream of streams.values()) {
-            stream.active = false;
-            stream.stoppedAt = stoppedAt;
-            stream.stopReason = reason;
+    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.stoppedAt = stoppedAt;
+            stream.stopReason = reason;
         }
         if (device?.activeLiveStream) {
             device.activeLiveStream.active = false;
@@ -5139,59 +5646,6 @@ export function createRemoteHub(options = {}) {
             safeString(stream?.streamPurpose, 24).toLowerCase() === 'control') || null;
     }
 
-    function stopCompetingMacCaptureStreams(deviceId, device, nextStreamId, nextPurpose) {
-        if (normalizeLivePlatform(device?.platform) !== 'macos') {
-            return { ok: true, stopped: [] };
-        }
-
-        const activeControl = getActiveControlStream(device);
-        if (nextPurpose !== 'control'
-            && activeControl
-            && activeControl.streamId !== nextStreamId) {
-            return {
-                ok: true,
-                suppressed: true,
-                reason: 'CONTROL_CAPTURE_OWNS_DEVICE',
-                ownerStreamId: activeControl.streamId,
-                ownerCommandId: activeControl.commandId,
-                captureGeneration: Number(activeControl.captureGeneration || 0)
-            };
-        }
-
-        const stopped = [];
-        for (const stream of getActiveLiveStreams(device)) {
-            if (!stream?.streamId || stream.streamId === nextStreamId) {
-                continue;
-            }
-            const stopCommandId = crypto.randomUUID();
-            const result = sendCommand(deviceId, {
-                command: 'stream.stop',
-                commandId: stopCommandId,
-                payload: {
-                    streamId: stream.streamId,
-                    requestedAt: new Date().toISOString(),
-                    reason: `mac-capture-owner-transition:${nextPurpose}`
-                }
-            });
-            if (!result.ok) {
-                return {
-                    ok: false,
-                    error: 'CAPTURE_TRANSITION_IN_PROGRESS',
-                    streamId: stream.streamId,
-                    detail: result.error || 'stream-stop-dispatch-failed'
-                };
-            }
-            stream.active = false;
-            stream.pendingCommandId = '';
-            stream.pendingStartedAt = '';
-            stream.pendingRestartToken = '';
-            stream.stoppedAt = new Date().toISOString();
-            stream.stopReason = `mac-capture-owner-transition:${nextPurpose}`;
-            stopped.push({ streamId: stream.streamId, commandId: stopCommandId });
-        }
-        return { ok: true, stopped };
-    }
-
     function nextCaptureGeneration(device) {
         const current = Number(device?.captureGenerationCounter || 0);
         const next = Number.isSafeInteger(current) && current > 0 ? current + 1 : 1;
@@ -5208,18 +5662,17 @@ export function createRemoteHub(options = {}) {
     }
 
     function normalizeLiveStreamStartOptions(options = {}) {
-        const transfer = buildRemoteFrameTransferDescriptor(options.mode || options.frameMode || DEFAULT_REMOTE_FRAME_MODE);
-        const streamPurpose = safeString(options.streamPurpose || options.purpose || 'wall', 24) || 'wall';
-        const platform = normalizeLivePlatform(options.platform);
-        const macWallProfile = platform === 'macos' && streamPurpose !== 'control';
-        const maxFps = streamPurpose === 'control' ? 60 : macWallProfile ? 8 : 30;
-        const defaultFps = macWallProfile && options.fps === undefined ? 4 : 8;
-        const maxWidth = clampNumber(options.maxWidth, 320, macWallProfile ? 432 : 3840, macWallProfile ? 432 : 640);
-        const maxHeight = clampNumber(options.maxHeight, 180, macWallProfile ? 243 : 2160, macWallProfile ? 243 : 360);
-        const fps = clampNumber(options.fps, 1, maxFps, defaultFps);
-        const quality = clampNumber(options.quality, 20, 95, 45);
-        const monitorIndex = normalizeMonitorIndex(options.monitorIndex ?? options.screenIndex ?? options.displayIndex);
-        return { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose, platform, macWallProfile };
+        const transfer = buildRemoteFrameTransferDescriptor(options.mode || options.frameMode || DEFAULT_REMOTE_FRAME_MODE);
+        const streamPurpose = safeString(options.streamPurpose || options.purpose || 'wall', 24) || 'wall';
+        const platform = normalizeLivePlatform(options.platform);
+        const maxFps = streamPurpose === 'control' ? 60 : 30;
+        const defaultFps = 8;
+        const maxWidth = clampNumber(options.maxWidth, 320, 3840, 640);
+        const maxHeight = clampNumber(options.maxHeight, 180, 2160, 360);
+        const fps = clampNumber(options.fps, 1, maxFps, defaultFps);
+        const quality = clampNumber(options.quality, 20, 95, 45);
+        const monitorIndex = normalizeMonitorIndex(options.monitorIndex ?? options.screenIndex ?? options.displayIndex);
+        return { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose, platform };
     }
 
     function liveStreamStartStillPending(activeLiveStream) {
@@ -5230,13 +5683,35 @@ export function createRemoteHub(options = {}) {
         return Number.isFinite(startedAt) && Date.now() - startedAt < LIVE_STREAM_PENDING_REUSE_MS;
     }
 
-    function liveStreamReplacementStillPending(activeLiveStream) {
-        if (!activeLiveStream?.active || !safeString(activeLiveStream.pendingCommandId, 128)) {
-            return false;
-        }
-        const startedAt = Date.parse(activeLiveStream.pendingStartedAt || '');
-        return Number.isFinite(startedAt) && Date.now() - startedAt < LIVE_STREAM_REPLACEMENT_PENDING_MS;
-    }
+    function liveStreamReplacementStillPending(activeLiveStream) {
+        const pending = getPendingLiveStreamDescriptor(activeLiveStream);
+        if (!activeLiveStream?.active || !safeString(pending?.commandId, 128)) {
+            return false;
+        }
+        const startedAt = Date.parse(pending.startedAt || '');
+        return Number.isFinite(startedAt) && Date.now() - startedAt < LIVE_STREAM_REPLACEMENT_PENDING_MS;
+    }
+
+    function liveStreamHasCurrentFrame(activeLiveStream) {
+        if (!activeLiveStream?.active
+            || activeLiveStream.open !== true
+            || Number(activeLiveStream.framesReceived || 0) < 1) {
+            return false;
+        }
+        const latestFrame = activeLiveStream.latestFrame;
+        if (!latestFrame || latestFrame.currentGenerationVerified !== true) {
+            return false;
+        }
+        const activeCommandId = safeString(activeLiveStream.commandId, 128);
+        const frameCommandId = safeString(latestFrame.commandId, 128);
+        if (activeCommandId && frameCommandId !== activeCommandId) {
+            return false;
+        }
+        const activeCaptureGeneration = Number(activeLiveStream.captureGeneration || 0);
+        const frameCaptureGeneration = Number(latestFrame.captureGeneration || 0);
+        return activeCaptureGeneration <= 0
+            || (frameCaptureGeneration > 0 && frameCaptureGeneration === activeCaptureGeneration);
+    }
 
     function getLiveStreamFreshWindowMs(activeLiveStream) {
         const fps = Number(activeLiveStream?.fps || 0);
@@ -5296,17 +5771,20 @@ export function createRemoteHub(options = {}) {
             const activeLiveStream = getDeviceLiveStream(device, streamId);
             const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
             if (activeLiveStream
-                && liveStreamMatchesOptions(activeLiveStream, normalized)
-                && (activeLiveStream.open === true || liveStreamStartStillPending(activeLiveStream))) {
-                return {
-                    ok: true,
-                    commandId: activeLiveStream.commandId,
-                    streamId,
-                    fps,
+                && liveStreamMatchesOptions(activeLiveStream, normalized)
+                && (activeLiveStream.open === true || liveStreamStartStillPending(activeLiveStream))) {
+                return {
+                    ok: true,
+                    commandId: activeLiveStream.commandId,
+                    sessionId: device.sessionId,
+                    streamId,
+                    streamPurpose,
+                    fps,
                     mode: transfer.mode,
-                    frameMode: transfer.frameMode,
+                    frameMode: transfer.frameMode,
                     monitorIndex,
                     captureGeneration: Number(activeLiveStream.captureGeneration || 0),
+                    ready: liveStreamHasCurrentFrame(activeLiveStream),
                     synthetic: true,
                     reused: true
                 };
@@ -5359,7 +5837,20 @@ export function createRemoteHub(options = {}) {
                 mode: transfer.mode,
                 synthetic: true
             });
-            return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode, monitorIndex, captureGeneration, synthetic: true };
+            return {
+                ok: true,
+                commandId,
+                sessionId: device.sessionId,
+                streamId,
+                streamPurpose,
+                fps,
+                mode: transfer.mode,
+                frameMode: transfer.frameMode,
+                monitorIndex,
+                captureGeneration,
+                ready: true,
+                synthetic: true
+            };
         }
 
         if (!device?.socket || device.socket.destroyed || !device.connected) {
@@ -5374,70 +5865,57 @@ export function createRemoteHub(options = {}) {
         const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
         const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
         const activeLiveStream = getDeviceLiveStream(device, streamId);
-        const macTransition = stopCompetingMacCaptureStreams(deviceId, device, streamId, streamPurpose);
-        if (!macTransition.ok) {
-            return macTransition;
-        }
-        if (macTransition.suppressed) {
-            emitRemoteEvent('RemoteLiveStreamStartSuppressed', device, {
-                streamId,
-                streamPurpose,
-                reason: macTransition.reason,
-                ownerStreamId: macTransition.ownerStreamId,
-                ownerCommandId: macTransition.ownerCommandId,
-                captureGeneration: macTransition.captureGeneration
-            });
-            return {
-                ok: true,
-                suppressed: true,
-                streamId,
-                streamPurpose,
-                reason: macTransition.reason,
-                ownerStreamId: macTransition.ownerStreamId,
-                ownerCommandId: macTransition.ownerCommandId,
-                captureGeneration: macTransition.captureGeneration
-            };
-        }
-        if (activeLiveStream?.pendingCommandId) {
-            if (liveStreamReplacementStillPending(activeLiveStream)) {
-                emitRemoteEvent('RemoteLiveStreamRestartPending', device, {
-                    streamId,
-                    commandId: activeLiveStream.pendingCommandId,
-                    activeCommandId: activeLiveStream.commandId,
-                    reason: safeString(options.restartReason || 'duplicate-restart', 128)
-                });
-                return {
-                    ok: true,
-                    commandId: activeLiveStream.pendingCommandId,
-                    streamId,
-                    fps: Number(activeLiveStream.fps || fps),
-                    mode: activeLiveStream.mode || transfer.mode,
-                    frameMode: activeLiveStream.frameMode || transfer.frameMode,
-                    monitorIndex: Number(activeLiveStream.monitorIndex || monitorIndex),
-                    captureGeneration: Number(activeLiveStream.captureGeneration || 0),
+        const pendingDescriptor = getPendingLiveStreamDescriptor(activeLiveStream);
+        if (pendingDescriptor?.commandId) {
+            const pendingMatchesRequest = liveStreamMatchesOptions(pendingDescriptor, normalized);
+            if (pendingMatchesRequest && liveStreamReplacementStillPending(activeLiveStream)) {
+                emitRemoteEvent('RemoteLiveStreamRestartPending', device, {
+                    streamId,
+                    commandId: pendingDescriptor.commandId,
+                    activeCommandId: activeLiveStream.commandId,
+                    reason: safeString(options.restartReason || 'duplicate-restart', 128)
+                });
+                return {
+                    ok: true,
+                    commandId: pendingDescriptor.commandId,
+                    sessionId: device.sessionId,
+                    streamId,
+                    streamPurpose: safeString(pendingDescriptor.streamPurpose, 24) || streamPurpose,
+                    fps: Number(pendingDescriptor.fps || fps),
+                    mode: pendingDescriptor.mode || transfer.mode,
+                    frameMode: pendingDescriptor.frameMode || transfer.frameMode,
+                    monitorIndex: Number(pendingDescriptor.monitorIndex ?? monitorIndex),
+                    captureGeneration: Number(pendingDescriptor.captureGeneration || 0),
+                    ready: false,
                     pending: true,
                     reused: true
                 };
-            }
-            activeLiveStream.pendingCommandId = '';
-            activeLiveStream.pendingStartedAt = '';
-            activeLiveStream.pendingRestartToken = '';
-        }
+            }
+            failPendingLiveStream(
+                device,
+                pendingDescriptor.commandId,
+                liveStreamReplacementStillPending(activeLiveStream)
+                    ? 'stream-restart-superseded'
+                    : 'stream-start-timeout');
+        }
         const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
         if (activeLiveStream
             && options.forceRestart !== true
             && options.reuseExisting === true
             && liveStreamMatchesOptions(activeLiveStream, normalized)
             && liveStreamIsReusable(activeLiveStream)) {
-            return {
-                ok: true,
-                commandId: activeLiveStream.commandId,
-                streamId,
+            return {
+                ok: true,
+                commandId: activeLiveStream.commandId,
+                sessionId: device.sessionId,
+                streamId,
+                streamPurpose,
                 fps: Number(activeLiveStream.fps || fps),
                 mode: activeLiveStream.mode || transfer.mode,
                 frameMode: activeLiveStream.frameMode || transfer.frameMode,
                 monitorIndex: Number(activeLiveStream.monitorIndex || monitorIndex),
                 captureGeneration: Number(activeLiveStream.captureGeneration || 0),
+                ready: liveStreamHasCurrentFrame(activeLiveStream),
                 reused: true
             };
         }
@@ -5454,15 +5932,18 @@ export function createRemoteHub(options = {}) {
                     monitorIndex
                 });
             }
-            return {
-                ok: true,
-                commandId: activeLiveStream.commandId,
-                streamId,
+            return {
+                ok: true,
+                commandId: activeLiveStream.commandId,
+                sessionId: device.sessionId,
+                streamId,
+                streamPurpose,
                 fps,
                 mode: transfer.mode,
                 frameMode: transfer.frameMode,
                 monitorIndex,
                 captureGeneration: Number(activeLiveStream.captureGeneration || 0),
+                ready: liveStreamHasCurrentFrame(activeLiveStream),
                 reused: true
             };
         }
@@ -5522,24 +6003,20 @@ export function createRemoteHub(options = {}) {
             return result;
         }
 
-        const previousCommandId = safeString(activeLiveStream?.commandId, 128);
-        const replacingActiveStream = activeLiveStream?.active === true
-            && !!previousCommandId
-            && previousCommandId !== commandId;
-        setDeviceLiveStream(device, {
-            ...(activeLiveStream || {}),
-            streamId,
-            commandId: replacingActiveStream ? previousCommandId : commandId,
-            pendingCommandId: replacingActiveStream ? commandId : '',
-            pendingStartedAt: replacingActiveStream ? now : '',
-            pendingRestartToken: replacingActiveStream ? safeString(options.restartToken, 128) : '',
-            active: true,
-            open: replacingActiveStream ? activeLiveStream.open === true : false,
-            openedAt: replacingActiveStream ? activeLiveStream.openedAt || '' : '',
-            openTransport: replacingActiveStream ? activeLiveStream.openTransport || '' : '',
-            mode: transfer.mode,
-            frameMode: transfer.frameMode,
-            frameProfile: transfer.frameProfile,
+        const previousCommandId = safeString(activeLiveStream?.commandId, 128);
+        const replacingActiveStream = activeLiveStream?.active === true
+            && !!previousCommandId
+            && previousCommandId !== commandId;
+        const nextDescriptor = {
+            streamId,
+            commandId,
+            active: true,
+            open: false,
+            openedAt: '',
+            openTransport: '',
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
             encoding: transfer.encoding,
             codec: transfer.codec,
             compression: transfer.compression,
@@ -5550,17 +6027,32 @@ export function createRemoteHub(options = {}) {
             maxWidth,
             maxHeight,
             quality,
-            monitorIndex,
-            monitorCount: 1,
-            startedAt: replacingActiveStream ? activeLiveStream.startedAt || now : now,
-            stoppedAt: '',
-            stopReason: '',
-            lastFrameAt: '',
+            monitorIndex,
+            monitorCount: 1,
+            startedAt: now,
+            restartToken: safeString(options.restartToken, 128),
+            stoppedAt: '',
+            stopReason: '',
+            lastFrameAt: '',
             lastFrameSeq: 0,
             framesReceived: 0,
             streamPurpose,
-            captureGeneration
-        });
+            captureGeneration,
+            latestFrame: null,
+            width: 0,
+            height: 0,
+            sourceWidth: 0,
+            sourceHeight: 0
+        };
+        if (replacingActiveStream) {
+            setPendingLiveStreamDescriptor(activeLiveStream, nextDescriptor);
+            scheduleLiveStreamReplacementTimeout(device, activeLiveStream);
+            setDeviceLiveStream(device, activeLiveStream);
+        } else {
+            const nextStreamState = { ...nextDescriptor };
+            setPendingLiveStreamDescriptor(nextStreamState, null);
+            setDeviceLiveStream(device, nextStreamState);
+        }
         device.counters.liveStreamsStarted += 1;
         emitRemoteEvent('RemoteLiveStreamStarted', device, {
             streamId,
@@ -5573,7 +6065,19 @@ export function createRemoteHub(options = {}) {
             monitorIndex
         });
 
-        return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode, monitorIndex, captureGeneration };
+        return {
+            ok: true,
+            commandId,
+            sessionId: device.sessionId,
+            streamId,
+            streamPurpose,
+            fps,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            monitorIndex,
+            captureGeneration,
+            ready: false
+        };
     }
 
     function stopLiveStream(deviceId, options = {}) {
@@ -5583,24 +6087,25 @@ export function createRemoteHub(options = {}) {
         const purposeStreamId = streamPurpose ? makeStableLiveStreamId(deviceId, streamPurpose) : '';
         const streamId = requestedStreamId || purposeStreamId || device?.activeLiveStream?.streamId || '';
         const streamState = getDeviceLiveStream(device, streamId);
-        if (streamState && streamState.active !== true) {
-            return {
+        if (streamState && streamState.active !== true) {
+            clearPendingLiveStreamDescriptor(device, streamState);
+            return {
                 ok: true,
                 commandId: safeString(options.commandId, 128),
                 streamId,
-                alreadyStopped: true
-            };
-        }
-        if (device?.synthetic === true && device.connected) {
-            const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
-            device.counters.commandsSent += 1;
-            if (streamState) {
-                streamState.active = false;
-                streamState.pendingCommandId = '';
-                streamState.pendingStartedAt = '';
-                streamState.pendingRestartToken = '';
-                streamState.stoppedAt = new Date().toISOString();
-                streamState.stopReason = 'manager-request';
+                alreadyStopped: true
+            };
+        }
+        if (streamState) {
+            clearPendingLiveStreamDescriptor(device, streamState);
+        }
+        if (device?.synthetic === true && device.connected) {
+            const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+            device.counters.commandsSent += 1;
+            if (streamState) {
+                streamState.active = false;
+                streamState.stoppedAt = new Date().toISOString();
+                streamState.stopReason = 'manager-request';
             }
             device.counters.liveStreamsStopped += 1;
             emitRemoteEvent('RemoteLiveStreamStopped', device, {
@@ -5628,14 +6133,11 @@ export function createRemoteHub(options = {}) {
         if (!result.ok) {
             return result;
         }
-
-        if (streamState) {
-            streamState.active = false;
-            streamState.pendingCommandId = '';
-            streamState.pendingStartedAt = '';
-            streamState.pendingRestartToken = '';
-            streamState.stoppedAt = new Date().toISOString();
-            streamState.stopReason = 'manager-request';
+
+        if (streamState) {
+            streamState.active = false;
+            streamState.stoppedAt = new Date().toISOString();
+            streamState.stopReason = 'manager-request';
         }
         device.counters.liveStreamsStopped += 1;
         emitRemoteEvent('RemoteLiveStreamStopped', device, {