livedesk 0.1.397 → 0.1.399

package/bin/livedesk.js

@@ -1146,6 +1146,7 @@ async function runManager(args, resolvedRole = null) {
     LIVEDESK_DEVICE_ID: String(resolvedRole?.deviceId || process.env.LIVEDESK_DEVICE_ID || ''),
     LIVEDESK_DEVICE_NAME: String(resolvedRole?.deviceName || process.env.LIVEDESK_DEVICE_NAME || os.hostname()),
     LIVEDESK_ROLE_CACHE_PATH: join(MANAGER_STATE_DIR, 'device-role.json'),
+    LIVEDESK_AUTH_STATE_PATH: join(MANAGER_STATE_DIR, 'auth.json'),
     LIVEDESK_ROLE_SOURCE: String(resolvedRole?.source || process.env.LIVEDESK_ROLE_SOURCE || '')
   };
   const debugConsole = process.env.LIVEDESK_DEBUG === '1';

package/bootstrap/legacy-client-update.js

@@ -243,8 +243,18 @@ function readConfig(env = process.env) {
       cleanVersion(env.LIVEDESK_CLIENT_UPDATE_CURRENT_PRODUCT_VERSION)
       || cleanVersion(env.LIVEDESK_NPM_LAUNCHER_VERSION),
     currentAgentVersion: cleanVersion(env.LIVEDESK_CLIENT_UPDATE_CURRENT_AGENT_VERSION),
-    launcherPid: positivePid(env.LIVEDESK_CLIENT_PARENT_PID),
-    agentPid: positivePid(env.LIVEDESK_CLIENT_UPDATE_AGENT_PID),
+    // Dedicated RemoteFast and Node Agent handoffs freeze the owned process
+    // tree under UPDATE_WAIT_PID / UPDATE_AGENT_PID. The Hub-owned bridge for
+    // older Agents uses the CLIENT_* aliases. Accept both contracts so the
+    // exact target package can always prove and stop the same old runtime.
+    launcherPid: positivePid(
+      env.LIVEDESK_UPDATE_WAIT_PID
+      || env.LIVEDESK_CLIENT_PARENT_PID
+    ),
+    agentPid: positivePid(
+      env.LIVEDESK_UPDATE_AGENT_PID
+      || env.LIVEDESK_CLIENT_UPDATE_AGENT_PID
+    ),
     starterPid: positivePid(env.LIVEDESK_UPDATE_STARTER_PID),
     updateDeadlineEpochMs: Number(env.LIVEDESK_CLIENT_UPDATE_DEADLINE_EPOCH_MS),
     runtimePort: normalizePort(env.LIVEDESK_CLIENT_RUNTIME_PORT || env.LIVEDESK_LOCAL_RUNTIME_PORT),
@@ -1528,15 +1538,20 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
   ));
 
   log(`started operation=${config.operationId || 'unknown'} target=${config.targetProductVersion}/${config.targetVersion} current=${config.currentProductVersion || 'unknown'} device=${config.deviceId}`);
-  if (!config.operationId
-    || !config.deviceId
-    || !config.targetProductVersion
-    || !config.targetVersion
-    || !config.currentProductVersion
-    || !config.currentAgentVersion
-    || config.launcherPid <= 1
-    || config.agentPid <= 1) {
-    throw new Error('legacy update configuration is incomplete');
+  const missingConfiguration = [
+    ['operationId', config.operationId],
+    ['deviceId', config.deviceId],
+    ['targetProductVersion', config.targetProductVersion],
+    ['targetVersion', config.targetVersion],
+    ['currentProductVersion', config.currentProductVersion],
+    ['currentAgentVersion', config.currentAgentVersion],
+    ['launcherPid', config.launcherPid > 1],
+    ['agentPid', config.agentPid > 1]
+  ].filter(([, value]) => !value).map(([name]) => name);
+  if (missingConfiguration.length > 0) {
+    throw new Error(
+      `legacy update configuration is incomplete: missing ${missingConfiguration.join(', ')}`
+    );
   }
   ensureDeadline('configuration validation');
   if (cleanVersion(productManifest.version) !== config.targetProductVersion) {

package/client/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);
@@ -134,27 +135,30 @@ export function buildUnifiedRoleRestartEnvironment(role, baseEnv = process.env,
     };
 }
 
