@livedesk/client 0.1.173 → 0.1.175

package/README.md

@@ -89,7 +89,7 @@ Frame pipeline roadmap:
 
 - Mode 1: `mode1-jpeg` - current test path using screen capture, resize, and JPEG binary frames.
 - Mode 2: `mode2-lzo` - cross-platform wall path using independent RGB565LE frames capped at 320x180 and compressed as LZO1X blocks. The wall defaults to 8 fps. macOS and Linux keep one persistent local capture helper per client process. Legacy `mode2-lz4` settings migrate to this mode.
-- Mode 3: `mode3-h264-hw` - OS-specific hardware H.264 path. Windows tries Media Foundation/NVENC/QSV/AMF, macOS prefers ScreenCaptureKit plus VideoToolbox, and Linux tries NVENC/VAAPI/QSV. macOS emits one startup key frame and then an approximately one-second GOP. The launcher uses bundled ffmpeg for fallback paths unless `LIVEDESK_FFMPEG` points to a custom binary. On macOS, set `LIVEDESK_FFMPEG_AVFOUNDATION_INPUT` only when the ScreenCaptureKit helper is unavailable and the AVFoundation fallback input is not `1:none`.
+- Mode 3: `mode3-h264-hw` - OS-specific H.264 path. Windows tries Media Foundation/NVENC/QSV/AMF, macOS prefers ScreenCaptureKit plus VideoToolbox, and Linux tries NVENC/VAAPI/QSV before falling back to the bundled ffmpeg `libx264` encoder. Linux users do not need to install ffmpeg separately when starting LiveDesk through the published npm package. macOS emits one startup key frame and then an approximately one-second GOP. The launcher uses bundled ffmpeg for fallback paths unless `LIVEDESK_FFMPEG` points to a custom binary. On macOS, set `LIVEDESK_FFMPEG_AVFOUNDATION_INPUT` only when the ScreenCaptureKit helper is unavailable and the AVFoundation fallback input is not `1:none`.
 
 Legacy mode names such as `remote-fast` and `remote-quality` are treated as
 Mode 1 aliases.

package/bin/livedesk-client.js

@@ -14,6 +14,7 @@ import { createClientRuntimeServer } from '../src/runtime/client-runtime-server.
 import { installAgentTerminationHandlers } from '../src/runtime/agent-process-lifecycle.js';
 import { createHubWakeListener } from '../src/runtime/hub-wake-listener.js';
 import { normalizeRuntimeAuthSession } from '../../runtime-core/src/auth-session.js';
+import { startRoleTransitionSupervisor } from '../../runtime-core/src/role-transition-supervisor.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -21,6 +22,7 @@ const packageRoot = resolve(__dirname, '..');
 const nodeAgentPath = join(__dirname, 'livedesk-client-node.js');
 const FAST_PREFLIGHT_TIMEOUT_MS = 5000;
 const DEFAULT_MANAGER = '127.0.0.1:5197';
+const DEFAULT_HUB_CLIENT_PORT = 5197;
 const DEFAULT_AUTH_CALLBACK_HOST = '127.0.0.1';
 const DEFAULT_AUTH_CALLBACK_PORT = 5179;
 const ENDPOINT_PROBE_TIMEOUT_MS = 900;
@@ -112,30 +114,53 @@ function writeLocalRoleCache(role, deviceId, roleVersion = 0, assignedHubId = ''
     return true;
 }
 
