@mindexec/cli 0.2.119 → 0.2.120

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.119",
+  "version": "0.2.120",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",

package/remote-hub.js

@@ -372,8 +372,8 @@ function serializeRemoteFrame(frame, deviceId, frameKind, options = {}) {
         framePath,
         frameUrl: framePath
     };
-    if (options.includeDataUrl !== false) {
-        serialized.dataUrl = dataUrl;
+    if (options.includeDataUrl === true) {
+        serialized.dataUrl = dataUrl || buildFrameDataUrl(payload, '', publicFrame.mimeType || publicFrame.format || 'image/jpeg');
     }
 
     return serialized;
@@ -1114,7 +1114,7 @@ export function createRemoteHub(options = {}) {
 
     function listDevices(options = {}) {
         const serializeOptions = {
-            includeDataUrl: options.includeDataUrl !== false
+            includeDataUrl: options.includeDataUrl === true
         };
         return [...devices.values()]
             .map(device => serializeDevice(device, serializeOptions))
@@ -1969,7 +1969,6 @@ export function createRemoteHub(options = {}) {
             contentHash,
             captureMs: readFrameCaptureMs(message),
             sameContentStreak,
-            dataUrl: buildFrameDataUrl(framePayload, frameData, mimeType),
             payload,
             accessToken: createFrameAccessToken()
         };
@@ -2040,7 +2039,6 @@ export function createRemoteHub(options = {}) {
             contentHash,
             captureMs: readFrameCaptureMs(message),
             sameContentStreak,
-            dataUrl: buildFrameDataUrl(framePayload, frameData, mimeType),
             payload,
             accessToken: createFrameAccessToken()
         };
@@ -2961,14 +2959,14 @@ export function createRemoteHub(options = {}) {
     function getDeviceLiveFrame(deviceId, options = {}) {
         const device = devices.get(String(deviceId || ''));
         return serializeRemoteFrame(device?.latestLiveFrame, device?.deviceId, 'live', {
-            includeDataUrl: options.includeDataUrl !== false
+            includeDataUrl: options.includeDataUrl === true
         });
     }
 
     function getDeviceThumbnail(deviceId, options = {}) {
         const device = devices.get(String(deviceId || ''));
         return serializeRemoteFrame(device?.latestThumbnail, device?.deviceId, 'thumbnail', {
-            includeDataUrl: options.includeDataUrl !== false
+            includeDataUrl: options.includeDataUrl === true
         });
     }
 

package/scripts/remote-http-smoke.mjs

@@ -373,10 +373,16 @@ async function runSyntheticEnabledSmoke() {
     });
     assert.equal(thumbnail.ok, true, JSON.stringify(thumbnail.payload));
     assert.equal(thumbnail.payload?.thumbnail?.streamId, 'http-smoke-thumb');
-    assert.ok(String(thumbnail.payload?.thumbnail?.dataUrl || '').startsWith('data:image/png;base64,'));
+    assert.ok(!('dataUrl' in thumbnail.payload.thumbnail));
     assert.ok(String(thumbnail.payload?.thumbnail?.framePath || '').includes(`/api/remote/devices/${encodeURIComponent(thumbnailTarget.deviceId)}/thumbnail?`));
     assert.equal(thumbnail.payload?.thumbnail?.frameUrl, thumbnail.payload?.thumbnail?.framePath);
 
+    const thumbnailWithData = await fetchJson(`${baseUrl}/api/remote/devices/${encodeURIComponent(thumbnailTarget.deviceId)}/thumbnail?includeDataUrl=true`, {
+        token: BRIDGE_TOKEN
+    });
+    assert.equal(thumbnailWithData.ok, true, JSON.stringify(thumbnailWithData.payload));
+    assert.ok(String(thumbnailWithData.payload?.thumbnail?.dataUrl || '').startsWith('data:image/png;base64,'));
+
     const thumbnailBinary = await fetchBinary(`${baseUrl}${thumbnail.payload.thumbnail.framePath}`);
     assert.equal(thumbnailBinary.ok, true, `${thumbnailBinary.status} ${thumbnailBinary.contentType}`);
     assert.equal(thumbnailBinary.contentType, 'image/png');
@@ -433,9 +439,15 @@ async function runSyntheticEnabledSmoke() {
     assert.equal(liveFrame.payload?.frame?.streamId, 'http-smoke-live');
     assert.equal(liveFrame.payload?.frame?.mode, 'remote-fast');
     assert.equal(liveFrame.payload?.frame?.fps, 20);
-    assert.ok(String(liveFrame.payload?.frame?.dataUrl || '').startsWith('data:image/png;base64,'));
+    assert.ok(!('dataUrl' in liveFrame.payload.frame));
     assert.ok(String(liveFrame.payload?.frame?.framePath || '').includes(`/api/remote/devices/${encodeURIComponent(liveTarget.deviceId)}/live/frame?`));
 
+    const liveFrameWithData = await fetchJson(`${baseUrl}/api/remote/devices/${encodeURIComponent(liveTarget.deviceId)}/live/frame?includeDataUrl=true`, {
+        token: BRIDGE_TOKEN
+    });
+    assert.equal(liveFrameWithData.ok, true, JSON.stringify(liveFrameWithData.payload));
+    assert.ok(String(liveFrameWithData.payload?.frame?.dataUrl || '').startsWith('data:image/png;base64,'));
+
     const liveBinary = await fetchBinary(`${baseUrl}${liveFrame.payload.frame.framePath}`);
     assert.equal(liveBinary.ok, true, `${liveBinary.status} ${liveBinary.contentType}`);
     assert.equal(liveBinary.contentType, 'image/png');

package/scripts/remote-hub-scale-smoke.mjs

@@ -37,9 +37,12 @@ try {
     assert.equal(devices.length, SYNTHETIC_COUNT);
     assert.equal(devices.filter(device => device.synthetic === true).length, SYNTHETIC_COUNT);
     assert.equal(devices.some(device => device.connected === false), true);
-    assert.equal(devices.some(device => device.latestThumbnail?.dataUrl), true);
+    assert.equal(devices.some(device => device.latestThumbnail && 'dataUrl' in device.latestThumbnail), false);
     assert.equal(devices.some(device => device.activeLiveStream?.active === true), true);
 
+    const devicesWithDataUrl = hub.listDevices({ includeDataUrl: true });
+    assert.equal(devicesWithDataUrl.some(device => device.latestThumbnail?.dataUrl), true);
+
     const deviceListPayload = {
         total: devices.length,
         pagination: 'none',
@@ -58,6 +61,8 @@ try {
     });
     assert.equal(thumbnailResult.ok, true);
     assert.equal(hub.getDeviceThumbnail(thumbnailTarget.deviceId).streamId, 'scale-thumb');
+    assert.equal('dataUrl' in hub.getDeviceThumbnail(thumbnailTarget.deviceId), false);
+    assert.ok(hub.getDeviceThumbnail(thumbnailTarget.deviceId, { includeDataUrl: true }).dataUrl);
 
     const liveTarget = devices.find(device => device.connected && device.capabilities?.liveStream);
     assert.ok(liveTarget);

package/server.js

@@ -8,9 +8,9 @@
 
 import express from 'express';
 import cors from 'cors';
-import { promises as fs, readFileSync, statSync, createReadStream } from 'fs';
+import { promises as fs, readFileSync, statSync, createReadStream, chmodSync } from 'fs';
 import path from 'path';
-import { exec, spawn, execFile } from 'child_process';
+import { exec, spawn, spawnSync, execFile } from 'child_process';
 import { promisify } from 'util';
 import os from 'os';
 import multer from 'multer';
@@ -2907,10 +2907,14 @@ 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;
+const REMOTE_AGENT_RACE_START_STAGGER_MS = 120;
+const REMOTE_AGENT_MAX_PARALLEL_CANDIDATES = 6;
 let remoteAgentState = createRemoteAgentIdleState();
 let remoteAgentSyncReportState = null;
 let remoteAgentSyncReportLogKey = '';
 let remoteAgentSyncReportLogAt = 0;
+let remoteAgentConnectPromise = null;
+const remoteAgentRecentSuccessfulManagers = new Map();
 
 function createRemoteAgentIdleState(overrides = {}) {
     return {
@@ -3211,6 +3215,46 @@ function createRemoteAgentConnectionKey(manager, leaseId) {
         .slice(0, 24);
 }
 
+function getRemoteAgentRecentManagerKey(leaseId = '') {
+    return safeRemoteAgentField(leaseId || 'default', 128) || 'default';
+}
+
+function rememberRemoteAgentSuccessfulManager(manager, leaseId = '') {
+    const endpoint = normalizeRemoteManagerEndpoint(manager);
+    if (!endpoint) {
+        return;
+    }
+
+    remoteAgentRecentSuccessfulManagers.set(getRemoteAgentRecentManagerKey(leaseId), {
+        endpoint,
+        updatedAt: Date.now()
+    });
+}
+
+function prioritizeRemoteAgentManagers(managers, leaseId = '') {
+    const normalized = normalizeRemoteManagerEndpointList(managers);
+    if (normalized.length <= 1) {
+        return normalized;
+    }
+
+    const recent = remoteAgentRecentSuccessfulManagers.get(getRemoteAgentRecentManagerKey(leaseId));
+    const recentEndpoint = normalizeRemoteManagerEndpoint(recent?.endpoint);
+    if (!recentEndpoint) {
+        return normalized;
+    }
+
+    const recentIndex = normalized.findIndex(item => item.toLowerCase() === recentEndpoint.toLowerCase());
+    if (recentIndex <= 0) {
+        return normalized;
+    }
+
+    return [
+        normalized[recentIndex],
+        ...normalized.slice(0, recentIndex),
+        ...normalized.slice(recentIndex + 1)
+    ];
+}
+
 function isRemoteAgentProcessRunning() {
     const proc = remoteAgentState.proc;
     return remoteAgentState.status === 'running'
@@ -3225,19 +3269,183 @@ function isLocalRemoteHostTargetActive() {
         && (!status.hostTargetHostInstanceId || status.hostTargetHostInstanceId === BRIDGE_INSTANCE_ID);
 }
 
-function resolveRemoteAgentLauncher() {
-    const localLauncher = path.join(BRIDGE_ROOT, 'node_modules', '@mindexec', 'remote', 'bin', 'mindexec-remote.js');
-    try {
-        if (statSync(localLauncher).isFile()) {
+function getRemoteFastRuntimeId() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === 'win32' && arch === 'x64') {
+        return 'win-x64';
+    }
+    if (platform === 'darwin' && arch === 'arm64') {
+        return 'osx-arm64';
+    }
+    if (platform === 'darwin' && arch === 'x64') {
+        return 'osx-x64';
+    }
+    return '';
+}
+
+function getRemoteFastRuntimeExecutableName() {
+    return process.platform === 'win32'
+        ? 'mindexec-remote-fast.exe'
+        : 'mindexec-remote-fast';
+}
+
+function getBundledRemoteFastRuntimeDirs() {
+    const rid = getRemoteFastRuntimeId();
+    if (!rid) {
+        return [];
+    }
+
+    return [
+        path.join(BRIDGE_ROOT, 'remote-fast', rid),
+        path.join(BRIDGE_ROOT, 'remote', 'fast', rid),
+        path.join(BRIDGE_ROOT, 'node_modules', '@mindexec', 'remote', 'fast', rid),
+        path.resolve(BRIDGE_ROOT, '..', 'remote', 'fast', rid),
+        path.resolve(BRIDGE_ROOT, '..', 'RemoteAgent', 'fast', rid)
+    ];
+}
+
+function resolveRemoteFastLauncher() {
+    const rid = getRemoteFastRuntimeId();
+    if (!rid) {
+        return {
+            ok: false,
+            error: `remote-fast-not-packaged:${process.platform}-${process.arch}`
+        };
+    }
+
+    const failures = [];
+    const seen = new Set();
+    for (const dir of getBundledRemoteFastRuntimeDirs()) {
+        const resolvedDir = path.resolve(dir);
+        const key = resolvedDir.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+
+        const executable = path.join(resolvedDir, getRemoteFastRuntimeExecutableName());
+        try {
+            if (statSync(executable).isFile()) {
+                if (process.platform !== 'win32') {
+                    try {
+                        const currentMode = statSync(executable).mode;
+                        chmodSync(executable, currentMode | 0o755);
+                    } catch {
+                        // best effort only
+                    }
+                }
+
+                const preflight = spawnSync(executable, ['--version'], {
+                    encoding: 'utf8',
+                    windowsHide: true,
+                    timeout: 2500
+                });
+                if (preflight.status === 0) {
+                    return {
+                        ok: true,
+                        command: executable,
+                        argsPrefix: [],
+                        launcher: executable,
+                        usingNpx: false,
+                        directFast: true,
+                        rid
+                    };
+                }
+                failures.push(`${executable}:exit:${preflight.status}`);
+            }
+        } catch {
+            // Try DLL or next directory.
+        }
+
+        const dll = path.join(resolvedDir, 'mindexec-remote-fast.dll');
+        try {
+            if (statSync(dll).isFile()) {
+                const preflight = spawnSync('dotnet', [dll, '--version'], {
+                    encoding: 'utf8',
+                    windowsHide: true,
+                    timeout: 2500
+                });
+                if (preflight.status === 0) {
+                    return {
+                        ok: true,
+                        command: 'dotnet',
+                        argsPrefix: [dll],
+                        launcher: dll,
+                        usingNpx: false,
+                        directFast: true,
+                        rid
+                    };
+                }
+                failures.push(`${dll}:exit:${preflight.status}`);
+            }
+        } catch {
+            // Try next directory.
+        }
+    }
+
+    return {
+        ok: false,
+        error: failures.length > 0
+            ? failures.join('; ')
+            : `remote-fast-runtime-missing:${rid}`
+    };
+}
+
+function resolveLocalRemotePackageLaunchers() {
+    return [
+        path.join(BRIDGE_ROOT, 'remote', 'bin', 'mindexec-remote.js'),
+        path.join(BRIDGE_ROOT, 'node_modules', '@mindexec', 'remote', 'bin', 'mindexec-remote.js'),
+        path.resolve(BRIDGE_ROOT, '..', 'remote', 'bin', 'mindexec-remote.js'),
+        path.resolve(BRIDGE_ROOT, '..', 'RemoteAgent', 'bin', 'mindexec-remote.js')
+    ];
+}
+
+function resolveRemotePackageLauncher() {
+    const seen = new Set();
+    for (const candidate of resolveLocalRemotePackageLaunchers()) {
+        const resolved = path.resolve(candidate);
+        const key = resolved.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        try {
+            if (statSync(resolved).isFile()) {
+                return {
+                    command: process.execPath,
+                    argsPrefix: [resolved],
+                    launcher: resolved,
+                    usingNpx: false,
+                    directFast: false
+                };
+            }
+        } catch {
+            // Try next package layout.
+        }
+    }
+    return null;
+}
+
+function resolveRemoteAgentLauncher(engine = REMOTE_AGENT_DEFAULT_ENGINE) {
+    const normalizedEngine = normalizeRemoteAgentEngine(engine);
+    if (normalizedEngine !== 'node') {
+        const fast = resolveRemoteFastLauncher();
+        if (fast.ok) {
+            return fast;
+        }
+
+        if (normalizedEngine === 'fast') {
             return {
-                command: process.execPath,
-                argsPrefix: [localLauncher],
-                launcher: localLauncher,
-                usingNpx: false
+                ok: false,
+                error: fast.error || 'remote-fast-unavailable'
             };
         }
-    } catch {
-        // Fall back to npx for source checkouts or older package installs.
+    }
+
+    const localPackage = resolveRemotePackageLauncher();
+    if (localPackage) {
+        return localPackage;
     }
 
     const npxCli = resolveNpxCliLauncher();
@@ -3246,7 +3454,8 @@ function resolveRemoteAgentLauncher() {
             command: process.execPath,
             argsPrefix: [npxCli, '-y', '@mindexec/remote@latest'],
             launcher: npxCli,
-            usingNpx: true
+            usingNpx: true,
+            directFast: false
         };
     }
 
@@ -3255,7 +3464,8 @@ function resolveRemoteAgentLauncher() {
             command: process.env.ComSpec || 'cmd.exe',
             argsPrefix: ['/d', '/s', '/c', 'npx.cmd', '-y', '@mindexec/remote@latest'],
             launcher: 'cmd.exe /c npx.cmd',
-            usingNpx: true
+            usingNpx: true,
+            directFast: false
         };
     }
 
@@ -3263,7 +3473,8 @@ function resolveRemoteAgentLauncher() {
         command: 'npx',
         argsPrefix: ['-y', '@mindexec/remote@latest'],
         launcher: 'npx',
-        usingNpx: true
+        usingNpx: true,
+        directFast: false
     };
 }
 
@@ -3343,11 +3554,11 @@ async function startRemoteAgentConnection(options = {}) {
     const nodeId = safeRemoteAgentField(options.nodeId, 128);
     const source = safeRemoteAgentField(options.source || 'registry', 64);
     const engine = normalizeRemoteAgentEngine(options.engine);
-    const managers = normalizeRemoteManagerEndpointList(
+    const managers = prioritizeRemoteAgentManagers(normalizeRemoteManagerEndpointList(
         options.manager || options.managerEndpoint || options.endpoint,
         options.managerCandidates,
         options.endpointCandidates,
-        options.candidates);
+        options.candidates), leaseId);
 
     if (managers.length === 0) {
         logWarn('remote', 'managed RemoteAgent connect rejected: invalid manager endpoint');
@@ -3385,45 +3596,321 @@ async function startRemoteAgentConnection(options = {}) {
         await stopRemoteAgentConnection('replaced-by-new-target');
     }
 
-    let lastResult = null;
+    if (remoteAgentConnectPromise) {
+        return await remoteAgentConnectPromise;
+    }
+
+    remoteAgentConnectPromise = startRemoteAgentConnectionRace({
+        managers,
+        pairToken,
+        leaseId,
+        nodeId,
+        source,
+        engine
+    }).finally(() => {
+        remoteAgentConnectPromise = null;
+    });
+    return await remoteAgentConnectPromise;
+}
+
+function buildRemoteAgentLaunchArgs(launcher, manager, pairToken, engine) {
+    const args = [
+        ...launcher.argsPrefix,
+        'connect',
+        '--manager',
+        manager,
+        '--pair',
+        pairToken
+    ];
+
+    if (launcher.directFast === true) {
+        args.push('--transport', 'ws');
+        return args;
+    }
+
+    args.push('--engine', engine);
+    return args;
+}
+
+function appendRemoteAgentAttemptOutput(attempt, stream, chunk) {
+    const text = chunk.toString();
+    const key = stream === 'stderr' ? 'stderrTail' : 'stdoutTail';
+    attempt.state[key] = String((attempt.state[key] || '') + text).slice(-REMOTE_AGENT_STDIO_TAIL_CHARS);
+    if (/Connected to RemoteHub/i.test(text)) {
+        attempt.state.ready = true;
+        attempt.state.connectedAt = new Date().toISOString();
+    }
+    attempt.state.updatedAt = new Date().toISOString();
+}
+
+function summarizeRemoteAgentAttempt(attempt) {
+    return formatRemoteAgentFailureSummary(attempt?.state || {});
+}
+
+function createRemoteAgentAttempt(options = {}) {
+    const manager = normalizeRemoteManagerEndpoint(options.manager);
+    const pairToken = safeRemoteAgentField(options.pairToken || options.pair, 512);
+    const leaseId = safeRemoteAgentField(options.leaseId, 128);
+    const nodeId = safeRemoteAgentField(options.nodeId, 128);
+    const source = safeRemoteAgentField(options.source || 'registry', 64);
+    const engine = normalizeRemoteAgentEngine(options.engine);
+    const managerCandidates = normalizeRemoteManagerEndpointList(options.managerCandidates, manager);
+
+    const connectionKey = createRemoteAgentConnectionKey(manager, leaseId);
+    const launcher = options.launcher || resolveRemoteAgentLauncher(engine);
+    if (launcher?.ok === false) {
+        return {
+            manager,
+            failed: true,
+            error: launcher.error || 'remote-agent-launcher-unavailable',
+            state: createRemoteAgentIdleState({
+                status: 'failed',
+                manager,
+                managerCandidates,
+                leaseId,
+                nodeId,
+                engine,
+                source,
+                connectionKey,
+                lastError: launcher.error || 'remote-agent-launcher-unavailable'
+            })
+        };
+    }
+
+    const state = createRemoteAgentIdleState({
+        status: 'starting',
+        manager,
+        managerCandidates,
+        leaseId,
+        nodeId,
+        engine,
+        source,
+        connectionKey,
+        startedAt: new Date().toISOString(),
+        ready: false,
+        connectedAt: '',
+        launcher: launcher.launcher,
+        usingNpx: launcher.usingNpx
+    });
+
+    const args = buildRemoteAgentLaunchArgs(launcher, manager, pairToken, engine);
+    const attempt = {
+        manager,
+        pairToken,
+        leaseId,
+        nodeId,
+        source,
+        engine,
+        launcher,
+        args,
+        state,
+        child: null,
+        failed: false,
+        error: ''
+    };
+
+    try {
+        const child = spawn(launcher.command, args, {
+            cwd: BRIDGE_ROOT,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            env: {
+                ...process.env,
+                MINDEXEC_REMOTE_AGENT_MANAGED: '1'
+            }
+        });
+
+        attempt.child = child;
+        state.proc = child;
+        state.pid = Number(child.pid || 0);
+        state.status = 'running';
+        state.updatedAt = new Date().toISOString();
+
+        child.stdout.on('data', chunk => appendRemoteAgentAttemptOutput(attempt, 'stdout', chunk));
+        child.stderr.on('data', chunk => appendRemoteAgentAttemptOutput(attempt, 'stderr', chunk));
+        child.once('error', err => {
+            attempt.failed = true;
+            attempt.error = err?.message || String(err);
+            state.status = 'failed';
+            state.lastError = attempt.error;
+            state.updatedAt = new Date().toISOString();
+        });
+        child.once('exit', (code, signal) => {
+            if (state.status === 'running' && state.ready === true) {
+                state.status = code === 0 ? 'exited' : 'failed';
+            } else {
+                attempt.failed = true;
+                state.status = code === 0 ? 'exited' : 'failed';
+            }
+            state.exitCode = Number.isFinite(code) ? code : null;
+            state.signal = signal || '';
+            state.exitedAt = new Date().toISOString();
+            state.updatedAt = state.exitedAt;
+            if (code !== 0 && !state.lastError) {
+                state.lastError = signal ? `signal:${signal}` : `exit:${code}`;
+            }
+            attempt.error = attempt.error || state.lastError || `exit:${code ?? 'unknown'}`;
+        });
+    } catch (err) {
+        attempt.failed = true;
+        attempt.error = err?.message || String(err);
+        state.status = 'failed';
+        state.lastError = attempt.error;
+        state.updatedAt = new Date().toISOString();
+    }
+
+    return attempt;
+}
+
+async function stopRemoteAgentAttempt(attempt, reason = 'race-lost') {
+    if (!attempt?.child) {
+        return;
+    }
+
+    if (attempt.child.exitCode !== null || attempt.child.killed) {
+        return;
+    }
+
+    try {
+        await terminateProcessTree(attempt.child);
+    } catch (err) {
+        logWarn('remote', `managed RemoteAgent cleanup failed ${formatKeyValue('manager', attempt.manager || '-')} ${formatKeyValue('reason', reason)} ${formatKeyValue('error', err?.message || err)}`);
+    }
+}
+
+async function startRemoteAgentConnectionRace(options = {}) {
+    const managers = normalizeRemoteManagerEndpointList(options.managers).slice(0, REMOTE_AGENT_MAX_PARALLEL_CANDIDATES);
+    const pairToken = safeRemoteAgentField(options.pairToken || options.pair, 512);
+    const leaseId = safeRemoteAgentField(options.leaseId, 128);
+    const nodeId = safeRemoteAgentField(options.nodeId, 128);
+    const source = safeRemoteAgentField(options.source || 'registry', 64);
+    const engine = normalizeRemoteAgentEngine(options.engine);
+    const launcher = resolveRemoteAgentLauncher(engine);
+    if (launcher?.ok === false) {
+        const error = launcher.error || 'remote-agent-launcher-unavailable';
+        remoteAgentState = createRemoteAgentIdleState({
+            status: 'failed',
+            manager: managers[0] || '',
+            managerCandidates: managers,
+            leaseId,
+            nodeId,
+            engine,
+            source,
+            lastError: error,
+            updatedAt: new Date().toISOString()
+        });
+        emitBridgeEvent('RemoteAgentFailed', serializeRemoteAgentState());
+        return { ok: false, error, agent: serializeRemoteAgentState() };
+    }
+
+    remoteAgentState = createRemoteAgentIdleState({
+        status: 'starting',
+        manager: managers[0] || '',
+        managerCandidates: managers,
+        leaseId,
+        nodeId,
+        engine,
+        source,
+        startedAt: new Date().toISOString(),
+        launcher: 'race',
+        usingNpx: false
+    });
+
+    const attempts = [];
     for (let index = 0; index < managers.length; index += 1) {
         const manager = managers[index];
-        if (managers.length > 1) {
-            logEvent(
-                'remote',
-                `managed RemoteAgent candidate ${index + 1}/${managers.length} ${formatKeyValue('manager', manager)}`,
-                'remote');
-        }
+        logEvent(
+            'remote',
+            `managed RemoteAgent race ${index + 1}/${managers.length} ${formatKeyValue('manager', manager)}`,
+            'remote');
 
-        const result = await startRemoteAgentConnectionAttempt({
+        const attempt = createRemoteAgentAttempt({
             manager,
             managerCandidates: managers,
             pairToken,
             leaseId,
             nodeId,
             source,
-            engine
+            engine,
+            launcher
         });
-        if (result?.ok === true) {
-            return result;
+        attempts.push(attempt);
+
+        if (index + 1 < managers.length && REMOTE_AGENT_RACE_START_STAGGER_MS > 0) {
+            await new Promise(resolve => setTimeout(resolve, REMOTE_AGENT_RACE_START_STAGGER_MS));
         }
+    }
 
-        lastResult = result;
-        if (isRemoteAgentProcessRunning()) {
-            await stopRemoteAgentConnection(`candidate-failed:${manager}`);
+    const startedAt = Date.now();
+    let winner = null;
+    while (Date.now() - startedAt < REMOTE_AGENT_READY_TIMEOUT_MS) {
+        winner = attempts.find(attempt =>
+            attempt?.state?.ready === true
+            && attempt?.child
+            && attempt.child.exitCode === null
+            && !attempt.child.killed);
+        if (winner) {
+            break;
         }
 
-        if (index + 1 < managers.length) {
-            logWarn(
-                'remote',
-                `managed RemoteAgent candidate failed; trying next ${formatKeyValue('manager', manager)} ${formatKeyValue('error', result?.error || 'unknown')}`);
+        const allFinished = attempts.every(attempt =>
+            attempt.failed === true
+            || !attempt.child
+            || attempt.child.exitCode !== null
+            || attempt.child.killed);
+        if (allFinished) {
+            break;
         }
+
+        await new Promise(resolve => setTimeout(resolve, 60));
     }
 
+    if (winner) {
+        for (const attempt of attempts) {
+            if (attempt !== winner) {
+                await stopRemoteAgentAttempt(attempt, 'race-lost');
+            }
+        }
+
+        remoteAgentState = winner.state;
+        remoteAgentState.status = 'running';
+        remoteAgentState.proc = winner.child;
+        remoteAgentState.updatedAt = new Date().toISOString();
+        rememberRemoteAgentSuccessfulManager(winner.manager, leaseId);
+        emitBridgeEvent('RemoteAgentStarted', serializeRemoteAgentState());
+        logEvent(
+            'remote',
+            `managed RemoteAgent connected ${formatKeyValue('manager', winner.manager)} ${formatKeyValue('launcher', winner.launcher?.launcher || '-')}`,
+            'remote');
+        return { ok: true, alreadyRunning: false, agent: serializeRemoteAgentState() };
+    }
+
+    const lastAttempt = attempts.findLast?.(attempt => attempt?.error || attempt?.state?.lastError)
+        || attempts[attempts.length - 1]
+        || null;
+    for (const attempt of attempts) {
+        await stopRemoteAgentAttempt(attempt, 'race-failed');
+    }
+
+    const error = lastAttempt
+        ? summarizeRemoteAgentAttempt(lastAttempt)
+        : 'all-manager-candidates-failed';
+    remoteAgentState = createRemoteAgentIdleState({
+        status: 'failed',
+        manager: managers[0] || '',
+        managerCandidates: managers,
+        leaseId,
+        nodeId,
+        engine,
+        source,
+        lastError: error,
+        updatedAt: new Date().toISOString()
+    });
+    emitBridgeEvent('RemoteAgentFailed', serializeRemoteAgentState());
     return {
         ok: false,
-        error: lastResult?.error || 'all-manager-candidates-failed',
-        agent: lastResult?.agent || serializeRemoteAgentState()
+        error,
+        agent: serializeRemoteAgentState()
     };
 }
 
@@ -3445,17 +3932,11 @@ async function startRemoteAgentConnectionAttempt(options = {}) {
     }
 
     const connectionKey = createRemoteAgentConnectionKey(manager, leaseId);
-    const launcher = resolveRemoteAgentLauncher();
-    const args = [
-        ...launcher.argsPrefix,
-        'connect',
-        '--manager',
-        manager,
-        '--pair',
-        pairToken,
-        '--engine',
-        engine
-    ];
+    const launcher = resolveRemoteAgentLauncher(engine);
+    if (launcher?.ok === false) {
+        return { ok: false, error: launcher.error || 'remote-agent-launcher-unavailable', agent: serializeRemoteAgentState() };
+    }
+    const args = buildRemoteAgentLaunchArgs(launcher, manager, pairToken, engine);
 
     remoteAgentState = createRemoteAgentIdleState({
         status: 'starting',
@@ -8065,7 +8546,7 @@ app.get('/api/remote/status', (req, res) => {
 
 app.get('/api/remote/devices', (req, res) => {
     res.setHeader('Cache-Control', 'no-store');
-    const includeDataUrl = !/^(0|false|no|url|metadata)$/i.test(String(req.query?.includeDataUrl ?? req.query?.frameData ?? ''));
+    const includeDataUrl = /^(1|true|yes|on|data|base64)$/i.test(String(req.query?.includeDataUrl ?? req.query?.frameData ?? ''));
     const devices = remoteHub.listDevices({ includeDataUrl });
     res.json({
         total: devices.length,
@@ -8285,7 +8766,7 @@ function isRemoteCapabilityEnabled(device, key) {
 }
 
 function includeRemoteFrameDataUrl(req) {
-    return !/^(0|false|no|url|metadata)$/i.test(String(req.query?.includeDataUrl ?? req.query?.frameData ?? ''));
+    return /^(1|true|yes|on|data|base64)$/i.test(String(req.query?.includeDataUrl ?? req.query?.frameData ?? ''));
 }
 
 function sendRemoteFrameBinary(req, res, frameKind) {

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

@@ -14103,6 +14103,7 @@
     function isRemoteFleetFrameSource(value) {
         const source = String(value || '').trim();
         if (/^data:image\/(png|jpe?g|webp|svg\+xml);base64,/i.test(source)
+            || /^blob:/i.test(source)
             || /^\/api\/remote\//i.test(source)) {
             return true;
         }
@@ -14374,7 +14375,18 @@
             return null;
         }
 
-        if (typeof fetch !== 'function' || typeof createImageBitmap !== 'function') {
+        if (typeof createImageBitmap !== 'function') {
+            return null;
+        }
+
+        const timeoutMs = getRemoteFleetFrameDecodeTimeoutMs(frame);
+        if (frame._remoteFleetPayloadBlob) {
+            return await withRemoteFleetFrameTimeout(
+                createImageBitmap(frame._remoteFleetPayloadBlob),
+                timeoutMs);
+        }
+
+        if (typeof fetch !== 'function') {
             return null;
         }
 
@@ -14412,7 +14424,6 @@
             entry.expiresAt = now + REMOTE_FLEET_FRAME_BLOB_CACHE_MS;
         }
 
-        const timeoutMs = getRemoteFleetFrameDecodeTimeoutMs(frame);
         const blob = await withRemoteFleetFrameTimeout(
             entry.promise,
             timeoutMs,
@@ -14431,7 +14442,7 @@
     }
 
     function cloneRemoteFleetFramePatch(frame) {
-        return {
+        const patch = {
             deviceId: String(frame?.deviceId || '').trim(),
             kind: String(frame?.kind || 'thumbnail').trim().toLowerCase(),
             frameSeq: Number.isFinite(Number(frame?.frameSeq)) ? Math.floor(Number(frame.frameSeq)) : 0,
@@ -14443,6 +14454,16 @@
             captureMs: Number(frame?.captureMs || 0) || 0,
             sameContentStreak: Number(frame?.sameContentStreak || 0) || 0
         };
+        if (frame?._remoteFleetPayloadBlob) {
+            patch._remoteFleetPayloadBlob = frame._remoteFleetPayloadBlob;
+        }
+        if (frame?._remoteFleetObjectUrl) {
+            patch._remoteFleetObjectUrl = frame._remoteFleetObjectUrl;
+        }
+        if (frame?._remoteFleetBinaryFrame === true) {
+            patch._remoteFleetBinaryFrame = true;
+        }
+        return patch;
     }
 
     function isRemoteFleetFrameNewerForPreview(preview, frame, comparePending = false) {
@@ -14543,23 +14564,7 @@
             placeholder.remove();
         }
 
-        const previewMode = String(preview?.dataset?.remoteFleetDevicePreview || '');
-        if (previewMode === 'tile') {
-            preview.querySelector?.('[data-remote-fleet-frame-badge="true"]')?.remove();
-            return true;
-        }
-
-        const badge = ensureRemoteFleetFrameBadge(preview, frame);
-        if (badge) {
-            const at = frame.receivedAt || frame.capturedAt || '';
-            badge.textContent = frame.kind === 'live'
-                ? `LIVE ${at ? formatRemoteFleetAge(at) : ''}`.trim()
-                : (at ? formatRemoteFleetAge(at) : 'Screen');
-            badge.style.display = 'inline-flex';
-            badge.style.background = frame.kind === 'live'
-                ? 'rgba(220, 38, 38, 0.84)'
-                : 'rgba(15, 23, 42, 0.72)';
-        }
+        preview.querySelector?.('[data-remote-fleet-frame-badge="true"]')?.remove();
 
         return true;
     }
@@ -14880,11 +14885,10 @@
 
     function applyRemoteFleetFramePatchToPreview(preview, frame) {
         if (String(frame?.kind || '').toLowerCase() === 'live') {
-            preview._remoteFleetPendingFrame = null;
-            delete preview.dataset.remoteFleetPendingFrameKind;
-            delete preview.dataset.remoteFleetPendingFrameSeq;
-            delete preview.dataset.remoteFleetPendingFrameUrl;
-            return queueRemoteFleetImageSwap(preview, frame);
+            preview._remoteFleetPendingImageFrame = null;
+            delete preview.dataset.remoteFleetPendingImageKind;
+            delete preview.dataset.remoteFleetPendingImageSeq;
+            delete preview.dataset.remoteFleetPendingImageUrl;
         }
 
         return queueRemoteFleetFramePaint(preview, frame);
@@ -14964,6 +14968,16 @@
                 return;
             }
 
+            const binarySession = bodyView._remoteFleetBinaryFrameSession;
+            const binarySocket = binarySession?.ws || null;
+            if (binarySocket
+                && typeof WebSocket !== 'undefined'
+                && (binarySocket.readyState === WebSocket.OPEN || binarySocket.readyState === WebSocket.CONNECTING)) {
+                lastTick = timestamp;
+                bodyView._remoteFleetFrameLoopRaf = requestRemoteFleetFrameLoopFrame(loop);
+                return;
+            }
+
             if (timestamp - lastTick >= intervalMs && bodyView._remoteFleetFrameRefreshInFlight !== true) {
                 lastTick = timestamp;
                 bodyView._remoteFleetFrameRefreshInFlight = true;
@@ -15993,29 +16007,6 @@
             `;
             preview.appendChild(placeholder);
         }
-        const previewBadge = document.createElement('span');
-        previewBadge.dataset.remoteFleetFrameBadge = 'true';
-        previewBadge.textContent = hasLiveFrame
-            ? `LIVE ${previewAt ? formatRemoteFleetAge(previewAt) : ''}`.trim()
-            : (previewAt ? formatRemoteFleetAge(previewAt) : (hubStatus === 'online' ? 'Pinned' : 'Hub offline'));
-        previewBadge.style.cssText = `
-            position: absolute;
-            left: 7px;
-            bottom: 7px;
-            max-width: calc(100% - 14px);
-            padding: 4px 7px;
-            border-radius: 999px;
-            background: ${hasLiveFrame ? 'rgba(220, 38, 38, 0.84)' : 'rgba(15, 23, 42, 0.74)'};
-            color: #e2e8f0;
-            font-size: 9px;
-            font-weight: 950;
-            line-height: 1;
-            overflow: hidden;
-            text-overflow: ellipsis;
-            white-space: nowrap;
-            letter-spacing: 0;
-        `;
-        preview.appendChild(previewBadge);
         bodyView.appendChild(preview);
 
         const stats = document.createElement('div');

package/wwwroot/_framework/blazor.boot.json

@@ -1,7 +1,7 @@
 {
   "mainAssemblyName": "MindExecution.Web",
   "resources": {
-    "hash": "sha256-Sm5LEcaIEbOQMLRdM7FmN29gN1AP1yTcQOVH+E/ZgGY=",
+    "hash": "sha256-o8W1U0lBmrbs5unXcwG+/IEh2KogSA7Rk3MqjQnNfGU=",
     "fingerprinting": {
       "Google.Protobuf.9h59ukbel7.dll": "Google.Protobuf.dll",
       "Markdig.d1j7v41cl1.dll": "Markdig.dll",
@@ -131,7 +131,7 @@
       "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.Shared.uwkrc41o75.dll": "MindExecution.Shared.dll",
       "MindExecution.Web.994sb3nzuy.dll": "MindExecution.Web.dll",
       "dotnet.js": "dotnet.js",
       "dotnet.native.qc8g39g30v.js": "dotnet.native.js",
@@ -282,7 +282,7 @@
       "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.Shared.uwkrc41o75.dll": "sha256-YjF+7VcGo3+nB0fsa2nh3AiaRyrHS1AL6d6Mq4RWKqo=",
       "MindExecution.Web.994sb3nzuy.dll": "sha256-jQshtLmhEC4xenzdD9PqHjaCuKvJf/frzaKBi2weDAg="
     },
     "lazyAssembly": {

package/wwwroot/index.html

@@ -7,8 +7,8 @@
     <title>MindExec | Run your ideas as AI task graphs</title>
     <meta name="description" content="MindExec is an AI execution canvas for solo builders, researchers, developers, and creators. Start with free browser tools, then move serious work into saved MindCanvas projects." />
     <base href="/" />
-    <link rel="stylesheet" href="_content/MindExecution.Shared/css/app.css?v=20260616-template-mdm-input-routing-v574" />
-    <link rel="stylesheet" href="_content/MindExecution.Shared/css/mind-map-overrides.css?v=20260616-template-mdm-input-routing-v574" />
+    <link rel="stylesheet" href="_content/MindExecution.Shared/css/app.css?v=20260616-mdm-ws-fast-v575" />
+    <link rel="stylesheet" href="_content/MindExecution.Shared/css/mind-map-overrides.css?v=20260616-mdm-ws-fast-v575" />
     <!-- ?쇄뼹??Font Awesome (local) ?쇄뼹??-->
     <link rel="stylesheet" href="_content/MindExecution.Shared/lib/font-awesome/css/all.min.css" />
     <!-- ?꿎뼯??-->
@@ -579,7 +579,7 @@
             }
 
             const base = '_content/MindExecution.Shared/js/';
-        const scriptVersion = '20260616-template-mdm-input-routing-v574';
+        const scriptVersion = '20260616-mdm-ws-fast-v575';
             const scriptUrl = (script) => `${base}${script}?v=${scriptVersion}`;
             console.log(`[Script Loader] Shared JS version: ${scriptVersion}`);
             const criticalScripts = [

package/wwwroot/service-worker-assets.js

@@ -1,5 +1,5 @@
 self.assetsManifest = {
-    "version":  "j2+Rgs1I",
+    "version":  "vnLn5hRl",
     "assets":  [
                    {
                        "hash":  "sha256-+CSYMcqLNTsq3VnH11jgYyOCCdxvHzL74CBmo4sCmMU=",
@@ -86,7 +86,7 @@
                        "url":  "_content/MindExecution.Shared/js/mind-map-core.js.backup"
                    },
                    {
-                       "hash":  "sha256-x6IqfFnk+HJevHd67L05oQLv68rKhUOs+PFwvnpYjp4=",
+                       "hash":  "sha256-eGHfAJwh8N3LmDZTr3/anW3CVrYCEYowGfK4N8KPzik=",
                        "url":  "_content/MindExecution.Shared/js/mind-map-css3d-manager.js"
                    },
                    {
@@ -442,8 +442,8 @@
                        "url":  "_framework/MindExecution.Plugins.YouTube.vy0nsbcoo4.dll"
                    },
                    {
-                       "hash":  "sha256-Au9QMwnm9MaP2+xzdldeQYtj4tRXzwOBWYOxmYR8spM=",
-                       "url":  "_framework/MindExecution.Shared.e8lipb57xv.dll"
+                       "hash":  "sha256-YjF+7VcGo3+nB0fsa2nh3AiaRyrHS1AL6d6Mq4RWKqo=",
+                       "url":  "_framework/MindExecution.Shared.uwkrc41o75.dll"
                    },
                    {
                        "hash":  "sha256-jQshtLmhEC4xenzdD9PqHjaCuKvJf/frzaKBi2weDAg=",
@@ -770,7 +770,7 @@
                        "url":  "_framework/Websocket.Client.vapounvmnl.dll"
                    },
                    {
-                       "hash":  "sha256-XSS0rv+S2JAW90BVDbFUd23REh87EAC1P5aFjXSMAGo=",
+                       "hash":  "sha256-lL/HCjpHZ3+EWJkTvNj72sH8NLl/eSU2UZDTr6bP99c=",
                        "url":  "_framework/blazor.boot.json"
                    },
                    {
@@ -834,7 +834,7 @@
                        "url":  "image-manifest.json"
                    },
                    {
-                       "hash":  "sha256-A1rOSgC5wEjKNEOppREqJ/PkL33qbguPos0pVcG6L/4=",
+                       "hash":  "sha256-IYebw41Eytj+5xl0lRltZ9R7wOwuHg0mlcgar2MiudE=",
                        "url":  "index.html"
                    },
                    {

package/wwwroot/service-worker.js

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