@mindexec/cli 0.2.116 → 0.2.118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.116",
+  "version": "0.2.118",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",
@@ -20,7 +20,7 @@
   "scripts": {
     "start": "node launch-bridge.cjs",
     "dev": "node launch-bridge.cjs --watch",
-    "test:syntax": "node --check server.js && node --check remote-hub.js && node --check codex-runtime.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check scripts/setup-tree-sitter-grammars.mjs && node --check scripts/auth-session-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs && node --check scripts/remote-frame-ws-smoke.mjs",
+    "test:syntax": "node --check server.js && node --check remote-hub.js && node --check codex-runtime.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check scripts/setup-tree-sitter-grammars.mjs && node --check scripts/auth-session-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs && node --check scripts/remote-frame-ws-smoke.mjs && node --check scripts/remote-agent-ws-smoke.mjs",
     "test:auth": "node scripts/auth-session-smoke.mjs",
     "test:remote": "node scripts/remote-hub-smoke.mjs",
     "test:remote:scale": "node scripts/remote-hub-scale-smoke.mjs",
@@ -47,7 +47,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@mindexec/remote": "^0.1.16",
+    "@mindexec/remote": "^0.1.17",
     "@openai/codex-sdk": "^0.137.0",
     "chokidar": "^3.6.0",
     "cors": "^2.8.5",

package/remote-hub.js

@@ -592,10 +592,266 @@ function writeJsonLine(socket, payload) {
         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 || (() => {});
@@ -1921,7 +2177,146 @@ export function createRemoteHub(options = {}) {
         }
     }
 
-    function handleSocket(socket) {
+    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);
@@ -1940,7 +2335,7 @@ export function createRemoteHub(options = {}) {
             }
         }, 10000);
 
-        socket.on('data', chunk => {
+        const processData = chunk => {
             const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
             state.buffer = state.buffer.length > 0
                 ? Buffer.concat([state.buffer, incoming])
@@ -1999,7 +2394,12 @@ export function createRemoteHub(options = {}) {
                     logWarn('remote', `invalid agent message: ${err?.message || err}`);
                 }
             }
-        });
+        };
+
+        socket.on('data', processData);
+        if (firstChunk) {
+            processData(firstChunk);
+        }
 
         socket.on('close', () => {
             allSockets.delete(socket);
@@ -2013,6 +2413,22 @@ export function createRemoteHub(options = {}) {
         });
     }
 
+    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 });

