@livedesk/client 0.1.170 → 0.1.172

package/bin/livedesk-client-node.js

@@ -43,13 +43,93 @@ function normalizeClientUpdateTargetVersion(value) {
 }
 
 function getClientUpdateStatePath() {
-    return String(process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH || path.join(os.homedir(), '.livedesk', 'client-update.json'));
+    return path.resolve(
+        String(process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH || path.join(os.homedir(), '.livedesk', 'client-update.json'))
+    );
+}
+
+function getClientUpdateNeutralCwd(operationId) {
+    const safeOperationId = String(operationId || '')
+        .replace(/[^A-Za-z0-9._-]/g, '_')
+        .slice(0, 120) || 'unknown';
+    return path.join(os.tmpdir(), 'livedesk-update-cwd', `client-${safeOperationId}`);
+}
+
+async function prepareClientUpdateNeutralCwd(operationId) {
+    const neutralCwd = path.resolve(getClientUpdateNeutralCwd(operationId));
+    await fs.mkdir(neutralCwd, { recursive: true });
+    for (let ancestor = neutralCwd; ; ancestor = path.dirname(ancestor)) {
+        const shadowPath = [
+            path.join(ancestor, 'package.json'),
+            path.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 = path.dirname(ancestor);
+        if (parent === ancestor) break;
+    }
+    return neutralCwd;
+}
+
+function buildClientUpdateNpxEnvironment(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 isClientUpdatePidAlive(value) {
+    const pid = Number(value);
+    if (!Number.isInteger(pid) || pid <= 1) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        return error?.code === 'EPERM';
+    }
+}
+
+function canReclaimClientUpdateOperation(previous) {
+    const handoffOwners = [
+        previous?.supervisorPid,
+        previous?.starterPid
+    ].map(Number).filter(pid => Number.isInteger(pid) && pid > 1);
+    if (handoffOwners.length > 0) {
+        return handoffOwners.every(pid => !isClientUpdatePidAlive(pid));
+    }
+    if (String(previous?.stage || '') === 'scheduled') {
+        const schedulingOwners = [
+            previous?.agentPid,
+            previous?.launcherPid
+        ].map(Number).filter(pid => Number.isInteger(pid) && pid > 1);
+        return schedulingOwners.length > 0
+            && schedulingOwners.every(pid => !isClientUpdatePidAlive(pid));
+    }
+    return false;
 }
 
 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'));
@@ -60,11 +140,28 @@ async function writeClientUpdateState(stage, details = {}) {
         && previous.operationId !== operationId
         && stage === 'scheduled'
         && ['connected', 'failed', 'restored'].includes(String(previous.stage || ''));
-    if (previous?.operationId && previous.operationId !== operationId && !replacesTerminalOperation) return;
+    const reclaimsDeadOperation = previous?.operationId
+        && previous.operationId !== operationId
+        && stage === 'scheduled'
+        && canReclaimClientUpdateOperation(previous);
+    const replacesPreviousOperation = replacesTerminalOperation || reclaimsDeadOperation;
+    if (previous?.operationId && previous.operationId !== operationId && !replacesPreviousOperation) return;
+    if (!replacesPreviousOperation
+        && previous?.attemptId
+        && attemptId
+        && previous.attemptId !== attemptId) {
+        return;
+    }
+    if (!replacesPreviousOperation
+        && 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 : '')
+        || (!replacesPreviousOperation ? previous?.targetProductVersion : '')
         || ''
     ).trim();
     const targetAgentVersion = String(
@@ -72,12 +169,12 @@ async function writeClientUpdateState(stage, details = {}) {
         || details.targetVersion
         || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_AGENT_VERSION
         || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION
-        || (!replacesTerminalOperation ? previous?.targetAgentVersion : '')
-        || (!replacesTerminalOperation ? previous?.targetVersion : '')
+        || (!replacesPreviousOperation ? previous?.targetAgentVersion : '')
+        || (!replacesPreviousOperation ? previous?.targetVersion : '')
         || ''
     ).trim();
     const state = {
-        ...(!replacesTerminalOperation && previous && typeof previous === 'object' ? previous : {}),
+        ...(!replacesPreviousOperation && previous && typeof previous === 'object' ? previous : {}),
         operationId,
         stage,
         targetVersion: targetAgentVersion,
@@ -87,7 +184,7 @@ async function writeClientUpdateState(stage, details = {}) {
         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(),
+        attemptId,
         updatedAt: new Date().toISOString(),
         ...details
     };
@@ -95,15 +192,33 @@ async function writeClientUpdateState(stage, details = {}) {
     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 });
+        let current = null;
+        try {
+            current = JSON.parse(await fs.readFile(statePath, 'utf8'));
+        } catch {
+            // A missing first-write state is still owned by this transition.
+        }
+        if (String(current?.operationId || '') !== String(previous?.operationId || '')
+            || String(current?.stage || '') !== String(previous?.stage || '')
+            || String(current?.updatedAt || '') !== String(previous?.updatedAt || '')) {
+            return;
+        }
         await fs.rename(temporaryPath, statePath);
     } finally {
         await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
     }
 }
 
