@livedesk/hub 0.1.5 → 0.1.7

package/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';
@@ -58,14 +59,14 @@ const REMOTE_FRAME_MODE_PROFILES = Object.freeze({
         modeVersion: 1,
         implemented: true
     }),
-    'mode2-lzo': Object.freeze({
-        mode: 'mode2-lzo',
-        label: 'Mode 2 - RGB565 LZO Wall',
+    'mode2-lzo': Object.freeze({
+        mode: 'mode2-lzo',
+        label: 'Internal Atlas Input - RGB565 LZO',
         transport: 'ws-binary',
         encoding: 'image-raw',
         codec: 'rgb565',
         compression: 'lzo1x',
-        profile: 'mode2-lzo-rgb565-v1',
+        profile: 'atlas-input-rgb565-lzo-v1',
         modeVersion: 2,
         implemented: true
     }),
@@ -151,7 +152,7 @@ const DEFAULT_PUBLIC_IP_TIMEOUT_MS = 1800;
 const DUPLICATE_DEVICE_ACTIVE_REJECT_MS = 15000;
 const DUPLICATE_DEVICE_LOG_THROTTLE_MS = 60000;
 const DUPLICATE_DEVICE_RETRY_AFTER_MS = 30000;
-const AGENT_BINARY_INGRESS_QUEUE_PACKETS = 256;
+const AGENT_BINARY_INGRESS_QUEUE_PACKETS = 8;
 const MODE5_AGENT_BINARY_INGRESS_QUEUE_PACKETS = 2;
 const AGENT_BINARY_INGRESS_DRAIN_BUDGET_PACKETS = 64;
 const SYNTHETIC_FRAME_DATA_URL = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC';
@@ -320,7 +321,7 @@ function isWildcardHost(value) {
         || host === '';
 }
 
-function isPrivateIPv4(value) {
+function isPrivateIPv4(value) {
     const parts = String(value || '').split('.').map(part => Number(part));
     if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) {
         return false;
@@ -329,9 +330,71 @@ function isPrivateIPv4(value) {
     return parts[0] === 10
         || (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
         || (parts[0] === 192 && parts[1] === 168);
-}
-
-function isPublicIPv4(value) {
+}
+
+function isPrivateNetworkAddress(value) {
+    const address = String(value || '').replace(/^::ffff:/i, '').trim().toLowerCase();
+    return isLoopbackHost(address)
+        || isPrivateIPv4(address)
+        || address.startsWith('fe80:')
+        || address.startsWith('fc')
+        || address.startsWith('fd');
+}
+
+function readCpuTimes() {
+    let idle = 0;
+    let total = 0;
+    for (const cpu of os.cpus()) {
+        const times = Object.values(cpu.times || {}).map(Number);
+        idle += Number(cpu.times?.idle || 0);
+        total += times.reduce((sum, value) => sum + (Number.isFinite(value) ? value : 0), 0);
+    }
+    return { idle, total };
+}
+
+function createHubRuntimeDiagnosticsSampler() {
+    let previousCpu = readCpuTimes();
+    let previousProcessCpu = process.cpuUsage();
+    let previousAt = Date.now();
+    return () => {
+        const now = Date.now();
+        const cpu = readCpuTimes();
+        const processCpu = process.cpuUsage();
+        const elapsedMs = Math.max(1, now - previousAt);
+        const totalDelta = Math.max(0, cpu.total - previousCpu.total);
+        const idleDelta = Math.max(0, cpu.idle - previousCpu.idle);
+        const processMicros = Math.max(
+            0,
+            processCpu.user - previousProcessCpu.user + processCpu.system - previousProcessCpu.system
+        );
+        const cpuLogicalCores = Math.max(1, os.cpus().length || 1);
+        const totalMemoryBytes = Math.max(0, Number(os.totalmem() || 0));
+        const freeMemoryBytes = Math.max(0, Number(os.freemem() || 0));
+        const snapshot = {
+            collectedAt: new Date(now).toISOString(),
+            system: {
+                cpuLogicalCores,
+                cpuUsageRatio: totalDelta > 0
+                    ? Math.max(0, Math.min(1, 1 - idleDelta / totalDelta))
+                    : null,
+                processCpuRatio: Math.max(0, Math.min(1, processMicros / (elapsedMs * 1000 * cpuLogicalCores))),
+                totalMemoryBytes,
+                freeMemoryBytes,
+                memoryUsedRatio: totalMemoryBytes > 0
+                    ? Math.max(0, Math.min(1, (totalMemoryBytes - freeMemoryBytes) / totalMemoryBytes))
+                    : null,
+                processMemoryBytes: Math.max(0, Number(process.memoryUsage().rss || 0)),
+                uptimeSeconds: Math.max(0, Number(os.uptime() || 0))
+            }
+        };
+        previousCpu = cpu;
+        previousProcessCpu = processCpu;
+        previousAt = now;
+        return snapshot;
+    };
+}
+
+function isPublicIPv4(value) {
     const parts = String(value || '').split('.').map(part => Number(part));
     if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) {
         return false;
@@ -617,11 +680,12 @@ function normalizeRemoteInputEvent(value = {}) {
     const location = Number(input.location ?? input.Location);
     const monitorIndex = Number(input.monitorIndex ?? input.MonitorIndex ?? input.screenIndex ?? input.ScreenIndex ?? input.displayIndex ?? input.DisplayIndex);
     const inputSeq = Number(input.inputSeq ?? input.InputSeq);
-    const issuedAtEpochMs = Number(input.issuedAtEpochMs ?? input.IssuedAtEpochMs);
-    const hubReceivedAtEpochMs = Number(input.hubReceivedAtEpochMs ?? input.HubReceivedAtEpochMs);
-    return {
-        type,
-        monitorIndex: Number.isFinite(monitorIndex) ? normalizeMonitorIndex(monitorIndex) : 0,
+    const issuedAtEpochMs = Number(input.issuedAtEpochMs ?? input.IssuedAtEpochMs);
+    const hubReceivedAtEpochMs = Number(input.hubReceivedAtEpochMs ?? input.HubReceivedAtEpochMs);
+    const captureGeneration = Number(input.captureGeneration ?? input.CaptureGeneration);
+    return {
+        type,
+        monitorIndex: Number.isFinite(monitorIndex) ? normalizeMonitorIndex(monitorIndex) : 0,
         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),
@@ -636,9 +700,14 @@ function normalizeRemoteInputEvent(value = {}) {
         shiftKey: input.shiftKey === true || input.ShiftKey === true,
         ctrlKey: input.ctrlKey === true || input.ControlKey === true || input.CtrlKey === true,
         altKey: input.altKey === true || input.AltKey === true,
-        metaKey: input.metaKey === true || input.MetaKey === true || input.commandKey === true || input.CommandKey === true,
-        controlLeaseId: safeString(input.controlLeaseId || input.ControlLeaseId, 128),
-        inputSeq: Number.isSafeInteger(inputSeq) && inputSeq > 0 ? inputSeq : 0,
+        metaKey: input.metaKey === true || input.MetaKey === true || input.commandKey === true || input.CommandKey === true,
+        controlLeaseId: safeString(input.controlLeaseId || input.ControlLeaseId, 128),
+        controlSessionId: safeString(input.controlSessionId || input.sessionId || input.ControlSessionId || input.SessionId, 160),
+        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,
         hubReceivedAtEpochMs: Number.isFinite(hubReceivedAtEpochMs) ? hubReceivedAtEpochMs : 0,
@@ -920,9 +989,10 @@ function serializeDevice(device, options = {}) {
         platform: device.platform,
         arch: device.arch,
         slotNumber: device.slotNumber || 0,
-        pid: device.pid,
-        agentVersion: device.agentVersion,
-        protocol: device.protocol,
+        pid: device.pid,
+        agentVersion: device.agentVersion,
+        productVersion: device.productVersion,
+        protocol: device.protocol,
         protocolVersion: device.protocolVersion,
         frameProtocol: device.frameProtocol ? { ...device.frameProtocol } : null,
         frameModes: Array.isArray(device.frameModes)
@@ -1383,7 +1453,7 @@ class RemoteHubWebSocketAgentSocket {
     }
 }
 
-export function createRemoteHub(options = {}) {
+export function createRemoteHub(options = {}) {
     const env = options.env || process.env;
     const logEvent = options.logEvent || (() => {});
     const logWarn = options.logWarn || (() => {});
@@ -1396,9 +1466,10 @@ export function createRemoteHub(options = {}) {
     const getWelcomeDevicePolicy = typeof options.getWelcomeDevicePolicy === 'function'
         ? options.getWelcomeDevicePolicy
         : getEffectiveDevicePolicy;
-    const udpTransport = options.udpTransport && typeof options.udpTransport === 'object'
-        ? options.udpTransport
-        : null;
+    const udpTransport = options.udpTransport && typeof options.udpTransport === 'object'
+        ? options.udpTransport
+        : null;
+    const sampleHubRuntimeDiagnostics = createHubRuntimeDiagnosticsSampler();
 
     function getDevicePolicy(device) {
         try {
@@ -1425,11 +1496,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();
@@ -1750,11 +1826,22 @@ export function createRemoteHub(options = {}) {
         };
     }
 
-    function getStatus({ includeSecrets = false } = {}) {
-        const connectedDevices = [...devices.values()].filter(device => device.connected).length;
-        const activeHostTarget = serializeHostTarget();
-        const routeInfo = getAgentEndpointRouteInfo();
-        return {
+    function getStatus({ includeSecrets = false } = {}) {
+        const connectedDevices = [...devices.values()].filter(device => device.connected).length;
+        const connectedRoutes = [...devices.values()]
+            .filter(device => device.connected)
+            .map(device => String(device.remoteAddress || '').replace(/^::ffff:/i, '').trim())
+            .filter(Boolean);
+        const externalDeviceCount = connectedRoutes.filter(address => !isPrivateNetworkAddress(address)).length;
+        const activeHostTarget = serializeHostTarget();
+        const routeInfo = getAgentEndpointRouteInfo();
+        const diagnostics = sampleHubRuntimeDiagnostics();
+        diagnostics.network = {
+            lanDeviceCount: connectedRoutes.length - externalDeviceCount,
+            externalDeviceCount,
+            route: externalDeviceCount > 0 ? 'external' : connectedRoutes.length > 0 ? 'lan' : 'idle'
+        };
+        return {
             enabled,
             started,
             host,
@@ -1804,9 +1891,10 @@ export function createRemoteHub(options = {}) {
                 sessionCount: 0,
                 readySessionCount: 0
             },
-            externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
-            lastError
-        };
+            externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
+            diagnostics,
+            lastError
+        };
     }
 
     function rotatePairingPin() {
@@ -1971,9 +2059,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',
@@ -2038,10 +2128,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({
@@ -2076,9 +2167,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
@@ -2313,7 +2405,7 @@ export function createRemoteHub(options = {}) {
         const replace = options.replace !== false;
         const now = new Date();
         const platforms = ['win32', 'linux', 'darwin'];
-        const machineKinds = ['Mac mini', 'Mini PC', 'Workstation', 'Render node', 'Dev box'];
+        const machineKinds = ['Mac mini', 'Mini PC', 'Client', 'Render node', 'Dev box'];
         const workloadRoles = ['LLM worker', 'Image worker', 'Video worker', 'Idle reserve', 'Build worker'];
         const gpuNames = ['Apple M-series GPU', 'NVIDIA RTX local', 'Radeon Pro', 'Intel Arc', 'Integrated GPU'];
         const npuNames = ['Apple Neural Engine', 'Ryzen AI NPU', 'Intel AI Boost', 'Qualcomm Hexagon', 'NPU not present'];
@@ -2630,9 +2722,10 @@ export function createRemoteHub(options = {}) {
             platform: safeString(hello.platform, 80),
             arch: safeString(hello.arch, 40),
             slotNumber: normalizeSlotNumber(hello.slotNumber ?? hello.slot ?? hello.computerNumber),
-            pid: Number.isFinite(Number(hello.pid)) ? Number(hello.pid) : 0,
-            agentVersion: safeString(hello.agentVersion, 40),
-            protocol: safeString(hello.protocol, 80) || REMOTE_AGENT_PROTOCOL,
+            pid: Number.isFinite(Number(hello.pid)) ? Number(hello.pid) : 0,
+            agentVersion: safeString(hello.agentVersion, 40),
+            productVersion: safeString(hello.productVersion, 40),
+            protocol: safeString(hello.protocol, 80) || REMOTE_AGENT_PROTOCOL,
             protocolVersion: Number.isFinite(Number(hello.protocolVersion)) ? Math.max(1, Math.floor(Number(hello.protocolVersion))) : 1,
             frameProtocol: frameProtocol || buildRemoteFrameProtocolDescriptor(),
             frameModes: frameModes.length > 0 ? frameModes : getSupportedRemoteFrameModeProfiles(),
@@ -2851,9 +2944,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 });
     }
 
@@ -3111,10 +3205,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;
@@ -3122,11 +3216,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;
@@ -3365,10 +3711,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,
@@ -3376,12 +3820,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',
@@ -3391,21 +3836,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();
-        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,
+            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,
+            open: true,
+            openedAt,
+            openTransport: transport,
             mode: transfer.mode,
             frameMode: transfer.frameMode,
             frameProfile: transfer.frameProfile,
@@ -3419,47 +3874,54 @@ export function createRemoteHub(options = {}) {
             height: Number.isFinite(Number(message.height)) ? Number(message.height) : Number(streamState.height || 0),
             sourceWidth: Number.isFinite(Number(message.sourceWidth)) ? Number(message.sourceWidth) : Number(streamState.sourceWidth || 0),
             sourceHeight: Number.isFinite(Number(message.sourceHeight)) ? Number(message.sourceHeight) : Number(streamState.sourceHeight || 0),
-            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),
-            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;
-    }
+            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),
+            streamPurpose: safeString(message.streamPurpose || streamState.streamPurpose, 24) || 'wall',
+            captureGeneration: Number.isSafeInteger(Number(message.captureGeneration)) && Number(message.captureGeneration) > 0
+                ? Number(message.captureGeneration)
+                : Number(streamState.captureGeneration || 0),
+            openedFrameSeq: Number.isFinite(Number(message.frameSeq)) ? Number(message.frameSeq) : Number(streamState.openedFrameSeq || 0)
+        };
+        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);
-        const isActiveGeneration = !commandId || !activeCommandId || commandId === activeCommandId;
+            });
+            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;
             emitRemoteEvent('RemoteFrameDropped', device, {
@@ -3471,8 +3933,25 @@ export function createRemoteHub(options = {}) {
                 frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
                 transport
             });
-            return false;
-        }
+            return false;
+        }
+        const frameCaptureGeneration = Number(message.captureGeneration || streamState.captureGeneration || 0);
+        const activeCaptureGeneration = Number(streamState.captureGeneration || 0);
+        if (activeCaptureGeneration > 0
+            && frameCaptureGeneration > 0
+            && frameCaptureGeneration !== activeCaptureGeneration) {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: 'stale-capture-generation-frame',
+                streamId,
+                commandId,
+                captureGeneration: frameCaptureGeneration,
+                activeCaptureGeneration,
+                frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
+                transport
+            });
+            return false;
+        }
 
         const byteLength = normalizeFrameByteLength(framePayload, frameData);
         if ((!Buffer.isBuffer(framePayload) && !frameData)
@@ -3494,7 +3973,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`;
@@ -3506,14 +3985,22 @@ export function createRemoteHub(options = {}) {
             streamState.compression = transfer.compression;
             streamState.transferProtocol = transfer.transferProtocol;
             streamState.transferProtocolVersion = transfer.transferProtocolVersion;
-            streamState.handshake = transfer.handshake;
-        }
-        device.latestLiveFrame = {
-            streamId,
-            frameSeq,
-            streamFrameSeq: Number.isFinite(Number(message.streamFrameSeq)) ? Number(message.streamFrameSeq) : frameSeq,
-            commandId,
-            width: Number.isFinite(Number(message.width)) ? Number(message.width) : 0,
+            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 || 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,
             sourceWidth: Number.isFinite(Number(message.sourceWidth)) ? Number(message.sourceWidth) : Number(message.width || 0),
             sourceHeight: Number.isFinite(Number(message.sourceHeight)) ? Number(message.sourceHeight) : Number(message.height || 0),
@@ -3603,11 +4090,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)
@@ -3906,8 +4403,21 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        if (!state.authenticated) {
-            if (message.type !== 'hello') {
+        if (!state.authenticated) {
+            if (message.type === 'slot.assign') {
+                if (!timingSafeStringEqual(message.pairToken, pairToken)) {
+                    writeJsonLine(socket, { type: 'slot.assignment', ok: false, error: 'invalid-pair-token' });
+                    socket.end();
+                    return;
+                }
+                const result = assignDeviceSlot(
+                    message.deviceId || message.DeviceId,
+                    message.slotNumber ?? message.slot ?? message.SlotNumber);
+                writeJsonLine(socket, { type: 'slot.assignment', ...result });
+                socket.end();
+                return;
+            }
+            if (message.type !== 'hello') {
                 writeJsonLine(socket, { type: 'error', error: 'hello-required' });
                 socket.destroy();
                 return;
@@ -3981,32 +4491,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;
@@ -4028,25 +4533,30 @@ export function createRemoteHub(options = {}) {
                 device.status = typeof message.status === 'object' && message.status
                     ? { ...message.status }
                     : {};
-                {
-                    const nextSlotNumber = normalizeSlotNumber(device.status.slotNumber);
-                    if (nextSlotNumber > 0) {
-                        device.slotNumber = nextSlotNumber;
-                    }
-                }
+                {
+                    const nextSlotNumber = normalizeSlotNumber(device.status.slotNumber);
+                    const assignedSlotNumber = normalizeSlotNumber(device.slotAssignment?.slotNumber);
+                    if (nextSlotNumber > 0 && (!assignedSlotNumber || nextSlotNumber === assignedSlotNumber)) {
+                        device.slotNumber = nextSlotNumber;
+                    }
+                }
                 device.lastStatusAt = device.lastSeenAt;
                 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, {
@@ -4061,8 +4571,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;
@@ -4483,9 +4997,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();
             }
@@ -4530,15 +5045,16 @@ export function createRemoteHub(options = {}) {
         started = false;
     }
 
-    function disconnectDevice(deviceId, reason = 'manager-disconnect') {
+    function disconnectDevice(deviceId, reason = 'manager-disconnect') {
         const device = devices.get(String(deviceId || ''));
         if (device?.synthetic === true) {
             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;
         }
 
@@ -4547,11 +5063,67 @@ export function createRemoteHub(options = {}) {
         }
 
         writeJsonLine(device.socket, { type: 'disconnect', reason });
-        device.socket.destroy();
-        return true;
-    }
-
-    function sendCommand(deviceId, command) {
+        device.socket.destroy();
+        return true;
+    }
+
+    function assignDeviceSlot(deviceId, value) {
+        const normalizedDeviceId = safeString(deviceId, 160);
+        const slotNumber = normalizeSlotNumber(value);
+        if (!normalizedDeviceId) {
+            return { ok: false, error: 'device-id-required' };
+        }
+        if (slotNumber <= 0) {
+            return { ok: false, error: 'invalid-slot-number' };
+        }
+
+        const device = devices.get(normalizedDeviceId);
+        if (!device?.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const conflict = [...devices.values()].find(candidate =>
+            candidate?.connected
+            && candidate.deviceId !== normalizedDeviceId
+            && normalizeSlotNumber(candidate.slotNumber) === slotNumber);
+        if (conflict) {
+            return {
+                ok: false,
+                error: 'slot-taken',
+                slotNumber,
+                conflict: {
+                    deviceId: conflict.deviceId,
+                    deviceName: conflict.deviceName || conflict.hostname || conflict.deviceId,
+                    hostname: conflict.hostname || '',
+                    slotNumber
+                }
+            };
+        }
+
+        const previousSlotNumber = normalizeSlotNumber(device.slotNumber);
+        device.slotNumber = slotNumber;
+        device.status = {
+            ...(device.status && typeof device.status === 'object' ? device.status : {}),
+            slotNumber
+        };
+        device.slotAssignment = {
+            slotNumber,
+            assignedAt: new Date().toISOString()
+        };
+        emitRemoteEvent('RemoteDeviceSlotAssigned', device, {
+            previousSlotNumber,
+            slotNumber
+        });
+        return {
+            ok: true,
+            deviceId: normalizedDeviceId,
+            deviceName: device.deviceName || device.hostname || normalizedDeviceId,
+            previousSlotNumber,
+            slotNumber
+        };
+    }
+
+    function sendCommand(deviceId, command) {
         const device = devices.get(String(deviceId || ''));
         const commandName = safeString(command?.command || 'ping', 80);
         const requiredPermission = commandName === 'input.control'
@@ -4629,20 +5201,28 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'device-not-connected' };
         }
 
-        const command = safeString(options.command, 20000);
-        if (!command) return { ok: false, error: 'client-update-command-missing' };
-        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
-        const sent = writeJsonLine(device.socket, {
-            type: 'command',
-            commandId,
-            command: 'command.run',
-            payload: {
-                command,
-                timeoutMs: clampNumber(options.timeoutMs, 1000, 120000, 30000),
-                permissionMode: 'full-access'
-            },
-            issuedAt: new Date().toISOString()
-        });
+        const command = safeString(options.command, 20000);
+        if (!command) return { ok: false, error: 'client-update-command-missing' };
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const timeoutMs = clampNumber(options.timeoutMs, 1000, 120000, 30000);
+        const sent = writeJsonLine(device.socket, {
+            type: 'command',
+            commandId,
+            command: 'command.run',
+            payload: {
+                command,
+                timeoutMs,
+                permissionMode: 'full-access',
+                // RemoteFast releases before 0.1.170 read command.run inputs
+                // from toolArguments, while Node and current Agents accept the
+                // direct payload fields. Carry both during the update bridge.
+                toolArguments: {
+                    command,
+                    timeoutMs
+                }
+            },
+            issuedAt: new Date().toISOString()
+        });
         if (!sent) return { ok: false, error: 'device-not-connected' };
         device.counters.commandsSent += 1;
         emitRemoteEvent('RemoteCommandQueued', device, {
@@ -4664,20 +5244,57 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'device-not-connected' };
         }
 
-        const denied = policyError(device, 'allowControl');
-        if (denied) return { ok: false, error: denied };
-
-        if (!readCapabilityFlag(device.capabilities, 'control')) {
-            return { ok: false, error: 'device-input-control-unavailable' };
-        }
-
-        const normalized = normalizeRemoteInputEvent(input);
-        if (!normalized.type) {
-            return { ok: false, error: 'missing-input-type' };
-        }
-
-        const inputSocket = device.inputSocket;
-        if (inputSocket && !inputSocket.destroyed) {
+        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')) {
+            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)
+            || !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 {
+                ok: false,
+                error: 'STALE_CONTROL_SESSION',
+                activeSessionId: safeString(device.sessionId, 160)
+            };
+        }
+        if (!normalized.controlCommandId
+            || normalized.controlCommandId !== safeString(controlStream.commandId, 128)) {
+            return {
+                ok: false,
+                error: 'STALE_CONTROL_SESSION',
+                activeCommandId: safeString(controlStream.commandId, 128)
+            };
+        }
+        if (normalized.captureGeneration !== Number(controlStream.captureGeneration || 0)) {
+            return {
+                ok: false,
+                error: 'STALE_CAPTURE_GENERATION',
+                activeCaptureGeneration: Number(controlStream.captureGeneration || 0)
+            };
+        }
+
+        const inputSocket = device.inputSocket;
+        if (inputSocket && !inputSocket.destroyed) {
             const sent = writeJsonLine(inputSocket, {
                 type: 'input.control',
                 payload: {
@@ -4687,22 +5304,57 @@ export function createRemoteHub(options = {}) {
                 }
             });
             if (sent) {
-                device.counters.commandsSent += 1;
-                device.inputLastSeenAt = new Date().toISOString();
-                return { ok: true, inputSocket: true };
-            }
+                device.counters.commandsSent += 1;
+                device.inputLastSeenAt = new Date().toISOString();
+                return {
+                    ok: true,
+                    inputSocket: true,
+                    sessionId: device.sessionId,
+                    commandId: controlStream.commandId,
+                    captureGeneration: controlStream.captureGeneration
+                };
+            }
 
             detachInputSocket(inputSocket, 'input-socket-write-failed');
         }
 
-        return sendCommand(deviceId, {
+        const hubForwardedAtEpochMs = Date.now();
+        const fallback = sendCommand(deviceId, {
             command: 'input.control',
-            payload: {
-                ...normalized,
-                hubForwardedAtEpochMs: Date.now(),
-                issuedAt: normalized.issuedAt || new Date().toISOString()
-            }
+            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 = {}) {
@@ -5015,31 +5667,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;
@@ -5047,12 +5768,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;
@@ -5061,11 +5783,30 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function makeStableLiveStreamId(deviceId, purpose = 'wall') {
-        const hash = crypto.createHash('sha1').update(String(deviceId || 'device')).digest('hex').slice(0, 16);
-        const role = safeString(purpose, 24).toLowerCase().replace(/[^a-z0-9_-]+/g, '-') || 'wall';
-        return `${role}-${hash}`;
-    }
+    function makeStableLiveStreamId(deviceId, purpose = 'wall') {
+        const hash = crypto.createHash('sha1').update(String(deviceId || 'device')).digest('hex').slice(0, 16);
+        const role = safeString(purpose, 24).toLowerCase().replace(/[^a-z0-9_-]+/g, '-') || 'wall';
+        return `${role}-${hash}`;
+    }
+
+    function getActiveLiveStreams(device) {
+        if (!device || typeof device !== 'object') {
+            return [];
+        }
+        return [...ensureDeviceLiveStreams(device).values()].filter(stream => stream?.active === true);
+    }
+
+    function getActiveControlStream(device) {
+        return getActiveLiveStreams(device).find(stream =>
+            safeString(stream?.streamPurpose, 24).toLowerCase() === 'control') || null;
+    }
+
+    function nextCaptureGeneration(device) {
+        const current = Number(device?.captureGenerationCounter || 0);
+        const next = Number.isSafeInteger(current) && current > 0 ? current + 1 : 1;
+        device.captureGenerationCounter = next;
+        return next;
+    }
 
     function normalizeLivePlatform(value) {
         const normalized = safeString(value, 32).toLowerCase();
@@ -5075,20 +5816,27 @@ export function createRemoteHub(options = {}) {
         return normalized || 'unknown';
     }
 
-    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 };
-    }
+    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 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 liveStreamModePolicyError(normalized) {
+        if (normalized?.transfer?.frameMode === 'mode2-lzo'
+            && normalized?.streamPurpose !== 'atlas') {
+            return 'MODE2_ATLAS_ONLY: Mode 2 is reserved for internal Mode 4 Atlas input and cannot be used for Wall or Control.';
+        }
+        return '';
+    }
 
     function liveStreamStartStillPending(activeLiveStream) {
         if (!activeLiveStream?.active || activeLiveStream.open === true) {
@@ -5098,13 +5846,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);
@@ -5157,29 +5927,36 @@ export function createRemoteHub(options = {}) {
                 return { ok: false, error: 'device-live-stream-unavailable' };
             }
 
-            const now = new Date().toISOString();
-            const normalized = normalizeLiveStreamStartOptions({ fps: 2, ...options, platform: device.platform });
-            const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
-            const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
-            const activeLiveStream = getDeviceLiveStream(device, streamId);
-            const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+            const now = new Date().toISOString();
+            const normalized = normalizeLiveStreamStartOptions({ fps: 2, ...options, platform: device.platform });
+            const modePolicyError = liveStreamModePolicyError(normalized);
+            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 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,
-                    monitorIndex,
-                    synthetic: true,
-                    reused: true
-                };
-            }
-            device.counters.commandsSent += 1;
-            setDeviceLiveStream(device, {
+                    frameMode: transfer.frameMode,
+                    monitorIndex,
+                    captureGeneration: Number(activeLiveStream.captureGeneration || 0),
+                    ready: liveStreamHasCurrentFrame(activeLiveStream),
+                    synthetic: true,
+                    reused: true
+                };
+            }
+            const captureGeneration = nextCaptureGeneration(device);
+            device.counters.commandsSent += 1;
+            setDeviceLiveStream(device, {
                 streamId,
                 commandId,
                 active: true,
@@ -5204,11 +5981,12 @@ export function createRemoteHub(options = {}) {
                 startedAt: now,
                 stoppedAt: '',
                 stopReason: '',
-                lastFrameAt: '',
-                lastFrameSeq: 0,
-                framesReceived: 0,
-                streamPurpose
-            });
+                lastFrameAt: '',
+                lastFrameSeq: 0,
+                framesReceived: 0,
+                streamPurpose,
+                captureGeneration
+            });
             device.counters.liveStreamsStarted += 1;
             applySyntheticLiveFrame(device, streamId, {
                 commandId,
@@ -5224,7 +6002,20 @@ export function createRemoteHub(options = {}) {
                 mode: transfer.mode,
                 synthetic: true
             });
-            return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode, monitorIndex, 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) {
@@ -5234,51 +6025,66 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'device-live-stream-unavailable' };
         }
 
-        const now = new Date().toISOString();
-        const normalized = normalizeLiveStreamStartOptions({ ...options, platform: device.platform });
-        const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
-        const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
-        const activeLiveStream = getDeviceLiveStream(device, streamId);
-        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),
-                    pending: true,
-                    reused: true
-                };
-            }
-            activeLiveStream.pendingCommandId = '';
-            activeLiveStream.pendingStartedAt = '';
-            activeLiveStream.pendingRestartToken = '';
-        }
+        const now = new Date().toISOString();
+        const normalized = normalizeLiveStreamStartOptions({ ...options, platform: device.platform });
+        const modePolicyError = liveStreamModePolicyError(normalized);
+        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 activeLiveStream = getDeviceLiveStream(device, streamId);
+        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
+                };
+            }
+            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),
-                reused: true
-            };
+                frameMode: activeLiveStream.frameMode || transfer.frameMode,
+                monitorIndex: Number(activeLiveStream.monitorIndex || monitorIndex),
+                captureGeneration: Number(activeLiveStream.captureGeneration || 0),
+                ready: liveStreamHasCurrentFrame(activeLiveStream),
+                reused: true
+            };
         }
         if (activeLiveStream
             && options.forceRestart !== true
@@ -5293,16 +6099,20 @@ 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,
-                reused: true
-            };
+                frameMode: transfer.frameMode,
+                monitorIndex,
+                captureGeneration: Number(activeLiveStream.captureGeneration || 0),
+                ready: liveStreamHasCurrentFrame(activeLiveStream),
+                reused: true
+            };
         }
         if (options.forceRestart === true && activeLiveStream) {
             emitRemoteEvent('RemoteLiveStreamForcedRestart', device, {
@@ -5329,10 +6139,11 @@ export function createRemoteHub(options = {}) {
                 lastFrameAt: activeLiveStream.lastFrameAt || ''
             });
         }
-        const result = sendCommand(deviceId, {
-            command: 'stream.start',
-            commandId,
-            payload: {
+        const captureGeneration = nextCaptureGeneration(device);
+        const result = sendCommand(deviceId, {
+            command: 'stream.start',
+            commandId,
+            payload: {
                 streamId,
                 mode: transfer.mode,
                 frameMode: transfer.frameMode,
@@ -5347,34 +6158,32 @@ export function createRemoteHub(options = {}) {
                 maxWidth,
                 maxHeight,
                 quality,
-                monitorIndex,
-                streamPurpose,
-                requestedAt: now
-            }
+                monitorIndex,
+                streamPurpose,
+                captureGeneration,
+                sessionId: device.sessionId,
+                requestedAt: now
+            }
         });
 
         if (!result.ok) {
             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,
@@ -5385,16 +6194,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
-        });
+            framesReceived: 0,
+            streamPurpose,
+            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,
@@ -5407,7 +6232,19 @@ export function createRemoteHub(options = {}) {
             monitorIndex
         });
 
-        return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode, monitorIndex };
+        return {
+            ok: true,
+            commandId,
+            sessionId: device.sessionId,
+            streamId,
+            streamPurpose,
+            fps,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            monitorIndex,
+            captureGeneration,
+            ready: false
+        };
     }
 
     function stopLiveStream(deviceId, options = {}) {
@@ -5417,24 +6254,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, {
@@ -5462,14 +6300,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, {
@@ -5634,9 +6469,10 @@ export function createRemoteHub(options = {}) {
         getTaskBatch,
         cancelTaskBatch,
         retryTaskBatch,
-        listDeviceFrames,
-        disconnectDevice,
-        sendCommand,
+        listDeviceFrames,
+        disconnectDevice,
+        assignDeviceSlot,
+        sendCommand,
         sendLegacyClientUpdate,
         sendInputControl,
         notifyAgentProgress,