@livedesk/client 0.1.171 → 0.1.173

package/bin/livedesk-client-node.js

@@ -43,7 +43,84 @@ 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 = {}) {
@@ -63,14 +140,19 @@ 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;
-    if (!replacesTerminalOperation
+    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 (!replacesTerminalOperation
+    if (!replacesPreviousOperation
         && previous?.stage === 'connected'
         && previous?.restartVerified === true
         && stage !== 'connected') {
@@ -79,7 +161,7 @@ async function writeClientUpdateState(stage, details = {}) {
     const targetProductVersion = String(
         details.targetProductVersion
         || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION
-        || (!replacesTerminalOperation ? previous?.targetProductVersion : '')
+        || (!replacesPreviousOperation ? previous?.targetProductVersion : '')
         || ''
     ).trim();
     const targetAgentVersion = String(
@@ -87,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,
@@ -110,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'));
@@ -126,22 +226,32 @@ async function waitForClientUpdateShutdownSignal(operationId, timeoutMs = 150_00
                 await wait(200);
                 continue;
             }
-            if (state.stage === 'preflight-ready' || 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() {
@@ -1451,23 +1561,39 @@ function buildClientUpdateBootstrapScript() {
         'const fs = require("node:fs");',
         'const path = require("node:path");',
         '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 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 targetProductVersion = cleanVersion(process.env.LIVEDESK_CLIENT_UPDATE_TARGET_PRODUCT_VERSION || process.env.LIVEDESK_CLIENT_UPDATE_TARGET_VERSION);',
+        '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 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 sleep = ms => new Promise(resolve => setTimeout(resolve, ms));',
+        '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 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); } }',
-        '}',
+        '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');
 }
@@ -1477,6 +1603,7 @@ async function scheduleClientUpdate(options, payload = {}) {
     const statePath = getClientUpdateStatePath();
     let targetProductVersion = '';
     let targetAgentVersion = '';
+    let updateDeadlineEpochMs = 0;
     try {
         targetProductVersion = normalizeClientUpdateTargetVersion(
             payload.targetProductVersion
@@ -1496,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: ''
@@ -1520,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
@@ -1557,6 +1707,7 @@ async function scheduleClientUpdate(options, payload = {}) {
                     targetProductVersion,
                     targetAgentVersion,
                     operationId,
+                    updateDeadlineEpochMs,
                     statePath,
                     parentPid,
                     restartAfterMs: 0
@@ -1610,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

@@ -2888,15 +2888,18 @@ async function startConnectionChoiceServer(supabase, options = {}) {
 
 async function chooseClientConnection(supabase, options = {}) {
     if (isTruthy(process.env.LIVEDESK_UNIFIED_RUNTIME)) {
-        const connectionPage = createClientRuntimeServer({
-            host: process.env.LIVEDESK_CLIENT_RUNTIME_HOST || '127.0.0.1',
-            port: options.authPort || DEFAULT_AUTH_CALLBACK_PORT,
-            webDist: process.env.LIVEDESK_WEB_DIST || '',
+        const connectionPage = createClientRuntimeServer({
+            host: process.env.LIVEDESK_CLIENT_RUNTIME_HOST || '127.0.0.1',
+            port: options.authPort || DEFAULT_AUTH_CALLBACK_PORT,
+            webDist: process.env.LIVEDESK_WEB_DIST || '',
             appVersion: process.env.LIVEDESK_NPM_LAUNCHER_VERSION || readPackageVersion(),
-            deviceId: options.deviceId,
-            engine: options.engine,
+            deviceId: options.deviceId,
+            engine: options.engine,
             savedSession: options.savedSession,
+            initialChoice: options.initialChoice,
+            initialChoiceMessage: options.initialChoiceMessage,
             beginGoogleSignIn: async redirectTo => {
+                if (!supabase?.auth) throw new Error('supabase-session-required');
                 const { data, error } = await supabase.auth.signInWithOAuth({
                     provider: 'google',
                     options: {
@@ -2910,15 +2913,22 @@ async function chooseClientConnection(supabase, options = {}) {
                 return { url: data.url };
             },
             exchangeGoogleCode: async code => {
+                if (!supabase?.auth) throw new Error('supabase-session-required');
                 const { data, error } = await supabase.auth.exchangeCodeForSession(code);
                 if (error) throw error;
                 if (!data?.session) throw new Error('google-session-missing');
                 if (!writeSavedSessionToFile(data.session)) throw new Error('refresh-token-required');
                 return data.session;
             },
-            resolvePin: pin => resolveManagerFromPin(supabase, pin),
-            changeRole: async (role, snapshot) => {
-                const session = await refreshSessionIfNeeded(supabase);
+            resolvePin: pin => {
+                if (!supabase) throw new Error('supabase-session-required');
+                return resolveManagerFromPin(supabase, pin);
+            },
+            changeRole: async (role, snapshot) => {
+                if (!supabase) {
+                    return { ok: false, error: 'supabase-session-required' };
+                }
+                const session = await refreshSessionIfNeeded(supabase);
                 if (!session?.access_token) {
                     return { ok: false, error: 'supabase-session-required' };
                 }
@@ -3255,7 +3265,7 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
     let connectionPage = null;
     let discoverySource = '';
 
-    if (shouldLogin) {
+    if (shouldLogin) {
         const supabase = await createSupabaseClient();
         const startupArgs = buildStartupClientArgs(parsed);
         let savedSession = null;
@@ -3362,10 +3372,38 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                 message: `Connected to LiveDesk Hub at ${manager}.`
             });
         }
-        console.log(`Found LiveDesk Hub at ${manager}.`);
-    }
-
-    const slot = normalizeSlotNumber(parsed.slot);
+        console.log(`Found LiveDesk Hub at ${manager}.`);
+    }
+    // Exact-package updates preserve the already paired Hub endpoint and pass
+    // --no-login so the replacement cannot block on browser auth. The unified
+    // launcher must still own its local runtime/status API; the package
+    // supervisor uses that API to prove the new launcher and Agent are stable
+    // before it commits the update.
+    if (!shouldLogin
+        && !existingConnectionPage
+        && isTruthy(process.env.LIVEDESK_UNIFIED_RUNTIME)
+        && manager
+        && pair) {
+        const preservedSession = readSavedSessionFromFile();
+        const explicitConnection = await chooseClientConnection(null, {
+            authPort: parsed.authPort,
+            deviceId: parsed.deviceId,
+            engine: parsed.engine,
+            savedSession: preservedSession,
+            openBrowser: false,
+            initialChoice: {
+                type: 'explicit',
+                manager,
+                pair,
+                endpointCandidates: [manager],
+                ...(preservedSession?.access_token ? { session: preservedSession } : {})
+            },
+            initialChoiceMessage: `Using the existing LiveDesk Hub pairing at ${manager}.`
+        });
+        connectionPage = explicitConnection.connectionPage || null;
+    }
+
+    const slot = normalizeSlotNumber(parsed.slot);
     if (manager) {
         forwarded = upsertForwardedOption(forwarded, '--manager', manager);
     }

package/package.json

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

package/src/runtime/client-runtime-server.js

@@ -514,9 +514,16 @@ function sendText(res, status, body, type = 'text/plain; charset=utf-8') {
   res.end(body);
 }
 
-export function createClientRuntimeServer(options = {}) {
-  const host = normalizeString(options.host, 80) || DEFAULT_HOST;
+export function createClientRuntimeServer(options = {}) {
+  const host = normalizeString(options.host, 80) || DEFAULT_HOST;
   const port = normalizePort(options.port, DEFAULT_PORT);
+  const initialChoice = options.initialChoice && typeof options.initialChoice === 'object'
+    ? options.initialChoice
+    : null;
+  const initialChoiceMessage = normalizeString(
+    options.initialChoiceMessage,
+    1000
+  ) || 'Existing LiveDesk credentials accepted. Starting the Client.';
   const trustedWebOrigins = createTrustedWebOrigins(port);
   const webDist = resolve(String(options.webDist || process.env.LIVEDESK_WEB_DIST || '').trim() || join(process.cwd(), 'apps', 'web', 'dist'));
   const deviceId = normalizeString(options.deviceId || process.env.LIVEDESK_DEVICE_ID, 160);
@@ -1030,23 +1037,29 @@ export function createClientRuntimeServer(options = {}) {
         else res.end();
       });
     });
-    server.once('error', rejectStart);
-    server.listen(port, host, () => {
-      runtime.emit('runtime.http.started', { host, port });
-      const saved = normalizeRuntimeAuthSession(options.savedSession, { requireRefreshToken: true });
-      if (saved.ok) {
+    server.once('error', rejectStart);
+    server.listen(port, host, () => {
+      runtime.emit('runtime.http.started', { host, port });
+      if (initialChoice) {
         setImmediate(() => {
-          try {
-            if (!writeSavedSession(saved.session)) throw new Error('refresh-token-required');
-            state.auth.persisted = true;
-            complete({ type: 'google', session: saved.session }, 'Saved sign-in found. Finding the LiveDesk Hub.');
-          } catch (error) {
-            recordAuthAttempt('rejected', `session-persistence-failed:${normalizeString(error?.message || error, 160)}`);
-          }
+          complete(initialChoice, initialChoiceMessage);
         });
+      } else {
+        const saved = normalizeRuntimeAuthSession(options.savedSession, { requireRefreshToken: true });
+        if (saved.ok) {
+          setImmediate(() => {
+            try {
+              if (!writeSavedSession(saved.session)) throw new Error('refresh-token-required');
+              state.auth.persisted = true;
+              complete({ type: 'google', session: saved.session }, 'Saved sign-in found. Finding the LiveDesk Hub.');
+            } catch (error) {
+              recordAuthAttempt('rejected', `session-persistence-failed:${normalizeString(error?.message || error, 160)}`);
+            }
+          });
+        }
       }
-      resolveStart();
-    });
+      resolveStart();
+    });
   });
 
   return {