livedesk 0.1.388 → 0.1.389

package/bin/livedesk.js

@@ -27,13 +27,250 @@ const PORT_CLEANUP_TIMEOUT_MS = 3000;
 const PORT_CLEANUP_POLL_MS = 100;
 const EXISTING_RUNTIME_STOP_TIMEOUT_MS = 10000;
 const HUB_STARTUP_RETRY_LIMIT = 1;
-const HUB_UPDATE_POLL_MS = 250;
-const MANAGER_STATE_DIR = process.env.LIVEDESK_STATE_DIR || join(os.homedir(), '.livedesk');
+const HUB_UPDATE_POLL_MS = 250;
+const HUB_UPDATE_SUPERVISOR_HANDSHAKE_TIMEOUT_MS = 10_000;
+const HUB_UPDATE_SUPERVISOR_HANDSHAKE_POLL_MS = 25;
+const HUB_UPDATE_SUPERVISOR_CLAIM_STABILITY_MS = 350;
+const UPDATE_ORIGINAL_CWD = resolve(
+  String(process.env.LIVEDESK_UPDATE_ORIGINAL_CWD || process.cwd()).trim() || process.cwd()
+);
+const MANAGER_STATE_DIR = resolve(
+  UPDATE_ORIGINAL_CWD,
+  process.env.LIVEDESK_STATE_DIR || join(os.homedir(), '.livedesk')
+);
 const MANAGER_STATE_PATH = join(MANAGER_STATE_DIR, 'manager.json');
