@yeaft/webchat-agent 1.0.341 → 1.0.342

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.341",
+  "version": "1.0.342",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/upgrade-command.js

@@ -1,9 +1,12 @@
-import { copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { delimiter, dirname, join, win32 } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 
 export const DEFAULT_UPGRADE_REGISTRY = 'https://pkg.yeaft.com/';
 
+const WINDOWS_UPGRADE_LOCK_NAME = 'active.lock';
+
 const ONLINE_METADATA_FLAGS = [
   '--prefer-online',
   '--prefer-offline=false',
@@ -71,13 +74,73 @@ export function buildUpgradeInstallCommand(packageSpec, options) {
   return ['npm', ...buildUpgradeInstallArgs(packageSpec, options)].join(' ');
 }
 
-/** Build a shell-free detached Node invocation for the Windows updater. */
-export function buildWindowsUpgradeInvocation({ nodePath, runnerPath, payloadPath, logPath }) {
+/** Allocate one isolated runtime directory and atomically lock the instance. */
+export function createWindowsUpgradeRun(upgradeRoot, {
+  runId = randomUUID(),
+  parentPid = process.pid,
+} = {}) {
+  if (!/^[A-Za-z0-9._-]+$/u.test(runId)) throw new TypeError('runId contains invalid path characters');
+  if (!Number.isInteger(parentPid) || parentPid <= 0) throw new TypeError('parentPid must be a positive integer');
+  const lockPath = join(upgradeRoot, WINDOWS_UPGRADE_LOCK_NAME);
+  mkdirSync(upgradeRoot, { recursive: true });
+
+  try {
+    mkdirSync(lockPath);
+  } catch (err) {
+    if (err?.code !== 'EEXIST') throw err;
+    let owner = null;
+    try { owner = JSON.parse(readFileSync(join(lockPath, 'owner.json'), 'utf8')); } catch {}
+    const detail = /^[A-Za-z0-9._-]+$/u.test(owner?.runId || '') ? ` (run ${owner.runId})` : '';
+    throw new Error(`A Windows upgrade lock already exists for this instance${detail} at ${lockPath}; remove it only after confirming no upgrade is running`);
+  }
+
+  const runDir = join(upgradeRoot, 'runs', runId);
+  try {
+    writeFileSync(join(lockPath, 'owner.json'), JSON.stringify({ runId, parentPid, createdAt: Date.now() }));
+    mkdirSync(dirname(runDir), { recursive: true });
+    mkdirSync(runDir);
+    return {
+      runId,
+      runDir,
+      lockPath,
+      bootstrapPath: join(runDir, 'windows-upgrade-bootstrap.js'),
+      runnerPath: join(runDir, 'windows-upgrade-runner.js'),
+      commandPath: join(runDir, 'upgrade-command.js'),
+      payloadPath: join(runDir, 'payload.json'),
+      handoffPath: join(runDir, 'started'),
+      authorizePath: join(runDir, 'authorized'),
+      cancelPath: join(runDir, 'cancelled'),
+    };
+  } catch (err) {
+    try { rmSync(lockPath, { recursive: true, force: true }); } catch {}
+    throw err;
+  }
+}
+
+/** Release the instance lock only when it still belongs to this run. */
+export function releaseWindowsUpgradeLock(lockPath, runId) {
+  if (!lockPath || !runId) return false;
+  let owner;
+  try {
+    owner = JSON.parse(readFileSync(join(lockPath, 'owner.json'), 'utf8'));
+  } catch {
+    return false;
+  }
+  if (owner?.runId !== runId) return false;
+  try {
+    rmSync(lockPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Build a shell-free Node invocation for the short-lived bootstrap. */
+export function buildWindowsUpgradeInvocation({ nodePath, bootstrapPath, runnerPath, payloadPath, logPath }) {
   return {
     command: nodePath,
-    args: [runnerPath, payloadPath],
+    args: [bootstrapPath, runnerPath, payloadPath],
     options: {
-      detached: true,
       stdio: 'ignore',
       windowsHide: true,
       env: { ...process.env, YEAFT_UPGRADE_LOG: logPath },
@@ -85,17 +148,33 @@ export function buildWindowsUpgradeInvocation({ nodePath, runnerPath, payloadPat
   };
 }
 
-/**
- * Copy the updater out of the npm package before npm replaces that package.
- * The runner imports only this helper module, so copy both files together.
- */
-export function prepareWindowsUpgradeRunner({ sourceRunnerPath, sourceCommandPath, runnerPath, commandPath, payloadPath, payload }) {
+/** Copy the bootstrap and updater out of the package before npm replaces it. */
+export function prepareWindowsUpgradeRunner({
+  sourceBootstrapPath,
+  sourceRunnerPath,
+  sourceCommandPath,
+  bootstrapPath,
+  runnerPath,
+  commandPath,
+  payloadPath,
+  payload,
+}) {
   const runtimeDir = dirname(runnerPath);
   const moduleManifestPath = join(runtimeDir, 'package.json');
   mkdirSync(runtimeDir, { recursive: true });
-  for (const path of [runnerPath, commandPath, moduleManifestPath, payloadPath, payload.handoffPath]) {
+  for (const path of [
+    bootstrapPath,
+    runnerPath,
+    commandPath,
+    moduleManifestPath,
+    payloadPath,
+    payload.handoffPath,
+    payload.authorizePath,
+    payload.cancelPath,
+  ]) {
     try { rmSync(path, { force: true }); } catch {}
   }
+  copyFileSync(sourceBootstrapPath, bootstrapPath);
   copyFileSync(sourceRunnerPath, runnerPath);
   copyFileSync(sourceCommandPath, commandPath);
   writeFileSync(moduleManifestPath, JSON.stringify({ type: 'module' }));
@@ -117,94 +196,163 @@ function waitForSpawn(child) {
   });
 }
 
+function waitForExit(child, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    if (child.exitCode != null || child.signalCode != null) {
+      resolve({ code: child.exitCode, signal: child.signalCode });
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.removeListener('error', onError);
+      child.removeListener('exit', onExit);
+      reject(new Error(`Windows upgrade bootstrap did not exit within ${timeoutMs}ms`));
+    }, timeoutMs);
+    const onError = err => {
+      clearTimeout(timer);
+      child.removeListener('exit', onExit);
+      reject(err);
+    };
+    const onExit = (code, signal) => {
+      clearTimeout(timer);
+      child.removeListener('error', onError);
+      resolve({ code, signal });
+    };
+    child.once('error', onError);
+    child.once('exit', onExit);
+  });
+}
+
+function readHandoff(handoffPath, runId) {
+  try {
+    const handoff = JSON.parse(readFileSync(handoffPath, 'utf8'));
+    if (handoff?.runId !== runId) return null;
+    if (!Number.isInteger(handoff.runnerPid) || handoff.runnerPid <= 0) return null;
+    return handoff;
+  } catch {
+    return null;
+  }
+}
+
+function isProcessRunning(pid, probe = process.kill) {
+  try {
+    probe(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
 async function waitForUpgradeHandoff({
   handoffPath,
+  runId,
   child,
   fileExists,
   sleep,
   timeoutMs,
   pollIntervalMs,
   getChildError,
+  processRunning,
 }) {
   const deadline = Date.now() + timeoutMs;
-  let handoffSeen = false;
   while (Date.now() < deadline) {
     const childError = getChildError();
     if (childError) throw childError;
-    if (child.exitCode != null || child.signalCode != null) {
-      const status = child.exitCode != null ? `code ${child.exitCode}` : `signal ${child.signalCode}`;
-      throw new Error(`Windows upgrade launcher exited before handoff (${status})`);
-    }
 
-    // Require the marker on two consecutive polls. A batch file that writes the
-    // marker and immediately exits must not be allowed to tear down PM2.
-    if (fileExists(handoffPath)) {
-      if (handoffSeen) return;
-      handoffSeen = true;
-    } else {
-      handoffSeen = false;
+    const handoff = fileExists(handoffPath) ? readHandoff(handoffPath, runId) : null;
+    if (handoff && processRunning(handoff.runnerPid)) return handoff;
+    // A clean bootstrap exit only confirms the detached spawn. The runner may
+    // still be starting and must get the rest of the handoff timeout to reply.
+    if (child.signalCode != null || (child.exitCode != null && child.exitCode !== 0)) {
+      const status = child.signalCode != null ? `signal ${child.signalCode}` : `code ${child.exitCode}`;
+      throw new Error(`Windows upgrade bootstrap exited before handoff (${status})`);
     }
     await sleep(pollIntervalMs);
   }
-  throw new Error(`Windows upgrade launcher did not confirm handoff within ${timeoutMs}ms`);
+  throw new Error(`Windows upgrade runner did not confirm handoff within ${timeoutMs}ms`);
 }
 
 /**
- * Launch the detached Windows updater and confirm that its handoff marker
- * remains present before the caller stops PM2 or exits.
+ * Launch a short-lived bootstrap, verify the updater PID, wait for the bootstrap
+ * to exit, and verify the updater again. Only then may the caller exit or let
+ * the updater remove the PM2 app.
  */
 export async function launchWindowsUpgradeScript({
+  runId,
   nodePath,
+  bootstrapPath,
   runnerPath,
   payloadPath,
   logPath,
   handoffPath,
+  authorizePath,
+  cancelPath,
+  lockPath,
   spawnProcess,
   fileExists = existsSync,
   removeFile = path => rmSync(path, { force: true }),
+  writeCancel = (path, id) => writeFileSync(path, JSON.stringify({ runId: id, cancelledAt: Date.now() })),
+  writeAuthorize = (path, id) => writeFileSync(path, JSON.stringify({ runId: id, authorizedAt: Date.now() })),
   sleep = delay,
+  processRunning = isProcessRunning,
   timeoutMs = 5000,
   pollIntervalMs = 50,
-  onHandoff,
 }) {
+  if (!runId) throw new TypeError('runId is required');
   if (typeof spawnProcess !== 'function') throw new TypeError('spawnProcess is required');
   if (!handoffPath) throw new TypeError('handoffPath is required');
+  if (!authorizePath) throw new TypeError('authorizePath is required');
+  if (!cancelPath) throw new TypeError('cancelPath is required');
+  if (!lockPath) throw new TypeError('lockPath is required');
 
-  const invocation = buildWindowsUpgradeInvocation({ nodePath, runnerPath, payloadPath, logPath });
+  const invocation = buildWindowsUpgradeInvocation({ nodePath, bootstrapPath, runnerPath, payloadPath, logPath });
   let child;
   try {
     child = spawnProcess(invocation.command, invocation.args, invocation.options);
   } catch (err) {
-    throw new Error(`Windows upgrade launcher failed: ${err.message}`, { cause: err });
+    releaseWindowsUpgradeLock(lockPath, runId);
+    throw new Error(`Windows upgrade bootstrap failed: ${err.message}`, { cause: err });
   }
 
   let childError = null;
+  let bootstrapSpawned = false;
   const onChildError = err => { childError = err; };
   child.on('error', onChildError);
   try {
     await waitForSpawn(child);
-    await waitForUpgradeHandoff({
+    bootstrapSpawned = true;
+    const handoff = await waitForUpgradeHandoff({
       handoffPath,
+      runId,
       child,
       fileExists,
       sleep,
       timeoutMs,
       pollIntervalMs,
       getChildError: () => childError,
+      processRunning,
     });
-    await onHandoff?.();
+    const status = await waitForExit(child, timeoutMs);
+    if (status.code !== 0) {
+      const detail = status.signal ? `signal ${status.signal}` : `code ${status.code}`;
+      throw new Error(`Windows upgrade bootstrap exited with ${detail}`);
+    }
+    if (!processRunning(handoff.runnerPid)) {
+      throw new Error('Windows upgrade runner did not survive bootstrap exit');
+    }
+    writeAuthorize(authorizePath, runId);
   } catch (err) {
+    try { writeCancel(cancelPath, runId); } catch {}
     try { child.kill(); } catch {}
     try { removeFile(handoffPath); } catch {}
+    if (!bootstrapSpawned) releaseWindowsUpgradeLock(lockPath, runId);
     if (childError === err) {
-      throw new Error(`Windows upgrade launcher failed: ${err.message}`, { cause: err });
+      throw new Error(`Windows upgrade bootstrap failed: ${err.message}`, { cause: err });
     }
     throw err;
   } finally {
     child.removeListener('error', onChildError);
   }
 
-  child.unref();
   return nodePath;
 }
 

package/windows-upgrade-bootstrap.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import { appendFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+function appendLog(logPath, message) {
+  if (!logPath) return;
+  try {
+    appendFileSync(logPath, `[Upgrade] ${message}\n`);
+  } catch {}
+}
+
+/**
+ * Spawn the real updater from a short-lived intermediate process. Once this
+ * bootstrap exits, the updater is no longer in the live process tree rooted at
+ * the PM2-managed Agent, so PM2's Windows tree kill cannot terminate it.
+ */
+export function spawnWindowsUpgradeRunner({
+  nodePath,
+  runnerPath,
+  payloadPath,
+  logPath,
+}, spawnProcess = spawn) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawnProcess(nodePath, [runnerPath, payloadPath], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env: { ...process.env, YEAFT_UPGRADE_LOG: logPath },
+      });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+
+    const onError = err => {
+      child.removeListener('spawn', onSpawn);
+      reject(err);
+    };
+    const onSpawn = () => {
+      child.removeListener('error', onError);
+      child.unref();
+      resolve(child.pid);
+    };
+    child.once('error', onError);
+    child.once('spawn', onSpawn);
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const [runnerPath, payloadPath] = process.argv.slice(2);
+  const logPath = process.env.YEAFT_UPGRADE_LOG;
+  try {
+    if (!runnerPath || !payloadPath) throw new Error('runner path and payload path are required');
+    const runnerPid = await spawnWindowsUpgradeRunner({
+      nodePath: process.execPath,
+      runnerPath,
+      payloadPath,
+      logPath,
+    });
+    appendLog(logPath, `Bootstrap launched updater PID ${runnerPid}`);
+  } catch (err) {
+    appendLog(logPath, `Bootstrap failed: ${err?.stack || err}`);
+    process.exitCode = 1;
+  }
+}

package/windows-upgrade-runner.js

@@ -7,12 +7,15 @@ import { pathToFileURL } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import {
   buildUpgradeInstallArgs,
+  releaseWindowsUpgradeLock,
   resolveWindowsNpmCliPath,
 } from './upgrade-command.js';
 
 const PID_POLL_INTERVAL_MS = 100;
 const PID_WAIT_TIMEOUT_MS = 30_000;
+const HANDOFF_AUTH_TIMEOUT_MS = 15_000;
 const FILE_LOCK_RETRY_MS = [0, 250, 750, 1_500];
+const PM2_RETRY_MS = [0, 250, 750];
 
 function appendLog(logPath, message) {
   try {
@@ -107,79 +110,203 @@ export async function installWindowsUpgrade({
   return { exitCode: 1, attempts: FILE_LOCK_RETRY_MS.length, command, args };
 }
 
-export async function startPm2Service({ nodePath, pm2CliPath, ecosystemPath, logPath, run = runProcess }) {
-  if (!pm2CliPath || !ecosystemPath) return true;
-  appendLog(logPath, 'Re-registering Agent via PM2');
-  const startCode = await run(nodePath, [pm2CliPath, 'start', ecosystemPath], {
+export async function stopPm2Service({ nodePath, pm2CliPath, pm2AppName, logPath, run = runProcess }) {
+  if (!pm2CliPath || !pm2AppName) return true;
+  appendLog(logPath, `Removing PM2 app ${pm2AppName} before install`);
+  const deleteCode = await run(nodePath, [pm2CliPath, 'delete', pm2AppName], {
     env: process.env,
     windowsHide: true,
     stdio: 'ignore',
   });
-  if (startCode !== 0) return false;
-  const saveCode = await run(nodePath, [pm2CliPath, 'save'], {
-    env: process.env,
-    windowsHide: true,
-    stdio: 'ignore',
+  return deleteCode === 0;
+}
+
+async function runPm2WithRetry({ nodePath, pm2CliPath, args, logPath, label, run, sleep }) {
+  for (let attempt = 0; attempt < PM2_RETRY_MS.length; attempt++) {
+    const retryDelayMs = PM2_RETRY_MS[attempt];
+    if (retryDelayMs) {
+      appendLog(logPath, `Retrying PM2 ${label} after ${retryDelayMs}ms`);
+      await sleep(retryDelayMs);
+    }
+    try {
+      const code = await run(nodePath, [pm2CliPath, ...args], {
+        env: process.env,
+        windowsHide: true,
+        stdio: 'ignore',
+      });
+      if (code === 0) return true;
+      appendLog(logPath, `PM2 ${label} failed with exit code ${code} (attempt ${attempt + 1})`);
+    } catch (err) {
+      appendLog(logPath, `PM2 ${label} failed to run (attempt ${attempt + 1}): ${err?.message || err}`);
+    }
+  }
+  return false;
+}
+
+export async function startPm2Service({
+  nodePath,
+  pm2CliPath,
+  ecosystemPath,
+  logPath,
+  run = runProcess,
+  sleep = delay,
+}) {
+  if (!pm2CliPath || !ecosystemPath) return true;
+  appendLog(logPath, 'Re-registering Agent via PM2');
+  const started = await runPm2WithRetry({
+    nodePath,
+    pm2CliPath,
+    args: ['start', ecosystemPath],
+    logPath,
+    label: 'start',
+    run,
+    sleep,
+  });
+  if (!started) return false;
+  return runPm2WithRetry({
+    nodePath,
+    pm2CliPath,
+    args: ['save'],
+    logPath,
+    label: 'save',
+    run,
+    sleep,
   });
-  return saveCode === 0;
+}
+
+function readRunMarker(path, runId) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))?.runId === runId;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForHandoffAuthorization({ authorizePath, cancelPath, runId, sleep = delay }) {
+  const deadline = Date.now() + HANDOFF_AUTH_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (readRunMarker(cancelPath, runId)) return false;
+    if (readRunMarker(authorizePath, runId)) return true;
+    await sleep(PID_POLL_INTERVAL_MS);
+  }
+  return false;
+}
+
+function removeTransientFiles(handoffPath, authorizePath, payloadPath, cancelPath) {
+  for (const path of [handoffPath, authorizePath, payloadPath, cancelPath]) {
+    try { rmSync(path, { force: true }); } catch {}
+  }
 }
 
 /**
- * Run after the original Agent exits. No shell pipeline is involved: Windows
- * PID polling is handled by Node and npm/PM2 run through their JS entry points.
+ * Wait for the original Agent to exit, remove its PM2 registration, install the
+ * exact package version, and restore the selected PM2 instance. Every process
+ * invocation is shell-free.
  */
 export async function runWindowsUpgrade(options, dependencies = {}) {
   const {
+    runId,
+    lockPath,
     parentPid,
     packageSpec,
     globalInstall,
     installDir,
     logPath,
     handoffPath,
+    authorizePath,
+    cancelPath,
+    bootstrapPath,
     runnerPath,
     commandPath,
     payloadPath,
     nodePath,
     npmCliPath,
     pm2CliPath,
+    pm2AppName,
     ecosystemPath,
   } = options;
   const wait = dependencies.waitForProcessExit || waitForProcessExit;
   const install = dependencies.installWindowsUpgrade || installWindowsUpgrade;
+  const stopService = dependencies.stopPm2Service || stopPm2Service;
   const startService = dependencies.startPm2Service || startPm2Service;
+  const authorizeHandoff = dependencies.waitForHandoffAuthorization || waitForHandoffAuthorization;
+  const releaseLock = dependencies.releaseWindowsUpgradeLock || releaseWindowsUpgradeLock;
+  const cleanupPaths = [bootstrapPath, runnerPath, commandPath];
+  const cancelled = () => cancelPath && readRunMarker(cancelPath, runId);
 
-  mkdirSync(dirname(handoffPath), { recursive: true });
-  writeFileSync(handoffPath, 'started');
-  appendLog(logPath, `Started at ${new Date().toISOString()}`);
-  appendLog(logPath, `Waiting for PID ${parentPid} to exit`);
-  const exited = await wait(parentPid);
-  if (!exited) appendLog(logPath, `Timed out waiting for PID ${parentPid}; continuing with bounded npm retries`);
-  else appendLog(logPath, 'Original process exited');
+  if (!runId) throw new TypeError('runId is required');
+  if (!lockPath) throw new TypeError('lockPath is required');
 
-  let result;
   try {
-    result = await install({ nodePath, npmCliPath, packageSpec, globalInstall, installDir, logPath });
-  } catch (err) {
-    appendLog(logPath, `npm install failed to start: ${err?.message || err}`);
-    result = { exitCode: 1, attempts: 0 };
-  }
-  appendLog(logPath, `npm install ${result.exitCode === 0 ? 'succeeded' : `failed with exit code ${result.exitCode}`} after ${result.attempts} attempt(s)`);
+    mkdirSync(dirname(handoffPath), { recursive: true });
+    if (cancelled()) {
+      appendLog(logPath, 'Upgrade was cancelled before handoff; refusing to modify the installation');
+      return { exitCode: 1, restarted: false, cleanupPaths };
+    }
+    writeFileSync(handoffPath, JSON.stringify({ runId, runnerPid: process.pid, startedAt: Date.now() }));
+    appendLog(logPath, `Started run ${runId} at ${new Date().toISOString()}`);
+    const authorized = await authorizeHandoff({ authorizePath, cancelPath, runId });
+    if (!authorized) {
+      appendLog(logPath, 'Upgrade handoff was not authorized; refusing to modify the installation');
+      return { exitCode: 1, restarted: false, cleanupPaths };
+    }
+    appendLog(logPath, `Waiting for PID ${parentPid} to exit`);
+    const exited = await wait(parentPid);
+    if (!exited) {
+      appendLog(logPath, `Timed out waiting for PID ${parentPid}; refusing to modify a live installation`);
+      return { exitCode: 1, restarted: false, cleanupPaths };
+    }
+    appendLog(logPath, 'Original process exited');
+    if (cancelled()) {
+      appendLog(logPath, 'Upgrade was cancelled during handoff; refusing to modify the installation');
+      return { exitCode: 1, restarted: false, cleanupPaths };
+    }
 
-  let restarted = false;
-  try {
-    restarted = await startService({ nodePath, pm2CliPath, ecosystemPath, logPath });
-  } catch (err) {
-    appendLog(logPath, `WARNING: PM2 service restart failed: ${err?.message || err}`);
-  }
-  if (!restarted) appendLog(logPath, 'WARNING: PM2 service was not restarted');
-  appendLog(logPath, `Finished at ${new Date().toISOString()}`);
+    let stopped = false;
+    try {
+      stopped = await stopService({ nodePath, pm2CliPath, pm2AppName, logPath });
+    } catch (err) {
+      appendLog(logPath, `PM2 app removal failed: ${err?.message || err}`);
+    }
+    if (!stopped) {
+      appendLog(logPath, `PM2 app ${pm2AppName} could not be removed; refusing to install`);
+      let restored = false;
+      try {
+        restored = await startService({ nodePath, pm2CliPath, ecosystemPath, logPath });
+      } catch (err) {
+        appendLog(logPath, `WARNING: PM2 recovery failed: ${err?.message || err}`);
+      }
+      if (!restored) appendLog(logPath, 'WARNING: PM2 service was not restored after removal failure');
+      return { exitCode: 1, restarted: restored, cleanupPaths };
+    }
 
-  // Do not delete the running script. Windows keeps it executable until exit,
-  // but deferred cleanup on the next upgrade is more reliable than self-delete.
-  for (const path of [handoffPath, payloadPath]) {
-    try { rmSync(path, { force: true }); } catch {}
+    let result;
+    try {
+      result = await install({ nodePath, npmCliPath, packageSpec, globalInstall, installDir, logPath });
+    } catch (err) {
+      appendLog(logPath, `npm install failed to start: ${err?.message || err}`);
+      result = { exitCode: 1, attempts: 0 };
+    }
+    appendLog(logPath, `npm install ${result.exitCode === 0 ? 'succeeded' : `failed with exit code ${result.exitCode}`} after ${result.attempts} attempt(s)`);
+
+    let restarted = false;
+    try {
+      restarted = await startService({ nodePath, pm2CliPath, ecosystemPath, logPath });
+    } catch (err) {
+      appendLog(logPath, `WARNING: PM2 service restart failed: ${err?.message || err}`);
+    }
+    if (!restarted) appendLog(logPath, 'WARNING: PM2 service was not restarted');
+    const exitCode = result.exitCode === 0 && restarted ? 0 : 1;
+    appendLog(logPath, `Finished at ${new Date().toISOString()} with exit code ${exitCode}`);
+    return { exitCode, restarted, cleanupPaths };
+  } finally {
+    removeTransientFiles(handoffPath, authorizePath, payloadPath, cancelPath);
+    if (!releaseLock(lockPath, runId)) {
+      const message = `Upgrade lock was not released for run ${runId}`;
+      appendLog(logPath, message);
+      throw new Error(message);
+    }
   }
-  return { exitCode: result.exitCode, restarted, cleanupPaths: [runnerPath, commandPath] };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {