livedesk 0.1.384 → 0.1.385

package/bin/livedesk.js

@@ -5,7 +5,7 @@ import net from 'node:net';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { execFile, spawn } from 'node:child_process';
-import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import os from 'node:os';
 import { resolveDeviceRole, writeRoleCache } from '../bootstrap/device-role.js';
@@ -27,10 +27,29 @@ 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 MANAGER_STATE_PATH = join(MANAGER_STATE_DIR, 'manager.json');
-
-function printHelp() {
+const MANAGER_STATE_DIR = process.env.LIVEDESK_STATE_DIR || join(os.homedir(), '.livedesk');
+const MANAGER_STATE_PATH = join(MANAGER_STATE_DIR, 'manager.json');
+
+function writeJsonAtomic(filePath, value) {
+  if (!filePath) return;
+  mkdirSync(dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  let renamed = false;
+  try {
+    writeFileSync(temporaryPath, JSON.stringify(value, null, 2), {
+      encoding: 'utf8',
+      mode: 0o600
+    });
+    renameSync(temporaryPath, filePath);
+    renamed = true;
+  } finally {
+    if (!renamed) {
+      try { rmSync(temporaryPath, { force: true }); } catch { /* best effort cleanup */ }
+    }
+  }
+}
+
+function printHelp() {
   process.stdout.write(`
 LiveDesk
 
@@ -772,20 +791,44 @@ function resolveNpxInvocation(npxArgs) {
 
 function buildHubRestartBootstrapScript() {
   return [
-    'const { spawn } = require("node:child_process");',
-    'const { appendFileSync } = require("node:fs");',
+    'const { execFile, spawn } = require("node:child_process");',
+    'const { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } = require("node:fs");',
+    'const { dirname } = 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);',
     'const logPath = process.env.LIVEDESK_RESTART_LOG_PATH || "";',
+    '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 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 isAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };',
-    'const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));',
-    'const waitForExit = async pid => { for (let attempt = 0; attempt < 240 && pid > 1; attempt += 1) { if (!isAlive(pid)) return; await sleep(250); } if (pid > 1 && isAlive(pid)) throw new Error("Previous LiveDesk Hub launcher did not exit before restart."); };',
-    'const command = process.env.LIVEDESK_RESTART_COMMAND || "";',
-    'const args = JSON.parse(Buffer.from(process.env.LIVEDESK_RESTART_ARGS_BASE64 || "", "base64").toString("utf8"));',
-    '(async () => { log(`waiting for launcher pid=${waitPid}`); await waitForExit(waitPid); if (!command || !Array.isArray(args)) throw new Error("LiveDesk Hub restart command is unavailable."); log(`starting ${command}`); const next = spawn(command, args, { cwd: process.env.LIVEDESK_RESTART_CWD || process.cwd(), env: process.env, detached: true, stdio: "ignore", windowsHide: true }); await new Promise((resolve, reject) => { next.once("error", reject); next.once("spawn", () => { log(`spawned pid=${next.pid || 0}`); resolve(); }); }); next.once("exit", (code, signal) => log(`restart command exited code=${code ?? "none"} signal=${signal || "none"}`)); await sleep(1500); next.unref(); })().catch(error => { log("bootstrap failed: " + error.message); process.exitCode = 1; });',
-    ''
-  ].join('\n');
-}
+    '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));',
+    'const numberFromEnv = (name, fallback, minimum) => { const value = Number(process.env[name]); return Number.isFinite(value) && value >= minimum ? Math.round(value) : fallback; };',
+    'const waitForExit = async (pid, timeoutMs) => { const deadline = Date.now() + timeoutMs; while (pid > 1 && Date.now() < deadline) { if (!isAlive(pid)) return; await sleep(250); } if (pid > 1 && isAlive(pid)) throw new Error(`Previous LiveDesk Hub launcher pid=${pid} did not exit within ${timeoutMs}ms.`); };',
+    '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 expectedVersion = process.env.LIVEDESK_RESTART_EXPECTED_VERSION || "";',
+    'const fallbackVersion = process.env.LIVEDESK_RESTART_FALLBACK_VERSION || "";',
+    '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 pollMs = numberFromEnv("LIVEDESK_RESTART_HEALTH_POLL_MS", 250, 50);',
+    '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; });',
+    ''
+  ].join('\n');
+}
 
 async function runManager(args, resolvedRole = null) {
   const options = parseManagerArgs(args);
@@ -800,30 +843,42 @@ async function runManager(args, resolvedRole = null) {
   const openUrl = options.openUrlExplicit
     ? (options.openUrl || `http://127.0.0.1:${httpPort}`)
     : `http://127.0.0.1:${httpPort}`;
-  const pairToken = process.env.REMOTE_HUB_PAIR_TOKEN
-    || process.env.LIVEDESK_CLIENT_PAIR_TOKEN
-    || process.env.MINDEXEC_REMOTE_PAIR_TOKEN
-    || getStablePairToken();
-  mkdirSync(MANAGER_STATE_DIR, { recursive: true });
-  const updateRequestPath = join(MANAGER_STATE_DIR, `hub-update-${httpPort}-${remotePort}.json`);
-  rmSync(updateRequestPath, { force: true });
+  const pairToken = process.env.REMOTE_HUB_PAIR_TOKEN
+    || process.env.LIVEDESK_CLIENT_PAIR_TOKEN
+    || process.env.MINDEXEC_REMOTE_PAIR_TOKEN
+    || getStablePairToken();
+  const configuredHttpHost = options.host || process.env.LIVEDESK_HUB_HTTP_HOST || '127.0.0.1';
+  const normalizedHttpHost = String(configuredHttpHost).trim().replace(/^\[|\]$/g, '');
+  const hubProbeHost = normalizedHttpHost === '0.0.0.0'
+    ? '127.0.0.1'
+    : (normalizedHttpHost === '::' ? '::1' : normalizedHttpHost);
+  const hubProbeUrlHost = hubProbeHost.includes(':') ? `[${hubProbeHost}]` : hubProbeHost;
+  const hubProbeBaseUrl = `http://${hubProbeUrlHost}:${httpPort}`;
+  mkdirSync(MANAGER_STATE_DIR, { recursive: true });
+  const updateRequestPath = join(MANAGER_STATE_DIR, `hub-update-${httpPort}-${remotePort}.json`);
+  const hubUpdateResultPath = join(MANAGER_STATE_DIR, `hub-update-result-${httpPort}-${remotePort}.json`);
+  rmSync(updateRequestPath, { force: true });
 
   if (options.cleanPortsOnStart) {
     await stopProcessesOnPorts([httpPort, remotePort]);
   }
 
-  const internalHubEntry = resolve(packageRoot, 'hub', 'src', 'server.js');
-  const hubEntry = existsSync(internalHubEntry)
-    ? internalHubEntry
-    : resolvePackageEntry('@livedesk/hub', '@livedesk/hub/src/server.js');
+  const configuredHubEntry = String(process.env.LIVEDESK_HUB_ENTRY || '').trim();
+  const internalHubEntry = resolve(packageRoot, 'hub', 'src', 'server.js');
+  const hubEntry = configuredHubEntry && existsSync(configuredHubEntry)
+    ? configuredHubEntry
+    : (existsSync(internalHubEntry)
+      ? internalHubEntry
+      : resolvePackageEntry('@livedesk/hub', '@livedesk/hub/src/server.js'));
   const packagedWebDist = resolve(packageRoot, 'web', 'dist');
-  const env = {
-    ...process.env,
-    LIVEDESK_HUB_HTTP_HOST: options.host || process.env.LIVEDESK_HUB_HTTP_HOST || '127.0.0.1',
+  const env = {
+    ...process.env,
+    LIVEDESK_HUB_HTTP_HOST: configuredHttpHost,
     LIVEDESK_HUB_HTTP_PORT: String(httpPort),
-    LIVEDESK_MANAGER_VERSION: readVersion(),
-    LIVEDESK_CLIENT_PACKAGE_VERSION: readClientVersion(),
-    LIVEDESK_HUB_UPDATE_REQUEST_PATH: updateRequestPath,
+    LIVEDESK_MANAGER_VERSION: readVersion(),
+    LIVEDESK_CLIENT_PACKAGE_VERSION: readClientVersion(),
+    LIVEDESK_HUB_UPDATE_REQUEST_PATH: updateRequestPath,
+    LIVEDESK_HUB_UPDATE_RESULT_PATH: hubUpdateResultPath,
     REMOTE_HUB_PORT: String(remotePort),
     REMOTE_HUB_PAIR_TOKEN: pairToken,
     LIVEDESK_WEB_DIST: existsSync(resolve(packagedWebDist, 'index.html')) ? packagedWebDist : (process.env.LIVEDESK_WEB_DIST || ''),
@@ -854,35 +909,93 @@ async function runManager(args, resolvedRole = null) {
   };
 
   let startupRetryCount = 0;
-  let restartRequested = false;
-  let activeChild = null;
-  let updatePollId = null;
-
-  const restartWithLatest = () => {
-    const nextArgs = ['-y', '--prefer-online', 'livedesk@latest', '--force-role', 'hub', '--no-open', ...args];
+  let restartRequest = null;
+  let activeChild = null;
+  let updatePollId = 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 nextArgs = ['-y', '--prefer-online', packageTarget, '--force-role', 'hub', '--no-open', ...args];
     const restartInvocation = resolveNpxInvocation(nextArgs);
-    const restartBootstrap = spawn(process.execPath, ['-e', buildHubRestartBootstrapScript()], {
-      env: {
-        ...process.env,
-        LIVEDESK_RESTART_WAIT_PID: String(process.pid),
+    const fallbackInvocation = {
+      command: process.execPath,
+      args: [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();
+    try {
+      writeJsonAtomic(hubUpdateResultPath, {
+        operationId,
+        stage: 'supervisor-starting',
+        outcome: 'in-progress',
+        targetVersion: requestedVersion,
+        fallbackVersion: readVersion(),
+        previousRuntimePid: Number(request?.pid || 0),
+        launcherPid: process.pid,
+        startedAt: restartStartedAt,
+        updatedAt: restartStartedAt
+      });
+    } catch (error) {
+      reportLauncherUpdate(`[LiveDesk Hub] Could not persist the restart supervisor state: ${error instanceof Error ? error.message : String(error)}.`, true);
+    }
+    const restartBootstrap = spawn(process.execPath, ['-e', buildHubRestartBootstrapScript()], {
+      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_RESULT_PATH: hubUpdateResultPath,
         LIVEDESK_RESTART_COMMAND: restartInvocation.command,
         LIVEDESK_RESTART_ARGS_BASE64: Buffer.from(JSON.stringify(restartInvocation.args), 'utf8').toString('base64'),
+        LIVEDESK_RESTART_FALLBACK_COMMAND: fallbackInvocation.command,
+        LIVEDESK_RESTART_FALLBACK_ARGS_BASE64: Buffer.from(JSON.stringify(fallbackInvocation.args), 'utf8').toString('base64'),
+        LIVEDESK_RESTART_EXPECTED_VERSION: requestedVersion,
+        LIVEDESK_RESTART_FALLBACK_VERSION: readVersion(),
+        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_LOG_PATH: hubLogPath
-      },
+      },
       stdio: 'ignore',
       detached: true,
       windowsHide: true
-    });
-    restartBootstrap.once('error', error => {
-      console.error(`Failed to prepare LiveDesk Hub restart: ${error.message}`);
-    });
-    restartBootstrap.once('spawn', () => restartBootstrap.unref());
-    reportLauncherUpdate('[LiveDesk Hub] Update approved. The current Hub launcher is exiting and the latest Hub will start automatically.');
-    setTimeout(() => process.exit(0), 100);
-  };
+    });
+    restartBootstrap.once('error', error => {
+      reportLauncherUpdate(`[LiveDesk Hub] Failed to start the update restart supervisor: ${error.message}. Restoring the current Hub.`, true);
+      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);
+      }
+      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 pollUpdateRequest = () => {
+  const pollUpdateRequest = () => {
     if (!existsSync(updateRequestPath)) return;
     try {
       const request = JSON.parse(readFileSync(updateRequestPath, 'utf8'));
@@ -901,12 +1014,41 @@ 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 {
-        restartRequested = true;
-        reportLauncherUpdate(`[LiveDesk Hub] Restart requested for update ${request.operationId || 'unknown'}.`);
-        if (activeChild && !activeChild.killed) {
-          activeChild.kill('SIGTERM');
-        }
-      }
+        restartRequest = { ...request, pid: requestPid };
+        reportLauncherUpdate(`[LiveDesk Hub] Restart requested for update ${request.operationId || 'unknown'} target=${request.latestVersion || 'latest'}.`);
+        const updateChild = activeChild;
+        let shutdownFallbackStarted = false;
+        const forceStop = reason => {
+          if (!updateChild || updateChild.exitCode !== null || updateChild.signalCode) return;
+          if (shutdownFallbackStarted) return;
+          shutdownFallbackStarted = true;
+          reportLauncherUpdate(`[LiveDesk Hub] Update shutdown fallback: ${reason}; terminating Hub pid=${requestPid}.`, true);
+          try { updateChild.kill('SIGTERM'); } catch { /* child already exited */ }
+          updateHardStopTimer = setTimeout(() => {
+            if (!updateChild || updateChild.exitCode !== null || updateChild.signalCode) return;
+            reportLauncherUpdate(`[LiveDesk Hub] Update shutdown hard fallback: Hub pid=${requestPid} ignored graceful termination; force-stopping its process tree.`, true);
+            if (process.platform === 'win32') {
+              execFile('taskkill.exe', ['/PID', String(requestPid), '/T', '/F'], { windowsHide: true }, error => {
+                if (error && updateChild.exitCode === null && !updateChild.signalCode) {
+                  reportLauncherUpdate(`[LiveDesk Hub] taskkill fallback failed for pid=${requestPid}: ${error.message}`, true);
+                }
+              });
+            } else {
+              try { updateChild.kill('SIGKILL'); } catch { /* child already exited */ }
+            }
+          }, 3_000);
+          updateHardStopTimer.unref?.();
+        };
+        updateStopTimer = setTimeout(() => forceStop('graceful shutdown exceeded 10 seconds'), 10_000);
+        updateStopTimer.unref?.();
+        void fetch(`${hubProbeBaseUrl}/api/runtime/shutdown`, {
+          method: 'POST',
+          signal: AbortSignal.timeout(2_500)
+        }).then(response => {
+          if (!response.ok) throw new Error(`HTTP ${response.status}`);
+          reportLauncherUpdate(`[LiveDesk Hub] Update shutdown acknowledged by Hub pid=${requestPid}.`);
+        }).catch(error => forceStop(`shutdown API failed (${error?.message || error})`));
+      }
     } catch {
       // The Hub writes the request atomically; a partial/stale file is retried.
     }
@@ -941,18 +1083,27 @@ async function runManager(args, resolvedRole = null) {
     child.once('error', error => {
       console.error(`Failed to start LiveDesk Hub: ${error.message}`);
       process.exitCode = 1;
-    });
-    child.once('exit', (code, signal) => {
-      const startupOutput = stderrChunks.join('');
-      if (restartRequested) {
-        restartRequested = false;
-        if (updatePollId) {
-          clearInterval(updatePollId);
-          updatePollId = null;
-        }
-        restartWithLatest();
-        return;
-      }
+    });
+    child.once('exit', (code, signal) => {
+      const startupOutput = stderrChunks.join('');
+      if (restartRequest) {
+        const request = restartRequest;
+        restartRequest = null;
+        if (updateStopTimer) {
+          clearTimeout(updateStopTimer);
+          updateStopTimer = null;
+        }
+        if (updateHardStopTimer) {
+          clearTimeout(updateHardStopTimer);
+          updateHardStopTimer = null;
+        }
+        if (updatePollId) {
+          clearInterval(updatePollId);
+          updatePollId = null;
+        }
+        restartWithLatest(request);
+        return;
+      }
       if (!signal && code === ROLE_TRANSITION_EXIT_CODE) {
         if (updatePollId) {
           clearInterval(updatePollId);