@livedesk/client 0.1.169 → 0.1.170

package/bin/livedesk-client-node.js

@@ -9,14 +9,15 @@ import { spawn } from 'child_process';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const AGENT_VERSION = (() => {
+const AGENT_VERSION = (() => {
     try {
         return String(require('../package.json').version || '0.0.0');
     } catch {
         return '0.0.0';
-    }
-})();
-const DEFAULT_MANAGER = '127.0.0.1:5197';
+    }
+})();
+const PRODUCT_VERSION = String(process.env.LIVEDESK_NPM_LAUNCHER_VERSION || AGENT_VERSION).trim() || AGENT_VERSION;
+const DEFAULT_MANAGER = '127.0.0.1:5197';
 const DEFAULT_HEARTBEAT_MS = 5000;
 const DEFAULT_RECONNECT_MS = 5000;
 const EXIT_INVALID_PAIR_TOKEN = 23;
@@ -29,7 +30,118 @@ const MAX_AI_OUTPUT_CHARS = 6000;
 const MAX_FILE_TRANSFER_FILES = 24;
 const MAX_FILE_TRANSFER_BYTES = 24 * 1024 * 1024;
 const MAX_AGENT_OUTPUT_CHARS = 32000;
-const launchedProcessRegistry = new Map();
+const launchedProcessRegistry = new Map();
+const CLIENT_UPDATE_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+function normalizeClientUpdateTargetVersion(value) {
+    const version = String(value || '').trim().replace(/^v/i, '');
+    if (!version) return '';
+    if (!CLIENT_UPDATE_VERSION_PATTERN.test(version)) {
+        throw new Error(`Invalid LiveDesk product update version: ${version}`);
+    }
+    return version;
+}
+
+function getClientUpdateStatePath() {
+    return String(process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH || path.join(os.homedir(), '.livedesk', 'client-update.json'));
+}
+
+async function writeClientUpdateState(stage, details = {}) {
+    const statePath = getClientUpdateStatePath();
+    const operationId = String(details.operationId || process.env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || '').trim();
+    if (!operationId) return;
+    let previous = null;
+    try {
+        previous = JSON.parse(await fs.readFile(statePath, 'utf8'));
+    } catch {
+        // The first update stage creates the file.
+    }
+    const replacesTerminalOperation = previous?.operationId
+        && previous.operationId !== operationId
+        && stage === 'scheduled'
+        && ['connected', 'failed', 'restored'].includes(String(previous.stage || ''));
+    if (previous?.operationId && previous.operationId !== operationId && !replacesTerminalOperation) return;
+    const targetProductVersion = String(
+        details.targetProductVersion
+        || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION
+        || (!replacesTerminalOperation ? previous?.targetProductVersion : '')
+        || ''
+    ).trim();
+    const targetAgentVersion = String(
+        details.targetAgentVersion
+        || details.targetVersion
+        || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION
+        || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION
+        || (!replacesTerminalOperation ? previous?.targetAgentVersion : '')
+        || (!replacesTerminalOperation ? previous?.targetVersion : '')
+        || ''
+    ).trim();
+    const state = {
+        ...(!replacesTerminalOperation && previous && typeof previous === 'object' ? previous : {}),
+        operationId,
+        stage,
+        targetVersion: targetAgentVersion,
+        targetProductVersion,
+        targetAgentVersion,
+        productVersion: PRODUCT_VERSION,
+        agentVersion: AGENT_VERSION,
+        agentPid: process.pid,
+        launcherPid: Number(process.env.LIVEDESK_CLIENT_PARENT_PID || 0) || 0,
+        attemptId: String(details.attemptId || process.env.LIVEDESK_CLIENT_UPDATE_ATTEMPT_ID || '').trim(),
+        updatedAt: new Date().toISOString(),
+        ...details
+    };
+    await fs.mkdir(path.dirname(statePath), { recursive: true });
+    const temporaryPath = `${statePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    try {
+        await fs.writeFile(temporaryPath, JSON.stringify(state, null, 2), { encoding: 'utf8', mode: 0o600 });
+        await fs.rename(temporaryPath, statePath);
+    } finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+
+async function waitForClientUpdateShutdownSignal(operationId, timeoutMs = 150_000) {
+    const statePath = getClientUpdateStatePath();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+            if (state?.operationId !== operationId) {
+                await wait(200);
+                continue;
+            }
+            if (state.stage === 'waiting-for-shutdown') return true;
+            if (state.stage === 'failed') {
+                console.error(`LiveDesk client update preparation failed: ${state.error || 'unknown error'}`);
+                return false;
+            }
+        } catch {
+            // The detached supervisor may still be writing its first stage.
+        }
+        await wait(200);
+    }
+    await writeClientUpdateState('failed', {
+        operationId,
+        error: 'Timed out waiting for the LiveDesk update supervisor to prepare the exact package.'
+    }).catch(() => undefined);
+    console.error('LiveDesk client update preparation timed out; the current Agent will remain running.');
+    return false;
+}
+
+function markClientUpdateConnected() {
+    const operationId = String(process.env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || '').trim();
+    if (!operationId) return;
+    void writeClientUpdateState('connected', {
+        operationId,
+        attemptId: String(process.env.LIVEDESK_CLIENT_UPDATE_ATTEMPT_ID || '').trim(),
+        connectedAt: new Date().toISOString(),
+        restartVerified: true,
+        error: ''
+    }).catch(error => {
+        console.error(`LiveDesk client update diagnostics could not be persisted: ${error?.message || error}`);
+    });
+}
 
 function printHelp() {
     console.log(`
@@ -1318,76 +1430,165 @@ function remotePolicyAllows(options, command) {
     return denied ? { ok: false, error: `${denied}-blocked-by-settings` } : { ok: true };
 }
 
-function buildClientUpdateBootstrapScript() {
-    return [
-        'const { spawn } = require("node:child_process");',
+function buildClientUpdateBootstrapScript() {
+    return [
+        'const { spawn, spawnSync } = require("node:child_process");',
         'const fs = require("node:fs");',
         'const path = require("node:path");',
+        'const crypto = require("node:crypto");',
         '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 launcher did not exit before update installation."); };',
-        'const nodeDir = path.dirname(process.execPath);',
+        'const operationId = String(process.env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || "").trim();',
+        'const statePath = String(process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH || path.join(require("node:os").homedir(), ".livedesk", "client-update.json"));',
+        'const logPath = statePath.replace(/\\.json$/i, "") + ".log";',
+        'const cleanVersion = value => String(value || "").trim().replace(/^v/i, "");',
+        'const versionPattern = /^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/;',
+        'const targetProductVersion = cleanVersion(process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION);',
+        'const targetAgentVersion = cleanVersion(process.env.LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION || targetProductVersion);',
+        'const currentProductVersion = cleanVersion(process.env.LIVEDESK_CLIENT_UPDATE_CURRENT_PRODUCT_VERSION || process.env.LIVEDESK_NPM_LAUNCHER_VERSION);',
+        'const currentAgentVersion = cleanVersion(process.env.LIVEDESK_CLIENT_UPDATE_CURRENT_AGENT_VERSION || process.env.LIVEDESK_CLIENT_PACKAGE_VERSION || currentProductVersion);',
+        'for (const [label, version] of [["target product", targetProductVersion], ["target Agent", targetAgentVersion], ["current product", currentProductVersion], ["current Agent", currentAgentVersion]]) { if (!versionPattern.test(version)) throw new Error("Invalid LiveDesk " + label + " update version: " + version); }',
+        'const packageSpec = "livedesk@" + targetProductVersion;',
+        'const localLauncher = String(process.env.LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER || process.env.LIVEDESK_UNIFIED_LAUNCHER_ENTRY || "").trim();',
+        'const preservedArgs = (() => { try { const decoded = JSON.parse(Buffer.from(String(process.env.LIVEDESK_CLIENT_UPDATE_ARGS_BASE64 || ""), "base64").toString("utf8")); return Array.isArray(decoded) ? decoded.map(value => String(value)) : []; } catch { return []; } })();',
+        'const proofTimeoutMs = Math.max(500, Number(process.env.LIVEDESK_CLIENT_UPDATE_PROOF_TIMEOUT_MS || 30000));',
+        'const proofPollMs = Math.max(25, Number(process.env.LIVEDESK_CLIENT_UPDATE_PROOF_POLL_MS || 200));',
+        'const killGraceMs = Math.max(50, Number(process.env.LIVEDESK_CLIENT_UPDATE_KILL_GRACE_MS || 1500));',
+        'const targetLaunchLimit = 3;',
+        'const restoreLaunchLimit = 2;',
+        'const readState = () => { try { return JSON.parse(fs.readFileSync(statePath, "utf8")); } catch { return {}; } };',
+        'const writeState = (stage, details = {}) => { fs.mkdirSync(path.dirname(statePath), { recursive: true }); const previous = readState(); const replacesTerminalOperation = previous.operationId && previous.operationId !== operationId && stage === "preparing-package" && ["connected", "failed", "restored"].includes(String(previous.stage || "")); if (previous.operationId && previous.operationId !== operationId && !replacesTerminalOperation) return false; const base = replacesTerminalOperation ? {} : previous; const next = { ...base, operationId, stage, targetVersion: targetAgentVersion, targetProductVersion, targetAgentVersion, currentProductVersion, currentAgentVersion, supervisorPid: process.pid, updatedAt: new Date().toISOString(), ...details }; const temporary = statePath + "." + process.pid + "." + Math.random().toString(16).slice(2) + ".tmp"; fs.writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 }); fs.renameSync(temporary, statePath); return true; };',
+        'const log = message => { try { fs.mkdirSync(path.dirname(logPath), { recursive: true }); fs.appendFileSync(logPath, new Date().toISOString() + " " + message + "\\n", "utf8"); } catch {} };',
+        'const isAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };',
+        'const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));',
+        'const waitForExit = async (pid, timeoutMs) => { const deadline = Date.now() + timeoutMs; while (pid > 1 && Date.now() < deadline) { if (!isAlive(pid)) return true; await sleep(250); } return pid <= 1 || !isAlive(pid); };',
+        'const killProcessTree = async pid => { if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid) return; if (process.platform === "win32") { spawnSync("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }); } else { try { process.kill(-pid, "SIGTERM"); } catch { try { process.kill(pid, "SIGTERM"); } catch {} } await sleep(killGraceMs); try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch {} } } await waitForExit(pid, killGraceMs); };',
+        'const ensureExit = async (pid, label) => { if (pid <= 1 || await waitForExit(pid, 20000)) return; log(label + " pid=" + pid + " did not exit gracefully; terminating its process tree."); await killProcessTree(pid); if (isAlive(pid)) throw new Error(label + " process " + pid + " did not exit before restart."); };',
+        '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 => candidate && (!path.isAbsolute(candidate) || fs.existsSync(candidate)));',
-        'if (!npx) throw new Error("LiveDesk npx executable was not found.");',
+        'if (!npx) { writeState("failed", { error: "LiveDesk npx executable was not found." }); throw new Error("LiveDesk npx executable was not found."); }',
         '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);',
+        'const quoteCmd = value => "\\"" + String(value).replaceAll("%", "%%").replaceAll("\\"", "\\"\\"") + "\\"";',
+        'const invocation = npxArgs => npxCli ? { command: process.execPath, args: [npxCli, ...npxArgs] } : process.platform === "win32" ? { command: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", "call " + quoteCmd(npx) + " " + npxArgs.map(quoteCmd).join(" ")] } : { command: npx, args: npxArgs };',
+        'const runToExit = (npxArgs, timeoutMs) => new Promise((resolve, reject) => { const call = invocation(npxArgs); const child = spawn(call.command, call.args, { env: process.env, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }); let stdout = ""; let stderr = ""; let settled = false; child.stdout?.on("data", chunk => { stdout = (stdout + chunk.toString()).slice(-65536); }); child.stderr?.on("data", chunk => { stderr = (stderr + chunk.toString()).slice(-65536); }); const timer = setTimeout(() => { if (settled) return; settled = true; void killProcessTree(child.pid || 0).finally(() => reject(new Error("LiveDesk package preparation timed out."))); }, timeoutMs); child.once("error", error => { if (settled) return; settled = true; clearTimeout(timer); reject(error); }); child.once("exit", (code, signal) => { if (settled) return; settled = true; clearTimeout(timer); resolve({ code: code ?? -1, signal, stdout, stderr }); }); });',
+        'const attempts = [];',
+        'const attemptIdFor = (kind, number) => operationId + "-" + kind + "-" + number + "-" + crypto.randomBytes(4).toString("hex");',
+        'const updateAttempt = (attempt, patch) => { Object.assign(attempt, patch, { updatedAt: new Date().toISOString() }); return attempts.map(item => ({ ...item })); };',
+        'const killAttempt = async (restartPid, attemptId) => { const state = readState(); const pids = new Set([Number(restartPid || 0)]); if (state.operationId === operationId && state.attemptId === attemptId) { pids.add(Number(state.launcherPid || 0)); pids.add(Number(state.agentPid || 0)); } for (const pid of pids) await killProcessTree(pid); };',
+        'const launchAndVerify = async ({ kind, number, expectedProductVersion, expectedAgentVersion, call }) => { const attemptId = attemptIdFor(kind, number); const attempt = { attemptId, kind, number, status: "launching", expectedProductVersion, expectedAgentVersion, startedAt: new Date().toISOString() }; attempts.push(attempt); const attemptEnv = { ...process.env, LIVEDESK_CLIENT_UPDATE_ATTEMPT_ID: attemptId, LIVEDESK_CLIENT_UPDATE_ATTEMPT_KIND: kind, LIVEDESK_CLIENT_UPDATE_ATTEMPT_NUMBER: String(number), LIVEDESK_CLIENT_UPDATE_OPERATION_ID: operationId, LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION: targetProductVersion, LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION: targetAgentVersion, LIVEDESK_CLIENT_UPDATE_TARGET_VERSION: targetAgentVersion }; const logFd = fs.openSync(logPath, "a"); let child; try { child = spawn(call.command, call.args, { cwd: process.env.LIVEDESK_CLIENT_UPDATE_CWD || process.cwd(), env: attemptEnv, detached: true, windowsHide: true, stdio: ["ignore", logFd, logFd] }); await new Promise((resolve, reject) => { child.once("error", reject); child.once("spawn", resolve); }); } finally { fs.closeSync(logFd); } const restartPid = Number(child?.pid || 0); updateAttempt(attempt, { status: "waiting-for-connected-proof", restartPid }); writeState(kind + "-launched", { attemptId, attemptKind: kind, attemptNumber: number, restartPid, attempts: attempts.map(item => ({ ...item })), restartVerified: false, error: "" }); let exitResult = null; child.once("exit", (code, signal) => { exitResult = { code, signal }; }); const deadline = Date.now() + proofTimeoutMs; let proof = null; let failure = ""; while (Date.now() < deadline) { const state = readState(); if (state.operationId === operationId && state.attemptId === attemptId && state.stage === "connected") { const observedProduct = cleanVersion(state.productVersion); const observedAgent = cleanVersion(state.agentVersion); if (observedProduct === expectedProductVersion && observedAgent === expectedAgentVersion) { proof = state; break; } failure = "Connected version mismatch expected product " + expectedProductVersion + " / Agent " + expectedAgentVersion + ", observed product " + (observedProduct || "unknown") + " / Agent " + (observedAgent || "unknown") + "."; break; } if (exitResult) { failure = "Launcher exited before exact connected proof (code=" + (exitResult.code ?? "none") + ", signal=" + (exitResult.signal || "none") + ")."; break; } await sleep(proofPollMs); } if (proof) { updateAttempt(attempt, { status: "connected", connectedAt: proof.connectedAt || new Date().toISOString(), productVersion: cleanVersion(proof.productVersion), agentVersion: cleanVersion(proof.agentVersion) }); if (child && !exitResult) child.unref(); writeState(kind === "target" ? "connected" : "restored", { attemptId, attemptKind: kind, attemptNumber: number, restartPid, launcherPid: Number(proof.launcherPid || 0), agentPid: Number(proof.agentPid || 0), productVersion: cleanVersion(proof.productVersion), agentVersion: cleanVersion(proof.agentVersion), attempts: attempts.map(item => ({ ...item })), restartVerified: kind === "target", restored: kind === "restore", connectedAt: proof.connectedAt || new Date().toISOString(), error: kind === "restore" ? "Target update failed; previous local Client was restored." : "" }); return true; } failure = failure || "Timed out waiting for exact connected proof for " + attemptId + "."; await killAttempt(restartPid, attemptId); updateAttempt(attempt, { status: "failed", failedAt: new Date().toISOString(), killed: true, error: failure }); writeState(kind + "-attempt-failed", { attemptId, attemptKind: kind, attemptNumber: number, restartPid, attempts: attempts.map(item => ({ ...item })), restartVerified: false, error: failure }); log(attemptId + " failed: " + failure); return false; };',
         '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 scheduleClientUpdate(options, payload = {}) {
-    const configuredParentPid = Number(process.env.LIVEDESK_CLIENT_PARENT_PID || process.ppid);
-    const parentPid = Number.isInteger(configuredParentPid) && configuredParentPid > 1
-        ? configuredParentPid
-        : process.pid;
-    if (!Number.isInteger(parentPid) || parentPid <= 1) {
-        return Promise.reject(new Error('LiveDesk client launcher process id is unavailable.'));
-    }
-    const nodeBinDir = path.dirname(process.execPath);
-    const npxCandidates = process.platform === 'win32'
-        ? [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeBinDir, 'npx.cmd'), path.join(nodeBinDir, 'npx.exe'), 'npx.cmd']
-        : [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeBinDir, 'npx'), 'npx'];
-    const command = npxCandidates.find(candidate => candidate && (!path.isAbsolute(candidate) || existsSync(candidate)));
-    if (!command) {
-        return Promise.reject(new Error('LiveDesk npx executable was not found.'));
-    }
-    return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, ['-e', buildClientUpdateBootstrapScript()], {
-            env: {
-                ...process.env,
-                LIVEDESK_NODE_EXECUTABLE: process.execPath,
-                LIVEDESK_NPX_EXECUTABLE: command,
-                LIVEDESK_UPDATE_WAIT_PID: String(parentPid),
-                LIVEDESK_UPDATE_AGENT_PID: String(process.pid),
-                LIVEDESK_SKIP_BROWSER_OPEN: '1',
-                LIVEDESK_CLIENT_UPDATE_TARGET_VERSION: String(payload.targetVersion || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION || '')
-            },
-            detached: true,
-            stdio: 'ignore',
-            windowsHide: true
-        });
-        child.once('error', reject);
-        child.once('spawn', () => {
-            child.unref();
-            resolve({
-                ok: true,
-                status: 'update-scheduled',
-                targetVersion: String(payload.targetVersion || ''),
-                parentPid,
-                restartAfterMs: 500
-            });
-        });
-    });
-}
+        '(async () => { writeState("preparing-package", { packageSpec, attempts: [], error: "" }); log("preparing " + packageSpec); const prepared = await runToExit(["-y", "--prefer-online", packageSpec, "--version"], 120000); if (prepared.code !== 0) throw new Error("LiveDesk package preparation failed (exit=" + prepared.code + "): " + (prepared.stderr || prepared.stdout).trim().slice(-2000)); const stdoutVersions = prepared.stdout.split(/\\r?\\n/).map(line => line.trim()).filter(line => versionPattern.test(line)); if (!stdoutVersions.includes(targetProductVersion)) throw new Error("Prepared LiveDesk stdout did not report requested product version " + targetProductVersion + ". stdout=" + prepared.stdout.trim().slice(-1000)); writeState("waiting-for-shutdown", { observedVersion: targetProductVersion, observedProductVersion: targetProductVersion, preparedAt: new Date().toISOString(), attempts: [], error: "" }); log("package ready product=" + targetProductVersion + "; waiting for current runtime shutdown"); await ensureExit(agentPid, "Agent"); await ensureExit(waitPid, "Launcher"); const roleArgs = ["--force-role", "client", "--no-login", "--no-open", ...preservedArgs]; const targetCall = invocation(["-y", "--prefer-online", packageSpec, ...roleArgs]); for (let number = 1; number <= targetLaunchLimit; number += 1) { if (await launchAndVerify({ kind: "target", number, expectedProductVersion: targetProductVersion, expectedAgentVersion: targetAgentVersion, call: targetCall })) { log("target connected with exact product " + targetProductVersion + " / Agent " + targetAgentVersion); return; } } writeState("restoring", { attempts: attempts.map(item => ({ ...item })), error: "All target launch attempts failed; restoring previous local Client." }); const restoreCall = localLauncher && fs.existsSync(localLauncher) ? { command: process.execPath, args: [localLauncher, ...roleArgs] } : invocation(["-y", "--prefer-offline", "livedesk@" + currentProductVersion, ...roleArgs]); for (let number = 1; number <= restoreLaunchLimit; number += 1) { if (await launchAndVerify({ kind: "restore", number, expectedProductVersion: currentProductVersion, expectedAgentVersion: currentAgentVersion, call: restoreCall })) { log("previous local Client restored at product " + currentProductVersion + " / Agent " + currentAgentVersion); process.exitCode = 1; return; } } throw new Error("Target update failed after 3 attempts and previous local Client restoration failed after 2 attempts."); })().catch(error => { const message = error?.stack || error?.message || String(error); log("failed: " + message); try { writeState("failed", { attempts: attempts.map(item => ({ ...item })), error: String(error?.message || error).slice(0, 4000), failedAt: new Date().toISOString(), restartVerified: false }); } catch {} process.exitCode = 1; });',
+        ''
+    ].join('\n');
+}
+
+async function scheduleClientUpdate(options, payload = {}) {
+    const operationId = String(payload.operationId || crypto.randomUUID()).trim();
+    const statePath = getClientUpdateStatePath();
+    let targetProductVersion = '';
+    let targetAgentVersion = '';
+    try {
+        targetProductVersion = normalizeClientUpdateTargetVersion(
+            payload.targetProductVersion
+            || payload.productVersion
+            || payload.managerVersion
+            || payload.targetVersion
+            || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION
+            || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION
+            || ''
+        );
+        targetAgentVersion = normalizeClientUpdateTargetVersion(
+            payload.targetAgentVersion
+            || payload.clientVersion
+            || payload.targetVersion
+            || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION
+            || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION
+            || targetProductVersion
+            || ''
+        );
+        await writeClientUpdateState('scheduled', {
+            operationId,
+            targetVersion: targetAgentVersion,
+            targetProductVersion,
+            targetAgentVersion,
+            requestedAt: new Date().toISOString(),
+            restartVerified: false,
+            error: ''
+        });
+        const configuredParentPid = Number(process.env.LIVEDESK_CLIENT_PARENT_PID || process.ppid);
+        const parentPid = Number.isInteger(configuredParentPid) && configuredParentPid > 1
+            ? configuredParentPid
+            : process.pid;
+        if (!Number.isInteger(parentPid) || parentPid <= 1) {
+            throw new Error('LiveDesk client launcher process id is unavailable.');
+        }
+        const nodeBinDir = path.dirname(process.execPath);
+        const npxCandidates = process.platform === 'win32'
+            ? [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeBinDir, 'npx.cmd'), path.join(nodeBinDir, 'npx.exe'), 'npx.cmd']
+            : [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeBinDir, 'npx'), 'npx'];
+        const command = npxCandidates.find(candidate => candidate && (!path.isAbsolute(candidate) || existsSync(candidate)));
+        if (!command) {
+            throw new Error('LiveDesk npx executable was not found.');
+        }
+        return await new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, ['-e', buildClientUpdateBootstrapScript()], {
+                env: {
+                    ...process.env,
+                    LIVEDESK_NODE_EXECUTABLE: process.execPath,
+                    LIVEDESK_NPX_EXECUTABLE: command,
+                    LIVEDESK_UPDATE_WAIT_PID: String(parentPid),
+                    LIVEDESK_UPDATE_AGENT_PID: String(process.pid),
+                    LIVEDESK_SKIP_BROWSER_OPEN: '1',
+                    LIVEDESK_CLIENT_UPDATE_TARGET_VERSION: targetAgentVersion,
+                    LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION: targetProductVersion,
+                    LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION: targetAgentVersion,
+                    LIVEDESK_CLIENT_UPDATE_CURRENT_PRODUCT_VERSION: PRODUCT_VERSION,
+                    LIVEDESK_CLIENT_UPDATE_CURRENT_AGENT_VERSION: AGENT_VERSION,
+                    LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER: String(
+                        process.env.LIVEDESK_UNIFIED_LAUNCHER_ENTRY
+                        || process.env.LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER
+                        || ''
+                    ),
+                    LIVEDESK_CLIENT_UPDATE_OPERATION_ID: operationId,
+                    LIVEDESK_CLIENT_UPDATE_STATE_PATH: statePath,
+                    LIVEDESK_CLIENT_UPDATE_CWD: process.cwd()
+                },
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: true
+            });
+            child.once('error', reject);
+            child.once('spawn', () => {
+                child.unref();
+                resolve({
+                    ok: true,
+                    status: 'update-scheduled',
+                    targetVersion: targetAgentVersion,
+                    targetProductVersion,
+                    targetAgentVersion,
+                    operationId,
+                    statePath,
+                    parentPid,
+                    restartAfterMs: 0
+                });
+            });
+        });
+    } catch (error) {
+        await writeClientUpdateState('failed', {
+            operationId,
+            targetVersion: targetAgentVersion,
+            targetProductVersion,
+            targetAgentVersion,
+            error: error?.message || String(error),
+            failedAt: new Date().toISOString(),
+            restartVerified: false
+        }).catch(() => undefined);
+        throw error;
+    }
+}
 
 async function handleRemoteCommand(socket, options, message, nextFrameSeq, activeStreams) {
     const command = String(message.command || '');
@@ -1414,16 +1615,18 @@ async function handleRemoteCommand(socket, options, message, nextFrameSeq, activ
         return;
     }
 
-    if (command === 'livedesk.client-update') {
-        try {
-            const result = await scheduleClientUpdate(options, message.payload || {});
+    if (command === 'livedesk.client-update') {
+        try {
+            const result = await scheduleClientUpdate(options, message.payload || {});
             writeJsonLine(socket, {
                 type: 'command.result',
-                commandId: message.commandId,
-                result
-            });
-            setTimeout(() => process.exit(EXIT_CLIENT_UPDATE), 500);
-        } catch (error) {
+                commandId: message.commandId,
+                result
+            });
+            if (await waitForClientUpdateShutdownSignal(result.operationId)) {
+                process.exit(EXIT_CLIENT_UPDATE);
+            }
+        } catch (error) {
             writeJsonLine(socket, {
                 type: 'command.result',
                 commandId: message.commandId,
@@ -1751,9 +1954,10 @@ function connectOnce(options, deviceId) {
                 hostname: os.hostname(),
                 platform: os.platform(),
                 arch: os.arch(),
-                pid: process.pid,
-                agentVersion: AGENT_VERSION,
-                capabilities: {
+                pid: process.pid,
+                agentVersion: AGENT_VERSION,
+                productVersion: PRODUCT_VERSION,
+                capabilities: {
                     status: true,
                     thumbnail: options.thumbnailEnabled,
                     liveStream: options.liveEnabled,
@@ -1768,7 +1972,8 @@ function connectOnce(options, deviceId) {
                     fileTransferMaxBytes: MAX_FILE_TRANSFER_BYTES,
                     computerAgent: options.taskEnabled,
                     taskDispatch: options.taskEnabled,
-                    clientUpdate: true,
+                    clientUpdate: true,
+                    productVersion: PRODUCT_VERSION,
                     agentApproval: options.taskEnabled,
                     agentAudit: options.taskEnabled,
                     agentTools: [...NODE_AGENT_OPERATIONS],
@@ -1793,11 +1998,12 @@ function connectOnce(options, deviceId) {
                 }
 
                 const message = JSON.parse(line);
-                if (message.type === 'welcome') {
+                if (message.type === 'welcome') {
                     options.effectivePolicy = message.effectivePolicy && typeof message.effectivePolicy === 'object'
                         ? message.effectivePolicy
                         : null;
-                    console.log(`Connected to LiveDesk Hub as ${options.name} (${deviceId})`);
+                    console.log(`Connected to LiveDesk Hub as ${options.name} (${deviceId})`);
+                    markClientUpdateConnected();
                     writeJsonLine(socket, {
                         type: 'status',
                         status: getStatus(options)

package/bin/livedesk-client.js

@@ -46,6 +46,8 @@ const CLIENT_AUTH_STORAGE_KEY = 'livedesk.client.supabase.auth';
 const CLIENT_HUB_TARGET_CACHE_STORAGE_KEY = 'livedesk.client.last-hub-target';
 const DEVICE_ROLE_CACHE_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'device-role.json');
 const FAST_PREFLIGHT_CACHE_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'fast-preflight.json');
+const CLIENT_UPDATE_STATE_PATH = process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH
+    || join(UNIFIED_CLIENT_STATE_DIR, 'client-update.json');
 let activeAgentProcess = null;
 let roleRestartRequest = null;
 let discoveryWakeController = new AbortController();
@@ -377,7 +379,7 @@ function upsertForwardedOption(args, flag, value) {
     return next;
 }
 
-function appendForwardedFlag(args, flag) {
+function appendForwardedFlag(args, flag) {
     if (args.includes(flag)) {
         return args;
     }
@@ -550,6 +552,83 @@ function createFileStorage(filePath) {
     };
 }
 
+const CLIENT_UPDATE_SINGLE_FLAGS = new Set([
+    '--help',
+    '-h',
+    '--version',
+    '--login',
+    '--logout',
+    '--no-login',
+    '--startup-run',
+    '--no-open',
+    '--exit-on-disconnect',
+    '--exit-on-invalid-pair',
+    '--once'
+]);
+const CLIENT_UPDATE_VALUE_FLAGS = new Set([
+    '--update-wait-pid',
+    // Pairing credentials stay in the inherited private environment and must
+    // never be copied onto a replacement process command line.
+    '--pair'
+]);
+
+export function buildClientUpdateRestartArgs(prepared = {}) {
+    const source = Array.isArray(prepared.forwarded) ? prepared.forwarded : [];
+    const args = [];
+    for (let index = 0; index < source.length; index += 1) {
+        const arg = String(source[index] || '');
+        if (!arg || arg === 'connect' || CLIENT_UPDATE_SINGLE_FLAGS.has(arg)) {
+            continue;
+        }
+        if (arg.startsWith('--pair=')) {
+            continue;
+        }
+        if (CLIENT_UPDATE_VALUE_FLAGS.has(arg)) {
+            index += 1;
+            continue;
+        }
+        args.push(arg);
+    }
+    return args;
+}
+
+function readClientUpdateState() {
+    try {
+        return JSON.parse(readFileSync(CLIENT_UPDATE_STATE_PATH, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function writeClientUpdateRuntimeStage(stage, details = {}) {
+    const operationId = String(process.env.LIVEDESK_CLIENT_UPDATE_OPERATION_ID || '').trim();
+    if (!operationId) return;
+    const previous = readClientUpdateState();
+    if (previous?.operationId && previous.operationId !== operationId) return;
+    const targetVersion = String(process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION || '').trim().replace(/^v/i, '');
+    const productVersion = String(process.env.LIVEDESK_NPM_LAUNCHER_VERSION || readPackageVersion()).trim();
+    const state = {
+        ...(previous && typeof previous === 'object' ? previous : {}),
+        operationId,
+        stage,
+        targetVersion,
+        productVersion,
+        agentVersion: readPackageVersion(),
+        launcherPid: process.pid,
+        updatedAt: new Date().toISOString(),
+        ...details
+    };
+    mkdirSync(dirname(CLIENT_UPDATE_STATE_PATH), { recursive: true });
+    const temporaryPath = `${CLIENT_UPDATE_STATE_PATH}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        writeFileSync(temporaryPath, JSON.stringify(state, null, 2), 'utf8');
+        try { chmodSync(temporaryPath, 0o600); } catch { /* Windows profile ACLs remain authoritative. */ }
+        renameSync(temporaryPath, CLIENT_UPDATE_STATE_PATH);
+    } catch {
+        rmSync(temporaryPath, { force: true });
+    }
+}
+
 function hubCacheOwnerForSession(session) {
     const userId = String(session?.user?.id || '').trim();
     return userId ? `user:${userId}` : '';
@@ -3487,7 +3566,7 @@ function resolveBundledFfmpegPaths() {
     return paths;
 }
 
-function buildClientAgentEnvironment(prepared) {
+function buildClientAgentEnvironment(prepared) {
     const env = { ...process.env };
     env.LIVEDESK_CLIENT_PARENT_PID = String(process.pid);
     // The client can be started by Explorer, a startup shortcut, or a GUI shell
@@ -3515,10 +3594,14 @@ function buildClientAgentEnvironment(prepared) {
     env.LIVEDESK_CLIENT_MANAGER = String(prepared?.manager || env.LIVEDESK_CLIENT_MANAGER || '');
     env.LIVEDESK_CLIENT_PAIR_TOKEN = String(prepared?.pair || env.LIVEDESK_CLIENT_PAIR_TOKEN || '');
     env.LIVEDESK_CLIENT_NAME = String(prepared?.name || env.LIVEDESK_CLIENT_NAME || '');
-    env.LIVEDESK_CLIENT_SLOT = String(prepared?.slot || env.LIVEDESK_CLIENT_SLOT || '');
-    env.LIVEDESK_CLIENT_ENGINE = String(prepared?.engine || env.LIVEDESK_CLIENT_ENGINE || 'auto');
-    return env;
-}
+    env.LIVEDESK_CLIENT_SLOT = String(prepared?.slot || env.LIVEDESK_CLIENT_SLOT || '');
+    env.LIVEDESK_CLIENT_ENGINE = String(prepared?.engine || env.LIVEDESK_CLIENT_ENGINE || 'auto');
+    env.LIVEDESK_CLIENT_UPDATE_STATE_PATH = CLIENT_UPDATE_STATE_PATH;
+    env.LIVEDESK_CLIENT_UPDATE_ARGS_BASE64 = Buffer
+        .from(JSON.stringify(buildClientUpdateRestartArgs(prepared)), 'utf8')
+        .toString('base64');
+    return env;
+}
 
 function buildFastEnvironment(prepared) {
     const env = buildClientAgentEnvironment(prepared);
@@ -3721,13 +3804,17 @@ function resolveFastLaunch(runtime) {
     };
 }
 
-function spawnAgent(command, args, env = process.env, onStart = null) {
+function spawnAgent(command, args, env = process.env, onStart = null) {
     const child = spawn(command, args, {
         env,
         stdio: 'inherit',
         windowsHide: true
     });
-    activeAgentProcess = child;
+    activeAgentProcess = child;
+    writeClientUpdateRuntimeStage('agent-started', {
+        agentPid: Number(child.pid || 0),
+        restartVerified: false
+    });
     if (typeof onStart === 'function') {
         onStart(child);
     }
@@ -3771,10 +3858,13 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
     if (!isTruthy(process.env.LIVEDESK_UNIFIED_RUNTIME)) {
         console.warn('[LiveDesk] @livedesk/client is deprecated. Use the unified livedesk package or LiveDesk Desktop.');
     }
-    const parsed = parseLauncherArgs(argv);
-    if (parsed.updateWaitPid) {
-        await waitForProcessExit(parsed.updateWaitPid);
-    }
+    const parsed = parseLauncherArgs(argv);
+    if (parsed.updateWaitPid) {
+        await waitForProcessExit(parsed.updateWaitPid);
+    }
+    writeClientUpdateRuntimeStage('launcher-started', {
+        restartVerified: false
+    });
     if (parsed.help) {
         printHelp();
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.169",
+  "version": "0.1.170",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -39,10 +39,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.373",
-    "@livedesk/fast-osx-arm64": "0.1.375",
-    "@livedesk/fast-osx-x64": "0.1.375",
-    "@livedesk/fast-win-x64": "0.1.373"
+    "@livedesk/fast-linux-x64": "0.1.374",
+    "@livedesk/fast-osx-arm64": "0.1.376",
+    "@livedesk/fast-osx-x64": "0.1.376",
+    "@livedesk/fast-win-x64": "0.1.374"
   },
   "publishConfig": {
     "access": "public"