@livedesk/hub 0.1.4 → 0.1.6

package/src/live-desk-update.js

@@ -1,147 +1,142 @@
-import { randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 
-export const LIVE_DESK_UPDATE_COMMAND = 'livedesk.client-update';
-// 0.1.143 contains the launcher-PID-aware updater. Older clients use the
-// Hub-generated legacy command so they can still be upgraded safely.
-export const LIVE_DESK_DEDICATED_CLIENT_UPDATE_MIN_VERSION = '0.1.143';
-export const LIVE_DESK_UPDATE_TIMEOUT_MS = 180_000;
-export const LIVE_DESK_UPDATE_CHECK_INTERVAL_MS = 60_000;
+export const LIVE_DESK_UPDATE_COMMAND = 'livedesk.client-update';
+// 0.1.172 delegates to the exact-version, identity-preserving package
+// supervisor. 0.1.171 still lacks bounded handoff cancellation, so it must
+// use the Hub-owned compatibility bridge too.
+// Older dedicated handlers can spawn the new package but cannot prove that the
+// same device returned, so the Hub-owned compatibility bridge upgrades them.
+export const LIVE_DESK_DEDICATED_CLIENT_UPDATE_MIN_VERSION = '0.1.172';
+export const LIVE_DESK_UPDATE_CLIENT_BATCH_SIZE = 5;
+export const LIVE_DESK_UPDATE_TARGET_TIMEOUT_MS = 480_000;
+export const LIVE_DESK_UPDATE_TIMEOUT_MS = 90 * 60_000;
+export const LIVE_DESK_UPDATE_CLIENT_RESTART_STABILITY_MS = 60_000;
+export const LIVE_DESK_UPDATE_CHECK_INTERVAL_MS = 60_000;
+export const LIVE_DESK_LEGACY_COMMAND_MAX_LENGTH = 3900;
 
-function cleanVersion(value) {
-  return String(value || '').trim().replace(/^v/i, '');
-}
-
-export function compareVersions(left, right) {
-  const a = cleanVersion(left).split(/[+-]/, 1)[0].split('.').map(part => Number(part) || 0);
-  const b = cleanVersion(right).split(/[+-]/, 1)[0].split('.').map(part => Number(part) || 0);
-  const length = Math.max(a.length, b.length, 3);
-  for (let index = 0; index < length; index += 1) {
-    const difference = (a[index] || 0) - (b[index] || 0);
-    if (difference !== 0) return difference;
-  }
-  return 0;
+function cleanVersion(value) {
+  return String(value || '').trim().replace(/^v/i, '');
+}
+
+function parseVersion(value) {
+  const cleaned = cleanVersion(value);
+  const match = cleaned.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split('.') : []
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) return 0;
+  if (left.length === 0) return 1;
+  if (right.length === 0) return -1;
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left[index] === undefined) return -1;
+    if (right[index] === undefined) return 1;
+    const leftNumeric = /^\d+$/.test(left[index]);
+    const rightNumeric = /^\d+$/.test(right[index]);
+    if (leftNumeric && rightNumeric) {
+      const difference = Number(left[index]) - Number(right[index]);
+      if (difference !== 0) return difference;
+      continue;
+    }
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    const difference = left[index].localeCompare(right[index], 'en');
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+export function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (!a || !b) return cleanVersion(left).localeCompare(cleanVersion(right), 'en');
+  for (let index = 0; index < 3; index += 1) {
+    const difference = a.core[index] - b.core[index];
+    if (difference !== 0) return difference;
+  }
+  return comparePrerelease(a.prerelease, b.prerelease);
 }
 
 export function isVersionAtLeast(candidate, required) {
   return !!cleanVersion(candidate) && !!cleanVersion(required) && compareVersions(candidate, required) >= 0;
 }
 