-async function waitForClientUpdateShutdownSignal(operationId, timeoutMs = 150_000) {
+async function waitForClientUpdateShutdownSignal(
+    operationId,
+    updateDeadlineEpochMs,
+    timeoutMs = 180_000
+) {
     const statePath = getClientUpdateStatePath();
-    const deadline = Date.now() + timeoutMs;
+    const deadline = Math.min(
+        Date.now() + timeoutMs,
+        Number(updateDeadlineEpochMs) || 0
+    );
     while (Date.now() < deadline) {
         try {
             const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
@@ -111,22 +226,32 @@ async function waitForClientUpdateShutdownSignal(operationId, timeoutMs = 150_00
                 await wait(200);
                 continue;
             }
-            if (state.stage === 'waiting-for-shutdown') return true;
+            if (state.stage === 'preflight-ready' || state.stage === 'waiting-for-shutdown') {
+                return { ready: true, error: '' };
+            }
             if (state.stage === 'failed') {
-                console.error(`LiveDesk client update preparation failed: ${state.error || 'unknown error'}`);
-                return false;
+                const error = String(state.error || 'LiveDesk client update preparation failed.');
+                console.error(`LiveDesk client update preparation failed: ${error}`);
+                return { ready: false, error };
             }
         } catch {
             // The detached supervisor may still be writing its first stage.
         }
         await wait(200);
     }
+    const deadlineExpired = Date.now() >= Number(updateDeadlineEpochMs);
+    const error = deadlineExpired
+        ? 'The absolute LiveDesk Client update deadline expired before shutdown.'
+        : 'Timed out waiting for the LiveDesk update supervisor to prepare the exact package.';
     await writeClientUpdateState('failed', {
         operationId,
-        error: 'Timed out waiting for the LiveDesk update supervisor to prepare the exact package.'
+        error,
+        cancelRequested: true,
+        deadlineExpired,
+        failedAt: new Date().toISOString()
     }).catch(() => undefined);
     console.error('LiveDesk client update preparation timed out; the current Agent will remain running.');
-    return false;
+    return { ready: false, error };
 }
 
 function markClientUpdateConnected() {
@@ -1432,55 +1557,43 @@ function remotePolicyAllows(options, command) {
 
 function buildClientUpdateBootstrapScript() {
     return [
-        'const { spawn, spawnSync } = require("node:child_process");',
+        'const { spawn } = 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 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 originalCwd = path.resolve(String(process.env.LIVEDESK_UPDATE_ORIGINAL_CWD || process.cwd()));',
+        'const statePath = path.resolve(originalCwd, String(process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH || path.join(require("node:os").homedir(), ".livedesk", "client-update.json")));',
+        'const neutralCwdValue = String(process.env.LIVEDESK_UPDATE_NEUTRAL_CWD || "").trim();',
+        'const neutralCwd = neutralCwdValue ? path.resolve(neutralCwdValue) : "";',
         '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 updateDeadlineEpochMs = Number(process.env.LIVEDESK_CLIENT_UPDATE_DEADLINE_EPOCH_MS || 0);',
+        'const deadlineExpired = () => !Number.isSafeInteger(updateDeadlineEpochMs) || Date.now() >= updateDeadlineEpochMs;',
+        '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 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 isAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; } };',
+        'const isGroupAlive = pid => { try { process.kill(-pid, 0); return true; } catch (error) { return error?.code === "EPERM"; } };',
+        'const stateLockPath = statePath + ".lock"; const lockWaitBuffer = new Int32Array(new SharedArrayBuffer(4));',
+        'const waitForStateLock = ms => Atomics.wait(lockWaitBuffer, 0, 0, Math.max(1, ms));',
+        'const removeAbandonedStateLock = () => { let owner = null; try { owner = JSON.parse(fs.readFileSync(stateLockPath, "utf8")); } catch {} const ownerPid = Number(owner?.pid || 0); if (Number.isInteger(ownerPid) && ownerPid > 1) { if (isAlive(ownerPid)) return false; } else { try { if (Date.now() - fs.statSync(stateLockPath).mtimeMs < 5000) return false; } catch { return true; } } try { fs.rmSync(stateLockPath); return true; } catch { return false; } };',
+        'const withStateLock = callback => { fs.mkdirSync(path.dirname(stateLockPath), { recursive: true }); const deadline = Date.now() + 10000; let descriptor = null; let token = ""; while (descriptor === null) { try { descriptor = fs.openSync(stateLockPath, "wx", 0o600); token = process.pid + "-" + Date.now() + "-" + Math.random().toString(16).slice(2); fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, token, acquiredAt: new Date().toISOString() }), "utf8"); } catch (error) { if (descriptor !== null) { try { fs.closeSync(descriptor); } catch {} descriptor = null; try { fs.rmSync(stateLockPath, { force: true }); } catch {} } if (error?.code !== "EEXIST") throw error; if (removeAbandonedStateLock()) continue; if (Date.now() >= deadline) throw new Error("Timed out waiting for the LiveDesk update state lock: " + stateLockPath); waitForStateLock(Math.min(25, Math.max(1, deadline - Date.now()))); } } try { return callback(); } finally { try { fs.closeSync(descriptor); } catch {} try { const owner = JSON.parse(fs.readFileSync(stateLockPath, "utf8")); if (owner?.token === token && Number(owner?.pid) === process.pid) fs.rmSync(stateLockPath, { force: true }); } catch {} } };',
+        'const writeFailure = (error, cancelRequested = false) => { try { withStateLock(() => { const previous = readState(); if (previous.operationId && previous.operationId !== operationId) return; if (previous.stage === "preflight-ready" || previous.stage === "waiting-for-shutdown" || previous.stage === "connected" || previous.stage === "restored") return; const now = new Date().toISOString(); const next = { ...previous, operationId, stage: "failed", targetProductVersion, restartVerified: false, cancelRequested: cancelRequested || previous.cancelRequested === true, 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 writeCancellation = error => withStateLock(() => { const previous = readState(); if (previous.operationId && previous.operationId !== operationId) return "superseded"; if (previous.operationId !== operationId) return false; if (previous.stage === "preflight-ready" || previous.stage === "waiting-for-shutdown") return "ready"; if (previous.stage === "failed") return previous.cancelRequested === true ? "cancelled" : "failed"; const now = new Date().toISOString(); const next = { ...previous, operationId, stage: "failed", targetProductVersion, restartVerified: false, cancelRequested: true, error: String(error?.message || error).slice(0, 4000), cancelledAt: now, failedAt: now, updatedAt: now }; const temporary = statePath + "." + process.pid + ".cancel.tmp"; fs.writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 }); fs.renameSync(temporary, statePath); return "cancelled"; });',
+        'const terminateTree = async child => { const pid = Number(child?.pid || 0); if (pid <= 1) return; if (process.platform === "win32") { await new Promise(resolve => { const killer = spawn("taskkill.exe", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }); let done = false; const finish = () => { if (done) return; done = true; clearTimeout(timer); resolve(); }; const timer = setTimeout(() => { try { killer.kill("SIGKILL"); } catch {} finish(); }, 10000); killer.once("error", finish); killer.once("exit", finish); }); if (isAlive(pid)) { try { child.kill("SIGKILL"); } catch {} } return; } try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} } const gracefulDeadline = Date.now() + 2000; while (Date.now() < gracefulDeadline && (isGroupAlive(pid) || isAlive(pid))) await sleep(100); if (isGroupAlive(pid) || isAlive(pid)) { try { process.kill(-pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} } } };',
+        'const writeHandoffStarted = () => withStateLock(() => { if (deadlineExpired()) throw new Error("The absolute LiveDesk Client update deadline expired before handoff."); const previous = readState(); if (previous.operationId !== operationId) throw new Error("LiveDesk update handoff was superseded before exact-package launch."); const now = new Date().toISOString(); const next = { ...previous, operationId, stage: "handoff-started", starterPid: process.pid, updateDeadlineEpochMs, restartVerified: false, error: "", updatedAt: now }; const temporary = statePath + "." + process.pid + ".handoff-started.tmp"; fs.writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 }); fs.renameSync(temporary, statePath); });',
+        '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 cancelTimedOutHandoff = async () => { const error = new Error(deadlineExpired() ? "The absolute LiveDesk Client update deadline expired before exact-package preflight." : "Timed out waiting for exact-package update preflight."); while (!settled) { inspect(); if (settled) return; let outcome; try { outcome = writeCancellation(error); } catch (lockError) { finish(lockError); return; } if (outcome === "ready" || outcome === "failed") { inspect(); if (settled) return; } else if (outcome === "cancelled" || outcome === "superseded") { await terminateTree(child); finish(null, true); return; } await sleep(25); } }; const poll = setInterval(inspect, 100); const timeoutMs = Math.max(1, Math.min(Math.max(1000, Number(process.env.LIVEDESK_CLIENT_UPDATE_HANDOFF_TIMEOUT_MS || 140000)), updateDeadlineEpochMs - Date.now())); const timeout = setTimeout(() => { void cancelTimedOutHandoff(); }, timeoutMs); 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(); };',
+        'const prepareNeutralCwd = () => { if (!neutralCwd) throw new Error("LiveDesk update neutral working directory is unavailable"); fs.mkdirSync(neutralCwd, { recursive: true }); for (let ancestor = neutralCwd; ; ancestor = path.dirname(ancestor)) { const shadow = [path.join(ancestor, "package.json"), path.join(ancestor, "node_modules", "livedesk", "package.json")].find(fs.existsSync); if (shadow) throw new Error("LiveDesk update neutral working directory is shadowed by " + shadow + ": " + neutralCwd); const parent = path.dirname(ancestor); if (parent === ancestor) break; } };',
+        'if (!operationId || !versionPattern.test(targetProductVersion) || deadlineExpired()) { writeFailure(new Error("Invalid or expired LiveDesk exact-package update handoff."), true); } else { try { prepareNeutralCwd(); writeHandoffStarted();',
+        'const env = { ...process.env, LIVEDESK_UPDATE_STARTER_PID: String(process.pid) }; const isolated = 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 (isolated.has(key.toLowerCase())) delete env[key]; env.INIT_CWD = neutralCwd; env.npm_config_local_prefix = neutralCwd; env.npm_config_include_workspace_root = "false";',
         '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) { 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 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 = 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 () => { 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; });',
+        '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, { cwd: neutralCwd, env, detached: true, stdio: "ignore", windowsHide: true }); child.once("error", writeFailure); child.once("spawn", () => monitorPreflight(child)); } catch (error) { writeFailure(error); } }',
+        '} catch (error) { writeFailure(error, deadlineExpired()); } }',
         ''
     ].join('\n');
 }
@@ -1490,6 +1603,7 @@ async function scheduleClientUpdate(options, payload = {}) {
     const statePath = getClientUpdateStatePath();
     let targetProductVersion = '';
     let targetAgentVersion = '';
+    let updateDeadlineEpochMs = 0;
     try {
         targetProductVersion = normalizeClientUpdateTargetVersion(
             payload.targetProductVersion
@@ -1509,11 +1623,22 @@ async function scheduleClientUpdate(options, payload = {}) {
             || targetProductVersion
             || ''
         );
+        const updateTimeoutMs = Number(payload.updateTimeoutMs);
+        if (!Number.isSafeInteger(updateTimeoutMs)
+            || updateTimeoutMs < 1_000
+            || updateTimeoutMs > 90 * 60_000) {
+            throw new Error('LiveDesk Client update requires a bounded deadline budget.');
+        }
+        updateDeadlineEpochMs = Date.now() + updateTimeoutMs;
+        const originalCwd = path.resolve(process.cwd());
+        const neutralCwd = await prepareClientUpdateNeutralCwd(operationId);
         await writeClientUpdateState('scheduled', {
             operationId,
             targetVersion: targetAgentVersion,
             targetProductVersion,
             targetAgentVersion,
+            updateTimeoutMs,
+            updateDeadlineEpochMs,
             requestedAt: new Date().toISOString(),
             restartVerified: false,
             error: ''
@@ -1533,29 +1658,41 @@ async function scheduleClientUpdate(options, payload = {}) {
         if (!command) {
             throw new Error('LiveDesk npx executable was not found.');
         }
+        const frozenCommand = path.isAbsolute(command) || !/[\\/]/.test(command)
+            ? command
+            : path.resolve(originalCwd, command);
+        const configuredLocalLauncher = String(
+            process.env.LIVEDESK_UNIFIED_LAUNCHER_ENTRY
+            || process.env.LIVEDESK_CLIENT_UPDATE_LOCAL_LAUNCHER
+            || ''
+        ).trim();
+        const localLauncher = configuredLocalLauncher
+            ? path.resolve(originalCwd, configuredLocalLauncher)
+            : '';
+        const updateEnvironment = buildClientUpdateNpxEnvironment({
+            ...process.env,
+            LIVEDESK_NODE_EXECUTABLE: process.execPath,
+            LIVEDESK_NPX_EXECUTABLE: frozenCommand,
+            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: localLauncher,
+            LIVEDESK_CLIENT_UPDATE_OPERATION_ID: operationId,
+            LIVEDESK_CLIENT_UPDATE_DEADLINE_EPOCH_MS: String(updateDeadlineEpochMs),
+            LIVEDESK_CLIENT_UPDATE_STATE_PATH: statePath,
+            LIVEDESK_UPDATE_NEUTRAL_CWD: neutralCwd,
+            LIVEDESK_UPDATE_ORIGINAL_CWD: originalCwd,
+            LIVEDESK_CLIENT_UPDATE_CWD: originalCwd
+        }, neutralCwd);
         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()
-                },
+                cwd: neutralCwd,
+                env: updateEnvironment,
                 detached: true,
                 stdio: 'ignore',
                 windowsHide: true
@@ -1570,6 +1707,7 @@ async function scheduleClientUpdate(options, payload = {}) {
                     targetProductVersion,
                     targetAgentVersion,
                     operationId,
+                    updateDeadlineEpochMs,
                     statePath,
                     parentPid,
                     restartAfterMs: 0
@@ -1623,8 +1761,27 @@ async function handleRemoteCommand(socket, options, message, nextFrameSeq, activ
                 commandId: message.commandId,
                 result
             });
-            if (await waitForClientUpdateShutdownSignal(result.operationId)) {
-                process.exit(EXIT_CLIENT_UPDATE);
+            const shutdownSignal = await waitForClientUpdateShutdownSignal(
+                result.operationId,
+                result.updateDeadlineEpochMs
+            );
+            if (shutdownSignal.ready) {
+                // The exact package supervisor is the sole owner of old-runtime
+                // termination, so a deadline can never race a voluntary exit.
+                return;
+            } else {
+                writeJsonLine(socket, {
+                    type: 'command.result',
+                    commandId: message.commandId,
+                    error: shutdownSignal.error,
+                    result: {
+                        ok: false,
+                        status: 'failed',
+                        error: shutdownSignal.error,
+                        operationId: result.operationId,
+                        completedAt: new Date().toISOString()
+                    }
+                });
             }
         } catch (error) {
             writeJsonLine(socket, {

package/bin/livedesk-client.js

@@ -603,8 +603,15 @@ function readClientUpdateState() {
 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 = {
@@ -615,6 +622,7 @@ function writeClientUpdateRuntimeStage(stage, details = {}) {
         productVersion,
         agentVersion: readPackageVersion(),
         launcherPid: process.pid,
+        attemptId,
         updatedAt: new Date().toISOString(),
         ...details
     };
@@ -3592,9 +3600,10 @@ 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_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
@@ -3805,16 +3814,19 @@ function resolveFastLaunch(runtime) {
 }
 
 function spawnAgent(command, args, env = process.env, onStart = null) {
-    const child = spawn(command, args, {
-        env,
-        stdio: 'inherit',
-        windowsHide: true
-    });
-    activeAgentProcess = child;
-    writeClientUpdateRuntimeStage('agent-started', {
-        agentPid: Number(child.pid || 0),
+    // 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);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.170",
+  "version": "0.1.172",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -39,10 +39,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@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"
+    "@livedesk/fast-linux-x64": "0.1.378",
+    "@livedesk/fast-osx-arm64": "0.1.378",
+    "@livedesk/fast-osx-x64": "0.1.378",
+    "@livedesk/fast-win-x64": "0.1.378"
   },
   "publishConfig": {
     "access": "public"