livedesk 0.1.388 → 0.1.389

package/bootstrap/legacy-client-update.js

@@ -9,11 +9,12 @@ import {
   readFileSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync
 } from 'node:fs';
 import http from 'node:http';
 import os from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 const DEFAULT_RUNTIME_PORT = 5179;
 const TARGET_ATTEMPT_LIMIT = 3;
@@ -22,6 +23,13 @@ const VERIFY_TIMEOUT_MS = 45_000;
 const VERIFY_POLL_MS = 500;
 const VERIFY_STABLE_MS = 5_000;
 const PROCESS_ARGUMENT_QUERY_TIMEOUT_MS = 10_000;
+const SUPERSEDED_OPERATION_CODE = 'LIVEDESK_CLIENT_UPDATE_SUPERSEDED';
+const DEADLINE_EXPIRED_CODE = 'LIVEDESK_CLIENT_UPDATE_DEADLINE_EXPIRED';
+const TERMINAL_UPDATE_STAGES = new Set(['connected', 'failed', 'restored']);
+const UPDATE_STATE_LOCK_TIMEOUT_MS = 10_000;
+const UPDATE_STATE_LOCK_POLL_MS = 25;
+const UPDATE_STATE_EMPTY_LOCK_STALE_MS = 5_000;
+const updateStateLockWaitBuffer = new Int32Array(new SharedArrayBuffer(4));
 
 const PRESERVED_SINGLE_FLAGS = new Set([
   '--control',
@@ -67,6 +75,106 @@ function cleanVersion(value) {
   return String(value || '').trim().replace(/^v/i, '');
 }
 
+function safePathSegment(value, fallback = 'unknown') {
+  return String(value || '')
+    .replace(/[^A-Za-z0-9._-]/g, '_')
+    .slice(0, 120) || fallback;
+}
+
+export class LegacyClientUpdateSupersededError extends Error {
+  constructor(expectedOperationId, actualOperationId) {
+    super(
+      `LiveDesk Client update ${expectedOperationId || 'unknown'} was superseded by `
+      + `${actualOperationId || 'another operation'}.`
+    );
+    this.name = 'LegacyClientUpdateSupersededError';
+    this.code = SUPERSEDED_OPERATION_CODE;
+    this.expectedOperationId = String(expectedOperationId || '');
+    this.actualOperationId = String(actualOperationId || '');
+  }
+}
+
+export function isLegacyClientUpdateSupersededError(error) {
+  return error?.code === SUPERSEDED_OPERATION_CODE;
+}
+
+export function isLegacyClientUpdateDeadlineExpiredError(error) {
+  return error?.code === DEADLINE_EXPIRED_CODE;
+}
+
+export function assertLegacyClientUpdateDeadline(
+  config,
+  now = Date.now,
+  checkpoint = 'update'
+) {
+  const deadlineEpochMs = Number(config?.updateDeadlineEpochMs);
+  if (!Number.isSafeInteger(deadlineEpochMs) || deadlineEpochMs <= 0) {
+    const error = new Error('LiveDesk Client update has no valid absolute deadline.');
+    error.code = DEADLINE_EXPIRED_CODE;
+    error.deadlineExpired = true;
+    throw error;
+  }
+  const currentEpochMs = Number(now());
+  if (currentEpochMs < deadlineEpochMs) return deadlineEpochMs - currentEpochMs;
+  const error = new Error(
+    `LiveDesk Client update deadline expired before ${checkpoint} `
+    + `(deadline=${new Date(deadlineEpochMs).toISOString()}).`
+  );
+  error.code = DEADLINE_EXPIRED_CODE;
+  error.deadlineExpired = true;
+  throw error;
+}
+
+export function getLegacyClientUpdateNeutralCwd(stateDir, operationId) {
+  return join(
+    os.tmpdir(),
+    'livedesk-update-cwd',
+    `client-${safePathSegment(operationId)}`
+  );
+}
+
+function prepareNeutralCwd(cwd) {
+  const configuredCwd = String(cwd || '').trim();
+  if (!configuredCwd) throw new Error('LiveDesk update neutral working directory is unavailable');
+  const neutralCwd = resolve(configuredCwd);
+  mkdirSync(neutralCwd, { recursive: true });
+  for (let ancestor = neutralCwd; ; ancestor = dirname(ancestor)) {
+    const shadowPath = [
+      join(ancestor, 'package.json'),
+      join(ancestor, 'node_modules', 'livedesk', 'package.json')
+    ].find(candidate => existsSync(candidate));
+    if (shadowPath) {
+      throw new Error(
+        `LiveDesk update neutral working directory is shadowed by ${shadowPath}: ${neutralCwd}`
+      );
+    }
+    const parent = dirname(ancestor);
+    if (parent === ancestor) break;
+  }
+  return neutralCwd;
+}
+
+export function buildLegacyClientUpdateNpxEnvironment(baseEnv, neutralCwd) {
+  const env = { ...baseEnv };
+  const isolatedNames = new Set([
+    'init_cwd',
+    'npm_config_local_prefix',
+    'npm_config_workspace',
+    'npm_config_workspaces',
+    'npm_config_include_workspace_root',
+    'npm_package_json',
+    'npm_lifecycle_event',
+    'npm_lifecycle_script'
+  ]);
+  for (const key of Object.keys(env)) {
+    if (isolatedNames.has(key.toLowerCase())) delete env[key];
+  }
+  env.INIT_CWD = neutralCwd;
+  env.npm_config_local_prefix = neutralCwd;
+  env.npm_config_include_workspace_root = 'false';
+  return env;
+}
+
 function positivePid(value) {
   const parsed = Number(value);
   return Number.isInteger(parsed) && parsed > 1 ? parsed : 0;
@@ -83,10 +191,51 @@ function readManifest(relativePath) {
   return JSON.parse(readFileSync(new URL(relativePath, import.meta.url), 'utf8'));
 }
 
+export function expandLegacyBridgeEnvironment(env) {
+  try {
+    const values = JSON.parse(
+      Buffer.from(String(env.C || ''), 'base64').toString('utf8')
+    );
+    if (!Array.isArray(values)
+      || values.length !== 8
+      || values.some(value => typeof value !== 'string')) {
+      return env;
+    }
+    return {
+      ...env,
+      LIVEDESK_CLIENT_UPDATE_OPERATION_ID: values[0],
+      LIVEDESK_DEVICE_ID: values[1],
+      LIVEDESK_CLIENT_UPDATE_AGENT_PID: values[2],
+      LIVEDESK_CLIENT_UPDATE_CURRENT_PRODUCT_VERSION: values[3],
+      LIVEDESK_CLIENT_UPDATE_CURRENT_AGENT_VERSION: values[4],
+      LIVEDESK_CLIENT_UPDATE_TARGET_VERSION: values[5],
+      LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION: values[6],
+      LIVEDESK_CLIENT_UPDATE_DEADLINE_EPOCH_MS: values[7]
+    };
+  } catch {
+    return env;
+  }
+}
+
 function readConfig(env = process.env) {
-  const stateDir = String(env.LIVEDESK_STATE_DIR || join(os.homedir(), '.livedesk'));
+  env = expandLegacyBridgeEnvironment(env);
+  const operationId = String(env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || '').trim();
+  const originalCwd = resolve(String(
+    env.LIVEDESK_UPDATE_ORIGINAL_CWD
+    || env.LIVEDESK_CLIENT_UPDATE_CWD
+    || process.cwd()
+  ).trim());
+  const stateDir = resolve(
+    originalCwd,
+    String(env.LIVEDESK_STATE_DIR || join(os.homedir(), '.livedesk'))
+  );
+  const configuredStatePath = String(
+    env.LIVEDESK_LEGACY_CLIENT_UPDATE_STATE_PATH
+    || env.LIVEDESK_CLIENT_UPDATE_STATE_PATH
+    || join(stateDir, 'client-update-legacy.json')
+  );
   return {
-    operationId: String(env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || '').trim(),
+    operationId,
     deviceId: String(env.LIVEDESK_DEVICE_ID || '').trim(),
     targetVersion: cleanVersion(env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION),
     targetProductVersion: cleanVersion(env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION),
@@ -97,13 +246,12 @@ function readConfig(env = process.env) {
     launcherPid: positivePid(env.LIVEDESK_CLIENT_PARENT_PID),
     agentPid: positivePid(env.LIVEDESK_CLIENT_UPDATE_AGENT_PID),
     starterPid: positivePid(env.LIVEDESK_UPDATE_STARTER_PID),
+    updateDeadlineEpochMs: Number(env.LIVEDESK_CLIENT_UPDATE_DEADLINE_EPOCH_MS),
     runtimePort: normalizePort(env.LIVEDESK_CLIENT_RUNTIME_PORT || env.LIVEDESK_LOCAL_RUNTIME_PORT),
     stateDir,
-    statePath: String(
-      env.LIVEDESK_LEGACY_CLIENT_UPDATE_STATE_PATH
-      || env.LIVEDESK_CLIENT_UPDATE_STATE_PATH
-      || join(stateDir, 'client-update-legacy.json')
-    ),
+    statePath: resolve(originalCwd, configuredStatePath),
+    neutralCwd: getLegacyClientUpdateNeutralCwd(stateDir, operationId),
+    originalCwd,
     restartArgs: []
   };
 }
@@ -393,7 +541,11 @@ export function buildLegacyClientRestartConfiguration({
 function captureRestartConfiguration(config, env, readArguments = readLegacyProcessArguments) {
   const preservedArgs = decodePreservedArgs(env);
   if (preservedArgs) {
-    return buildLegacyClientRestartConfiguration({ env, preservedArgs });
+    return {
+      ...buildLegacyClientRestartConfiguration({ env, preservedArgs }),
+      launcherArgs: [],
+      agentArgs: []
+    };
   }
   let launcherArgs;
   let agentArgs;
@@ -406,7 +558,63 @@ function captureRestartConfiguration(config, env, readArguments = readLegacyProc
       + `the existing Client was left running. ${error?.message || error}`
     );
   }
-  return buildLegacyClientRestartConfiguration({ env, launcherArgs, agentArgs });
+  return {
+    ...buildLegacyClientRestartConfiguration({ env, launcherArgs, agentArgs }),
+    launcherArgs,
+    agentArgs
+  };
+}
+
+export function resolveExactLocalRestoreLauncher(config, env, frozen) {
+  const candidates = [
+    env.LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER,
+    env.LIVEDESK_UNIFIED_LAUNCHER_ENTRY,
+    ...(Array.isArray(frozen?.launcherArgs) ? frozen.launcherArgs : [])
+  ]
+    .map(value => String(value || '').trim())
+    .filter(Boolean);
+  const checked = [];
+  for (const candidate of candidates) {
+    const entryPath = resolve(config.originalCwd, candidate);
+    if (!existsSync(entryPath) || checked.includes(entryPath)) continue;
+    checked.push(entryPath);
+    const productRoot = resolve(dirname(entryPath), '..');
+    const productManifestPath = join(productRoot, 'package.json');
+    const clientManifestPath = join(productRoot, 'client', 'package.json');
+    if (!existsSync(productManifestPath) || !existsSync(clientManifestPath)) continue;
+    let productManifest;
+    let clientManifest;
+    try {
+      productManifest = JSON.parse(readFileSync(productManifestPath, 'utf8'));
+      clientManifest = JSON.parse(readFileSync(clientManifestPath, 'utf8'));
+    } catch {
+      continue;
+    }
+    const productName = String(productManifest?.name || '');
+    const clientName = String(clientManifest?.name || '');
+    const productVersion = cleanVersion(productManifest?.version);
+    const bundledAgentVersion = cleanVersion(productManifest?.livedeskClientVersion);
+    const clientVersion = cleanVersion(clientManifest?.version);
+    if (productName !== 'livedesk'
+      || clientName !== '@livedesk/client'
+      || productVersion !== config.currentProductVersion
+      || clientVersion !== config.currentAgentVersion) {
+      continue;
+    }
+    if (bundledAgentVersion && bundledAgentVersion !== config.currentAgentVersion) continue;
+    return {
+      entryPath,
+      productRoot,
+      productManifestPath,
+      clientManifestPath,
+      productVersion,
+      agentVersion: clientVersion
+    };
+  }
+  throw new Error(
+    `LiveDesk could not freeze an exact local restore artifact for `
+    + `${config.currentProductVersion}/${config.currentAgentVersion}; the existing Client was left running.`
+  );
 }
 
 function readUpdateState(config) {
@@ -417,6 +625,176 @@ function readUpdateState(config) {
   }
 }
 
+function waitForUpdateStateLock(milliseconds) {
+  Atomics.wait(updateStateLockWaitBuffer, 0, 0, Math.max(1, milliseconds));
+}
+
+function updateStateLockPath(config) {
+  return `${config.statePath}.lock`;
+}
+
+function removeAbandonedUpdateStateLock(lockPath, aliveImpl, now) {
+  let owner = null;
+  try {
+    owner = JSON.parse(readFileSync(lockPath, 'utf8'));
+  } catch {
+    // A just-created lock can be observed before its owner record is written.
+  }
+  const ownerPid = positivePid(owner?.pid);
+  if (ownerPid > 1) {
+    if (aliveImpl(ownerPid)) return false;
+  } else {
+    try {
+      if (now() - statSync(lockPath).mtimeMs < UPDATE_STATE_EMPTY_LOCK_STALE_MS) return false;
+    } catch {
+      return true;
+    }
+  }
+  try {
+    rmSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function withLegacyClientUpdateStateLock(
+  config,
+  callback,
+  {
+    aliveImpl = isAlive,
+    now = Date.now,
+    timeoutMs = UPDATE_STATE_LOCK_TIMEOUT_MS,
+    pollMs = UPDATE_STATE_LOCK_POLL_MS
+  } = {}
+) {
+  const lockPath = updateStateLockPath(config);
+  const deadline = now() + Math.max(1, timeoutMs);
+  mkdirSync(dirname(lockPath), { recursive: true });
+  let descriptor = null;
+  let token = '';
+  while (descriptor === null) {
+    try {
+      descriptor = openSync(lockPath, 'wx', 0o600);
+      token = randomBytes(12).toString('hex');
+      writeFileSync(descriptor, JSON.stringify({
+        pid: process.pid,
+        token,
+        acquiredAt: new Date().toISOString()
+      }), 'utf8');
+    } catch (error) {
+      if (descriptor !== null) {
+        try { closeSync(descriptor); } catch { /* best effort */ }
+        descriptor = null;
+        try { rmSync(lockPath, { force: true }); } catch { /* failed owner initialization */ }
+      }
+      if (error?.code !== 'EEXIST') throw error;
+      if (removeAbandonedUpdateStateLock(lockPath, aliveImpl, now)) continue;
+      if (now() >= deadline) {
+        throw new Error(`Timed out waiting for the LiveDesk update state lock: ${lockPath}`);
+      }
+      waitForUpdateStateLock(Math.min(Math.max(1, pollMs), Math.max(1, deadline - now())));
+    }
+  }
+  try {
+    return callback();
+  } finally {
+    try { closeSync(descriptor); } catch { /* process teardown may have closed it */ }
+    try {
+      const owner = JSON.parse(readFileSync(lockPath, 'utf8'));
+      if (owner?.token === token && Number(owner?.pid) === process.pid) {
+        rmSync(lockPath, { force: true });
+      }
+    } catch {
+      // A killed owner leaves a stale lock for the next operation to reclaim.
+    }
+  }
+}
+
+export function assertLegacyClientUpdateOperationOwnership(
+  config,
+  readState = readUpdateState
+) {
+  const state = readState(config);
+  const actualOperationId = String(state?.operationId || '').trim();
+  if (actualOperationId && actualOperationId !== String(config?.operationId || '').trim()) {
+    throw new LegacyClientUpdateSupersededError(config?.operationId, actualOperationId);
+  }
+  if (actualOperationId
+    && actualOperationId === String(config?.operationId || '').trim()
+    && state?.cancelRequested === true) {
+    throw new LegacyClientUpdateSupersededError(
+      config?.operationId,
+      `${actualOperationId}:cancelled`
+    );
+  }
+  return state;
+}
+
+export function canReclaimLegacyClientUpdateOperation(previous, aliveImpl = isAlive) {
+  const handoffOwners = [
+    positivePid(previous?.supervisorPid),
+    positivePid(previous?.starterPid)
+  ].filter(pid => pid > 1);
+  if (handoffOwners.length > 0) {
+    return handoffOwners.every(pid => !aliveImpl(pid));
+  }
+  if (String(previous?.stage || '') === 'scheduled') {
+    const schedulingOwners = [
+      positivePid(previous?.agentPid),
+      positivePid(previous?.launcherPid)
+    ].filter(pid => pid > 1);
+    return schedulingOwners.length > 0
+      && schedulingOwners.every(pid => !aliveImpl(pid));
+  }
+  return false;
+}
+
+export function claimLegacyClientUpdateOperation(config, aliveImpl = isAlive, now = Date.now) {
+  return withLegacyClientUpdateStateLock(config, () => {
+    assertLegacyClientUpdateDeadline(config, now, 'operation claim');
+    const previous = readUpdateState(config);
+    const previousOperationId = String(previous?.operationId || '').trim();
+    if (previousOperationId === config.operationId) {
+      if (previous?.cancelRequested === true) {
+        throw new LegacyClientUpdateSupersededError(
+          config.operationId,
+          `${previousOperationId}:cancelled`
+        );
+      }
+      return previous;
+    }
+    if (previousOperationId && !TERMINAL_UPDATE_STAGES.has(String(previous?.stage || ''))) {
+      if (!canReclaimLegacyClientUpdateOperation(previous, aliveImpl)) {
+        throw new LegacyClientUpdateSupersededError(config.operationId, previousOperationId);
+      }
+    }
+    mkdirSync(dirname(config.statePath), { recursive: true });
+    const next = {
+      operationId: config.operationId,
+      stage: 'scheduled',
+      targetVersion: config.targetVersion,
+      targetProductVersion: config.targetProductVersion,
+      targetAgentVersion: config.targetVersion,
+      currentProductVersion: config.currentProductVersion,
+      updateDeadlineEpochMs: config.updateDeadlineEpochMs,
+      supervisorPid: process.pid,
+      claimedAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      restartVerified: false,
+      error: ''
+    };
+    const temporaryPath = `${config.statePath}.${process.pid}.${randomBytes(5).toString('hex')}.claim.tmp`;
+    try {
+      writeFileSync(temporaryPath, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
+      renameSync(temporaryPath, config.statePath);
+    } finally {
+      rmSync(temporaryPath, { force: true });
+    }
+    return next;
+  }, { aliveImpl, now });
+}
+
 function proofStatePath(config, attemptId) {
   const safeAttemptId = String(attemptId || '')
     .replace(/[^A-Za-z0-9._-]/g, '_')
@@ -424,29 +802,36 @@ function proofStatePath(config, attemptId) {
   return join(dirname(config.statePath), `client-update-proof-${safeAttemptId}.json`);
 }
 
-function writeUpdateState(config, stage, details = {}) {
-  mkdirSync(dirname(config.statePath), { recursive: true });
-  const previous = readUpdateState(config);
-  const next = {
-    ...(previous && previous.operationId === config.operationId ? previous : {}),
-    operationId: config.operationId,
-    stage,
-    targetVersion: config.targetVersion,
-    targetProductVersion: config.targetProductVersion,
-    targetAgentVersion: config.targetVersion,
-    currentProductVersion: config.currentProductVersion,
-    supervisorPid: process.pid,
-    updatedAt: new Date().toISOString(),
-    ...details
-  };
-  const temporaryPath = `${config.statePath}.${process.pid}.${randomBytes(5).toString('hex')}.tmp`;
-  try {
-    writeFileSync(temporaryPath, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
-    renameSync(temporaryPath, config.statePath);
-  } finally {
-    rmSync(temporaryPath, { force: true });
-  }
-  return next;
+export function writeUpdateState(config, stage, details = {}, { now = Date.now } = {}) {
+  return withLegacyClientUpdateStateLock(config, () => {
+    assertLegacyClientUpdateOperationOwnership(config);
+    if (stage === 'preflight-ready') {
+      assertLegacyClientUpdateDeadline(config, now, 'preflight-ready commit');
+    }
+    mkdirSync(dirname(config.statePath), { recursive: true });
+    const previous = readUpdateState(config);
+    const next = {
+      ...(previous && previous.operationId === config.operationId ? previous : {}),
+      operationId: config.operationId,
+      stage,
+      targetVersion: config.targetVersion,
+      targetProductVersion: config.targetProductVersion,
+      targetAgentVersion: config.targetVersion,
+      currentProductVersion: config.currentProductVersion,
+      updateDeadlineEpochMs: config.updateDeadlineEpochMs,
+      supervisorPid: process.pid,
+      updatedAt: new Date().toISOString(),
+      ...details
+    };
+    const temporaryPath = `${config.statePath}.${process.pid}.${randomBytes(5).toString('hex')}.tmp`;
+    try {
+      writeFileSync(temporaryPath, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
+      renameSync(temporaryPath, config.statePath);
+    } finally {
+      rmSync(temporaryPath, { force: true });
+    }
+    return next;
+  }, { now });
 }
 
 function isAlive(pid) {
@@ -463,13 +848,21 @@ function sleep(milliseconds) {
   return new Promise(resolve => setTimeout(resolve, milliseconds));
 }
 
-async function waitForExit(pid, timeoutMs, sleepImpl = sleep, aliveImpl = isAlive) {
+async function waitForExit(
+  pid,
+  timeoutMs,
+  sleepImpl = sleep,
+  aliveImpl = isAlive,
+  ownershipCheck = () => undefined
+) {
   if (pid <= 1) return true;
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
+    ownershipCheck();
     if (!aliveImpl(pid)) return true;
     await sleepImpl(200);
   }
+  ownershipCheck();
   return !aliveImpl(pid);
 }
 
@@ -600,8 +993,7 @@ function resolveNpxInvocation(args, env = process.env) {
   };
 }
 
-function spawnReplacement(version, preference, env = process.env, restartArgs = [], outputPath = '') {
-  const packageArgs = ['-y', preference, `livedesk@${version}`];
+export function spawnReplacement(version, preference, env = process.env, restartArgs = [], outputPath = '') {
   const roleArgs = [
     '--force-role',
     'client',
@@ -611,7 +1003,22 @@ function spawnReplacement(version, preference, env = process.env, restartArgs =
     '--device-id',
     env.LIVEDESK_DEVICE_ID
   ];
-  const invocation = resolveNpxInvocation([...packageArgs, ...roleArgs], env);
+  const localRestoreLauncher = String(env.LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER || '').trim();
+  const isLocalRestore = env.LIVEDESK_CLIENT_UPDATE_ATTEMPT_KIND === 'restore'
+    && localRestoreLauncher
+    && existsSync(localRestoreLauncher);
+  const invocation = isLocalRestore
+    ? { command: process.execPath, args: [localRestoreLauncher, ...roleArgs] }
+    : resolveNpxInvocation(['-y', preference, `livedesk@${version}`, ...roleArgs], env);
+  const neutralCwd = isLocalRestore
+    ? ''
+    : prepareNeutralCwd(env.LIVEDESK_UPDATE_NEUTRAL_CWD);
+  const replacementEnv = isLocalRestore
+    ? { ...env }
+    : buildLegacyClientUpdateNpxEnvironment(env, neutralCwd);
+  const replacementCwd = isLocalRestore
+    ? resolve(String(env.LIVEDESK_UPDATE_ORIGINAL_CWD || process.cwd()))
+    : neutralCwd;
   let outputFd = null;
   if (outputPath) {
     mkdirSync(dirname(outputPath), { recursive: true });
@@ -620,7 +1027,8 @@ function spawnReplacement(version, preference, env = process.env, restartArgs =
   let child;
   try {
     child = spawn(invocation.command, invocation.args, {
-      env,
+      env: replacementEnv,
+      cwd: replacementCwd,
       detached: true,
       stdio: outputFd === null ? 'ignore' : ['ignore', outputFd, outputFd],
       windowsHide: true
@@ -635,13 +1043,8 @@ function spawnReplacement(version, preference, env = process.env, restartArgs =
 }
 
 function hasLegacyConnectedOutput(outputPath, deviceId) {
-  if (!outputPath || !existsSync(outputPath)) return false;
-  let output = '';
-  try {
-    output = readFileSync(outputPath, 'utf8').slice(-256 * 1024);
-  } catch {
-    return false;
-  }
+  const output = readReplacementOutput(outputPath);
+  if (!output) return false;
   const escapedDeviceId = String(deviceId || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   if (!escapedDeviceId) return false;
   return new RegExp(
@@ -649,6 +1052,90 @@ function hasLegacyConnectedOutput(outputPath, deviceId) {
   ).test(output);
 }
 
+function readReplacementOutput(outputPath) {
+  if (!outputPath || !existsSync(outputPath)) return '';
+  try {
+    return readFileSync(outputPath, 'utf8').slice(-256 * 1024);
+  } catch {
+    return '';
+  }
+}
+
+function listWindowsProcessTree() {
+  const script = [
+    '$ErrorActionPreference = "Stop"',
+    '[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)',
+    'Get-CimInstance Win32_Process',
+    '| Select-Object ProcessId,ParentProcessId,Name,ExecutablePath,CommandLine',
+    '| ConvertTo-Json -Compress'
+  ].join(' ');
+  const encoded = Buffer.from(script, 'utf16le').toString('base64');
+  const result = spawnSync(
+    'powershell.exe',
+    ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded],
+    {
+      encoding: 'utf8',
+      timeout: PROCESS_ARGUMENT_QUERY_TIMEOUT_MS,
+      windowsHide: true
+    }
+  );
+  if (result.error || result.status !== 0) return [];
+  try {
+    const parsed = JSON.parse(String(result.stdout || '').trim() || '[]');
+    return (Array.isArray(parsed) ? parsed : [parsed]).map(item => ({
+      pid: positivePid(item?.ProcessId),
+      parentPid: positivePid(item?.ParentProcessId),
+      command: `${item?.Name || ''} ${item?.ExecutablePath || ''} ${item?.CommandLine || ''}`
+    }));
+  } catch {
+    return [];
+  }
+}
+
+function listPosixProcessTree() {
+  const result = spawnSync('ps', ['-axo', 'pid=,ppid=,comm=,command='], {
+    encoding: 'utf8',
+    timeout: PROCESS_ARGUMENT_QUERY_TIMEOUT_MS
+  });
+  if (result.error || result.status !== 0) return [];
+  return String(result.stdout || '')
+    .split(/\r?\n/)
+    .map(line => line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s*(.*)$/))
+    .filter(Boolean)
+    .map(match => ({
+      pid: positivePid(match[1]),
+      parentPid: positivePid(match[2]),
+      command: `${match[3] || ''} ${match[4] || ''}`
+    }));
+}
+
+export function findLegacyRestoreAgentProcess(
+  launcherPid,
+  platform = process.platform,
+  listProcesses = platform === 'win32' ? listWindowsProcessTree : listPosixProcessTree
+) {
+  const rootPid = positivePid(launcherPid);
+  if (!rootPid) return null;
+  const processes = listProcesses().filter(item => item.pid > 1);
+  const byParent = new Map();
+  for (const item of processes) {
+    const children = byParent.get(item.parentPid) || [];
+    children.push(item);
+    byParent.set(item.parentPid, children);
+  }
+  const queue = [...(byParent.get(rootPid) || [])];
+  const descendants = [];
+  while (queue.length > 0) {
+    const next = queue.shift();
+    descendants.push(next);
+    queue.push(...(byParent.get(next.pid) || []));
+  }
+  return descendants.find(item => (
+    /livedesk-client-fast|livedesk-client-node|MindExec\.RemoteAgent\.Fast|RemoteAgent\.Fast/i
+      .test(String(item.command || ''))
+  )) || null;
+}
+
 async function terminateReplacementTree(child) {
   const pid = positivePid(child?.pid);
   if (pid <= 1) return;
@@ -658,9 +1145,23 @@ async function terminateReplacementTree(child) {
         windowsHide: true,
         stdio: 'ignore'
       });
-      killer.once('error', resolve);
-      killer.once('exit', resolve);
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        try { killer.kill('SIGKILL'); } catch { /* taskkill already stopped */ }
+        finish();
+      }, 10_000);
+      killer.once('error', finish);
+      killer.once('exit', finish);
     });
+    if (isAlive(pid)) {
+      try { child.kill('SIGKILL'); } catch { /* best effort after bounded taskkill */ }
+    }
     return;
   }
   try {
@@ -674,10 +1175,23 @@ async function terminateReplacementTree(child) {
   }
 }
 
-async function terminateOldRuntime(config, { sleepImpl = sleep, aliveImpl = isAlive } = {}) {
+async function terminateOldRuntime(
+  config,
+  {
+    sleepImpl = sleep,
+    aliveImpl = isAlive,
+    ownershipCheck = () => undefined,
+    deadlineCheck = () => undefined
+  } = {}
+) {
+  ownershipCheck();
   if (config.launcherPid <= 1) throw new Error('legacy update has no valid launcher PID');
   const victims = [...new Set([config.launcherPid, config.agentPid].filter(pid => pid > 1 && pid !== process.pid))];
+  // This is the last side-effect-free boundary. Once the first signal is sent,
+  // expiry recovery can no longer promise that the unchanged Client survives.
+  deadlineCheck();
   for (const pid of victims) {
+    ownershipCheck();
     try {
       process.kill(pid, 'SIGTERM');
     } catch {
@@ -685,6 +1199,7 @@ async function terminateOldRuntime(config, { sleepImpl = sleep, aliveImpl = isAl
     }
   }
   await sleepImpl(2500);
+  ownershipCheck();
   for (const pid of victims) {
     if (!aliveImpl(pid)) continue;
     try {
@@ -693,8 +1208,20 @@ async function terminateOldRuntime(config, { sleepImpl = sleep, aliveImpl = isAl
       // Already stopped.
     }
   }
-  const launcherExited = await waitForExit(config.launcherPid, 15_000, sleepImpl, aliveImpl);
-  const agentExited = await waitForExit(config.agentPid, 15_000, sleepImpl, aliveImpl);
+  const launcherExited = await waitForExit(
+    config.launcherPid,
+    15_000,
+    sleepImpl,
+    aliveImpl,
+    ownershipCheck
+  );
+  const agentExited = await waitForExit(
+    config.agentPid,
+    15_000,
+    sleepImpl,
+    aliveImpl,
+    ownershipCheck
+  );
   if (!launcherExited || !agentExited) {
     throw new Error(`old runtime did not exit launcher=${launcherExited} agent=${agentExited}`);
   }
@@ -715,6 +1242,8 @@ export async function launchAndVerifyLegacyClientReplacement(
   const aliveImpl = options.aliveImpl || isAlive;
   const now = options.now || Date.now;
   const log = options.log || (() => undefined);
+  const ownershipCheck = options.assertOperationOwnership
+    || (() => assertLegacyClientUpdateOperationOwnership(config));
   const attemptId = String(
     options.attemptId
     || `${config.operationId}-${kind}-${attempt}-${randomBytes(5).toString('hex')}`
@@ -746,10 +1275,16 @@ export async function launchAndVerifyLegacyClientReplacement(
     LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION: agentVersion,
     LIVEDESK_CLIENT_UPDATE_TARGET_VERSION: agentVersion,
     LIVEDESK_CLIENT_UPDATE_STATE_PATH: proofConfig.statePath,
+    LIVEDESK_UPDATE_NEUTRAL_CWD: config.neutralCwd,
+    LIVEDESK_UPDATE_ORIGINAL_CWD: config.originalCwd,
+    LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER: kind === 'restore'
+      ? String(config.localRestoreLauncher?.entryPath || '')
+      : '',
     LIVEDESK_CLIENT_RUNTIME_PORT: String(config.runtimePort),
     LIVEDESK_DEVICE_ID: config.deviceId,
     LIVEDESK_SKIP_BROWSER_OPEN: '1'
   };
+  ownershipCheck();
   writeState(config, `${kind}-launching`, {
     attemptId,
     attemptKind: kind,
@@ -760,6 +1295,7 @@ export async function launchAndVerifyLegacyClientReplacement(
     restartVerified: false,
     error: ''
   });
+  ownershipCheck();
   const child = await (options.spawnReplacement || spawnReplacement)(
     version,
     preference,
@@ -778,12 +1314,51 @@ export async function launchAndVerifyLegacyClientReplacement(
   let verifiedSince = null;
   let lastVerified = null;
   let terminalProofFailure = false;
+  let legacyRestoreAgent = null;
   while (now() < deadline) {
     try {
+      ownershipCheck();
       const state = readProofState();
       let proof;
       let proofSource = 'agent-state';
-      try {
+      let verified;
+      const localRestoreArtifact = kind === 'restore'
+        ? config.localRestoreLauncher
+        : null;
+      const restoreWelcomeObserved = !!localRestoreArtifact
+        && (options.hasLegacyConnectedOutput || hasLegacyConnectedOutput)(
+          outputPath,
+          config.deviceId
+        );
+      const restoreArtifactMatches = cleanVersion(localRestoreArtifact?.productVersion) === cleanVersion(version)
+        && cleanVersion(localRestoreArtifact?.agentVersion) === cleanVersion(agentVersion);
+      if (restoreWelcomeObserved && restoreArtifactMatches) {
+        if (!legacyRestoreAgent || !aliveImpl(positivePid(legacyRestoreAgent.pid))) {
+          legacyRestoreAgent = await (
+            options.findLegacyRestoreAgentProcess
+            || findLegacyRestoreAgentProcess
+          )(pid);
+        }
+        const restoreAgentPid = positivePid(legacyRestoreAgent?.pid);
+        if (pid <= 1 || !aliveImpl(pid)) {
+          throw new Error('exact local restore launcher exited during verification');
+        }
+        if (restoreAgentPid <= 1 || !aliveImpl(restoreAgentPid)) {
+          throw new Error('exact local restore Agent descendant is not running');
+        }
+        proof = {
+          launcherPid: pid,
+          agentPid: restoreAgentPid,
+          productVersion: version,
+          agentVersion
+        };
+        proofSource = 'legacy-hub-welcome-process-tree';
+        verified = {
+          runtimePid: pid,
+          agentPid: restoreAgentPid,
+          appVersion: version
+        };
+      } else {
         proof = validateLegacyClientConnectedProof(state, {
           operationId: config.operationId,
           attemptId,
@@ -791,22 +1366,13 @@ export async function launchAndVerifyLegacyClientReplacement(
           agentVersion,
           previousRuntimePid: config.launcherPid
         });
-      } catch (proofError) {
-        const restoreWelcomeObserved = kind === 'restore'
-          && (options.hasLegacyConnectedOutput || hasLegacyConnectedOutput)(
-            outputPath,
-            config.deviceId
-          );
-        if (!restoreWelcomeObserved) throw proofError;
-        proof = null;
-        proofSource = 'legacy-welcome-output';
+        const status = await requestStatus(config.runtimePort);
+        verified = validateLegacyClientReplacementStatus(status, {
+          deviceId: config.deviceId,
+          productVersion: version,
+          previousRuntimePid: config.launcherPid
+        });
       }
-      const status = await requestStatus(config.runtimePort);
-      const verified = validateLegacyClientReplacementStatus(status, {
-        deviceId: config.deviceId,
-        productVersion: version,
-        previousRuntimePid: config.launcherPid
-      });
       if (!proof) {
         proof = {
           launcherPid: verified.runtimePid,
@@ -828,6 +1394,7 @@ export async function launchAndVerifyLegacyClientReplacement(
       lastVerified = { ...verified, proof, proofSource };
       if (verifiedSince === null) verifiedSince = now();
       if (now() - verifiedSince >= (options.verifyStableMs ?? VERIFY_STABLE_MS)) {
+        ownershipCheck();
         log(
           `${kind} attempt=${attempt} id=${attemptId} verified `
           + `launcher=${verified.runtimePid} agent=${verified.agentPid} `
@@ -855,6 +1422,11 @@ export async function launchAndVerifyLegacyClientReplacement(
         return { ...verified, agentVersion: proof.agentVersion, attemptId };
       }
     } catch (error) {
+      if (isLegacyClientUpdateSupersededError(error)) {
+        await (options.terminateReplacementTree || terminateReplacementTree)(child);
+        if (!options.readUpdateState) rmSync(proofConfig.statePath, { force: true });
+        throw error;
+      }
       lastError = error;
       const state = readProofState();
       terminalProofFailure = state?.stage === 'connected'
@@ -873,6 +1445,7 @@ export async function launchAndVerifyLegacyClientReplacement(
     `${kind} attempt=${attempt} did not become healthy: `
     + `${lastError?.message || (lastVerified ? 'runtime did not remain stable' : 'verification deadline expired')}`
   );
+  ownershipCheck();
   writeState(config, `${kind}-attempt-failed`, {
     attemptId,
     attemptKind: kind,
@@ -886,17 +1459,50 @@ export async function launchAndVerifyLegacyClientReplacement(
 }
 
 export async function runLegacyClientUpdateSupervisor(options = {}) {
-  const env = options.env || process.env;
+  const env = expandLegacyBridgeEnvironment(options.env || process.env);
   const config = readConfig(env);
   const log = createLogger(config, options.writeLog);
-  const persistState = options.writeUpdateState || writeUpdateState;
+  const now = options.now || Date.now;
+  const persistState = options.writeUpdateState
+    || ((value, stage, details) => writeUpdateState(value, stage, details, { now }));
+  const ownershipCheck = options.assertOperationOwnership
+    || (() => assertLegacyClientUpdateOperationOwnership(config));
+  const claimOperation = options.claimOperation
+    || (() => claimLegacyClientUpdateOperation(config, options.aliveImpl || isAlive, now));
   const productManifest = options.productManifest || readManifest('../package.json');
   const clientManifest = options.clientManifest || readManifest('../client/package.json');
   const sleepImpl = options.sleepImpl || sleep;
   const terminateOld = options.terminateOldRuntime || (value => terminateOldRuntime(value, {
     sleepImpl,
-    aliveImpl: options.aliveImpl || isAlive
+    aliveImpl: options.aliveImpl || isAlive,
+    ownershipCheck,
+    deadlineCheck: () => ensureDeadline('old-runtime termination')
   }));
+  const cancelExpiredDeadline = (error, checkpoint) => {
+    try {
+      persistState(config, 'failed', {
+        restartVerified: false,
+        cancelRequested: true,
+        deadlineExpired: true,
+        deadlineCheckpoint: checkpoint,
+        deadlineExpiredAt: new Date(now()).toISOString(),
+        failedAt: new Date(now()).toISOString(),
+        error: String(error?.message || error).slice(0, 4000)
+      });
+    } catch {
+      // A concurrent cancellation/supersession already makes the operation inert.
+    }
+  };
+  const ensureDeadline = checkpoint => {
+    try {
+      return assertLegacyClientUpdateDeadline(config, now, checkpoint);
+    } catch (error) {
+      if (isLegacyClientUpdateDeadlineExpiredError(error)) {
+        cancelExpiredDeadline(error, checkpoint);
+      }
+      throw error;
+    }
+  };
   const attemptReplacement = options.attemptReplacement || ((
     version,
     kind,
@@ -915,7 +1521,8 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
       ...options,
       env,
       log,
-      sleepImpl
+      sleepImpl,
+      assertOperationOwnership: ownershipCheck
       }
     )
   ));
@@ -931,6 +1538,7 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
     || config.agentPid <= 1) {
     throw new Error('legacy update configuration is incomplete');
   }
+  ensureDeadline('configuration validation');
   if (cleanVersion(productManifest.version) !== config.targetProductVersion) {
     throw new Error(`prepared product mismatch expected=${config.targetProductVersion} actual=${productManifest.version || 'unknown'}`);
   }
@@ -938,6 +1546,7 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
     || cleanVersion(clientManifest.version) !== config.targetVersion) {
     throw new Error(`prepared Agent mismatch expected=${config.targetVersion} bundled=${productManifest.livedeskClientVersion || 'unknown'} client=${clientManifest.version || 'unknown'}`);
   }
+  config.neutralCwd = prepareNeutralCwd(config.neutralCwd);
   const frozen = (options.captureRestartConfiguration || captureRestartConfiguration)(
     config,
     env,
@@ -945,21 +1554,49 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
   );
   config.restartArgs = [...frozen.restartArgs];
   config.runtimePort = frozen.runtimePort;
+  config.localRestoreLauncher = (
+    options.resolveExactLocalRestoreLauncher
+    || resolveExactLocalRestoreLauncher
+  )(config, env, frozen);
   log(`options-frozen count=${config.restartArgs.length} runtimePort=${config.runtimePort} engine=${frozen.engine}`);
-  persistState(config, 'preflight-ready', {
-    runtimePort: config.runtimePort,
-    engine: frozen.engine,
-    restartArgCount: config.restartArgs.length,
-    restartVerified: false,
-    error: ''
-  });
+  log(
+    `restore-frozen launcher=${config.localRestoreLauncher.entryPath} `
+    + `version=${config.localRestoreLauncher.productVersion}/${config.localRestoreLauncher.agentVersion}`
+  );
+  ensureDeadline('operation claim');
+  claimOperation();
+  ownershipCheck();
+  ensureDeadline('preflight-ready commit');
+  try {
+    persistState(config, 'preflight-ready', {
+      runtimePort: config.runtimePort,
+      engine: frozen.engine,
+      restartArgCount: config.restartArgs.length,
+      restartVerified: false,
+      error: ''
+    });
+  } catch (error) {
+    if (isLegacyClientUpdateDeadlineExpiredError(error)) {
+      cancelExpiredDeadline(error, 'preflight-ready commit');
+    }
+    throw error;
+  }
   log(`preflight-ready target=${config.targetProductVersion}/${config.targetVersion}`);
-  await waitForExit(config.starterPid, 10_000, sleepImpl, options.aliveImpl || isAlive);
+  await waitForExit(
+    config.starterPid,
+    10_000,
+    sleepImpl,
+    options.aliveImpl || isAlive,
+    ownershipCheck
+  );
+  ownershipCheck();
+  ensureDeadline('old-runtime termination');
   log(`stopping launcher=${config.launcherPid} agent=${config.agentPid}`);
   await terminateOld(config);
 
   const targetErrors = [];
   for (let attempt = 1; attempt <= TARGET_ATTEMPT_LIMIT; attempt += 1) {
+    ownershipCheck();
     try {
       await attemptReplacement(
         config.targetProductVersion,
@@ -968,6 +1605,7 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
         '--prefer-online',
         config.targetVersion
       );
+      ownershipCheck();
       log(`completed target=${config.targetProductVersion}/${config.targetVersion}`);
       persistState(config, 'connected', {
         restartVerified: true,
@@ -976,6 +1614,7 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
       });
       return { outcome: 'updated', attempt };
     } catch (error) {
+      if (isLegacyClientUpdateSupersededError(error)) throw error;
       targetErrors.push(String(error?.message || error));
       log(`target attempt=${attempt} failed error=${error?.message || error}`);
     }
@@ -986,6 +1625,7 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
   }
   const restoreErrors = [];
   for (let attempt = 1; attempt <= RESTORE_ATTEMPT_LIMIT; attempt += 1) {
+    ownershipCheck();
     try {
       await attemptReplacement(
         config.currentProductVersion,
@@ -994,6 +1634,7 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
         '--prefer-offline',
         config.currentAgentVersion
       );
+      ownershipCheck();
       log(`restored version=${config.currentProductVersion}`);
       persistState(config, 'restored', {
         productVersion: config.currentProductVersion,
@@ -1009,6 +1650,7 @@ export async function runLegacyClientUpdateSupervisor(options = {}) {
         error: `Target ${config.targetProductVersion} failed verification: ${targetErrors.join(' | ')}`
       };
     } catch (error) {
+      if (isLegacyClientUpdateSupersededError(error)) throw error;
       restoreErrors.push(String(error?.message || error));
       log(`restore attempt=${attempt} failed error=${error?.message || error}`);
     }
@@ -1027,14 +1669,16 @@ export async function runLegacyClientUpdateSupervisorCli() {
     const config = readConfig();
     const log = createLogger(config);
     log(`failed error=${error?.stack || error}`);
-    try {
-      writeUpdateState(config, 'failed', {
-        restartVerified: false,
-        failedAt: new Date().toISOString(),
-        error: String(error?.message || error).slice(0, 4000)
-      });
-    } catch {
-      // The persistent log remains the fallback on a read-only state directory.
+    if (!isLegacyClientUpdateSupersededError(error)) {
+      try {
+        writeUpdateState(config, 'failed', {
+          restartVerified: false,
+          failedAt: new Date().toISOString(),
+          error: String(error?.message || error).slice(0, 4000)
+        });
+      } catch {
+        // The persistent log remains the fallback on a read-only state directory.
+      }
     }
     console.error(error?.message || error);
     process.exitCode = 1;