livedesk 0.1.385 → 0.1.387

package/bootstrap/legacy-client-update.js

@@ -0,0 +1,1040 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import { dirname, join } from 'node:path';
+
+const DEFAULT_RUNTIME_PORT = 5179;
+const TARGET_ATTEMPT_LIMIT = 3;
+const RESTORE_ATTEMPT_LIMIT = 2;
+const VERIFY_TIMEOUT_MS = 45_000;
+const VERIFY_POLL_MS = 500;
+const VERIFY_STABLE_MS = 5_000;
+const PROCESS_ARGUMENT_QUERY_TIMEOUT_MS = 10_000;
+
+const PRESERVED_SINGLE_FLAGS = new Set([
+  '--control',
+  '--no-control',
+  '--thumbnail',
+  '--no-thumbnail',
+  '--live',
+  '--no-live',
+  '--audio',
+  '--no-audio',
+  '--tasks',
+  '--no-tasks',
+  '--ai',
+  '--no-ai',
+  '--fake-ai',
+  '--fake-thumbnail',
+  '--trace-frames'
+]);
+const PRESERVED_VALUE_FLAGS = new Set([
+  '--name',
+  '--heartbeat',
+  '--files-dir',
+  '--ai-model',
+  '--transport'
+]);
+const JOINED_VALUE_FLAGS = new Set(['--name', '--files-dir']);
+const SETTING_GROUPS = new Map([
+  ['--control', 'control'],
+  ['--no-control', 'control'],
+  ['--thumbnail', 'thumbnail'],
+  ['--no-thumbnail', 'thumbnail'],
+  ['--live', 'live'],
+  ['--no-live', 'live'],
+  ['--audio', 'audio'],
+  ['--no-audio', 'audio'],
+  ['--tasks', 'tasks'],
+  ['--no-tasks', 'tasks'],
+  ['--ai', 'ai'],
+  ['--no-ai', 'ai']
+]);
+
+function cleanVersion(value) {
+  return String(value || '').trim().replace(/^v/i, '');
+}
+
+function positivePid(value) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 1 ? parsed : 0;
+}
+
+function normalizePort(value) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535
+    ? parsed
+    : DEFAULT_RUNTIME_PORT;
+}
+
+function readManifest(relativePath) {
+  return JSON.parse(readFileSync(new URL(relativePath, import.meta.url), 'utf8'));
+}
+
+function readConfig(env = process.env) {
+  const stateDir = String(env.LIVEDESK_STATE_DIR || join(os.homedir(), '.livedesk'));
+  return {
+    operationId: String(env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || '').trim(),
+    deviceId: String(env.LIVEDESK_DEVICE_ID || '').trim(),
+    targetVersion: cleanVersion(env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION),
+    targetProductVersion: cleanVersion(env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION),
+    currentProductVersion: cleanVersion(env.LIVEDESK_CLIENT_UPDATE_CURRENT_PRODUCT_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),
+    starterPid: positivePid(env.LIVEDESK_UPDATE_STARTER_PID),
+    runtimePort: normalizePort(env.LIVEDESK_CLIENT_RUNTIME_PORT || env.LIVEDESK_LOCAL_RUNTIME_PORT),
+    stateDir,
+    statePath: String(
+      env.LIVEDESK_LEGACY_CLIENT_UPDATE_STATE_PATH
+      || env.LIVEDESK_CLIENT_UPDATE_STATE_PATH
+      || join(stateDir, 'client-update-legacy.json')
+    ),
+    restartArgs: []
+  };
+}
+
+function createLogger(config, writeLog = null) {
+  if (typeof writeLog === 'function') return writeLog;
+  const logPath = join(config.stateDir, 'client-update-legacy.log');
+  return message => {
+    try {
+      mkdirSync(config.stateDir, { recursive: true });
+      appendFileSync(logPath, `${new Date().toISOString()} ${message}\n`, 'utf8');
+    } catch {
+      // A read-only profile must not stop recovery.
+    }
+  };
+}
+
+function parseWindowsCommandLine(commandLine) {
+  const source = String(commandLine || '');
+  const args = [];
+  let current = '';
+  let quoted = false;
+  let backslashes = 0;
+  let started = false;
+
+  const flushBackslashes = count => {
+    if (count > 0) current += '\\'.repeat(count);
+  };
+  const push = () => {
+    if (!started) return;
+    flushBackslashes(backslashes);
+    backslashes = 0;
+    args.push(current);
+    current = '';
+    started = false;
+  };
+
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index];
+    if (character === '\\') {
+      backslashes += 1;
+      started = true;
+      continue;
+    }
+    if (character === '"') {
+      current += '\\'.repeat(Math.floor(backslashes / 2));
+      if (backslashes % 2 === 1) {
+        current += '"';
+      } else {
+        quoted = !quoted;
+      }
+      backslashes = 0;
+      started = true;
+      continue;
+    }
+    flushBackslashes(backslashes);
+    backslashes = 0;
+    if (!quoted && /\s/.test(character)) {
+      push();
+      continue;
+    }
+    current += character;
+    started = true;
+  }
+  push();
+  return args;
+}
+
+function parseShellCommandLine(commandLine) {
+  const source = String(commandLine || '');
+  const args = [];
+  let current = '';
+  let quote = '';
+  let escaped = false;
+  let started = false;
+  const push = () => {
+    if (!started) return;
+    args.push(current);
+    current = '';
+    started = false;
+  };
+  for (const character of source) {
+    if (escaped) {
+      current += character;
+      escaped = false;
+      started = true;
+      continue;
+    }
+    if (character === '\\' && quote !== "'") {
+      escaped = true;
+      started = true;
+      continue;
+    }
+    if (quote) {
+      if (character === quote) {
+        quote = '';
+      } else {
+        current += character;
+      }
+      started = true;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      push();
+      continue;
+    }
+    current += character;
+    started = true;
+  }
+  if (escaped) current += '\\';
+  push();
+  return args;
+}
+
+function decodePreservedArgs(env) {
+  const encoded = String(env.LIVEDESK_CLIENT_UPDATE_ARGS_BASE64 || '').trim();
+  if (!encoded) return null;
+  try {
+    const decoded = JSON.parse(Buffer.from(encoded, 'base64').toString('utf8'));
+    if (!Array.isArray(decoded)) return null;
+    return decoded.map(value => String(value));
+  } catch {
+    return null;
+  }
+}
+
+function processArgumentsFromWindows(pid) {
+  const script = [
+    '$ErrorActionPreference = "Stop"',
+    '[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)',
+    `$p = Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}"`,
+    'if ($null -eq $p -or [string]::IsNullOrWhiteSpace($p.CommandLine)) { exit 3 }',
+    '[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$p.CommandLine))'
+  ].join(';');
+  const encoded = Buffer.from(script, 'utf16le').toString('base64');
+  const result = spawnSync(
+    'powershell.exe',
+    ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded],
+    {
+      encoding: 'utf8',
+      timeout: PROCESS_ARGUMENT_QUERY_TIMEOUT_MS,
+      windowsHide: true
+    }
+  );
+  if (result.error || result.status !== 0) {
+    throw new Error(
+      `Windows process argument query failed for pid ${pid}: `
+      + `${result.error?.message || String(result.stderr || '').trim() || `exit ${result.status}`}`
+    );
+  }
+  const commandLine = Buffer.from(String(result.stdout || '').trim(), 'base64').toString('utf8');
+  const args = parseWindowsCommandLine(commandLine);
+  if (args.length === 0) throw new Error(`Windows process ${pid} has no readable arguments`);
+  return args;
+}
+
+function processArgumentsFromProc(pid) {
+  const bytes = readFileSync(`/proc/${pid}/cmdline`);
+  const args = bytes
+    .toString('utf8')
+    .split('\0')
+    .filter(value => value.length > 0);
+  if (args.length === 0) throw new Error(`Process ${pid} has no readable arguments`);
+  return args;
+}
+
+function processArgumentsFromPs(pid) {
+  const result = spawnSync('ps', ['-ww', '-p', String(pid), '-o', 'command='], {
+    encoding: 'utf8',
+    timeout: PROCESS_ARGUMENT_QUERY_TIMEOUT_MS
+  });
+  if (result.error || result.status !== 0 || !String(result.stdout || '').trim()) {
+    throw new Error(
+      `ps argument query failed for pid ${pid}: `
+      + `${result.error?.message || String(result.stderr || '').trim() || `exit ${result.status}`}`
+    );
+  }
+  return parseShellCommandLine(result.stdout);
+}
+
+export function readLegacyProcessArguments(pid, platform = process.platform) {
+  const processId = positivePid(pid);
+  if (!processId) throw new Error(`Invalid process id for argument snapshot: ${pid}`);
+  if (platform === 'win32') return processArgumentsFromWindows(processId);
+  if (platform === 'linux' && existsSync(`/proc/${processId}/cmdline`)) {
+    return processArgumentsFromProc(processId);
+  }
+  if (platform === 'darwin' || platform === 'linux' || platform === 'freebsd') {
+    return processArgumentsFromPs(processId);
+  }
+  throw new Error(`LiveDesk cannot snapshot Client arguments on ${platform}`);
+}
+
+function readOptionValue(args, index, joinUntilFlag) {
+  const values = [];
+  for (let cursor = index + 1; cursor < args.length; cursor += 1) {
+    const value = String(args[cursor] || '');
+    if (!value || value === '--') continue;
+    if (value.startsWith('--')) break;
+    values.push(value);
+    if (!joinUntilFlag) break;
+  }
+  return values.join(' ');
+}
+
+function collectPreservedOptions(sources) {
+  const selected = new Map();
+  for (const source of sources) {
+    const args = Array.isArray(source) ? source.map(value => String(value)) : [];
+    for (let index = 0; index < args.length; index += 1) {
+      const token = args[index];
+      const equalsAt = token.indexOf('=');
+      const flag = equalsAt > 0 ? token.slice(0, equalsAt) : token;
+      if (PRESERVED_SINGLE_FLAGS.has(flag)) {
+        selected.set(SETTING_GROUPS.get(flag) || flag, [flag]);
+        continue;
+      }
+      if (!PRESERVED_VALUE_FLAGS.has(flag)) continue;
+      const value = equalsAt > 0
+        ? token.slice(equalsAt + 1)
+        : readOptionValue(args, index, JOINED_VALUE_FLAGS.has(flag));
+      if (!value) continue;
+      selected.set(flag, [flag, value]);
+    }
+  }
+  return [...selected.values()].flat();
+}
+
+function findOptionValue(args, flag) {
+  const source = Array.isArray(args) ? args.map(value => String(value)) : [];
+  let found = '';
+  for (let index = 0; index < source.length; index += 1) {
+    const token = source[index];
+    if (token.startsWith(`${flag}=`)) {
+      found = token.slice(flag.length + 1);
+      continue;
+    }
+    if (token === flag && source[index + 1] && !String(source[index + 1]).startsWith('--')) {
+      found = String(source[index + 1]);
+    }
+  }
+  return found;
+}
+
+function normalizeEngine(value) {
+  const engine = String(value || '').trim().toLowerCase();
+  if (engine === 'c#' || engine === 'csharp' || engine === 'fast') return 'fast';
+  if (engine === 'js' || engine === 'legacy' || engine === 'node') return 'node';
+  return 'auto';
+}
+
+export function buildLegacyClientRestartConfiguration({
+  env = process.env,
+  launcherArgs = [],
+  agentArgs = [],
+  preservedArgs = decodePreservedArgs(env)
+} = {}) {
+  const sources = [preservedArgs || [], launcherArgs, agentArgs];
+  const restartArgs = collectPreservedOptions(sources);
+  const commandLinePort = findOptionValue(launcherArgs, '--auth-port')
+    || findOptionValue(preservedArgs, '--auth-port');
+  const runtimePort = normalizePort(
+    commandLinePort
+    || env.LIVEDESK_CLIENT_RUNTIME_PORT
+    || env.LIVEDESK_CLIENT_AUTH_PORT
+    || env.LIVEDESK_LOCAL_RUNTIME_PORT
+  );
+  const commandLineEngine = findOptionValue(launcherArgs, '--engine')
+    || findOptionValue(preservedArgs, '--engine');
+  const engineFlag = [...launcherArgs, ...(preservedArgs || [])].find(value => (
+    value === '--fast' || value === '--csharp' || value === '--node'
+  ));
+  const engine = normalizeEngine(
+    env.LIVEDESK_CLIENT_ENGINE
+    || commandLineEngine
+    || (engineFlag === '--node' ? 'node' : engineFlag ? 'fast' : 'auto')
+  );
+  restartArgs.push('--engine', engine, '--auth-port', String(runtimePort));
+  return { restartArgs, runtimePort, engine };
+}
+
+function captureRestartConfiguration(config, env, readArguments = readLegacyProcessArguments) {
+  const preservedArgs = decodePreservedArgs(env);
+  if (preservedArgs) {
+    return buildLegacyClientRestartConfiguration({ env, preservedArgs });
+  }
+  let launcherArgs;
+  let agentArgs;
+  try {
+    launcherArgs = readArguments(config.launcherPid);
+    agentArgs = readArguments(config.agentPid);
+  } catch (error) {
+    throw new Error(
+      `LiveDesk could not freeze the current Client options before update; `
+      + `the existing Client was left running. ${error?.message || error}`
+    );
+  }
+  return buildLegacyClientRestartConfiguration({ env, launcherArgs, agentArgs });
+}
+
+function readUpdateState(config) {
+  try {
+    return JSON.parse(readFileSync(config.statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function proofStatePath(config, attemptId) {
+  const safeAttemptId = String(attemptId || '')
+    .replace(/[^A-Za-z0-9._-]/g, '_')
+    .slice(0, 160);
+  return join(dirname(config.statePath), `client-update-proof-${safeAttemptId}.json`);
+}
+
+function writeUpdateState(config, stage, details = {}) {
+  mkdirSync(dirname(config.statePath), { recursive: true });
+  const previous = readUpdateState(config);
+  const next = {
+    ...(previous && previous.operationId === config.operationId ? previous : {}),
+    operationId: config.operationId,
+    stage,
+    targetVersion: config.targetVersion,
+    targetProductVersion: config.targetProductVersion,
+    targetAgentVersion: config.targetVersion,
+    currentProductVersion: config.currentProductVersion,
+    supervisorPid: process.pid,
+    updatedAt: new Date().toISOString(),
+    ...details
+  };
+  const temporaryPath = `${config.statePath}.${process.pid}.${randomBytes(5).toString('hex')}.tmp`;
+  try {
+    writeFileSync(temporaryPath, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporaryPath, config.statePath);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+  return next;
+}
+
+function isAlive(pid) {
+  if (pid <= 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function sleep(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+async function waitForExit(pid, timeoutMs, sleepImpl = sleep, aliveImpl = isAlive) {
+  if (pid <= 1) return true;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!aliveImpl(pid)) return true;
+    await sleepImpl(200);
+  }
+  return !aliveImpl(pid);
+}
+
+function requestRuntimeStatus(port, timeoutMs = 1500) {
+  return new Promise((resolve, reject) => {
+    const request = http.get({
+      host: '127.0.0.1',
+      port,
+      path: '/api/runtime/status',
+      headers: { Accept: 'application/json' }
+    }, response => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', chunk => {
+        body += chunk;
+        if (body.length > 1024 * 1024) request.destroy(new Error('runtime status response is too large'));
+      });
+      response.once('end', () => {
+        if (response.statusCode !== 200) {
+          reject(new Error(`runtime status returned HTTP ${response.statusCode || 0}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          reject(new Error('runtime status returned invalid JSON'));
+        }
+      });
+    });
+    request.setTimeout(timeoutMs, () => request.destroy(new Error('runtime status timed out')));
+    request.once('error', reject);
+  });
+}
+
+export function validateLegacyClientReplacementStatus(
+  status,
+  { deviceId, productVersion, previousRuntimePid = 0 }
+) {
+  const runtimePid = positivePid(status?.runtimePid);
+  const agentPid = positivePid(status?.agent?.pid);
+  if (status?.ok !== true || status?.role !== 'client' || status?.runtimeStarted !== true) {
+    throw new Error('replacement Client runtime is not ready');
+  }
+  if (String(status?.deviceId || '') !== String(deviceId || '')) {
+    throw new Error(`replacement device mismatch expected=${deviceId || 'unknown'} actual=${status?.deviceId || 'unknown'}`);
+  }
+  if (cleanVersion(status?.appVersion) !== cleanVersion(productVersion)) {
+    throw new Error(`replacement product mismatch expected=${productVersion || 'unknown'} actual=${status?.appVersion || 'unknown'}`);
+  }
+  if (runtimePid <= 1 || (previousRuntimePid > 1 && runtimePid === previousRuntimePid)) {
+    throw new Error(`replacement runtime PID is invalid or unchanged (${runtimePid || 0})`);
+  }
+  if (status?.agent?.state !== 'running' || agentPid <= 1) {
+    throw new Error('replacement Agent is not running');
+  }
+  return { runtimePid, agentPid, appVersion: cleanVersion(status.appVersion) };
+}
+
+export function validateLegacyClientConnectedProof(
+  state,
+  {
+    operationId,
+    attemptId,
+    productVersion,
+    agentVersion,
+    previousRuntimePid = 0
+  }
+) {
+  const launcherPid = positivePid(state?.launcherPid);
+  const agentPid = positivePid(state?.agentPid);
+  if (state?.stage !== 'connected' || state?.restartVerified !== true) {
+    throw new Error('replacement Agent has not published connected proof');
+  }
+  if (String(state?.operationId || '') !== String(operationId || '')
+    || String(state?.attemptId || '') !== String(attemptId || '')) {
+    throw new Error('replacement connected proof belongs to another operation or attempt');
+  }
+  if (cleanVersion(state?.productVersion) !== cleanVersion(productVersion)) {
+    throw new Error(
+      `replacement proof product mismatch expected=${productVersion || 'unknown'} `
+      + `actual=${state?.productVersion || 'unknown'}`
+    );
+  }
+  if (cleanVersion(state?.agentVersion) !== cleanVersion(agentVersion)) {
+    throw new Error(
+      `replacement proof Agent mismatch expected=${agentVersion || 'unknown'} `
+      + `actual=${state?.agentVersion || 'unknown'}`
+    );
+  }
+  if (launcherPid <= 1 || (previousRuntimePid > 1 && launcherPid === previousRuntimePid)) {
+    throw new Error(`replacement proof launcher PID is invalid or unchanged (${launcherPid || 0})`);
+  }
+  if (agentPid <= 1) throw new Error('replacement proof has no Agent PID');
+  return {
+    launcherPid,
+    agentPid,
+    productVersion: cleanVersion(state.productVersion),
+    agentVersion: cleanVersion(state.agentVersion)
+  };
+}
+
+function resolveNpxInvocation(args, env = process.env) {
+  const nodeDirectory = dirname(process.execPath);
+  const npmExecPath = String(env.npm_execpath || env.NPM_EXECPATH || '').trim();
+  const cliCandidates = [
+    env.LIVEDESK_NPX_CLI_PATH,
+    npmExecPath ? join(dirname(npmExecPath), 'npx-cli.js') : '',
+    env.LIVEDESK_NPX_EXECUTABLE
+      ? join(dirname(env.LIVEDESK_NPX_EXECUTABLE), 'node_modules', 'npm', 'bin', 'npx-cli.js')
+      : '',
+    join(nodeDirectory, 'node_modules', 'npm', 'bin', 'npx-cli.js')
+  ].filter(Boolean);
+  const npxCli = cliCandidates.find(candidate => existsSync(candidate));
+  if (npxCli) return { command: process.execPath, args: [npxCli, ...args] };
+
+  const executableCandidates = process.platform === 'win32'
+    ? [env.LIVEDESK_NPX_EXECUTABLE, join(nodeDirectory, 'npx.cmd'), 'npx.cmd']
+    : [env.LIVEDESK_NPX_EXECUTABLE, join(nodeDirectory, 'npx'), 'npx'];
+  const npx = executableCandidates.find(candidate => candidate && (!candidate.includes('/') && !candidate.includes('\\') || existsSync(candidate)))
+    || executableCandidates.at(-1);
+  if (!npx) throw new Error('LiveDesk npx executable was not found');
+  if (process.platform !== 'win32') return { command: npx, args };
+
+  const quote = value => `"${String(value).replaceAll('"', '""')}"`;
+  return {
+    command: process.env.ComSpec || 'cmd.exe',
+    args: ['/d', '/s', '/c', `call ${quote(npx)} ${args.map(quote).join(' ')}`]
+  };
+}
+
+function spawnReplacement(version, preference, env = process.env, restartArgs = [], outputPath = '') {
+  const packageArgs = ['-y', preference, `livedesk@${version}`];
+  const roleArgs = [
+    '--force-role',
+    'client',
+    '--no-login',
+    '--no-open',
+    ...restartArgs,
+    '--device-id',
+    env.LIVEDESK_DEVICE_ID
+  ];
+  const invocation = resolveNpxInvocation([...packageArgs, ...roleArgs], env);
+  let outputFd = null;
+  if (outputPath) {
+    mkdirSync(dirname(outputPath), { recursive: true });
+    outputFd = openSync(outputPath, 'a');
+  }
+  let child;
+  try {
+    child = spawn(invocation.command, invocation.args, {
+      env,
+      detached: true,
+      stdio: outputFd === null ? 'ignore' : ['ignore', outputFd, outputFd],
+      windowsHide: true
+    });
+  } finally {
+    if (outputFd !== null) closeSync(outputFd);
+  }
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('spawn', () => resolve(child));
+  });
+}
+
+function hasLegacyConnectedOutput(outputPath, deviceId) {
+  if (!outputPath || !existsSync(outputPath)) return false;
+  let output = '';
+  try {
+    output = readFileSync(outputPath, 'utf8').slice(-256 * 1024);
+  } catch {
+    return false;
+  }
+  const escapedDeviceId = String(deviceId || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  if (!escapedDeviceId) return false;
+  return new RegExp(
+    `Connected to LiveDesk Hub as [^\\r\\n]*\\(${escapedDeviceId}\\)(?:\\s+via\\s+\\S+)?`
+  ).test(output);
+}
+
+async function terminateReplacementTree(child) {
+  const pid = positivePid(child?.pid);
+  if (pid <= 1) return;
+  if (process.platform === 'win32') {
+    await new Promise(resolve => {
+      const killer = spawn('taskkill.exe', ['/PID', String(pid), '/T', '/F'], {
+        windowsHide: true,
+        stdio: 'ignore'
+      });
+      killer.once('error', resolve);
+      killer.once('exit', resolve);
+    });
+    return;
+  }
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      // The failed replacement already exited.
+    }
+  }
+}
+
+async function terminateOldRuntime(config, { sleepImpl = sleep, aliveImpl = isAlive } = {}) {
+  if (config.launcherPid <= 1) throw new Error('legacy update has no valid launcher PID');
+  const victims = [...new Set([config.launcherPid, config.agentPid].filter(pid => pid > 1 && pid !== process.pid))];
+  for (const pid of victims) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // Already stopped.
+    }
+  }
+  await sleepImpl(2500);
+  for (const pid of victims) {
+    if (!aliveImpl(pid)) continue;
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // Already stopped.
+    }
+  }
+  const launcherExited = await waitForExit(config.launcherPid, 15_000, sleepImpl, aliveImpl);
+  const agentExited = await waitForExit(config.agentPid, 15_000, sleepImpl, aliveImpl);
+  if (!launcherExited || !agentExited) {
+    throw new Error(`old runtime did not exit launcher=${launcherExited} agent=${agentExited}`);
+  }
+}
+
+export async function launchAndVerifyLegacyClientReplacement(
+  config,
+  version,
+  agentVersion,
+  kind,
+  attempt,
+  preference,
+  options = {}
+) {
+  const sleepImpl = options.sleepImpl || sleep;
+  const requestStatus = options.requestStatus || requestRuntimeStatus;
+  const writeState = options.writeUpdateState || writeUpdateState;
+  const aliveImpl = options.aliveImpl || isAlive;
+  const now = options.now || Date.now;
+  const log = options.log || (() => undefined);
+  const attemptId = String(
+    options.attemptId
+    || `${config.operationId}-${kind}-${attempt}-${randomBytes(5).toString('hex')}`
+  );
+  const proofConfig = {
+    ...config,
+    statePath: String(options.proofStatePath || proofStatePath(config, attemptId))
+  };
+  const readProofState = options.readUpdateState
+    ? () => options.readUpdateState(proofConfig)
+    : () => readUpdateState(proofConfig);
+  if (!options.readUpdateState) rmSync(proofConfig.statePath, { force: true });
+  const outputPath = String(
+    options.outputPath
+    || (kind === 'restore'
+      ? join(
+        config.stateDir,
+        `client-update-${attemptId.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 160)}.log`
+      )
+      : '')
+  );
+  const replacementEnv = {
+    ...(options.env || process.env),
+    LIVEDESK_CLIENT_UPDATE_OPERATION_ID: config.operationId,
+    LIVEDESK_CLIENT_UPDATE_ATTEMPT_ID: attemptId,
+    LIVEDESK_CLIENT_UPDATE_ATTEMPT_KIND: kind,
+    LIVEDESK_CLIENT_UPDATE_ATTEMPT_NUMBER: String(attempt),
+    LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION: version,
+    LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION: agentVersion,
+    LIVEDESK_CLIENT_UPDATE_TARGET_VERSION: agentVersion,
+    LIVEDESK_CLIENT_UPDATE_STATE_PATH: proofConfig.statePath,
+    LIVEDESK_CLIENT_RUNTIME_PORT: String(config.runtimePort),
+    LIVEDESK_DEVICE_ID: config.deviceId,
+    LIVEDESK_SKIP_BROWSER_OPEN: '1'
+  };
+  writeState(config, `${kind}-launching`, {
+    attemptId,
+    attemptKind: kind,
+    attemptNumber: attempt,
+    expectedProductVersion: version,
+    expectedAgentVersion: agentVersion,
+    outputPath,
+    restartVerified: false,
+    error: ''
+  });
+  const child = await (options.spawnReplacement || spawnReplacement)(
+    version,
+    preference,
+    replacementEnv,
+    config.restartArgs,
+    outputPath
+  );
+  const pid = positivePid(child?.pid);
+  log(`${kind} attempt=${attempt} id=${attemptId} spawned pid=${pid} version=${version}/${agentVersion}`);
+  // The replacement can reach the Hub and publish its connected proof before
+  // spawnReplacement resolves. Do not write a post-spawn lifecycle state here:
+  // it could overwrite that one-shot proof and turn a successful restart into
+  // a false timeout. The pre-spawn attempt state already owns this attempt.
+  const deadline = now() + (options.verifyTimeoutMs ?? VERIFY_TIMEOUT_MS);
+  let lastError = null;
+  let verifiedSince = null;
+  let lastVerified = null;
+  let terminalProofFailure = false;
+  while (now() < deadline) {
+    try {
+      const state = readProofState();
+      let proof;
+      let proofSource = 'agent-state';
+      try {
+        proof = validateLegacyClientConnectedProof(state, {
+          operationId: config.operationId,
+          attemptId,
+          productVersion: version,
+          agentVersion,
+          previousRuntimePid: config.launcherPid
+        });
+      } catch (proofError) {
+        const restoreWelcomeObserved = kind === 'restore'
+          && (options.hasLegacyConnectedOutput || hasLegacyConnectedOutput)(
+            outputPath,
+            config.deviceId
+          );
+        if (!restoreWelcomeObserved) throw proofError;
+        proof = null;
+        proofSource = 'legacy-welcome-output';
+      }
+      const status = await requestStatus(config.runtimePort);
+      const verified = validateLegacyClientReplacementStatus(status, {
+        deviceId: config.deviceId,
+        productVersion: version,
+        previousRuntimePid: config.launcherPid
+      });
+      if (!proof) {
+        proof = {
+          launcherPid: verified.runtimePid,
+          agentPid: verified.agentPid,
+          productVersion: verified.appVersion,
+          agentVersion
+        };
+      }
+      if (proof.launcherPid !== verified.runtimePid || proof.agentPid !== verified.agentPid) {
+        throw new Error(
+          `replacement connected proof PIDs do not match local runtime `
+          + `proof=${proof.launcherPid}/${proof.agentPid} `
+          + `runtime=${verified.runtimePid}/${verified.agentPid}`
+        );
+      }
+      if (!aliveImpl(proof.launcherPid) || !aliveImpl(proof.agentPid)) {
+        throw new Error('replacement connected-proof process exited during verification');
+      }
+      lastVerified = { ...verified, proof, proofSource };
+      if (verifiedSince === null) verifiedSince = now();
+      if (now() - verifiedSince >= (options.verifyStableMs ?? VERIFY_STABLE_MS)) {
+        log(
+          `${kind} attempt=${attempt} id=${attemptId} verified `
+          + `launcher=${verified.runtimePid} agent=${verified.agentPid} `
+          + `version=${verified.appVersion}/${proof.agentVersion} proof=${proofSource}`
+        );
+        writeState(config, kind === 'target' ? 'connected' : 'restored', {
+          attemptId,
+          attemptKind: kind,
+          attemptNumber: attempt,
+          restartPid: pid,
+          launcherPid: verified.runtimePid,
+          agentPid: verified.agentPid,
+          productVersion: verified.appVersion,
+          agentVersion: proof.agentVersion,
+          proofSource,
+          restartVerified: kind === 'target',
+          restored: kind === 'restore',
+          connectedAt: state?.connectedAt || state?.details?.connectedAt || new Date().toISOString(),
+          error: kind === 'restore'
+            ? `Target ${config.targetProductVersion} failed; previous Client ${version} was restored.`
+            : ''
+        });
+        if (!options.readUpdateState) rmSync(proofConfig.statePath, { force: true });
+        child.unref?.();
+        return { ...verified, agentVersion: proof.agentVersion, attemptId };
+      }
+    } catch (error) {
+      lastError = error;
+      const state = readProofState();
+      terminalProofFailure = state?.stage === 'connected'
+        && String(state?.operationId || '') === config.operationId
+        && String(state?.attemptId || '') === attemptId
+        && /mismatch|another operation|PID|process exited/i.test(String(error?.message || error));
+      verifiedSince = null;
+      lastVerified = null;
+    }
+    if (terminalProofFailure || (pid > 1 && !aliveImpl(pid))) break;
+    await sleepImpl(options.verifyPollMs ?? VERIFY_POLL_MS);
+  }
+  await (options.terminateReplacementTree || terminateReplacementTree)(child);
+  if (!options.readUpdateState) rmSync(proofConfig.statePath, { force: true });
+  const failure = new Error(
+    `${kind} attempt=${attempt} did not become healthy: `
+    + `${lastError?.message || (lastVerified ? 'runtime did not remain stable' : 'verification deadline expired')}`
+  );
+  writeState(config, `${kind}-attempt-failed`, {
+    attemptId,
+    attemptKind: kind,
+    attemptNumber: attempt,
+    restartPid: pid,
+    failedAt: new Date().toISOString(),
+    restartVerified: false,
+    error: failure.message
+  });
+  throw failure;
+}
+
+export async function runLegacyClientUpdateSupervisor(options = {}) {
+  const env = options.env || process.env;
+  const config = readConfig(env);
+  const log = createLogger(config, options.writeLog);
+  const persistState = options.writeUpdateState || writeUpdateState;
+  const productManifest = options.productManifest || readManifest('../package.json');
+  const clientManifest = options.clientManifest || readManifest('../client/package.json');
+  const sleepImpl = options.sleepImpl || sleep;
+  const terminateOld = options.terminateOldRuntime || (value => terminateOldRuntime(value, {
+    sleepImpl,
+    aliveImpl: options.aliveImpl || isAlive
+  }));
+  const attemptReplacement = options.attemptReplacement || ((
+    version,
+    kind,
+    attempt,
+    preference,
+    expectedAgentVersion
+  ) => (
+    launchAndVerifyLegacyClientReplacement(
+      config,
+      version,
+      expectedAgentVersion,
+      kind,
+      attempt,
+      preference,
+      {
+      ...options,
+      env,
+      log,
+      sleepImpl
+      }
+    )
+  ));
+
+  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');
+  }
+  if (cleanVersion(productManifest.version) !== config.targetProductVersion) {
+    throw new Error(`prepared product mismatch expected=${config.targetProductVersion} actual=${productManifest.version || 'unknown'}`);
+  }
+  if (cleanVersion(productManifest.livedeskClientVersion) !== config.targetVersion
+    || cleanVersion(clientManifest.version) !== config.targetVersion) {
+    throw new Error(`prepared Agent mismatch expected=${config.targetVersion} bundled=${productManifest.livedeskClientVersion || 'unknown'} client=${clientManifest.version || 'unknown'}`);
+  }
+  const frozen = (options.captureRestartConfiguration || captureRestartConfiguration)(
+    config,
+    env,
+    options.readProcessArguments || readLegacyProcessArguments
+  );
+  config.restartArgs = [...frozen.restartArgs];
+  config.runtimePort = frozen.runtimePort;
+  log(`options-frozen count=${config.restartArgs.length} runtimePort=${config.runtimePort} engine=${frozen.engine}`);
+  persistState(config, 'preflight-ready', {
+    runtimePort: config.runtimePort,
+    engine: frozen.engine,
+    restartArgCount: config.restartArgs.length,
+    restartVerified: false,
+    error: ''
+  });
+  log(`preflight-ready target=${config.targetProductVersion}/${config.targetVersion}`);
+  await waitForExit(config.starterPid, 10_000, sleepImpl, options.aliveImpl || isAlive);
+  log(`stopping launcher=${config.launcherPid} agent=${config.agentPid}`);
+  await terminateOld(config);
+
+  const targetErrors = [];
+  for (let attempt = 1; attempt <= TARGET_ATTEMPT_LIMIT; attempt += 1) {
+    try {
+      await attemptReplacement(
+        config.targetProductVersion,
+        'target',
+        attempt,
+        '--prefer-online',
+        config.targetVersion
+      );
+      log(`completed target=${config.targetProductVersion}/${config.targetVersion}`);
+      persistState(config, 'connected', {
+        restartVerified: true,
+        completedAt: new Date().toISOString(),
+        error: ''
+      });
+      return { outcome: 'updated', attempt };
+    } catch (error) {
+      targetErrors.push(String(error?.message || error));
+      log(`target attempt=${attempt} failed error=${error?.message || error}`);
+    }
+  }
+
+  if (!config.currentProductVersion) {
+    throw new Error(`target failed and no exact restore version is available: ${targetErrors.join(' | ')}`);
+  }
+  const restoreErrors = [];
+  for (let attempt = 1; attempt <= RESTORE_ATTEMPT_LIMIT; attempt += 1) {
+    try {
+      await attemptReplacement(
+        config.currentProductVersion,
+        'restore',
+        attempt,
+        '--prefer-offline',
+        config.currentAgentVersion
+      );
+      log(`restored version=${config.currentProductVersion}`);
+      persistState(config, 'restored', {
+        productVersion: config.currentProductVersion,
+        agentVersion: config.currentAgentVersion,
+        restartVerified: false,
+        restored: true,
+        restoredAt: new Date().toISOString(),
+        error: `Target ${config.targetProductVersion} failed verification: ${targetErrors.join(' | ')}`
+      });
+      return {
+        outcome: 'restored',
+        attempt,
+        error: `Target ${config.targetProductVersion} failed verification: ${targetErrors.join(' | ')}`
+      };
+    } catch (error) {
+      restoreErrors.push(String(error?.message || error));
+      log(`restore attempt=${attempt} failed error=${error?.message || error}`);
+    }
+  }
+  throw new Error(
+    `target failed after ${TARGET_ATTEMPT_LIMIT} attempts and restore failed after ${RESTORE_ATTEMPT_LIMIT} attempts: `
+    + [...targetErrors, ...restoreErrors].join(' | ')
+  );
+}
+
+export async function runLegacyClientUpdateSupervisorCli() {
+  try {
+    const result = await runLegacyClientUpdateSupervisor();
+    if (result.outcome === 'restored') process.exitCode = 1;
+  } catch (error) {
+    const config = readConfig();
+    const log = createLogger(config);
+    log(`failed error=${error?.stack || error}`);
+    try {
+      writeUpdateState(config, 'failed', {
+        restartVerified: false,
+        failedAt: new Date().toISOString(),
+        error: String(error?.message || error).slice(0, 4000)
+      });
+    } catch {
+      // The persistent log remains the fallback on a read-only state directory.
+    }
+    console.error(error?.message || error);
+    process.exitCode = 1;
+  }
+}