@livedesk/client 0.1.172 → 0.1.174

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,
@@ -2888,15 +2968,18 @@ async function startConnectionChoiceServer(supabase, options = {}) {
 
 async function chooseClientConnection(supabase, options = {}) {
     if (isTruthy(process.env.LIVEDESK_UNIFIED_RUNTIME)) {
-        const connectionPage = createClientRuntimeServer({
-            host: process.env.LIVEDESK_CLIENT_RUNTIME_HOST || '127.0.0.1',
-            port: options.authPort || DEFAULT_AUTH_CALLBACK_PORT,
-            webDist: process.env.LIVEDESK_WEB_DIST || '',
+        const connectionPage = createClientRuntimeServer({
+            host: process.env.LIVEDESK_CLIENT_RUNTIME_HOST || '127.0.0.1',
+            port: options.authPort || DEFAULT_AUTH_CALLBACK_PORT,
+            webDist: process.env.LIVEDESK_WEB_DIST || '',
             appVersion: process.env.LIVEDESK_NPM_LAUNCHER_VERSION || readPackageVersion(),
-            deviceId: options.deviceId,
-            engine: options.engine,
+            deviceId: options.deviceId,
+            engine: options.engine,
             savedSession: options.savedSession,
+            initialChoice: options.initialChoice,
+            initialChoiceMessage: options.initialChoiceMessage,
             beginGoogleSignIn: async redirectTo => {
+                if (!supabase?.auth) throw new Error('supabase-session-required');
                 const { data, error } = await supabase.auth.signInWithOAuth({
                     provider: 'google',
                     options: {
@@ -2910,15 +2993,26 @@ async function chooseClientConnection(supabase, options = {}) {
                 return { url: data.url };
             },
             exchangeGoogleCode: async code => {
+                if (!supabase?.auth) throw new Error('supabase-session-required');
                 const { data, error } = await supabase.auth.exchangeCodeForSession(code);
                 if (error) throw error;
                 if (!data?.session) throw new Error('google-session-missing');
                 if (!writeSavedSessionToFile(data.session)) throw new Error('refresh-token-required');
                 return data.session;
             },
-            resolvePin: pin => resolveManagerFromPin(supabase, pin),
-            changeRole: async (role, snapshot) => {
-                const session = await refreshSessionIfNeeded(supabase);
+            resolvePin: pin => {
+                if (!supabase) throw new Error('supabase-session-required');
+                return resolveManagerFromPin(supabase, pin);
+            },
+            changeRole: async (role, snapshot) => {
+                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' };
                 }
@@ -3255,7 +3349,7 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
     let connectionPage = null;
     let discoverySource = '';
 
-    if (shouldLogin) {
+    if (shouldLogin) {
         const supabase = await createSupabaseClient();
         const startupArgs = buildStartupClientArgs(parsed);
         let savedSession = null;
@@ -3362,10 +3456,38 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                 message: `Connected to LiveDesk Hub at ${manager}.`
             });
         }
-        console.log(`Found LiveDesk Hub at ${manager}.`);
-    }
-
-    const slot = normalizeSlotNumber(parsed.slot);
+        console.log(`Found LiveDesk Hub at ${manager}.`);
+    }
+    // Exact-package updates preserve the already paired Hub endpoint and pass
+    // --no-login so the replacement cannot block on browser auth. The unified
+    // launcher must still own its local runtime/status API; the package
+    // supervisor uses that API to prove the new launcher and Agent are stable
+    // before it commits the update.
+    if (!shouldLogin
+        && !existingConnectionPage
+        && isTruthy(process.env.LIVEDESK_UNIFIED_RUNTIME)
+        && manager
+        && pair) {
+        const preservedSession = readSavedSessionFromFile();
+        const explicitConnection = await chooseClientConnection(null, {
+            authPort: parsed.authPort,
+            deviceId: parsed.deviceId,
+            engine: parsed.engine,
+            savedSession: preservedSession,
+            openBrowser: false,
+            initialChoice: {
+                type: 'explicit',
+                manager,
+                pair,
+                endpointCandidates: [manager],
+                ...(preservedSession?.access_token ? { session: preservedSession } : {})
+            },
+            initialChoiceMessage: `Using the existing LiveDesk Hub pairing at ${manager}.`
+        });
+        connectionPage = explicitConnection.connectionPage || null;
+    }
+
+    const slot = normalizeSlotNumber(parsed.slot);
     if (manager) {
         forwarded = upsertForwardedOption(forwarded, '--manager', manager);
     }
@@ -3892,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);
@@ -3986,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.172",
+  "version": "0.1.174",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -39,10 +39,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.378",
-    "@livedesk/fast-osx-arm64": "0.1.378",
-    "@livedesk/fast-osx-x64": "0.1.378",
-    "@livedesk/fast-win-x64": "0.1.378"
+    "@livedesk/fast-linux-x64": "0.1.380",
+    "@livedesk/fast-osx-arm64": "0.1.380",
+    "@livedesk/fast-osx-x64": "0.1.380",
+    "@livedesk/fast-win-x64": "0.1.380"
   },
   "publishConfig": {
     "access": "public"

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

@@ -514,9 +514,16 @@ function sendText(res, status, body, type = 'text/plain; charset=utf-8') {
   res.end(body);
 }
 
-export function createClientRuntimeServer(options = {}) {
-  const host = normalizeString(options.host, 80) || DEFAULT_HOST;
+export function createClientRuntimeServer(options = {}) {
+  const host = normalizeString(options.host, 80) || DEFAULT_HOST;
   const port = normalizePort(options.port, DEFAULT_PORT);
+  const initialChoice = options.initialChoice && typeof options.initialChoice === 'object'
+    ? options.initialChoice
+    : null;
+  const initialChoiceMessage = normalizeString(
+    options.initialChoiceMessage,
+    1000
+  ) || 'Existing LiveDesk credentials accepted. Starting the Client.';
   const trustedWebOrigins = createTrustedWebOrigins(port);
   const webDist = resolve(String(options.webDist || process.env.LIVEDESK_WEB_DIST || '').trim() || join(process.cwd(), 'apps', 'web', 'dist'));
   const deviceId = normalizeString(options.deviceId || process.env.LIVEDESK_DEVICE_ID, 160);
@@ -732,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())),
@@ -1030,23 +1038,29 @@ export function createClientRuntimeServer(options = {}) {
         else res.end();
       });
     });
-    server.once('error', rejectStart);
-    server.listen(port, host, () => {
-      runtime.emit('runtime.http.started', { host, port });
-      const saved = normalizeRuntimeAuthSession(options.savedSession, { requireRefreshToken: true });
-      if (saved.ok) {
+    server.once('error', rejectStart);
+    server.listen(port, host, () => {
+      runtime.emit('runtime.http.started', { host, port });
+      if (initialChoice) {
         setImmediate(() => {
-          try {
-            if (!writeSavedSession(saved.session)) throw new Error('refresh-token-required');
-            state.auth.persisted = true;
-            complete({ type: 'google', session: saved.session }, 'Saved sign-in found. Finding the LiveDesk Hub.');
-          } catch (error) {
-            recordAuthAttempt('rejected', `session-persistence-failed:${normalizeString(error?.message || error, 160)}`);
-          }
+          complete(initialChoice, initialChoiceMessage);
         });
+      } else {
+        const saved = normalizeRuntimeAuthSession(options.savedSession, { requireRefreshToken: true });
+        if (saved.ok) {
+          setImmediate(() => {
+            try {
+              if (!writeSavedSession(saved.session)) throw new Error('refresh-token-required');
+              state.auth.persisted = true;
+              complete({ type: 'google', session: saved.session }, 'Saved sign-in found. Finding the LiveDesk Hub.');
+            } catch (error) {
+              recordAuthAttempt('rejected', `session-persistence-failed:${normalizeString(error?.message || error, 160)}`);
+            }
+          });
+        }
       }
-      resolveStart();
-    });
+      resolveStart();
+    });
   });
 
   return {