livedesk 0.1.0 → 0.1.2

package/hub/src/remote-hub.js

@@ -0,0 +1,3949 @@
+import net from 'net';
+import os from 'os';
+import crypto from 'crypto';
+
+const DEFAULT_REMOTE_HUB_PORT = 5197;
+const DEFAULT_REMOTE_HUB_HOST = '0.0.0.0';
+const DEFAULT_HEARTBEAT_MS = 5000;
+const DEFAULT_AGENT_TASK_TIMEOUT_MS = 120000;
+const MAX_LINE_CHARS = 4 * 1024 * 1024;
+const MAX_THUMBNAIL_BASE64_CHARS = 3 * 1024 * 1024;
+const MAX_STREAM_BASE64_CHARS = 3 * 1024 * 1024;
+const MAX_THUMBNAIL_BINARY_BYTES = Math.floor(MAX_THUMBNAIL_BASE64_CHARS * 3 / 4);
+const MAX_STREAM_BINARY_BYTES = Math.floor(MAX_STREAM_BASE64_CHARS * 3 / 4);
+const MAX_AUDIO_BASE64_CHARS = 1024 * 1024;
+const MAX_AUDIO_BINARY_BYTES = Math.floor(MAX_AUDIO_BASE64_CHARS * 3 / 4);
+const MAX_AGENT_TASK_CHARS = 4000;
+const MAX_AGENT_TASK_RESULT_CHARS = 3000;
+const RECENT_TASK_LIMIT = 12;
+const RECENT_TASK_BATCH_LIMIT = 16;
+const RECENT_FRAME_CACHE_TTL_MS = 12000;
+const RECENT_THUMBNAIL_FRAME_CACHE_LIMIT = 4;
+const RECENT_LIVE_FRAME_CACHE_LIMIT = 80;
+const RECENT_THUMBNAIL_FRAME_CACHE_MAX_BYTES = 3 * 1024 * 1024;
+const RECENT_LIVE_FRAME_CACHE_MAX_BYTES = 24 * 1024 * 1024;
+const REMOTE_PROTOCOL_VERSION = 2;
+const REMOTE_AGENT_PROTOCOL = 'mindexec.remote.agent';
+const REMOTE_FRAME_PROTOCOL = 'mindexec.remote.frame.v2';
+const REMOTE_FRAME_PROTOCOL_VERSION = 2;
+const REMOTE_FRAME_HANDSHAKE = 'smartview-request-open-frame';
+const DEFAULT_REMOTE_FRAME_MODE = 'remote-fast';
+const REMOTE_FRAME_MODE_PROFILES = Object.freeze({
+    thumbnail: Object.freeze({
+        mode: 'thumbnail',
+        label: 'Thumbnail PNG/JPEG Binary',
+        transport: 'ws-binary',
+        encoding: 'image',
+        codec: 'image',
+        compression: 'image/*',
+        profile: 'thumbnail-binary-v1',
+        modeVersion: 1,
+        implemented: true
+    }),
+    'remote-fast': Object.freeze({
+        mode: 'remote-fast',
+        label: 'RemoteFast JPEG Binary',
+        transport: 'ws-binary',
+        encoding: 'image',
+        codec: 'jpeg',
+        compression: 'image/jpeg',
+        profile: 'jpeg-binary-v1',
+        modeVersion: 1,
+        implemented: true
+    }),
+    'remote-quality': Object.freeze({
+        mode: 'remote-quality',
+        label: 'RemoteQuality JPEG Binary',
+        transport: 'ws-binary',
+        encoding: 'image',
+        codec: 'jpeg',
+        compression: 'image/jpeg',
+        profile: 'jpeg-quality-binary-v1',
+        modeVersion: 1,
+        implemented: true
+    }),
+    'video-codec': Object.freeze({
+        mode: 'video-codec',
+        label: 'Video Codec Stream',
+        transport: 'ws-binary',
+        encoding: 'video',
+        codec: 'video',
+        compression: 'video/*',
+        profile: 'future-video-codec',
+        modeVersion: 0,
+        implemented: false
+    })
+});
+const REMOTE_FRAME_MODE_ALIASES = new Map([
+    ['fast', 'remote-fast'],
+    ['remotefast', 'remote-fast'],
+    ['remote_fast', 'remote-fast'],
+    ['remote-fast', 'remote-fast'],
+    ['quality', 'remote-quality'],
+    ['remotequality', 'remote-quality'],
+    ['remote_quality', 'remote-quality'],
+    ['remote-quality', 'remote-quality'],
+    ['thumb', 'thumbnail'],
+    ['thumbnail', 'thumbnail'],
+    ['video', 'video-codec'],
+    ['codec', 'video-codec'],
+    ['video-codec', 'video-codec']
+]);
+const MAX_SYNTHETIC_DEVICES = 1000;
+const DEFAULT_HOST_TARGET_LEASE_MS = 30000;
+const DEFAULT_PUBLIC_IP_REFRESH_MS = 5 * 60 * 1000;
+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 SYNTHETIC_FRAME_DATA_URL = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC';
+const SYNTHETIC_FRAME_PAYLOAD = Buffer.from(SYNTHETIC_FRAME_DATA_URL.split(',')[1], 'base64');
+const SYNTHETIC_FRAME_HASH = crypto.createHash('sha256').update(SYNTHETIC_FRAME_PAYLOAD).digest('hex').slice(0, 16);
+const PUBLIC_IPV4_PROVIDERS = Object.freeze([
+    'https://api.ipify.org?format=json',
+    'https://checkip.amazonaws.com/',
+    'https://ifconfig.me/ip'
+]);
+
+function isEnabledValue(value, fallback = true) {
+    if (value === undefined || value === null || value === '') {
+        return fallback;
+    }
+
+    return /^(1|true|yes|on)$/i.test(String(value).trim());
+}
+
+function isDisabledValue(value) {
+    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function clampNumber(value, min, max, fallback) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+
+    return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function normalizePort(value) {
+    return clampNumber(value, 0, 65535, DEFAULT_REMOTE_HUB_PORT);
+}
+
+function safeString(value, maxLength = 200) {
+    return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
+}
+
+function normalizeRemoteFrameMode(value, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const requested = safeString(value, 80).toLowerCase();
+    const fallbackMode = REMOTE_FRAME_MODE_PROFILES[fallback] ? fallback : DEFAULT_REMOTE_FRAME_MODE;
+    if (!requested) {
+        return fallbackMode;
+    }
+
+    const normalized = REMOTE_FRAME_MODE_ALIASES.get(requested) || requested;
+    const profile = REMOTE_FRAME_MODE_PROFILES[normalized];
+    if (!profile || profile.implemented !== true) {
+        return fallbackMode;
+    }
+
+    return normalized;
+}
+
+function serializeRemoteFrameModeProfile(profile) {
+    return {
+        mode: profile.mode,
+        label: profile.label,
+        transport: profile.transport,
+        encoding: profile.encoding,
+        codec: profile.codec,
+        compression: profile.compression,
+        profile: profile.profile,
+        modeVersion: profile.modeVersion,
+        implemented: profile.implemented === true
+    };
+}
+
+function getRemoteFrameModeProfile(value, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const mode = normalizeRemoteFrameMode(value, fallback);
+    return serializeRemoteFrameModeProfile(REMOTE_FRAME_MODE_PROFILES[mode]);
+}
+
+function getSupportedRemoteFrameModeProfiles() {
+    return Object.values(REMOTE_FRAME_MODE_PROFILES)
+        .filter(profile => profile.implemented === true)
+        .map(serializeRemoteFrameModeProfile);
+}
+
+function buildRemoteFrameProtocolDescriptor() {
+    return {
+        protocol: REMOTE_FRAME_PROTOCOL,
+        version: REMOTE_FRAME_PROTOCOL_VERSION,
+        handshake: REMOTE_FRAME_HANDSHAKE,
+        defaultMode: DEFAULT_REMOTE_FRAME_MODE,
+        modes: getSupportedRemoteFrameModeProfiles()
+    };
+}
+
+function buildRemoteFrameTransferDescriptor(value, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const profile = getRemoteFrameModeProfile(value, fallback);
+    return {
+        mode: profile.mode,
+        frameMode: profile.mode,
+        frameProfile: profile.profile,
+        encoding: profile.encoding,
+        codec: profile.codec,
+        compression: profile.compression,
+        transferProtocol: REMOTE_FRAME_PROTOCOL,
+        transferProtocolVersion: REMOTE_FRAME_PROTOCOL_VERSION,
+        handshake: REMOTE_FRAME_HANDSHAKE
+    };
+}
+
+function buildRemoteFrameTransferDescriptorFromMessage(message = {}, fallback = DEFAULT_REMOTE_FRAME_MODE) {
+    const descriptor = buildRemoteFrameTransferDescriptor(message.frameMode || message.mode, fallback);
+    return {
+        ...descriptor,
+        frameProfile: safeString(message.frameProfile, 80) || descriptor.frameProfile,
+        encoding: safeString(message.encoding, 40) || descriptor.encoding,
+        codec: safeString(message.codec, 40) || descriptor.codec,
+        compression: safeString(message.compression || message.mimeType || message.format, 80) || descriptor.compression,
+        transferProtocol: safeString(message.transferProtocol, 80) || descriptor.transferProtocol,
+        transferProtocolVersion: Number.isFinite(Number(message.transferProtocolVersion))
+            ? Math.max(1, Math.floor(Number(message.transferProtocolVersion)))
+            : descriptor.transferProtocolVersion,
+        handshake: safeString(message.handshake, 80) || descriptor.handshake
+    };
+}
+
+function normalizeIncomingFrameModeProfile(value) {
+    if (!value) {
+        return null;
+    }
+
+    if (typeof value === 'string') {
+        return getRemoteFrameModeProfile(value);
+    }
+
+    if (typeof value !== 'object') {
+        return null;
+    }
+
+    const profile = buildRemoteFrameTransferDescriptor(value.mode || value.frameMode || value.profile);
+    return {
+        mode: profile.mode,
+        label: safeString(value.label, 80) || profile.mode,
+        transport: safeString(value.transport, 40) || 'ws-binary',
+        encoding: safeString(value.encoding, 40) || profile.encoding,
+        codec: safeString(value.codec, 40) || profile.codec,
+        compression: safeString(value.compression, 80) || profile.compression,
+        profile: safeString(value.profile || value.frameProfile, 80) || profile.frameProfile,
+        modeVersion: Number.isFinite(Number(value.modeVersion)) ? Math.max(0, Math.floor(Number(value.modeVersion))) : 1,
+        implemented: value.implemented !== false
+    };
+}
+
+function isLoopbackHost(value) {
+    const host = String(value || '').trim().toLowerCase();
+    return host === 'localhost'
+        || host === '127.0.0.1'
+        || host === '::1'
+        || host === '[::1]';
+}
+
+function isWildcardHost(value) {
+    const host = String(value || '').trim().toLowerCase();
+    return host === '0.0.0.0'
+        || host === '::'
+        || host === '[::]'
+        || host === '';
+}
+
+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;
+    }
+
+    return parts[0] === 10
+        || (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
+        || (parts[0] === 192 && parts[1] === 168);
+}
+
+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;
+    }
+
+    if (parts[0] === 0 || parts[0] === 10 || parts[0] === 127 || parts[0] >= 224) {
+        return false;
+    }
+
+    if (parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127) {
+        return false;
+    }
+
+    if (parts[0] === 169 && parts[1] === 254) {
+        return false;
+    }
+
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) {
+        return false;
+    }
+
+    if (parts[0] === 192 && (parts[1] === 0 || parts[1] === 168)) {
+        return false;
+    }
+
+    if (parts[0] === 198 && (parts[1] === 18 || parts[1] === 19)) {
+        return false;
+    }
+
+    return true;
+}
+
+function isPreferredPhysicalInterfaceName(value) {
+    const name = String(value || '').toLowerCase();
+    return /(^|[\s_\-()])((wi[\s_\-]?fi)|wifi|wireless|wlan|ethernet|lan|이더넷|en\d+|eth\d+)(?=$|[\s_\-()])/i.test(name);
+}
+
+function isVirtualInterfaceName(value) {
+    const name = String(value || '').toLowerCase();
+    return /virtual|vethernet|hyper-v|hyperv|vmware|virtualbox|vbox|docker|wsl|container|bluetooth|loopback|npcap|isatap|teredo/i.test(name);
+}
+
+function getIPv4LastOctet(value) {
+    const parts = String(value || '').split('.').map(part => Number(part));
+    if (parts.length !== 4 || parts.some(part => !Number.isInteger(part))) {
+        return -1;
+    }
+
+    return parts[3];
+}
+
+function scoreReachableIPv4Candidate(candidate) {
+    const address = String(candidate?.address || '');
+    const name = String(candidate?.name || '');
+    let score = 0;
+
+    if (isPrivateIPv4(address)) {
+        score += 1000;
+    }
+
+    if (/^192\.168\./.test(address)) {
+        score += 90;
+    } else if (/^10\./.test(address)) {
+        score += 80;
+    } else if (/^172\.(1[6-9]|2\d|3[0-1])\./.test(address)) {
+        score += 70;
+    }
+
+    if (isPreferredPhysicalInterfaceName(name)) {
+        score += 500;
+    }
+
+    if (isVirtualInterfaceName(name)) {
+        score -= 1200;
+    }
+
+    if (/^169\.254\./.test(address)) {
+        score -= 2000;
+    }
+
+    const lastOctet = getIPv4LastOctet(address);
+    if (lastOctet === 1) {
+        score -= 60;
+    } else if (lastOctet === 0 || lastOctet === 255) {
+        score -= 100;
+    }
+
+    if (candidate?.mac && candidate.mac === '00:00:00:00:00:00') {
+        score -= 50;
+    }
+
+    return score;
+}
+
+function getReachableIPv4CandidateEntries() {
+    const candidates = [];
+    const interfaces = os.networkInterfaces();
+    for (const [name, entries] of Object.entries(interfaces)) {
+        for (const entry of entries || []) {
+            if (entry?.family !== 'IPv4' || entry.internal) {
+                continue;
+            }
+
+            const address = safeString(entry.address, 64);
+            if (!address || address === '0.0.0.0') {
+                continue;
+            }
+
+            candidates.push({
+                address,
+                name: safeString(name, 128),
+                mac: safeString(entry.mac, 32),
+                score: 0,
+                virtual: isVirtualInterfaceName(name),
+                preferred: isPreferredPhysicalInterfaceName(name)
+            });
+        }
+    }
+
+    return candidates
+        .map(candidate => ({
+            ...candidate,
+            score: scoreReachableIPv4Candidate(candidate)
+        }))
+        .sort((left, right) => right.score - left.score || left.address.localeCompare(right.address))
+        .filter((candidate, index, all) => all.findIndex(item => item.address === candidate.address) === index);
+}
+
+function getReachableIPv4Candidates() {
+    return getReachableIPv4CandidateEntries().map(candidate => candidate.address);
+}
+
+function getReachableIPv4Address() {
+    const candidates = getReachableIPv4Candidates();
+    return candidates.find(isPrivateIPv4) || candidates[0] || '127.0.0.1';
+}
+
+function buildEndpoint(hostValue, portValue) {
+    const hostText = safeString(hostValue, 128);
+    const port = normalizePort(portValue);
+    if (!hostText || !port) {
+        return '';
+    }
+
+    const hostPart = hostText.includes(':') && !hostText.startsWith('[')
+        ? `[${hostText}]`
+        : hostText;
+    return `${hostPart}:${port}`;
+}
+
+function extractIPv4FromText(value) {
+    const text = safeString(value, 1000);
+    const match = text.match(/\b(?:\d{1,3}\.){3}\d{1,3}\b/);
+    return match ? match[0] : '';
+}
+
+async function fetchTextWithTimeout(url, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                accept: 'application/json,text/plain;q=0.9,*/*;q=0.1',
+                'user-agent': 'LiveDesk-Hub/0.1'
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`${response.status} ${response.statusText}`);
+        }
+        return await response.text();
+    } finally {
+        clearTimeout(timeoutId);
+    }
+}
+
+function normalizeSlotNumber(value) {
+    const number = Number(value);
+    return Number.isInteger(number) && number >= 1 && number <= 999 ? number : 0;
+}
+
+function parseManagerEndpoint(value) {
+    const endpoint = safeString(value, 256);
+    const match = endpoint.match(/^(\[[^\]]+\]|[^:\s]+):(\d{1,5})$/);
+    if (!match) {
+        return null;
+    }
+
+    const host = match[1].replace(/^\[|\]$/g, '');
+    const port = Number(match[2]);
+    if (!host || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        return null;
+    }
+
+    return { endpoint, host, port };
+}
+
+function getAccountRouteEndpointReason(endpoint, context = {}) {
+    const parsed = parseManagerEndpoint(endpoint);
+    if (!parsed) {
+        return 'invalid-manager-endpoint';
+    }
+
+    if (isLoopbackHost(parsed.host)) {
+        return context.wildcardWithoutReachableAddress ? 'no-reachable-ipv4' : 'loopback-endpoint';
+    }
+
+    if (isWildcardHost(parsed.host)) {
+        return 'wildcard-endpoint';
+    }
+
+    if (/^169\.254\./.test(parsed.host)) {
+        return 'link-local-endpoint';
+    }
+
+    return 'ok';
+}
+
+function safeText(value, maxLength = 1000) {
+    return String(value ?? '').replace(/\0/g, '').trim().slice(0, maxLength);
+}
+
+function normalizeApprovalLevel(value) {
+    const level = safeString(value, 80).toLowerCase();
+    return level === 'ai-assist' ? 'ai-assist' : 'task-only';
+}
+
+function normalizeRemoteInputEvent(value = {}) {
+    const input = value && typeof value === 'object' ? value : {};
+    const type = safeString(input.type || input.Type, 48);
+    const normalizedX = Number(input.normalizedX ?? input.NormalizedX);
+    const normalizedY = Number(input.normalizedY ?? input.NormalizedY);
+    const deltaX = Number(input.deltaX ?? input.DeltaX);
+    const deltaY = Number(input.deltaY ?? input.DeltaY);
+    return {
+        type,
+        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),
+        deltaX: Number.isFinite(deltaX) ? Math.max(-4096, Math.min(4096, deltaX)) : 0,
+        deltaY: Number.isFinite(deltaY) ? Math.max(-4096, Math.min(4096, deltaY)) : 0,
+        key: safeString(input.key || input.Key, 80),
+        code: safeString(input.code || input.Code, 80),
+        text: safeText(input.text || input.Text, 256),
+        repeat: input.repeat === true || input.Repeat === true,
+        controlLeaseId: safeString(input.controlLeaseId || input.ControlLeaseId, 128),
+        issuedAt: safeString(input.issuedAt || input.IssuedAt, 80)
+    };
+}
+
+function readCapabilityFlag(capabilities, key) {
+    const value = capabilities?.[key];
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function createDeviceCounters(overrides = {}) {
+    return {
+        messagesReceived: 0,
+        statusReceived: 0,
+        commandsSent: 0,
+        commandResultsReceived: 0,
+        thumbnailFramesReceived: 0,
+        thumbnailFramesDropped: 0,
+        liveFramesReceived: 0,
+        liveFramesDropped: 0,
+        liveStreamsStarted: 0,
+        liveStreamsStopped: 0,
+        audioStreamsStarted: 0,
+        audioStreamsStopped: 0,
+        audioFramesReceived: 0,
+        audioFramesDropped: 0,
+        tasksQueued: 0,
+        taskResultsReceived: 0,
+        taskResultsFailed: 0,
+        taskResultsTimedOut: 0,
+        ...overrides
+    };
+}
+
+function normalizeDeviceId(value) {
+    const id = safeString(value, 128).replace(/[^a-zA-Z0-9_.:-]/g, '-');
+    return id || crypto.randomUUID();
+}
+
+function maskToken(token) {
+    const value = String(token || '');
+    if (value.length <= 8) {
+        return value ? '****' : '';
+    }
+
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+
+function timingSafeStringEqual(left, right) {
+    const a = Buffer.from(String(left || ''), 'utf8');
+    const b = Buffer.from(String(right || ''), 'utf8');
+    if (a.length !== b.length) {
+        return false;
+    }
+
+    return crypto.timingSafeEqual(a, b);
+}
+
+function parseJsonLine(line) {
+    const text = String(line || '').trim();
+    if (!text) {
+        return null;
+    }
+
+    return JSON.parse(text);
+}
+
+function createFrameAccessToken() {
+    return crypto.randomBytes(18).toString('base64url');
+}
+
+function buildRemoteFramePath(deviceId, frameKind, frame) {
+    const token = safeString(frame?.accessToken, 128);
+    const frameSeq = Number(frame?.frameSeq);
+    if (!deviceId || !token || !Number.isFinite(frameSeq)) {
+        return '';
+    }
+
+    const endpoint = frameKind === 'thumbnail' ? 'thumbnail' : 'live/frame';
+    const params = new URLSearchParams({
+        format: 'binary',
+        seq: String(Math.floor(frameSeq)),
+        token
+    });
+    return `/api/remote/devices/${encodeURIComponent(deviceId)}/${endpoint}?${params.toString()}`;
+}
+
+function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
+    if (!frame) {
+        return null;
+    }
+
+    const {
+        payload,
+        accessToken,
+        dataUrl,
+        ...publicFrame
+    } = frame;
+
+    const framePath = buildRemoteFramePath(deviceId, frameKind, frame);
+    const serialized = {
+        ...publicFrame,
+        framePath,
+        frameUrl: framePath
+    };
+    if (options.includeDataUrl === true) {
+        serialized.dataUrl = dataUrl || buildFrameDataUrl(payload, '', publicFrame.mimeType || publicFrame.format || 'image/jpeg');
+    }
+
+    return serialized;
+}
+
+function getRecentFrameCache(device, frameKind) {
+    if (!device) {
+        return null;
+    }
+
+    if (!device.recentFramePayloads) {
+        device.recentFramePayloads = {
+            thumbnail: [],
+            live: []
+        };
+    }
+
+    const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+    if (!Array.isArray(device.recentFramePayloads[kind])) {
+        device.recentFramePayloads[kind] = [];
+    }
+
+    return device.recentFramePayloads[kind];
+}
+
+function getRecentFrameCacheLimit(frameKind) {
+    return frameKind === 'thumbnail'
+        ? RECENT_THUMBNAIL_FRAME_CACHE_LIMIT
+        : RECENT_LIVE_FRAME_CACHE_LIMIT;
+}
+
+function getRecentFrameCacheMaxBytes(frameKind) {
+    return frameKind === 'thumbnail'
+        ? RECENT_THUMBNAIL_FRAME_CACHE_MAX_BYTES
+        : RECENT_LIVE_FRAME_CACHE_MAX_BYTES;
+}
+
+function pruneRecentFrameCache(cache, frameKind, nowMs = Date.now()) {
+    if (!Array.isArray(cache)) {
+        return;
+    }
+
+    const limit = getRecentFrameCacheLimit(frameKind);
+    const maxBytes = getRecentFrameCacheMaxBytes(frameKind);
+    let byteTotal = 0;
+    for (let index = cache.length - 1; index >= 0; index -= 1) {
+        const entry = cache[index];
+        const frame = entry?.frame;
+        if (!entry
+            || entry.expiresAt <= nowMs
+            || !frame
+            || !Buffer.isBuffer(frame.payload)
+            || !Number.isFinite(Number(frame.frameSeq))
+            || !safeString(frame.accessToken, 128)) {
+            cache.splice(index, 1);
+        }
+    }
+
+    for (let index = 0; index < cache.length; index += 1) {
+        const entry = cache[index];
+        const byteLength = Number(entry?.byteLength || entry?.frame?.payload?.length || 0) || 0;
+        byteTotal += byteLength;
+        if (index >= limit || byteTotal > maxBytes) {
+            cache.splice(index);
+            break;
+        }
+    }
+}
+
+function rememberRecentFramePayload(device, frameKind, frame) {
+    if (!device || !frame || !Buffer.isBuffer(frame.payload)) {
+        return;
+    }
+
+    const frameSeq = Number(frame.frameSeq);
+    const accessToken = safeString(frame.accessToken, 128);
+    if (!Number.isFinite(frameSeq) || !accessToken) {
+        return;
+    }
+
+    const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+    const cache = getRecentFrameCache(device, kind);
+    if (!cache) {
+        return;
+    }
+
+    const nowMs = Date.now();
+    const normalizedSeq = Math.floor(frameSeq);
+    for (let index = cache.length - 1; index >= 0; index -= 1) {
+        const existing = cache[index]?.frame;
+        if (Number(existing?.frameSeq) === normalizedSeq
+            || safeString(existing?.accessToken, 128) === accessToken) {
+            cache.splice(index, 1);
+        }
+    }
+
+    cache.unshift({
+        frame,
+        byteLength: frame.payload.length,
+        cachedAt: nowMs,
+        expiresAt: nowMs + RECENT_FRAME_CACHE_TTL_MS
+    });
+    pruneRecentFrameCache(cache, kind, nowMs);
+}
+
+function isFramePayloadRequestMatch(frame, options = {}) {
+    if (!frame || !Buffer.isBuffer(frame.payload)) {
+        return false;
+    }
+
+    const requestedSeq = Number(options.frameSeq);
+    if (Number.isFinite(requestedSeq) && Math.floor(requestedSeq) !== Number(frame.frameSeq)) {
+        return false;
+    }
+
+    const token = safeString(options.token, 128);
+    if (token && !timingSafeStringEqual(token, frame.accessToken)) {
+        return false;
+    }
+
+    if (options.requireToken === true && !token) {
+        return false;
+    }
+
+    return true;
+}
+
+function findRecentFramePayload(device, frameKind, options = {}) {
+    const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+    const latest = kind === 'thumbnail'
+        ? device?.latestThumbnail
+        : device?.latestLiveFrame;
+    if (isFramePayloadRequestMatch(latest, options)) {
+        return latest;
+    }
+
+    const token = safeString(options.token, 128);
+    const requestedSeq = Number(options.frameSeq);
+    if (!token && !Number.isFinite(requestedSeq)) {
+        return null;
+    }
+
+    const cache = getRecentFrameCache(device, kind);
+    if (!cache) {
+        return null;
+    }
+
+    pruneRecentFrameCache(cache, kind);
+    const entry = cache.find(item => isFramePayloadRequestMatch(item?.frame, options));
+    return entry?.frame || null;
+}
+
+function serializeDevice(device, options = {}) {
+    if (!device) {
+        return null;
+    }
+
+    return {
+        deviceId: device.deviceId,
+        sessionId: device.sessionId,
+        deviceName: device.deviceName,
+        hostname: device.hostname,
+        platform: device.platform,
+        arch: device.arch,
+        slotNumber: device.slotNumber || 0,
+        pid: device.pid,
+        agentVersion: device.agentVersion,
+        protocol: device.protocol,
+        protocolVersion: device.protocolVersion,
+        frameProtocol: device.frameProtocol ? { ...device.frameProtocol } : null,
+        frameModes: Array.isArray(device.frameModes)
+            ? device.frameModes.map(profile => ({ ...profile }))
+            : [],
+        capabilities: { ...device.capabilities },
+        connected: device.connected,
+        connectedAt: device.connectedAt,
+        disconnectedAt: device.disconnectedAt,
+        lastSeenAt: device.lastSeenAt,
+        lastStatusAt: device.lastStatusAt,
+        lastDisconnectReason: device.lastDisconnectReason,
+        remoteAddress: device.remoteAddress,
+        remotePort: device.remotePort,
+        latestThumbnail: serializeRemoteFrame(device.latestThumbnail, device.deviceId, 'thumbnail', options),
+        latestLiveFrame: serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', options),
+        activeLiveStream: device.activeLiveStream ? { ...device.activeLiveStream } : null,
+        activeAudioStream: device.activeAudioStream ? { ...device.activeAudioStream } : null,
+        latestAudioFrame: device.latestAudioFrame
+            ? {
+                streamId: device.latestAudioFrame.streamId,
+                frameSeq: device.latestAudioFrame.frameSeq,
+                mimeType: device.latestAudioFrame.mimeType,
+                sampleRate: device.latestAudioFrame.sampleRate,
+                channels: device.latestAudioFrame.channels,
+                capturedAt: device.latestAudioFrame.capturedAt,
+                receivedAt: device.latestAudioFrame.receivedAt,
+                byteLength: device.latestAudioFrame.byteLength
+            }
+            : null,
+        latestTask: device.latestTask ? { ...device.latestTask } : null,
+        synthetic: device.synthetic === true,
+        recentTasks: Array.isArray(device.recentTasks)
+            ? device.recentTasks.map(task => ({ ...task }))
+            : [],
+        status: { ...device.status },
+        counters: { ...device.counters }
+    };
+}
+
+function serializeTaskBatch(batch) {
+    if (!batch) {
+        return null;
+    }
+
+    return {
+        batchId: batch.batchId,
+        title: batch.title,
+        instructionPreview: batch.instructionPreview,
+        approvalLevel: batch.approvalLevel,
+        status: batch.status,
+        requestedAt: batch.requestedAt,
+        updatedAt: batch.updatedAt,
+        total: batch.total,
+        queued: batch.queued,
+        pending: batch.pending,
+        completed: batch.completed,
+        failed: batch.failed,
+        timedOut: batch.timedOut,
+        results: Array.isArray(batch.results)
+            ? batch.results.map(item => ({ ...item }))
+            : []
+    };
+}
+
+function writeJsonLine(socket, payload) {
+    if (!socket || socket.destroyed) {
+        return false;
+    }
+
+    if (socket.__remoteHubWebSocket === true && typeof socket.sendJson === 'function') {
+        return socket.sendJson(payload);
+    }
+
+    socket.write(`${JSON.stringify(payload)}\n`);
+    return true;
+}
+
+function isRemoteHubWebSocketUpgradeStart(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 4) {
+        return false;
+    }
+
+    return buffer.subarray(0, Math.min(buffer.length, 16)).toString('latin1').startsWith('GET ');
+}
+
+function parseRemoteHubWebSocketUpgrade(buffer) {
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd < 0) {
+        return null;
+    }
+
+    const headerText = buffer.subarray(0, headerEnd).toString('latin1');
+    const lines = headerText.split('\r\n');
+    const requestLine = lines.shift() || '';
+    const [method, path] = requestLine.split(/\s+/);
+    const headers = {};
+    for (const line of lines) {
+        const separator = line.indexOf(':');
+        if (separator <= 0) {
+            continue;
+        }
+
+        headers[line.slice(0, separator).trim().toLowerCase()] = line.slice(separator + 1).trim();
+    }
+
+    return {
+        method,
+        path,
+        headers,
+        head: buffer.subarray(headerEnd + 4)
+    };
+}
+
+function buildRemoteHubWebSocketAcceptKey(key) {
+    return crypto
+        .createHash('sha1')
+        .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+        .digest('base64');
+}
+
+function buildRemoteHubWebSocketFrame(opcode, payload) {
+    const body = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload || ''), 'utf8');
+    let header = null;
+    if (body.length < 126) {
+        header = Buffer.allocUnsafe(2);
+        header[0] = 0x80 | opcode;
+        header[1] = body.length;
+    } else if (body.length <= 0xffff) {
+        header = Buffer.allocUnsafe(4);
+        header[0] = 0x80 | opcode;
+        header[1] = 126;
+        header.writeUInt16BE(body.length, 2);
+    } else {
+        header = Buffer.allocUnsafe(10);
+        header[0] = 0x80 | opcode;
+        header[1] = 127;
+        header.writeBigUInt64BE(BigInt(body.length), 2);
+    }
+
+    return Buffer.concat([header, body], header.length + body.length);
+}
+
+function parseRemoteHubWebSocketBinaryFrame(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 5) {
+        return null;
+    }
+
+    const metaLength = buffer.readUInt32BE(0);
+    if (!Number.isFinite(metaLength)
+        || metaLength <= 0
+        || metaLength > 64 * 1024
+        || 4 + metaLength >= buffer.length) {
+        return null;
+    }
+
+    const header = JSON.parse(buffer.subarray(4, 4 + metaLength).toString('utf8'));
+    const payload = buffer.subarray(4 + metaLength);
+    return { header, payload };
+}
+
+class RemoteHubWebSocketAgentSocket {
+    constructor(socket) {
+        this.__remoteHubWebSocket = true;
+        this.socket = socket;
+        this.remoteAddress = socket.remoteAddress;
+        this.remotePort = socket.remotePort;
+        this.destroyed = false;
+        this.buffer = Buffer.alloc(0);
+        this.fragmentOpcode = 0;
+        this.fragments = [];
+        this.onTextMessage = () => {};
+        this.onBinaryMessage = () => {};
+        this.onCloseMessage = () => {};
+    }
+
+    setNoDelay() {}
+
+    setKeepAlive() {}
+
+    sendJson(payload) {
+        return this.sendText(JSON.stringify(payload));
+    }
+
+    write(payload) {
+        if (this.destroyed) {
+            return false;
+        }
+
+        const text = (Buffer.isBuffer(payload) ? payload.toString('utf8') : String(payload || '')).replace(/\n$/, '');
+        return this.sendText(text);
+    }
+
+    sendText(text) {
+        return this.sendFrame(0x1, Buffer.from(String(text || ''), 'utf8'));
+    }
+
+    sendFrame(opcode, payload) {
+        if (this.destroyed || this.socket.destroyed) {
+            return false;
+        }
+
+        try {
+            this.socket.write(buildRemoteHubWebSocketFrame(opcode, payload));
+            return true;
+        } catch {
+            this.destroy();
+            return false;
+        }
+    }
+
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+
+        this.destroyed = true;
+        try {
+            if (!this.socket.destroyed) {
+                this.socket.write(buildRemoteHubWebSocketFrame(0x8, Buffer.alloc(0)));
+            }
+        } catch {
+            // Ignore close-frame failures.
+        }
+        try {
+            this.socket.destroy();
+        } catch {
+            // Ignore socket destroy failures.
+        }
+    }
+
+    handleData(chunk) {
+        if (this.destroyed) {
+            return;
+        }
+
+        this.buffer = this.buffer.length > 0
+            ? Buffer.concat([this.buffer, chunk])
+            : chunk;
+
+        while (!this.destroyed) {
+            if (this.buffer.length < 2) {
+                return;
+            }
+
+            const first = this.buffer[0];
+            const second = this.buffer[1];
+            const fin = (first & 0x80) !== 0;
+            const opcode = first & 0x0f;
+            const masked = (second & 0x80) !== 0;
+            let payloadLength = second & 0x7f;
+            let offset = 2;
+
+            if (payloadLength === 126) {
+                if (this.buffer.length < offset + 2) return;
+                payloadLength = this.buffer.readUInt16BE(offset);
+                offset += 2;
+            } else if (payloadLength === 127) {
+                if (this.buffer.length < offset + 8) return;
+                const bigLength = this.buffer.readBigUInt64BE(offset);
+                if (bigLength > BigInt(Number.MAX_SAFE_INTEGER)) {
+                    this.destroy();
+                    return;
+                }
+                payloadLength = Number(bigLength);
+                offset += 8;
+            }
+
+            if (!masked) {
+                this.destroy();
+                return;
+            }
+
+            if (this.buffer.length < offset + 4 + payloadLength) {
+                return;
+            }
+
+            const mask = this.buffer.subarray(offset, offset + 4);
+            offset += 4;
+            const payload = Buffer.from(this.buffer.subarray(offset, offset + payloadLength));
+            this.buffer = this.buffer.subarray(offset + payloadLength);
+            for (let index = 0; index < payload.length; index += 1) {
+                payload[index] ^= mask[index & 3];
+            }
+
+            if (opcode === 0x8) {
+                this.destroyed = true;
+                this.onCloseMessage('websocket-close');
+                try {
+                    this.socket.destroy();
+                } catch {
+                    // Ignore socket destroy failures.
+                }
+                return;
+            }
+
+            if (opcode === 0x9) {
+                this.sendFrame(0xA, payload);
+                continue;
+            }
+
+            if (opcode === 0xA) {
+                continue;
+            }
+
+            let messageOpcode = opcode;
+            let messagePayload = payload;
+            if (!fin) {
+                this.fragmentOpcode = opcode;
+                this.fragments = [payload];
+                continue;
+            }
+
+            if (opcode === 0x0) {
+                this.fragments.push(payload);
+                messageOpcode = this.fragmentOpcode;
+                messagePayload = Buffer.concat(this.fragments);
+                this.fragmentOpcode = 0;
+                this.fragments = [];
+            }
+
+            if (messageOpcode === 0x1) {
+                this.onTextMessage(messagePayload.toString('utf8'));
+            } else if (messageOpcode === 0x2) {
+                this.onBinaryMessage(messagePayload);
+            }
+        }
+    }
+}
+
+export function createRemoteHub(options = {}) {
+    const env = options.env || process.env;
+    const logEvent = options.logEvent || (() => {});
+    const logWarn = options.logWarn || (() => {});
+    const emitEvent = options.emitEvent || (() => {});
+    const emitFrame = typeof options.emitFrame === 'function' ? options.emitFrame : (() => {});
+    const emitAudio = typeof options.emitAudio === 'function' ? options.emitAudio : (() => {});
+
+    const enabled = isEnabledValue(env.LIVEDESK_REMOTE_HUB ?? env.MINDEXEC_REMOTE_HUB ?? env.REMOTE_HUB_ENABLED, true)
+        && !isDisabledValue(env.REMOTE_HUB_DISABLED);
+    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 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();
+    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 pairToken = safeString(
+        options.pairToken || env.REMOTE_HUB_PAIR_TOKEN || env.LIVEDESK_CLIENT_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN || crypto.randomBytes(6).toString('hex'),
+        256);
+    const duplicateDeviceLogThrottleMs = clampNumber(
+        env.MINDEXEC_REMOTE_DUPLICATE_DEVICE_LOG_MS || env.REMOTE_HUB_DUPLICATE_DEVICE_LOG_MS,
+        5000,
+        10 * 60 * 1000,
+        DUPLICATE_DEVICE_LOG_THROTTLE_MS);
+    const duplicateDeviceRetryAfterMs = clampNumber(
+        env.MINDEXEC_REMOTE_DUPLICATE_DEVICE_RETRY_MS || env.REMOTE_HUB_DUPLICATE_DEVICE_RETRY_MS,
+        5000,
+        10 * 60 * 1000,
+        DUPLICATE_DEVICE_RETRY_AFTER_MS);
+
+    const devices = new Map();
+    const taskBatches = new Map();
+    const sockets = new Map();
+    const allSockets = new Set();
+    const duplicateDeviceLogAt = new Map();
+    let server = null;
+    let started = false;
+    let boundPort = requestedPort;
+    let lastError = '';
+    let hostTarget = null;
+    let publicIPv4Cache = {
+        address: safeString(env.LIVEDESK_REMOTE_PUBLIC_IPV4 || env.LIVEDESK_PUBLIC_IPV4 || env.REMOTE_HUB_PUBLIC_IPV4, 64),
+        updatedAt: 0,
+        checkedAt: 0,
+        error: ''
+    };
+
+    if (!isPublicIPv4(publicIPv4Cache.address)) {
+        publicIPv4Cache.address = '';
+    }
+
+    const publicIpDiscoveryEnabled = isEnabledValue(env.LIVEDESK_PUBLIC_IP_DISCOVERY ?? env.REMOTE_HUB_PUBLIC_IP_DISCOVERY, true)
+        && !isDisabledValue(env.LIVEDESK_PUBLIC_IP_DISCOVERY_DISABLED ?? env.REMOTE_HUB_PUBLIC_IP_DISCOVERY_DISABLED);
+
+    function getPublicIPv4EndpointCandidate() {
+        const address = safeString(publicIPv4Cache.address, 64);
+        if (!isPublicIPv4(address)) {
+            return null;
+        }
+
+        const endpoint = buildEndpoint(address, boundPort || requestedPort);
+        if (!endpoint) {
+            return null;
+        }
+
+        return {
+            address,
+            name: 'Public IPv4',
+            mac: '',
+            score: -100,
+            virtual: false,
+            preferred: false,
+            public: true,
+            endpoint
+        };
+    }
+
+    async function refreshPublicIPv4Candidate(options = {}) {
+        if (!publicIpDiscoveryEnabled) {
+            return publicIPv4Cache.address;
+        }
+
+        const now = Date.now();
+        const force = options.force === true;
+        const refreshMs = clampNumber(
+            env.LIVEDESK_PUBLIC_IP_REFRESH_MS || env.REMOTE_HUB_PUBLIC_IP_REFRESH_MS,
+            30_000,
+            60 * 60 * 1000,
+            DEFAULT_PUBLIC_IP_REFRESH_MS);
+
+        if (!force && publicIPv4Cache.checkedAt > 0 && now - publicIPv4Cache.checkedAt < refreshMs) {
+            return publicIPv4Cache.address;
+        }
+
+        publicIPv4Cache.checkedAt = now;
+        const timeoutMs = clampNumber(
+            env.LIVEDESK_PUBLIC_IP_TIMEOUT_MS || env.REMOTE_HUB_PUBLIC_IP_TIMEOUT_MS,
+            500,
+            10_000,
+            DEFAULT_PUBLIC_IP_TIMEOUT_MS);
+
+        for (const provider of PUBLIC_IPV4_PROVIDERS) {
+            try {
+                const text = await fetchTextWithTimeout(provider, timeoutMs);
+                let address = '';
+                try {
+                    const payload = JSON.parse(text);
+                    address = safeString(payload?.ip || payload?.origin || payload?.address, 64);
+                } catch {
+                    address = extractIPv4FromText(text);
+                }
+                address = extractIPv4FromText(address) || address;
+                if (!isPublicIPv4(address)) {
+                    continue;
+                }
+                if (publicIPv4Cache.address !== address) {
+                    logEvent('remote', `public IPv4 candidate detected ${address}`, 'remote');
+                }
+                publicIPv4Cache = {
+                    address,
+                    updatedAt: Date.now(),
+                    checkedAt: Date.now(),
+                    error: ''
+                };
+                return publicIPv4Cache.address;
+            } catch (err) {
+                publicIPv4Cache.error = err instanceof Error ? err.message : String(err);
+            }
+        }
+
+        return publicIPv4Cache.address;
+    }
+
+    function getAnnouncedHost() {
+        if (publicHost) {
+            return publicHost;
+        }
+
+        if (isWildcardHost(host)) {
+            return getReachableIPv4Address();
+        }
+
+        return host;
+    }
+
+    function getAgentEndpoint() {
+        if (publicEndpoint) {
+            return publicEndpoint;
+        }
+
+        return `${getAnnouncedHost()}:${boundPort || requestedPort}`;
+    }
+
+    function getAgentEndpointRouteInfo() {
+        const includeInterfaceCandidates = !publicEndpoint && isWildcardHost(host);
+        const candidateDetails = includeInterfaceCandidates
+            ? getReachableIPv4CandidateEntries()
+            : [];
+        const candidateEndpoints = candidateDetails
+            .map(candidate => ({
+                ...candidate,
+                endpoint: buildEndpoint(candidate.address, boundPort || requestedPort)
+            }))
+            .filter(candidate => candidate.endpoint);
+        const publicCandidate = getPublicIPv4EndpointCandidate();
+        const externalCandidateEndpoints = publicCandidate ? [publicCandidate] : [];
+        const endpoint = getAgentEndpoint();
+        const endpointCandidates = [
+            endpoint,
+            ...candidateEndpoints.map(candidate => candidate.endpoint),
+            ...externalCandidateEndpoints.map(candidate => candidate.endpoint)
+        ].filter((value, index, all) => value && all.indexOf(value) === index);
+        const wildcardWithoutReachableAddress =
+            !publicEndpoint
+            && !publicHost
+            && isWildcardHost(host)
+            && candidateDetails.length === 0;
+        const reason = getAccountRouteEndpointReason(endpoint, { wildcardWithoutReachableAddress });
+        const parsed = parseManagerEndpoint(endpoint);
+        return {
+            endpoint,
+            host: parsed?.host || '',
+            port: parsed?.port || 0,
+            accountRouteReady: reason === 'ok',
+            reason,
+            candidates: endpointCandidates,
+            candidateDetails: [
+                ...candidateEndpoints,
+                ...externalCandidateEndpoints
+            ]
+        };
+    }
+
+    function getActiveHostTarget() {
+        if (!hostTarget) {
+            return null;
+        }
+
+        const expiresMs = Date.parse(hostTarget.expiresAt || '');
+        if (Number.isFinite(expiresMs) && expiresMs <= Date.now()) {
+            const expiredTarget = hostTarget;
+            hostTarget = null;
+            emitRemoteEvent('RemoteHostTargetExpired', null, {
+                hostTarget: {
+                    ...expiredTarget,
+                    active: false
+                }
+            });
+            return null;
+        }
+
+        return hostTarget;
+    }
+
+    function serializeHostTarget(target = getActiveHostTarget()) {
+        if (!target) {
+            return {
+                active: false,
+                nodeId: '',
+                leaseId: '',
+                hostInstanceId: '',
+                endpoint: '',
+                endpointCandidates: [],
+                activatedAt: '',
+                updatedAt: '',
+                expiresAt: ''
+            };
+        }
+
+        return {
+            active: true,
+            nodeId: target.nodeId,
+            leaseId: target.leaseId,
+            hostInstanceId: target.hostInstanceId || hostInstanceId,
+            endpoint: target.endpoint,
+            endpointCandidates: Array.isArray(target.endpointCandidates) ? [...target.endpointCandidates] : [target.endpoint].filter(Boolean),
+            activatedAt: target.activatedAt,
+            updatedAt: target.updatedAt,
+            expiresAt: target.expiresAt
+        };
+    }
+
+    async function setHostTarget(options = {}) {
+        const enabled = options.enabled !== false;
+        const nodeId = safeString(options.nodeId, 128);
+        if (!enabled) {
+            const previous = getActiveHostTarget();
+            if (!previous) {
+                return {
+                    ok: true,
+                    active: false,
+                    hostTarget: serializeHostTarget(null)
+                };
+            }
+
+            if (nodeId && previous.nodeId && nodeId !== previous.nodeId) {
+                return {
+                    ok: false,
+                    error: 'host-target-node-mismatch',
+                    active: true,
+                    hostTarget: serializeHostTarget(previous)
+                };
+            }
+
+            hostTarget = null;
+            emitRemoteEvent('RemoteHostTargetCleared', null, {
+                hostTarget: {
+                    ...serializeHostTarget(previous),
+                    active: false
+                }
+            });
+            return {
+                ok: true,
+                active: false,
+                hostTarget: serializeHostTarget(null)
+            };
+        }
+
+        if (!nodeId) {
+            return {
+                ok: false,
+                error: 'missing-node-id',
+                active: false,
+                hostTarget: serializeHostTarget()
+            };
+        }
+
+        const now = new Date();
+        const leaseMs = clampNumber(options.leaseMs, 5000, 10 * 60 * 1000, DEFAULT_HOST_TARGET_LEASE_MS);
+        const previous = getActiveHostTarget();
+        const activeSameNode = previous?.nodeId === nodeId;
+        await refreshPublicIPv4Candidate({ force: options.refreshPublicIp === true || options.takeover === true });
+        const routeInfo = getAgentEndpointRouteInfo();
+        hostTarget = {
+            nodeId,
+            leaseId: activeSameNode && previous?.leaseId
+                ? previous.leaseId
+                : (safeString(options.leaseId, 128) || crypto.randomUUID()),
+            hostInstanceId,
+            endpoint: routeInfo.endpoint,
+            endpointCandidates: routeInfo.candidates,
+            activatedAt: activeSameNode && previous?.activatedAt ? previous.activatedAt : now.toISOString(),
+            updatedAt: now.toISOString(),
+            expiresAt: new Date(now.getTime() + leaseMs).toISOString()
+        };
+
+        emitRemoteEvent('RemoteHostTargetSet', null, {
+            hostTarget: serializeHostTarget(hostTarget),
+            replacedNodeId: previous && previous.nodeId !== nodeId ? previous.nodeId : ''
+        });
+        if (!activeSameNode || !routeInfo.accountRouteReady) {
+            logEvent(
+                'remote',
+                `host target ${routeInfo.accountRouteReady ? 'account-ready' : 'local-only'} endpoint=${routeInfo.endpoint} candidates=${routeInfo.candidates.length} reason=${routeInfo.reason}`,
+                'remote');
+        }
+        return {
+            ok: true,
+            active: true,
+            hostTarget: serializeHostTarget(hostTarget)
+        };
+    }
+
+    function getStatus({ includeSecrets = false } = {}) {
+        const connectedDevices = [...devices.values()].filter(device => device.connected).length;
+        const activeHostTarget = serializeHostTarget();
+        const routeInfo = getAgentEndpointRouteInfo();
+        return {
+            enabled,
+            started,
+            host,
+            agentHost: routeInfo.host || getAnnouncedHost(),
+            port: boundPort || requestedPort,
+            protocol: 'tcp-jsonl',
+            protocolVersion: REMOTE_PROTOCOL_VERSION,
+            agentProtocol: REMOTE_AGENT_PROTOCOL,
+            frameProtocol: buildRemoteFrameProtocolDescriptor(),
+            frameModes: getSupportedRemoteFrameModeProfiles(),
+            heartbeatMs,
+            taskTimeoutMs,
+            managerPackage,
+            managerVersion,
+            hostInstanceId,
+            agentPackage: '@livedesk/client',
+            agentEndpoint: routeInfo.endpoint,
+            agentEndpointAccountRouteReady: routeInfo.accountRouteReady,
+            agentEndpointRouteReason: routeInfo.reason,
+            agentEndpointCandidates: routeInfo.candidates,
+            agentEndpointCandidateDetails: routeInfo.candidateDetails,
+            pairToken: includeSecrets ? pairToken : undefined,
+            pairTokenPreview: maskToken(pairToken),
+            deviceCount: devices.size,
+            connectedDeviceCount: connectedDevices,
+            canvasDeviceListMode: 'all-devices',
+            canvasPagination: 'none',
+            hostTargetActive: activeHostTarget.active,
+            hostTargetNodeId: activeHostTarget.nodeId,
+            hostTargetLeaseId: activeHostTarget.leaseId,
+            hostTargetHostInstanceId: activeHostTarget.hostInstanceId,
+            hostTargetEndpoint: activeHostTarget.endpoint,
+            hostTargetEndpointCandidates: activeHostTarget.endpointCandidates,
+            hostTargetActivatedAt: activeHostTarget.activatedAt,
+            hostTargetUpdatedAt: activeHostTarget.updatedAt,
+            hostTargetExpiresAt: activeHostTarget.expiresAt,
+            publicIPv4Address: publicIPv4Cache.address,
+            publicIPv4UpdatedAt: publicIPv4Cache.updatedAt ? new Date(publicIPv4Cache.updatedAt).toISOString() : '',
+            publicIPv4Error: publicIPv4Cache.error,
+            externalExposure: isWildcardHost(host) || !isLoopbackHost(host),
+            lastError
+        };
+    }
+
+    function listDevices(options = {}) {
+        const serializeOptions = {
+            includeDataUrl: options.includeDataUrl === true
+        };
+        return [...devices.values()]
+            .map(device => serializeDevice(device, serializeOptions))
+            .filter(Boolean)
+            .sort((a, b) => {
+                const nameCompare = String(a.deviceName || '').localeCompare(String(b.deviceName || ''));
+                const slotA = Number(a.slotNumber || 0);
+                const slotB = Number(b.slotNumber || 0);
+                if (slotA > 0 || slotB > 0) {
+                    if (slotA <= 0) {
+                        return 1;
+                    }
+                    if (slotB <= 0) {
+                        return -1;
+                    }
+                    if (slotA !== slotB) {
+                        return slotA - slotB;
+                    }
+                }
+                if (nameCompare !== 0) {
+                    return nameCompare;
+                }
+
+                return String(a.deviceId).localeCompare(String(b.deviceId));
+            });
+    }
+
+    function listDeviceFrames(options = {}) {
+        const ids = Array.isArray(options.deviceIds)
+            ? options.deviceIds.map(value => safeString(value, 160)).filter(Boolean)
+            : [];
+        const idSet = ids.length > 0 ? new Set(ids) : null;
+        const includeThumbnail = options.includeThumbnail !== false;
+        const includeLive = options.includeLive !== false;
+
+        return [...devices.values()]
+            .filter(device => !idSet || idSet.has(device.deviceId))
+            .map(device => ({
+                deviceId: device.deviceId,
+                connected: device.connected === true,
+                thumbnailEnabled: readCapabilityFlag(device.capabilities, 'thumbnail'),
+                liveStreamActive: device.activeLiveStream?.active === true,
+                liveStreamId: device.activeLiveStream?.streamId || '',
+                liveStreamFps: Number(device.activeLiveStream?.fps || 0),
+                liveStreamLastFrameAt: device.activeLiveStream?.lastFrameAt || '',
+                thumbnail: includeThumbnail
+                    ? serializeRemoteFrame(device.latestThumbnail, device.deviceId, 'thumbnail', { includeDataUrl: false })
+                    : null,
+                live: includeLive
+                    ? serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', { includeDataUrl: false })
+                    : null
+            }))
+            .sort((a, b) => String(a.deviceId).localeCompare(String(b.deviceId)));
+    }
+
+    function listTaskBatches() {
+        return [...taskBatches.values()]
+            .map(serializeTaskBatch)
+            .filter(Boolean)
+            .sort((left, right) => String(right.requestedAt || '').localeCompare(String(left.requestedAt || '')));
+    }
+
+    function getLatestTaskBatch() {
+        return listTaskBatches()[0] || null;
+    }
+
+    function emitRemoteEvent(type, device = null, extra = {}) {
+        emitEvent(type, {
+            ...extra,
+            remoteHub: getStatus({ includeSecrets: false }),
+            device: serializeDevice(device)
+        });
+    }
+
+    function makeSyntheticFrame(device, streamId, mode = 'thumbnail', options = {}) {
+        const now = new Date().toISOString();
+        const descriptor = buildRemoteFrameTransferDescriptor(mode, mode === 'thumbnail' ? 'thumbnail' : DEFAULT_REMOTE_FRAME_MODE);
+        const frameSeq = Number(device?.counters?.thumbnailFramesReceived || 0)
+            + Number(device?.counters?.liveFramesReceived || 0)
+            + 1;
+        return {
+            streamId: safeString(streamId, 128) || `${mode}-${Date.now()}`,
+            frameSeq,
+            commandId: safeString(options.commandId, 128),
+            width: clampNumber(options.width, 2, 2560, mode === 'remote-fast' ? 960 : 360),
+            height: clampNumber(options.height, 1, 1440, mode === 'remote-fast' ? 540 : 220),
+            mimeType: 'image/png',
+            format: 'image/png',
+            mode,
+            frameMode: descriptor.frameMode,
+            frameProfile: descriptor.frameProfile,
+            encoding: descriptor.encoding,
+            codec: 'png',
+            compression: 'image/png',
+            transferProtocol: descriptor.transferProtocol,
+            transferProtocolVersion: descriptor.transferProtocolVersion,
+            handshake: descriptor.handshake,
+            fps: clampNumber(options.fps, 1, 24, mode === 'remote-fast' ? 20 : 1),
+            capturedAt: now,
+            receivedAt: now,
+            byteLength: 68,
+            transport: 'synthetic',
+            contentHash: SYNTHETIC_FRAME_HASH,
+            captureMs: 0,
+            sameContentStreak: 0,
+            dataUrl: SYNTHETIC_FRAME_DATA_URL,
+            payload: SYNTHETIC_FRAME_PAYLOAD,
+            accessToken: createFrameAccessToken()
+        };
+    }
+
+    function applySyntheticThumbnail(device, command) {
+        if (!device) {
+            return null;
+        }
+
+        const payload = command?.payload || {};
+        const frame = makeSyntheticFrame(device, payload.streamId || 'synthetic-thumb', 'thumbnail', {
+            commandId: command?.commandId,
+            width: payload.maxWidth || 360,
+            height: payload.maxHeight || 220
+        });
+        delete frame.mode;
+        delete frame.fps;
+        device.latestThumbnail = frame;
+        rememberRecentFramePayload(device, 'thumbnail', frame);
+        device.lastSeenAt = frame.receivedAt;
+        device.counters.thumbnailFramesReceived += 1;
+        emitRemoteEvent('RemoteFrameReceived', device, {
+            streamId: frame.streamId,
+            frameSeq: frame.frameSeq,
+            synthetic: true
+        });
+        return frame;
+    }
+
+    function applySyntheticLiveFrame(device, streamId, options = {}) {
+        if (!device?.activeLiveStream?.active) {
+            return null;
+        }
+
+        const frame = makeSyntheticFrame(device, streamId || device.activeLiveStream.streamId, device.activeLiveStream.mode || DEFAULT_REMOTE_FRAME_MODE, {
+            commandId: options.commandId || device.activeLiveStream.commandId,
+            width: options.maxWidth || 960,
+            height: options.maxHeight || 540,
+            fps: options.fps || device.activeLiveStream.fps
+        });
+        device.latestLiveFrame = frame;
+        rememberRecentFramePayload(device, 'live', frame);
+        emitFrame({
+            kind: 'live',
+            deviceId: device.deviceId,
+            frame: serializeRemoteFrame(frame, device.deviceId, 'live', { includeDataUrl: false }),
+            payload: frame.payload,
+            mimeType: frame.mimeType,
+            byteLength: frame.byteLength
+        });
+        device.activeLiveStream.lastFrameAt = frame.receivedAt;
+        device.activeLiveStream.lastFrameSeq = frame.frameSeq;
+        device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;
+        device.lastSeenAt = frame.receivedAt;
+        device.counters.liveFramesReceived += 1;
+        emitRemoteEvent('RemoteFrameReceived', device, {
+            streamId: frame.streamId,
+            frameSeq: frame.frameSeq,
+            synthetic: true
+        });
+        return frame;
+    }
+
+    function closeExistingDeviceSocket(deviceId, nextSessionId) {
+        const existing = devices.get(deviceId);
+        if (!existing?.socket || existing.socket.destroyed) {
+            return;
+        }
+
+        existing.lastDisconnectReason = 'replaced-by-new-session';
+        failAllPendingTasks(existing, 'replaced-by-new-session');
+        writeJsonLine(existing.socket, {
+            type: 'disconnect',
+            reason: 'replaced-by-new-session',
+            nextSessionId
+        });
+        existing.socket.destroy();
+    }
+
+    function getDeviceActivityMs(device) {
+        return Math.max(
+            Date.parse(device?.lastSeenAt || '') || 0,
+            Date.parse(device?.lastStatusAt || '') || 0,
+            Date.parse(device?.connectedAt || '') || 0
+        );
+    }
+
+    function isDeviceConnectionFresh(device, nowMs = Date.now()) {
+        if (!device?.connected || !device.socket || device.socket.destroyed) {
+            return false;
+        }
+
+        const lastActivityMs = getDeviceActivityMs(device);
+        if (!lastActivityMs) {
+            return true;
+        }
+
+        const freshnessMs = Math.max(DUPLICATE_DEVICE_ACTIVE_REJECT_MS, heartbeatMs * 3);
+        return nowMs - lastActivityMs <= freshnessMs;
+    }
+
+    function rejectDuplicateActiveDevice(socket, existing, attemptedSessionId) {
+        const retryAfterMs = Math.max(heartbeatMs, duplicateDeviceRetryAfterMs);
+        writeJsonLine(socket, {
+            type: 'disconnect',
+            reason: 'duplicate-device-active',
+            retryAfterMs,
+            activeSessionId: existing.sessionId,
+            attemptedSessionId
+        });
+
+        existing.counters.duplicateConnectionsRejected = (existing.counters.duplicateConnectionsRejected || 0) + 1;
+        const nowMs = Date.now();
+        const lastLoggedAt = duplicateDeviceLogAt.get(existing.deviceId) || 0;
+        if (nowMs - lastLoggedAt >= duplicateDeviceLogThrottleMs) {
+            duplicateDeviceLogAt.set(existing.deviceId, nowMs);
+            logEvent(
+                'remote',
+                `duplicate device connection suppressed ${existing.deviceName} (${existing.deviceId}); keeping active session ${existing.sessionId}`,
+                'remote');
+        }
+
+        try {
+            socket.end?.();
+        } catch {
+            // Best-effort graceful close before hard destroy.
+        }
+
+        setTimeout(() => {
+            try {
+                socket.destroy?.();
+            } catch {
+                // Ignore destroy failures.
+            }
+        }, 25).unref?.();
+    }
+
+    function clearSyntheticFleet() {
+        let removed = 0;
+        for (const [deviceId, device] of devices.entries()) {
+            if (device.synthetic === true) {
+                devices.delete(deviceId);
+                removed += 1;
+            }
+        }
+
+        return { ok: true, removed, total: devices.size };
+    }
+
+    function seedSyntheticFleet(options = {}) {
+        const count = clampNumber(options.count, 1, MAX_SYNTHETIC_DEVICES, 250);
+        const connectedRatio = Math.max(0, Math.min(1, Number(options.connectedRatio ?? 0.88)));
+        const thumbnailRatio = Math.max(0, Math.min(1, Number(options.thumbnailRatio ?? 0.7)));
+        const aiAssistRatio = Math.max(0, Math.min(1, Number(options.aiAssistRatio ?? 0.35)));
+        const liveCount = clampNumber(options.liveCount, 0, Math.min(count, 24), Math.min(6, count));
+        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 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'];
+
+        if (replace) {
+            clearSyntheticFleet();
+        }
+
+        let connected = 0;
+        let aiAssist = 0;
+        let live = 0;
+        for (let index = 0; index < count; index += 1) {
+            const ordinal = index + 1;
+            const deviceId = `synthetic-${String(ordinal).padStart(4, '0')}`;
+            const isConnected = index / count < connectedRatio;
+            const hasThumbnail = index / count < thumbnailRatio;
+            const hasAiAssist = index / count < aiAssistRatio;
+            const isLive = isConnected && index < liveCount;
+            const seenAt = new Date(now.getTime() - index * 1350).toISOString();
+            const connectedAt = new Date(now.getTime() - (index + 8) * 60000).toISOString();
+            const platform = platforms[index % platforms.length];
+            const usedMemRatio = Number((0.18 + (index % 71) / 100).toFixed(2));
+            const load1 = Number(((index % 19) / 3).toFixed(2));
+            const cpuCores = platform === 'darwin' ? 10 : index % 3 === 0 ? 24 : 12;
+            const cpuUsageRatio = Number(Math.min(0.96, Math.max(0.04, load1 / Math.max(1, cpuCores))).toFixed(2));
+            const diskTotalBytes = (index % 4 === 0 ? 4 : 2) * 1024 ** 4;
+            const diskUsedRatio = Number((0.22 + (index % 61) / 100).toFixed(2));
+            const diskFreeBytes = Math.round(diskTotalBytes * (1 - diskUsedRatio));
+            const temperatureC = 42 + (index % 48);
+            const gpuUsageRatio = Number(Math.min(0.98, Math.max(0.03, ((index * 7) % 89) / 100)).toFixed(2));
+            const gpuMemoryTotalBytes = (platform === 'darwin' ? 32 : index % 3 === 0 ? 24 : 12) * 1024 ** 3;
+            const gpuMemoryUsedRatio = Number((0.2 + ((index * 5) % 67) / 100).toFixed(2));
+            const gpuMemoryFreeBytes = Math.round(gpuMemoryTotalBytes * (1 - gpuMemoryUsedRatio));
+            const npuUsageRatio = index % 5 === 4
+                ? undefined
+                : Number(Math.min(0.95, Math.max(0.02, ((index * 11) % 73) / 100)).toFixed(2));
+            const npuTops = index % 5 === 4 ? 0 : platform === 'darwin' ? 38 : index % 2 === 0 ? 45 : 16;
+            const machineKind = machineKinds[index % machineKinds.length];
+            const workloadRole = workloadRoles[index % workloadRoles.length];
+            const toolBusy = index % 9 === 0;
+            const toolOnline = index % 4 !== 3;
+            const taskStatus = index % 17 === 0
+                ? 'failed'
+                : index % 5 === 0
+                    ? 'completed'
+                    : index % 7 === 0
+                        ? 'queued'
+                        : '';
+            const latestTask = taskStatus
+                ? {
+                    taskId: `synthetic-task-${ordinal}`,
+                    commandId: `synthetic-command-${ordinal}`,
+                    title: taskStatus === 'failed' ? 'Synthetic issue check' : 'Synthetic status task',
+                    instructionPreview: 'Synthetic fleet scale validation task.',
+                    status: taskStatus,
+                    approvalLevel: hasAiAssist ? 'ai-assist' : 'task-only',
+                    requestedAt: seenAt,
+                    sentAt: seenAt,
+                    updatedAt: seenAt,
+                    completedAt: taskStatus === 'completed' || taskStatus === 'failed' ? seenAt : '',
+                    error: taskStatus === 'failed' ? 'Synthetic task failure sample.' : '',
+                    resultKind: 'synthetic-agent-task',
+                    resultModel: hasAiAssist ? 'synthetic-ai' : '',
+                    resultResponseId: hasAiAssist ? `synthetic-response-${ordinal}` : '',
+                    resultSummary: taskStatus === 'failed'
+                        ? 'Synthetic task reported a sample issue.'
+                        : 'Synthetic task completed for scale validation.'
+                }
+                : null;
+            const device = {
+                socket: null,
+                synthetic: true,
+                deviceId,
+                sessionId: `synthetic-session-${ordinal}`,
+                deviceName: `${machineKind} ${String(ordinal).padStart(3, '0')}`,
+                hostname: `synthetic-host-${String(ordinal).padStart(4, '0')}`,
+                platform,
+                arch: index % 4 === 0 ? 'arm64' : 'x64',
+                pid: 0,
+                agentVersion: 'synthetic-scale',
+                capabilities: {
+                    status: true,
+                    thumbnail: hasThumbnail,
+                    control: false,
+                    liveStream: true,
+                    computerAgent: true,
+                    taskDispatch: true,
+                    aiAssist: hasAiAssist,
+                    aiModel: hasAiAssist ? 'synthetic-ai' : '',
+                    aiProvider: hasAiAssist ? 'synthetic' : ''
+                },
+                connected: isConnected,
+                connectedAt: isConnected ? connectedAt : '',
+                disconnectedAt: isConnected ? '' : seenAt,
+                lastSeenAt: seenAt,
+                lastStatusAt: seenAt,
+                lastDisconnectReason: isConnected ? '' : 'synthetic-offline',
+                remoteAddress: 'synthetic.local',
+                remotePort: 0,
+                status: {
+                    platform,
+                    release: platform === 'win32' ? 'Windows 11' : platform === 'darwin' ? 'macOS' : 'Linux',
+                    uptimeSec: (ordinal * 791) % 1209600,
+                    role: workloadRole,
+                    usedMemRatio,
+                    totalMem: cpuCores >= 20 ? 128 * 1024 ** 3 : 64 * 1024 ** 3,
+                    freeMem: Math.round((cpuCores >= 20 ? 128 * 1024 ** 3 : 64 * 1024 ** 3) * (1 - usedMemRatio)),
+                    loadavg: [load1, Math.max(0, load1 - 0.2), Math.max(0, load1 - 0.4)],
+                    cpu: {
+                        cores: cpuCores,
+                        usageRatio: cpuUsageRatio,
+                        load1
+                    },
+                    memory: {
+                        usedRatio: usedMemRatio
+                    },
+                    disk: {
+                        root: platform === 'win32' ? 'C:\\' : '/',
+                        totalBytes: diskTotalBytes,
+                        freeBytes: diskFreeBytes,
+                        usedRatio: diskUsedRatio
+                    },
+                    gpu: {
+                        name: gpuNames[index % gpuNames.length],
+                        usageRatio: gpuUsageRatio,
+                        temperatureC: temperatureC + 3,
+                        memory: {
+                            totalBytes: gpuMemoryTotalBytes,
+                            freeBytes: gpuMemoryFreeBytes,
+                            usedRatio: gpuMemoryUsedRatio
+                        }
+                    },
+                    npu: {
+                        name: npuNames[index % npuNames.length],
+                        usageRatio: npuUsageRatio,
+                        tops: npuTops
+                    },
+                    thermal: {
+                        cpuC: temperatureC,
+                        gpuC: temperatureC + 3
+                    },
+                    network: {
+                        link: index % 6 === 0 ? '2.5GbE' : '1GbE',
+                        latencyMs: 1 + (index % 12),
+                        rxMbps: 35 + ((index * 13) % 640),
+                        txMbps: 12 + ((index * 17) % 220),
+                        usageRatio: Number(Math.min(0.94, ((index * 9) % 81) / 100).toFixed(2))
+                    },
+                    workload: {
+                        role: workloadRole,
+                        status: taskStatus || (toolBusy ? 'running' : 'idle'),
+                        title: taskStatus ? 'Fleet validation task' : toolBusy ? 'Processing local job' : 'idle',
+                        summary: taskStatus ? 'Synthetic status for fleet-scale validation.' : ''
+                    },
+                    tools: {
+                        ollama: {
+                            status: toolOnline ? (toolBusy ? 'busy' : 'online') : 'offline',
+                            port: 11434,
+                            version: toolOnline ? 'local' : ''
+                        },
+                        lmStudio: {
+                            status: index % 5 === 0 ? 'online' : 'offline',
+                            port: 1234
+                        },
+                        comfyui: {
+                            status: index % 3 === 0 ? (toolBusy ? 'busy' : 'online') : 'offline',
+                            port: 8188
+                        },
+                        stableDiffusion: {
+                            status: index % 7 === 0 ? 'online' : 'offline',
+                            port: 7860
+                        }
+                    }
+                },
+                latestThumbnail: null,
+                latestLiveFrame: null,
+                recentFramePayloads: {
+                    thumbnail: [],
+                    live: []
+                },
+                activeLiveStream: null,
+                activeAudioStream: null,
+                latestAudioFrame: null,
+                latestTask,
+                recentTasks: latestTask ? [latestTask] : [],
+                pendingTaskCommands: new Map(),
+                pendingTaskTimers: new Map(),
+                counters: createDeviceCounters({
+                    messagesReceived: 1,
+                    statusReceived: 1,
+                    tasksQueued: latestTask ? 1 : 0,
+                    taskResultsReceived: latestTask && ['completed', 'failed'].includes(latestTask.status) ? 1 : 0,
+                    taskResultsFailed: latestTask?.status === 'failed' ? 1 : 0
+                })
+            };
+
+            if (hasThumbnail) {
+                const frame = makeSyntheticFrame(device, `synthetic-thumb-${ordinal}`, 'thumbnail', {
+                    width: 360,
+                    height: 220
+                });
+                delete frame.mode;
+                delete frame.fps;
+                frame.receivedAt = seenAt;
+                frame.capturedAt = seenAt;
+                device.latestThumbnail = frame;
+                rememberRecentFramePayload(device, 'thumbnail', frame);
+                device.counters.thumbnailFramesReceived = 1;
+            }
+
+            if (isLive) {
+                const transfer = buildRemoteFrameTransferDescriptor(DEFAULT_REMOTE_FRAME_MODE);
+                device.activeLiveStream = {
+                    streamId: `synthetic-live-${ordinal}`,
+                    commandId: `synthetic-live-command-${ordinal}`,
+                    active: true,
+                    open: true,
+                    openedAt: seenAt,
+                    openTransport: 'synthetic',
+                    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,
+                    fps: 20,
+                    startedAt: seenAt,
+                    stoppedAt: '',
+                    stopReason: '',
+                    lastFrameAt: '',
+                    lastFrameSeq: 0,
+                    framesReceived: 0
+                };
+                applySyntheticLiveFrame(device, device.activeLiveStream.streamId, {
+                    commandId: device.activeLiveStream.commandId,
+                    fps: 20
+                });
+                live += 1;
+            }
+
+            if (isConnected) {
+                connected += 1;
+            }
+            if (hasAiAssist) {
+                aiAssist += 1;
+            }
+            devices.set(deviceId, device);
+        }
+
+        emitRemoteEvent('RemoteSyntheticFleetSeeded', null, {
+            count,
+            connected,
+            aiAssist,
+            live
+        });
+        return {
+            ok: true,
+            synthetic: true,
+            seeded: count,
+            connected,
+            aiAssist,
+            live,
+            total: devices.size,
+            max: MAX_SYNTHETIC_DEVICES
+        };
+    }
+
+    function attachDevice(socket, hello) {
+        const nowMs = Date.now();
+        const now = new Date(nowMs).toISOString();
+        const sessionId = crypto.randomUUID();
+        const deviceId = normalizeDeviceId(hello.deviceId);
+        const existing = devices.get(deviceId);
+
+        if (isDeviceConnectionFresh(existing, nowMs)) {
+            rejectDuplicateActiveDevice(socket, existing, sessionId);
+            return null;
+        }
+
+        closeExistingDeviceSocket(deviceId, sessionId);
+
+        const frameProtocol = typeof hello.frameProtocol === 'object' && hello.frameProtocol
+            ? { ...hello.frameProtocol }
+            : null;
+        const frameModes = Array.isArray(hello.frameModes)
+            ? hello.frameModes.map(normalizeIncomingFrameModeProfile).filter(Boolean)
+            : [];
+        const capabilities = typeof hello.capabilities === 'object' && hello.capabilities
+            ? { ...hello.capabilities }
+            : {};
+        if (!capabilities.frameProtocol) {
+            capabilities.frameProtocol = frameProtocol || buildRemoteFrameProtocolDescriptor();
+        }
+        if (!capabilities.frameModes) {
+            capabilities.frameModes = frameModes.length > 0
+                ? frameModes.map(profile => ({ ...profile }))
+                : getSupportedRemoteFrameModeProfiles();
+        }
+
+        const device = {
+            socket,
+            deviceId,
+            sessionId,
+            deviceName: safeString(hello.deviceName || hello.hostname || deviceId, 120),
+            hostname: safeString(hello.hostname, 120),
+            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,
+            protocolVersion: Number.isFinite(Number(hello.protocolVersion)) ? Math.max(1, Math.floor(Number(hello.protocolVersion))) : 1,
+            frameProtocol: frameProtocol || buildRemoteFrameProtocolDescriptor(),
+            frameModes: frameModes.length > 0 ? frameModes : getSupportedRemoteFrameModeProfiles(),
+            capabilities,
+            connected: true,
+            connectedAt: now,
+            disconnectedAt: '',
+            lastSeenAt: now,
+            lastStatusAt: '',
+            lastDisconnectReason: '',
+            remoteAddress: socket.remoteAddress || '',
+            remotePort: socket.remotePort || 0,
+            status: {},
+            latestThumbnail: null,
+            latestLiveFrame: null,
+            recentFramePayloads: {
+                thumbnail: [],
+                live: []
+            },
+            activeLiveStream: null,
+            activeAudioStream: null,
+            latestAudioFrame: null,
+            latestTask: null,
+            recentTasks: [],
+            pendingTaskCommands: new Map(),
+            pendingTaskTimers: new Map(),
+            synthetic: false,
+            counters: createDeviceCounters({ messagesReceived: 1 })
+        };
+
+        devices.set(deviceId, device);
+        sockets.set(socket, deviceId);
+        writeJsonLine(socket, {
+            type: 'welcome',
+            protocol: REMOTE_AGENT_PROTOCOL,
+            protocolVersion: REMOTE_PROTOCOL_VERSION,
+            sessionId,
+            deviceId,
+            heartbeatMs,
+            frameProtocol: buildRemoteFrameProtocolDescriptor(),
+            frameModes: getSupportedRemoteFrameModeProfiles(),
+            serverTime: now
+        });
+
+        logEvent('remote', `device connected ${device.deviceName} (${deviceId})`, 'success');
+        emitRemoteEvent('RemoteDeviceConnected', device);
+        return device;
+    }
+
+    function detachSocket(socket, reason = 'socket-closed') {
+        const deviceId = sockets.get(socket);
+        sockets.delete(socket);
+        if (!deviceId) {
+            return;
+        }
+
+        const device = devices.get(deviceId);
+        if (!device || device.socket !== socket) {
+            return;
+        }
+
+        device.connected = false;
+        device.socket = null;
+        device.disconnectedAt = new Date().toISOString();
+        device.lastDisconnectReason = reason;
+        if (device.activeLiveStream) {
+            device.activeLiveStream.active = false;
+            device.activeLiveStream.stoppedAt = device.disconnectedAt;
+            device.activeLiveStream.stopReason = reason;
+        }
+        failAllPendingTasks(device, 'device-disconnected');
+        logWarn('remote', `device disconnected ${device.deviceName} (${deviceId}): ${reason}`);
+        emitRemoteEvent('RemoteDeviceDisconnected', device, { reason });
+    }
+
+    function rememberDeviceTask(device, task) {
+        if (!device || !task) {
+            return null;
+        }
+
+        const existingIndex = device.recentTasks.findIndex(item =>
+            item.taskId === task.taskId || item.commandId === task.commandId);
+        if (existingIndex >= 0) {
+            device.recentTasks.splice(existingIndex, 1);
+        }
+
+        device.recentTasks.unshift(task);
+        if (device.recentTasks.length > RECENT_TASK_LIMIT) {
+            device.recentTasks.length = RECENT_TASK_LIMIT;
+        }
+
+        device.latestTask = task;
+        if (task.commandId) {
+            device.pendingTaskCommands.set(task.commandId, task);
+        }
+
+        return task;
+    }
+
+    function trimTaskBatches() {
+        const ordered = [...taskBatches.values()]
+            .sort((left, right) => String(right.requestedAt || '').localeCompare(String(left.requestedAt || '')));
+        for (const batch of ordered.slice(RECENT_TASK_BATCH_LIMIT)) {
+            taskBatches.delete(batch.batchId);
+        }
+    }
+
+    function beginTaskBatch(deviceIds, options = {}) {
+        const targets = [...new Set((deviceIds || [])
+            .map(deviceId => safeString(deviceId, 128))
+            .filter(Boolean))]
+            .slice(0, 500);
+        const now = new Date().toISOString();
+        const instruction = safeText(options.instruction, MAX_AGENT_TASK_CHARS);
+        const batchId = safeString(options.batchId, 128) || crypto.randomUUID();
+        const title = safeString(options.title, 120)
+            || safeString(instruction.split(/\r?\n/)[0], 120)
+            || 'Remote task batch';
+        const batch = {
+            batchId,
+            title,
+            instructionPreview: safeText(instruction, 320),
+            approvalLevel: normalizeApprovalLevel(options.approvalLevel),
+            status: targets.length > 0 ? 'running' : 'failed',
+            requestedAt: now,
+            updatedAt: now,
+            total: targets.length,
+            queued: 0,
+            pending: 0,
+            completed: 0,
+            failed: targets.length > 0 ? 0 : 1,
+            timedOut: 0,
+            results: targets.map(deviceId => ({
+                deviceId,
+                ok: false,
+                status: 'targeted',
+                error: '',
+                commandId: '',
+                taskId: '',
+                approvalLevel: normalizeApprovalLevel(options.approvalLevel),
+                updatedAt: now
+            }))
+        };
+
+        taskBatches.set(batchId, batch);
+        trimTaskBatches();
+        return batch;
+    }
+
+    function getTaskBatchItem(batch, deviceId) {
+        if (!batch) {
+            return null;
+        }
+
+        const id = safeString(deviceId, 128);
+        if (!id) {
+            return null;
+        }
+
+        let item = batch.results.find(result => result.deviceId === id);
+        if (!item) {
+            item = {
+                deviceId: id,
+                ok: false,
+                status: 'targeted',
+                error: '',
+                commandId: '',
+                taskId: '',
+                approvalLevel: batch.approvalLevel,
+                updatedAt: new Date().toISOString()
+            };
+            batch.results.push(item);
+            batch.total = batch.results.length;
+        }
+
+        return item;
+    }
+
+    function recalculateTaskBatch(batch) {
+        if (!batch) {
+            return null;
+        }
+
+        const results = Array.isArray(batch.results) ? batch.results : [];
+        batch.total = results.length;
+        batch.queued = results.filter(item => item.ok === true).length;
+        batch.completed = results.filter(item => item.status === 'completed').length;
+        batch.failed = results.filter(item => item.status === 'failed' || (item.ok === false && !!item.error)).length;
+        batch.timedOut = results.filter(item => item.error === 'task-timeout').length;
+        batch.pending = results.filter(item =>
+            item.ok === true
+            && item.status !== 'completed'
+            && item.status !== 'failed').length;
+        batch.updatedAt = new Date().toISOString();
+
+        if (batch.total === 0) {
+            batch.status = 'failed';
+        } else if (batch.completed + batch.failed >= batch.total) {
+            batch.status = batch.failed > 0 ? 'completed-with-failures' : 'completed';
+        } else if (batch.queued > 0) {
+            batch.status = 'running';
+        } else {
+            batch.status = 'failed';
+        }
+
+        return batch;
+    }
+
+    function syncTaskBatchFromTask(device, task) {
+        const batchId = safeString(task?.batchId, 128);
+        if (!batchId) {
+            return null;
+        }
+
+        const batch = taskBatches.get(batchId);
+        if (!batch) {
+            return null;
+        }
+
+        const item = getTaskBatchItem(batch, device?.deviceId);
+        if (!item) {
+            return null;
+        }
+
+        item.ok = true;
+        item.status = safeString(task.status, 40) || 'queued';
+        item.error = safeString(task.error, 500);
+        item.commandId = safeString(task.commandId, 128);
+        item.taskId = safeString(task.taskId, 128);
+        item.approvalLevel = normalizeApprovalLevel(task.approvalLevel || batch.approvalLevel);
+        item.updatedAt = task.updatedAt || task.completedAt || task.sentAt || new Date().toISOString();
+        return recalculateTaskBatch(batch);
+    }
+
+    function syncTaskBatchDispatchFailure(batchId, deviceId, error, extra = {}) {
+        const batch = taskBatches.get(safeString(batchId, 128));
+        if (!batch) {
+            return null;
+        }
+
+        const item = getTaskBatchItem(batch, deviceId);
+        if (!item) {
+            return null;
+        }
+
+        item.ok = false;
+        item.status = 'failed';
+        item.error = safeString(error, 500) || 'task-dispatch-failed';
+        item.commandId = safeString(extra.commandId, 128);
+        item.taskId = safeString(extra.taskId, 128);
+        item.approvalLevel = normalizeApprovalLevel(extra.approvalLevel || batch.approvalLevel);
+        item.updatedAt = new Date().toISOString();
+        return recalculateTaskBatch(batch);
+    }
+
+    function clearTaskTimeout(device, commandId) {
+        const key = safeString(commandId, 128);
+        if (!device?.pendingTaskTimers || !key) {
+            return;
+        }
+
+        const timer = device.pendingTaskTimers.get(key);
+        if (timer) {
+            clearTimeout(timer);
+        }
+        device.pendingTaskTimers.delete(key);
+    }
+
+    function failPendingTask(device, commandId, error = 'task-timeout') {
+        const key = safeString(commandId, 128);
+        if (!device?.pendingTaskCommands || !key) {
+            return null;
+        }
+
+        const task = device.pendingTaskCommands.get(key);
+        if (!task) {
+            clearTaskTimeout(device, key);
+            return null;
+        }
+
+        const now = new Date().toISOString();
+        clearTaskTimeout(device, key);
+        task.status = 'failed';
+        task.updatedAt = now;
+        task.completedAt = now;
+        task.error = safeString(error, 500) || 'task-timeout';
+        task.resultSummary = task.error;
+        task.resultKind = task.resultKind || 'agent-task';
+        device.latestTask = task;
+        device.pendingTaskCommands.delete(key);
+        device.counters.taskResultsReceived += 1;
+        device.counters.taskResultsFailed += 1;
+        if (task.error === 'task-timeout') {
+            device.counters.taskResultsTimedOut += 1;
+        }
+        syncTaskBatchFromTask(device, task);
+        emitRemoteEvent('RemoteTaskResult', device, {
+            commandId: key,
+            taskId: task.taskId,
+            status: task.status,
+            error: task.error
+        });
+        return task;
+    }
+
+    function failAllPendingTasks(device, error = 'device-disconnected') {
+        if (!device?.pendingTaskCommands) {
+            return 0;
+        }
+
+        const commandIds = [...device.pendingTaskCommands.keys()];
+        let failed = 0;
+        for (const commandId of commandIds) {
+            if (failPendingTask(device, commandId, error)) {
+                failed += 1;
+            }
+        }
+        return failed;
+    }
+
+    function scheduleTaskTimeout(device, task) {
+        const commandId = safeString(task?.commandId, 128);
+        if (!device?.pendingTaskTimers || !commandId) {
+            return;
+        }
+
+        clearTaskTimeout(device, commandId);
+        const timer = setTimeout(() => {
+            failPendingTask(device, commandId, 'task-timeout');
+        }, taskTimeoutMs);
+        timer.unref?.();
+        device.pendingTaskTimers.set(commandId, timer);
+    }
+
+    function summarizeTaskResult(result) {
+        if (result && typeof result === 'object') {
+            return safeText(
+                result.summary
+                    || result.message
+                    || result.output
+                    || result.result
+                    || JSON.stringify(result),
+                MAX_AGENT_TASK_RESULT_CHARS);
+        }
+
+        return safeText(result ?? '', MAX_AGENT_TASK_RESULT_CHARS);
+    }
+
+    function applyTaskResult(device, commandId, result, error) {
+        if (!device || !commandId) {
+            return null;
+        }
+
+        const resultTaskId = result && typeof result === 'object'
+            ? safeString(result.taskId, 128)
+            : '';
+        const task = resultTaskId
+            ? device.recentTasks.find(item => item.taskId === resultTaskId)
+            : device.pendingTaskCommands.get(commandId);
+        if (!task) {
+            return null;
+        }
+
+        if (device.pendingTaskCommands.get(commandId) !== task) {
+            return null;
+        }
+
+        const now = device.lastSeenAt || new Date().toISOString();
+        const status = error
+            ? 'failed'
+            : safeString(result?.status, 40) || 'completed';
+        clearTaskTimeout(device, commandId);
+        task.status = status;
+        task.updatedAt = now;
+        task.completedAt = safeString(result?.completedAt, 80) || now;
+        task.error = error;
+        task.resultSummary = error || summarizeTaskResult(result);
+        task.resultKind = safeString(result?.kind || result?.mode || 'agent-task', 80);
+        task.resultModel = safeString(result?.model || result?.aiModel || '', 120);
+        task.resultResponseId = safeString(result?.responseId || result?.id || '', 160);
+        device.latestTask = task;
+        device.pendingTaskCommands.delete(commandId);
+        device.counters.taskResultsReceived += 1;
+        if (error) {
+            device.counters.taskResultsFailed += 1;
+        }
+        syncTaskBatchFromTask(device, task);
+
+        return task;
+    }
+
+    function normalizeFrameByteLength(framePayload, frameData = '') {
+        if (Buffer.isBuffer(framePayload)) {
+            return framePayload.length;
+        }
+
+        return Math.floor(String(frameData || '').length * 3 / 4);
+    }
+
+    function buildFrameDataUrl(framePayload, frameData, mimeType) {
+        if (Buffer.isBuffer(framePayload)) {
+            return `data:${mimeType};base64,${framePayload.toString('base64')}`;
+        }
+
+        return String(frameData || '').startsWith('data:')
+            ? String(frameData || '')
+            : `data:${mimeType};base64,${frameData}`;
+    }
+
+    function buildFramePayloadBuffer(framePayload, frameData) {
+        if (Buffer.isBuffer(framePayload)) {
+            return Buffer.from(framePayload);
+        }
+
+        const raw = String(frameData || '');
+        const commaIndex = raw.indexOf(',');
+        const base64 = raw.startsWith('data:') && commaIndex >= 0
+            ? raw.slice(commaIndex + 1)
+            : raw;
+        return Buffer.from(base64, 'base64');
+    }
+
+    function buildFrameContentHash(message, payload) {
+        const provided = safeString(message.contentHash || message.frameHash || message.hash, 96)
+            .toLowerCase()
+            .replace(/[^a-z0-9:_-]/g, '')
+            .slice(0, 64);
+        if (provided) {
+            return provided;
+        }
+
+        if (!Buffer.isBuffer(payload) || payload.length === 0) {
+            return '';
+        }
+
+        return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 16);
+    }
+
+    function readFrameCaptureMs(message) {
+        const value = Number(message.captureMs);
+        return Number.isFinite(value) && value >= 0
+            ? Math.round(value)
+            : 0;
+    }
+
+    function computeSameContentStreak(previousFrame, contentHash) {
+        if (!contentHash || !previousFrame?.contentHash || previousFrame.contentHash !== contentHash) {
+            return 0;
+        }
+
+        return clampNumber(Number(previousFrame.sameContentStreak || 0) + 1, 0, 1000000, 1);
+    }
+
+    function applyThumbnailFrame(device, message, framePayload, transport = 'json-base64') {
+        const frameData = Buffer.isBuffer(framePayload)
+            ? ''
+            : safeString(framePayload, MAX_THUMBNAIL_BASE64_CHARS + 1);
+        const frameSeq = Number(message.frameSeq);
+        const byteLength = normalizeFrameByteLength(framePayload, frameData);
+        if ((!Buffer.isBuffer(framePayload) && !frameData)
+            || byteLength > MAX_THUMBNAIL_BINARY_BYTES
+            || !Number.isFinite(frameSeq)) {
+            device.counters.thumbnailFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: 'invalid-thumbnail-frame',
+                frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
+                transport
+            });
+            return false;
+        }
+
+        const mimeType = safeString(message.mimeType || message.format || 'image/jpeg', 80) || 'image/jpeg';
+        const capturedAt = safeString(message.capturedAt, 80) || device.lastSeenAt;
+        const payload = buildFramePayloadBuffer(framePayload, frameData);
+        const contentHash = buildFrameContentHash(message, payload);
+        const sameContentStreak = computeSameContentStreak(device.latestThumbnail, contentHash);
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, 'thumbnail');
+        device.latestThumbnail = {
+            streamId: safeString(message.streamId, 128) || 'thumbnail',
+            frameSeq,
+            commandId: safeString(message.commandId, 128),
+            width: Number.isFinite(Number(message.width)) ? Number(message.width) : 0,
+            height: Number.isFinite(Number(message.height)) ? Number(message.height) : 0,
+            mimeType,
+            format: mimeType,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            codec: transfer.codec,
+            compression: transfer.compression || mimeType,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
+            capturedAt,
+            receivedAt: device.lastSeenAt,
+            byteLength,
+            transport,
+            contentHash,
+            captureMs: readFrameCaptureMs(message),
+            sameContentStreak,
+            payload,
+            accessToken: createFrameAccessToken()
+        };
+        rememberRecentFramePayload(device, 'thumbnail', device.latestThumbnail);
+        device.counters.thumbnailFramesReceived += 1;
+        emitRemoteEvent('RemoteFrameReceived', device, {
+            streamId: device.latestThumbnail.streamId,
+            frameSeq,
+            width: device.latestThumbnail.width,
+            height: device.latestThumbnail.height,
+            transport,
+            contentHash,
+            sameContentStreak
+        });
+        return true;
+    }
+
+    function applyLiveStreamOpen(device, message, transport = 'json') {
+        const streamId = safeString(message.streamId, 128) || 'live';
+        if (!device.activeLiveStream?.active || device.activeLiveStream.streamId !== streamId) {
+            emitRemoteEvent('RemoteLiveStreamOpenIgnored', device, {
+                reason: 'stale-live-stream-open',
+                streamId,
+                transport
+            });
+            return false;
+        }
+
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, device.activeLiveStream.mode || DEFAULT_REMOTE_FRAME_MODE);
+        const openedAt = safeString(message.openedAt, 80) || device.lastSeenAt || new Date().toISOString();
+        device.activeLiveStream = {
+            ...device.activeLiveStream,
+            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(device.activeLiveStream.width || 0),
+            height: Number.isFinite(Number(message.height)) ? Number(message.height) : Number(device.activeLiveStream.height || 0),
+            openedFrameSeq: Number.isFinite(Number(message.frameSeq)) ? Number(message.frameSeq) : Number(device.activeLiveStream.openedFrameSeq || 0)
+        };
+        emitRemoteEvent('RemoteLiveStreamOpened', device, {
+            streamId,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            compression: transfer.compression,
+            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';
+        if (!device.activeLiveStream?.active || device.activeLiveStream.streamId !== streamId) {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: 'stale-live-stream-frame',
+                streamId,
+                frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
+                transport
+            });
+            return false;
+        }
+
+        const byteLength = normalizeFrameByteLength(framePayload, frameData);
+        if ((!Buffer.isBuffer(framePayload) && !frameData)
+            || byteLength > MAX_STREAM_BINARY_BYTES
+            || !Number.isFinite(frameSeq)) {
+            device.counters.liveFramesDropped += 1;
+            emitRemoteEvent('RemoteFrameDropped', device, {
+                reason: 'invalid-live-frame',
+                streamId,
+                frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
+                transport
+            });
+            return false;
+        }
+
+        const mimeType = safeString(message.mimeType || message.format || 'image/jpeg', 80) || 'image/jpeg';
+        const capturedAt = safeString(message.capturedAt, 80) || device.lastSeenAt;
+        const payload = buildFramePayloadBuffer(framePayload, frameData);
+        const contentHash = buildFrameContentHash(message, payload);
+        const sameContentStreak = computeSameContentStreak(device.latestLiveFrame, contentHash);
+        const transfer = buildRemoteFrameTransferDescriptorFromMessage(message, device.activeLiveStream.mode || DEFAULT_REMOTE_FRAME_MODE);
+        if (device.activeLiveStream.open !== true) {
+            device.activeLiveStream.open = true;
+            device.activeLiveStream.openedAt = device.lastSeenAt;
+            device.activeLiveStream.openTransport = `${transport}-implicit`;
+            device.activeLiveStream.mode = transfer.mode;
+            device.activeLiveStream.frameMode = transfer.frameMode;
+            device.activeLiveStream.frameProfile = transfer.frameProfile;
+            device.activeLiveStream.encoding = transfer.encoding;
+            device.activeLiveStream.codec = transfer.codec;
+            device.activeLiveStream.compression = transfer.compression;
+            device.activeLiveStream.transferProtocol = transfer.transferProtocol;
+            device.activeLiveStream.transferProtocolVersion = transfer.transferProtocolVersion;
+            device.activeLiveStream.handshake = transfer.handshake;
+        }
+        device.latestLiveFrame = {
+            streamId,
+            frameSeq,
+            commandId: safeString(message.commandId, 128),
+            width: Number.isFinite(Number(message.width)) ? Number(message.width) : 0,
+            height: Number.isFinite(Number(message.height)) ? Number(message.height) : 0,
+            mimeType,
+            format: mimeType,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode,
+            frameProfile: transfer.frameProfile,
+            encoding: transfer.encoding,
+            codec: transfer.codec,
+            compression: transfer.compression || mimeType,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
+            fps: Number.isFinite(Number(message.fps)) ? Number(message.fps) : device.activeLiveStream.fps,
+            capturedAt,
+            receivedAt: device.lastSeenAt,
+            byteLength,
+            transport,
+            contentHash,
+            captureMs: readFrameCaptureMs(message),
+            sameContentStreak,
+            payload,
+            accessToken: createFrameAccessToken()
+        };
+        rememberRecentFramePayload(device, 'live', device.latestLiveFrame);
+        emitFrame({
+            kind: 'live',
+            deviceId: device.deviceId,
+            frame: serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', { includeDataUrl: false }),
+            payload: device.latestLiveFrame.payload,
+            mimeType: device.latestLiveFrame.mimeType,
+            byteLength: device.latestLiveFrame.byteLength
+        });
+        device.activeLiveStream.lastFrameAt = device.lastSeenAt;
+        device.activeLiveStream.lastFrameSeq = frameSeq;
+        device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;
+        device.activeLiveStream.mode = transfer.mode;
+        device.activeLiveStream.frameMode = transfer.frameMode;
+        device.activeLiveStream.frameProfile = transfer.frameProfile;
+        device.activeLiveStream.encoding = transfer.encoding;
+        device.activeLiveStream.codec = transfer.codec;
+        device.activeLiveStream.compression = transfer.compression;
+        device.activeLiveStream.transferProtocol = transfer.transferProtocol;
+        device.activeLiveStream.transferProtocolVersion = transfer.transferProtocolVersion;
+        device.activeLiveStream.handshake = transfer.handshake;
+        device.counters.liveFramesReceived += 1;
+        emitRemoteEvent('RemoteFrameReceived', device, {
+            streamId,
+            frameSeq,
+            width: device.latestLiveFrame.width,
+            height: device.latestLiveFrame.height,
+            mode: device.latestLiveFrame.mode,
+            transport,
+            contentHash,
+            sameContentStreak
+        });
+        return true;
+    }
+
+    function applyAudioFrame(device, message, framePayload, transport = 'json-base64') {
+        const audioData = Buffer.isBuffer(framePayload)
+            ? ''
+            : safeString(framePayload, MAX_AUDIO_BASE64_CHARS + 1);
+        const frameSeq = Number(message.frameSeq);
+        const streamId = safeString(message.streamId, 128) || device.activeAudioStream?.streamId || 'audio';
+        const byteLength = normalizeFrameByteLength(framePayload, audioData);
+        if ((!Buffer.isBuffer(framePayload) && !audioData)
+            || byteLength > MAX_AUDIO_BINARY_BYTES
+            || !Number.isFinite(frameSeq)) {
+            device.counters.audioFramesDropped += 1;
+            emitRemoteEvent('RemoteAudioFrameDropped', device, {
+                reason: 'invalid-audio-frame',
+                streamId,
+                frameSeq: Number.isFinite(frameSeq) ? frameSeq : null,
+                transport
+            });
+            return false;
+        }
+
+        const payload = buildFramePayloadBuffer(framePayload, audioData);
+        const mimeType = safeString(message.mimeType || message.format || 'audio/webm;codecs=opus', 120) || 'audio/webm;codecs=opus';
+        const capturedAt = safeString(message.capturedAt, 80) || device.lastSeenAt;
+        device.latestAudioFrame = {
+            streamId,
+            frameSeq,
+            commandId: safeString(message.commandId, 128),
+            mimeType,
+            format: mimeType,
+            sampleRate: Number.isFinite(Number(message.sampleRate)) ? Number(message.sampleRate) : 48000,
+            channels: Number.isFinite(Number(message.channels)) ? Math.max(1, Math.min(8, Math.floor(Number(message.channels)))) : 2,
+            capturedAt,
+            receivedAt: device.lastSeenAt,
+            byteLength,
+            transport,
+            payload
+        };
+        if (device.activeAudioStream) {
+            device.activeAudioStream.active = true;
+            device.activeAudioStream.open = true;
+            device.activeAudioStream.lastFrameAt = device.lastSeenAt;
+            device.activeAudioStream.lastFrameSeq = frameSeq;
+            device.activeAudioStream.framesReceived = (device.activeAudioStream.framesReceived || 0) + 1;
+            device.activeAudioStream.mimeType = mimeType;
+            device.activeAudioStream.sampleRate = device.latestAudioFrame.sampleRate;
+            device.activeAudioStream.channels = device.latestAudioFrame.channels;
+        }
+        device.counters.audioFramesReceived += 1;
+        emitAudio({
+            deviceId: device.deviceId,
+            frame: {
+                streamId,
+                frameSeq,
+                mimeType,
+                sampleRate: device.latestAudioFrame.sampleRate,
+                channels: device.latestAudioFrame.channels,
+                capturedAt,
+                receivedAt: device.latestAudioFrame.receivedAt,
+                byteLength
+            },
+            payload,
+            mimeType,
+            byteLength
+        });
+        emitRemoteEvent('RemoteAudioFrameReceived', device, {
+            streamId,
+            frameSeq,
+            mimeType,
+            byteLength,
+            transport
+        });
+        return true;
+    }
+
+    function handleAgentBinaryFrame(socket, state, header, framePayload) {
+        if (!state.authenticated || !state.device) {
+            writeJsonLine(socket, { type: 'error', error: 'hello-required' });
+            socket.destroy();
+            return;
+        }
+
+        const device = state.device;
+        device.counters.messagesReceived += 1;
+        device.lastSeenAt = new Date().toISOString();
+
+        const frameKind = safeString(header.frameKind || header.kind || header.frameType || '', 40).toLowerCase();
+        if (frameKind === 'thumbnail' || header.type === 'thumbnail.binary') {
+            applyThumbnailFrame(device, header, framePayload, 'binary');
+            return;
+        }
+
+        if (frameKind === 'stream' || frameKind === 'live' || header.type === 'stream.binary') {
+            applyLiveFrame(device, header, framePayload, 'binary');
+            return;
+        }
+
+        if (frameKind === 'audio' || header.type === 'audio.binary') {
+            applyAudioFrame(device, header, framePayload, 'binary');
+            return;
+        }
+
+        emitRemoteEvent('RemoteAgentMessageIgnored', device, {
+            messageType: safeString(header.type, 80),
+            frameKind
+        });
+    }
+
+    function handleAgentMessage(socket, state, message) {
+        if (!message || typeof message !== 'object') {
+            return;
+        }
+
+        if (!state.authenticated) {
+            if (message.type !== 'hello') {
+                writeJsonLine(socket, { type: 'error', error: 'hello-required' });
+                socket.destroy();
+                return;
+            }
+
+            if (!timingSafeStringEqual(message.pairToken, pairToken)) {
+                writeJsonLine(socket, { type: 'error', error: 'invalid-pair-token' });
+                socket.destroy();
+                return;
+            }
+
+            const device = attachDevice(socket, message);
+            if (!device) {
+                return;
+            }
+
+            state.authenticated = true;
+            state.device = device;
+            return;
+        }
+
+        const device = state.device;
+        if (!device) {
+            socket.destroy();
+            return;
+        }
+
+        device.counters.messagesReceived += 1;
+        device.lastSeenAt = new Date().toISOString();
+
+        switch (message.type) {
+            case 'heartbeat':
+            case 'status':
+                device.status = typeof message.status === 'object' && message.status
+                    ? { ...message.status }
+                    : {};
+                {
+                    const nextSlotNumber = normalizeSlotNumber(device.status.slotNumber);
+                    if (nextSlotNumber > 0) {
+                        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 task = applyTaskResult(device, commandId, message.result ?? null, error);
+                    if (task) {
+                        emitRemoteEvent('RemoteTaskResult', device, {
+                            commandId,
+                            taskId: task.taskId,
+                            status: task.status,
+                            error: task.error
+                        });
+                    }
+                }
+                emitRemoteEvent('RemoteCommandResult', device, {
+                    commandId: safeString(message.commandId, 128),
+                    result: message.result ?? null,
+                    error: safeString(message.error, 500)
+                });
+                break;
+            case 'thumbnail.frame': {
+                applyThumbnailFrame(device, message, message.data, 'json-base64');
+                break;
+            }
+            case 'stream.open': {
+                applyLiveStreamOpen(device, message, 'json');
+                break;
+            }
+            case 'stream.frame': {
+                applyLiveFrame(device, message, message.data, 'json-base64');
+                break;
+            }
+            case 'audio.frame': {
+                applyAudioFrame(device, message, message.data, 'json-base64');
+                break;
+            }
+            default:
+                emitRemoteEvent('RemoteAgentMessageIgnored', device, {
+                    messageType: safeString(message.type, 80)
+                });
+                break;
+        }
+    }
+
+    function handleWebSocketAgentSocket(socket) {
+        allSockets.add(socket);
+        socket.setNoDelay(true);
+        socket.setKeepAlive(true, heartbeatMs);
+
+        const state = {
+            authenticated: false,
+            device: null
+        };
+
+        const helloTimer = setTimeout(() => {
+            if (!state.authenticated) {
+                writeJsonLine(socket, { type: 'error', error: 'hello-timeout' });
+                socket.destroy();
+            }
+        }, 10000);
+
+        socket.onTextMessage = text => {
+            try {
+                handleAgentMessage(socket, state, parseJsonLine(String(text || '')));
+            } catch (err) {
+                writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
+                logWarn('remote', `invalid websocket agent message: ${err?.message || err}`);
+            }
+        };
+
+        socket.onBinaryMessage = payload => {
+            try {
+                const packet = parseRemoteHubWebSocketBinaryFrame(payload);
+                if (!packet?.header || !Buffer.isBuffer(packet.payload)) {
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
+                    return;
+                }
+
+                const frameKind = safeString(packet.header.frameKind || packet.header.kind || packet.header.frameType, 40).toLowerCase();
+                const maxBytes = frameKind === 'thumbnail'
+                    ? MAX_THUMBNAIL_BINARY_BYTES
+                    : MAX_STREAM_BINARY_BYTES;
+                const byteLength = Number(packet.header.byteLength ?? packet.header.payloadBytes ?? packet.payload.length);
+                if (!Number.isFinite(byteLength)
+                    || byteLength < 1
+                    || byteLength > maxBytes
+                    || byteLength !== packet.payload.length) {
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-binary-frame' });
+                    logWarn('remote', 'invalid websocket binary frame from agent.');
+                    return;
+                }
+
+                handleAgentBinaryFrame(socket, state, packet.header, packet.payload);
+            } catch (err) {
+                writeJsonLine(socket, { type: 'error', error: 'invalid-websocket-binary-frame' });
+                logWarn('remote', `invalid websocket binary frame: ${err?.message || err}`);
+            }
+        };
+
+        const detach = reason => {
+            allSockets.delete(socket);
+            clearTimeout(helloTimer);
+            detachSocket(socket, reason);
+        };
+
+        socket.onCloseMessage = reason => detach(reason || 'websocket-closed');
+        socket.socket.on('close', () => detach('websocket-closed'));
+        socket.socket.on('error', err => detach(err?.message || 'websocket-error'));
+    }
+
+    function handleWebSocketUpgradeSocket(socket, firstChunk) {
+        let upgradeBuffer = Buffer.isBuffer(firstChunk) ? firstChunk : Buffer.from(firstChunk);
+        let onUpgradeData = null;
+        const fail = (status, message) => {
+            try {
+                socket.write(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\n\r\n`);
+            } catch {
+                // Ignore write failures while rejecting the upgrade.
+            }
+            socket.destroy();
+        };
+
+        const completeUpgrade = () => {
+            const request = parseRemoteHubWebSocketUpgrade(upgradeBuffer);
+            if (!request) {
+                return false;
+            }
+
+            const upgrade = String(request.headers.upgrade || '').toLowerCase();
+            const connection = String(request.headers.connection || '').toLowerCase();
+            const key = safeString(request.headers['sec-websocket-key'], 256);
+            const pathName = safeString(String(request.path || '').split('?')[0], 128) || '/';
+            const allowedPath = pathName === '/'
+                || pathName === '/remote-agent'
+                || pathName === '/api/remote/agent/ws';
+            if (request.method !== 'GET'
+                || upgrade !== 'websocket'
+                || !connection.includes('upgrade')
+                || !key
+                || !allowedPath) {
+                fail(400, 'Bad Request');
+                return true;
+            }
+
+            const acceptKey = buildRemoteHubWebSocketAcceptKey(key);
+            socket.write([
+                'HTTP/1.1 101 Switching Protocols',
+                'Upgrade: websocket',
+                'Connection: Upgrade',
+                `Sec-WebSocket-Accept: ${acceptKey}`,
+                '\r\n'
+            ].join('\r\n'));
+
+            if (onUpgradeData) {
+                socket.removeListener('data', onUpgradeData);
+            }
+            const wsSocket = new RemoteHubWebSocketAgentSocket(socket);
+            const onFrameData = chunk => wsSocket.handleData(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            socket.on('data', onFrameData);
+            socket.once('close', () => {
+                socket.removeListener('data', onFrameData);
+            });
+            handleWebSocketAgentSocket(wsSocket);
+            if (request.head.length > 0) {
+                wsSocket.handleData(request.head);
+            }
+            return true;
+        };
+
+        onUpgradeData = chunk => {
+            upgradeBuffer = Buffer.concat([upgradeBuffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+            if (upgradeBuffer.length > 16 * 1024) {
+                fail(431, 'Request Header Fields Too Large');
+                return;
+            }
+            completeUpgrade();
+        };
+
+        if (!completeUpgrade()) {
+            socket.on('data', onUpgradeData);
+        }
+    }
+
+    function handleTcpAgentSocket(socket, firstChunk = null) {
+        allSockets.add(socket);
+        socket.setNoDelay(true);
+        socket.setKeepAlive(true, heartbeatMs);
+
+        const state = {
+            authenticated: false,
+            device: null,
+            buffer: Buffer.alloc(0),
+            pendingBinaryFrame: null
+        };
+
+        const helloTimer = setTimeout(() => {
+            if (!state.authenticated) {
+                writeJsonLine(socket, { type: 'error', error: 'hello-timeout' });
+                socket.destroy();
+            }
+        }, 10000);
+
+        const processData = chunk => {
+            const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            state.buffer = state.buffer.length > 0
+                ? Buffer.concat([state.buffer, incoming])
+                : incoming;
+
+            while (!socket.destroyed) {
+                if (state.pendingBinaryFrame) {
+                    const { header, byteLength } = state.pendingBinaryFrame;
+                    if (state.buffer.length < byteLength) {
+                        return;
+                    }
+
+                    const framePayload = state.buffer.subarray(0, byteLength);
+                    state.buffer = state.buffer.subarray(byteLength);
+                    state.pendingBinaryFrame = null;
+                    handleAgentBinaryFrame(socket, state, header, framePayload);
+                    continue;
+                }
+
+                const newlineIndex = state.buffer.indexOf(0x0a);
+                if (newlineIndex < 0) {
+                    if (state.buffer.length > MAX_LINE_CHARS) {
+                        writeJsonLine(socket, { type: 'error', error: 'message-too-large' });
+                        socket.destroy();
+                    }
+                    return;
+                }
+
+                const lineBuffer = state.buffer.subarray(0, newlineIndex);
+                state.buffer = state.buffer.subarray(newlineIndex + 1);
+
+                try {
+                    const message = parseJsonLine(lineBuffer.toString('utf8'));
+                    if (message?.type === 'frame.binary') {
+                        const frameKind = safeString(message.frameKind || message.kind || message.frameType, 40).toLowerCase();
+                        const maxBytes = frameKind === 'thumbnail'
+                            ? MAX_THUMBNAIL_BINARY_BYTES
+                            : MAX_STREAM_BINARY_BYTES;
+                        const byteLength = Number(message.byteLength ?? message.payloadBytes ?? message.dataLength);
+                        if (!Number.isFinite(byteLength) || byteLength < 1 || byteLength > maxBytes) {
+                            writeJsonLine(socket, { type: 'error', error: 'invalid-binary-frame' });
+                            logWarn('remote', 'invalid binary frame header from agent.');
+                            continue;
+                        }
+
+                        state.pendingBinaryFrame = {
+                            header: message,
+                            byteLength: Math.floor(byteLength)
+                        };
+                        continue;
+                    }
+
+                    handleAgentMessage(socket, state, message);
+                } catch (err) {
+                    writeJsonLine(socket, { type: 'error', error: 'invalid-json' });
+                    logWarn('remote', `invalid agent message: ${err?.message || err}`);
+                }
+            }
+        };
+
+        socket.on('data', processData);
+        if (firstChunk) {
+            processData(firstChunk);
+        }
+
+        socket.on('close', () => {
+            allSockets.delete(socket);
+            clearTimeout(helloTimer);
+            detachSocket(socket);
+        });
+        socket.on('error', err => {
+            allSockets.delete(socket);
+            clearTimeout(helloTimer);
+            detachSocket(socket, err?.message || 'socket-error');
+        });
+    }
+
+    function handleSocket(socket) {
+        socket.once('data', chunk => {
+            const firstChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (isRemoteHubWebSocketUpgradeStart(firstChunk)) {
+                handleWebSocketUpgradeSocket(socket, firstChunk);
+                return;
+            }
+
+            handleTcpAgentSocket(socket, firstChunk);
+        });
+
+        socket.once('error', () => {
+            // The transport-specific handler owns logging after the first byte.
+        });
+    }
+
+    async function start() {
+        if (!enabled || started) {
+            return getStatus({ includeSecrets: false });
+        }
+
+        await new Promise((resolve, reject) => {
+            server = net.createServer(handleSocket);
+            server.once('error', err => {
+                lastError = err?.message || String(err);
+                server = null;
+                reject(err);
+            });
+            server.listen(requestedPort, host, () => {
+                started = true;
+                boundPort = server.address()?.port || requestedPort;
+                lastError = '';
+                logEvent('remote', `RemoteHub listening on tcp://${host}:${boundPort}`, 'success');
+                if (host === '0.0.0.0' || host === '::') {
+                    logWarn('remote', 'RemoteHub is externally reachable. Use a strong pairing token and trusted network.');
+                }
+                emitRemoteEvent('RemoteHubStarted', null);
+                resolve();
+            });
+        });
+
+        return getStatus({ includeSecrets: false });
+    }
+
+    async function close() {
+        for (const device of devices.values()) {
+            failAllPendingTasks(device, 'hub-shutdown');
+            if (device.socket && !device.socket.destroyed) {
+                writeJsonLine(device.socket, { type: 'disconnect', reason: 'hub-shutdown' });
+                device.socket.destroy();
+            }
+        }
+
+        for (const socket of allSockets) {
+            if (!socket.destroyed) {
+                socket.destroy();
+            }
+        }
+
+        sockets.clear();
+        if (!server) {
+            started = false;
+            return;
+        }
+
+        await new Promise(resolve => {
+            let settled = false;
+            const settle = () => {
+                if (settled) {
+                    return;
+                }
+
+                settled = true;
+                clearTimeout(closeTimer);
+                resolve();
+            };
+
+            const closeTimer = setTimeout(settle, 1000);
+            closeTimer.unref?.();
+
+            try {
+                server.close(settle);
+            } catch {
+                settle();
+            }
+        });
+
+        server = null;
+        started = false;
+    }
+
+    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;
+            if (device.activeLiveStream) {
+                device.activeLiveStream.active = false;
+                device.activeLiveStream.stoppedAt = device.disconnectedAt;
+                device.activeLiveStream.stopReason = reason;
+            }
+            failAllPendingTasks(device, 'device-disconnected');
+            emitRemoteEvent('RemoteDeviceDisconnected', device, { reason, synthetic: true });
+            return true;
+        }
+
+        if (!device?.socket || device.socket.destroyed) {
+            return false;
+        }
+
+        writeJsonLine(device.socket, { type: 'disconnect', reason });
+        device.socket.destroy();
+        return true;
+    }
+
+    function sendCommand(deviceId, command) {
+        const device = devices.get(String(deviceId || ''));
+        if (device?.synthetic === true && device.connected) {
+            const commandId = safeString(command?.commandId, 128) || crypto.randomUUID();
+            device.counters.commandsSent += 1;
+            device.lastSeenAt = new Date().toISOString();
+            if (command?.command === 'thumbnail.capture') {
+                applySyntheticThumbnail(device, {
+                    commandId,
+                    payload: command?.payload || {}
+                });
+            }
+            emitRemoteEvent('RemoteCommandQueued', device, {
+                commandId,
+                command: safeString(command?.command || 'ping', 80),
+                synthetic: true
+            });
+            emitRemoteEvent('RemoteCommandResult', device, {
+                commandId,
+                result: { ok: true, synthetic: true },
+                error: ''
+            });
+            return { ok: true, commandId, synthetic: true };
+        }
+
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const commandId = safeString(command?.commandId, 128) || crypto.randomUUID();
+        const payload = {
+            type: 'command',
+            commandId,
+            command: safeString(command?.command || 'ping', 80),
+            payload: command?.payload ?? null,
+            issuedAt: new Date().toISOString()
+        };
+
+        writeJsonLine(device.socket, payload);
+        device.counters.commandsSent += 1;
+        emitRemoteEvent('RemoteCommandQueued', device, {
+            commandId,
+            command: payload.command
+        });
+        return { ok: true, commandId };
+    }
+
+    function sendInputControl(deviceId, input = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device) {
+            return { ok: false, error: 'device-not-found' };
+        }
+
+        if (!device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        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' };
+        }
+
+        return sendCommand(deviceId, {
+            command: 'input.control',
+            payload: {
+                ...normalized,
+                issuedAt: normalized.issuedAt || new Date().toISOString()
+            }
+        });
+    }
+
+    function requestAgentTask(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device) {
+            return { ok: false, error: 'device-not-found' };
+        }
+
+        if (device?.synthetic === true && device.connected) {
+            const instruction = safeText(options.instruction, MAX_AGENT_TASK_CHARS);
+            if (!instruction) {
+                return { ok: false, error: 'missing-instruction' };
+            }
+
+            const now = new Date().toISOString();
+            const approvalLevel = normalizeApprovalLevel(options.approvalLevel);
+            if (approvalLevel === 'ai-assist' && !readCapabilityFlag(device.capabilities, 'aiAssist')) {
+                return { ok: false, error: 'device-ai-assist-unavailable' };
+            }
+
+            const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+            const taskId = safeString(options.taskId, 128) || crypto.randomUUID();
+            const title = safeString(options.title, 120)
+                || safeString(instruction.split(/\r?\n/)[0], 120)
+                || 'Remote task';
+            const task = {
+                batchId: safeString(options.batchId, 128),
+                taskId,
+                commandId,
+                title,
+                instructionPreview: safeText(instruction, 320),
+                status: 'completed',
+                approvalLevel,
+                requestedAt: now,
+                sentAt: now,
+                updatedAt: now,
+                completedAt: now,
+                error: '',
+                resultKind: approvalLevel === 'ai-assist' ? 'synthetic-ai-assist' : 'synthetic-agent-task',
+                resultModel: approvalLevel === 'ai-assist'
+                    ? safeString(options.model, 120) || 'synthetic-ai'
+                    : '',
+                resultResponseId: approvalLevel === 'ai-assist'
+                    ? `synthetic-response-${taskId}`
+                    : '',
+                resultSummary: approvalLevel === 'ai-assist'
+                    ? `Synthetic AI assist completed for ${device.deviceName}.`
+                    : `Synthetic task accepted by ${device.deviceName}.`
+            };
+
+            device.counters.commandsSent += 1;
+            device.counters.commandResultsReceived += 1;
+            device.counters.tasksQueued += 1;
+            device.counters.taskResultsReceived += 1;
+            device.lastSeenAt = now;
+            rememberDeviceTask(device, task);
+            device.pendingTaskCommands.delete(commandId);
+            syncTaskBatchFromTask(device, task);
+            emitRemoteEvent('RemoteTaskQueued', device, {
+                commandId,
+                taskId,
+                title,
+                approvalLevel,
+                synthetic: true
+            });
+            emitRemoteEvent('RemoteTaskResult', device, {
+                commandId,
+                taskId,
+                status: task.status,
+                error: '',
+                synthetic: true
+            });
+            return { ok: true, commandId, taskId, approvalLevel, synthetic: true };
+        }
+
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const instruction = safeText(options.instruction, MAX_AGENT_TASK_CHARS);
+        if (!instruction) {
+            return { ok: false, error: 'missing-instruction' };
+        }
+
+        const now = new Date().toISOString();
+        const approvalLevel = normalizeApprovalLevel(options.approvalLevel);
+        if (approvalLevel === 'ai-assist' && !readCapabilityFlag(device.capabilities, 'aiAssist')) {
+            return { ok: false, error: 'device-ai-assist-unavailable' };
+        }
+
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const taskId = safeString(options.taskId, 128) || crypto.randomUUID();
+        const title = safeString(options.title, 120)
+            || safeString(instruction.split(/\r?\n/)[0], 120)
+            || 'Remote task';
+        const task = {
+            batchId: safeString(options.batchId, 128),
+            taskId,
+            commandId,
+            title,
+            instructionPreview: safeText(instruction, 320),
+            status: 'queued',
+            approvalLevel,
+            requestedAt: now,
+            sentAt: now,
+            updatedAt: now,
+            completedAt: '',
+            error: '',
+            resultKind: '',
+            resultModel: '',
+            resultResponseId: '',
+            resultSummary: ''
+        };
+
+        const sent = writeJsonLine(device.socket, {
+            type: 'command',
+            commandId,
+            command: 'agent.task',
+            payload: {
+                taskId,
+                title,
+                instruction,
+                approvalLevel,
+                model: safeString(options.model, 120),
+                requestedAt: now
+            },
+            issuedAt: now
+        });
+
+        if (!sent) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        device.counters.commandsSent += 1;
+        device.counters.tasksQueued += 1;
+        rememberDeviceTask(device, task);
+        syncTaskBatchFromTask(device, task);
+        scheduleTaskTimeout(device, task);
+        emitRemoteEvent('RemoteTaskQueued', device, {
+            commandId,
+            taskId,
+            title,
+            approvalLevel
+        });
+        return { ok: true, commandId, taskId, approvalLevel };
+    }
+
+    function requestAgentTaskBatch(deviceIds, options = {}) {
+        const targets = [...new Set((deviceIds || [])
+            .map(deviceId => safeString(deviceId, 128))
+            .filter(Boolean))]
+            .slice(0, 500);
+
+        if (targets.length === 0) {
+            return {
+                ok: false,
+                error: 'no-target-devices',
+                total: 0,
+                queued: 0,
+                approvalLevel: normalizeApprovalLevel(options.approvalLevel),
+                results: []
+            };
+        }
+
+        const batch = beginTaskBatch(targets, options);
+        const results = targets.map(deviceId => {
+            const result = requestAgentTask(deviceId, {
+                ...options,
+                batchId: batch.batchId
+            });
+
+            if (result.ok !== true) {
+                syncTaskBatchDispatchFailure(batch.batchId, deviceId, result.error, result);
+            }
+
+            return {
+                deviceId,
+                ...result
+            };
+        });
+
+        const queued = results.filter(result => result.ok === true).length;
+        const updatedBatch = taskBatches.get(batch.batchId) || batch;
+        recalculateTaskBatch(updatedBatch);
+        return {
+            ok: queued > 0,
+            batchId: batch.batchId,
+            total: targets.length,
+            queued,
+            approvalLevel: batch.approvalLevel,
+            results,
+            batch: serializeTaskBatch(updatedBatch),
+            error: queued > 0 ? undefined : 'no-task-queued'
+        };
+    }
+
+    function requestThumbnail(deviceId, options = {}) {
+        return sendCommand(deviceId, {
+            command: 'thumbnail.capture',
+            commandId: safeString(options.commandId, 128) || crypto.randomUUID(),
+            payload: {
+                streamId: safeString(options.streamId, 128) || `thumb-${Date.now()}`,
+                maxWidth: clampNumber(options.maxWidth, 160, 1920, 360),
+                maxHeight: clampNumber(options.maxHeight, 90, 1080, 220),
+                quality: clampNumber(options.quality, 20, 95, 55),
+                requestedAt: new Date().toISOString()
+            }
+        });
+    }
+
+    function startLiveStream(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (device?.synthetic === true && device.connected) {
+            if (!readCapabilityFlag(device.capabilities, 'liveStream')) {
+                return { ok: false, error: 'device-live-stream-unavailable' };
+            }
+
+            const now = new Date().toISOString();
+            const streamId = safeString(options.streamId, 128) || `live-${Date.now()}`;
+            const fps = clampNumber(options.fps, 1, 24, 20);
+            const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+            const transfer = buildRemoteFrameTransferDescriptor(options.mode || DEFAULT_REMOTE_FRAME_MODE);
+            device.counters.commandsSent += 1;
+            device.activeLiveStream = {
+                streamId,
+                commandId,
+                active: true,
+                open: true,
+                openedAt: now,
+                openTransport: 'synthetic',
+                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,
+                fps,
+                startedAt: now,
+                stoppedAt: '',
+                stopReason: '',
+                lastFrameAt: '',
+                lastFrameSeq: 0,
+                framesReceived: 0
+            };
+            device.counters.liveStreamsStarted += 1;
+            applySyntheticLiveFrame(device, streamId, {
+                commandId,
+                maxWidth: options.maxWidth,
+                maxHeight: options.maxHeight,
+                fps
+            });
+            emitRemoteEvent('RemoteLiveStreamStarted', device, {
+                streamId,
+                commandId,
+                fps,
+                mode: transfer.mode,
+                synthetic: true
+            });
+            return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode, synthetic: true };
+        }
+
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+        if (!readCapabilityFlag(device.capabilities, 'liveStream')) {
+            return { ok: false, error: 'device-live-stream-unavailable' };
+        }
+
+        const now = new Date().toISOString();
+        const streamId = safeString(options.streamId, 128) || `live-${Date.now()}`;
+        const fps = clampNumber(options.fps, 1, 24, 12);
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const transfer = buildRemoteFrameTransferDescriptor(options.mode || DEFAULT_REMOTE_FRAME_MODE);
+        const result = sendCommand(deviceId, {
+            command: 'stream.start',
+            commandId,
+            payload: {
+                streamId,
+                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,
+                fps,
+                maxWidth: clampNumber(options.maxWidth, 320, 2560, 960),
+                maxHeight: clampNumber(options.maxHeight, 180, 1440, 540),
+                quality: clampNumber(options.quality, 20, 95, 60),
+                requestedAt: now
+            }
+        });
+
+        if (!result.ok) {
+            return result;
+        }
+
+        device.activeLiveStream = {
+            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,
+            transferProtocol: transfer.transferProtocol,
+            transferProtocolVersion: transfer.transferProtocolVersion,
+            handshake: transfer.handshake,
+            fps,
+            startedAt: now,
+            stoppedAt: '',
+            stopReason: '',
+            lastFrameAt: '',
+            lastFrameSeq: 0,
+            framesReceived: 0
+        };
+        device.counters.liveStreamsStarted += 1;
+        emitRemoteEvent('RemoteLiveStreamStarted', device, {
+            streamId,
+            commandId,
+            fps,
+            mode: transfer.mode,
+            frameMode: transfer.frameMode
+        });
+
+        return { ok: true, commandId, streamId, fps, mode: transfer.mode, frameMode: transfer.frameMode };
+    }
+
+    function stopLiveStream(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (device?.synthetic === true && device.connected) {
+            const streamId = safeString(options.streamId, 128) || device.activeLiveStream?.streamId || '';
+            const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+            device.counters.commandsSent += 1;
+            if (device.activeLiveStream && (!streamId || device.activeLiveStream.streamId === streamId)) {
+                device.activeLiveStream.active = false;
+                device.activeLiveStream.stoppedAt = new Date().toISOString();
+                device.activeLiveStream.stopReason = 'manager-request';
+            }
+            device.counters.liveStreamsStopped += 1;
+            emitRemoteEvent('RemoteLiveStreamStopped', device, {
+                streamId,
+                commandId,
+                synthetic: true
+            });
+            return { ok: true, commandId, streamId, synthetic: true };
+        }
+
+        if (!device?.socket || device.socket.destroyed || !device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+
+        const streamId = safeString(options.streamId, 128) || device.activeLiveStream?.streamId || '';
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const result = sendCommand(deviceId, {
+            command: 'stream.stop',
+            commandId,
+            payload: {
+                streamId,
+                requestedAt: new Date().toISOString()
+            }
+        });
+
+        if (!result.ok) {
+            return result;
+        }
+
+        if (device.activeLiveStream && (!streamId || device.activeLiveStream.streamId === streamId)) {
+            device.activeLiveStream.active = false;
+            device.activeLiveStream.stoppedAt = new Date().toISOString();
+            device.activeLiveStream.stopReason = 'manager-request';
+        }
+        device.counters.liveStreamsStopped += 1;
+        emitRemoteEvent('RemoteLiveStreamStopped', device, {
+            streamId,
+            commandId
+        });
+
+        return { ok: true, commandId, streamId };
+    }
+
+    function startAudioStream(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device) {
+            return { ok: false, error: 'device-not-found' };
+        }
+        if (!device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+        if (!readCapabilityFlag(device.capabilities, 'audio') && !readCapabilityFlag(device.capabilities, 'remoteAudio')) {
+            return { ok: false, error: 'device-audio-unavailable' };
+        }
+        if (device.synthetic === true || !device.socket || device.socket.destroyed) {
+            return { ok: false, error: 'device-audio-unavailable' };
+        }
+
+        const now = new Date().toISOString();
+        const streamId = safeString(options.streamId, 128) || `audio-${Date.now()}`;
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const result = sendCommand(deviceId, {
+            command: 'audio.start',
+            commandId,
+            payload: {
+                streamId,
+                mimeType: safeString(options.mimeType, 120) || 'audio/webm;codecs=opus',
+                sampleRate: clampNumber(options.sampleRate, 8000, 192000, 48000),
+                channels: clampNumber(options.channels, 1, 8, 2),
+                requestedAt: now
+            }
+        });
+        if (!result.ok) {
+            return result;
+        }
+
+        device.activeAudioStream = {
+            streamId,
+            commandId,
+            active: true,
+            open: false,
+            startedAt: now,
+            stoppedAt: '',
+            stopReason: '',
+            lastFrameAt: '',
+            lastFrameSeq: 0,
+            framesReceived: 0,
+            mimeType: safeString(options.mimeType, 120) || 'audio/webm;codecs=opus',
+            sampleRate: clampNumber(options.sampleRate, 8000, 192000, 48000),
+            channels: clampNumber(options.channels, 1, 8, 2)
+        };
+        device.counters.audioStreamsStarted += 1;
+        emitRemoteEvent('RemoteAudioStreamStarted', device, {
+            streamId,
+            commandId
+        });
+        return { ok: true, commandId, streamId };
+    }
+
+    function stopAudioStream(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device) {
+            return { ok: false, error: 'device-not-found' };
+        }
+        if (!device.connected) {
+            return { ok: false, error: 'device-not-connected' };
+        }
+        if (device.synthetic === true || !device.socket || device.socket.destroyed) {
+            return { ok: false, error: 'device-audio-unavailable' };
+        }
+        const streamId = safeString(options.streamId, 128) || device.activeAudioStream?.streamId || '';
+        const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
+        const result = sendCommand(deviceId, {
+            command: 'audio.stop',
+            commandId,
+            payload: {
+                streamId,
+                requestedAt: new Date().toISOString()
+            }
+        });
+        if (!result.ok) {
+            return result;
+        }
+        if (device.activeAudioStream && (!streamId || device.activeAudioStream.streamId === streamId)) {
+            device.activeAudioStream.active = false;
+            device.activeAudioStream.stoppedAt = new Date().toISOString();
+            device.activeAudioStream.stopReason = 'manager-request';
+        }
+        device.counters.audioStreamsStopped += 1;
+        emitRemoteEvent('RemoteAudioStreamStopped', device, {
+            streamId,
+            commandId
+        });
+        return { ok: true, commandId, streamId };
+    }
+
+    function getDeviceLiveFrame(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        return serializeRemoteFrame(device?.latestLiveFrame, device?.deviceId, 'live', {
+            includeDataUrl: options.includeDataUrl === true
+        });
+    }
+
+    function getDeviceThumbnail(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        return serializeRemoteFrame(device?.latestThumbnail, device?.deviceId, 'thumbnail', {
+            includeDataUrl: options.includeDataUrl === true
+        });
+    }
+
+    function getFramePayload(deviceId, frameKind, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        if (!device) {
+            return null;
+        }
+
+        const kind = frameKind === 'thumbnail' ? 'thumbnail' : 'live';
+        const frame = findRecentFramePayload(device, kind, options);
+        if (!frame) {
+            return null;
+        }
+
+        return {
+            frame: serializeRemoteFrame(frame, device.deviceId, kind, { includeDataUrl: false }),
+            payload: frame.payload,
+            mimeType: safeString(frame.mimeType || frame.format || 'application/octet-stream', 120) || 'application/octet-stream',
+            byteLength: frame.payload.length
+        };
+    }
+
+    return {
+        start,
+        close,
+        getStatus,
+        listDevices,
+        listTaskBatches,
+        getLatestTaskBatch,
+        listDeviceFrames,
+        disconnectDevice,
+        sendCommand,
+        sendInputControl,
+        requestAgentTask,
+        requestAgentTaskBatch,
+        setHostTarget,
+        requestThumbnail,
+        startLiveStream,
+        stopLiveStream,
+        startAudioStream,
+        stopAudioStream,
+        getDeviceLiveFrame,
+        getDeviceThumbnail,
+        getFramePayload,
+        seedSyntheticFleet,
+        clearSyntheticFleet,
+        getPairToken: () => pairToken
+    };
+}
+
+export function getDefaultRemoteAgentDeviceInfo() {
+    return {
+        hostname: os.hostname(),
+        platform: os.platform(),
+        arch: os.arch(),
+        pid: process.pid
+    };
+}