-function encodePowerShell(value) {
-  return Buffer.from(String(value || ''), 'utf16le').toString('base64');
-}
-
-function quotePowerShell(value) {
-  return `'${String(value ?? '').replaceAll("'", "''")}'`;
-}
-
-function buildWindowsLegacyUpdateCommand({ manager, pair, name, slot, targetVersion }) {
-  const script = [
-    '$ErrorActionPreference = "Stop"',
-    '$cursor = Get-CimInstance Win32_Process -Filter ("ProcessId={0}" -f $PID)',
-    '$launcherPid = 0',
-    '$configuredLauncherPid = 0',
-    'if ([int]::TryParse([string]$env:LIVEDESK_CLIENT_PARENT_PID, [ref]$configuredLauncherPid) -and $configuredLauncherPid -gt 1) { try { Get-Process -Id $configuredLauncherPid -ErrorAction Stop | Out-Null; $launcherPid = $configuredLauncherPid } catch {} }',
-    'if ($launcherPid -le 0) {',
-    '  for ($depth = 0; $depth -lt 12 -and $cursor; $depth++) {',
-    '    $parent = Get-CimInstance Win32_Process -Filter ("ProcessId={0}" -f [int]$cursor.ParentProcessId)',
-    '    if (-not $parent) { break }',
-    '    $commandLine = [string]$parent.CommandLine',
-    '    if ($commandLine -match "(?i)(livedesk-client\\.js|livedesk\\.js)") { $launcherPid = [int]$parent.ProcessId; break }',
-    '    $cursor = $parent',
-    '  }',
-    '}',
-    'if ($launcherPid -le 0) { throw "LiveDesk client launcher process was not found." }',
-    `$env:LIVEDESK_CLIENT_MANAGER = ${quotePowerShell(manager)}`,
-    `$env:LIVEDESK_CLIENT_PAIR_TOKEN = ${quotePowerShell(pair)}`,
-    `$env:LIVEDESK_CLIENT_NAME = ${quotePowerShell(name)}`,
-    `$env:LIVEDESK_CLIENT_SLOT = ${quotePowerShell(slot || '')}`,
-    `$env:LIVEDESK_CLIENT_UPDATE_TARGET_VERSION = ${quotePowerShell(targetVersion)}`,
-    '$node = [string]$env:LIVEDESK_NODE_EXECUTABLE',
-    'if ($node -and -not (Test-Path -LiteralPath $node -PathType Leaf)) { $node = "" }',
-    'if (-not $node) { $node = (Get-Command node.exe -ErrorAction SilentlyContinue).Source }',
-    'if (-not $node) { throw "LiveDesk node executable was not found." }',
-    `$env:LIVEDESK_UPDATE_BOOTSTRAP_BASE64 = ${quotePowerShell(Buffer.from(buildUnixClientUpdateBootstrapScript(), 'utf8').toString('base64'))}`,
-    '$env:LIVEDESK_UPDATE_WAIT_PID = [string]$launcherPid',
-    '$env:LIVEDESK_UPDATE_AGENT_PID = "0"',
-    '$bootstrapRunner = "eval(Buffer.from(process.env.LIVEDESK_UPDATE_BOOTSTRAP_BASE64, \'base64\').toString(\'utf8\'))"',
-    'Start-Process -FilePath $node -ArgumentList @("-e", $bootstrapRunner) -WindowStyle Hidden',
-    'Start-Sleep -Milliseconds 750',
-    'Start-Process -FilePath "taskkill.exe" -ArgumentList @("/PID", [string]$launcherPid, "/T", "/F") -WindowStyle Hidden',
-    ''
-  ].join('\r\n');
-  return `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodePowerShell(script)}`;
-}
-
-function buildUnixClientUpdateBootstrapScript() {
-  return [
-    'const { spawn } = require("node:child_process");',
-    'const fs = require("node:fs");',
-    'const path = require("node:path");',
-    'const waitPid = Number(process.env.LIVEDESK_UPDATE_WAIT_PID || 0);',
-    'const agentPid = Number(process.env.LIVEDESK_UPDATE_AGENT_PID || 0);',
-    '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 < 360 && pid > 1; attempt += 1) { if (!isAlive(pid)) return; await sleep(500); } if (pid > 1 && isAlive(pid)) throw new Error("LiveDesk client process did not exit before update installation."); };',
-    'const nodeDir = path.dirname(process.execPath);',
-    'const npxCandidates = process.platform === "win32" ? [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeDir, "npx.cmd"), path.join(nodeDir, "npx.exe"), "npx.cmd"] : [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeDir, "npx"), "npx"];',
-    'const npx = npxCandidates.find(candidate => !path.isAbsolute(candidate) || fs.existsSync(candidate)) || npxCandidates[npxCandidates.length - 1];',
-    'const npmExecPath = String(process.env.npm_execpath || process.env.NPM_EXECPATH || "").trim();',
-    'const npxCliCandidates = [process.env.LIVEDESK_NPX_CLI_PATH, npmExecPath ? path.join(path.dirname(npmExecPath), "npx-cli.js") : "", path.join(nodeDir, "node_modules", "npm", "bin", "npx-cli.js")].filter(Boolean);',
-    'const npxCli = npxCliCandidates.find(candidate => fs.existsSync(candidate));',
-    'const npxArgs = ["-y", "--prefer-online", "livedesk@latest", "--force-role", "client", "--no-login", "--no-open"];',
-    'const command = npxCli ? process.execPath : (process.platform === "win32" ? (process.env.ComSpec || "cmd.exe") : npx);',
-    'const commandArgs = npxCli ? [npxCli, ...npxArgs] : (process.platform === "win32" ? ["/d", "/s", "/c", "call \\"" + npx + "\\" " + npxArgs.join(" ")] : npxArgs);',
-    'process.env.LIVEDESK_SKIP_BROWSER_OPEN = "1";',
-    '(async () => { await waitForExit(waitPid); await waitForExit(agentPid); const updater = spawn(command, commandArgs, { detached: true, stdio: "ignore", windowsHide: true, env: process.env }); updater.once("error", error => { console.error("LiveDesk updater failed to start: " + error.message); process.exitCode = 1; }); updater.once("spawn", () => updater.unref()); })().catch(error => { console.error("LiveDesk updater failed: " + error.message); process.exitCode = 1; });',
-    ''
-  ].join('\n');
-}
-
-function buildUnixLegacyUpdateCommand({ manager, pair, name, slot, targetVersion }) {
-  const script = [
-    'const { execFileSync, spawn } = require("node:child_process");',
-    'const fs = require("node:fs");',
-    'const path = require("node:path");',
-    'const parentOf = pid => { try { return Number(execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" }).trim()) || 0; } catch { return 0; } };',
-    'const commandOf = pid => { try { return execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8" }); } catch { return ""; } };',
-    'const isAlive = pid => { try { process.kill(pid, 0); return true; } catch { return false; } };',
-    'const configuredLauncherPid = Number(process.env.LIVEDESK_CLIENT_PARENT_PID || 0);',
-    'let launcherPid = Number.isInteger(configuredLauncherPid) && configuredLauncherPid > 1 && isAlive(configuredLauncherPid) ? configuredLauncherPid : 0;',
-    'let agentPid = Number(process.env.LIVEDESK_CLIENT_AGENT_PID || 0);',
-    'let cursor = parentOf(process.pid);',
-    'for (let depth = 0; depth < 12 && cursor; depth++) { const command = commandOf(cursor); if (!agentPid && /livedesk-client-node\\.js|livedesk-client-fast|RemoteAgent\\.Fast/i.test(command)) agentPid = cursor; if (!launcherPid && /livedesk-client\\.js|livedesk\\.js/i.test(command)) launcherPid = cursor; cursor = parentOf(cursor); }',
-    'if (launcherPid <= 1) throw new Error("LiveDesk client launcher process was not found.");',
-    'const waitPid = launcherPid;',
-    `process.env.LIVEDESK_CLIENT_MANAGER = ${JSON.stringify(String(manager || ''))};`,
-    `process.env.LIVEDESK_CLIENT_PAIR_TOKEN = ${JSON.stringify(String(pair || ''))};`,
-    `process.env.LIVEDESK_CLIENT_NAME = ${JSON.stringify(String(name || ''))};`,
-    `process.env.LIVEDESK_CLIENT_SLOT = ${JSON.stringify(String(slot || ''))};`,
-    `process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION = ${JSON.stringify(String(targetVersion || ''))};`,
-    `const bootstrapScript = ${JSON.stringify(buildUnixClientUpdateBootstrapScript())};`,
-    'const bootstrapEnv = { ...process.env, LIVEDESK_UPDATE_WAIT_PID: String(waitPid), LIVEDESK_UPDATE_AGENT_PID: String(agentPid) };',
-    'const updater = spawn(process.execPath, ["-e", bootstrapScript], { detached: true, stdio: "ignore", env: bootstrapEnv });',
-    'updater.once("error", error => { console.error("LiveDesk updater bootstrap failed to start: " + error.message); process.exitCode = 1; });',
-    'updater.once("spawn", () => { updater.unref(); setTimeout(() => { try { process.kill(waitPid, "SIGTERM"); } catch {} if (agentPid > 1 && agentPid !== process.pid) setTimeout(() => { try { process.kill(agentPid, "SIGTERM"); } catch {} }, 500); }, 750); });',
-    ''
-  ].join('\n');
-  return [
-    'if [ -n "$LIVEDESK_NODE_EXECUTABLE" ]; then node_bin="$LIVEDESK_NODE_EXECUTABLE"; else node_bin="$(ps -p "$LIVEDESK_CLIENT_PARENT_PID" -o comm= 2>/dev/null | sed "s/^ *//")"; if [ -z "$node_bin" ]; then node_bin="node"; fi; fi',
-    `"$node_bin" -e ${JSON.stringify(script)}`
-  ].join('\n');
-}
-
-function buildLegacyUpdateCommand(device, credentials, targetVersion) {
-  const payload = {
-    manager: credentials.manager,
-    pair: credentials.pairToken,
-    name: device.deviceName || device.hostname || '',
-    slot: device.slotNumber || '',
-    targetVersion
-  };
-  return ['win32', 'windows'].includes(String(device.platform || '').toLowerCase())
-    ? buildWindowsLegacyUpdateCommand(payload)
-    : buildUnixLegacyUpdateCommand(payload);
-}
+function encodePowerShell(value) {
+  return Buffer.from(String(value || ''), 'utf16le').toString('base64');
+}
+
+function buildLegacyPackageSupervisorStarterSource() {
+  const source = [
+    "const{spawn}=require('node:child_process'),f=require('node:fs'),p=require('node:path'),c=JSON.parse(Buffer.from(process.env.C,'base64')),e={...process.env,LIVEDESK_UPDATE_STARTER_PID:String(process.pid),LIVEDESK_UPDATE_ORIGINAL_CWD:process.cwd()},w=p.join(require('node:os').tmpdir(),'livedesk-update-cwd','client-'+c[0]),u=e.LIVEDESK_NPX_EXECUTABLE,s=process.platform,j=process.execPath,n=u||(s==='win32'?'npx.cmd':'npx'),x=[e.LIVEDESK_NPX_CLI_PATH,e.npm_execpath&&p.join(p.dirname(e.npm_execpath),'npx-cli.js'),u&&p.join(p.dirname(u),'node_modules/npm/bin/npx-cli.js'),p.join(p.dirname(j),'node_modules/npm/bin/npx-cli.js')].find(v=>v&&f.existsSync(v)),a=['-y','--prefer-online','livedesk@'+c[6],'--internal-legacy-client-update'],z=String.fromCharCode(32),q=v=>'\"'+String(v).replaceAll('\"','\"\"')+'\"';if(!(+c[7]>0))process.exit(1);c[7]=String(Date.now()+Number(c[7]));e.C=Buffer.from(JSON.stringify(c)).toString('base64');f.mkdirSync(w,{recursive:true});if(f.readdirSync(w)[0])process.exit(1);let/**/t=w;for(;;t=p.dirname(t)){if(['package.json','node_modules/livedesk/package.json'].some(v=>f.existsSync(p.join(t,v))))process.exit(1);if(p.dirname(t)===t)break}Object.keys(e).forEach(k=>/^(INIT_CWD|npm_config_(local_prefix|workspaces?|include_workspace_root))$/i.test(k)&&Reflect.deleteProperty(e,k));Object.assign(e,{INIT_CWD:w,npm_config_local_prefix:w,npm_config_include_workspace_root:'false',LIVEDESK_UPDATE_NEUTRAL_CWD:w});e.i=x?{c:j,a:[x,...a]}:s==='win32'?{c:e.ComSpec||'cmd.exe',a:['/d','/s','/c','call'+z+q(n)+z+a.map(q).join(z)]}:{c:n,a};e.r=spawn(e.i.c,e.i.a,{cwd:w,env:e,detached:true,stdio:'ignore',windowsHide:true});",
+    "e.r.on('error',()=>process.exit(1));e.r.unref();"
+  ].join('');
+  if (source.includes(' ')) throw new Error('LiveDesk legacy starter source must not contain spaces.');
+  return source;
+}
+
+function assertLegacyCommandLength(command, platform) {
+  if (command.length > LIVE_DESK_LEGACY_COMMAND_MAX_LENGTH) {
+    throw new Error(
+      `LiveDesk legacy ${platform} update command is ${command.length} characters; `
+      + `the compatibility limit is ${LIVE_DESK_LEGACY_COMMAND_MAX_LENGTH}.`
+    );
+  }
+  return command;
+}
+
+function buildLegacyPlatformCommand(platform, payload) {
+  const environment = [
+    String(payload.operationId || ''),
+    String(payload.deviceId || ''),
+    String(Number(payload.agentPid) || 0),
+    cleanVersion(payload.currentProductVersion),
+    cleanVersion(payload.currentAgentVersion),
+    cleanVersion(payload.targetVersion),
+    cleanVersion(payload.targetProductVersion),
+    String(Math.floor(Number(payload.updateTimeoutMs) || 0))
+  ];
+  const configBase64 = Buffer.from(JSON.stringify(environment), 'utf8').toString('base64');
+  const starter = buildLegacyPackageSupervisorStarterSource();
+  const starterBase64 = Buffer.from(starter, 'utf8').toString('base64');
+  const windows = ['win32', 'windows'].includes(String(platform || '').toLowerCase());
+  const powerShellStarter = [
+    "$ErrorActionPreference='Stop'",
+    '$n=[string]$env:LIVEDESK_NODE_EXECUTABLE',
+    'if(-not $n){$n=(Get-Command node.exe -ErrorAction SilentlyContinue).Source}',
+    "if(-not $n){throw 'LiveDesk node executable was not found.'}",
+    "$j=\"eval(Buffer.from(process.env.S,'base64').toString('utf8'))\"",
+    "$p=Start-Process -FilePath $n -ArgumentList @('-e',$j) -WindowStyle Hidden -PassThru",
+    "if(-not $p){throw 'LiveDesk update starter failed.'}"
+  ].join(';');
+  const command = windows
+    ? `set C=${configBase64}&set S=${starterBase64}&powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodePowerShell(powerShellStarter)}`
+    : `C='${configBase64}' S='${starterBase64}' "${'${LIVEDESK_NODE_EXECUTABLE:-node}'}" -e 'eval(Buffer.from(process.env.S,"base64").toString("utf8"))'`;
+  return assertLegacyCommandLength(command, windows ? 'Windows' : 'Unix');
+}
+
+function buildLegacyUpdateCommand(
+  device,
+  operationId,
+  targetVersion,
+  targetProductVersion,
+  updateTimeoutMs
+) {
+  const payload = {
+    operationId,
+    deviceId: device.deviceId || '',
+    agentPid: device.pid || 0,
+    currentProductVersion: device.productVersion || '',
+    currentAgentVersion: device.agentVersion || '',
+    targetVersion,
+    targetProductVersion,
+    updateTimeoutMs
+  };
+  return buildLegacyPlatformCommand(device.platform, payload);
+}
 
 async function fetchLatestPackage(packageName, fetchImpl) {
   const encodedName = packageName.startsWith('@') ? packageName.replace('/', '%2F') : packageName;
@@ -158,58 +153,121 @@ async function fetchLatestPackage(packageName, fetchImpl) {
   return { version, package: payload };
 }
 
-export async function fetchLatestLiveDeskRelease(fetchImpl = globalThis.fetch) {
+export async function fetchLatestLiveDeskRelease(fetchImpl = globalThis.fetch) {
   if (typeof fetchImpl !== 'function') throw new Error('fetch is unavailable for LiveDesk update checks.');
   const [manager, client] = await Promise.all([
     fetchLatestPackage('livedesk', fetchImpl),
     fetchLatestPackage('@livedesk/client', fetchImpl)
   ]);
-  return {
-    latestManagerVersion: manager.version,
-    latestClientVersion: client.version,
-    managerPackage: manager.package,
-    clientPackage: client.package,
-    checkedAt: new Date().toISOString()
-  };
-}
+  const bundledClientVersion = cleanVersion(manager.package?.livedeskClientVersion);
+  if (!bundledClientVersion) {
+    throw new Error(`livedesk@${manager.version} is missing required livedeskClientVersion release metadata.`);
+  }
+  return {
+    latestManagerVersion: manager.version,
+    latestClientVersion: bundledClientVersion,
+    registryClientVersion: client.version,
+    releaseSkew: compareVersions(client.version, bundledClientVersion) === 0
+      ? ''
+      : `livedesk@${manager.version} bundles Client ${bundledClientVersion}, while @livedesk/client latest is ${client.version}.`,
+    managerPackage: manager.package,
+    clientPackage: client.package,
+    checkedAt: new Date().toISOString()
+  };
+}
 
-function statusForRun(run) {
-  if (!run) return null;
-  return {
-    operationId: run.operationId,
-    state: run.state,
-    startedAt: run.startedAt,
-    updatedAt: run.updatedAt,
-    targetCount: run.targets.length,
-    completedCount: run.targets.filter(target => target.state === 'completed').length,
-    waitingCount: run.targets.filter(target => target.state === 'waiting').length,
-    failedCount: run.targets.filter(target => target.state === 'failed').length,
-    error: run.error || '',
-    targets: run.targets.map(target => ({ ...target }))
-  };
-}
+function statusForRun(run) {
+  if (!run) return null;
+  const completedCount = run.targets.filter(target => target.state === 'completed').length;
+  const failedCount = run.targets.filter(target => target.state === 'failed').length;
+  const queuedCount = run.targets.filter(target => target.state === 'queued').length;
+  const pendingOfflineCount = run.targets.filter(target => target.state === 'pending-offline').length;
+  const activeCount = run.targets.filter(target => target.state === 'waiting').length;
+  return {
+    operationId: run.operationId,
+    state: run.state,
+    startedAt: run.startedAt,
+    updatedAt: run.updatedAt,
+    targetCount: run.targets.length,
+    completedCount,
+    waitingCount: run.targets.length - completedCount - failedCount,
+    activeCount,
+    queuedCount,
+    pendingOfflineCount,
+    failedCount,
+    batchSize: run.batchSize,
+    clientRestartStabilityMs: run.clientRestartStabilityMs,
+    latestManagerVersion: run.latestManagerVersion,
+    latestClientVersion: run.latestClientVersion,
+    error: run.error || '',
+    targets: run.targets.map(target => ({ ...target }))
+  };
+}
 
-function connectedDevices(remoteHub) {
+function connectedDevices(remoteHub) {
   return remoteHub.listDevices({ includeDataUrl: false })
     .filter(device => device.connected === true && device.synthetic !== true)
     .slice(0, 500);
-}
-
-export function createLiveDeskUpdateManager({
+}
+
+function knownOfflineDevices(remoteHub) {
+  return remoteHub.listDevices({ includeDataUrl: false })
+    .filter(device => device.connected !== true && device.synthetic !== true)
+    .slice(0, 500);
+}
+
+function deviceNeedsUpdate(device, latestManagerVersion, latestClientVersion) {
+  return !isVersionAtLeast(device?.productVersion, latestManagerVersion)
+    || !isVersionAtLeast(device?.agentVersion, latestClientVersion);
+}
+
+function resetReconnectCandidate(target) {
+  target.candidateSessionId = '';
+  target.candidatePid = 0;
+  target.candidateConnectedAt = '';
+  target.candidateProductVersion = '';
+  target.candidateAgentVersion = '';
+  target.candidateSince = '';
+  target.stabilityDeadlineAt = '';
+}
+
+export function createLiveDeskUpdateManager({
   remoteHub,
   currentManagerVersion,
-  currentClientVersion,
-  restartSupported = false,
-  requestHubRestart,
-  fetchImpl = globalThis.fetch,
-  now = () => Date.now()
-}) {
+  currentClientVersion,
+  restartSupported = false,
+  requestHubRestart,
+  fetchImpl = globalThis.fetch,
+  now = () => Date.now(),
+  clientBatchSize = LIVE_DESK_UPDATE_CLIENT_BATCH_SIZE,
+  targetTimeoutMs = LIVE_DESK_UPDATE_TARGET_TIMEOUT_MS,
+  operationTimeoutMs = LIVE_DESK_UPDATE_TIMEOUT_MS,
+  clientRestartStabilityMs = LIVE_DESK_UPDATE_CLIENT_RESTART_STABILITY_MS
+}) {
   let latestRelease = null;
   let checkError = '';
   let checkPromise = null;
-  let run = null;
-  let checkTimer = null;
-  let runTimer = null;
+  let run = null;
+  let checkTimer = null;
+  let runTimer = null;
+  const effectiveClientBatchSize = Math.max(
+    1,
+    Math.min(50, Math.floor(Number(clientBatchSize) || LIVE_DESK_UPDATE_CLIENT_BATCH_SIZE))
+  );
+  const effectiveTargetTimeoutMs = Math.max(
+    10_000,
+    Number(targetTimeoutMs) || LIVE_DESK_UPDATE_TARGET_TIMEOUT_MS
+  );
+  const effectiveOperationTimeoutMs = Math.max(
+    effectiveTargetTimeoutMs,
+    Number(operationTimeoutMs) || LIVE_DESK_UPDATE_TIMEOUT_MS
+  );
+  const effectiveClientRestartStabilityMs = Math.max(
+    0,
+    Number.isFinite(Number(clientRestartStabilityMs))
+      ? Number(clientRestartStabilityMs)
+      : LIVE_DESK_UPDATE_CLIENT_RESTART_STABILITY_MS
+  );
 
   const touch = () => {
     if (run) run.updatedAt = new Date(now()).toISOString();
@@ -234,45 +292,110 @@ export function createLiveDeskUpdateManager({
   };
 
   const getStatus = () => {
-    const managerUpdateAvailable = !!latestRelease
-      && compareVersions(latestRelease.latestManagerVersion, currentManagerVersion) > 0;
-    const clientDevices = connectedDevices(remoteHub);
-    const outdatedClientDevices = latestRelease
-      ? clientDevices.filter(device => !isVersionAtLeast(device.agentVersion, latestRelease.latestClientVersion))
-      : [];
-    const clientPackageUpdateAvailable = !!latestRelease
-      && compareVersions(latestRelease.latestClientVersion, currentClientVersion) > 0;
+    const managerUpdateAvailable = !!latestRelease
+      && compareVersions(latestRelease.latestManagerVersion, currentManagerVersion) > 0;
+    const clientDevices = connectedDevices(remoteHub);
+    const outdatedClientDevices = latestRelease
+      ? clientDevices.filter(device => deviceNeedsUpdate(
+        device,
+        latestRelease.latestManagerVersion,
+        latestRelease.latestClientVersion
+      ))
+      : [];
+    const pendingOfflineClientCount = latestRelease
+      ? knownOfflineDevices(remoteHub).filter(device => deviceNeedsUpdate(
+        device,
+        latestRelease.latestManagerVersion,
+        latestRelease.latestClientVersion
+      )).length
+      : 0;
+    const clientPackageUpdateAvailable = !!latestRelease
+      && compareVersions(latestRelease.latestClientVersion, currentClientVersion) > 0;
     const clientUpdateAvailable = clientPackageUpdateAvailable || outdatedClientDevices.length > 0;
     const updateAvailable = managerUpdateAvailable || clientUpdateAvailable;
     const activeRun = statusForRun(run);
     return {
       currentVersion: String(currentManagerVersion || ''),
       currentClientVersion: String(currentClientVersion || ''),
-      latestVersion: latestRelease?.latestManagerVersion || '',
-      latestClientVersion: latestRelease?.latestClientVersion || '',
-      updateAvailable,
+      latestVersion: latestRelease?.latestManagerVersion || '',
+      latestClientVersion: latestRelease?.latestClientVersion || '',
+      registryClientVersion: latestRelease?.registryClientVersion || '',
+      releaseSkew: latestRelease?.releaseSkew || '',
+      updateAvailable,
       managerUpdateAvailable,
       clientUpdateAvailable,
-      clientPackageUpdateAvailable,
-      outdatedClientCount: outdatedClientDevices.length,
-      checkedAt: latestRelease?.checkedAt || '',
+      clientPackageUpdateAvailable,
+      outdatedClientCount: outdatedClientDevices.length,
+      pendingOfflineClientCount,
+      checkedAt: latestRelease?.checkedAt || '',
       checkError,
       restartSupported: !!restartSupported,
       canApply: updateAvailable && (!managerUpdateAvailable && !clientPackageUpdateAvailable || !!restartSupported),
-      ...(activeRun || { state: 'idle', operationId: '', targetCount: 0, completedCount: 0, waitingCount: 0, failedCount: 0, targets: [] })
+      ...(activeRun || {
+        state: 'idle',
+        operationId: '',
+        targetCount: 0,
+        completedCount: 0,
+        waitingCount: 0,
+        activeCount: 0,
+        queuedCount: 0,
+        pendingOfflineCount: 0,
+        failedCount: 0,
+        batchSize: effectiveClientBatchSize,
+        clientRestartStabilityMs: effectiveClientRestartStabilityMs,
+        targets: []
+      })
     };
   };
 
-  const failRun = (message) => {
-    if (!run) return;
-    run.state = 'failed';
-    run.error = String(message || 'LiveDesk update failed.');
-    touch();
-    if (runTimer) {
-      clearInterval(runTimer);
-      runTimer = null;
-    }
-  };
+  const failRun = (message) => {
+    if (!run) return;
+    run.state = 'failed';
+    run.error = String(message || 'LiveDesk update failed.');
+    for (const target of run.targets) {
+      if (target.state === 'completed') continue;
+      target.state = 'failed';
+      if (!target.error) {
+        target.error = `Rollout stopped: ${run.error}`;
+      }
+    }
+    touch();
+    if (runTimer) {
+      clearInterval(runTimer);
+      runTimer = null;
+    }
+  };
+
+  const reconcileHubRestartResult = (restartResult) => {
+    if (!run || run.state !== 'hub-restart-requested') return false;
+    const operationId = String(restartResult?.operationId || '').trim();
+    if (!operationId || operationId !== run.operationId) return false;
+    const stage = String(restartResult?.stage || '').trim();
+    const outcome = String(restartResult?.outcome || '').trim();
+    if (outcome !== 'failed' || !['failed', 'preflight-failed'].includes(stage)) return false;
+    failRun(
+      restartResult?.error
+      || (stage === 'preflight-failed'
+        ? 'Hub update restart preflight failed before shutdown.'
+        : 'Hub update restart failed.')
+    );
+    return true;
+  };
+
+  const retrySettlingTargets = () => {
+    if (!run || run.state !== 'failed') return [];
+    const currentTime = now();
+    const devices = new Map(
+      remoteHub.listDevices({ includeDataUrl: false })
+        .map(device => [String(device.deviceId), device])
+    );
+    return run.targets.filter(target => {
+      if (target.state !== 'failed' || !target.dispatchedAt) return false;
+      const deadline = Date.parse(target.deadlineAt || '');
+      if (!(deadline > currentTime)) return false;
+      return devices.get(target.deviceId)?.connected !== true;
+    });
+  };
 
   const requestRestart = () => {
     if (!restartSupported) {
@@ -281,8 +404,8 @@ export function createLiveDeskUpdateManager({
     }
     const result = requestHubRestart?.({
       operationId: run?.operationId || '',
-      latestVersion: latestRelease?.latestManagerVersion || '',
-      latestClientVersion: latestRelease?.latestClientVersion || '',
+      latestVersion: run?.latestManagerVersion || latestRelease?.latestManagerVersion || '',
+      latestClientVersion: run?.latestClientVersion || latestRelease?.latestClientVersion || '',
       // Current versions update every connected Client before the Hub exits.
       // Older Hub versions did the reverse and set this flag themselves; the
       // new server still supports that one-time migration path.
@@ -299,75 +422,214 @@ export function createLiveDeskUpdateManager({
     return true;
   };
 
-  const verifyTargets = () => {
-    if (!run || run.state !== 'waiting-for-clients') return;
-    const devices = new Map(connectedDevices(remoteHub).map(device => [String(device.deviceId), device]));
-    for (const target of run.targets) {
-      if (target.state === 'failed' || target.state === 'completed') continue;
-      const device = devices.get(target.deviceId);
-      if (device?.connected === true && isVersionAtLeast(device.agentVersion, run.latestClientVersion)) {
-        target.state = 'completed';
-        target.currentVersion = String(device.agentVersion || '');
-        target.completedAt = new Date(now()).toISOString();
-      } else {
-        target.state = 'waiting';
-      }
-    }
-    touch();
-    if (run.targets.every(target => target.state === 'completed')) {
-      if (runTimer) {
-        clearInterval(runTimer);
-        runTimer = null;
-      }
-      if (run.needsHubRestart) {
-        requestRestart();
-      } else {
-        run.state = 'clients-updated';
-        touch();
-      }
-      return;
-    }
-    if (now() - Date.parse(run.startedAt) >= LIVE_DESK_UPDATE_TIMEOUT_MS) {
-      failRun(`Timed out waiting for ${run.targets.filter(target => target.state !== 'completed').length} client(s) to reconnect with ${run.latestClientVersion}.`);
+  const dispatchTarget = (target, device) => {
+    const dispatchedAtEpochMs = now();
+    const updateDeadlineEpochMs = dispatchedAtEpochMs + effectiveTargetTimeoutMs;
+    const dispatchedSessionId = String(device?.sessionId || '').trim();
+    if (!dispatchedSessionId) {
+      target.state = 'failed';
+      target.error = 'client-update-session-unavailable';
+      return false;
+    }
+    target.dispatchedSessionId = dispatchedSessionId;
+    target.dispatchedPid = Math.max(0, Math.floor(Number(device?.pid) || 0));
+    resetReconnectCandidate(target);
+    const supportsDedicated = device.capabilities?.clientUpdate === true
+      && isVersionAtLeast(device.agentVersion, LIVE_DESK_DEDICATED_CLIENT_UPDATE_MIN_VERSION);
+    const payload = {
+      targetVersion: run.latestClientVersion,
+      targetProductVersion: run.latestManagerVersion,
+      managerVersion: run.latestManagerVersion,
+      operationId: run.operationId,
+      updateTimeoutMs: effectiveTargetTimeoutMs
+    };
+    const result = supportsDedicated
+      ? remoteHub.sendCommand(device.deviceId, { command: LIVE_DESK_UPDATE_COMMAND, payload })
+      : remoteHub.sendLegacyClientUpdate(device.deviceId, {
+        command: buildLegacyUpdateCommand(
+          device,
+          run.operationId,
+          run.latestClientVersion,
+          run.latestManagerVersion,
+          effectiveTargetTimeoutMs
+        ),
+        timeoutMs: 30_000
+      });
+    if (result?.ok !== true) {
+      const dispatchError = String(result?.error || 'client-update-dispatch-failed');
+      if (['device-not-connected', 'device-not-found'].includes(dispatchError)) {
+        target.state = 'pending-offline';
+        target.method = '';
+        target.commandId = '';
+        target.dispatchedAt = '';
+        target.deadlineAt = '';
+        target.dispatchedSessionId = '';
+        target.dispatchedPid = 0;
+        resetReconnectCandidate(target);
+        target.error = '';
+        return 'pending-offline';
+      }
+      target.state = 'failed';
+      target.error = dispatchError;
+      return false;
     }
-  };
-
-  const dispatchTarget = (target, credentials) => {
-    const device = target.device;
-    const supportsDedicated = device.capabilities?.clientUpdate === true
-      && isVersionAtLeast(device.agentVersion, LIVE_DESK_DEDICATED_CLIENT_UPDATE_MIN_VERSION);
-    const payload = {
-      targetVersion: run.latestClientVersion,
-      managerVersion: run.latestManagerVersion,
-      operationId: run.operationId
-    };
-    const result = supportsDedicated
-      ? remoteHub.sendCommand(device.deviceId, { command: LIVE_DESK_UPDATE_COMMAND, payload })
-      : remoteHub.sendLegacyClientUpdate(device.deviceId, {
-        command: buildLegacyUpdateCommand(device, credentials, run.latestClientVersion),
-        timeoutMs: 30_000
-      });
-    if (result?.ok !== true) {
-      target.state = 'failed';
-      target.error = String(result?.error || 'client-update-dispatch-failed');
-      return false;
-    }
-    target.state = 'waiting';
-    target.method = supportsDedicated ? 'dedicated' : 'legacy-command-run';
-    target.commandId = String(result.commandId || result.taskId || '');
-    return true;
-  };
-
-  const startUpdate = async () => {
-    if (run && ['dispatching', 'waiting-for-clients', 'hub-restart-requested'].includes(run.state)) {
-      return { ok: true, ...getStatus() };
-    }
-    const release = latestRelease || await checkLatest();
+    target.state = 'waiting';
+    target.method = supportsDedicated ? 'dedicated' : 'legacy-command-run';
+    target.commandId = String(result.commandId || result.taskId || '');
+    target.dispatchedAt = new Date(dispatchedAtEpochMs).toISOString();
+    target.deadlineAt = new Date(updateDeadlineEpochMs).toISOString();
+    return true;
+  };
+
+  const dispatchQueuedTargets = () => {
+    if (!run || run.state !== 'waiting-for-clients') return true;
+    const activeCount = run.targets.filter(target => target.state === 'waiting').length;
+    let availableSlots = Math.max(0, run.batchSize - activeCount);
+    if (availableSlots <= 0) return true;
+    const devices = new Map(connectedDevices(remoteHub).map(device => [String(device.deviceId), device]));
+    for (const target of run.targets) {
+      if (availableSlots <= 0) break;
+      if (!['queued', 'pending-offline'].includes(target.state)) continue;
+      const device = devices.get(target.deviceId);
+      if (!device?.connected) {
+        target.state = 'pending-offline';
+        continue;
+      }
+      target.state = 'queued';
+      let dispatchResult;
+      try {
+        dispatchResult = dispatchTarget(target, device);
+      } catch (error) {
+        target.state = 'failed';
+        target.error = String(error?.message || error || 'client-update-command-build-failed').slice(0, 500);
+        failRun(`Client ${target.deviceName || target.deviceId} could not be scheduled: ${target.error}`);
+        return false;
+      }
+      if (dispatchResult === false) {
+        failRun(`Client ${target.deviceName || target.deviceId} could not be scheduled: ${target.error}`);
+        return false;
+      }
+      if (dispatchResult === true) {
+        availableSlots -= 1;
+      }
+    }
+    touch();
+    return true;
+  };
+
+  const verifyTargets = () => {
+    if (!run || run.state !== 'waiting-for-clients') return;
+    const currentTime = now();
+    if (currentTime - Date.parse(run.startedAt) >= effectiveOperationTimeoutMs) {
+      const unfinishedCount = run.targets.filter(target => target.state !== 'completed').length;
+      failRun(`Timed out waiting for ${unfinishedCount} client(s) to finish the rollout.`);
+      return;
+    }
+    const devices = new Map(connectedDevices(remoteHub).map(device => [String(device.deviceId), device]));
+    for (const target of run.targets) {
+      if (target.state === 'failed' || target.state === 'completed') continue;
+      const device = devices.get(target.deviceId);
+      if (target.state === 'waiting') {
+        const sessionId = String(device?.sessionId || '').trim();
+        const connectedAt = String(device?.connectedAt || '');
+        const connectedAtEpochMs = Date.parse(connectedAt);
+        const dispatchedAtEpochMs = Date.parse(target.dispatchedAt || '');
+        const candidatePid = Math.max(0, Math.floor(Number(device?.pid) || 0));
+        const candidateProductVersion = String(device?.productVersion || '');
+        const candidateAgentVersion = String(device?.agentVersion || '');
+        const qualifiesForStability = device?.connected === true
+          && !!sessionId
+          && candidatePid > 1
+          && sessionId !== target.dispatchedSessionId
+          && connectedAtEpochMs >= dispatchedAtEpochMs
+          && !deviceNeedsUpdate(device, run.latestManagerVersion, run.latestClientVersion);
+        const sameCandidate = qualifiesForStability
+          && target.candidateSessionId === sessionId
+          && target.candidatePid === candidatePid
+          && target.candidateConnectedAt === connectedAt
+          && target.candidateProductVersion === candidateProductVersion
+          && target.candidateAgentVersion === candidateAgentVersion;
+
+        if (!qualifiesForStability) {
+          resetReconnectCandidate(target);
+        } else if (!sameCandidate) {
+          target.candidateSessionId = sessionId;
+          target.candidatePid = candidatePid;
+          target.candidateConnectedAt = connectedAt;
+          target.candidateProductVersion = candidateProductVersion;
+          target.candidateAgentVersion = candidateAgentVersion;
+          target.candidateSince = new Date(currentTime).toISOString();
+          target.stabilityDeadlineAt = new Date(
+            currentTime + run.clientRestartStabilityMs
+          ).toISOString();
+        }
+
+        if (qualifiesForStability
+          && target.candidateSessionId === sessionId
+          && currentTime >= Date.parse(target.stabilityDeadlineAt || '')) {
+          target.state = 'completed';
+          target.currentVersion = String(device.agentVersion || '');
+          target.currentProductVersion = String(device.productVersion || '');
+          target.completedAt = new Date(currentTime).toISOString();
+          continue;
+        }
+      }
+      if (target.state === 'waiting'
+        && Date.parse(target.deadlineAt || '') > 0
+        && currentTime >= Date.parse(target.deadlineAt)) {
+        target.state = 'failed';
+        target.error = `Timed out waiting for product ${run.latestManagerVersion} / Client ${run.latestClientVersion}.`;
+        failRun(`Client ${target.deviceName || target.deviceId} did not restart on the requested versions within ${Math.round(effectiveTargetTimeoutMs / 1000)} seconds.`);
+        return;
+      }
+      if (target.state === 'pending-offline' && device?.connected === true) {
+        target.state = 'queued';
+      }
+    }
+    if (!dispatchQueuedTargets()) return;
+    touch();
+    if (run.targets.every(target => target.state === 'completed')) {
+      if (runTimer) {
+        clearInterval(runTimer);
+        runTimer = null;
+      }
+      if (run.needsHubRestart) {
+        requestRestart();
+      } else {
+        run.state = 'clients-updated';
+        touch();
+      }
+      return;
+    }
+  };
+
+  const startUpdate = async () => {
+    if (run && ['dispatching', 'waiting-for-clients', 'hub-restart-requested'].includes(run.state)) {
+      return { ok: true, ...getStatus() };
+    }
+    const settlingTargets = retrySettlingTargets();
+    if (settlingTargets.length > 0) {
+      const names = settlingTargets
+        .slice(0, 3)
+        .map(target => target.deviceName || target.deviceId)
+        .join(', ');
+      const remaining = settlingTargets.length > 3 ? ` and ${settlingTargets.length - 3} more` : '';
+      return {
+        ...getStatus(),
+        ok: false,
+        error: `The previous rollout is still settling for offline Client(s): ${names}${remaining}. Retry after they reconnect or their restart deadline passes.`
+      };
+    }
+    const release = latestRelease || await checkLatest();
     if (!release) return { ok: false, error: checkError || 'LiveDesk update check failed.', ...getStatus() };
     const managerNeedsUpdate = compareVersions(release.latestManagerVersion, currentManagerVersion) > 0;
     const clientPackageNeedsUpdate = compareVersions(release.latestClientVersion, currentClientVersion) > 0;
     const connected = connectedDevices(remoteHub);
-    const outdatedClients = connected.filter(device => !isVersionAtLeast(device.agentVersion, release.latestClientVersion));
+    const outdatedClients = connected.filter(device => deviceNeedsUpdate(
+      device,
+      release.latestManagerVersion,
+      release.latestClientVersion
+    ));
     const needsHubRestart = managerNeedsUpdate || clientPackageNeedsUpdate;
     if (!managerNeedsUpdate && !clientPackageNeedsUpdate && outdatedClients.length === 0) {
       return { ok: true, state: 'clients-updated', ...getStatus() };
@@ -376,57 +638,77 @@ export function createLiveDeskUpdateManager({
       return { ok: false, error: 'Hub launcher restart is unavailable. Start LiveDesk through npx livedesk@latest.', ...getStatus() };
     }
     const targets = outdatedClients;
-    const credentials = remoteHub.getStatus({ includeSecrets: true });
-    run = {
+    run = {
       operationId: randomUUID(),
       state: 'dispatching',
       startedAt: new Date(now()).toISOString(),
       updatedAt: new Date(now()).toISOString(),
       latestManagerVersion: release.latestManagerVersion,
-      latestClientVersion: release.latestClientVersion,
+      latestClientVersion: release.latestClientVersion,
       needsHubRestart,
-      error: '',
-      targets: targets.map(device => ({
+      batchSize: effectiveClientBatchSize,
+      clientRestartStabilityMs: effectiveClientRestartStabilityMs,
+      error: '',
+      targets: targets.map(device => ({
         deviceId: String(device.deviceId || ''),
-        deviceName: String(device.deviceName || device.hostname || device.deviceId || ''),
-        oldVersion: String(device.agentVersion || ''),
-        currentVersion: '',
-        state: 'queued',
-        method: '',
-        commandId: '',
-        error: '',
-        device
-      }))
-    };
-    for (const target of run.targets) dispatchTarget(target, credentials);
-    run.targets = run.targets.map(({ device, ...target }) => target);
-    touch();
-    if (run.targets.some(target => target.state === 'failed')) {
-      failRun('One or more clients could not be scheduled for update.');
-      return { ok: false, error: run.error, ...getStatus() };
-    }
-    if (run.targets.length === 0) {
-      if (run.needsHubRestart) {
-        requestRestart();
-      } else {
+        deviceName: String(device.deviceName || device.hostname || device.deviceId || ''),
+        oldVersion: String(device.agentVersion || ''),
+        oldProductVersion: String(device.productVersion || ''),
+        currentVersion: '',
+        currentProductVersion: '',
+        state: 'queued',
+        method: '',
+        commandId: '',
+        dispatchedAt: '',
+        deadlineAt: '',
+        dispatchedSessionId: '',
+        dispatchedPid: 0,
+        candidateSessionId: '',
+        candidatePid: 0,
+        candidateConnectedAt: '',
+        candidateProductVersion: '',
+        candidateAgentVersion: '',
+        candidateSince: '',
+        stabilityDeadlineAt: '',
+        completedAt: '',
+        error: ''
+      }))
+    };
+    touch();
+    if (run.targets.length === 0) {
+      if (run.needsHubRestart) {
+        if (!requestRestart()) {
+          return { ok: false, error: run.error, ...getStatus() };
+        }
+      } else {
         run.state = 'clients-updated';
         touch();
       }
       return { ok: true, ...getStatus() };
-    }
-    run.state = 'waiting-for-clients';
-    runTimer = setInterval(verifyTargets, 1000);
+    }
+    run.state = 'waiting-for-clients';
+    if (!dispatchQueuedTargets()) {
+      return { ok: false, error: run.error, ...getStatus() };
+    }
+    runTimer = setInterval(verifyTargets, 1000);
     runTimer.unref?.();
     verifyTargets();
     return { ok: true, ...getStatus() };
-  };
-
-  const handleRemoteEvent = (type, event) => {
-    if (!run || run.state !== 'waiting-for-clients' || type !== 'RemoteCommandResult') return;
+  };
+
+  const handleRemoteEvent = (type, event) => {
+    if (!run || run.state !== 'waiting-for-clients') return;
+    if (type === 'RemoteDeviceConnected' || type === 'RemoteDeviceDisconnected') {
+      verifyTargets();
+      return;
+    }
+    if (type !== 'RemoteCommandResult') return;
     const deviceId = String(event?.device?.deviceId || '');
     const commandId = String(event?.commandId || '');
     const target = run.targets.find(item => item.deviceId === deviceId && item.commandId === commandId);
-    if (!target || !['dedicated', 'legacy-command-run'].includes(target.method)) return;
+    if (!target
+      || target.state !== 'waiting'
+      || !['dedicated', 'legacy-command-run'].includes(target.method)) return;
     const result = event?.result;
     if (event?.error || result?.ok === false || result?.status === 'failed' || result?.status === 'rejected') {
       target.state = 'failed';
@@ -444,10 +726,11 @@ export function createLiveDeskUpdateManager({
 
   return {
     checkLatest,
-    getStatus,
-    startUpdate,
-    handleRemoteEvent,
-    close() {
+    getStatus,
+    startUpdate,
+    handleRemoteEvent,
+    reconcileHubRestartResult,
+    close() {
       if (checkTimer) clearInterval(checkTimer);
       if (runTimer) clearInterval(runTimer);
       checkTimer = null;