livedesk 0.1.384 → 0.1.385

package/hub/src/live-desk-update.js

@@ -1,25 +1,59 @@
 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.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_CLIENT_BATCH_SIZE = 5;
+export const LIVE_DESK_UPDATE_TARGET_TIMEOUT_MS = 300_000;
+export const LIVE_DESK_UPDATE_TIMEOUT_MS = 60 * 60_000;
+export const LIVE_DESK_UPDATE_CHECK_INTERVAL_MS = 60_000;
 
-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) {
@@ -34,7 +68,7 @@ function quotePowerShell(value) {
   return `'${String(value ?? '').replaceAll("'", "''")}'`;
 }
 
-function buildWindowsLegacyUpdateCommand({ manager, pair, name, slot, targetVersion }) {
+function buildWindowsLegacyUpdateCommand({ manager, pair, name, slot, targetVersion, targetProductVersion }) {
   const script = [
     '$ErrorActionPreference = "Stop"',
     '$cursor = Get-CimInstance Win32_Process -Filter ("ProcessId={0}" -f $PID)',
@@ -54,8 +88,9 @@ function buildWindowsLegacyUpdateCommand({ manager, pair, name, slot, targetVers
     `$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)}`,
+    `$env:LIVEDESK_CLIENT_SLOT = ${quotePowerShell(slot || '')}`,
+    `$env:LIVEDESK_CLIENT_UPDATE_TARGET_VERSION = ${quotePowerShell(targetVersion)}`,
+    `$env:LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION = ${quotePowerShell(targetProductVersion)}`,
     '$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 }',
@@ -88,7 +123,9 @@ function buildUnixClientUpdateBootstrapScript() {
     '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 targetProductVersion = String(process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION || "").trim();',
+    'const packageSpec = /^\\d+\\.\\d+\\.\\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(targetProductVersion) ? "livedesk@" + targetProductVersion : "livedesk@latest";',
+    'const npxArgs = ["-y", "--prefer-online", packageSpec, "--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";',
@@ -97,7 +134,7 @@ function buildUnixClientUpdateBootstrapScript() {
   ].join('\n');
 }
 
-function buildUnixLegacyUpdateCommand({ manager, pair, name, slot, targetVersion }) {
+function buildUnixLegacyUpdateCommand({ manager, pair, name, slot, targetVersion, targetProductVersion }) {
   const script = [
     'const { execFileSync, spawn } = require("node:child_process");',
     'const fs = require("node:fs");',
@@ -115,8 +152,9 @@ function buildUnixLegacyUpdateCommand({ manager, pair, name, slot, targetVersion
     `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 || ''))};`,
+    `process.env.LIVEDESK_CLIENT_SLOT = ${JSON.stringify(String(slot || ''))};`,
+    `process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION = ${JSON.stringify(String(targetVersion || ''))};`,
+    `process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION = ${JSON.stringify(String(targetProductVersion || ''))};`,
     `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 });',
@@ -130,13 +168,14 @@ function buildUnixLegacyUpdateCommand({ manager, pair, name, slot, targetVersion
   ].join('\n');
 }
 
-function buildLegacyUpdateCommand(device, credentials, targetVersion) {
-  const payload = {
-    manager: credentials.manager,
+function buildLegacyUpdateCommand(device, credentials, targetVersion, targetProductVersion) {
+  const payload = {
+    manager: credentials.agentEndpoint || credentials.manager,
     pair: credentials.pairToken,
     name: device.deviceName || device.hostname || '',
     slot: device.slotNumber || '',
-    targetVersion
+    targetVersion,
+    targetProductVersion
   };
   return ['win32', 'windows'].includes(String(device.platform || '').toLowerCase())
     ? buildWindowsLegacyUpdateCommand(payload)
@@ -158,58 +197,103 @@ 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,
+    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);
-}
+}
+
+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);
+}
 
 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
+}) {
   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 touch = () => {
     if (run) run.updatedAt = new Date(now()).toISOString();
@@ -234,45 +318,93 @@ 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,
+        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 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 +413,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 +431,155 @@ 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, 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 dispatchTarget = (target, device, credentials) => {
+    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
+    };
+    const result = supportsDedicated
+      ? remoteHub.sendCommand(device.deviceId, { command: LIVE_DESK_UPDATE_COMMAND, payload })
+      : remoteHub.sendLegacyClientUpdate(device.deviceId, {
+        command: buildLegacyUpdateCommand(
+          device,
+          credentials,
+          run.latestClientVersion,
+          run.latestManagerVersion
+        ),
+        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.error = '';
+        return 'pending-offline';
+      }
+      target.state = 'failed';
+      target.error = dispatchError;
+      return false;
     }
-    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(now()).toISOString();
+    target.deadlineAt = new Date(now() + effectiveTargetTimeoutMs).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]));
+    const credentials = remoteHub.getStatus({ includeSecrets: true });
+    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';
+      const dispatchResult = dispatchTarget(target, device, credentials);
+      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'
+        && device?.connected === true
+        && !deviceNeedsUpdate(device, run.latestManagerVersion, run.latestClientVersion)) {
+        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,46 +588,49 @@ 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,
+      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: '',
+        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() };
@@ -426,7 +641,9 @@ export function createLiveDeskUpdateManager({
     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';