mindexec-ai 0.2.385

package/remote-hub.js

@@ -0,0 +1,3106 @@
+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_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 = 1;
+const MAX_SYNTHETIC_DEVICES = 1000;
+const DEFAULT_HOST_TARGET_LEASE_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);
+
+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 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 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 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,
+        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,
+        pid: device.pid,
+        agentVersion: device.agentVersion,
+        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,
+        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 enabled = isEnabledValue(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.MINDEXEC_MANAGER_PACKAGE ?? 'mindexec-ai', 128);
+    const managerVersion = safeString(options.managerVersion ?? env.MINDEXEC_MANAGER_VERSION ?? '', 64);
+    const hostInstanceId = safeString(options.hostInstanceId ?? env.MINDEXEC_BRIDGE_INSTANCE_ID ?? crypto.randomUUID(), 128) || crypto.randomUUID();
+    const publicEndpoint = safeString(env.MINDEXEC_REMOTE_PUBLIC_ENDPOINT || env.REMOTE_HUB_PUBLIC_ENDPOINT, 256);
+    const publicHost = safeString(env.MINDEXEC_REMOTE_PUBLIC_HOST || env.REMOTE_HUB_PUBLIC_HOST, 128);
+    const pairToken = safeString(
+        options.pairToken || env.REMOTE_HUB_PAIR_TOKEN || env.MINDEXEC_REMOTE_PAIR_TOKEN || crypto.randomBytes(6).toString('hex'),
+        256);
+
+    const devices = new Map();
+    const taskBatches = new Map();
+    const sockets = new Map();
+    const allSockets = new Set();
+    let server = null;
+    let started = false;
+    let boundPort = requestedPort;
+    let lastError = '';
+    let hostTarget = null;
+
+    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 endpoint = getAgentEndpoint();
+        const endpointCandidates = [
+            endpoint,
+            ...candidateEndpoints.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
+        };
+    }
+
+    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
+        };
+    }
+
+    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;
+        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,
+            heartbeatMs,
+            taskTimeoutMs,
+            managerPackage,
+            managerVersion,
+            hostInstanceId,
+            agentPackage: '@mindexec/remote',
+            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,
+            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 || ''));
+                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 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,
+            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, 'remote-fast', {
+            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 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'];
+
+        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 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: `Synthetic PC ${String(ordinal).padStart(4, '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,
+                    usedMemRatio,
+                    loadavg: [load1, Math.max(0, load1 - 0.2), Math.max(0, load1 - 0.4)]
+                },
+                latestThumbnail: null,
+                latestLiveFrame: null,
+                recentFramePayloads: {
+                    thumbnail: [],
+                    live: []
+                },
+                activeLiveStream: 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) {
+                device.activeLiveStream = {
+                    streamId: `synthetic-live-${ordinal}`,
+                    commandId: `synthetic-live-command-${ordinal}`,
+                    active: true,
+                    mode: 'remote-fast',
+                    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 now = new Date().toISOString();
+        const sessionId = crypto.randomUUID();
+        const deviceId = normalizeDeviceId(hello.deviceId);
+
+        closeExistingDeviceSocket(deviceId, sessionId);
+
+        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),
+            pid: Number.isFinite(Number(hello.pid)) ? Number(hello.pid) : 0,
+            agentVersion: safeString(hello.agentVersion, 40),
+            capabilities: typeof hello.capabilities === 'object' && hello.capabilities
+                ? { ...hello.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,
+            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',
+            protocolVersion: REMOTE_PROTOCOL_VERSION,
+            sessionId,
+            deviceId,
+            heartbeatMs,
+            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 readFrameDroppedByAgent(message) {
+        const value = Number(message.droppedByAgent ?? message.agentDrops ?? message.drops);
+        return Number.isFinite(value) && value >= 0
+            ? Math.round(value)
+            : 0;
+    }
+
+    function readFrameDirtyRectCount(message) {
+        if (Array.isArray(message.dirtyRects)) {
+            return message.dirtyRects.length;
+        }
+
+        const value = Number(message.dirtyRectCount ?? message.dirtyRegionCount ?? message.changedRegionCount);
+        return Number.isFinite(value) && value >= 0
+            ? Math.round(value)
+            : 0;
+    }
+
+    function readFrameDirtyPixelRatio(message) {
+        const value = Number(message.dirtyPixelRatio ?? message.dirtyRatio ?? message.dirtyAreaRatio ?? message.changedPixelRatio);
+        if (!Number.isFinite(value) || value < 0) {
+            return 0;
+        }
+
+        if (value <= 1) {
+            return value;
+        }
+
+        if (value <= 100) {
+            return value / 100;
+        }
+
+        return 1;
+    }
+
+    function readFrameDeltaEncoded(message) {
+        const value = message.deltaEncoded ?? message.isDeltaEncoded ?? message.deltaFrame;
+        if (typeof value === 'boolean') {
+            return value;
+        }
+
+        if (typeof value === 'number') {
+            return value > 0;
+        }
+
+        return /^(1|true|yes|on|delta)$/i.test(String(value || '').trim());
+    }
+
+    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 droppedByAgent = readFrameDroppedByAgent(message);
+        const dirtyRectCount = readFrameDirtyRectCount(message);
+        const dirtyPixelRatio = readFrameDirtyPixelRatio(message);
+        const codec = safeString(message.codec || message.encoder || message.encoding, 80);
+        const deltaEncoded = readFrameDeltaEncoded(message);
+        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,
+            capturedAt,
+            receivedAt: device.lastSeenAt,
+            byteLength,
+            transport,
+            contentHash,
+            captureMs: readFrameCaptureMs(message),
+            sameContentStreak,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded,
+            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,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded
+        });
+        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 droppedByAgent = readFrameDroppedByAgent(message);
+        const dirtyRectCount = readFrameDirtyRectCount(message);
+        const dirtyPixelRatio = readFrameDirtyPixelRatio(message);
+        const codec = safeString(message.codec || message.encoder || message.encoding, 80);
+        const deltaEncoded = readFrameDeltaEncoded(message);
+        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: safeString(message.mode || device.activeLiveStream.mode || 'remote-fast', 80),
+            fps: Number.isFinite(Number(message.fps)) ? Number(message.fps) : device.activeLiveStream.fps,
+            capturedAt,
+            receivedAt: device.lastSeenAt,
+            byteLength,
+            transport,
+            contentHash,
+            captureMs: readFrameCaptureMs(message),
+            sameContentStreak,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded,
+            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.counters.liveFramesReceived += 1;
+        emitRemoteEvent('RemoteFrameReceived', device, {
+            streamId,
+            frameSeq,
+            width: device.latestLiveFrame.width,
+            height: device.latestLiveFrame.height,
+            mode: device.latestLiveFrame.mode,
+            transport,
+            contentHash,
+            sameContentStreak,
+            droppedByAgent,
+            dirtyRectCount,
+            dirtyPixelRatio,
+            codec,
+            deltaEncoded
+        });
+        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;
+        }
+
+        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;
+            }
+
+            state.authenticated = true;
+            state.device = attachDevice(socket, message);
+            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 }
+                    : {};
+                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.frame': {
+                applyLiveFrame(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();
+            device.counters.commandsSent += 1;
+            device.activeLiveStream = {
+                streamId,
+                commandId,
+                active: true,
+                mode: 'remote-fast',
+                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,
+                synthetic: true
+            });
+            return { ok: true, commandId, streamId, fps, 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 result = sendCommand(deviceId, {
+            command: 'stream.start',
+            commandId,
+            payload: {
+                streamId,
+                mode: safeString(options.mode, 80) || 'remote-fast',
+                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,
+            mode: 'remote-fast',
+            fps,
+            startedAt: now,
+            stoppedAt: '',
+            stopReason: '',
+            lastFrameAt: '',
+            lastFrameSeq: 0,
+            framesReceived: 0
+        };
+        device.counters.liveStreamsStarted += 1;
+        emitRemoteEvent('RemoteLiveStreamStarted', device, {
+            streamId,
+            commandId,
+            fps
+        });
+
+        return { ok: true, commandId, streamId, fps };
+    }
+
+    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 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,
+        getDeviceLiveFrame,
+        getDeviceThumbnail,
+        getFramePayload,
+        seedSyntheticFleet,
+        clearSyntheticFleet,
+        getPairToken: () => pairToken
+    };
+}
+
+export function getDefaultRemoteAgentDeviceInfo() {
+    return {
+        hostname: os.hostname(),
+        platform: os.platform(),
+        arch: os.arch(),
+        pid: process.pid
+    };
+}