@livedesk/hub 0.1.31 → 0.1.33

package/src/remote-hub.js

@@ -1,10 +1,10 @@
 import net from 'net';
 import os from 'os';
-import crypto from 'crypto';
-import { isSecureHandshakeStart } from '@livedesk/runtime-core';
-import { createDeviceCredentialAuthority } from './security/device-credential-authority.js';
-import { createHubRelayControl, createSecureHubRelayControl } from './transport/relay-hub-control.js';
-import { createSecureDirectAcceptor } from './transport/secure-direct-acceptor.js';
+import crypto from 'crypto';
+import { isSecureHandshakeStart } from '@livedesk/runtime-core';
+import { createDeviceCredentialAuthority } from './security/device-credential-authority.js';
+import { createHubRelayControl, createSecureHubRelayControl } from './transport/relay-hub-control.js';
+import { createSecureDirectAcceptor } from './transport/secure-direct-acceptor.js';
 import { parseExactLiveStreamMonitorIndex } from './live-stream-monitor-contract.js';
 import {
     BoundedSegmentedBuffer,
@@ -35,10 +35,10 @@ const MAX_AGENT_TCP_BINARY_PACKET_BYTES = TCP_BINARY_FRAME_HEADER_BYTES
 const MAX_AGENT_WEBSOCKET_MESSAGE_BYTES = 4
     + MAX_AGENT_BINARY_META_BYTES
     + MAX_AGENT_BINARY_PAYLOAD_BYTES;
-const MAX_AGENT_SOCKET_ACCUMULATOR_BYTES = MAX_LINE_CHARS
-    + MAX_AGENT_TCP_BINARY_PACKET_BYTES
-    + (256 * 1024);
-const MAX_AGENT_MESSAGES_PER_SECOND = 240;
+const MAX_AGENT_SOCKET_ACCUMULATOR_BYTES = MAX_LINE_CHARS
+    + MAX_AGENT_TCP_BINARY_PACKET_BYTES
+    + (256 * 1024);
+const MAX_AGENT_MESSAGES_PER_SECOND = 240;
 const HTTP_HEADER_TERMINATOR = Buffer.from('\r\n\r\n', 'ascii');
 const MAX_AGENT_TASK_CHARS = 4000;
 const MAX_AGENT_TASK_RESULT_CHARS = 3000;
@@ -110,7 +110,7 @@ const MAC_NATIVE_RESOURCE_TELEMETRY_FIELDS = Object.freeze([
     'handoffOldestFrameAgeMs'
 ]);
 
-export function hasCompleteMacNativeResourceTelemetry(frame) {
+export function hasCompleteMacNativeResourceTelemetry(frame) {
     return Number(frame?.nativeCaptureTelemetryVersion) >= MAC_NATIVE_RESOURCE_TELEMETRY_VERSION
         && MAC_NATIVE_RESOURCE_TELEMETRY_FIELDS.every(field =>
             frame?.[field] !== null
@@ -828,61 +828,61 @@ function isPrivateIPv4(value) {
         || (parts[0] === 192 && parts[1] === 168);
 }
 
-function isPrivateNetworkAddress(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');
-}
-
-export function createRemoteMessageRateGate({
-    limit = MAX_AGENT_MESSAGES_PER_SECOND,
-    windowMs = 1_000,
-    now = () => Date.now()
-} = {}) {
-    const boundedLimit = Math.max(1, Math.min(10_000, Math.floor(Number(limit) || MAX_AGENT_MESSAGES_PER_SECOND)));
-    const boundedWindowMs = Math.max(100, Math.min(60_000, Math.floor(Number(windowMs) || 1_000)));
-    let windowStartedAt = Number(now());
-    let count = 0;
-    return Object.freeze({
-        consume() {
-            const current = Number(now());
-            if (!Number.isFinite(current) || current - windowStartedAt >= boundedWindowMs || current < windowStartedAt) {
-                windowStartedAt = current;
-                count = 0;
-            }
-            count += 1;
-            return count <= boundedLimit;
-        },
-        getStatus: () => ({ count, limit: boundedLimit, windowMs: boundedWindowMs, windowStartedAt })
-    });
-}
-
-export function evaluateRemoteConnectionPolicy({
-    remoteAddress = '',
-    relayConnection = false,
-    encrypted = false,
-    allowLegacyPlaintextForTests = false,
-    policy = {}
-} = {}) {
-    const address = String(remoteAddress || '').replace(/^::ffff:/i, '').trim().toLowerCase();
-    if (policy.requireEncryptedConnections === true
-        && encrypted !== true
-        && allowLegacyPlaintextForTests !== true) {
-        return 'encrypted-connection-required';
-    }
-    if (relayConnection === true || !isPrivateNetworkAddress(address)) {
-        return policy.allowInternetConnections === false
-            ? 'internet-connections-blocked-by-settings'
-            : '';
-    }
-    if (!isLoopbackHost(address) && policy.allowLanConnections === false) {
-        return 'lan-connections-blocked-by-settings';
-    }
-    return '';
-}
+        || address.startsWith('fd');
+}
+
+export function createRemoteMessageRateGate({
+    limit = MAX_AGENT_MESSAGES_PER_SECOND,
+    windowMs = 1_000,
+    now = () => Date.now()
+} = {}) {
+    const boundedLimit = Math.max(1, Math.min(10_000, Math.floor(Number(limit) || MAX_AGENT_MESSAGES_PER_SECOND)));
+    const boundedWindowMs = Math.max(100, Math.min(60_000, Math.floor(Number(windowMs) || 1_000)));
+    let windowStartedAt = Number(now());
+    let count = 0;
+    return Object.freeze({
+        consume() {
+            const current = Number(now());
+            if (!Number.isFinite(current) || current - windowStartedAt >= boundedWindowMs || current < windowStartedAt) {
+                windowStartedAt = current;
+                count = 0;
+            }
+            count += 1;
+            return count <= boundedLimit;
+        },
+        getStatus: () => ({ count, limit: boundedLimit, windowMs: boundedWindowMs, windowStartedAt })
+    });
+}
+
+export function evaluateRemoteConnectionPolicy({
+    remoteAddress = '',
+    relayConnection = false,
+    encrypted = false,
+    allowLegacyPlaintextForTests = false,
+    policy = {}
+} = {}) {
+    const address = String(remoteAddress || '').replace(/^::ffff:/i, '').trim().toLowerCase();
+    if (policy.requireEncryptedConnections === true
+        && encrypted !== true
+        && allowLegacyPlaintextForTests !== true) {
+        return 'encrypted-connection-required';
+    }
+    if (relayConnection === true || !isPrivateNetworkAddress(address)) {
+        return policy.allowInternetConnections === false
+            ? 'internet-connections-blocked-by-settings'
+            : '';
+    }
+    if (!isLoopbackHost(address) && policy.allowLanConnections === false) {
+        return 'lan-connections-blocked-by-settings';
+    }
+    return '';
+}
 
 function readCpuTimes() {
     let idle = 0;
@@ -1206,37 +1206,37 @@ function getRetiredAgentTaskError(options = {}) {
         : '';
 }
 
-const SUPPORTED_AGENT_OPERATIONS = new Set([
-    'system.health',
-    'gpu.status',
-    'disk.status',
-    'process.list',
-    'service.status',
-    'diagnostics.collect',
-    'file.read',
-    'file.list',
-    'network.status',
-    'logs.collect'
-]);
-
-const RETIRED_AGENT_MUTATING_OPERATIONS = new Set([
-    'process.control',
-    'service.control',
-    'application.launch',
-    'application.close',
-    'file.write',
-    'file.delete',
-    'command.run',
-    'script.run',
-    'software.install',
-    'system.power',
-    'system.configure'
-]);
-
-function normalizeAgentOperation(value) {
-    const operation = safeString(value, 80).toLowerCase();
-    return SUPPORTED_AGENT_OPERATIONS.has(operation) ? operation : '';
-}
+const SUPPORTED_AGENT_OPERATIONS = new Set([
+    'system.health',
+    'gpu.status',
+    'disk.status',
+    'process.list',
+    'service.status',
+    'diagnostics.collect',
+    'file.read',
+    'file.list',
+    'network.status',
+    'logs.collect'
+]);
+
+const RETIRED_AGENT_MUTATING_OPERATIONS = new Set([
+    'process.control',
+    'service.control',
+    'application.launch',
+    'application.close',
+    'file.write',
+    'file.delete',
+    'command.run',
+    'script.run',
+    'software.install',
+    'system.power',
+    'system.configure'
+]);
+
+function normalizeAgentOperation(value) {
+    const operation = safeString(value, 80).toLowerCase();
+    return SUPPORTED_AGENT_OPERATIONS.has(operation) ? operation : '';
+}
 
 const REMOTE_INPUT_MONITOR_KEYS = Object.freeze([
     'monitorIndex',
@@ -1402,7 +1402,7 @@ function buildRemoteFramePath(deviceId, frameKind, frame) {
     return `/api/remote/devices/${encodeURIComponent(deviceId)}/${endpoint}?${params.toString()}`;
 }
 
-function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
+function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
     if (!frame) {
         return null;
     }
@@ -1424,27 +1424,27 @@ function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
         serialized.dataUrl = dataUrl || buildFrameDataUrl(payload, '', publicFrame.mimeType || publicFrame.format || 'image/jpeg');
     }
 
-    return serialized;
-}
-
-function serializeActiveLiveStream(activeLiveStream, deviceId) {
-    if (!activeLiveStream) {
-        return null;
-    }
-
-    return {
-        ...activeLiveStream,
-        // The active descriptor is status metadata. Keep its internal frame
-        // owner intact for immediate delivery, but never duplicate encoded
-        // bytes or its bearer token into React/status snapshots.
-        latestFrame: serializeRemoteFrame(
-            activeLiveStream.latestFrame,
-            deviceId,
-            'live',
-            { includeDataUrl: false }
-        )
-    };
-}
+    return serialized;
+}
+
+function serializeActiveLiveStream(activeLiveStream, deviceId) {
+    if (!activeLiveStream) {
+        return null;
+    }
+
+    return {
+        ...activeLiveStream,
+        // The active descriptor is status metadata. Keep its internal frame
+        // owner intact for immediate delivery, but never duplicate encoded
+        // bytes or its bearer token into React/status snapshots.
+        latestFrame: serializeRemoteFrame(
+            activeLiveStream.latestFrame,
+            deviceId,
+            'live',
+            { includeDataUrl: false }
+        )
+    };
+}
 
 function getRecentFrameCache(device, frameKind) {
     if (!device) {
@@ -1635,7 +1635,7 @@ function serializeDevice(device, options = {}) {
         },
         latestThumbnail: serializeRemoteFrame(device.latestThumbnail, device.deviceId, 'thumbnail', options),
         latestLiveFrame: serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', options),
-        activeLiveStream: serializeActiveLiveStream(device.activeLiveStream, device.deviceId),
+        activeLiveStream: serializeActiveLiveStream(device.activeLiveStream, device.deviceId),
         liveCapturePause: device.liveCapturePause
             ? {
                 token: device.liveCapturePause.token,
@@ -2242,7 +2242,7 @@ export function createRemoteHub(options = {}) {
         : null;
     const sampleHubRuntimeDiagnostics = createHubRuntimeDiagnosticsSampler();
 
-    function getDevicePolicy(device) {
+    function getDevicePolicy(device) {
         try {
             return getEffectiveDevicePolicy({
                 deviceId: device?.deviceId || '',
@@ -2250,18 +2250,18 @@ export function createRemoteHub(options = {}) {
             }) || {};
         } catch {
             return {};
-        }
-    }
-
-    function connectionPolicyError(socket, policy = {}) {
-        return evaluateRemoteConnectionPolicy({
-            remoteAddress: socket?.remoteAddress || '',
-            relayConnection: socket?.__liveDeskRelayControl === true,
-            encrypted: socket?.__liveDeskSecurityContext?.encrypted === true,
-            allowLegacyPlaintextForTests,
-            policy
-        });
-    }
+        }
+    }
+
+    function connectionPolicyError(socket, policy = {}) {
+        return evaluateRemoteConnectionPolicy({
+            remoteAddress: socket?.remoteAddress || '',
+            relayConnection: socket?.__liveDeskRelayControl === true,
+            encrypted: socket?.__liveDeskSecurityContext?.encrypted === true,
+            allowLegacyPlaintextForTests,
+            policy
+        });
+    }
 
     function policyError(device, permission = '', command = '') {
         const policy = getDevicePolicy(device);
@@ -2311,82 +2311,83 @@ export function createRemoteHub(options = {}) {
     const hostInstanceId = safeString(options.hostInstanceId ?? env.LIVEDESK_HUB_INSTANCE_ID ?? env.MINDEXEC_BRIDGE_INSTANCE_ID ?? crypto.randomUUID(), 128) || crypto.randomUUID();
     const publicEndpoint = safeString(env.LIVEDESK_REMOTE_PUBLIC_ENDPOINT || env.MINDEXEC_REMOTE_PUBLIC_ENDPOINT || env.REMOTE_HUB_PUBLIC_ENDPOINT, 256);
     const publicHost = safeString(env.LIVEDESK_REMOTE_PUBLIC_HOST || env.MINDEXEC_REMOTE_PUBLIC_HOST || env.REMOTE_HUB_PUBLIC_HOST, 128);
-    const configuredEnrollmentToken = safeString(
-        options.pairToken || env.REMOTE_HUB_PAIR_TOKEN || env.LIVEDESK_CLIENT_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN,
-        256);
-    const allowLegacyPlaintextForTests = options.allowLegacyPlaintextForTests === true
-        || isEnabledValue(env.LIVEDESK_TEST_ALLOW_LEGACY_PLAINTEXT, false)
-        || env.LIVEDESK_TEST_MODE === '1';
-    const canonicalEnrollmentToken = /^[A-Za-z0-9_-]{43}$/.test(configuredEnrollmentToken)
-        && Buffer.from(configuredEnrollmentToken, 'base64url').length === 32
-        && Buffer.from(configuredEnrollmentToken, 'base64url').toString('base64url') === configuredEnrollmentToken
-        ? configuredEnrollmentToken
-        : '';
-    let pairToken = allowLegacyPlaintextForTests && configuredEnrollmentToken
-        ? configuredEnrollmentToken
-        : canonicalEnrollmentToken || crypto.randomBytes(32).toString('base64url');
-    const deviceCredentialAuthority = options.deviceCredentialAuthority || createDeviceCredentialAuthority({
-        dataDir: options.dataDir || env.LIVEDESK_DATA_DIR || undefined
-    });
-    const getSecurityIdentity = typeof options.getSecurityIdentity === 'function'
-        ? options.getSecurityIdentity
-        : () => ({ accountId: safeString(options.accountId || env.LIVEDESK_ACCOUNT_ID, 128) });
-    udpTransport?.setRendezvousProofIssuer?.(({ roomId, deviceId, ttlMs }) => {
-        const identity = getSecurityIdentity() || {};
-        return deviceCredentialAuthority.issueRendezvousProof({
-            roomId,
-            deviceId,
-            ttlMs,
-            accountId: safeString(identity.accountId, 128)
-        });
-    });
-    let pairingPin = /^\d{6}$/.test(String(options.pairingPin || env.LIVEDESK_PAIRING_PIN || '').trim())
+    const configuredEnrollmentToken = safeString(
+        options.pairToken || env.REMOTE_HUB_PAIR_TOKEN || env.LIVEDESK_CLIENT_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN,
+        256);
+    const allowLegacyPlaintextForTests = options.allowLegacyPlaintextForTests === true
+        || isEnabledValue(env.LIVEDESK_TEST_ALLOW_LEGACY_PLAINTEXT, false)
+        || env.LIVEDESK_TEST_MODE === '1';
+    const canonicalEnrollmentToken = /^[A-Za-z0-9_-]{43}$/.test(configuredEnrollmentToken)
+        && Buffer.from(configuredEnrollmentToken, 'base64url').length === 32
+        && Buffer.from(configuredEnrollmentToken, 'base64url').toString('base64url') === configuredEnrollmentToken
+        ? configuredEnrollmentToken
+        : '';
+    let pairToken = allowLegacyPlaintextForTests && configuredEnrollmentToken
+        ? configuredEnrollmentToken
+        : canonicalEnrollmentToken || crypto.randomBytes(32).toString('base64url');
+    const deviceCredentialAuthority = options.deviceCredentialAuthority || createDeviceCredentialAuthority({
+        dataDir: options.dataDir || env.LIVEDESK_DATA_DIR || undefined
+    });
+    const getSecurityIdentity = typeof options.getSecurityIdentity === 'function'
+        ? options.getSecurityIdentity
+        : () => ({ accountId: safeString(options.accountId || env.LIVEDESK_ACCOUNT_ID, 128) });
+    udpTransport?.setRendezvousProofIssuer?.(({ roomId, deviceId, role, ttlMs }) => {
+        const identity = getSecurityIdentity() || {};
+        return deviceCredentialAuthority.issueRendezvousProof({
+            roomId,
+            deviceId,
+            role,
+            ttlMs,
+            accountId: safeString(identity.accountId, 128)
+        });
+    });
+    let pairingPin = /^\d{6}$/.test(String(options.pairingPin || env.LIVEDESK_PAIRING_PIN || '').trim())
         ? String(options.pairingPin || env.LIVEDESK_PAIRING_PIN).trim()
         : generatePairingPin();
-    let pairingPinUpdatedAt = new Date().toISOString();
-    const consumeEnrollmentToken = expected => {
-        if (!timingSafeStringEqual(expected, pairToken)) return false;
-        pairToken = crypto.randomBytes(32).toString('base64url');
-        pairingPin = generatePairingPin();
-        pairingPinUpdatedAt = new Date().toISOString();
-        emitRemoteEvent('RemoteEnrollmentTokenRotated', null, {
-            pairingPinUpdatedAt,
-            hubId: deviceCredentialAuthority.hubId
-        });
-        return true;
-    };
-    const relayControl = options.relayControl && typeof options.relayControl === 'object'
-        ? options.relayControl
-        : allowLegacyPlaintextForTests
-            ? createHubRelayControl({
-                env,
-                pairToken,
-                logEvent,
-                logWarn,
-                onPeerSocket: socket => handleTcpAgentSocket(socket)
-            })
-            : createSecureHubRelayControl({
-                env,
-                authority: deviceCredentialAuthority,
-                getIdentity: () => getSecurityIdentity() || {},
-                getEnrollmentToken: () => pairToken,
-                consumeEnrollmentToken,
-                logEvent,
-                logWarn,
-                onPeerSocket: socket => handleTcpAgentSocket(socket)
-            });
-    const secureDirectAcceptor = createSecureDirectAcceptor({
-        authority: deviceCredentialAuthority,
-        getIdentity: () => getSecurityIdentity() || {},
-        getEnrollmentToken: () => pairToken,
-        consumeEnrollmentToken,
-        onSecureSocket: socket => handleTcpAgentSocket(socket),
-        onAudit: audit => emitEvent('RemoteSecurityHandshakeAudit', {
-            ...audit,
-            remoteHub: getStatus({ includeSecrets: false })
-        }),
-        logWarn
-    });
+    let pairingPinUpdatedAt = new Date().toISOString();
+    const consumeEnrollmentToken = expected => {
+        if (!timingSafeStringEqual(expected, pairToken)) return false;
+        pairToken = crypto.randomBytes(32).toString('base64url');
+        pairingPin = generatePairingPin();
+        pairingPinUpdatedAt = new Date().toISOString();
+        emitRemoteEvent('RemoteEnrollmentTokenRotated', null, {
+            pairingPinUpdatedAt,
+            hubId: deviceCredentialAuthority.hubId
+        });
+        return true;
+    };
+    const relayControl = options.relayControl && typeof options.relayControl === 'object'
+        ? options.relayControl
+        : allowLegacyPlaintextForTests
+            ? createHubRelayControl({
+                env,
+                pairToken,
+                logEvent,
+                logWarn,
+                onPeerSocket: socket => handleTcpAgentSocket(socket)
+            })
+            : createSecureHubRelayControl({
+                env,
+                authority: deviceCredentialAuthority,
+                getIdentity: () => getSecurityIdentity() || {},
+                getEnrollmentToken: () => pairToken,
+                consumeEnrollmentToken,
+                logEvent,
+                logWarn,
+                onPeerSocket: socket => handleTcpAgentSocket(socket)
+            });
+    const secureDirectAcceptor = createSecureDirectAcceptor({
+        authority: deviceCredentialAuthority,
+        getIdentity: () => getSecurityIdentity() || {},
+        getEnrollmentToken: () => pairToken,
+        consumeEnrollmentToken,
+        onSecureSocket: socket => handleTcpAgentSocket(socket),
+        onAudit: audit => emitEvent('RemoteSecurityHandshakeAudit', {
+            ...audit,
+            remoteHub: getStatus({ includeSecrets: false })
+        }),
+        logWarn
+    });
     const duplicateDeviceLogThrottleMs = clampNumber(
         env.MINDEXEC_REMOTE_DUPLICATE_DEVICE_LOG_MS || env.REMOTE_HUB_DUPLICATE_DEVICE_LOG_MS,
         5000,
@@ -2411,8 +2412,8 @@ export function createRemoteHub(options = {}) {
     const transportDiagnostics = new Map();
     const transportDiagnosticStartingDevices = new Set();
     const duplicateDeviceLogAt = new Map();
-    let server = null;
-    let controlIdleSweepTimer = null;
+    let server = null;
+    let controlIdleSweepTimer = null;
     let started = false;
     let boundPort = requestedPort;
     let lastError = '';
@@ -2734,8 +2735,8 @@ export function createRemoteHub(options = {}) {
             host,
             agentHost: routeInfo.host || getAnnouncedHost(),
             port: boundPort || requestedPort,
-            protocol: 'secure-record-v1',
-            protocolVersion: REMOTE_PROTOCOL_VERSION,
+            protocol: 'secure-record-v1',
+            protocolVersion: REMOTE_PROTOCOL_VERSION,
             agentProtocol: REMOTE_AGENT_PROTOCOL,
             frameProtocol: buildRemoteFrameProtocolDescriptor(),
             frameModes: getSupportedRemoteFrameModeProfiles(),
@@ -2751,18 +2752,18 @@ export function createRemoteHub(options = {}) {
             agentEndpointCandidates: routeInfo.candidates,
             agentEndpointCandidateDetails: routeInfo.candidateDetails,
             pairToken: includeSecrets ? pairToken : undefined,
-            pairTokenPreview: maskToken(pairToken),
-            pairingPin: includeSecrets ? pairingPin : '',
-            pairingPinUpdatedAt,
-            security: {
-                direct: secureDirectAcceptor.getStatus(),
-                hubId: deviceCredentialAuthority.hubId,
-                hubPublicKeyFingerprint: crypto.createHash('sha256')
-                    .update(Buffer.from(deviceCredentialAuthority.hubPublicKey, 'base64url'))
-                    .digest('hex'),
-                enrolledDeviceCount: deviceCredentialAuthority.listDevices().filter(item => !item.revokedAt).length,
-                legacyPlaintextForTests: allowLegacyPlaintextForTests
-            },
+            pairTokenPreview: maskToken(pairToken),
+            pairingPin: includeSecrets ? pairingPin : '',
+            pairingPinUpdatedAt,
+            security: {
+                direct: secureDirectAcceptor.getStatus(),
+                hubId: deviceCredentialAuthority.hubId,
+                hubPublicKeyFingerprint: crypto.createHash('sha256')
+                    .update(Buffer.from(deviceCredentialAuthority.hubPublicKey, 'base64url'))
+                    .digest('hex'),
+                enrolledDeviceCount: deviceCredentialAuthority.listDevices().filter(item => !item.revokedAt).length,
+                legacyPlaintextForTests: allowLegacyPlaintextForTests
+            },
             deviceCount: devices.size,
             connectedDeviceCount: connectedDevices,
             canvasDeviceListMode: 'all-devices',
@@ -4022,22 +4023,22 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function closeInputSocket(device, reason = 'input-socket-closed') {
+    function closeInputSocket(device, reason = 'input-socket-closed') {
         const socket = device?.inputSocket;
         if (!socket) {
             return;
         }
-
-        const writeOwner = device.inputWriteOwner;
-        if (device.controlOwnerConnectionId) {
-            endControlSession(
-                device,
-                device.controlOwnerConnectionId,
-                reason,
-                writeOwner,
-                writeOwner?.getBindingKey?.() || '');
-        }
-        device.inputSocket = null;
+
+        const writeOwner = device.inputWriteOwner;
+        if (device.controlOwnerConnectionId) {
+            endControlSession(
+                device,
+                device.controlOwnerConnectionId,
+                reason,
+                writeOwner,
+                writeOwner?.getBindingKey?.() || '');
+        }
+        device.inputSocket = null;
         device.inputWriteOwner = null;
         device.inputSocketConnectionId = '';
         device.inputOwnerConnectionId = '';
@@ -4067,17 +4068,17 @@ export function createRemoteHub(options = {}) {
         if (!device || device.inputSocket !== socket) {
             return;
         }
-
-        const writeOwner = device.inputWriteOwner;
-        if (device.controlOwnerConnectionId) {
-            endControlSession(
-                device,
-                device.controlOwnerConnectionId,
-                reason,
-                null,
-                '');
-        }
-        device.inputSocket = null;
+
+        const writeOwner = device.inputWriteOwner;
+        if (device.controlOwnerConnectionId) {
+            endControlSession(
+                device,
+                device.controlOwnerConnectionId,
+                reason,
+                null,
+                '');
+        }
+        device.inputSocket = null;
         device.inputWriteOwner = null;
         device.inputSocketConnectionId = '';
         device.inputOwnerConnectionId = '';
@@ -4509,11 +4510,11 @@ export function createRemoteHub(options = {}) {
             inputWriteOwner: null,
             inputSocketConnectionId: '',
             inputOwnerConnectionId: '',
-            inputOwnerBindingKey: '',
-            controlOwnerSessionId: '',
-            controlOwnerConnectionId: '',
-            controlOwnerStartedAtMs: 0,
-            controlOwnerLastInputAtMs: 0,
+            inputOwnerBindingKey: '',
+            controlOwnerSessionId: '',
+            controlOwnerConnectionId: '',
+            controlOwnerStartedAtMs: 0,
+            controlOwnerLastInputAtMs: 0,
             frameSocket: null,
             audioSocket: null,
             fileSocket: null,
@@ -7434,14 +7435,14 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        if (!state.authenticated) {
-            const securityContext = socket.__liveDeskSecurityContext;
-            const secureDeviceAuthenticated = securityContext?.authenticated === true
-                && securityContext?.encrypted === true
-                && safeString(securityContext.accountId, 128)
-                && safeString(securityContext.hubId, 128)
-                && safeString(securityContext.deviceId, 128);
-            if (message.type === 'hello' && socket.__liveDeskRelayControl === true) {
+        if (!state.authenticated) {
+            const securityContext = socket.__liveDeskSecurityContext;
+            const secureDeviceAuthenticated = securityContext?.authenticated === true
+                && securityContext?.encrypted === true
+                && safeString(securityContext.accountId, 128)
+                && safeString(securityContext.hubId, 128)
+                && safeString(securityContext.deviceId, 128);
+            if (message.type === 'hello' && socket.__liveDeskRelayControl === true) {
                 message = {
                     ...message,
                     capabilities: {
@@ -7451,14 +7452,14 @@ export function createRemoteHub(options = {}) {
                         dedicatedInputChannel: false
                     }
                 };
-            }
-            if (message.type === 'slot.assign') {
-                if (!secureDeviceAuthenticated
-                    || safeString(message.deviceId || message.DeviceId, 128) !== securityContext.deviceId) {
-                    writeJsonLine(socket, { type: 'slot.assignment', ok: false, error: 'authenticated-device-credential-required' });
-                    socket.end();
-                    return;
-                }
+            }
+            if (message.type === 'slot.assign') {
+                if (!secureDeviceAuthenticated
+                    || safeString(message.deviceId || message.DeviceId, 128) !== securityContext.deviceId) {
+                    writeJsonLine(socket, { type: 'slot.assignment', ok: false, error: 'authenticated-device-credential-required' });
+                    socket.end();
+                    return;
+                }
                 const result = assignDeviceSlot(
                     message.deviceId || message.DeviceId,
                     message.slotNumber ?? message.slot ?? message.SlotNumber);
@@ -7472,54 +7473,57 @@ export function createRemoteHub(options = {}) {
                 return;
             }
 
-            if (secureDeviceAuthenticated) {
-                if (safeString(message.deviceId || message.DeviceId, 128) !== securityContext.deviceId) {
-                    writeJsonLine(socket, { type: 'error', error: 'device-credential-binding-invalid' });
-                    socket.destroy();
-                    return;
-                }
-                const helloChannel = safeString(message.channel || message.Channel || 'control', 40).toLowerCase() || 'control';
-                if (helloChannel !== securityContext.channel) {
-                    writeJsonLine(socket, { type: 'error', error: 'secure-channel-binding-invalid' });
-                    socket.destroy();
-                    return;
-                }
-            } else {
-                const legacyAllowed = socket.__liveDeskRelayControl === true
-                    || socket.__liveDeskLegacyPlaintext === true && allowLegacyPlaintextForTests;
-                if (!legacyAllowed || !timingSafeStringEqual(message.pairToken, pairToken)) {
-                    writeJsonLine(socket, { type: 'error', error: 'authenticated-device-credential-required' });
-                    socket.destroy();
-                    return;
-                }
-            }
-
-            const incomingDeviceId = safeString(message.deviceId || message.DeviceId, 128);
-            const incomingCapabilities = message.capabilities && typeof message.capabilities === 'object'
-                ? message.capabilities
-                : {};
-            const incomingPolicy = getWelcomeDevicePolicy({
-                deviceId: incomingDeviceId,
-                capabilities: incomingCapabilities
-            }) || {};
-            const connectionDenied = connectionPolicyError(socket, incomingPolicy);
-            if (connectionDenied) {
-                writeJsonLine(socket, { type: 'error', error: connectionDenied });
-                emitEvent('RemoteSecurityPolicyAudit', {
-                    result: 'rejected',
-                    reason: connectionDenied,
-                    deviceId: incomingDeviceId,
-                    sessionId: safeString(socket.__liveDeskSecurityContext?.sessionId, 160),
-                    accountId: safeString(socket.__liveDeskSecurityContext?.accountId, 128),
-                    hubId: safeString(socket.__liveDeskSecurityContext?.hubId, 128),
-                    transport: socket.__liveDeskRelayControl === true ? 'relay' : 'direct-tcp',
-                    remoteAddress: safeString(socket.remoteAddress, 256)
-                });
-                socket.destroy();
-                return;
-            }
-
-            const channel = safeString(message.channel || message.Channel, 40).toLowerCase();
+            if (secureDeviceAuthenticated) {
+                if (safeString(message.deviceId || message.DeviceId, 128) !== securityContext.deviceId) {
+                    writeJsonLine(socket, { type: 'error', error: 'device-credential-binding-invalid' });
+                    socket.destroy();
+                    return;
+                }
+                const helloChannel = safeString(message.channel || message.Channel || 'control', 40).toLowerCase() || 'control';
+                if (helloChannel !== securityContext.channel) {
+                    writeJsonLine(socket, { type: 'error', error: 'secure-channel-binding-invalid' });
+                    socket.destroy();
+                    return;
+                }
+            } else {
+                const legacyAllowed = socket.__liveDeskRelayControl === true
+                    || socket.__liveDeskLegacyPlaintext === true && allowLegacyPlaintextForTests;
+                if (!legacyAllowed || !timingSafeStringEqual(message.pairToken, pairToken)) {
+                    writeJsonLine(socket, { type: 'error', error: 'authenticated-device-credential-required' });
+                    socket.destroy();
+                    return;
+                }
+            }
+
+            const incomingDeviceId = safeString(message.deviceId || message.DeviceId, 128);
+            const incomingCapabilities = message.capabilities && typeof message.capabilities === 'object'
+                ? message.capabilities
+                : {};
+            const incomingPolicy = getWelcomeDevicePolicy({
+                deviceId: incomingDeviceId,
+                capabilities: incomingCapabilities
+            }) || {};
+            const connectionDenied = connectionPolicyError(socket, incomingPolicy);
+            if (connectionDenied) {
+                const deniedTransport = socket.__liveDeskRelayControl === true ? 'relay' : 'direct-tcp';
+                const deniedRemoteAddress = safeString(socket.remoteAddress, 256) || 'unknown';
+                logWarn('security', 'Remote connection rejected reason=' + connectionDenied + ' transport=' + deniedTransport + ' remote=' + deniedRemoteAddress);
+                writeJsonLine(socket, { type: 'error', error: connectionDenied });
+                emitEvent('RemoteSecurityPolicyAudit', {
+                    result: 'rejected',
+                    reason: connectionDenied,
+                    deviceId: incomingDeviceId,
+                    sessionId: safeString(socket.__liveDeskSecurityContext?.sessionId, 160),
+                    accountId: safeString(socket.__liveDeskSecurityContext?.accountId, 128),
+                    hubId: safeString(socket.__liveDeskSecurityContext?.hubId, 128),
+                    transport: socket.__liveDeskRelayControl === true ? 'relay' : 'direct-tcp',
+                    remoteAddress: safeString(socket.remoteAddress, 256)
+                });
+                socket.destroy();
+                return;
+            }
+
+            const channel = safeString(message.channel || message.Channel, 40).toLowerCase();
             if (channel === 'input') {
                 const device = attachInputSocket(socket, message);
                 if (!device) {
@@ -7686,27 +7690,27 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function enforceAgentMessageRate(socket, state, channel = 'control') {
-        if (state.messageRateGate.consume()) return true;
-        const device = state.device;
-        emitEvent('RemoteAbuseDefense', {
-            result: 'rejected',
-            reason: 'authenticated-message-rate-exceeded',
-            deviceId: device?.deviceId || '',
-            sessionId: device?.sessionId || '',
-            accountId: socket.__liveDeskSecurityContext?.accountId || '',
-            hubId: socket.__liveDeskSecurityContext?.hubId || '',
-            transport: socket.__liveDeskRelayControl === true ? 'relay' : 'direct-tcp',
-            channel,
-            remoteAddress: safeString(socket.remoteAddress, 256),
-            rate: state.messageRateGate.getStatus()
-        });
-        writeJsonLine(socket, { type: 'error', error: 'message-rate-exceeded' });
-        socket.destroy();
-        return false;
-    }
-
-    function handleWebSocketAgentSocket(socket) {
+    function enforceAgentMessageRate(socket, state, channel = 'control') {
+        if (state.messageRateGate.consume()) return true;
+        const device = state.device;
+        emitEvent('RemoteAbuseDefense', {
+            result: 'rejected',
+            reason: 'authenticated-message-rate-exceeded',
+            deviceId: device?.deviceId || '',
+            sessionId: device?.sessionId || '',
+            accountId: socket.__liveDeskSecurityContext?.accountId || '',
+            hubId: socket.__liveDeskSecurityContext?.hubId || '',
+            transport: socket.__liveDeskRelayControl === true ? 'relay' : 'direct-tcp',
+            channel,
+            remoteAddress: safeString(socket.remoteAddress, 256),
+            rate: state.messageRateGate.getStatus()
+        });
+        writeJsonLine(socket, { type: 'error', error: 'message-rate-exceeded' });
+        socket.destroy();
+        return false;
+    }
+
+    function handleWebSocketAgentSocket(socket) {
         allSockets.add(socket);
         socket.setNoDelay(true);
         socket.setKeepAlive(true, heartbeatMs);
@@ -7720,11 +7724,11 @@ export function createRemoteHub(options = {}) {
             audioOnly: false,
             fileOnly: false,
             parserBuffer: socket.buffer,
-            binaryIngress: null,
-            binaryQueueDrops: 0,
-            binaryQueueEpoch: crypto.randomUUID(),
-            messageRateGate: createRemoteMessageRateGate(),
-            closed: false
+            binaryIngress: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            messageRateGate: createRemoteMessageRateGate(),
+            closed: false
         };
         attachAgentBinaryIngress(socket, state);
 
@@ -7735,9 +7739,9 @@ export function createRemoteHub(options = {}) {
             }
         }, 10000);
 
-        socket.onTextMessage = text => {
-            if (!enforceAgentMessageRate(socket, state, 'websocket-text')) return;
-            try {
+        socket.onTextMessage = text => {
+            if (!enforceAgentMessageRate(socket, state, 'websocket-text')) return;
+            try {
                 handleAgentMessage(socket, state, parseJsonLine(String(text || '')));
             } catch (err) {
                 writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
@@ -7745,9 +7749,9 @@ export function createRemoteHub(options = {}) {
             }
         };
 
-        socket.onBinaryMessage = payload => {
-            if (!enforceAgentMessageRate(socket, state, 'websocket-binary')) return;
-            try {
+        socket.onBinaryMessage = payload => {
+            if (!enforceAgentMessageRate(socket, state, 'websocket-binary')) return;
+            try {
                 const packet = parseRemoteHubWebSocketBinaryFrame(payload);
                 if (!packet?.header || !Buffer.isBuffer(packet.payload)) {
                     writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
@@ -7902,11 +7906,11 @@ export function createRemoteHub(options = {}) {
             buffer: new BoundedSegmentedBuffer(MAX_AGENT_SOCKET_ACCUMULATOR_BYTES),
             lineScanOffset: 0,
             pendingBinaryFrame: null,
-            binaryIngress: null,
-            binaryQueueDrops: 0,
-            binaryQueueEpoch: crypto.randomUUID(),
-            messageRateGate: createRemoteMessageRateGate(),
-            closed: false
+            binaryIngress: null,
+            binaryQueueDrops: 0,
+            binaryQueueEpoch: crypto.randomUUID(),
+            messageRateGate: createRemoteMessageRateGate(),
+            closed: false
         };
         attachAgentBinaryIngress(socket, state);
 
@@ -8021,18 +8025,18 @@ export function createRemoteHub(options = {}) {
                     return;
                 }
 
-                try {
-                    const message = parseJsonLine(lineBuffer.toString('utf8'));
-                    if (!enforceAgentMessageRate(socket, state, state.frameOnly
-                        ? 'frame'
-                        : state.audioOnly
-                            ? 'audio'
-                            : state.inputOnly
-                                ? 'input'
-                                : state.fileOnly ? 'file' : 'control')) {
-                        return;
-                    }
-                    if (message?.type === 'frame.binary') {
+                try {
+                    const message = parseJsonLine(lineBuffer.toString('utf8'));
+                    if (!enforceAgentMessageRate(socket, state, state.frameOnly
+                        ? 'frame'
+                        : state.audioOnly
+                            ? 'audio'
+                            : state.inputOnly
+                                ? 'input'
+                                : state.fileOnly ? 'file' : 'control')) {
+                        return;
+                    }
+                    if (message?.type === 'frame.binary') {
                         const frameKind = safeString(message.frameKind || message.kind || message.frameType, 40).toLowerCase();
                         const maxBytes = frameKind === 'thumbnail'
                             ? MAX_THUMBNAIL_BINARY_BYTES
@@ -8086,35 +8090,35 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function handleSocket(socket) {
-        if (!allowLegacyPlaintextForTests) {
-            secureDirectAcceptor.accept(socket);
-            return;
-        }
-        socket.once('data', chunk => {
-            const firstChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-            if (isSecureHandshakeStart(firstChunk)) {
-                secureDirectAcceptor.accept(socket, firstChunk);
-                return;
-            }
-            if (isRemoteHubWebSocketUpgradeStart(firstChunk)) {
-                if (!allowLegacyPlaintextForTests) {
-                    socket.write('HTTP/1.1 426 Upgrade Required\r\nConnection: close\r\n\r\n');
-                    socket.destroy();
-                    return;
-                }
-                socket.__liveDeskLegacyPlaintext = true;
-                handleWebSocketUpgradeSocket(socket, firstChunk);
-                return;
-            }
-            if (!allowLegacyPlaintextForTests) {
-                writeJsonLine(socket, { type: 'error', error: 'secure-direct-required' });
-                socket.destroy();
-                return;
-            }
-            socket.__liveDeskLegacyPlaintext = true;
-            handleTcpAgentSocket(socket, firstChunk);
-        });
+    function handleSocket(socket) {
+        if (!allowLegacyPlaintextForTests) {
+            secureDirectAcceptor.accept(socket);
+            return;
+        }
+        socket.once('data', chunk => {
+            const firstChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (isSecureHandshakeStart(firstChunk)) {
+                secureDirectAcceptor.accept(socket, firstChunk);
+                return;
+            }
+            if (isRemoteHubWebSocketUpgradeStart(firstChunk)) {
+                if (!allowLegacyPlaintextForTests) {
+                    socket.write('HTTP/1.1 426 Upgrade Required\r\nConnection: close\r\n\r\n');
+                    socket.destroy();
+                    return;
+                }
+                socket.__liveDeskLegacyPlaintext = true;
+                handleWebSocketUpgradeSocket(socket, firstChunk);
+                return;
+            }
+            if (!allowLegacyPlaintextForTests) {
+                writeJsonLine(socket, { type: 'error', error: 'secure-direct-required' });
+                socket.destroy();
+                return;
+            }
+            socket.__liveDeskLegacyPlaintext = true;
+            handleTcpAgentSocket(socket, firstChunk);
+        });
 
         socket.once('error', () => {
             // The transport-specific handler owns logging after the first byte.
@@ -8136,10 +8140,10 @@ export function createRemoteHub(options = {}) {
                 started = true;
                 boundPort = candidateServer.address()?.port || port;
                 lastError = '';
-                logEvent('remote', `LiveDesk Hub client endpoint listening with authenticated encryption on tcp://${host}:${boundPort}`, 'success');
-                if (host === '0.0.0.0' || host === '::') {
-                    logWarn('remote', 'LiveDesk Hub client endpoint is externally reachable; Secure Direct device credentials are required.');
-                }
+                logEvent('remote', `LiveDesk Hub client endpoint listening with authenticated encryption on tcp://${host}:${boundPort}`, 'success');
+                if (host === '0.0.0.0' || host === '::') {
+                    logWarn('remote', 'LiveDesk Hub client endpoint is externally reachable; Secure Direct device credentials are required.');
+                }
                 emitRemoteEvent('RemoteHubStarted', null);
                 resolve();
             });
@@ -8151,14 +8155,14 @@ export function createRemoteHub(options = {}) {
             return getStatus({ includeSecrets: false });
         }
 
-        try {
-            await udpTransport?.start?.();
-            await listenOnPort(requestedPort);
-            if (!controlIdleSweepTimer) {
-                controlIdleSweepTimer = setInterval(sweepIdleControlSessions, 1_000);
-                controlIdleSweepTimer.unref?.();
-            }
-            try {
+        try {
+            await udpTransport?.start?.();
+            await listenOnPort(requestedPort);
+            if (!controlIdleSweepTimer) {
+                controlIdleSweepTimer = setInterval(sweepIdleControlSessions, 1_000);
+                controlIdleSweepTimer.unref?.();
+            }
+            try {
                 await relayControl?.start?.();
             } catch {
                 logWarn('relay', 'Encrypted relay control could not start; direct TCP remains available.');
@@ -8179,12 +8183,12 @@ export function createRemoteHub(options = {}) {
         return getStatus({ includeSecrets: false });
     }
 
-    async function close() {
-        if (controlIdleSweepTimer) {
-            clearInterval(controlIdleSweepTimer);
-            controlIdleSweepTimer = null;
-        }
-        for (const state of [...agentBinaryIngressStates]) {
+    async function close() {
+        if (controlIdleSweepTimer) {
+            clearInterval(controlIdleSweepTimer);
+            controlIdleSweepTimer = null;
+        }
+        for (const state of [...agentBinaryIngressStates]) {
             closeAgentBinaryIngress(state, 'hub-shutdown');
         }
 
@@ -8390,7 +8394,61 @@ export function createRemoteHub(options = {}) {
         return { ok: true, commandId };
     }
 
-    function refreshDevicePolicies(deviceIds = undefined) {
+    async function sendCommandAwaitResult(deviceId, command, options = {}) {
+        const normalizedDeviceId = safeString(deviceId, 160);
+        const device = devices.get(normalizedDeviceId);
+        const commandId = safeString(command?.commandId, 128) || crypto.randomUUID();
+        const commandWithId = { ...(command || {}), commandId };
+
+        if (device?.synthetic === true && device.connected) {
+            const sent = sendCommand(normalizedDeviceId, commandWithId);
+            return {
+                ...sent,
+                queued: sent.ok === true,
+                acknowledged: sent.ok === true,
+                acknowledgement: sent.ok === true
+                    ? { ok: true, commandId, result: { ok: true, synthetic: true }, error: '' }
+                    : { ok: false, commandId, result: null, error: sent.error || 'command-not-sent' }
+            };
+        }
+
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            const sent = sendCommand(normalizedDeviceId, commandWithId);
+            return {
+                ...sent,
+                queued: false,
+                acknowledged: false,
+                acknowledgement: {
+                    ok: false,
+                    commandId,
+                    result: null,
+                    error: sent.error || 'device-not-connected'
+                }
+            };
+        }
+
+        const timeoutMs = clampNumber(options.timeoutMs, 1000, 120_000, 30_000);
+        // Register before writing: a loopback Agent can return command.result in
+        // the same event-loop turn as the command write.
+        const acknowledgementPromise = waitForCommandResult(device, commandId, timeoutMs);
+        const sent = sendCommand(normalizedDeviceId, commandWithId);
+        if (!sent.ok) {
+            failPendingCommandResultWaiter(device, commandId, sent.error || 'command-not-sent');
+        }
+        const acknowledgement = await acknowledgementPromise;
+        return {
+            ...sent,
+            ok: sent.ok === true && acknowledgement.ok === true,
+            queued: sent.ok === true,
+            acknowledged: acknowledgement.ok === true,
+            acknowledgement,
+            error: acknowledgement.ok === true
+                ? undefined
+                : acknowledgement.error || sent.error || 'command-result-failed'
+        };
+    }
+
+    function refreshDevicePolicies(deviceIds = undefined) {
         const requestedIds = Array.isArray(deviceIds) && deviceIds.length > 0
             ? new Set(deviceIds.map(deviceId => safeString(deviceId, 160)).filter(Boolean))
             : null;
@@ -8399,31 +8457,34 @@ export function createRemoteHub(options = {}) {
         for (const device of devices.values()) {
             if (requestedIds && !requestedIds.has(device.deviceId)) continue;
             if (!device?.socket || device.socket.destroyed || !device.connected) continue;
-            total += 1;
-            const effectivePolicy = getDevicePolicy(device);
-            const connectionDenied = connectionPolicyError(device.socket, effectivePolicy);
-            if (connectionDenied) {
-                emitEvent('RemoteSecurityPolicyAudit', {
-                    result: 'rejected',
-                    reason: connectionDenied,
-                    deviceId: device.deviceId,
-                    sessionId: device.sessionId,
-                    transport: device.controlTransport,
-                    remoteAddress: device.remoteAddress
-                });
-                disconnectDevice(device.deviceId, connectionDenied);
-                continue;
-            }
-            if (effectivePolicy.allowControl !== true && device.controlOwnerConnectionId) {
-                releaseInputOwner(
-                    device.deviceId,
-                    device.controlOwnerConnectionId,
-                    'control-disabled-by-policy');
-            }
-            if (effectivePolicy.allowRemoteAudio !== true && device.activeAudioStream) {
-                stopAudioStream(device.deviceId, { reason: 'remote-audio-disabled-by-policy' });
-            }
-            if (writeJsonLine(device.socket, {
+            total += 1;
+            const effectivePolicy = getDevicePolicy(device);
+            const connectionDenied = connectionPolicyError(device.socket, effectivePolicy);
+            if (connectionDenied) {
+                const deniedTransport = device.controlTransport || 'direct-tcp';
+                const deniedRemoteAddress = safeString(device.remoteAddress, 256) || 'unknown';
+                logWarn('security', 'Connected device rejected by refreshed policy reason=' + connectionDenied + ' transport=' + deniedTransport + ' remote=' + deniedRemoteAddress + ' device=' + device.deviceId);
+                emitEvent('RemoteSecurityPolicyAudit', {
+                    result: 'rejected',
+                    reason: connectionDenied,
+                    deviceId: device.deviceId,
+                    sessionId: device.sessionId,
+                    transport: device.controlTransport,
+                    remoteAddress: device.remoteAddress
+                });
+                disconnectDevice(device.deviceId, connectionDenied);
+                continue;
+            }
+            if (effectivePolicy.allowControl !== true && device.controlOwnerConnectionId) {
+                releaseInputOwner(
+                    device.deviceId,
+                    device.controlOwnerConnectionId,
+                    'control-disabled-by-policy');
+            }
+            if (effectivePolicy.allowRemoteAudio !== true && device.activeAudioStream) {
+                stopAudioStream(device.deviceId, { reason: 'remote-audio-disabled-by-policy' });
+            }
+            if (writeJsonLine(device.socket, {
                 type: 'policy.update',
                 effectivePolicy,
                 updatedAt: new Date().toISOString()
@@ -8502,7 +8563,7 @@ export function createRemoteHub(options = {}) {
         ]);
     }
 
-    function buildRemoteInputResetMessage(device, controlStream, ownerConnectionId, reason, activeMonitorIndex) {
+    function buildRemoteInputResetMessage(device, controlStream, ownerConnectionId, reason, activeMonitorIndex) {
         return {
             type: 'input.control',
             payload: {
@@ -8524,114 +8585,114 @@ export function createRemoteHub(options = {}) {
                 hubForwardedAtEpochMs: Date.now(),
                 issuedAt: new Date().toISOString()
             }
-        };
-    }
-
-    function controlSessionMessage(device, ownerConnectionId, type, reason = '') {
-        const policy = getDevicePolicy(device);
-        return {
-            type,
-            payload: {
-                controlOwnerSessionId: safeString(device?.controlOwnerSessionId, 160),
-                hubConnectionId: safeString(ownerConnectionId, 128),
-                deviceId: safeString(device?.deviceId, 160),
-                visibleIndicator: true,
-                lockOnEnd: type === 'control.session.stop' && policy.lockOnControlEnd === true,
-                idleControlMinutes: clampNumber(policy.idleControlMinutes, 5, 1440, 30),
-                reason: safeString(reason, 160),
-                issuedAt: new Date().toISOString()
-            }
-        };
-    }
-
-    function sendControlSessionMessage(device, ownerConnectionId, type, reason, inputWriteOwner, bindingKey) {
-        const message = controlSessionMessage(device, ownerConnectionId, type, reason);
-        if (inputWriteOwner && bindingKey) {
-            return inputWriteOwner.enqueue(message, bindingKey);
-        }
-        if (!device?.socket || device.socket.destroyed) {
-            return { ok: false, error: 'device-not-connected' };
-        }
-        const sent = writeJsonLine(device.socket, {
-            type: 'command',
-            commandId: crypto.randomUUID(),
-            command: type,
-            payload: message.payload,
-            issuedAt: new Date().toISOString()
-        });
-        return sent ? { ok: true, inputSocket: false } : { ok: false, error: 'device-not-connected' };
-    }
-
-    function beginControlSession(device, ownerConnectionId, inputWriteOwner, bindingKey) {
-        const owner = safeString(ownerConnectionId, 128);
-        if (!device || !owner) return { ok: false, error: 'control-owner-required' };
-        if (device.controlOwnerConnectionId === owner && device.controlOwnerSessionId) {
-            return { ok: true, alreadyActive: true };
-        }
-        device.controlOwnerSessionId = crypto.randomUUID();
-        device.controlOwnerConnectionId = owner;
-        device.controlOwnerStartedAtMs = Date.now();
-        device.controlOwnerLastInputAtMs = Date.now();
-        const sent = sendControlSessionMessage(
-            device,
-            owner,
-            'control.session.start',
-            'browser-control-owner-active',
-            inputWriteOwner,
-            bindingKey);
-        if (!sent.ok) {
-            device.controlOwnerSessionId = '';
-            device.controlOwnerConnectionId = '';
-            device.controlOwnerStartedAtMs = 0;
-            device.controlOwnerLastInputAtMs = 0;
-            return sent;
-        }
-        emitRemoteEvent('RemoteControlSessionStarted', device, {
-            controlOwnerSessionId: device.controlOwnerSessionId,
-            hubConnectionId: owner
-        });
-        return sent;
-    }
-
-    function endControlSession(device, ownerConnectionId, reason, inputWriteOwner, bindingKey) {
-        const owner = safeString(ownerConnectionId, 128);
-        if (!device?.controlOwnerSessionId
-            || !owner
-            || device.controlOwnerConnectionId !== owner) {
-            return { ok: false, error: 'control-owner-not-current' };
-        }
-        const controlOwnerSessionId = device.controlOwnerSessionId;
-        const sent = sendControlSessionMessage(
-            device,
-            owner,
-            'control.session.stop',
-            reason,
-            inputWriteOwner,
-            bindingKey);
-        device.controlOwnerSessionId = '';
-        device.controlOwnerConnectionId = '';
-        device.controlOwnerStartedAtMs = 0;
-        device.controlOwnerLastInputAtMs = 0;
-        emitRemoteEvent('RemoteControlSessionEnded', device, {
-            controlOwnerSessionId,
-            hubConnectionId: owner,
-            reason,
-            delivered: sent.ok === true
-        });
-        return sent;
-    }
-
-    function sweepIdleControlSessions() {
-        const nowMs = Date.now();
-        for (const device of devices.values()) {
-            if (!device?.connected || !device.controlOwnerConnectionId) continue;
-            const policy = getDevicePolicy(device);
-            if (policy.disconnectIdleControlSessions !== true) continue;
-            const idleMs = clampNumber(policy.idleControlMinutes, 5, 1440, 30) * 60 * 1000;
-            if (nowMs - Number(device.controlOwnerLastInputAtMs || 0) < idleMs) continue;
-            releaseInputOwner(device.deviceId, device.controlOwnerConnectionId, 'control-idle-timeout');
-        }
-    }
+        };
+    }
+
+    function controlSessionMessage(device, ownerConnectionId, type, reason = '') {
+        const policy = getDevicePolicy(device);
+        return {
+            type,
+            payload: {
+                controlOwnerSessionId: safeString(device?.controlOwnerSessionId, 160),
+                hubConnectionId: safeString(ownerConnectionId, 128),
+                deviceId: safeString(device?.deviceId, 160),
+                visibleIndicator: true,
+                lockOnEnd: type === 'control.session.stop' && policy.lockOnControlEnd === true,
+                idleControlMinutes: clampNumber(policy.idleControlMinutes, 5, 1440, 30),
+                reason: safeString(reason, 160),
+                issuedAt: new Date().toISOString()
+            }
+        };
+    }
+
+    function sendControlSessionMessage(device, ownerConnectionId, type, reason, inputWriteOwner, bindingKey) {
+        const message = controlSessionMessage(device, ownerConnectionId, type, reason);
+        if (inputWriteOwner && bindingKey) {
+            return inputWriteOwner.enqueue(message, bindingKey);
+        }
+        if (!device?.socket || device.socket.destroyed) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+        const sent = writeJsonLine(device.socket, {
+            type: 'command',
+            commandId: crypto.randomUUID(),
+            command: type,
+            payload: message.payload,
+            issuedAt: new Date().toISOString()
+        });
+        return sent ? { ok: true, inputSocket: false } : { ok: false, error: 'device-not-connected' };
+    }
+
+    function beginControlSession(device, ownerConnectionId, inputWriteOwner, bindingKey) {
+        const owner = safeString(ownerConnectionId, 128);
+        if (!device || !owner) return { ok: false, error: 'control-owner-required' };
+        if (device.controlOwnerConnectionId === owner && device.controlOwnerSessionId) {
+            return { ok: true, alreadyActive: true };
+        }
+        device.controlOwnerSessionId = crypto.randomUUID();
+        device.controlOwnerConnectionId = owner;
+        device.controlOwnerStartedAtMs = Date.now();
+        device.controlOwnerLastInputAtMs = Date.now();
+        const sent = sendControlSessionMessage(
+            device,
+            owner,
+            'control.session.start',
+            'browser-control-owner-active',
+            inputWriteOwner,
+            bindingKey);
+        if (!sent.ok) {
+            device.controlOwnerSessionId = '';
+            device.controlOwnerConnectionId = '';
+            device.controlOwnerStartedAtMs = 0;
+            device.controlOwnerLastInputAtMs = 0;
+            return sent;
+        }
+        emitRemoteEvent('RemoteControlSessionStarted', device, {
+            controlOwnerSessionId: device.controlOwnerSessionId,
+            hubConnectionId: owner
+        });
+        return sent;
+    }
+
+    function endControlSession(device, ownerConnectionId, reason, inputWriteOwner, bindingKey) {
+        const owner = safeString(ownerConnectionId, 128);
+        if (!device?.controlOwnerSessionId
+            || !owner
+            || device.controlOwnerConnectionId !== owner) {
+            return { ok: false, error: 'control-owner-not-current' };
+        }
+        const controlOwnerSessionId = device.controlOwnerSessionId;
+        const sent = sendControlSessionMessage(
+            device,
+            owner,
+            'control.session.stop',
+            reason,
+            inputWriteOwner,
+            bindingKey);
+        device.controlOwnerSessionId = '';
+        device.controlOwnerConnectionId = '';
+        device.controlOwnerStartedAtMs = 0;
+        device.controlOwnerLastInputAtMs = 0;
+        emitRemoteEvent('RemoteControlSessionEnded', device, {
+            controlOwnerSessionId,
+            hubConnectionId: owner,
+            reason,
+            delivered: sent.ok === true
+        });
+        return sent;
+    }
+
+    function sweepIdleControlSessions() {
+        const nowMs = Date.now();
+        for (const device of devices.values()) {
+            if (!device?.connected || !device.controlOwnerConnectionId) continue;
+            const policy = getDevicePolicy(device);
+            if (policy.disconnectIdleControlSessions !== true) continue;
+            const idleMs = clampNumber(policy.idleControlMinutes, 5, 1440, 30) * 60 * 1000;
+            if (nowMs - Number(device.controlOwnerLastInputAtMs || 0) < idleMs) continue;
+            releaseInputOwner(device.deviceId, device.controlOwnerConnectionId, 'control-idle-timeout');
+        }
+    }
 
     function getCurrentInputWriteOwner(device) {
         if (!device?.inputSocket
@@ -8774,16 +8835,16 @@ export function createRemoteHub(options = {}) {
                 normalized,
                 activeMonitorIndex);
             const previousInputBindingKey = String(device.inputOwnerBindingKey || '');
-            const ownerChanged = normalized.hubConnectionId
+            const ownerChanged = normalized.hubConnectionId
                 && previousOwnerConnectionId
                 && normalized.hubConnectionId !== previousOwnerConnectionId;
             const bindingChanged = previousInputBindingKey
                 && previousInputBindingKey !== activeInputBindingKey;
-            const writeBindingChanged = inputWriteOwner.getBindingKey() !== activeInputBindingKey;
-            const startingControlOwner = !!normalized.hubConnectionId
-                && (!device.controlOwnerConnectionId
-                    || device.controlOwnerConnectionId !== normalized.hubConnectionId);
-            if (ownerChanged || bindingChanged || writeBindingChanged) {
+            const writeBindingChanged = inputWriteOwner.getBindingKey() !== activeInputBindingKey;
+            const startingControlOwner = !!normalized.hubConnectionId
+                && (!device.controlOwnerConnectionId
+                    || device.controlOwnerConnectionId !== normalized.hubConnectionId);
+            if (ownerChanged || bindingChanged || writeBindingChanged) {
                 const resetSent = inputWriteOwner.replaceBinding(
                     activeInputBindingKey,
                     buildRemoteInputResetMessage(
@@ -8798,28 +8859,28 @@ export function createRemoteHub(options = {}) {
                         activeMonitorIndex));
                 if (!resetSent.ok) {
                     closeInputSocket(device, resetSent.error || 'input-owner-reset-write-failed');
-                    return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
-                }
-                if (startingControlOwner) {
-                    if (device.controlOwnerConnectionId) {
-                        endControlSession(
-                            device,
-                            device.controlOwnerConnectionId,
-                            'browser-input-owner-changed',
-                            inputWriteOwner,
-                            activeInputBindingKey);
-                    }
-                    const started = beginControlSession(
-                        device,
-                        normalized.hubConnectionId,
-                        inputWriteOwner,
-                        activeInputBindingKey);
-                    if (!started.ok) {
-                        closeInputSocket(device, started.error || 'control-session-indicator-start-failed');
-                        return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
-                    }
-                }
-            }
+                    return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+                }
+                if (startingControlOwner) {
+                    if (device.controlOwnerConnectionId) {
+                        endControlSession(
+                            device,
+                            device.controlOwnerConnectionId,
+                            'browser-input-owner-changed',
+                            inputWriteOwner,
+                            activeInputBindingKey);
+                    }
+                    const started = beginControlSession(
+                        device,
+                        normalized.hubConnectionId,
+                        inputWriteOwner,
+                        activeInputBindingKey);
+                    if (!started.ok) {
+                        closeInputSocket(device, started.error || 'control-session-indicator-start-failed');
+                        return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
+                    }
+                }
+            }
             const sent = inputWriteOwner.enqueue({
                 type: 'input.control',
                 payload: {
@@ -8832,8 +8893,8 @@ export function createRemoteHub(options = {}) {
                 if (normalized.hubConnectionId) {
                     device.inputOwnerConnectionId = normalized.hubConnectionId;
                 }
-                device.inputOwnerBindingKey = activeInputBindingKey;
-                device.controlOwnerLastInputAtMs = Date.now();
+                device.inputOwnerBindingKey = activeInputBindingKey;
+                device.controlOwnerLastInputAtMs = Date.now();
                 device.counters.commandsSent += 1;
                 device.inputLastSeenAt = new Date().toISOString();
                 return {
@@ -8862,27 +8923,27 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
         }
 
-        const hubForwardedAtEpochMs = Date.now();
-        const startingFallbackOwner = !!normalized.hubConnectionId
-            && (!device.controlOwnerConnectionId
-                || device.controlOwnerConnectionId !== normalized.hubConnectionId);
-        if (startingFallbackOwner) {
-            if (device.controlOwnerConnectionId) {
-                endControlSession(
-                    device,
-                    device.controlOwnerConnectionId,
-                    'browser-input-owner-changed',
-                    null,
-                    '');
-            }
-            const started = beginControlSession(
-                device,
-                normalized.hubConnectionId,
-                null,
-                '');
-            if (!started.ok) return started;
-        }
-        const fallback = sendCommand(deviceId, {
+        const hubForwardedAtEpochMs = Date.now();
+        const startingFallbackOwner = !!normalized.hubConnectionId
+            && (!device.controlOwnerConnectionId
+                || device.controlOwnerConnectionId !== normalized.hubConnectionId);
+        if (startingFallbackOwner) {
+            if (device.controlOwnerConnectionId) {
+                endControlSession(
+                    device,
+                    device.controlOwnerConnectionId,
+                    'browser-input-owner-changed',
+                    null,
+                    '');
+            }
+            const started = beginControlSession(
+                device,
+                normalized.hubConnectionId,
+                null,
+                '');
+            if (!started.ok) return started;
+        }
+        const fallback = sendCommand(deviceId, {
             command: 'input.control',
             payload: {
                 ...normalized,
@@ -8890,7 +8951,7 @@ export function createRemoteHub(options = {}) {
                 issuedAt: normalized.issuedAt || new Date().toISOString()
             }
         });
-        if (fallback.ok && normalized.requestAck && normalized.inputSeq > 0) {
+        if (fallback.ok && normalized.requestAck && normalized.inputSeq > 0) {
             schedulePendingInputFallback(device, {
                 commandId: fallback.commandId,
                 inputSeq: normalized.inputSeq,
@@ -8902,26 +8963,26 @@ export function createRemoteHub(options = {}) {
                 hubReceivedAtEpochMs: normalized.hubReceivedAtEpochMs,
                 hubForwardedAtEpochMs,
                 fallback: true,
-                timeoutTimer: null
-            });
-        }
-        if (fallback.ok) {
-            device.inputOwnerConnectionId = normalized.hubConnectionId;
-            device.inputOwnerBindingKey = buildRemoteInputBindingKey(
-                device,
-                controlStream,
-                normalized,
-                activeMonitorIndex);
-            device.controlOwnerLastInputAtMs = Date.now();
-        } else if (startingFallbackOwner) {
-            endControlSession(
-                device,
-                normalized.hubConnectionId,
-                'input-control-delivery-failed',
-                null,
-                '');
-        }
-        return fallback.ok
+                timeoutTimer: null
+            });
+        }
+        if (fallback.ok) {
+            device.inputOwnerConnectionId = normalized.hubConnectionId;
+            device.inputOwnerBindingKey = buildRemoteInputBindingKey(
+                device,
+                controlStream,
+                normalized,
+                activeMonitorIndex);
+            device.controlOwnerLastInputAtMs = Date.now();
+        } else if (startingFallbackOwner) {
+            endControlSession(
+                device,
+                normalized.hubConnectionId,
+                'input-control-delivery-failed',
+                null,
+                '');
+        }
+        return fallback.ok
             ? {
                 ...fallback,
                 inputSocket: false,
@@ -8947,20 +9008,20 @@ export function createRemoteHub(options = {}) {
             return { ok: false, error: 'input-owner-not-current' };
         }
 
-        const inputSocket = device.inputSocket;
-        const inputWriteOwner = getCurrentInputWriteOwner(device);
-        if (!inputSocket || !inputWriteOwner) {
-            const ended = endControlSession(device, owner, reason, null, '');
-            device.inputOwnerConnectionId = '';
-            device.inputOwnerBindingKey = '';
-            return {
-                ok: ended.ok !== false,
-                queued: false,
-                controlSessionEnded: ended.ok === true
-            };
-        }
-        const controlStream = getActiveControlStream(device);
-        const releaseBindingKey = buildRemoteInputReleaseBindingKey(device, owner);
+        const inputSocket = device.inputSocket;
+        const inputWriteOwner = getCurrentInputWriteOwner(device);
+        if (!inputSocket || !inputWriteOwner) {
+            const ended = endControlSession(device, owner, reason, null, '');
+            device.inputOwnerConnectionId = '';
+            device.inputOwnerBindingKey = '';
+            return {
+                ok: ended.ok !== false,
+                queued: false,
+                controlSessionEnded: ended.ok === true
+            };
+        }
+        const controlStream = getActiveControlStream(device);
+        const releaseBindingKey = buildRemoteInputReleaseBindingKey(device, owner);
         const sent = inputWriteOwner.replaceBinding(
             releaseBindingKey,
             buildRemoteInputResetMessage(
@@ -8969,24 +9030,24 @@ export function createRemoteHub(options = {}) {
                 owner,
                 reason,
                 normalizeMonitorIndex(controlStream?.monitorIndex)));
-        if (!sent.ok) {
+        if (!sent.ok) {
             closeInputSocket(device, sent.error || 'input-owner-release-write-failed');
             return { ok: false, error: 'INPUT_CHANNEL_RECONNECTING' };
-        }
-        const ended = endControlSession(
-            device,
-            owner,
-            reason,
-            inputWriteOwner,
-            releaseBindingKey);
-        device.inputOwnerConnectionId = '';
-        device.inputOwnerBindingKey = '';
-        return {
-            ok: ended.ok !== false,
-            queued: true,
-            backpressured: sent.backpressured === true || ended.backpressured === true,
-            controlSessionEnded: ended.ok === true
-        };
+        }
+        const ended = endControlSession(
+            device,
+            owner,
+            reason,
+            inputWriteOwner,
+            releaseBindingKey);
+        device.inputOwnerConnectionId = '';
+        device.inputOwnerBindingKey = '';
+        return {
+            ok: ended.ok !== false,
+            queued: true,
+            backpressured: sent.backpressured === true || ended.backpressured === true,
+            controlSessionEnded: ended.ok === true
+        };
     }
 
     function notifyAgentProgress(deviceIds, progress = {}) {
@@ -9026,12 +9087,12 @@ export function createRemoteHub(options = {}) {
         if (retiredRequestError) {
             return { ok: false, error: retiredRequestError };
         }
-        const device = devices.get(String(deviceId || ''));
-        const requestedOperation = safeString(options.operation, 80);
-        if (RETIRED_AGENT_MUTATING_OPERATIONS.has(requestedOperation.toLowerCase())) {
-            return { ok: false, error: 'agent-mutating-tool-disabled' };
-        }
-        const operation = normalizeAgentOperation(requestedOperation);
+        const device = devices.get(String(deviceId || ''));
+        const requestedOperation = safeString(options.operation, 80);
+        if (RETIRED_AGENT_MUTATING_OPERATIONS.has(requestedOperation.toLowerCase())) {
+            return { ok: false, error: 'agent-mutating-tool-disabled' };
+        }
+        const operation = normalizeAgentOperation(requestedOperation);
         if (requestedOperation && !operation) {
             return { ok: false, error: 'unsupported-agent-operation' };
         }
@@ -11279,6 +11340,7 @@ export function createRemoteHub(options = {}) {
         disconnectDevice,
         assignDeviceSlot,
         sendCommand,
+        sendCommandAwaitResult,
         refreshDevicePolicies,
         sendLegacyClientUpdate,
         sendInputControl,
@@ -11306,16 +11368,17 @@ export function createRemoteHub(options = {}) {
         handleUdpFrame,
         seedSyntheticFleet,
         clearSyntheticFleet,
-        getPairToken: () => pairToken,
-        getPairingPin: () => pairingPin,
-        getSecurityStatus: () => ({
-            hubId: deviceCredentialAuthority.hubId,
-            hubPublicKey: deviceCredentialAuthority.hubPublicKey,
-            direct: secureDirectAcceptor.getStatus(),
-            devices: deviceCredentialAuthority.listDevices()
-        }),
-        revokeDeviceCredential: (deviceId, reason) => deviceCredentialAuthority.revokeDevice(deviceId, reason),
-        clearDeviceCredentials: () => deviceCredentialAuthority.clearDevices()
+        getPairToken: () => pairToken,
+        getPairingPin: () => pairingPin,
+        getSecurityStatus: () => ({
+            hubId: deviceCredentialAuthority.hubId,
+            hubPublicKey: deviceCredentialAuthority.hubPublicKey,
+            hubIssuerKeyId: deviceCredentialAuthority.hubIssuerKeyId,
+            direct: secureDirectAcceptor.getStatus(),
+            devices: deviceCredentialAuthority.listDevices()
+        }),
+        revokeDeviceCredential: (deviceId, reason) => deviceCredentialAuthority.revokeDevice(deviceId, reason),
+        clearDeviceCredentials: () => deviceCredentialAuthority.clearDevices()
     };
 }