-function spawnUnifiedRoleRestart(role) {
-    if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) {
-        console.log(`[LiveDesk] Desktop supervisor will restart the runtime as ${role}.`);
-        return false;
-    }
-    const unifiedEntry = String(process.env.LIVEDESK_UNIFIED_LAUNCHER_ENTRY || '').trim();
-    const child = unifiedEntry && existsSync(unifiedEntry)
-        ? spawn(process.execPath, [unifiedEntry, '--force-role', role, '--no-open'], {
-            env: {
-                ...process.env,
-                LIVEDESK_ROLE_TRANSITION: '1',
-                LIVEDESK_RESTART_WAIT_PID: String(process.ppid),
-                LIVEDESK_SKIP_BROWSER_OPEN: '1'
-            },
-            detached: true,
-            stdio: 'ignore',
-            windowsHide: true
-        })
-        : process.platform === 'win32'
-            ? spawn('npx.cmd', ['-y', '--prefer-online', 'livedesk@latest', '--force-role', role, '--no-open'], { detached: true, stdio: 'ignore', windowsHide: true })
-            : spawn('npx', ['-y', '--prefer-online', 'livedesk@latest', '--force-role', role, '--no-open'], { detached: true, stdio: 'ignore' });
-    child.unref();
-    return true;
-}
+export function buildUnifiedRoleRestartEnvironment(role, baseEnv = process.env, runtimePid = process.pid) {
+    const normalizedRole = String(role || '').trim().toLowerCase();
+    const waitPid = Number(runtimePid);
+    if (normalizedRole !== 'hub' && normalizedRole !== 'client') {
+        throw new Error(`Unsupported LiveDesk role restart: ${role}`);
+    }
+    if (!Number.isInteger(waitPid) || waitPid <= 1) {
+        throw new Error(`Invalid LiveDesk runtime PID for role restart: ${runtimePid}`);
+    }
+    return {
+        ...baseEnv,
+        LIVEDESK_ROLE_TRANSITION: '1',
+        // The replacement must wait only for this Client runtime. Waiting for
+        // npm, npx, PowerShell, or another terminal parent can deadlock the
+        // takeover even after Supabase has selected this device as Hub.
+        LIVEDESK_RESTART_WAIT_PID: String(waitPid),
+        LIVEDESK_ROLE_TAKEOVER: normalizedRole === 'hub' ? '1' : '',
+        LIVEDESK_SKIP_BROWSER_OPEN: '1'
+    };
+}
+
+async function spawnUnifiedRoleRestart(role) {
+    if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) {
+        console.log(`[LiveDesk] Desktop supervisor will restart the runtime as ${role}.`);
+        return false;
+    }
+    const unifiedEntry = String(process.env.LIVEDESK_UNIFIED_LAUNCHER_ENTRY || '').trim();
+    const restartEnvironment = buildUnifiedRoleRestartEnvironment(role);
+    if (!unifiedEntry || !existsSync(unifiedEntry)) {
+        throw new Error(`LiveDesk unified role launcher is unavailable: ${unifiedEntry || 'missing path'}`);
+    }
+    const handoff = await startRoleTransitionSupervisor({
+        role,
+        previousPid: process.pid,
+        launcherEntry: unifiedEntry,
+        stateDir: UNIFIED_CLIENT_STATE_DIR,
+        runtimePort: Number(process.env.LIVEDESK_CLIENT_RUNTIME_PORT || DEFAULT_AUTH_CALLBACK_PORT),
+        remotePort: resolveHubClientPort(),
+        env: restartEnvironment,
+        cwd: process.cwd()
+    });
+    console.log(
+        `[LiveDesk] Role transition supervisor claimed target=${role} `
+        + `pid=${handoff.supervisorPid}. Diagnostics: ${handoff.logPath}`
+    );
+    return true;
+}
 
 function printHelp() {
     process.stdout.write(`
@@ -349,15 +374,64 @@ function parseLauncherArgs(argv) {
     };
 }
 
-function normalizePort(value) {
+function normalizePort(value) {
     const port = Number(String(value || '').trim());
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
         return 0;
     }
     return port;
-}
-
-function normalizeSlotNumber(value) {
+}
+
+export function resolveHubClientPort(env = process.env) {
+    return normalizePort(env.REMOTE_HUB_PORT || env.LIVEDESK_HUB_REMOTE_PORT) || DEFAULT_HUB_CLIENT_PORT;
+}
+
+export function preflightHubClientPort(port = resolveHubClientPort()) {
+    const normalizedPort = normalizePort(port);
+    if (!normalizedPort) {
+        return Promise.resolve({ ok: false, port: Number(port) || 0, code: 'invalid-hub-client-port' });
+    }
+    return new Promise(resolvePreflight => {
+        const probe = net.createServer();
+        let completed = false;
+        const finish = result => {
+            if (completed) return;
+            completed = true;
+            resolvePreflight({ port: normalizedPort, ...result });
+        };
+        probe.unref?.();
+        probe.once('error', error => {
+            finish({
+                ok: false,
+                code: error?.code === 'EADDRINUSE' ? 'hub-client-port-in-use' : 'hub-client-port-unavailable',
+                systemCode: String(error?.code || '')
+            });
+        });
+        probe.listen({ host: '0.0.0.0', port: normalizedPort, exclusive: true }, () => {
+            probe.close(error => {
+                if (error) {
+                    finish({ ok: false, code: 'hub-client-port-unavailable', systemCode: String(error?.code || '') });
+                    return;
+                }
+                finish({ ok: true, code: 'ok' });
+            });
+        });
+    });
+}
+
+function hubClientPortPreflightError(preflight) {
+    const port = Number(preflight?.port || resolveHubClientPort());
+    return {
+        ok: false,
+        code: String(preflight?.code || 'hub-client-port-unavailable'),
+        port,
+        error: preflight?.code === 'hub-client-port-in-use'
+            ? `LiveDesk cannot switch this computer to Hub because TCP ${port} is already in use. Change or stop the owning service, then try Switch to Hub again. The current Hub was not changed.`
+            : `LiveDesk cannot switch this computer to Hub because TCP ${port} is unavailable. Check the local port configuration, then try again. The current Hub was not changed.`
+    };
+}
+
+function normalizeSlotNumber(value) {
     const number = Number(String(value || '').trim());
     if (!Number.isInteger(number) || number < 1 || number > 999) {
         return '';
@@ -2628,12 +2702,18 @@ async function startConnectionChoiceServer(supabase, options = {}) {
                         payload = Object.fromEntries(params.entries());
                     }
                     const nextRole = String(payload.role || '').trim().toLowerCase();
-                    if (nextRole !== 'hub') {
+                    if (nextRole !== 'hub') {
                         res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8', 'Access-Control-Allow-Origin': '*' });
                         res.end(JSON.stringify({ ok: false, error: 'client-can-only-transition-to-hub' }));
-                        return;
-                    }
-                    const session = await refreshSessionIfNeeded(supabase);
+                        return;
+                    }
+                    const portPreflight = await preflightHubClientPort();
+                    if (!portPreflight.ok) {
+                        res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8', 'Access-Control-Allow-Origin': '*' });
+                        res.end(JSON.stringify(hubClientPortPreflightError(portPreflight)));
+                        return;
+                    }
+                    const session = await refreshSessionIfNeeded(supabase);
                     const expectedRoleVersion = Number(dashboardState.roleVersion || 0);
                     const { data, error } = await supabase.rpc('set_livedesk_device_role', {
                         p_device_id: deviceId,
@@ -2928,6 +3008,10 @@ async function chooseClientConnection(supabase, options = {}) {
                 if (!supabase) {
                     return { ok: false, error: 'supabase-session-required' };
                 }
+                const portPreflight = await preflightHubClientPort();
+                if (!portPreflight.ok) {
+                    return hubClientPortPreflightError(portPreflight);
+                }
                 const session = await refreshSessionIfNeeded(supabase);
                 if (!session?.access_token) {
                     return { ok: false, error: 'supabase-session-required' };
@@ -3688,7 +3772,7 @@ function buildFastEnvironment(prepared) {
         env.LIVEDESK_FFMPEG_PATHS = merged.join(separator);
     }
 
-    if (process.platform === 'darwin' || env.LIVEDESK_DEBUG_FFMPEG === '1') {
+    if (process.platform === 'darwin' || process.platform === 'linux' || env.LIVEDESK_DEBUG_FFMPEG === '1') {
         const describe = path => path.includes('ffmpeg-static')
             ? 'ffmpeg-static'
             : path.includes('@ffmpeg-installer')
@@ -3930,12 +4014,12 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
     while (true) {
         const prepared = await prepareLoginConnection(parsed, connectionPage);
         connectionPage = prepared.connectionPage || connectionPage;
-        const roleRestartBeforeAgent = connectionPage?.getRoleRestartRequest?.() || roleRestartRequest;
-        if (roleRestartBeforeAgent?.role) {
-            connectionPage?.close?.();
-            if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) process.exit(43);
-            spawnUnifiedRoleRestart(roleRestartBeforeAgent.role);
-            process.exit(0);
+        const roleRestartBeforeAgent = connectionPage?.getRoleRestartRequest?.() || roleRestartRequest;
+        if (roleRestartBeforeAgent?.role) {
+            if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) process.exit(43);
+            await spawnUnifiedRoleRestart(roleRestartBeforeAgent.role);
+            connectionPage?.close?.();
+            process.exit(0);
         }
         const fastRuntime = getFastRuntime();
         const useFast = shouldTryFast(prepared, fastRuntime);
@@ -4024,12 +4108,12 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
                 });
             });
         }
-        const requestedRoleRestart = connectionPage?.getRoleRestartRequest?.();
-        if (requestedRoleRestart?.role) {
-            connectionPage?.close?.();
-            if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) process.exit(43);
-            spawnUnifiedRoleRestart(requestedRoleRestart.role);
-            process.exit(0);
+        const requestedRoleRestart = connectionPage?.getRoleRestartRequest?.();
+        if (requestedRoleRestart?.role) {
+            if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) process.exit(43);
+            await spawnUnifiedRoleRestart(requestedRoleRestart.role);
+            connectionPage?.close?.();
+            process.exit(0);
         }
         if (result?.signal) {
             connectionPage?.close?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.173",
+  "version": "0.1.175",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -39,10 +39,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.379",
-    "@livedesk/fast-osx-arm64": "0.1.379",
-    "@livedesk/fast-osx-x64": "0.1.379",
-    "@livedesk/fast-win-x64": "0.1.379"
+    "@livedesk/fast-linux-x64": "0.1.381",
+    "@livedesk/fast-osx-arm64": "0.1.381",
+    "@livedesk/fast-osx-x64": "0.1.381",
+    "@livedesk/fast-win-x64": "0.1.381"
   },
   "publishConfig": {
     "access": "public"

package/src/runtime/client-runtime-server.js

@@ -739,6 +739,7 @@ export function createClientRuntimeServer(options = {}) {
         osVersion: os.release(),
         pid: process.pid,
         cpuUsagePercent: Math.round(cpuUsagePercent * 10) / 10,
+        cpuLogicalCores: Math.max(1, os.cpus().length),
         memoryTotalBytes: totalMemoryBytes,
         memoryUsedBytes: Math.max(0, totalMemoryBytes - freeMemoryBytes),
         uptimeSeconds: Math.max(0, Math.floor(os.uptime())),