@livedesk/client 0.1.169 → 0.1.171

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,133 @@ 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;
+    const attemptId = stage === 'scheduled'
+        ? ''
+        : String(details.attemptId || process.env.LIVEDESK_CLIENT_UPDATE_ATTEMPT_ID || '').trim();
+    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;
+    if (!replacesTerminalOperation
+        && previous?.attemptId
+        && attemptId
+        && previous.attemptId !== attemptId) {
+        return;
+    }
+    if (!replacesTerminalOperation
+        && previous?.stage === 'connected'
+        && previous?.restartVerified === true
+        && stage !== 'connected') {
+        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,
+        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 === 'preflight-ready' || 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 +1445,137 @@ 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 } = require("node:child_process");',
         'const fs = require("node:fs");',
         'const path = require("node:path");',
-        'const waitPid = Number(process.env.LIVEDESK_UPDATE_WAIT_PID || 0);',
-        'const agentPid = Number(process.env.LIVEDESK_UPDATE_AGENT_PID || 0);',
-        'const isAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };',
-        'const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));',
-        'const waitForExit = async pid => { for (let attempt = 0; attempt < 360 && pid > 1; attempt += 1) { if (!isAlive(pid)) return; await sleep(500); } if (pid > 1 && isAlive(pid)) throw new Error("LiveDesk client launcher did not exit before update installation."); };',
-        'const nodeDir = path.dirname(process.execPath);',
-        'const npxCandidates = process.platform === "win32" ? [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeDir, "npx.cmd"), path.join(nodeDir, "npx.exe"), "npx.cmd"] : [process.env.LIVEDESK_NPX_EXECUTABLE, path.join(nodeDir, "npx"), "npx"];',
-        'const npx = npxCandidates.find(candidate => candidate && (!path.isAbsolute(candidate) || fs.existsSync(candidate)));',
-        'if (!npx) 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);',
-        '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
-            });
-        });
-    });
-}
+        '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 cleanVersion = value => String(value || "").trim().replace(/^v/i, "");',
+        'const targetProductVersion = cleanVersion(process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION);',
+        'const versionPattern = /^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/;',
+        'const readState = () => { try { return JSON.parse(fs.readFileSync(statePath, "utf8")); } catch { return {}; } };',
+        'const writeFailure = error => { try { fs.mkdirSync(path.dirname(statePath), { recursive: true }); const previous = readState(); if (previous.operationId && previous.operationId !== operationId) return; const now = new Date().toISOString(); const next = { ...previous, operationId, stage: "failed", targetProductVersion, restartVerified: false, error: String(error?.message || error).slice(0, 4000), failedAt: now, updatedAt: now }; const temporary = statePath + "." + process.pid + ".handoff.tmp"; fs.writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 }); fs.renameSync(temporary, statePath); } catch {} process.stderr.write("LiveDesk update handoff failed: " + (error?.message || error) + "\\n"); process.exitCode = 1; };',
+        'const monitorPreflight = child => { let settled = false; const finish = (error, preserveFailure = false) => { if (settled) return; settled = true; clearInterval(poll); clearTimeout(timeout); child.unref(); if (preserveFailure) process.exitCode = 1; else if (error) writeFailure(error); }; const inspect = () => { const state = readState(); if (state.operationId !== operationId) return; if (state.stage === "preflight-ready" || state.stage === "waiting-for-shutdown") finish(); else if (state.stage === "failed") finish(null, true); }; const poll = setInterval(inspect, 100); const timeout = setTimeout(() => { try { child.kill(); } catch {} finish(new Error("Timed out waiting for exact-package update preflight.")); }, Math.max(1000, Number(process.env.LIVEDESK_CLIENT_UPDATE_HANDOFF_TIMEOUT_MS || 140000))); child.once("exit", (code, signal) => { inspect(); if (!settled) finish(new Error("Exact-package update supervisor exited before preflight (code=" + (code ?? "none") + ", signal=" + (signal || "none") + ").")); }); inspect(); };',
+        'if (!operationId || !versionPattern.test(targetProductVersion)) { writeFailure(new Error("Invalid LiveDesk exact-package update handoff.")); } else {',
+        'const env = { ...process.env, LIVEDESK_UPDATE_STARTER_PID: String(process.pid) };',
+        'const nodeDir = path.dirname(process.execPath);',
+        'const npxCli = [env.LIVEDESK_NPX_CLI_PATH, env.npm_execpath ? path.join(path.dirname(env.npm_execpath), "npx-cli.js") : "", env.LIVEDESK_NPX_EXECUTABLE ? path.join(path.dirname(env.LIVEDESK_NPX_EXECUTABLE), "node_modules", "npm", "bin", "npx-cli.js") : "", path.join(nodeDir, "node_modules", "npm", "bin", "npx-cli.js")].find(value => value && fs.existsSync(value));',
+        'const npx = env.LIVEDESK_NPX_EXECUTABLE || (process.platform === "win32" ? "npx.cmd" : "npx");',
+        'const args = ["-y", "--prefer-online", "livedesk@" + targetProductVersion, "--internal-legacy-client-update"];',
+        'const quoteCmd = value => "\\"" + String(value).replaceAll("%", "%%").replaceAll("\\"", "\\"\\"") + "\\"";',
+        'const invocation = npxCli ? { command: process.execPath, args: [npxCli, ...args] } : process.platform === "win32" ? { command: env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", "call " + quoteCmd(npx) + " " + args.map(quoteCmd).join(" ")] } : { command: npx, args };',
+        'if (!npxCli && path.isAbsolute(npx) && !fs.existsSync(npx)) { writeFailure(new Error("LiveDesk npx executable was not found: " + npx)); } else { try { const child = spawn(invocation.command, invocation.args, { env, detached: true, stdio: "ignore", windowsHide: true }); child.once("error", writeFailure); child.once("spawn", () => monitorPreflight(child)); } catch (error) { writeFailure(error); } }',
+        '}',
+        ''
+    ].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 +1602,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 +1941,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 +1959,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 +1985,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,91 @@ 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 attemptId = String(process.env.LIVEDESK_CLIENT_UPDATE_ATTEMPT_ID || '').trim();
+    const previous = readClientUpdateState();
+    if (previous?.operationId && previous.operationId !== operationId) return;
+    if (previous?.attemptId && attemptId && previous.attemptId !== attemptId) return;
+    if (previous?.stage === 'connected'
+        && previous?.restartVerified === true
+        && stage !== 'connected') {
+        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,
+        attemptId,
+        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 +3574,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
@@ -3513,12 +3600,17 @@ function buildClientAgentEnvironment(prepared) {
         env.LIVEDESK_NPX_CLI_PATH = npxCliPath;
     }
     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_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_DEVICE_ID = String(prepared?.deviceId || env.LIVEDESK_DEVICE_ID || '');
+    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 +3813,20 @@ function resolveFastLaunch(runtime) {
     };
 }
 
-function spawnAgent(command, args, env = process.env, onStart = null) {
-    const child = spawn(command, args, {
-        env,
-        stdio: 'inherit',
-        windowsHide: true
-    });
-    activeAgentProcess = child;
+function spawnAgent(command, args, env = process.env, onStart = null) {
+    // Publish only a pre-spawn stage. A very fast child can reach Hub welcome
+    // before spawn() returns; a post-spawn write would then erase its one-shot
+    // connected proof.
+    writeClientUpdateRuntimeStage('agent-launching', {
+        agentPid: 0,
+        restartVerified: false
+    });
+    const child = spawn(command, args, {
+        env,
+        stdio: 'inherit',
+        windowsHide: true
+    });
+    activeAgentProcess = child;
     if (typeof onStart === 'function') {
         onStart(child);
     }
@@ -3771,10 +3870,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.171",
   "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.377",
+    "@livedesk/fast-osx-arm64": "0.1.377",
+    "@livedesk/fast-osx-x64": "0.1.377",
+    "@livedesk/fast-win-x64": "0.1.377"
   },
   "publishConfig": {
     "access": "public"