package/scripts/remote-agent-ws-smoke.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { WebSocket } from 'ws';
+import { createRemoteHub } from '../remote-hub.js';
+
+const PAIR_TOKEN = 'remote-agent-ws-smoke-token';
+const DEVICE_ID = 'remote-agent-ws-smoke-device';
+const SMOKE_PNG = Buffer.from(
+    'iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAYAAAD0In+KAAAADElEQVR42mP8z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC',
+    'base64');
+
+function wait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function waitFor(predicate, timeoutMs = 5000, label = 'condition') {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const value = predicate();
+        if (value) {
+            return value;
+        }
+        await wait(25);
+    }
+
+    throw new Error(`Timed out waiting for ${label}.`);
+}
+
+function writeAgentBinaryFrame(ws, header, payload) {
+    const framePayload = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    const metadata = Buffer.from(JSON.stringify({
+        ...header,
+        type: 'frame.binary',
+        byteLength: framePayload.length
+    }), 'utf8');
+    const packet = Buffer.allocUnsafe(4 + metadata.length + framePayload.length);
+    packet.writeUInt32BE(metadata.length, 0);
+    metadata.copy(packet, 4);
+    framePayload.copy(packet, 4 + metadata.length);
+    ws.send(packet);
+}
+
+const hub = createRemoteHub({
+    env: {
+        MINDEXEC_REMOTE_HUB: '1',
+        REMOTE_HUB_HOST: '127.0.0.1',
+        REMOTE_HUB_PORT: '0',
+        REMOTE_HUB_PAIR_TOKEN: PAIR_TOKEN
+    }
+});
+
+let ws = null;
+
+try {
+    await hub.start();
+    const status = hub.getStatus({ includeSecrets: true });
+    assert.equal(status.started, true);
+
+    ws = new WebSocket(`ws://127.0.0.1:${status.port}/remote-agent`);
+    const received = [];
+    ws.on('message', data => {
+        if (typeof data !== 'string' && !Buffer.isBuffer(data)) {
+            return;
+        }
+
+        const text = Buffer.isBuffer(data) ? data.toString('utf8') : data;
+        if (!text.trim().startsWith('{')) {
+            return;
+        }
+
+        received.push(JSON.parse(text));
+    });
+
+    await new Promise((resolve, reject) => {
+        ws.once('open', resolve);
+        ws.once('error', reject);
+    });
+
+    ws.send(JSON.stringify({
+        type: 'hello',
+        pairToken: PAIR_TOKEN,
+        deviceId: DEVICE_ID,
+        deviceName: 'Remote Agent WS Smoke',
+        hostname: 'remote-agent-ws-smoke',
+        platform: process.platform,
+        arch: process.arch,
+        pid: process.pid,
+        agentVersion: '0.0.0-ws-smoke',
+        runtime: 'node-smoke',
+        capabilities: {
+            status: true,
+            thumbnail: true,
+            liveStream: true,
+            binaryFrames: true,
+            control: true,
+            computerAgent: true,
+            taskDispatch: true,
+            aiAssist: false
+        }
+    }));
+    ws.send(JSON.stringify({
+        type: 'status',
+        status: {
+            uptimeSec: 1,
+            totalMem: 2,
+            freeMem: 1,
+            timestamp: new Date().toISOString()
+        }
+    }));
+
+    await waitFor(() => received.find(item => item.type === 'welcome'), 5000, 'welcome');
+    const device = await waitFor(() => {
+        const current = hub.listDevices();
+        return current.length === 1 && current[0].deviceId === DEVICE_ID ? current[0] : null;
+    }, 5000, 'device registration');
+    assert.equal(device.connected, true);
+    assert.equal(device.capabilities.binaryFrames, true);
+
+    const inputCommand = hub.sendInputControl(DEVICE_ID, { type: 'noop' });
+    assert.equal(inputCommand.ok, true);
+    const inputMessage = await waitFor(
+        () => received.find(item => item.commandId === inputCommand.commandId),
+        5000,
+        'input command');
+    assert.equal(inputMessage.command, 'input.control');
+    ws.send(JSON.stringify({
+        type: 'command.result',
+        commandId: inputCommand.commandId,
+        result: {
+            input: true,
+            handled: true
+        }
+    }));
+    await waitFor(() => hub.listDevices()[0]?.counters?.commandResultsReceived === 1, 5000, 'input result');
+
+    const thumbnailCommand = hub.requestThumbnail(DEVICE_ID, {
+        streamId: 'remote-agent-ws-thumb',
+        maxWidth: 320,
+        maxHeight: 180,
+        quality: 50
+    });
+    assert.equal(thumbnailCommand.ok, true);
+    await waitFor(
+        () => received.find(item => item.commandId === thumbnailCommand.commandId),
+        5000,
+        'thumbnail command');
+    writeAgentBinaryFrame(ws, {
+        frameKind: 'thumbnail',
+        commandId: thumbnailCommand.commandId,
+        streamId: 'remote-agent-ws-thumb',
+        frameSeq: 11,
+        width: 2,
+        height: 1,
+        mimeType: 'image/png',
+        capturedAt: new Date().toISOString()
+    }, SMOKE_PNG);
+    const thumbnailDevice = await waitFor(() => {
+        const current = hub.listDevices()[0];
+        return current?.latestThumbnail?.frameSeq === 11 ? current : null;
+    }, 5000, 'websocket binary thumbnail');
+    assert.equal(thumbnailDevice.latestThumbnail.transport, 'binary');
+    assert.equal(thumbnailDevice.latestThumbnail.byteLength, SMOKE_PNG.length);
+
+    const liveCommand = hub.startLiveStream(DEVICE_ID, {
+        streamId: 'remote-agent-ws-live',
+        fps: 10,
+        maxWidth: 320,
+        maxHeight: 180,
+        quality: 50
+    });
+    assert.equal(liveCommand.ok, true);
+    await waitFor(
+        () => received.find(item => item.commandId === liveCommand.commandId),
+        5000,
+        'live command');
+    writeAgentBinaryFrame(ws, {
+        frameKind: 'stream',
+        commandId: liveCommand.commandId,
+        streamId: 'remote-agent-ws-live',
+        frameSeq: 12,
+        width: 2,
+        height: 1,
+        mimeType: 'image/png',
+        fps: 10,
+        capturedAt: new Date().toISOString()
+    }, SMOKE_PNG);
+    const liveDevice = await waitFor(() => {
+        const current = hub.listDevices()[0];
+        return current?.latestLiveFrame?.frameSeq === 12 ? current : null;
+    }, 5000, 'websocket binary live frame');
+    assert.equal(liveDevice.latestLiveFrame.transport, 'binary');
+    assert.equal(liveDevice.latestLiveFrame.streamId, 'remote-agent-ws-live');
+
+    ws.close();
+    console.log('RemoteAgent WebSocket smoke OK');
+} finally {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.close();
+    }
+    await hub.close();
+}