+const TERMINAL_HUB_UPDATE_OUTCOMES = new Set(['updated', 'restored', 'failed']);
+
+function safeUpdatePathSegment(value, fallback = 'unknown') {
+  return String(value || '')
+    .replace(/[^A-Za-z0-9._-]/g, '_')
+    .slice(0, 120) || fallback;
+}
+
+function normalizeExactUpdateVersion(value) {
+  const version = String(value || '').trim();
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version)
+    ? version
+    : '';
+}
+
+function prepareUpdateNeutralCwd(kind, operationId) {
+  const neutralCwd = join(
+    os.tmpdir(),
+    'livedesk-update-cwd',
+    `${safeUpdatePathSegment(kind, 'update')}-${safeUpdatePathSegment(operationId)}`
+  );
+  mkdirSync(neutralCwd, { recursive: true });
+  for (let ancestor = neutralCwd; ; ancestor = dirname(ancestor)) {
+    const shadowPath = ['package.json', join('node_modules', 'livedesk', 'package.json')]
+      .map(relativePath => join(ancestor, relativePath))
+      .find(candidate => existsSync(candidate));
+    if (shadowPath) {
+      throw new Error(
+        `LiveDesk update neutral working directory is shadowed by ${shadowPath}: ${neutralCwd}`
+      );
+    }
+    const parent = dirname(ancestor);
+    if (parent === ancestor) break;
+  }
+  return neutralCwd;
+}
+
+function buildNeutralNpxEnvironment(baseEnv, neutralCwd) {
+  const env = { ...baseEnv };
+  const isolatedNames = new Set([
+    'init_cwd',
+    'npm_config_local_prefix',
+    'npm_config_workspace',
+    'npm_config_workspaces',
+    'npm_config_include_workspace_root',
+    'npm_package_json',
+    'npm_lifecycle_event',
+    'npm_lifecycle_script'
+  ]);
+  for (const key of Object.keys(env)) {
+    if (isolatedNames.has(key.toLowerCase())) delete env[key];
+  }
+  env.INIT_CWD = neutralCwd;
+  env.npm_config_local_prefix = neutralCwd;
+  env.npm_config_include_workspace_root = 'false';
+  return env;
+}
+
+function restoreUpdateOriginalCwd() {
+  if (!process.env.LIVEDESK_UPDATE_ORIGINAL_CWD) return;
+  try {
+    process.chdir(UPDATE_ORIGINAL_CWD);
+  } catch (error) {
+    throw new Error(
+      `LiveDesk could not restore the pre-update working directory ${UPDATE_ORIGINAL_CWD}: `
+      + `${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid) {
+  const processId = Number(pid);
+  if (!Number.isInteger(processId) || processId <= 1) return false;
+  try {
+    process.kill(processId, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function canClaimHubUpdateResult(current, next) {
+  const currentOperationId = String(current?.operationId || '');
+  const nextOperationId = String(next?.operationId || '');
+  if (!currentOperationId || !nextOperationId || currentOperationId === nextOperationId) return true;
+  const isClaimStage = ['supervisor-starting', 'preflight-failed'].includes(String(next?.stage || ''));
+  if (!isClaimStage) return false;
+  if (TERMINAL_HUB_UPDATE_OUTCOMES.has(String(current?.outcome || ''))) return true;
+  const ownerPids = [
+    Number(current?.supervisorPid || 0),
+    Number(current?.launcherPid || 0)
+  ].filter(pid => Number.isInteger(pid) && pid > 1);
+  return ownerPids.length > 0 && ownerPids.every(pid => !isPidAlive(pid));
+}
+
+function resultRevision(value) {
+  return JSON.stringify([
+    String(value?.operationId || ''),
+    String(value?.stage || ''),
+    String(value?.outcome || ''),
+    String(value?.updatedAt || '')
+  ]);
+}
+
+function delay(milliseconds) {
+  return new Promise(resolveDelay => setTimeout(resolveDelay, milliseconds));
+}
+
+function readBoundedMilliseconds(value, fallback, minimum = 1) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= minimum ? Math.round(parsed) : fallback;
+}
+
+async function stopUnclaimedHubRestartSupervisor(child) {
+  const supervisorPid = Number(child?.pid || 0);
+  if (supervisorPid <= 1 || !isPidAlive(supervisorPid)) return;
+  try {
+    child.kill('SIGKILL');
+  } catch {
+    // The bounded liveness check below decides whether recovery is safe.
+  }
+  const deadline = Date.now() + 2_000;
+  while (Date.now() < deadline && isPidAlive(supervisorPid)) {
+    await delay(HUB_UPDATE_SUPERVISOR_HANDSHAKE_POLL_MS);
+  }
+  if (isPidAlive(supervisorPid)) {
+    throw new Error(
+      `Unclaimed Hub restart supervisor pid=${supervisorPid} could not be stopped; `
+      + 'the current launcher will remain alive and keep the unchanged Hub running.'
+    );
+  }
+}
+
+async function waitForHubRestartSupervisorClaim(child, expected) {
+  let exit = null;
+  let spawnError = null;
+  let spawned = false;
+  child.once('spawn', () => {
+    spawned = true;
+  });
+  child.once('error', error => {
+    spawnError = error;
+  });
+  child.once('exit', (code, signal) => {
+    exit = { code, signal };
+  });
+
+  const spawnDeadline = Date.now() + expected.timeoutMs;
+  while (!spawned && !spawnError && !exit && Date.now() < spawnDeadline) {
+    await delay(HUB_UPDATE_SUPERVISOR_HANDSHAKE_POLL_MS);
+  }
+  if (spawnError) {
+    throw new Error(`Hub restart supervisor spawn failed: ${spawnError.message}`);
+  }
+  if (!spawned) {
+    const detail = exit
+      ? `exited code=${exit.code ?? 'none'} signal=${exit.signal || 'none'}`
+      : `did not emit spawn within ${expected.timeoutMs}ms`;
+    throw new Error(`Hub restart supervisor ${detail} before claiming the handoff.`);
+  }
+
+  const supervisorPid = Number(child.pid || 0);
+  const claimDeadline = Date.now() + expected.timeoutMs;
+  let matchingClaimSince = 0;
+  while (Date.now() < claimDeadline) {
+    if (spawnError) {
+      throw new Error(`Hub restart supervisor failed before handoff: ${spawnError.message}`);
+    }
+    if (exit || !isPidAlive(supervisorPid)) {
+      throw new Error(
+        `Hub restart supervisor pid=${supervisorPid || 'unknown'} exited before handoff `
+        + `(code=${exit?.code ?? 'none'} signal=${exit?.signal || 'none'}).`
+      );
+    }
+    const claim = readJsonFile(expected.resultPath);
+    if (
+      claim?.operationId === expected.operationId
+      && claim?.stage === 'waiting-for-old-launcher'
+      && claim?.outcome === 'in-progress'
+      && Number(claim?.supervisorPid || 0) === supervisorPid
+      && Number(claim?.launcherPid || 0) === expected.launcherPid
+      && claim?.targetVersion === expected.targetVersion
+      && claim?.handoffToken === expected.handoffToken
+    ) {
+      if (!matchingClaimSince) matchingClaimSince = Date.now();
+      if (Date.now() - matchingClaimSince >= expected.stabilityMs) {
+        await delay(HUB_UPDATE_SUPERVISOR_HANDSHAKE_POLL_MS);
+        const stableClaim = readJsonFile(expected.resultPath);
+        if (
+          !exit
+          && isPidAlive(supervisorPid)
+          && stableClaim?.operationId === expected.operationId
+          && stableClaim?.stage === 'waiting-for-old-launcher'
+          && stableClaim?.outcome === 'in-progress'
+          && Number(stableClaim?.supervisorPid || 0) === supervisorPid
+          && Number(stableClaim?.launcherPid || 0) === expected.launcherPid
+          && stableClaim?.targetVersion === expected.targetVersion
+          && stableClaim?.handoffToken === expected.handoffToken
+        ) {
+          return stableClaim;
+        }
+        matchingClaimSince = 0;
+      }
+    } else {
+      matchingClaimSince = 0;
+    }
+    await delay(HUB_UPDATE_SUPERVISOR_HANDSHAKE_POLL_MS);
+  }
+  throw new Error(
+    `Hub restart supervisor pid=${supervisorPid || 'unknown'} did not atomically claim `
+    + `operation ${expected.operationId} within ${expected.timeoutMs}ms.`
+  );
+}
 
 function writeJsonAtomic(filePath, value) {
   if (!filePath) return;
   mkdirSync(dirname(filePath), { recursive: true });
+  const previous = readJsonFile(filePath);
+  if (!canClaimHubUpdateResult(previous, value)) {
+    throw new Error(
+      `Hub update result is owned by ${previous?.operationId || 'another operation'}; `
+      + `${value?.operationId || 'unknown'} cannot overwrite it.`
+    );
+  }
   const temporaryPath = `${filePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
   let renamed = false;
   try {
@@ -41,6 +278,12 @@ function writeJsonAtomic(filePath, value) {
       encoding: 'utf8',
       mode: 0o600
     });
+    const current = readJsonFile(filePath);
+    if (resultRevision(current) !== resultRevision(previous)) {
+      throw new Error(
+        `Hub update result ownership changed before ${value?.operationId || 'unknown'} could commit.`
+      );
+    }
     renameSync(temporaryPath, filePath);
     renamed = true;
   } finally {
@@ -793,8 +1036,8 @@ function resolveNpxInvocation(npxArgs) {
 function buildHubRestartBootstrapScript() {
   return [
     'const { execFile, spawn } = require("node:child_process");',
-    'const { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } = require("node:fs");',
-    'const { dirname } = require("node:path");',
+    'const { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } = require("node:fs");',
+    'const { dirname, join } = require("node:path");',
     'const net = require("node:net");',
     'const waitPid = Number(process.env.LIVEDESK_RESTART_WAIT_PID || 0);',
     'const previousRuntimePid = Number(process.env.LIVEDESK_RESTART_PREVIOUS_RUNTIME_PID || 0);',
@@ -802,9 +1045,17 @@ function buildHubRestartBootstrapScript() {
     'const resultPath = process.env.LIVEDESK_RESTART_RESULT_PATH || "";',
     'const operationId = process.env.LIVEDESK_RESTART_OPERATION_ID || `hub-update-${Date.now()}`;',
     'const startedAt = process.env.LIVEDESK_RESTART_STARTED_AT || new Date().toISOString();',
+    'const handoffToken = process.env.LIVEDESK_RESTART_HANDOFF_TOKEN || "";',
+    'const exitBeforeHandshakeOperationId = process.env.LIVEDESK_TEST_HUB_RESTART_EXIT_BEFORE_HANDSHAKE_OPERATION_ID || "";',
+    'const exitAfterHandshakeOperationId = process.env.LIVEDESK_TEST_HUB_RESTART_EXIT_AFTER_HANDSHAKE_OPERATION_ID || "";',
+    'const delayHandshakeOperationId = process.env.LIVEDESK_TEST_HUB_RESTART_DELAY_HANDSHAKE_OPERATION_ID || "";',
+    'const terminationFailureOperationId = process.env.LIVEDESK_TEST_HUB_RESTART_TERMINATION_FAILURE_OPERATION_ID || "";',
     'const log = message => { if (!logPath) return; try { appendFileSync(logPath, `[Hub restart] ${new Date().toISOString()} ${message}\\n`, "utf8"); } catch {} };',
-    'const readPreviousResult = () => { if (!resultPath) return null; try { const value = JSON.parse(readFileSync(resultPath, "utf8")); return value?.operationId === operationId ? value : null; } catch { return null; } };',
-    'const writeResult = (stage, details = {}) => { if (!resultPath) return; const now = new Date().toISOString(); const previous = readPreviousResult(); const value = { ...(previous || {}), operationId, stage, targetVersion: expectedVersion, fallbackVersion, previousRuntimePid, supervisorPid: process.pid, startedAt: previous?.startedAt || startedAt, updatedAt: now, ...details }; const temporaryPath = `${resultPath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`; let renamed = false; try { mkdirSync(dirname(resultPath), { recursive: true }); writeFileSync(temporaryPath, JSON.stringify(value, null, 2), { encoding: "utf8", mode: 0o600 }); renameSync(temporaryPath, resultPath); renamed = true; } catch (error) { log(`stage=result-write-failed resultStage=${stage} error=${error.message}`); } finally { if (!renamed) { try { rmSync(temporaryPath, { force: true }); } catch {} } } };',
+    'const readRawResult = () => { if (!resultPath) return null; try { return JSON.parse(readFileSync(resultPath, "utf8")); } catch { return null; } };',
+    'const ownershipError = actual => { const error = new Error(`Hub update ${operationId} was superseded by ${actual || "another operation"}.`); error.code = "LIVEDESK_HUB_UPDATE_SUPERSEDED"; return error; };',
+    'const assertResultOwnership = () => { const current = readRawResult(); if (current?.operationId && current.operationId !== operationId) throw ownershipError(current.operationId); if (current?.operationId === operationId && current?.handoffCancelled === true) throw ownershipError(`${operationId} (handoff cancelled)`); return current; };',
+    'const resultRevision = value => JSON.stringify([String(value?.operationId || ""), String(value?.stage || ""), String(value?.outcome || ""), String(value?.updatedAt || "")]);',
+    'const writeResult = (stage, details = {}) => { if (!resultPath) return; const now = new Date().toISOString(); const previous = assertResultOwnership(); const value = { ...(previous || {}), operationId, stage, targetVersion: expectedVersion, fallbackVersion, previousRuntimePid, launcherPid: waitPid, supervisorPid: process.pid, handoffToken, startedAt: previous?.startedAt || startedAt, updatedAt: now, ...details }; const temporaryPath = `${resultPath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`; let renamed = false; try { mkdirSync(dirname(resultPath), { recursive: true }); writeFileSync(temporaryPath, JSON.stringify(value, null, 2), { encoding: "utf8", mode: 0o600 }); const current = readRawResult(); if (resultRevision(current) !== resultRevision(previous)) throw ownershipError(current?.operationId); renameSync(temporaryPath, resultPath); renamed = true; } catch (error) { log(`stage=result-write-failed resultStage=${stage} error=${error.message}`); throw error; } finally { if (!renamed) { try { rmSync(temporaryPath, { force: true }); } catch {} } } };',
     'const isAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };',
     'const isGroupAlive = pid => { try { process.kill(-pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };',
     'const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));',
@@ -813,20 +1064,27 @@ function buildHubRestartBootstrapScript() {
     'const decodeArgs = name => JSON.parse(Buffer.from(process.env[name] || "", "base64").toString("utf8"));',
     'const primary = { command: process.env.LIVEDESK_RESTART_COMMAND || "", args: decodeArgs("LIVEDESK_RESTART_ARGS_BASE64") };',
     'const fallback = { command: process.env.LIVEDESK_RESTART_FALLBACK_COMMAND || "", args: decodeArgs("LIVEDESK_RESTART_FALLBACK_ARGS_BASE64") };',
+    'const fallbackCwd = process.env.LIVEDESK_RESTART_FALLBACK_CWD || process.env.LIVEDESK_UPDATE_ORIGINAL_CWD || "";',
     'const expectedVersion = process.env.LIVEDESK_RESTART_EXPECTED_VERSION || "";',
     'const fallbackVersion = process.env.LIVEDESK_RESTART_FALLBACK_VERSION || "";',
+    'const neutralCwd = process.env.LIVEDESK_RESTART_NEUTRAL_CWD || "";',
     'const healthBaseUrl = process.env.LIVEDESK_RESTART_HEALTH_URL || "http://127.0.0.1:5179";',
     'const remoteHost = process.env.LIVEDESK_RESTART_REMOTE_HOST || "127.0.0.1";',
     'const remotePort = Number(process.env.LIVEDESK_RESTART_REMOTE_PORT || 5197);',
     'const attemptLimit = numberFromEnv("LIVEDESK_RESTART_ATTEMPTS", 3, 1);',
-    'const healthTimeoutMs = numberFromEnv("LIVEDESK_RESTART_HEALTH_TIMEOUT_MS", 30000, 1000);',
+    'const configuredHealthTimeoutMs = numberFromEnv("LIVEDESK_RESTART_HEALTH_TIMEOUT_MS", 30000, 1000);',
+    'const healthTimeoutMs = terminationFailureOperationId === operationId ? numberFromEnv("LIVEDESK_TEST_HUB_RESTART_TERMINATION_HEALTH_TIMEOUT_MS", 1000, 250) : configuredHealthTimeoutMs;',
     'const pollMs = numberFromEnv("LIVEDESK_RESTART_HEALTH_POLL_MS", 250, 50);',
+    'const stabilityMs = numberFromEnv("LIVEDESK_RESTART_STABILITY_MS", 5000, 5000);',
+    'const prepareNeutralCwd = () => { if (!neutralCwd) throw new Error("LiveDesk Hub update neutral working directory is unavailable"); mkdirSync(neutralCwd, { recursive: true }); for (let ancestor = neutralCwd; ; ancestor = dirname(ancestor)) { const shadow = [join(ancestor, "package.json"), join(ancestor, "node_modules", "livedesk", "package.json")].find(existsSync); if (shadow) throw new Error(`LiveDesk Hub update neutral working directory is shadowed by ${shadow}: ${neutralCwd}`); const parent = dirname(ancestor); if (parent === ancestor) break; } };',
+    'const buildLaunchEnv = () => { const env = { ...process.env }; const isolated = new Set(["init_cwd", "npm_config_local_prefix", "npm_config_workspace", "npm_config_workspaces", "npm_config_include_workspace_root", "npm_package_json", "npm_lifecycle_event", "npm_lifecycle_script"]); for (const key of Object.keys(env)) if (isolated.has(key.toLowerCase())) delete env[key]; env.INIT_CWD = neutralCwd; env.npm_config_local_prefix = neutralCwd; env.npm_config_include_workspace_root = "false"; return env; };',
     'const requestJson = async path => { const response = await fetch(new URL(path, healthBaseUrl), { cache: "no-store", signal: AbortSignal.timeout(Math.min(2000, healthTimeoutMs)) }); if (!response.ok) throw new Error(`HTTP ${response.status} from ${path}`); return response.json(); };',
     'const probeRemotePort = () => new Promise((resolve, reject) => { const socket = net.createConnection({ host: remoteHost, port: remotePort }); const timer = setTimeout(() => socket.destroy(new Error("TCP probe timed out")), Math.min(1500, healthTimeoutMs)); timer.unref?.(); socket.once("connect", () => { clearTimeout(timer); socket.destroy(); resolve(); }); socket.once("error", error => { clearTimeout(timer); reject(error); }); });',
     'const probeReplacement = async requiredVersion => { const [status, health] = await Promise.all([requestJson("/api/runtime/status"), requestJson("/api/health")]); const runtimePid = Number(status?.runtimePid || 0); if (status?.role !== "hub" || status?.runtimeStarted !== true || runtimePid <= 1) throw new Error("replacement runtime status is not ready"); if (previousRuntimePid > 1 && runtimePid === previousRuntimePid) throw new Error(`old runtime pid=${runtimePid} is still answering`); if (requiredVersion && String(status?.appVersion || "") !== requiredVersion) throw new Error(`version mismatch expected=${requiredVersion} actual=${status?.appVersion || "unknown"}`); if (health?.ok !== true || health?.product !== "LiveDesk") throw new Error("replacement health response is invalid"); await probeRemotePort(); return { runtimePid, appVersion: String(status?.appVersion || "") }; };',
-    'const terminateTree = async child => { const pid = Number(child?.pid || 0); if (pid <= 1) return; log(`terminating unverified replacement pid=${pid}`); if (process.platform === "win32") { if (isAlive(pid)) await new Promise(resolve => execFile("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { windowsHide: true }, () => resolve())); await sleep(250); return; } try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} } const gracefulDeadline = Date.now() + 2000; while (Date.now() < gracefulDeadline && (isGroupAlive(pid) || isAlive(pid))) await sleep(100); if (isGroupAlive(pid) || isAlive(pid)) { log(`unverified replacement pid=${pid} ignored SIGTERM; sending SIGKILL to process group`); try { process.kill(-pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} } const hardDeadline = Date.now() + 1000; while (Date.now() < hardDeadline && (isGroupAlive(pid) || isAlive(pid))) await sleep(100); } };',
-    'const launchAndVerify = async (invocation, label, requiredVersion, attempt) => { if (!invocation.command || !Array.isArray(invocation.args)) throw new Error(`${label} restart command is unavailable`); log(`${label} attempt=${attempt} stage=spawning command=${invocation.command} target=${requiredVersion || "latest"}`); let exit = null; let exitedAt = 0; const child = spawn(invocation.command, invocation.args, { cwd: process.env.LIVEDESK_RESTART_CWD || process.cwd(), env: process.env, detached: true, stdio: "ignore", windowsHide: true }); await new Promise((resolve, reject) => { child.once("error", reject); child.once("spawn", resolve); }); log(`${label} attempt=${attempt} stage=spawned pid=${child.pid || 0}`); child.once("exit", (code, signal) => { exit = { code, signal }; exitedAt = Date.now(); log(`${label} attempt=${attempt} stage=exited code=${code ?? "none"} signal=${signal || "none"}`); }); const deadline = Date.now() + healthTimeoutMs; let lastError = null; while (Date.now() < deadline) { try { const status = await probeReplacement(requiredVersion); log(`${label} attempt=${attempt} stage=verified launcherPid=${child.pid || 0} runtimePid=${status.runtimePid} version=${status.appVersion || "unknown"} http=${healthBaseUrl} remote=${remoteHost}:${remotePort}`); child.unref(); return { ...status, launcherPid: Number(child.pid || 0) }; } catch (error) { lastError = error; } if (exit && Date.now() - exitedAt >= 1500) break; await sleep(pollMs); } await terminateTree(child); throw new Error(`${label} attempt=${attempt} did not become healthy: ${lastError?.message || (exit ? `command exited code=${exit.code ?? "none"} signal=${exit.signal || "none"}` : "health deadline expired")}`); };',
-    '(async () => { const targetErrors = []; const fallbackErrors = []; writeResult("waiting-for-old-launcher", { outcome: "in-progress" }); log(`stage=waiting-for-old-launcher pid=${waitPid}`); await waitForExit(waitPid, 60000); writeResult("old-launcher-exited", { outcome: "in-progress" }); log("stage=old-launcher-exited"); for (let attempt = 1; attempt <= attemptLimit; attempt += 1) { writeResult("target-attempt", { outcome: "in-progress", attempt }); try { const status = await launchAndVerify(primary, "target", expectedVersion, attempt); writeResult("updated", { outcome: "updated", attempt, runtimePid: status.runtimePid, launcherPid: status.launcherPid, appVersion: status.appVersion, completedAt: new Date().toISOString(), error: undefined }); log("stage=completed"); return; } catch (error) { targetErrors.push(error.message); writeResult("target-failed", { outcome: "in-progress", attempt, error: error.message }); log(`target attempt=${attempt} stage=failed error=${error.message}`); } } log(`stage=fallback-start target=${fallbackVersion || "current"}`); for (let attempt = 1; attempt <= 2; attempt += 1) { writeResult("fallback-attempt", { outcome: "in-progress", attempt, error: targetErrors.join(" | ") }); try { const status = await launchAndVerify(fallback, "fallback", fallbackVersion, attempt); writeResult("restored", { outcome: "restored", attempt, runtimePid: status.runtimePid, launcherPid: status.launcherPid, appVersion: status.appVersion, completedAt: new Date().toISOString(), error: `Target Hub ${expectedVersion || "latest"} failed verification: ${targetErrors.join(" | ")}` }); log("stage=completed-with-fallback"); return; } catch (error) { fallbackErrors.push(error.message); writeResult("fallback-failed", { outcome: "in-progress", attempt, error: [...targetErrors, ...fallbackErrors].join(" | ") }); log(`fallback attempt=${attempt} stage=failed error=${error.message}`); } } throw new Error(`No verified LiveDesk Hub replacement could be started. Target failures: ${targetErrors.join(" | ") || "none"}. Fallback failures: ${fallbackErrors.join(" | ") || "none"}. Inspect ${logPath || "the Hub restart log"} and start livedesk@latest manually.`); })().catch(error => { writeResult("failed", { outcome: "failed", completedAt: new Date().toISOString(), error: error.message }); log("stage=bootstrap-failed error=" + error.message); process.exitCode = 1; });',
+    'const terminationError = (pid, detail) => { const error = new Error(`Unverified replacement pid=${pid} could not be terminated${detail ? `: ${detail}` : ""}`); error.code = "LIVEDESK_HUB_RESTART_TERMINATION_FAILED"; return error; };',
+    'const terminateTree = async (child, runtimePid = 0) => { const pid = Number(child?.pid || 0); const observedRuntimePid = Number(runtimePid || 0); if (pid <= 1) return; const rootsAlive = () => isAlive(pid) || (observedRuntimePid > 1 && isAlive(observedRuntimePid)); log(`terminating unverified replacement pid=${pid} runtimePid=${observedRuntimePid || 0}`); if (process.platform === "win32") { let taskkillError = null; if (terminationFailureOperationId === operationId) { taskkillError = new Error("simulated taskkill no-op"); } else if (rootsAlive()) { await new Promise(resolve => execFile("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: 10000, killSignal: "SIGKILL" }, error => { taskkillError = error || null; resolve(); })); } const deadline = Date.now() + 2000; while (Date.now() < deadline && rootsAlive()) await sleep(100); if (rootsAlive()) throw terminationError(pid, taskkillError?.message || `launcher/runtime still alive after taskkill (${observedRuntimePid || "no runtime pid"})`); return; } if (terminationFailureOperationId !== operationId) { try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} } } const gracefulDeadline = Date.now() + 2000; while (Date.now() < gracefulDeadline && (isGroupAlive(pid) || rootsAlive())) await sleep(100); if (isGroupAlive(pid) || rootsAlive()) { if (terminationFailureOperationId !== operationId) { log(`unverified replacement pid=${pid} ignored SIGTERM; sending SIGKILL to process group`); try { process.kill(-pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} } } const hardDeadline = Date.now() + 1000; while (Date.now() < hardDeadline && (isGroupAlive(pid) || rootsAlive())) await sleep(100); } if (isGroupAlive(pid) || rootsAlive()) throw terminationError(pid, `launcher/process group/runtime still alive (${observedRuntimePid || "no runtime pid"})`); };',
+    'const launchAndVerify = async (invocation, label, requiredVersion, attempt) => { if (!invocation.command || !Array.isArray(invocation.args)) throw new Error(`${label} restart command is unavailable`); const isFallback = label === "fallback"; if (!isFallback) prepareNeutralCwd(); const launchCwd = isFallback ? fallbackCwd : neutralCwd; if (!launchCwd) throw new Error(`${label} restart working directory is unavailable`); const launchEnv = isFallback ? { ...process.env } : buildLaunchEnv(); assertResultOwnership(); log(`${label} attempt=${attempt} stage=spawning command=${invocation.command} target=${requiredVersion || "current"} cwd=${launchCwd}`); let exit = null; let lastRuntimePid = 0; let stableRuntimePid = 0; let stableSince = 0; const child = spawn(invocation.command, invocation.args, { cwd: launchCwd, env: launchEnv, detached: true, stdio: "ignore", windowsHide: true }); await new Promise((resolve, reject) => { child.once("error", reject); child.once("spawn", resolve); }); log(`${label} attempt=${attempt} stage=spawned pid=${child.pid || 0}`); child.once("exit", (code, signal) => { exit = { code, signal }; log(`${label} attempt=${attempt} stage=exited code=${code ?? "none"} signal=${signal || "none"}`); }); const deadline = Date.now() + healthTimeoutMs; let lastError = null; while (Date.now() < deadline) { try { assertResultOwnership(); if (exit || !isAlive(Number(child.pid || 0))) throw new Error(`launcher pid=${child.pid || 0} exited before stability proof`); const status = await probeReplacement(requiredVersion); lastRuntimePid = Number(status.runtimePid || 0); if (!isAlive(Number(child.pid || 0))) throw new Error(`launcher pid=${child.pid || 0} exited during stability proof`); if (!isAlive(lastRuntimePid)) throw new Error(`runtime pid=${lastRuntimePid || 0} exited during stability proof`); assertResultOwnership(); if (stableRuntimePid !== lastRuntimePid) { stableRuntimePid = lastRuntimePid; stableSince = Date.now(); log(`${label} attempt=${attempt} stage=stability-start launcherPid=${child.pid || 0} runtimePid=${lastRuntimePid} requiredMs=${stabilityMs}`); } if (Date.now() - stableSince >= stabilityMs) { log(`${label} attempt=${attempt} stage=verified launcherPid=${child.pid || 0} runtimePid=${status.runtimePid} version=${status.appVersion || "unknown"} stableMs=${Date.now() - stableSince} http=${healthBaseUrl} remote=${remoteHost}:${remotePort}`); child.unref(); return { ...status, launcherPid: Number(child.pid || 0) }; } } catch (error) { if (error?.code === "LIVEDESK_HUB_UPDATE_SUPERSEDED") { await terminateTree(child, lastRuntimePid); throw error; } lastError = error; stableRuntimePid = 0; stableSince = 0; } if (exit) break; await sleep(pollMs); } await terminateTree(child, lastRuntimePid); throw new Error(`${label} attempt=${attempt} did not remain healthy for ${stabilityMs}ms: ${lastError?.message || (exit ? `command exited code=${exit.code ?? "none"} signal=${exit.signal || "none"}` : "health deadline expired")}`); };',
+    '(async () => { const targetErrors = []; const fallbackErrors = []; if (exitBeforeHandshakeOperationId === operationId) { log("stage=test-exit-before-handshake"); process.exitCode = 86; return; } if (delayHandshakeOperationId === operationId) { const claimDelayMs = numberFromEnv("LIVEDESK_TEST_HUB_RESTART_HANDSHAKE_DELAY_MS", 2000, 1); log(`stage=test-delay-before-handshake delayMs=${claimDelayMs}`); await sleep(claimDelayMs); } writeResult("waiting-for-old-launcher", { outcome: "in-progress" }); log(`stage=waiting-for-old-launcher pid=${waitPid} supervisorPid=${process.pid}`); if (exitAfterHandshakeOperationId === operationId) { log("stage=test-exit-after-handshake"); process.exitCode = 87; return; } await waitForExit(waitPid, 60000); writeResult("old-launcher-exited", { outcome: "in-progress" }); log("stage=old-launcher-exited"); for (let attempt = 1; attempt <= attemptLimit; attempt += 1) { writeResult("target-attempt", { outcome: "in-progress", attempt }); try { const status = await launchAndVerify(primary, "target", expectedVersion, attempt); writeResult("updated", { outcome: "updated", attempt, runtimePid: status.runtimePid, launcherPid: status.launcherPid, appVersion: status.appVersion, completedAt: new Date().toISOString(), error: undefined }); log("stage=completed"); return; } catch (error) { if (["LIVEDESK_HUB_UPDATE_SUPERSEDED", "LIVEDESK_HUB_RESTART_TERMINATION_FAILED"].includes(error?.code)) throw error; targetErrors.push(error.message); writeResult("target-failed", { outcome: "in-progress", attempt, error: error.message }); log(`target attempt=${attempt} stage=failed error=${error.message}`); } } log(`stage=fallback-start target=${fallbackVersion || "current"}`); for (let attempt = 1; attempt <= 2; attempt += 1) { writeResult("fallback-attempt", { outcome: "in-progress", attempt, error: targetErrors.join(" | ") }); try { const status = await launchAndVerify(fallback, "fallback", fallbackVersion, attempt); writeResult("restored", { outcome: "restored", attempt, runtimePid: status.runtimePid, launcherPid: status.launcherPid, appVersion: status.appVersion, completedAt: new Date().toISOString(), error: `Target Hub ${expectedVersion} failed verification: ${targetErrors.join(" | ")}` }); log("stage=completed-with-fallback"); return; } catch (error) { if (["LIVEDESK_HUB_UPDATE_SUPERSEDED", "LIVEDESK_HUB_RESTART_TERMINATION_FAILED"].includes(error?.code)) throw error; fallbackErrors.push(error.message); writeResult("fallback-failed", { outcome: "in-progress", attempt, error: [...targetErrors, ...fallbackErrors].join(" | ") }); log(`fallback attempt=${attempt} stage=failed error=${error.message}`); } } throw new Error(`No verified LiveDesk Hub replacement could be started. Target failures: ${targetErrors.join(" | ") || "none"}. Fallback failures: ${fallbackErrors.join(" | ") || "none"}. Inspect ${logPath || "the Hub restart log"} and start the frozen local LiveDesk Hub manually.`); })().catch(error => { if (error?.code === "LIVEDESK_HUB_UPDATE_SUPERSEDED") { log("stage=bootstrap-superseded error=" + error.message); return; } try { writeResult("failed", { outcome: "failed", completedAt: new Date().toISOString(), error: error.message }); } catch (writeError) { log("stage=result-write-failed resultStage=failed error=" + writeError.message); } log("stage=bootstrap-failed error=" + error.message); process.exitCode = 1; });',
     ''
   ].join('\n');
 }
@@ -916,19 +1174,35 @@ async function runManager(args, resolvedRole = null) {
   let updateStopTimer = null;
   let updateHardStopTimer = null;
 
-  const restartWithLatest = request => {
-    const requestedVersion = /^[0-9A-Za-z][0-9A-Za-z.+-]*$/.test(String(request?.latestVersion || '').trim())
-      ? String(request.latestVersion).trim()
-      : '';
-    const packageTarget = requestedVersion ? `livedesk@${requestedVersion}` : 'livedesk@latest';
+  const restartWithLatest = async request => {
+    const requestedVersion = normalizeExactUpdateVersion(request?.latestVersion);
+    if (!requestedVersion) {
+      throw new Error('The Hub update target version must be one exact semantic version.');
+    }
+    const operationId = String(request?.operationId || `hub-update-${Date.now()}`).trim();
+    const originalCwd = String(
+      request?._originalCwd
+      || process.env.LIVEDESK_UPDATE_ORIGINAL_CWD
+      || process.cwd()
+    ).trim();
+    const neutralCwd = String(
+      request?._neutralCwd
+      || prepareUpdateNeutralCwd('hub', operationId)
+    );
+    const packageTarget = `livedesk@${requestedVersion}`;
     const nextArgs = ['-y', '--prefer-online', packageTarget, '--force-role', 'hub', '--no-open', ...args];
     const restartInvocation = resolveNpxInvocation(nextArgs);
     const fallbackInvocation = {
       command: process.execPath,
-      args: [String(process.argv[1] || resolve(__dirname, 'livedesk.js')), '--force-role', 'hub', '--no-open', ...args]
+      args: [resolve(String(process.argv[1] || resolve(__dirname, 'livedesk.js'))), '--force-role', 'hub', '--no-open', ...args]
     };
-    const operationId = String(request?.operationId || `hub-update-${Date.now()}`).trim();
     const restartStartedAt = new Date().toISOString();
+    const handoffToken = randomBytes(24).toString('hex');
+    const handshakeTimeoutMs = readBoundedMilliseconds(
+      process.env.LIVEDESK_RESTART_HANDSHAKE_TIMEOUT_MS,
+      HUB_UPDATE_SUPERVISOR_HANDSHAKE_TIMEOUT_MS,
+      250
+    );
     try {
       writeJsonAtomic(hubUpdateResultPath, {
         operationId,
@@ -938,19 +1212,23 @@ async function runManager(args, resolvedRole = null) {
         fallbackVersion: readVersion(),
         previousRuntimePid: Number(request?.pid || 0),
         launcherPid: process.pid,
+        handoffToken,
         startedAt: restartStartedAt,
         updatedAt: restartStartedAt
       });
     } catch (error) {
       reportLauncherUpdate(`[LiveDesk Hub] Could not persist the restart supervisor state: ${error instanceof Error ? error.message : String(error)}.`, true);
+      throw error;
     }
     const restartBootstrap = spawn(process.execPath, ['-e', buildHubRestartBootstrapScript()], {
+      cwd: neutralCwd,
       env: {
         ...process.env,
         LIVEDESK_RESTART_WAIT_PID: String(process.pid),
         LIVEDESK_RESTART_PREVIOUS_RUNTIME_PID: String(request?.pid || 0),
         LIVEDESK_RESTART_OPERATION_ID: operationId,
         LIVEDESK_RESTART_STARTED_AT: restartStartedAt,
+        LIVEDESK_RESTART_HANDOFF_TOKEN: handoffToken,
         LIVEDESK_RESTART_RESULT_PATH: hubUpdateResultPath,
         LIVEDESK_RESTART_COMMAND: restartInvocation.command,
         LIVEDESK_RESTART_ARGS_BASE64: Buffer.from(JSON.stringify(restartInvocation.args), 'utf8').toString('base64'),
@@ -961,39 +1239,49 @@ async function runManager(args, resolvedRole = null) {
         LIVEDESK_RESTART_HEALTH_URL: hubProbeBaseUrl,
         LIVEDESK_RESTART_REMOTE_HOST: '127.0.0.1',
         LIVEDESK_RESTART_REMOTE_PORT: String(remotePort),
-        LIVEDESK_RESTART_CWD: process.cwd(),
+        LIVEDESK_RESTART_NEUTRAL_CWD: neutralCwd,
+        LIVEDESK_RESTART_FALLBACK_CWD: originalCwd,
+        LIVEDESK_UPDATE_ORIGINAL_CWD: originalCwd,
         LIVEDESK_RESTART_LOG_PATH: hubLogPath
       },
       stdio: 'ignore',
-      detached: true,
-      windowsHide: true
+      detached: true,
+      windowsHide: true
     });
-    restartBootstrap.once('error', error => {
-      reportLauncherUpdate(`[LiveDesk Hub] Failed to start the update restart supervisor: ${error.message}. Restoring the current Hub.`, true);
+    try {
+      await waitForHubRestartSupervisorClaim(restartBootstrap, {
+        operationId,
+        targetVersion: requestedVersion,
+        resultPath: hubUpdateResultPath,
+        launcherPid: process.pid,
+        handoffToken,
+        timeoutMs: handshakeTimeoutMs,
+        stabilityMs: HUB_UPDATE_SUPERVISOR_CLAIM_STABILITY_MS
+      });
+    } catch (handshakeError) {
+      let stopError = null;
       try {
-        writeJsonAtomic(hubUpdateResultPath, {
-          operationId,
-          stage: 'failed',
-          outcome: 'failed',
-          targetVersion: requestedVersion,
-          fallbackVersion: readVersion(),
-          previousRuntimePid: Number(request?.pid || 0),
-          launcherPid: process.pid,
-          startedAt: restartStartedAt,
-          updatedAt: new Date().toISOString(),
-          completedAt: new Date().toISOString(),
-          error: `The Hub restart supervisor could not start: ${error.message}. The existing launcher restarted the unchanged Hub.`
-        });
-      } catch (persistError) {
-        reportLauncherUpdate(`[LiveDesk Hub] Could not persist the supervisor failure: ${persistError instanceof Error ? persistError.message : String(persistError)}.`, true);
+        await stopUnclaimedHubRestartSupervisor(restartBootstrap);
+      } catch (error) {
+        stopError = error;
       }
-      startHubProcess();
-    });
-    restartBootstrap.once('spawn', () => {
-      restartBootstrap.unref();
-      reportLauncherUpdate(`[LiveDesk Hub] Update handoff prepared target=${requestedVersion || 'latest'} supervisorPid=${restartBootstrap.pid || 0}. The current launcher will exit after its Hub stopped. Restart diagnostics: ${hubLogPath}`);
-      setTimeout(() => process.exit(0), 100);
-    });
+      const error = new Error(
+        `Hub restart supervisor handoff failed: `
+        + `${handshakeError instanceof Error ? handshakeError.message : String(handshakeError)}`
+        + `${stopError ? ` ${stopError.message}` : ''}`
+      );
+      error.supervisorPid = Number(restartBootstrap.pid || 0);
+      error.handoffToken = handoffToken;
+      error.handoffCancelled = true;
+      throw error;
+    }
+    restartBootstrap.unref();
+    reportLauncherUpdate(
+      `[LiveDesk Hub] Update handoff claimed target=${requestedVersion} `
+      + `supervisorPid=${restartBootstrap.pid || 0} operation=${operationId}. `
+      + `The current launcher will now exit. Restart diagnostics: ${hubLogPath}`
+    );
+    process.exit(0);
   };
 
   const pollUpdateRequest = () => {
@@ -1015,8 +1303,50 @@ async function runManager(args, resolvedRole = null) {
       } else if (requestPid !== activeChildPid) {
         reportLauncherUpdate(`[LiveDesk Hub] Ignored stale update restart request for pid ${requestPid}; active Hub pid is ${activeChildPid || 'unavailable'}.`, true);
       } else {
-        restartRequest = { ...request, pid: requestPid };
-        reportLauncherUpdate(`[LiveDesk Hub] Restart requested for update ${request.operationId || 'unknown'} target=${request.latestVersion || 'latest'}.`);
+        const operationId = String(request?.operationId || `hub-update-${Date.now()}`).trim();
+        const requestedVersion = normalizeExactUpdateVersion(request?.latestVersion);
+        const failPreflight = message => {
+          reportLauncherUpdate(`[LiveDesk Hub] ${message}. The current Hub remains running.`, true);
+          try {
+            const now = new Date().toISOString();
+            writeJsonAtomic(hubUpdateResultPath, {
+              operationId,
+              stage: 'preflight-failed',
+              outcome: 'failed',
+              targetVersion: String(request?.latestVersion || ''),
+              fallbackVersion: readVersion(),
+              previousRuntimePid: requestPid,
+              launcherPid: process.pid,
+              startedAt: now,
+              updatedAt: now,
+              completedAt: now,
+              error: message
+            });
+          } catch (persistError) {
+            reportLauncherUpdate(`[LiveDesk Hub] Could not persist the update preflight failure: ${persistError instanceof Error ? persistError.message : String(persistError)}.`, true);
+          }
+        };
+        if (!requestedVersion) {
+          failPreflight('Hub update preflight failed before shutdown: the requested target must be one exact semantic version');
+          return;
+        }
+        let neutralCwd;
+        try {
+          neutralCwd = prepareUpdateNeutralCwd('hub', operationId);
+        } catch (error) {
+          const message = `Hub update preflight failed before shutdown: ${error instanceof Error ? error.message : String(error)}`;
+          failPreflight(message);
+          return;
+        }
+        restartRequest = {
+          ...request,
+          latestVersion: requestedVersion,
+          pid: requestPid,
+          operationId,
+          _neutralCwd: neutralCwd,
+          _originalCwd: UPDATE_ORIGINAL_CWD
+        };
+        reportLauncherUpdate(`[LiveDesk Hub] Restart requested for update ${request.operationId || 'unknown'} target=${requestedVersion}.`);
         const updateChild = activeChild;
         let shutdownFallbackStarted = false;
         const forceStop = reason => {
@@ -1102,7 +1432,39 @@ async function runManager(args, resolvedRole = null) {
           clearInterval(updatePollId);
           updatePollId = null;
         }
-        restartWithLatest(request);
+        void restartWithLatest(request).catch(error => {
+          const message = `The Hub restart handoff failed after shutdown: ${error instanceof Error ? error.message : String(error)}`;
+          reportLauncherUpdate(`[LiveDesk Hub] ${message}. Restarting the unchanged Hub.`, true);
+          try {
+            const now = new Date().toISOString();
+            const previous = readJsonFile(hubUpdateResultPath);
+            writeJsonAtomic(hubUpdateResultPath, {
+              operationId: String(request?.operationId || ''),
+              stage: 'failed',
+              outcome: 'failed',
+              targetVersion: String(request?.latestVersion || ''),
+              fallbackVersion: readVersion(),
+              previousRuntimePid: Number(request?.pid || 0),
+              launcherPid: process.pid,
+              supervisorPid: Number(error?.supervisorPid || 0),
+              handoffToken: String(error?.handoffToken || previous?.handoffToken || ''),
+              handoffCancelled: error?.handoffCancelled === true,
+              startedAt: previous?.operationId === request?.operationId
+                ? (previous?.startedAt || now)
+                : now,
+              updatedAt: now,
+              completedAt: now,
+              error: message
+            });
+          } catch {
+            // The unchanged Hub still restarts even if diagnostics are read-only.
+          }
+          startHubProcess();
+          if (!updatePollId) {
+            updatePollId = setInterval(pollUpdateRequest, HUB_UPDATE_POLL_MS);
+            updatePollId.unref?.();
+          }
+        });
         return;
       }
       if (!signal && code === ROLE_TRANSITION_EXIT_CODE) {
@@ -1220,6 +1582,7 @@ async function runDesktopRoleBootstrap() {
 
 async function main() {
   const rawArgs = process.argv.slice(2);
+  restoreUpdateOriginalCwd();
   if (rawArgs.includes('--internal-legacy-client-update')) {
     await runLegacyClientUpdateSupervisorCli();
     return;