-function spawnUnifiedRoleRestart(role) {
+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);
-    const spawnOptions = {
+    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,
-        detached: true,
-        stdio: 'ignore',
-        windowsHide: true
-    };
-    const child = unifiedEntry && existsSync(unifiedEntry)
-        ? spawn(process.execPath, [unifiedEntry, '--force-role', role, '--no-open'], {
-            ...spawnOptions
-        })
-        : process.platform === 'win32'
-            ? spawn('npx.cmd', ['-y', '--prefer-online', 'livedesk@latest', '--force-role', role, '--no-open'], spawnOptions)
-            : spawn('npx', ['-y', '--prefer-online', 'livedesk@latest', '--force-role', role, '--no-open'], spawnOptions);
-    child.unref();
+        cwd: process.cwd()
+    });
+    console.log(
+        `[LiveDesk] Role transition supervisor claimed target=${role} `
+        + `pid=${handoff.supervisorPid}. Diagnostics: ${handoff.logPath}`
+    );
     return true;
 }
 
@@ -4010,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);
@@ -4104,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/hub/src/server.js

@@ -3,7 +3,7 @@
 import express from 'express';
 import crypto from 'node:crypto';
 import { createServer } from 'node:http';
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import os from 'node:os';
@@ -106,6 +106,10 @@ const supabasePublishableKey = String(configuredSupabaseKey || PRODUCTION_SUPABA
 const SUPABASE_AUTH_TIMEOUT_MS = process.env.LIVEDESK_AUTH_TEST_MODE === '1'
   ? readPositiveIntegerEnv('LIVEDESK_AUTH_TEST_TIMEOUT_MS', AUTH_REQUEST_TIMEOUT_MS)
   : AUTH_REQUEST_TIMEOUT_MS;
+const CLIENT_AUTH_STORAGE_KEY = 'livedesk.client.supabase.auth';
+const runtimeAuthStatePath = process.env.LIVEDESK_DESKTOP_HOST === '1'
+  ? ''
+  : String(process.env.LIVEDESK_AUTH_STATE_PATH || '').trim();
 const testLicensePlan = process.env.LIVEDESK_TEST_MODE === '1'
   && ['ltd', 'pro'].includes(String(process.env.LIVEDESK_TEST_LICENSE_PLAN || '').toLowerCase())
   ? String(process.env.LIVEDESK_TEST_LICENSE_PLAN).toLowerCase()
@@ -306,11 +310,82 @@ function normalizeSessionExpiryMs(value) {
   return numeric < 100_000_000_000 ? Math.round(numeric * 1000) : Math.round(numeric);
 }
 
+function readRuntimeAuthState() {
+  if (!runtimeAuthStatePath) return {};
+  try {
+    const state = JSON.parse(readFileSync(runtimeAuthStatePath, 'utf8'));
+    return state && typeof state === 'object' ? state : {};
+  } catch {
+    return {};
+  }
+}
+
+function readPersistedRuntimeSession(state = readRuntimeAuthState()) {
+  try {
+    const raw = state?.[CLIENT_AUTH_STORAGE_KEY];
+    const session = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return session && typeof session === 'object' ? session : null;
+  } catch {
+    return null;
+  }
+}
+
+function writePrivateRuntimeAuthState(state) {
+  if (!runtimeAuthStatePath) return false;
+  mkdirSync(dirname(runtimeAuthStatePath), { recursive: true });
+  const temporaryPath = `${runtimeAuthStatePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    writeFileSync(temporaryPath, JSON.stringify(state, null, 2), 'utf8');
+    try { chmodSync(temporaryPath, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
+    renameSync(temporaryPath, runtimeAuthStatePath);
+    try { chmodSync(runtimeAuthStatePath, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
+    return true;
+  } catch (error) {
+    try { rmSync(temporaryPath, { force: true }); } catch { /* best effort */ }
+    throw error;
+  }
+}
+
+function persistRuntimeSession(session) {
+  if (!runtimeAuthStatePath) return false;
+  const state = readRuntimeAuthState();
+  const previous = readPersistedRuntimeSession(state) || {};
+  const incomingUserId = String(session?.user?.id || '').trim();
+  const previousUserId = String(previous?.user?.id || '').trim();
+  const sameUser = !incomingUserId || !previousUserId || incomingUserId === previousUserId;
+  const refreshToken = String(
+    session?.refresh_token
+    || (sameUser ? previous?.refresh_token : '')
+    || ''
+  ).trim();
+  const normalized = normalizeRuntimeAuthSession({
+    ...previous,
+    ...session,
+    refresh_token: refreshToken,
+    user: {
+      ...(sameUser && previous?.user && typeof previous.user === 'object' ? previous.user : {}),
+      ...(session?.user && typeof session.user === 'object' ? session.user : {})
+    }
+  }, { requireRefreshToken: true });
+  if (!normalized.ok) return false;
+  state[CLIENT_AUTH_STORAGE_KEY] = JSON.stringify(normalized.session);
+  writePrivateRuntimeAuthState(state);
+  return true;
+}
+
+function clearPersistedRuntimeSession() {
+  if (!runtimeAuthStatePath) return false;
+  const state = readRuntimeAuthState();
+  delete state[CLIENT_AUTH_STORAGE_KEY];
+  return writePrivateRuntimeAuthState(state);
+}
+
 function clearRuntimeSession() {
   runtimeAccessToken = '';
   runtimeRefreshToken = '';
   runtimeAccessTokenExpiresAt = 0;
   runtimeManager.setAuthenticated(false);
+  try { clearPersistedRuntimeSession(); } catch { /* runtime auth is already invalid */ }
 }
 
 async function getRuntimeAccessToken() {
@@ -356,6 +431,15 @@ async function getRuntimeAccessToken() {
   runtimeRefreshToken = String(refreshed?.refresh_token || refreshToken).trim();
   runtimeAccessTokenExpiresAt = normalizeSessionExpiryMs(refreshed?.expires_at)
     || (Number(refreshed?.expires_in) > 0 ? Date.now() + Number(refreshed.expires_in) * 1000 : 0);
+  try {
+    persistRuntimeSession({
+      access_token: runtimeAccessToken,
+      refresh_token: runtimeRefreshToken,
+      expires_at: Math.floor(runtimeAccessTokenExpiresAt / 1000)
+    });
+  } catch (error) {
+    console.warn(`[LiveDesk Hub] Refreshed session persistence failed: ${error?.message || error}`);
+  }
   return runtimeAccessToken;
 }
 
@@ -2913,13 +2997,19 @@ app.post('/api/auth/session', async (req, res) => {
     runtimeRefreshToken = refreshToken;
     runtimeAccessTokenExpiresAt = normalizeSessionExpiryMs(expiresAt);
     runtimeManager.setAuthenticated(true, user.id);
+    const persisted = persistRuntimeSession({
+      access_token: accessToken,
+      refresh_token: refreshToken,
+      expires_at: expiresAt,
+      user
+    });
     const hostTarget = runtimeRole === 'hub'
       ? await publishHubHostTargetWithPendingRoleTakeover('session-received')
       : { ok: true, active: false };
     if (runtimeRole === 'hub') {
       startHubHostTargetLeaseRenewal();
     }
-    res.json({ ok: true, authenticated: true, userId: user.id, role: runtimeRole, hostTarget });
+    res.json({ ok: true, authenticated: true, persisted, userId: user.id, role: runtimeRole, hostTarget });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const status = authVerificationHttpStatus(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livedesk",
-  "version": "0.1.397",
+  "version": "0.1.399",
   "livedeskClientVersion": "0.1.173",
   "buildFlavor": "production",
   "description": "LiveDesk Hub and client launcher",

package/runtime-core/src/role-transition-supervisor.js

@@ -0,0 +1,382 @@
+import { execFile, spawn } from 'node:child_process';
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
+import net from 'node:net';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROLE_TRANSITION_SUPERVISOR_FLAG = '--run-livedesk-role-transition-supervisor';
+const SUPERVISOR_CLAIM_TIMEOUT_MS = 5_000;
+const OLD_RUNTIME_EXIT_TIMEOUT_MS = 60_000;
+const REPLACEMENT_HEALTH_TIMEOUT_MS = 25_000;
+const REPLACEMENT_STABILITY_MS = 750;
+const POLL_MS = 100;
+
+function wait(milliseconds) {
+  return new Promise(resolveWait => setTimeout(resolveWait, milliseconds));
+}
+
+function normalizeRole(value) {
+  const role = String(value || '').trim().toLowerCase();
+  return role === 'hub' || role === 'client' ? role : '';
+}
+
+function positiveInteger(value, fallback = 0) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : fallback;
+}
+
+function processIsAlive(pid) {
+  const processId = positiveInteger(pid);
+  if (processId <= 1) return false;
+  try {
+    process.kill(processId, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonAtomic(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporaryPath, JSON.stringify(value, null, 2), 'utf8');
+    renameSync(temporaryPath, path);
+  } catch (error) {
+    try { rmSync(temporaryPath, { force: true }); } catch { /* best effort */ }
+    throw error;
+  }
+}
+
+function appendDiagnostic(path, message) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `[${new Date().toISOString()}] ${String(message || '')}\n`, 'utf8');
+}
+
+async function waitForProcessExit(pid, timeoutMs = OLD_RUNTIME_EXIT_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!processIsAlive(pid)) return true;
+    await wait(POLL_MS);
+  }
+  return !processIsAlive(pid);
+}
+
+async function probeRuntimeStatus(port, role, previousPid) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/runtime/status`, {
+      cache: 'no-store',
+      signal: AbortSignal.timeout(1_500)
+    });
+    if (!response.ok) return null;
+    const status = await response.json();
+    const runtimePid = positiveInteger(status?.runtimePid);
+    if (status?.role !== role || runtimePid <= 1 || runtimePid === previousPid) {
+      return null;
+    }
+    if (role === 'hub' && status?.runtimeStarted !== true) {
+      return null;
+    }
+    return { status, runtimePid };
+  } catch {
+    return null;
+  }
+}
+
+function probeTcp(port) {
+  return new Promise(resolveProbe => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    const finish = ok => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolveProbe(ok);
+    };
+    const timer = setTimeout(() => finish(false), 1_500);
+    timer.unref?.();
+    socket.once('connect', () => {
+      clearTimeout(timer);
+      finish(true);
+    });
+    socket.once('error', () => {
+      clearTimeout(timer);
+      finish(false);
+    });
+  });
+}
+
+async function verifyReplacement({ child, role, previousPid, runtimePort, remotePort }) {
+  const deadline = Date.now() + REPLACEMENT_HEALTH_TIMEOUT_MS;
+  let stableRuntimePid = 0;
+  let stableSince = 0;
+  while (Date.now() < deadline) {
+    if (!processIsAlive(child.pid)) {
+      throw new Error(`replacement-launcher-exited:${child.pid || 0}`);
+    }
+    const probe = await probeRuntimeStatus(runtimePort, role, previousPid);
+    const remoteReady = probe && (role !== 'hub' || await probeTcp(remotePort));
+    if (probe && remoteReady) {
+      if (stableRuntimePid !== probe.runtimePid) {
+        stableRuntimePid = probe.runtimePid;
+        stableSince = Date.now();
+      } else if (Date.now() - stableSince >= REPLACEMENT_STABILITY_MS) {
+        return { runtimePid: probe.runtimePid, appVersion: String(probe.status?.appVersion || '') };
+      }
+    } else {
+      stableRuntimePid = 0;
+      stableSince = 0;
+    }
+    await wait(POLL_MS);
+  }
+  throw new Error(`replacement-health-timeout:${role}`);
+}
+
+async function terminateOwnedProcessTree(pid) {
+  const processId = positiveInteger(pid);
+  if (processId <= 1 || !processIsAlive(processId)) return;
+  if (process.platform === 'win32') {
+    await new Promise(resolveKill => {
+      execFile(
+        'taskkill.exe',
+        ['/PID', String(processId), '/T', '/F'],
+        { windowsHide: true, timeout: 10_000 },
+        () => resolveKill()
+      );
+    });
+    return;
+  }
+  try { process.kill(-processId, 'SIGTERM'); } catch {
+    try { process.kill(processId, 'SIGTERM'); } catch { /* already stopped */ }
+  }
+}
+
+function supervisorSettings(env = process.env) {
+  const launcherEntry = String(env.LIVEDESK_ROLE_TRANSITION_LAUNCHER_ENTRY || '').trim();
+  const statePath = String(env.LIVEDESK_ROLE_TRANSITION_STATE_PATH || '').trim();
+  const logPath = String(env.LIVEDESK_ROLE_TRANSITION_LOG_PATH || '').trim();
+  return {
+    transitionId: String(env.LIVEDESK_ROLE_TRANSITION_ID || '').trim(),
+    role: normalizeRole(env.LIVEDESK_ROLE_TRANSITION_TARGET),
+    previousPid: positiveInteger(env.LIVEDESK_ROLE_TRANSITION_PREVIOUS_PID),
+    launcherEntry: launcherEntry ? resolve(launcherEntry) : '',
+    statePath: statePath ? resolve(statePath) : '',
+    logPath: logPath ? resolve(logPath) : '',
+    launchCwd: resolve(String(env.LIVEDESK_ROLE_TRANSITION_CWD || process.cwd()).trim()),
+    runtimePort: positiveInteger(env.LIVEDESK_ROLE_TRANSITION_RUNTIME_PORT, 5179),
+    remotePort: positiveInteger(env.LIVEDESK_ROLE_TRANSITION_REMOTE_PORT, 5197)
+  };
+}
+
+async function runRoleTransitionSupervisor(env = process.env) {
+  const settings = supervisorSettings(env);
+  if (!settings.transitionId || !settings.role || settings.previousPid <= 1) {
+    throw new Error('invalid-role-transition-supervisor-settings');
+  }
+  if (!existsSync(settings.launcherEntry)) {
+    throw new Error(`role-transition-launcher-missing:${settings.launcherEntry}`);
+  }
+
+  const writeState = (stage, details = {}) => {
+    writeJsonAtomic(settings.statePath, {
+      transitionId: settings.transitionId,
+      role: settings.role,
+      stage,
+      supervisorPid: process.pid,
+      previousPid: settings.previousPid,
+      updatedAt: new Date().toISOString(),
+      ...details
+    });
+  };
+
+  appendDiagnostic(
+    settings.logPath,
+    `transition=${settings.transitionId} target=${settings.role} supervisor=${process.pid} previous=${settings.previousPid}`
+  );
+  writeState('supervisor-ready');
+  if (!await waitForProcessExit(settings.previousPid)) {
+    throw new Error(`previous-runtime-exit-timeout:${settings.previousPid}`);
+  }
+  writeState('previous-runtime-exited');
+
+  let lastError = null;
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    const replacementEnvironment = {
+      ...env,
+      LIVEDESK_ROLE_TRANSITION: '',
+      LIVEDESK_RESTART_WAIT_PID: '',
+      LIVEDESK_ROLE_TAKEOVER: settings.role === 'hub' ? '1' : '',
+      LIVEDESK_SKIP_BROWSER_OPEN: '1'
+    };
+    for (const name of Object.keys(replacementEnvironment)) {
+      if (name.startsWith('LIVEDESK_ROLE_TRANSITION_')) {
+        delete replacementEnvironment[name];
+      }
+    }
+
+    let logDescriptor = 0;
+    let child = null;
+    try {
+      logDescriptor = openSync(settings.logPath, 'a');
+      child = spawn(
+        process.execPath,
+        [settings.launcherEntry, '--force-role', settings.role, '--no-open'],
+        {
+          cwd: settings.launchCwd,
+          env: replacementEnvironment,
+          detached: true,
+          stdio: ['ignore', logDescriptor, logDescriptor],
+          windowsHide: true
+        }
+      );
+      await new Promise((resolveSpawn, rejectSpawn) => {
+        child.once('spawn', resolveSpawn);
+        child.once('error', rejectSpawn);
+      });
+    } catch (error) {
+      lastError = error;
+      appendDiagnostic(settings.logPath, `attempt=${attempt} launch-failed error=${error?.message || error}`);
+      if (child?.pid && processIsAlive(child.pid)) {
+        await terminateOwnedProcessTree(child.pid);
+      }
+      await wait(350);
+      continue;
+    } finally {
+      if (logDescriptor > 0) closeSync(logDescriptor);
+    }
+    child.unref();
+    writeState('replacement-launched', { attempt, launcherPid: child.pid || 0 });
+    appendDiagnostic(settings.logPath, `attempt=${attempt} replacement-launcher=${child.pid || 0}`);
+
+    try {
+      const verified = await verifyReplacement({
+        child,
+        role: settings.role,
+        previousPid: settings.previousPid,
+        runtimePort: settings.runtimePort,
+        remotePort: settings.remotePort
+      });
+      writeState('verified', {
+        attempt,
+        launcherPid: child.pid || 0,
+        runtimePid: verified.runtimePid,
+        appVersion: verified.appVersion,
+        completedAt: new Date().toISOString()
+      });
+      appendDiagnostic(
+        settings.logPath,
+        `verified target=${settings.role} launcher=${child.pid || 0} runtime=${verified.runtimePid} version=${verified.appVersion || 'unknown'}`
+      );
+      return;
+    } catch (error) {
+      lastError = error;
+      appendDiagnostic(settings.logPath, `attempt=${attempt} failed error=${error?.message || error}`);
+      if (processIsAlive(child.pid)) {
+        await terminateOwnedProcessTree(child.pid);
+      }
+      await wait(350);
+    }
+  }
+  throw lastError || new Error('role-transition-replacement-failed');
+}
+
+export async function startRoleTransitionSupervisor(options = {}) {
+  const role = normalizeRole(options.role);
+  const previousPid = positiveInteger(options.previousPid, process.pid);
+  const launcherEntryValue = String(options.launcherEntry || '').trim();
+  const stateDirValue = String(options.stateDir || '').trim();
+  const launcherEntry = launcherEntryValue ? resolve(launcherEntryValue) : '';
+  const stateDir = stateDirValue ? resolve(stateDirValue) : '';
+  if (!role || previousPid <= 1 || !launcherEntry || !existsSync(launcherEntry) || !stateDir) {
+    throw new Error('invalid-role-transition-handoff');
+  }
+
+  mkdirSync(stateDir, { recursive: true });
+  const statePath = join(stateDir, 'role-transition.json');
+  const logPath = join(stateDir, 'role-transition.log');
+  const transitionId = `role-${role}-${Date.now()}-${process.pid}`;
+  rmSync(statePath, { force: true });
+  const child = spawn(
+    process.execPath,
+    [fileURLToPath(import.meta.url), ROLE_TRANSITION_SUPERVISOR_FLAG],
+    {
+      cwd: options.cwd || process.cwd(),
+      env: {
+        ...(options.env || process.env),
+        LIVEDESK_ROLE_TRANSITION_ID: transitionId,
+        LIVEDESK_ROLE_TRANSITION_TARGET: role,
+        LIVEDESK_ROLE_TRANSITION_PREVIOUS_PID: String(previousPid),
+        LIVEDESK_ROLE_TRANSITION_LAUNCHER_ENTRY: launcherEntry,
+        LIVEDESK_ROLE_TRANSITION_STATE_PATH: statePath,
+        LIVEDESK_ROLE_TRANSITION_LOG_PATH: logPath,
+        LIVEDESK_ROLE_TRANSITION_CWD: String(options.cwd || process.cwd()),
+        LIVEDESK_ROLE_TRANSITION_RUNTIME_PORT: String(positiveInteger(options.runtimePort, 5179)),
+        LIVEDESK_ROLE_TRANSITION_REMOTE_PORT: String(positiveInteger(options.remotePort, 5197))
+      },
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true
+    }
+  );
+  await new Promise((resolveSpawn, rejectSpawn) => {
+    child.once('spawn', resolveSpawn);
+    child.once('error', rejectSpawn);
+  });
+  child.unref();
+
+  const deadline = Date.now() + SUPERVISOR_CLAIM_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const state = readJson(statePath);
+    if (state?.transitionId === transitionId
+      && state?.stage === 'supervisor-ready'
+      && positiveInteger(state?.supervisorPid) === child.pid) {
+      return { transitionId, supervisorPid: child.pid, statePath, logPath };
+    }
+    if (!processIsAlive(child.pid)) {
+      throw new Error(`role-transition-supervisor-exited:${child.pid || 0}`);
+    }
+    await wait(50);
+  }
+  await terminateOwnedProcessTree(child.pid);
+  throw new Error(`role-transition-supervisor-claim-timeout:${child.pid || 0}`);
+}
+
+const isDirectSupervisorRun = process.argv.includes(ROLE_TRANSITION_SUPERVISOR_FLAG)
+  && resolve(String(process.argv[1] || '')) === fileURLToPath(import.meta.url);
+if (isDirectSupervisorRun) {
+  runRoleTransitionSupervisor().catch(error => {
+    const settings = supervisorSettings();
+    try {
+      appendDiagnostic(settings.logPath, `failed error=${error?.message || error}`);
+      writeJsonAtomic(settings.statePath, {
+        transitionId: settings.transitionId,
+        role: settings.role,
+        stage: 'failed',
+        supervisorPid: process.pid,
+        previousPid: settings.previousPid,
+        error: error?.message || String(error),
+        updatedAt: new Date().toISOString(),
+        completedAt: new Date().toISOString()
+      });
+    } catch {
+      // The detached supervisor has no console; best-effort diagnostics only.
+    }
+    process.exitCode = 1;
+  });
+}