package/server.js

@@ -2906,7 +2906,11 @@ const REMOTE_AGENT_STDIO_TAIL_CHARS = 12000;
 const REMOTE_AGENT_EARLY_EXIT_MS = 1200;
 const REMOTE_AGENT_READY_TIMEOUT_MS = 5000;
 const REMOTE_AGENT_DEFAULT_ENGINE = 'auto';
+const REMOTE_AGENT_SYNC_REPORT_LOG_REPEAT_MS = 30000;
 let remoteAgentState = createRemoteAgentIdleState();
+let remoteAgentSyncReportState = null;
+let remoteAgentSyncReportLogKey = '';
+let remoteAgentSyncReportLogAt = 0;
 
 function createRemoteAgentIdleState(overrides = {}) {
     return {
@@ -2940,6 +2944,7 @@ function serializeRemoteAgentState() {
     const { proc, ...publicState } = remoteAgentState;
     return {
         ...publicState,
+        registrySync: remoteAgentSyncReportState,
         running: remoteAgentState.status === 'running'
             && !!remoteAgentState.proc
             && remoteAgentState.proc.exitCode === null
@@ -2947,6 +2952,71 @@ function serializeRemoteAgentState() {
     };
 }
 
+function createRemoteAgentSyncReport(body = {}) {
+    const normalizeList = value => Array.isArray(value)
+        ? value.map(item => safeRemoteAgentField(item, 160)).filter(Boolean).slice(0, 12)
+        : [];
+    return {
+        ok: body.ok === true || body.Ok === true,
+        attempted: body.attempted === true || body.Attempted === true,
+        connected: body.connected === true || body.Connected === true,
+        disconnected: body.disconnected === true || body.Disconnected === true,
+        skipped: body.skipped === true || body.Skipped === true,
+        reason: safeRemoteAgentField(body.reason || body.Reason, 160),
+        error: safeRemoteAgentField(body.error || body.Error, 240),
+        trigger: safeRemoteAgentField(body.trigger || body.Trigger, 80),
+        authenticated: body.authenticated === true || body.Authenticated === true,
+        localHostTargetActive: body.localHostTargetActive === true || body.LocalHostTargetActive === true,
+        localHostTargetLeaseId: safeRemoteAgentField(body.localHostTargetLeaseId || body.LocalHostTargetLeaseId, 128),
+        localHostTargetNodeId: safeRemoteAgentField(body.localHostTargetNodeId || body.LocalHostTargetNodeId, 128),
+        targetActive: body.targetActive === true || body.TargetActive === true,
+        targetEndpoint: normalizeRemoteManagerEndpoint(body.targetEndpoint || body.TargetEndpoint),
+        targetEndpointCandidates: normalizeList(body.targetEndpointCandidates || body.TargetEndpointCandidates),
+        targetLeaseId: safeRemoteAgentField(body.targetLeaseId || body.TargetLeaseId, 128),
+        targetNodeId: safeRemoteAgentField(body.targetNodeId || body.TargetNodeId, 128),
+        targetExpiresAt: safeRemoteAgentField(body.targetExpiresAt || body.TargetExpiresAt, 80),
+        updatedAt: new Date().toISOString()
+    };
+}
+
+function rememberRemoteAgentSyncReport(report) {
+    remoteAgentSyncReportState = report;
+    const reason = report.reason || report.error || (report.ok ? 'ok' : 'failed');
+    const status = report.connected
+        ? 'connected'
+        : report.disconnected
+            ? 'disconnected'
+            : report.attempted
+                ? 'attempted'
+                : report.skipped
+                    ? 'skipped'
+                    : report.ok
+                        ? 'ok'
+                        : 'failed';
+    const key = [
+        status,
+        reason,
+        report.targetEndpoint || '',
+        report.targetLeaseId || '',
+        report.localHostTargetActive ? 'local-host' : ''
+    ].join('|');
+    const now = Date.now();
+    if (reason === 'throttled') {
+        return;
+    }
+    if (key === remoteAgentSyncReportLogKey
+        && now - remoteAgentSyncReportLogAt < REMOTE_AGENT_SYNC_REPORT_LOG_REPEAT_MS) {
+        return;
+    }
+
+    remoteAgentSyncReportLogKey = key;
+    remoteAgentSyncReportLogAt = now;
+    logEvent(
+        'remote',
+        `registry sync ${status} ${formatKeyValue('reason', reason)} ${formatKeyValue('target', report.targetEndpoint || '-')} ${formatKeyValue('auth', report.authenticated ? 'yes' : 'no')}`,
+        'remote');
+}
+
 function appendRemoteAgentOutput(stream, chunk, stateConnectionKey = '') {
     if (stateConnectionKey && remoteAgentState.connectionKey !== stateConnectionKey) {
         return;
@@ -8066,6 +8136,13 @@ app.get('/api/remote/agent/status', (req, res) => {
     res.json(serializeRemoteAgentState());
 });
 
+app.post('/api/remote/agent/sync-report', (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const report = createRemoteAgentSyncReport(req.body || {});
+    rememberRemoteAgentSyncReport(report);
+    res.json({ ok: true, report });
+});
+
 app.post('/api/remote/agent/connect', async (req, res) => {
     res.setHeader('Cache-Control', 'no-store');
     try {

package/wwwroot/_content/MindExecution.Shared/js/mind-map-css3d-manager.js

@@ -13359,6 +13359,8 @@
     const REMOTE_FLEET_TASK_FOLLOW_REFRESH_MS = 2000;
     const REMOTE_FLEET_TASK_FOLLOW_MAX_TICKS = 60;
     const REMOTE_FLEET_HOST_LEASE_REFRESH_MS = 10000;
+    const REMOTE_FLEET_AUTO_HOST_STORAGE_KEY = 'MindExec.RemoteFleet.AutoHost';
+    const REMOTE_FLEET_AUTO_HOST_NODE_STORAGE_KEY = 'MindExec.RemoteFleet.AutoHostNodeId';
     const remoteFleetHostLeaseTimers = new Map();
     const remoteFleetLocalHostTargets = new Map();
     const remoteFleetBinaryFrameSessions = new Map();
@@ -13445,6 +13447,31 @@
         return result?.active === false || result?.Active === false;
     }
 
+    function isRemoteFleetAutoHostEnabled(nodeId) {
+        try {
+            const enabled = String(localStorage.getItem(REMOTE_FLEET_AUTO_HOST_STORAGE_KEY) || '').trim().toLowerCase();
+            if (enabled !== 'true') return false;
+            const storedNodeId = String(localStorage.getItem(REMOTE_FLEET_AUTO_HOST_NODE_STORAGE_KEY) || '').trim();
+            return !storedNodeId || storedNodeId === String(nodeId || '').trim();
+        } catch {
+            return false;
+        }
+    }
+
+    function rememberRemoteFleetAutoHostPreference(nodeId, enabled) {
+        try {
+            if (enabled === true) {
+                localStorage.setItem(REMOTE_FLEET_AUTO_HOST_STORAGE_KEY, 'true');
+                localStorage.setItem(REMOTE_FLEET_AUTO_HOST_NODE_STORAGE_KEY, String(nodeId || '').trim());
+            } else {
+                localStorage.removeItem(REMOTE_FLEET_AUTO_HOST_STORAGE_KEY);
+                localStorage.removeItem(REMOTE_FLEET_AUTO_HOST_NODE_STORAGE_KEY);
+            }
+        } catch {
+            // localStorage may be unavailable in restricted browser modes.
+        }
+    }
+
     function rememberRemoteFleetLocalHostTarget(nodeId, enabled, result) {
         const id = String(nodeId || '').trim();
         if (!id) return;
@@ -17371,6 +17398,7 @@
         const setRemoteFleetHostTarget = async (enabled, options = {}) => {
             const quiet = options?.quiet === true;
             const renew = options?.renew === true || quiet;
+            const syncNodeState = quiet !== true || options?.sync === true;
             const activeButton = enabled ? hostButton : null;
             if (!quiet && activeButton) {
                 activeButton.disabled = true;
@@ -17389,10 +17417,16 @@
                     error: result?.error || result?.Error || ''
                 });
                 rememberRemoteFleetLocalHostTarget(nodeId, enabled === true, result);
+                if (isRemoteFleetResultSuccess(result)) {
+                    rememberRemoteFleetAutoHostPreference(nodeId, enabled === true && isRemoteFleetResultActive(result));
+                }
                 if (quiet) {
                     if (!isRemoteFleetResultSuccess(result) || !isRemoteFleetResultActive(result)) {
                         stopRemoteFleetHostLeaseTimer(nodeId);
                     }
+                    if (syncNodeState) {
+                        await syncRemoteFleetNodeStateFromResult(result);
+                    }
                     return result;
                 }
                 await syncRemoteFleetNodeStateFromResult(result);
@@ -17577,6 +17611,17 @@
 
         if (isHostingTarget) {
             startRemoteFleetHostLeaseTimer(nodeId, () => setRemoteFleetHostTarget(true, { quiet: true, renew: true }));
+        } else if (isRemoteFleetAutoHostEnabled(nodeId) && bodyView._remoteFleetAutoHostRestoreStarted !== true) {
+            bodyView._remoteFleetAutoHostRestoreStarted = true;
+            setTimeout(() => {
+                if (!document.body.contains(bodyView)) return;
+                setRemoteFleetHostTarget(true, { quiet: true, renew: true, sync: true }).catch(error => {
+                    window.RuntimeTrace?.emit?.('remote.hostTarget.autoRestoreFailed', {
+                        nodeId,
+                        error: error?.message || String(error || '')
+                    });
+                });
+            }, 250);
         }
 
         const hasVisibleLiveTarget = getVisibleLiveFrameDeviceIds().length > 0

package/wwwroot/_framework/blazor.boot.json

@@ -1,7 +1,7 @@
 {
   "mainAssemblyName": "MindExecution.Web",
   "resources": {
-    "hash": "sha256-JxTp+hXYDhd47gICFMzpCDWm8b4z1JGet67SEEI1F3c=",
+    "hash": "sha256-Sm5LEcaIEbOQMLRdM7FmN29gN1AP1yTcQOVH+E/ZgGY=",
     "fingerprinting": {
       "Google.Protobuf.9h59ukbel7.dll": "Google.Protobuf.dll",
       "Markdig.d1j7v41cl1.dll": "Markdig.dll",
@@ -123,16 +123,16 @@
       "System.brmz7yk5qh.dll": "System.dll",
       "netstandard.yvr3prsx0x.dll": "netstandard.dll",
       "System.Private.CoreLib.c1dbswx1b2.dll": "System.Private.CoreLib.dll",
-      "MindExecution.Core.fc9cjbjplq.dll": "MindExecution.Core.dll",
-      "MindExecution.Kernel.pbzp3jfync.dll": "MindExecution.Kernel.dll",
-      "MindExecution.Plugins.Admin.gxzwlji1cf.dll": "MindExecution.Plugins.Admin.dll",
-      "MindExecution.Plugins.Business.vtaey8c59y.dll": "MindExecution.Plugins.Business.dll",
-      "MindExecution.Plugins.Concept.85y7un1ks6.dll": "MindExecution.Plugins.Concept.dll",
-      "MindExecution.Plugins.Directory.zc8ffaoknd.dll": "MindExecution.Plugins.Directory.dll",
-      "MindExecution.Plugins.PlanMaster.ylooagumgh.dll": "MindExecution.Plugins.PlanMaster.dll",
-      "MindExecution.Plugins.YouTube.azfozpumhv.dll": "MindExecution.Plugins.YouTube.dll",
-      "MindExecution.Shared.mppf8quyau.dll": "MindExecution.Shared.dll",
-      "MindExecution.Web.tln762tijf.dll": "MindExecution.Web.dll",
+      "MindExecution.Core.asayb4hw1o.dll": "MindExecution.Core.dll",
+      "MindExecution.Kernel.3zom09ir6j.dll": "MindExecution.Kernel.dll",
+      "MindExecution.Plugins.Admin.bk23zzy6wc.dll": "MindExecution.Plugins.Admin.dll",
+      "MindExecution.Plugins.Business.zwcvc8wufe.dll": "MindExecution.Plugins.Business.dll",
+      "MindExecution.Plugins.Concept.lxunwcdjgq.dll": "MindExecution.Plugins.Concept.dll",
+      "MindExecution.Plugins.Directory.jc0g7fvyzv.dll": "MindExecution.Plugins.Directory.dll",
+      "MindExecution.Plugins.PlanMaster.2sugb66h95.dll": "MindExecution.Plugins.PlanMaster.dll",
+      "MindExecution.Plugins.YouTube.vy0nsbcoo4.dll": "MindExecution.Plugins.YouTube.dll",
+      "MindExecution.Shared.e8lipb57xv.dll": "MindExecution.Shared.dll",
+      "MindExecution.Web.994sb3nzuy.dll": "MindExecution.Web.dll",
       "dotnet.js": "dotnet.js",
       "dotnet.native.qc8g39g30v.js": "dotnet.native.js",
       "dotnet.native.boem75ye5i.wasm": "dotnet.native.wasm",
@@ -278,18 +278,18 @@
       "System.Xml.XDocument.sn51jas17n.dll": "sha256-GNI2kFgFmPTwzuzwUn8gxK+AzGLUWRJFdg9JzIbrybQ=",
       "System.brmz7yk5qh.dll": "sha256-CfM2miyj1KHApFmqMdLYWio3S/jrdON2pW9Xr2nTwlo=",
       "netstandard.yvr3prsx0x.dll": "sha256-EksNn8Luo4bOWqJ6X7dIe9qG9oOqwOVzjH2xYyMNi+E=",
-      "MindExecution.Core.fc9cjbjplq.dll": "sha256-TymUFwryFLdbCYy2U5qdgE2ZV1yHaLR9bgyrmx6Tcp0=",
-      "MindExecution.Kernel.pbzp3jfync.dll": "sha256-Ff6WHyLD39V0fEjUiQlxX9Y+edssyTH+7T4zfBdj3s0=",
-      "MindExecution.Plugins.Concept.85y7un1ks6.dll": "sha256-ZK10a6NfAZTCKX0BpiH6e+pBatMwTeXMCtA79A+zGQg=",
-      "MindExecution.Plugins.PlanMaster.ylooagumgh.dll": "sha256-aoNSkErjCAqRgET/An00bm2GP3Jsnnu4hz8e/jpaLcI=",
-      "MindExecution.Shared.mppf8quyau.dll": "sha256-FsB415v0PlO8/788VKC99rE/BhViR61KcM9+Crxo9Ok=",
-      "MindExecution.Web.tln762tijf.dll": "sha256-vy73kyPmRU7hqhUFOFs9fdsn5AWmO7cNTRDoWigkc2M="
+      "MindExecution.Core.asayb4hw1o.dll": "sha256-5gla4JTR/zbvkGpneSt6S7ItE51+MjWgjW6L+B6Yevk=",
+      "MindExecution.Kernel.3zom09ir6j.dll": "sha256-78vR2SNkF9FwdQv0fEItSyz4HzgyzwGUROJAnpripPA=",
+      "MindExecution.Plugins.Concept.lxunwcdjgq.dll": "sha256-WVyvjaxW6UoGQvGW0icChLsXwYVCcdn0BLTftzlkCKc=",
+      "MindExecution.Plugins.PlanMaster.2sugb66h95.dll": "sha256-Lp0AieRHDo2H4Yl0Il1pPruy9nFUHJsX9t1AblXGD6Y=",
+      "MindExecution.Shared.e8lipb57xv.dll": "sha256-Au9QMwnm9MaP2+xzdldeQYtj4tRXzwOBWYOxmYR8spM=",
+      "MindExecution.Web.994sb3nzuy.dll": "sha256-jQshtLmhEC4xenzdD9PqHjaCuKvJf/frzaKBi2weDAg="
     },
     "lazyAssembly": {
-      "MindExecution.Plugins.Admin.gxzwlji1cf.dll": "sha256-5D5B2ZuUMj46zBMgH2dRA7CbQf++uukMPrEliFLuZWs=",
-      "MindExecution.Plugins.Business.vtaey8c59y.dll": "sha256-rU9MzRRmHuj0/IluV1dvE6x3aRCK/DA4DWKy1DO4VVg=",
-      "MindExecution.Plugins.Directory.zc8ffaoknd.dll": "sha256-Ey/HajaVuBxB/Ou4qsM70nhAZBoODeCENzG1J/uEsxs=",
-      "MindExecution.Plugins.YouTube.azfozpumhv.dll": "sha256-GjL5SM7+D8SKJBE528Y5Py29kQrTXPmG5OFr6+E0L4s="
+      "MindExecution.Plugins.Admin.bk23zzy6wc.dll": "sha256-uz7Nz0OZ8BBESp2Nr9YocyzV0dUrn7szPuD4/m/RWL8=",
+      "MindExecution.Plugins.Business.zwcvc8wufe.dll": "sha256-3YDsB2/uNI+feWqJk+cesLHgNt8s2/8hXxGPO6CRZZE=",
+      "MindExecution.Plugins.Directory.jc0g7fvyzv.dll": "sha256-PSe7135JPpTBmu4j+rGLF0Dc/6w/wDJNPi8zlfTmSMk=",
+      "MindExecution.Plugins.YouTube.vy0nsbcoo4.dll": "sha256-p8w1TI9Ri41EAG/j0MJCiuEcJdr4x/Hr5Spd2oluZjM="
     }
   },
   "cacheBootResources": true,

package/wwwroot/service-worker-assets.js

@@ -1,5 +1,5 @@
 self.assetsManifest = {
-    "version":  "pV7f33KI",
+    "version":  "31UVI5Fx",
     "assets":  [
                    {
                        "hash":  "sha256-+CSYMcqLNTsq3VnH11jgYyOCCdxvHzL74CBmo4sCmMU=",
@@ -86,7 +86,7 @@
                        "url":  "_content/MindExecution.Shared/js/mind-map-core.js.backup"
                    },
                    {
-                       "hash":  "sha256-8uQGgnoT3SXKM89hTz49ThSpGgT88GRP7ipe8xlR3z0=",
+                       "hash":  "sha256-vpLVZnaAN2JQkbnKVrjBOCGkbHU0uveNB4vqR1sMyHg=",
                        "url":  "_content/MindExecution.Shared/js/mind-map-css3d-manager.js"
                    },
                    {
@@ -410,44 +410,44 @@
                        "url":  "_framework/MimeMapping.og9ys58ylm.dll"
                    },
                    {
-                       "hash":  "sha256-TymUFwryFLdbCYy2U5qdgE2ZV1yHaLR9bgyrmx6Tcp0=",
-                       "url":  "_framework/MindExecution.Core.fc9cjbjplq.dll"
+                       "hash":  "sha256-5gla4JTR/zbvkGpneSt6S7ItE51+MjWgjW6L+B6Yevk=",
+                       "url":  "_framework/MindExecution.Core.asayb4hw1o.dll"
                    },
                    {
-                       "hash":  "sha256-Ff6WHyLD39V0fEjUiQlxX9Y+edssyTH+7T4zfBdj3s0=",
-                       "url":  "_framework/MindExecution.Kernel.pbzp3jfync.dll"
+                       "hash":  "sha256-78vR2SNkF9FwdQv0fEItSyz4HzgyzwGUROJAnpripPA=",
+                       "url":  "_framework/MindExecution.Kernel.3zom09ir6j.dll"
                    },
                    {
-                       "hash":  "sha256-5D5B2ZuUMj46zBMgH2dRA7CbQf++uukMPrEliFLuZWs=",
-                       "url":  "_framework/MindExecution.Plugins.Admin.gxzwlji1cf.dll"
+                       "hash":  "sha256-uz7Nz0OZ8BBESp2Nr9YocyzV0dUrn7szPuD4/m/RWL8=",
+                       "url":  "_framework/MindExecution.Plugins.Admin.bk23zzy6wc.dll"
                    },
                    {
-                       "hash":  "sha256-rU9MzRRmHuj0/IluV1dvE6x3aRCK/DA4DWKy1DO4VVg=",
-                       "url":  "_framework/MindExecution.Plugins.Business.vtaey8c59y.dll"
+                       "hash":  "sha256-3YDsB2/uNI+feWqJk+cesLHgNt8s2/8hXxGPO6CRZZE=",
+                       "url":  "_framework/MindExecution.Plugins.Business.zwcvc8wufe.dll"
                    },
                    {
-                       "hash":  "sha256-ZK10a6NfAZTCKX0BpiH6e+pBatMwTeXMCtA79A+zGQg=",
-                       "url":  "_framework/MindExecution.Plugins.Concept.85y7un1ks6.dll"
+                       "hash":  "sha256-WVyvjaxW6UoGQvGW0icChLsXwYVCcdn0BLTftzlkCKc=",
+                       "url":  "_framework/MindExecution.Plugins.Concept.lxunwcdjgq.dll"
                    },
                    {
-                       "hash":  "sha256-Ey/HajaVuBxB/Ou4qsM70nhAZBoODeCENzG1J/uEsxs=",
-                       "url":  "_framework/MindExecution.Plugins.Directory.zc8ffaoknd.dll"
+                       "hash":  "sha256-PSe7135JPpTBmu4j+rGLF0Dc/6w/wDJNPi8zlfTmSMk=",
+                       "url":  "_framework/MindExecution.Plugins.Directory.jc0g7fvyzv.dll"
                    },
                    {
-                       "hash":  "sha256-aoNSkErjCAqRgET/An00bm2GP3Jsnnu4hz8e/jpaLcI=",
-                       "url":  "_framework/MindExecution.Plugins.PlanMaster.ylooagumgh.dll"
+                       "hash":  "sha256-Lp0AieRHDo2H4Yl0Il1pPruy9nFUHJsX9t1AblXGD6Y=",
+                       "url":  "_framework/MindExecution.Plugins.PlanMaster.2sugb66h95.dll"
                    },
                    {
-                       "hash":  "sha256-GjL5SM7+D8SKJBE528Y5Py29kQrTXPmG5OFr6+E0L4s=",
-                       "url":  "_framework/MindExecution.Plugins.YouTube.azfozpumhv.dll"
+                       "hash":  "sha256-p8w1TI9Ri41EAG/j0MJCiuEcJdr4x/Hr5Spd2oluZjM=",
+                       "url":  "_framework/MindExecution.Plugins.YouTube.vy0nsbcoo4.dll"
                    },
                    {
-                       "hash":  "sha256-FsB415v0PlO8/788VKC99rE/BhViR61KcM9+Crxo9Ok=",
-                       "url":  "_framework/MindExecution.Shared.mppf8quyau.dll"
+                       "hash":  "sha256-Au9QMwnm9MaP2+xzdldeQYtj4tRXzwOBWYOxmYR8spM=",
+                       "url":  "_framework/MindExecution.Shared.e8lipb57xv.dll"
                    },
                    {
-                       "hash":  "sha256-vy73kyPmRU7hqhUFOFs9fdsn5AWmO7cNTRDoWigkc2M=",
-                       "url":  "_framework/MindExecution.Web.tln762tijf.dll"
+                       "hash":  "sha256-jQshtLmhEC4xenzdD9PqHjaCuKvJf/frzaKBi2weDAg=",
+                       "url":  "_framework/MindExecution.Web.994sb3nzuy.dll"
                    },
                    {
                        "hash":  "sha256-IsZJ91/OW+fHzNqIgEc7Y072ns8z9dGritiSyvR9Wgc=",
@@ -770,7 +770,7 @@
                        "url":  "_framework/Websocket.Client.vapounvmnl.dll"
                    },
                    {
-                       "hash":  "sha256-HDeRZ1juous1GiTsZw+QLukbDxOOYjh72G4Dta2w5Fc=",
+                       "hash":  "sha256-XSS0rv+S2JAW90BVDbFUd23REh87EAC1P5aFjXSMAGo=",
                        "url":  "_framework/blazor.boot.json"
                    },
                    {

package/wwwroot/service-worker.js

@@ -1,4 +1,4 @@
-/* Manifest version: pV7f33KI */
+/* Manifest version: 31UVI5Fx */
 // Hosted deployments should prefer the network over stale offline caches.
 // This service worker immediately clears old Blazor offline caches and unregisters itself.