agl 1.0.17 → 21.0.2

package/ts/classes.upgradetransaction.ts

@@ -0,0 +1,2900 @@
+import * as plugins from './plugins.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import {
+  controllerPackageName,
+  controllerProtocolVersion,
+  controllerUpgradeManagementVersion,
+  type IControllerStatus,
+} from '../ts_interfaces/index.js';
+import { controllerDataDirectory } from './classes.config.js';
+import {
+  isLoopbackPortListening,
+  queryControllerStatus,
+  requestControllerUpgradeFinalize,
+  requestControllerUpgradePrepareBegin,
+  stopVerifiedController,
+} from './classes.controllermanagement.js';
+import {
+  inspectControllerProcess,
+  listControllerDataWriterProcessesForCli,
+  listControllerProcessesForCli,
+  processIdentityHasCliCommand,
+  readControllerProcessIdentity,
+  readProcessGroupMemberPids,
+} from './classes.processinspection.js';
+import {
+  createUpgradeToken,
+  type TUpgradeTransaction,
+  type IUpgradeTransactionV3,
+  type IUpgradeExpectedController,
+  type IUpgradeWorkerPayload,
+  UpgradeCoordinator,
+  upgradeCoordinationVersion,
+  upgradePackageTransitionTransactionVersion,
+  upgradePackageTransitionSource,
+  upgradePackageTransitionTarget,
+  upgradeTokenEnvironmentVariable,
+  serializeUpgradeWorkerPayload,
+} from './classes.upgradecoordinator.js';
+
+const npmRegistryUrl = 'https://registry.npmjs.org/';
+const commandOutputByteLimit = 1024 * 1024;
+const loggedCommandOutputByteLimit = 16 * 1024 * 1024;
+const packageManagerTimeoutMs = 10 * 60 * 1000;
+const controllerRestartTimeoutMs = 90_000;
+const commandGroupDrainTimeoutMs = 5_000;
+const candidateCleanupRetryIntervalMs = 250;
+const retainedUpgradeLogCount = 10;
+const minimumPrunableUpgradeLogAgeMs = 30 * 60 * 1000;
+const upgradePreparationPollMs = 250;
+const upgradePreparationSourceCheckMs = 500;
+const upgradePreparationAcceptanceReconciliationMs = 5_000;
+const upgradePreparationCleanupAllowanceMs = 60_000;
+const upgradeLogPattern = /^upgrade-[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{6}\.[0-9]{3}Z-[A-Za-z0-9_-]{10}\.log$/;
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+let upgradeWorkerCliPath: string | undefined;
+const currentPackageIdentity = String(controllerPackageName)
+  === upgradePackageTransitionSource.packageName
+  ? upgradePackageTransitionSource
+  : upgradePackageTransitionTarget;
+const currentCliName = currentPackageIdentity.cliName;
+
+const packageManagerEnvironmentAllowlist = new Set([
+  'CI',
+  'COREPACK_HOME',
+  'FORCE_COLOR',
+  'HOME',
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'LANG',
+  'LOGNAME',
+  'NODE_EXTRA_CA_CERTS',
+  'NO_PROXY',
+  'NPM_CONFIG_REGISTRY',
+  'NPM_CONFIG_USERCONFIG',
+  'PATH',
+  'PNPM_HOME',
+  'SHELL',
+  'SSL_CERT_DIR',
+  'SSL_CERT_FILE',
+  'TEMP',
+  'TERM',
+  'TMP',
+  'TMPDIR',
+  'TZ',
+  'USER',
+  'XDG_CACHE_HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+  'XDG_RUNTIME_DIR',
+  'XDG_STATE_HOME',
+]);
+
+interface IParsedSemver {
+  major: string;
+  minor: string;
+  patch: string;
+  prerelease: string[];
+}
+
+class UpgradeCommandCleanupError extends Error {}
+
+interface IGlobalListDependency {
+  version?: unknown;
+  path?: unknown;
+}
+
+interface IGlobalListResult {
+  path?: unknown;
+  dependencies?: Record<string, IGlobalListDependency>;
+}
+
+export interface IPnpmGlobalInstallation {
+  packageManagerPath: string;
+  globalRoot: string;
+  globalBinDirectory: string;
+  packageDirectory: string;
+  cliPath: string;
+  packageVersion: string;
+}
+
+export interface IDetachedUpgradeWorker {
+  pid: number;
+  processGroupId: number;
+  fingerprint: string;
+  cliPath: string;
+  logFilePath: string;
+}
+
+const proxyEnvironmentValueIsSafe = (valueArg: string): boolean => {
+  try {
+    const parsed = new URL(valueArg);
+    return parsed.username.length === 0 && parsed.password.length === 0;
+  } catch {
+    return false;
+  }
+};
+
+export const createPackageManagerEnvironment = (
+  sourceArg: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv => {
+  const environment: NodeJS.ProcessEnv = {};
+  for (const [name, value] of Object.entries(sourceArg)) {
+    if (value === undefined) continue;
+    const normalizedName = name.toUpperCase();
+    if (
+      !packageManagerEnvironmentAllowlist.has(normalizedName)
+      && !normalizedName.startsWith('LC_')
+    ) continue;
+    if (
+      (normalizedName === 'HTTP_PROXY' || normalizedName === 'HTTPS_PROXY')
+      && !proxyEnvironmentValueIsSafe(value)
+    ) continue;
+    environment[name] = value;
+  }
+  return environment;
+};
+
+const findExecutable = async (nameArg: string, environmentArg: NodeJS.ProcessEnv): Promise<string> => {
+  const pathValue = environmentArg.PATH;
+  if (!pathValue) throw new Error(`Unable to locate ${nameArg}: PATH is empty.`);
+  for (const directory of pathValue.split(plugins.path.delimiter)) {
+    if (!directory) continue;
+    const candidate = plugins.path.join(directory, nameArg);
+    try {
+      await plugins.fs.promises.access(candidate, plugins.fs.constants.X_OK);
+      return await plugins.fs.promises.realpath(candidate);
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(`Unable to locate ${nameArg} on PATH.`);
+};
+
+interface IManagedCommandOptions {
+  executable: string;
+  arguments: string[];
+  environment: NodeJS.ProcessEnv;
+  timeoutMs: number;
+  captureOutput: boolean;
+  outputByteLimit?: number;
+}
+
+interface IPreparedManagedCommand extends IManagedCommandOptions {
+  cwd: string;
+  workerIdentity: NonNullable<Awaited<ReturnType<typeof readControllerProcessIdentity>>>;
+  ownsWorkerProcessGroup: boolean;
+}
+
+const prepareManagedCommand = async (
+  optionsArg: IManagedCommandOptions,
+): Promise<IPreparedManagedCommand> => {
+  const workerIdentity = await readControllerProcessIdentity(process.pid);
+  if (!workerIdentity) throw new Error('Unable to establish upgrade command ownership.');
+  const ownsWorkerProcessGroup = workerIdentity.processGroupLeader
+    && await processIdentityHasCliCommand(
+      workerIdentity,
+      upgradeWorkerCliPath ?? await resolveCurrentCliPath(),
+      '__upgrade-worker',
+      { allowMissingAbsolutePath: true },
+    );
+  return {
+    ...optionsArg,
+    cwd: plugins.os.homedir(),
+    workerIdentity,
+    ownsWorkerProcessGroup,
+  };
+};
+
+const runPreparedManagedCommand = async (
+  optionsArg: IPreparedManagedCommand,
+): Promise<{ stdout: string; stderr: string }> => {
+  const child = plugins.childProcess.spawn(optionsArg.executable, optionsArg.arguments, {
+    cwd: optionsArg.cwd,
+    detached: !optionsArg.ownsWorkerProcessGroup,
+    env: optionsArg.environment,
+    shell: false,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const outcomePromise = new Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error;
+  }>((resolve) => {
+    child.once('error', (errorArg) => resolve({ code: null, signal: null, error: errorArg }));
+    child.once('close', (codeArg, signalArg) => resolve({ code: codeArg, signal: signalArg }));
+  });
+  const commandProcessGroupId = optionsArg.ownsWorkerProcessGroup
+    ? optionsArg.workerIdentity.processGroupId
+    : child.pid;
+  let stdout = '';
+  let stderr = '';
+  let outputBytes = 0;
+  let outputError: Error | undefined;
+  const recordOutput = (
+    streamArg: 'stdout' | 'stderr',
+    chunkArg: Buffer,
+    sourceArg?: NodeJS.ReadableStream,
+  ) => {
+    outputBytes += chunkArg.byteLength;
+    if (outputBytes > (optionsArg.outputByteLimit ?? commandOutputByteLimit)) {
+      outputError ??= new Error('Upgrade command output exceeded its size limit.');
+      return;
+    }
+    if (optionsArg.captureOutput) {
+      if (streamArg === 'stdout') stdout += chunkArg.toString('utf8');
+      else stderr += chunkArg.toString('utf8');
+      return;
+    }
+    const destination = streamArg === 'stdout' ? process.stdout : process.stderr;
+    if (!destination.write(chunkArg) && sourceArg && 'pause' in sourceArg && 'resume' in sourceArg) {
+      sourceArg.pause();
+      destination.once('drain', () => sourceArg.resume());
+    }
+  };
+  child.stdout?.on('data', (chunkArg: Buffer) => recordOutput('stdout', chunkArg, child.stdout!));
+  child.stderr?.on('data', (chunkArg: Buffer) => recordOutput('stderr', chunkArg, child.stderr!));
+
+  const listCommandPids = async (): Promise<number[]> => {
+    if (!commandProcessGroupId) {
+      return child.pid && child.exitCode === null && child.signalCode === null ? [child.pid] : [];
+    }
+    const members = await readProcessGroupMemberPids(commandProcessGroupId);
+    return optionsArg.ownsWorkerProcessGroup
+      ? members.filter((processIdArg) => processIdArg !== process.pid)
+      : members;
+  };
+  const signalDirectChild = (signalArg: NodeJS.Signals): void => {
+    if (!child.pid || child.exitCode !== null || child.signalCode !== null) return;
+    try {
+      process.kill(child.pid, signalArg);
+    } catch (errorArg) {
+      if ((errorArg as NodeJS.ErrnoException).code !== 'ESRCH') throw errorArg;
+    }
+  };
+  const signalCommand = async (signalArg: NodeJS.Signals): Promise<void> => {
+    let processIds: number[];
+    try {
+      processIds = await listCommandPids();
+    } catch (errorArg) {
+      signalDirectChild(signalArg);
+      throw errorArg;
+    }
+    for (const processId of processIds) {
+      try {
+        process.kill(processId, signalArg);
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'ESRCH') throw errorArg;
+      }
+    }
+  };
+  const waitForCommandDrain = async (timeoutMsArg: number): Promise<boolean> => {
+    const deadline = Date.now() + timeoutMsArg;
+    while (Date.now() < deadline) {
+      if ((await listCommandPids()).length === 0) return true;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return (await listCommandPids()).length === 0;
+  };
+  let interruption: string | undefined;
+  let terminating: Promise<void> | undefined;
+  let terminationError: unknown;
+  const terminate = (): Promise<void> => {
+    if (terminating) return terminating;
+    terminating = (async () => {
+      try {
+        await signalCommand('SIGTERM');
+        if (await waitForCommandDrain(commandGroupDrainTimeoutMs)) return;
+        await signalCommand('SIGKILL');
+        if (!await waitForCommandDrain(commandGroupDrainTimeoutMs)) {
+          throw new Error('The upgrade command process group did not terminate.');
+        }
+      } catch (errorArg) {
+        terminationError = errorArg;
+        signalDirectChild('SIGKILL');
+        throw errorArg;
+      }
+    })();
+    return terminating;
+  };
+  const beginTermination = (reasonArg: string): void => {
+    interruption ??= reasonArg;
+    void terminate().catch(() => undefined);
+  };
+  const onSigint = () => beginTermination('SIGINT');
+  const onSigterm = () => beginTermination('SIGTERM');
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+  const timeout = setTimeout(() => beginTermination('timeout'), optionsArg.timeoutMs);
+  const outputLimitPoll = setInterval(() => {
+    if (outputError) beginTermination('output limit');
+  }, 25);
+  try {
+    const outcome = await outcomePromise;
+    try {
+      if (!await waitForCommandDrain(2_000)) {
+        beginTermination('surviving child processes');
+      }
+    } catch (errorArg) {
+      terminationError = errorArg;
+      signalDirectChild('SIGKILL');
+    }
+    if (terminating) await terminating.catch(() => undefined);
+    if (terminationError) {
+      throw new UpgradeCommandCleanupError('Upgrade command cleanup failed.', {
+        cause: terminationError,
+      });
+    }
+    if (interruption) {
+      throw new Error(`${plugins.path.basename(optionsArg.executable)} was interrupted by ${interruption}.`);
+    }
+    if (outputError) throw outputError;
+    if (outcome.error) throw outcome.error;
+    if (outcome.code !== 0) {
+      throw new Error(
+        `${plugins.path.basename(optionsArg.executable)} exited with ${outcome.signal ?? outcome.code ?? 'an unknown result'}${stderr.trim() ? `: ${stderr.trim()}` : '.'}`,
+      );
+    }
+    return { stdout, stderr };
+  } finally {
+    clearTimeout(timeout);
+    clearInterval(outputLimitPoll);
+    process.removeListener('SIGINT', onSigint);
+    process.removeListener('SIGTERM', onSigterm);
+  }
+};
+
+const runManagedCommand = async (
+  optionsArg: IManagedCommandOptions,
+): Promise<{ stdout: string; stderr: string }> => await runPreparedManagedCommand(
+  await prepareManagedCommand(optionsArg),
+);
+
+const runCapturedCommand = async (
+  executableArg: string,
+  argumentsArg: string[],
+  environmentArg: NodeJS.ProcessEnv,
+  timeoutMsArg = 30_000,
+  outputByteLimitArg = commandOutputByteLimit,
+): Promise<string> => {
+  const result = await runManagedCommand({
+    executable: executableArg,
+    arguments: argumentsArg,
+    environment: environmentArg,
+    timeoutMs: timeoutMsArg,
+    captureOutput: true,
+    outputByteLimit: outputByteLimitArg,
+  });
+  return result.stdout;
+};
+
+const assertSingleLineAbsolutePath = async (valueArg: string, nameArg: string): Promise<string> => {
+  const value = valueArg.trim();
+  if (!value || value.includes('\n') || !plugins.path.isAbsolute(value)) {
+    throw new Error(`${nameArg} did not return one absolute path.`);
+  }
+  return await plugins.fs.promises.realpath(value);
+};
+
+const readGlobalListDependency = (
+  outputArg: string,
+  packageNameArg: string,
+): { version: string; path: string } => {
+  let value: unknown;
+  try {
+    value = JSON.parse(outputArg) as unknown;
+  } catch {
+    throw new Error('pnpm list --global returned malformed JSON.');
+  }
+  if (!Array.isArray(value)) {
+    throw new Error('pnpm list --global returned an unexpected result.');
+  }
+  const dependencies = value.flatMap((entryArg) => {
+    if (!entryArg || typeof entryArg !== 'object' || Array.isArray(entryArg)) return [];
+    const entry = entryArg as IGlobalListResult;
+    const dependency = entry.dependencies?.[packageNameArg];
+    return dependency ? [dependency] : [];
+  });
+  if (dependencies.length !== 1) {
+    throw new Error(`Expected exactly one pnpm-global installation of ${packageNameArg}.`);
+  }
+  const dependency = dependencies[0];
+  if (
+    typeof dependency.version !== 'string'
+    || typeof dependency.path !== 'string'
+    || !plugins.path.isAbsolute(dependency.path)
+  ) {
+    throw new Error('pnpm reported invalid global package metadata.');
+  }
+  return { version: dependency.version, path: dependency.path };
+};
+
+export const resolvePnpmGlobalInstallation = async (): Promise<IPnpmGlobalInstallation> => {
+  if (process.platform !== 'linux' && process.platform !== 'darwin') {
+    throw new Error(`${currentCliName} upgrade is currently supported on Linux and macOS only.`);
+  }
+  const environment = createPackageManagerEnvironment();
+  const packageManagerPath = await findExecutable('pnpm', environment);
+  const globalRootOutput = await runCapturedCommand(
+    packageManagerPath,
+    ['root', '--global'],
+    environment,
+  );
+  const globalBinOutput = await runCapturedCommand(
+    packageManagerPath,
+    ['bin', '--global'],
+    environment,
+  );
+  const listOutput = await runCapturedCommand(
+    packageManagerPath,
+    ['list', '--global', controllerPackageName, '--depth=0', '--json'],
+    environment,
+  );
+  const globalRoot = await assertSingleLineAbsolutePath(globalRootOutput, 'pnpm root --global');
+  const globalBinDirectory = await assertSingleLineAbsolutePath(
+    globalBinOutput,
+    'pnpm bin --global',
+  );
+  const dependency = readGlobalListDependency(listOutput, controllerPackageName);
+  const dependencyRelativePath = plugins.path.relative(globalRoot, dependency.path);
+  if (
+    dependencyRelativePath.startsWith(`..${plugins.path.sep}`)
+    || dependencyRelativePath === '..'
+    || plugins.path.isAbsolute(dependencyRelativePath)
+  ) {
+    throw new Error('pnpm reported a global package path outside its global root.');
+  }
+  const packageDirectory = await plugins.fs.promises.realpath(dependency.path);
+  const packageJsonPath = plugins.path.join(packageDirectory, 'package.json');
+  const packageJsonStats = await plugins.fs.promises.stat(packageJsonPath);
+  if (!packageJsonStats.isFile() || packageJsonStats.size < 2 || packageJsonStats.size > 64 * 1024) {
+    throw new Error(`The pnpm-global ${controllerPackageName} package metadata is not a bounded file.`);
+  }
+  const packageJson = JSON.parse(await plugins.fs.promises.readFile(packageJsonPath, 'utf8')) as {
+    name?: unknown;
+    version?: unknown;
+    bin?: unknown;
+    controllerUpgradeManagementVersion?: unknown;
+  };
+  const currentIdentity: { cliName: string; managementVersion: number } = currentPackageIdentity;
+  if (
+    packageJson.name !== controllerPackageName
+    || packageJson.version !== dependency.version
+    || packageJson.controllerUpgradeManagementVersion !== currentIdentity.managementVersion
+    || Number(controllerUpgradeManagementVersion) !== currentIdentity.managementVersion
+    || !packageJson.bin
+    || typeof packageJson.bin !== 'object'
+    || Array.isArray(packageJson.bin)
+    || !Object.keys(packageJson.bin).length
+    || Object.keys(packageJson.bin).length !== 1
+    || (packageJson.bin as Record<string, unknown>)[currentIdentity.cliName] !== './cli.js'
+  ) {
+    throw new Error(`The pnpm-global ${controllerPackageName} package metadata is incompatible.`);
+  }
+  const cliPath = await plugins.fs.promises.realpath(plugins.path.join(packageDirectory, 'cli.js'));
+  if (!(await plugins.fs.promises.stat(cliPath)).isFile()) {
+    throw new Error('The pnpm-global controller direct CLI is not a file.');
+  }
+  return {
+    packageManagerPath,
+    globalRoot,
+    globalBinDirectory,
+    packageDirectory,
+    cliPath,
+    packageVersion: dependency.version,
+  };
+};
+
+interface IPackageTransitionContext {
+  packageManagerPath: string;
+  globalRoot: string;
+  globalBinDirectory: string;
+}
+
+interface IExactGlobalPackageInstallation extends IPnpmGlobalInstallation {
+  packageName: string;
+  cliName: string;
+  cliRelativePath: string;
+  listedPackagePath: string;
+  groupDirectory: string;
+}
+
+interface IPackageTransitionTopology {
+  source?: IExactGlobalPackageInstallation;
+  target?: IExactGlobalPackageInstallation;
+}
+
+type TPackageTransitionTopology = 'source-only' | 'grouped' | 'target-only';
+
+const parseGlobalListDependencies = (
+  outputArg: string,
+): { path: string; dependencies: Record<string, { version: string; path: string }> } => {
+  let value: unknown;
+  try {
+    value = JSON.parse(outputArg) as unknown;
+  } catch {
+    throw new Error('pnpm list --global returned malformed JSON.');
+  }
+  if (!Array.isArray(value) || value.length !== 1) {
+    throw new Error('pnpm list --global returned an unexpected package-transition result.');
+  }
+  const entry = value[0];
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error('pnpm list --global returned invalid package-transition metadata.');
+  }
+  const raw = entry as IGlobalListResult;
+  if (typeof raw.path !== 'string' || !plugins.path.isAbsolute(raw.path)) {
+    throw new Error('pnpm list --global omitted its global package root.');
+  }
+  const dependencies: Record<string, { version: string; path: string }> = {};
+  for (const packageName of [
+    upgradePackageTransitionSource.packageName,
+    upgradePackageTransitionTarget.packageName,
+  ]) {
+    const dependency = raw.dependencies?.[packageName];
+    if (!dependency) continue;
+    if (
+      typeof dependency.version !== 'string'
+      || typeof dependency.path !== 'string'
+      || !plugins.path.isAbsolute(dependency.path)
+    ) throw new Error(`pnpm reported invalid global metadata for ${packageName}.`);
+    dependencies[packageName] = {
+      version: dependency.version,
+      path: dependency.path,
+    };
+  }
+  return { path: raw.path, dependencies };
+};
+
+const packageGroupDirectory = (
+  globalRootArg: string,
+  packagePathArg: string,
+  packageNameArg: string,
+): string => {
+  const relative = plugins.path.relative(globalRootArg, packagePathArg);
+  if (
+    !relative
+    || relative === '..'
+    || relative.startsWith(`..${plugins.path.sep}`)
+    || plugins.path.isAbsolute(relative)
+  ) throw new Error(`pnpm reported ${packageNameArg} outside its global root.`);
+  const expectedSuffix = plugins.path.join('node_modules', ...packageNameArg.split('/'));
+  const suffix = `${plugins.path.sep}${expectedSuffix}`;
+  if (!relative.endsWith(suffix)) {
+    throw new Error(`pnpm reported an unexpected global path for ${packageNameArg}.`);
+  }
+  const groupRelativePath = relative.slice(0, -suffix.length);
+  if (!groupRelativePath || groupRelativePath.includes(plugins.path.sep)) {
+    throw new Error(`pnpm reported an invalid isolated group for ${packageNameArg}.`);
+  }
+  return plugins.path.join(globalRootArg, groupRelativePath);
+};
+
+const readExactGlobalPackage = async (
+  contextArg: IPackageTransitionContext,
+  dependencyArg: { version: string; path: string },
+  identityArg: {
+    packageName: string;
+    version: string;
+    managementVersion: number;
+    cliName: string;
+    cliRelativePath: string;
+  },
+): Promise<IExactGlobalPackageInstallation> => {
+  if (dependencyArg.version !== identityArg.version) {
+    throw new Error(
+      `The pnpm-global ${identityArg.packageName} version is ${dependencyArg.version}, not ${identityArg.version}.`,
+    );
+  }
+  const groupDirectory = packageGroupDirectory(
+    contextArg.globalRoot,
+    dependencyArg.path,
+    identityArg.packageName,
+  );
+  const packageDirectory = await plugins.fs.promises.realpath(dependencyArg.path);
+  const packageJsonPath = plugins.path.join(packageDirectory, 'package.json');
+  const packageJsonStats = await plugins.fs.promises.stat(packageJsonPath);
+  if (!packageJsonStats.isFile() || packageJsonStats.size < 2 || packageJsonStats.size > 64 * 1024) {
+    throw new Error(`The pnpm-global ${identityArg.packageName} metadata is not a bounded file.`);
+  }
+  let packageJson: unknown;
+  try {
+    packageJson = JSON.parse(await plugins.fs.promises.readFile(packageJsonPath, 'utf8')) as unknown;
+  } catch (errorArg) {
+    throw new Error(`The pnpm-global ${identityArg.packageName} metadata is malformed.`, {
+      cause: errorArg,
+    });
+  }
+  if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
+    throw new Error(`The pnpm-global ${identityArg.packageName} metadata is invalid.`);
+  }
+  const manifest = packageJson as Record<string, unknown>;
+  const bin = manifest.bin;
+  if (
+    manifest.name !== identityArg.packageName
+    || manifest.version !== identityArg.version
+    || manifest.controllerUpgradeManagementVersion !== identityArg.managementVersion
+    || !bin
+    || typeof bin !== 'object'
+    || Array.isArray(bin)
+    || Object.keys(bin).length !== 1
+    || (bin as Record<string, unknown>)[identityArg.cliName] !== identityArg.cliRelativePath
+  ) throw new Error(`The pnpm-global ${identityArg.packageName} identity is incompatible.`);
+  const cliPath = await plugins.fs.promises.realpath(
+    plugins.path.join(packageDirectory, identityArg.cliRelativePath),
+  );
+  if (!(await plugins.fs.promises.stat(cliPath)).isFile()) {
+    throw new Error(`The pnpm-global ${identityArg.packageName} direct CLI is not a file.`);
+  }
+  return {
+    packageManagerPath: contextArg.packageManagerPath,
+    globalRoot: contextArg.globalRoot,
+    globalBinDirectory: contextArg.globalBinDirectory,
+    packageDirectory,
+    cliPath,
+    packageVersion: identityArg.version,
+    packageName: identityArg.packageName,
+    cliName: identityArg.cliName,
+    cliRelativePath: identityArg.cliRelativePath,
+    listedPackagePath: dependencyArg.path,
+    groupDirectory,
+  };
+};
+
+const readGlobalShimTarget = async (
+  binDirectoryArg: string,
+  cliNameArg: string,
+): Promise<string | undefined> => {
+  const shimPath = plugins.path.join(binDirectoryArg, cliNameArg);
+  let stats: plugins.fs.Stats;
+  try {
+    stats = await plugins.fs.promises.lstat(shimPath);
+  } catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw errorArg;
+  }
+  if (
+    !stats.isFile()
+    || stats.isSymbolicLink()
+    || stats.size < 2
+    || stats.size > 1024 * 1024
+    || (stats.mode & 0o111) === 0
+  ) throw new Error(`The pnpm-global ${cliNameArg} shim is not a bounded executable file.`);
+  const contents = await plugins.fs.promises.readFile(shimPath, 'utf8');
+  const markers = [...contents.matchAll(/^# cmd-shim-target=(.+)$/gm)];
+  if (markers.length !== 1 || !plugins.path.isAbsolute(markers[0][1])) {
+    throw new Error(`The pnpm-global ${cliNameArg} shim has no exact ownership marker.`);
+  }
+  try {
+    return await plugins.fs.promises.realpath(markers[0][1]);
+  } catch (errorArg) {
+    throw new Error(`The pnpm-global ${cliNameArg} shim target is unavailable.`, {
+      cause: errorArg,
+    });
+  }
+};
+
+const assertGlobalShimOwnership = async (
+  binDirectoryArg: string,
+  cliNameArg: string,
+  cliPathArg?: string,
+): Promise<void> => {
+  const markerTarget = await readGlobalShimTarget(binDirectoryArg, cliNameArg);
+  if (markerTarget === undefined) {
+    if (cliPathArg === undefined) return;
+    throw new Error(`The pnpm-global ${cliNameArg} shim is missing.`);
+  }
+  if (cliPathArg === undefined) {
+    throw new Error(`The pnpm-global ${cliNameArg} shim survived without its owning package.`);
+  }
+  if (markerTarget !== cliPathArg) {
+    throw new Error(`The pnpm-global ${cliNameArg} shim is owned by a different package.`);
+  }
+};
+
+const maximumPnpmGlobalGroups = 1_024;
+
+const findExactGlobalPackageLink = async (
+  globalRootArg: string,
+  packageNameArg: string,
+  packageDirectoryArg: string,
+): Promise<{ listedPackagePath: string; groupDirectory: string }> => {
+  const entries = await plugins.fs.promises.readdir(globalRootArg, { withFileTypes: true });
+  if (entries.length > maximumPnpmGlobalGroups) {
+    throw new Error('The pnpm global root exceeds the recovery scan bound.');
+  }
+  const matches: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const candidate = plugins.path.join(
+      globalRootArg,
+      entry.name,
+      'node_modules',
+      ...packageNameArg.split('/'),
+    );
+    try {
+      if (await plugins.fs.promises.realpath(candidate) === packageDirectoryArg) {
+        matches.push(candidate);
+      }
+    } catch (errorArg) {
+      const code = (errorArg as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT' && code !== 'ENOTDIR') throw errorArg;
+    }
+  }
+  if (matches.length !== 1) {
+    throw new Error(`Expected exactly one filesystem-owned installation of ${packageNameArg}.`);
+  }
+  return {
+    listedPackagePath: matches[0],
+    groupDirectory: packageGroupDirectory(globalRootArg, matches[0], packageNameArg),
+  };
+};
+
+const resolveAuthoritativeRecoveryInstallation = async (
+  transactionArg: TUpgradeTransaction,
+  capturedInstallationArg: IPnpmGlobalInstallation,
+): Promise<IPnpmGlobalInstallation> => {
+  const [globalRoot, globalBinDirectory, packageManagerPath] = await Promise.all([
+    plugins.fs.promises.realpath(capturedInstallationArg.globalRoot),
+    plugins.fs.promises.realpath(capturedInstallationArg.globalBinDirectory),
+    plugins.fs.promises.realpath(capturedInstallationArg.packageManagerPath),
+  ]);
+  if (
+    globalRoot !== capturedInstallationArg.globalRoot
+    || globalBinDirectory !== capturedInstallationArg.globalBinDirectory
+    || packageManagerPath !== capturedInstallationArg.packageManagerPath
+  ) throw new Error('The captured pnpm recovery paths changed unexpectedly.');
+  await plugins.fs.promises.access(packageManagerPath, plugins.fs.constants.X_OK);
+
+  const currentIdentity: {
+    packageName: string;
+    versions: string[];
+    managementVersion: number;
+    cliName: string;
+    cliRelativePath: string;
+  } = transactionArg.version === upgradePackageTransitionTransactionVersion
+    ? (() => {
+        const identity = transactionArg.targetPackageCommitStarted === true
+          ? upgradePackageTransitionTarget
+          : upgradePackageTransitionSource;
+        return {
+          packageName: identity.packageName,
+          versions: [identity.version],
+          managementVersion: identity.managementVersion,
+          cliName: identity.cliName,
+          cliRelativePath: identity.cliRelativePath,
+        };
+      })()
+    : (() => {
+        const identity = String(controllerPackageName) === upgradePackageTransitionTarget.packageName
+          ? upgradePackageTransitionTarget
+          : upgradePackageTransitionSource;
+        return {
+          packageName: String(controllerPackageName),
+          versions: [
+            transactionArg.sourceVersion,
+            ...(transactionArg.targetVersion ? [transactionArg.targetVersion] : []),
+          ],
+          managementVersion: Number(controllerUpgradeManagementVersion),
+          cliName: identity.cliName,
+          cliRelativePath: identity.cliRelativePath,
+        };
+      })();
+  const cliPath = await readGlobalShimTarget(globalBinDirectory, currentIdentity.cliName);
+  if (!cliPath) {
+    throw new Error(`The authoritative pnpm-global ${currentIdentity.cliName} shim is missing.`);
+  }
+  const packageDirectory = plugins.path.dirname(cliPath);
+  if (
+    await plugins.fs.promises.realpath(
+      plugins.path.join(packageDirectory, currentIdentity.cliRelativePath),
+    ) !== cliPath
+  ) throw new Error('The authoritative recovery CLI path is incompatible.');
+  const packageJsonPath = plugins.path.join(packageDirectory, 'package.json');
+  const packageJsonStats = await plugins.fs.promises.stat(packageJsonPath);
+  if (!packageJsonStats.isFile() || packageJsonStats.size < 2 || packageJsonStats.size > 64 * 1024) {
+    throw new Error('The authoritative recovery package metadata is not a bounded file.');
+  }
+  let packageJson: unknown;
+  try {
+    packageJson = JSON.parse(await plugins.fs.promises.readFile(packageJsonPath, 'utf8')) as unknown;
+  } catch (errorArg) {
+    throw new Error('The authoritative recovery package metadata is malformed.', {
+      cause: errorArg,
+    });
+  }
+  if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
+    throw new Error('The authoritative recovery package metadata is invalid.');
+  }
+  const manifest = packageJson as Record<string, unknown>;
+  const bin = manifest.bin;
+  if (
+    manifest.name !== currentIdentity.packageName
+    || typeof manifest.version !== 'string'
+    || !currentIdentity.versions.includes(manifest.version)
+    || manifest.controllerUpgradeManagementVersion !== currentIdentity.managementVersion
+    || !bin
+    || typeof bin !== 'object'
+    || Array.isArray(bin)
+    || Object.keys(bin).length !== 1
+    || (bin as Record<string, unknown>)[currentIdentity.cliName]
+      !== currentIdentity.cliRelativePath
+  ) throw new Error('The authoritative recovery package identity is incompatible.');
+  if (!(await plugins.fs.promises.stat(cliPath)).isFile()) {
+    throw new Error('The authoritative recovery CLI is not a file.');
+  }
+  await findExactGlobalPackageLink(globalRoot, currentIdentity.packageName, packageDirectory);
+  return {
+    packageManagerPath,
+    globalRoot,
+    globalBinDirectory,
+    packageDirectory,
+    cliPath,
+    packageVersion: manifest.version,
+  };
+};
+
+const verifyPackageTransitionTopology = async (
+  contextArg: IPackageTransitionContext,
+  expectedArg: TPackageTransitionTopology,
+): Promise<IPackageTransitionTopology> => {
+  const output = await runCapturedCommand(
+    contextArg.packageManagerPath,
+    [
+      'list',
+      '--global',
+      upgradePackageTransitionSource.packageName,
+      upgradePackageTransitionTarget.packageName,
+      '--depth=0',
+      '--json',
+    ],
+    createPackageManagerEnvironment(),
+  );
+  const listed = parseGlobalListDependencies(output);
+  if (await plugins.fs.promises.realpath(listed.path) !== contextArg.globalRoot) {
+    throw new Error('The pnpm global root changed during the package transition.');
+  }
+  const sourceDependency = listed.dependencies[upgradePackageTransitionSource.packageName];
+  const targetDependency = listed.dependencies[upgradePackageTransitionTarget.packageName];
+  const sourceExpected = expectedArg !== 'target-only';
+  const targetExpected = expectedArg !== 'source-only';
+  if (Boolean(sourceDependency) !== sourceExpected || Boolean(targetDependency) !== targetExpected) {
+    throw new Error(`The pnpm-global package topology is not ${expectedArg}.`);
+  }
+  const [source, target] = await Promise.all([
+    sourceDependency
+      ? readExactGlobalPackage(contextArg, sourceDependency, upgradePackageTransitionSource)
+      : undefined,
+    targetDependency
+      ? readExactGlobalPackage(contextArg, targetDependency, upgradePackageTransitionTarget)
+      : undefined,
+  ]);
+  if (expectedArg === 'grouped' && source?.groupDirectory !== target?.groupDirectory) {
+    throw new Error('The source and target packages are not installed in one pnpm group.');
+  }
+  await Promise.all([
+    assertGlobalShimOwnership(
+      contextArg.globalBinDirectory,
+      upgradePackageTransitionSource.cliName,
+      source?.cliPath,
+    ),
+    assertGlobalShimOwnership(
+      contextArg.globalBinDirectory,
+      upgradePackageTransitionTarget.cliName,
+      target?.cliPath,
+    ),
+  ]);
+  return {
+    ...(source ? { source } : {}),
+    ...(target ? { target } : {}),
+  };
+};
+
+const resolvePackageManagerContext = async (): Promise<IPackageTransitionContext> => {
+  if (process.platform !== 'linux' && process.platform !== 'darwin') {
+    throw new Error(`${currentCliName} upgrade is currently supported on Linux and macOS only.`);
+  }
+  const environment = createPackageManagerEnvironment();
+  const packageManagerPath = await findExecutable('pnpm', environment);
+  const globalRoot = await assertSingleLineAbsolutePath(
+    await runCapturedCommand(packageManagerPath, ['root', '--global'], environment),
+    'pnpm root --global',
+  );
+  const globalBinDirectory = await assertSingleLineAbsolutePath(
+    await runCapturedCommand(packageManagerPath, ['bin', '--global'], environment),
+    'pnpm bin --global',
+  );
+  return { packageManagerPath, globalRoot, globalBinDirectory };
+};
+
+export const resolveInheritedUpgradeTargetInstallation = async (
+  transactionArg: TUpgradeTransaction,
+): Promise<IPnpmGlobalInstallation> => {
+  if (transactionArg.version === upgradeCoordinationVersion) {
+    return await resolvePnpmGlobalInstallation();
+  }
+  const topology = await verifyPackageTransitionTopology(
+    await resolvePackageManagerContext(),
+    'target-only',
+  );
+  if (!topology.target) throw new Error('The committed target package is unavailable.');
+  return topology.target;
+};
+
+export const resolveCurrentCliPath = async (): Promise<string> => {
+  return await plugins.fs.promises.realpath(
+    plugins.url.fileURLToPath(new URL('../cli.js', import.meta.url)),
+  );
+};
+
+const currentPackageIsDevelopmentCheckout = async (): Promise<boolean> => {
+  const packageRoot = plugins.path.dirname(await resolveCurrentCliPath());
+  try {
+    const stats = await plugins.fs.promises.lstat(plugins.path.join(packageRoot, '.git'));
+    return stats.isDirectory() || stats.isFile();
+  } catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw errorArg;
+  }
+};
+
+export const resolveCurrentPnpmGlobalInstallation = async (): Promise<IPnpmGlobalInstallation> => {
+  const [installation, cliPath] = await Promise.all([
+    resolvePnpmGlobalInstallation(),
+    resolveCurrentCliPath(),
+  ]);
+  if (installation.cliPath !== cliPath || installation.packageVersion !== commitinfo.version) {
+    throw new Error(`${currentCliName} upgrade must be run from the active pnpm-global installation.`);
+  }
+  return installation;
+};
+
+export const tryResolveCurrentPnpmGlobalInstallation = async (
+): Promise<IPnpmGlobalInstallation | undefined> => {
+  if (await currentPackageIsDevelopmentCheckout()) return undefined;
+  return await resolveCurrentPnpmGlobalInstallation();
+};
+
+const parseSemver = (valueArg: string): IParsedSemver => {
+  const match = semverPattern.exec(valueArg);
+  if (!match) throw new Error(`Invalid semantic version: ${valueArg}`);
+  const prerelease = match[4]?.split('.') ?? [];
+  if (prerelease.some((identifierArg) => /^\d+$/.test(identifierArg)
+    && identifierArg.length > 1
+    && identifierArg.startsWith('0'))) {
+    throw new Error(`Invalid semantic version: ${valueArg}`);
+  }
+  return {
+    major: match[1],
+    minor: match[2],
+    patch: match[3],
+    prerelease,
+  };
+};
+
+const compareNumericStrings = (leftArg: string, rightArg: string): number => {
+  if (leftArg.length !== rightArg.length) return leftArg.length < rightArg.length ? -1 : 1;
+  return leftArg === rightArg ? 0 : leftArg < rightArg ? -1 : 1;
+};
+
+export const compareSemver = (leftArg: string, rightArg: string): number => {
+  const left = parseSemver(leftArg);
+  const right = parseSemver(rightArg);
+  for (const key of ['major', 'minor', 'patch'] as const) {
+    const comparison = compareNumericStrings(left[key], right[key]);
+    if (comparison !== 0) return comparison;
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    if (left.prerelease.length === right.prerelease.length) return 0;
+    return left.prerelease.length === 0 ? 1 : -1;
+  }
+  const identifierCount = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < identifierCount; index++) {
+    const leftIdentifier = left.prerelease[index];
+    const rightIdentifier = right.prerelease[index];
+    if (leftIdentifier === undefined || rightIdentifier === undefined) {
+      return leftIdentifier === rightIdentifier ? 0 : leftIdentifier === undefined ? -1 : 1;
+    }
+    if (leftIdentifier === rightIdentifier) continue;
+    const leftNumeric = /^\d+$/.test(leftIdentifier);
+    const rightNumeric = /^\d+$/.test(rightIdentifier);
+    if (leftNumeric && rightNumeric) {
+      return compareNumericStrings(leftIdentifier, rightIdentifier);
+    }
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftIdentifier < rightIdentifier ? -1 : 1;
+  }
+  return 0;
+};
+
+const readLatestVersion = async (installationArg: IPnpmGlobalInstallation): Promise<string> => {
+  const output = await runCapturedCommand(
+    installationArg.packageManagerPath,
+    [
+      'view',
+      controllerPackageName,
+      'dist-tags.latest',
+      `--registry=${npmRegistryUrl}`,
+      '--json',
+    ],
+    createPackageManagerEnvironment(),
+  );
+  let version: unknown;
+  try {
+    version = JSON.parse(output) as unknown;
+  } catch {
+    throw new Error('pnpm view returned malformed JSON for the npm latest tag.');
+  }
+  if (typeof version !== 'string') {
+    throw new Error('The npm latest tag did not resolve to one package version.');
+  }
+  parseSemver(version);
+  return version;
+};
+
+const assertInternalRegistryUrl = (valueArg: string): string => {
+  let parsed: URL;
+  try {
+    parsed = new URL(valueArg);
+  } catch (errorArg) {
+    throw new Error('The internal upgrade registry URL is invalid.', { cause: errorArg });
+  }
+  if (
+    (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+    || parsed.username.length > 0
+    || parsed.password.length > 0
+  ) throw new Error('The internal upgrade registry URL is unsafe.');
+  return parsed.toString();
+};
+
+const resolveExactPackageTransitionTarget = async (
+  contextArg: IPackageTransitionContext,
+  registryUrlArg: string,
+): Promise<void> => {
+  const output = await runCapturedCommand(
+    contextArg.packageManagerPath,
+    [
+      'view',
+      `${upgradePackageTransitionTarget.packageName}@${upgradePackageTransitionTarget.version}`,
+      `--registry=${registryUrlArg}`,
+      '--json',
+    ],
+    createPackageManagerEnvironment(),
+  );
+  let metadata: unknown;
+  try {
+    metadata = JSON.parse(output) as unknown;
+  } catch (errorArg) {
+    throw new Error('pnpm view returned malformed target package metadata.', { cause: errorArg });
+  }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    throw new Error('pnpm view returned invalid target package metadata.');
+  }
+  const manifest = metadata as Record<string, unknown>;
+  const bin = manifest.bin;
+  if (
+    manifest.name !== upgradePackageTransitionTarget.packageName
+    || manifest.version !== upgradePackageTransitionTarget.version
+    || manifest.controllerUpgradeManagementVersion
+      !== upgradePackageTransitionTarget.managementVersion
+    || !bin
+    || typeof bin !== 'object'
+    || Array.isArray(bin)
+    || Object.keys(bin).length !== 1
+    || (bin as Record<string, unknown>)[upgradePackageTransitionTarget.cliName]
+      !== upgradePackageTransitionTarget.cliRelativePath
+  ) throw new Error('The exact target package metadata is incompatible.');
+};
+
+const openUpgradeLog = async (tokenArg: string): Promise<{
+  handle: plugins.fs.promises.FileHandle;
+  path: string;
+}> => {
+  const directory = controllerDataDirectory();
+  await plugins.fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
+  const directoryStats = await plugins.fs.promises.lstat(directory);
+  if (
+    !directoryStats.isDirectory()
+    || directoryStats.isSymbolicLink()
+    || (typeof process.getuid === 'function' && directoryStats.uid !== process.getuid())
+    || (directoryStats.mode & 0o077) !== 0
+  ) {
+    throw new Error(`The ${currentCliName} upgrade log directory is unsafe: ${directory}`);
+  }
+  const existingLogs: Array<{ path: string; mtimeMs: number }> = [];
+  for (const entry of await plugins.fs.promises.readdir(directory, { withFileTypes: true })) {
+    if (!entry.isFile() || !upgradeLogPattern.test(entry.name)) continue;
+    const existingPath = plugins.path.join(directory, entry.name);
+    const stats = await plugins.fs.promises.lstat(existingPath);
+    if (
+      !stats.isFile()
+      || stats.isSymbolicLink()
+      || (typeof process.getuid === 'function' && stats.uid !== process.getuid())
+      || (stats.mode & 0o077) !== 0
+    ) {
+      throw new Error(`An existing ${currentCliName} upgrade log is unsafe: ${existingPath}`);
+    }
+    existingLogs.push({ path: existingPath, mtimeMs: stats.mtimeMs });
+  }
+  existingLogs.sort((leftArg, rightArg) => rightArg.mtimeMs - leftArg.mtimeMs);
+  for (const staleLog of existingLogs.slice(retainedUpgradeLogCount - 1)) {
+    if (Date.now() - staleLog.mtimeMs < minimumPrunableUpgradeLogAgeMs) continue;
+    await plugins.fs.promises.unlink(staleLog.path).catch((errorArg) => {
+      if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+    });
+  }
+  const filePath = plugins.path.join(
+    directory,
+    `upgrade-${new Date().toISOString().replaceAll(':', '')}-${plugins.crypto
+      .createHash('sha256')
+      .update(tokenArg, 'utf8')
+      .digest('hex')
+      .slice(0, 10)}.log`,
+  );
+  const handle = await plugins.fs.promises.open(
+    filePath,
+    plugins.fs.constants.O_WRONLY
+      | plugins.fs.constants.O_APPEND
+      | plugins.fs.constants.O_CREAT
+      | plugins.fs.constants.O_EXCL
+      | plugins.fs.constants.O_NOFOLLOW,
+    0o600,
+  );
+  return { handle, path: filePath };
+};
+
+interface IUpgradeRecoveryWorkerContext {
+  version: 1;
+  mode: 'recovery';
+  canonicalGlobalRoot: string;
+  packageManagerPath: string;
+  globalBinDirectory: string;
+  cliPath: string;
+}
+
+const serializeUpgradeRecoveryWorkerContext = (
+  contextArg: IUpgradeRecoveryWorkerContext,
+): string => Buffer.from(JSON.stringify(contextArg), 'utf8').toString('base64url');
+
+const parseUpgradeRecoveryWorkerContext = (
+  valueArg: unknown,
+): IUpgradeRecoveryWorkerContext => {
+  if (typeof valueArg !== 'string' || valueArg.length < 16 || valueArg.length > 16 * 1024) {
+    throw new Error('The internal upgrade recovery worker context is invalid.');
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(valueArg, 'base64url').toString('utf8')) as unknown;
+  } catch (errorArg) {
+    throw new Error('The internal upgrade recovery worker context is malformed.', {
+      cause: errorArg,
+    });
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('The internal upgrade recovery worker context is malformed.');
+  }
+  const context = parsed as Record<string, unknown>;
+  if (
+    Object.keys(context).length !== 6
+    || ![
+      'version',
+      'mode',
+      'canonicalGlobalRoot',
+      'packageManagerPath',
+      'globalBinDirectory',
+      'cliPath',
+    ].every((keyArg) => Object.hasOwn(context, keyArg))
+    || context.version !== 1
+    || context.mode !== 'recovery'
+    || typeof context.canonicalGlobalRoot !== 'string'
+    || typeof context.packageManagerPath !== 'string'
+    || typeof context.globalBinDirectory !== 'string'
+    || typeof context.cliPath !== 'string'
+    || !plugins.path.isAbsolute(context.canonicalGlobalRoot)
+    || !plugins.path.isAbsolute(context.packageManagerPath)
+    || !plugins.path.isAbsolute(context.globalBinDirectory)
+    || !plugins.path.isAbsolute(context.cliPath)
+  ) throw new Error('The internal upgrade recovery worker context is incompatible.');
+  return context as unknown as IUpgradeRecoveryWorkerContext;
+};
+
+const waitForProcessGroupDrain = async (
+  processGroupIdArg: number,
+  timeoutMsArg: number,
+): Promise<boolean> => {
+  const deadline = Date.now() + timeoutMsArg;
+  while (Date.now() < deadline) {
+    if ((await readProcessGroupMemberPids(processGroupIdArg)).length === 0) return true;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return (await readProcessGroupMemberPids(processGroupIdArg)).length === 0;
+};
+
+const terminateSpawnedDetachedWorker = async (processIdArg: number): Promise<void> => {
+  const signal = (signalArg: NodeJS.Signals): void => {
+    try {
+      process.kill(-processIdArg, signalArg);
+    } catch (errorArg) {
+      if ((errorArg as NodeJS.ErrnoException).code !== 'ESRCH') throw errorArg;
+    }
+  };
+  signal('SIGTERM');
+  if (await waitForProcessGroupDrain(processIdArg, commandGroupDrainTimeoutMs)) return;
+  signal('SIGKILL');
+  if (!await waitForProcessGroupDrain(processIdArg, commandGroupDrainTimeoutMs)) {
+    throw new Error('The detached upgrade worker candidate group did not terminate.');
+  }
+};
+
+interface ICandidateCleanupRetryDependencies {
+  beforeAttempt?: (processIdArg?: number) => Promise<void>;
+  delay?: (millisecondsArg: number) => Promise<void>;
+}
+
+const retryCandidateCleanupUntilDrained = async (
+  cleanupArg: () => Promise<void>,
+  dependenciesArg: ICandidateCleanupRetryDependencies = {},
+  processIdArg?: number,
+): Promise<void> => {
+  const delay = dependenciesArg.delay
+    ?? (async (millisecondsArg: number) => new Promise((resolve) => (
+      setTimeout(resolve, millisecondsArg)
+    )));
+  while (true) {
+    try {
+      await dependenciesArg.beforeAttempt?.(processIdArg);
+      await cleanupArg();
+      return;
+    } catch {
+      await delay(candidateCleanupRetryIntervalMs);
+    }
+  }
+};
+
+interface IDetachedUpgradeWorkerProcessDependencies {
+  readProcessIdentity?: typeof readControllerProcessIdentity;
+  processHasCliCommand?: typeof processIdentityHasCliCommand;
+  candidateCleanup?: ICandidateCleanupRetryDependencies;
+}
+
+const launchDetachedUpgradeWorkerProcess = async (optionsArg: {
+  installation: IPnpmGlobalInstallation;
+  payload: IUpgradeWorkerPayload;
+  environment?: NodeJS.ProcessEnv;
+  internalArguments?: string[];
+}, dependenciesArg: IDetachedUpgradeWorkerProcessDependencies = {}): Promise<IDetachedUpgradeWorker> => {
+  if (process.platform !== 'linux' && process.platform !== 'darwin') {
+    throw new Error(`${currentCliName} upgrade is currently supported on Linux and macOS only.`);
+  }
+  const log = await openUpgradeLog(optionsArg.payload.token);
+  let child: plugins.childProcess.ChildProcess | undefined;
+  let logClosed = false;
+  try {
+    const launchedChild = plugins.childProcess.spawn(
+      process.execPath,
+      [
+        optionsArg.installation.cliPath,
+        '__upgrade-worker',
+        serializeUpgradeWorkerPayload(optionsArg.payload),
+        ...(optionsArg.internalArguments ?? []),
+      ],
+      {
+        cwd: plugins.os.homedir(),
+        detached: true,
+        env: {
+          ...(optionsArg.environment ?? process.env),
+          [upgradeTokenEnvironmentVariable]: optionsArg.payload.token,
+        },
+        shell: false,
+        stdio: ['ignore', log.handle.fd, log.handle.fd],
+      },
+    );
+    child = launchedChild;
+    await new Promise<void>((resolve, reject) => {
+      launchedChild.once('spawn', resolve);
+      launchedChild.once('error', reject);
+    });
+    await log.handle.close();
+    logClosed = true;
+    if (!launchedChild.pid) {
+      throw new Error(`The detached ${currentCliName} upgrade worker has no process ID.`);
+    }
+    const identity = await (dependenciesArg.readProcessIdentity
+      ?? readControllerProcessIdentity)(launchedChild.pid);
+    if (
+      !identity
+      || !identity.processGroupLeader
+      || identity.processGroupId !== launchedChild.pid
+      || !await (dependenciesArg.processHasCliCommand ?? processIdentityHasCliCommand)(
+        identity,
+        optionsArg.installation.cliPath,
+        '__upgrade-worker',
+      )
+    ) throw new Error('The detached upgrade worker candidate identity is invalid.');
+    launchedChild.unref();
+    return {
+      pid: identity.pid,
+      processGroupId: identity.processGroupId,
+      fingerprint: identity.fingerprint,
+      cliPath: optionsArg.installation.cliPath,
+      logFilePath: log.path,
+    };
+  } catch (errorArg) {
+    const errors: unknown[] = [errorArg];
+    if (!logClosed) {
+      try {
+        await log.handle.close();
+        logClosed = true;
+      } catch (logCleanupErrorArg) {
+        errors.push(logCleanupErrorArg);
+      }
+    }
+    if (child?.pid) {
+      await retryCandidateCleanupUntilDrained(
+        async () => terminateSpawnedDetachedWorker(child!.pid!),
+        dependenciesArg.candidateCleanup,
+        child.pid,
+      );
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(
+        errors,
+        'The detached upgrade worker launch and log cleanup both failed.',
+      );
+    }
+    throw errorArg;
+  }
+};
+
+interface ILaunchDetachedUpgradeWorkerOptions {
+  installation: IPnpmGlobalInstallation;
+  payload: IUpgradeWorkerPayload;
+  environment?: NodeJS.ProcessEnv;
+}
+
+export function launchDetachedUpgradeWorker(
+  optionsArg: ILaunchDetachedUpgradeWorkerOptions,
+): Promise<IDetachedUpgradeWorker>;
+export async function launchDetachedUpgradeWorker(
+  optionsArg: ILaunchDetachedUpgradeWorkerOptions,
+  dependenciesArg: IDetachedUpgradeWorkerProcessDependencies = {},
+): Promise<IDetachedUpgradeWorker> {
+  return await launchDetachedUpgradeWorkerProcess(optionsArg, dependenciesArg);
+}
+
+const launchDetachedRecoveryWorker = async (optionsArg: {
+  installation: IPnpmGlobalInstallation;
+  payload: IUpgradeWorkerPayload;
+  environment?: NodeJS.ProcessEnv;
+}): Promise<IDetachedUpgradeWorker> => await launchDetachedUpgradeWorkerProcess({
+  ...optionsArg,
+  internalArguments: [serializeUpgradeRecoveryWorkerContext({
+    version: 1,
+    mode: 'recovery',
+    canonicalGlobalRoot: optionsArg.installation.globalRoot,
+    packageManagerPath: optionsArg.installation.packageManagerPath,
+    globalBinDirectory: optionsArg.installation.globalBinDirectory,
+    cliPath: optionsArg.installation.cliPath,
+  })],
+});
+
+const runLoggedCommand = async (optionsArg: {
+  executable: string;
+  arguments: string[];
+  environment: NodeJS.ProcessEnv;
+  timeoutMs: number;
+}): Promise<void> => {
+  await runManagedCommand({
+    ...optionsArg,
+    captureOutput: false,
+    outputByteLimit: loggedCommandOutputByteLimit,
+  });
+};
+
+const installVersion = async (
+  installationArg: IPnpmGlobalInstallation,
+  versionArg: string,
+): Promise<void> => {
+  await runLoggedCommand({
+    executable: installationArg.packageManagerPath,
+    arguments: [
+      'add',
+      '--global',
+      '--save-exact',
+      '--yes',
+      '--reporter=append-only',
+      '--allow-build=node-pty',
+      '--allow-build=fs-ext-extra-prebuilt',
+      `--registry=${npmRegistryUrl}`,
+      `${controllerPackageName}@${versionArg}`,
+    ],
+    environment: createPackageManagerEnvironment(),
+    timeoutMs: packageManagerTimeoutMs,
+  });
+};
+
+const packageAddArguments = (packageSpecArg: string, registryUrlArg: string): string[] => [
+  'add',
+  '--global',
+  '--save-exact',
+  '--yes',
+  '--reporter=append-only',
+  '--allow-build=node-pty',
+  '--allow-build=fs-ext-extra-prebuilt',
+  `--registry=${registryUrlArg}`,
+  packageSpecArg,
+];
+
+const preparePackageAdd = async (
+  contextArg: IPackageTransitionContext,
+  packageSpecArg: string,
+  registryUrlArg: string,
+): Promise<IPreparedManagedCommand> => await prepareManagedCommand({
+  executable: contextArg.packageManagerPath,
+  arguments: packageAddArguments(packageSpecArg, registryUrlArg),
+  environment: createPackageManagerEnvironment(),
+  timeoutMs: packageManagerTimeoutMs,
+  captureOutput: false,
+  outputByteLimit: loggedCommandOutputByteLimit,
+});
+
+const addExactPackage = async (
+  contextArg: IPackageTransitionContext,
+  packageSpecArg: string,
+  registryUrlArg: string,
+): Promise<void> => {
+  await runPreparedManagedCommand(
+    await preparePackageAdd(contextArg, packageSpecArg, registryUrlArg),
+  );
+};
+
+const assertExpectedController = (
+  statusArg: IControllerStatus,
+  expectedArg: IUpgradeExpectedController,
+): void => {
+  if (
+    statusArg.controllerPid !== expectedArg.pid
+    || statusArg.processGroupId !== expectedArg.processGroupId
+    || statusArg.processFingerprint !== expectedArg.processFingerprint
+    || statusArg.lifecycleState !== 'ready'
+  ) {
+    throw new Error('The running controller changed after the upgrade request was authorized.');
+  }
+};
+
+const prepareControllerStart = async (
+  installationArg: IPnpmGlobalInstallation,
+  portArg: number,
+  tokenArg: string,
+): Promise<IPreparedManagedCommand> => await prepareManagedCommand({
+    executable: process.execPath,
+    arguments: [installationArg.cliPath, 'start', '--port', String(portArg)],
+    environment: {
+      ...process.env,
+      [upgradeTokenEnvironmentVariable]: tokenArg,
+    },
+    timeoutMs: controllerRestartTimeoutMs,
+    captureOutput: false,
+    outputByteLimit: loggedCommandOutputByteLimit,
+  });
+
+const startController = async (
+  installationArg: IPnpmGlobalInstallation,
+  portArg: number,
+  tokenArg: string,
+): Promise<void> => await runPreparedManagedCommand(
+  await prepareControllerStart(installationArg, portArg, tokenArg),
+).then(() => undefined);
+
+const retainedTargetTransactionMatches = (
+  transactionArg: TUpgradeTransaction,
+  installationArg: IPnpmGlobalInstallation,
+): transactionArg is TUpgradeTransaction & {
+  targetVersion: string;
+  targetStartupInvoked: true;
+  controller: NonNullable<TUpgradeTransaction['controller']>;
+} => Boolean(
+  !transactionArg.terminal
+  && transactionArg.controllerWasRunning
+  && transactionArg.targetStartupInvoked === true
+  && (transactionArg.version === upgradeCoordinationVersion
+    || transactionArg.targetPackageCommitted === true)
+  && (transactionArg.phase === 'restarting' || transactionArg.phase === 'continuing')
+  && transactionArg.targetVersion === installationArg.packageVersion
+  && transactionArg.controller?.command === '__serve'
+  && transactionArg.controller.cliPath === installationArg.cliPath
+  && transactionArg.controller.pid === transactionArg.controller.processGroupId
+  && /^linux:[1-9][0-9]*:[1-9][0-9]*$/.test(transactionArg.controller.fingerprint)
+);
+
+export interface IRetainedUpgradeTargetAuthorityOptions {
+  coordinator: UpgradeCoordinator;
+  token: string;
+}
+
+export interface IRetainedUpgradeTargetAuthorityDependencies {
+  platform?: NodeJS.Platform;
+  resolveInstallation?: (
+    transactionArg: TUpgradeTransaction,
+  ) => Promise<IPnpmGlobalInstallation>;
+  inspectProcess?: typeof inspectControllerProcess;
+}
+
+export const retainedUpgradeTargetIsAuthoritative = async (
+  optionsArg: IRetainedUpgradeTargetAuthorityOptions,
+  dependenciesArg: IRetainedUpgradeTargetAuthorityDependencies = {},
+): Promise<boolean> => {
+  if ((dependenciesArg.platform ?? process.platform) !== 'linux') return false;
+  const resolveInstallation = dependenciesArg.resolveInstallation
+    ?? resolveInheritedUpgradeTargetInstallation;
+  const inspectProcess = dependenciesArg.inspectProcess ?? inspectControllerProcess;
+  const transaction = await optionsArg.coordinator.readTransaction(optionsArg.token);
+  const installation = await resolveInstallation(transaction);
+  if (!retainedTargetTransactionMatches(transaction, installation)) return false;
+  const controller = transaction.controller;
+  const identity = await inspectProcess({
+    pid: controller.pid,
+    cliPath: controller.cliPath,
+    port: transaction.port,
+    expectedProcessGroupId: controller.processGroupId,
+    expectedFingerprint: controller.fingerprint,
+    command: controller.command,
+  });
+  if (!identity?.processGroupLeader || identity.fingerprint !== controller.fingerprint) return false;
+
+  const currentTransaction = await optionsArg.coordinator.readTransaction(optionsArg.token);
+  const currentInstallation = await resolveInstallation(currentTransaction);
+  if (
+    !retainedTargetTransactionMatches(currentTransaction, currentInstallation)
+    || currentTransaction.controller.pid !== controller.pid
+    || currentTransaction.controller.processGroupId !== controller.processGroupId
+    || currentTransaction.controller.fingerprint !== controller.fingerprint
+    || currentTransaction.controller.cliPath !== controller.cliPath
+  ) return false;
+  const currentIdentity = await inspectProcess({
+    pid: currentTransaction.controller.pid,
+    cliPath: currentTransaction.controller.cliPath,
+    port: currentTransaction.port,
+    expectedProcessGroupId: currentTransaction.controller.processGroupId,
+    expectedFingerprint: currentTransaction.controller.fingerprint,
+    command: currentTransaction.controller.command,
+  });
+  return Boolean(
+    currentIdentity?.processGroupLeader
+    && currentIdentity.fingerprint === currentTransaction.controller.fingerprint
+  );
+};
+
+const updateWorkerProgress = async (
+  coordinatorArg: UpgradeCoordinator,
+  tokenArg: string,
+  phaseArg: TUpgradeTransaction['phase'],
+  messageArg: string,
+): Promise<TUpgradeTransaction> => coordinatorArg.mutateTransaction(tokenArg, (current) => ({
+  ...current,
+  phase: phaseArg,
+  message: messageArg,
+}));
+
+const grantControllerAction = async (
+  coordinatorArg: UpgradeCoordinator,
+  tokenArg: string,
+  statusArg: IControllerStatus,
+  actionArg: 'prepare' | 'finalize',
+  modeArg?: 'continue' | 'compensate' | 'reopen',
+): Promise<void> => coordinatorArg.createControllerActionGrant({
+  token: tokenArg,
+  action: actionArg,
+  ...(modeArg === undefined ? {} : { mode: modeArg }),
+  packageVersion: statusArg.packageVersion,
+  controller: {
+    pid: statusArg.controllerPid,
+    processGroupId: statusArg.processGroupId,
+    processFingerprint: statusArg.processFingerprint,
+  },
+});
+
+const queryUpgradeManagedController = async (
+  portArg: number,
+  identityArg: {
+    packageName: string;
+    packageVersion: string;
+    managementVersion: number;
+  },
+): Promise<IControllerStatus> => queryControllerStatus(portArg, {
+  packageName: identityArg.packageName,
+  packageVersion: identityArg.packageVersion,
+  upgradeManagementVersion: identityArg.managementVersion,
+});
+
+const finalizeControllerUpgrade = async (
+  coordinatorArg: UpgradeCoordinator,
+  tokenArg: string,
+  statusArg: IControllerStatus,
+  modeArg: 'continue' | 'compensate' | 'reopen',
+): Promise<void> => {
+  await grantControllerAction(coordinatorArg, tokenArg, statusArg, 'finalize', modeArg);
+  let response: Awaited<ReturnType<typeof requestControllerUpgradeFinalize>>;
+  try {
+    response = await requestControllerUpgradeFinalize(statusArg.controllerPid > 0
+      ? (await coordinatorArg.readTransaction(tokenArg)).port
+      : 0, tokenArg, modeArg);
+  } finally {
+    await coordinatorArg.removeControllerActionGrant('finalize', tokenArg);
+  }
+  if (response.failed > 0) {
+    throw new Error(`${response.failed} paused session${response.failed === 1 ? '' : 's'} could not be continued.`);
+  }
+};
+
+export interface IWaitForControllerUpgradePreparationOptions {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  targetVersion: string;
+  gracePeriodMs: number;
+  controllerIsLive: () => Promise<boolean>;
+  now?: () => number;
+  delay?: (millisecondsArg: number) => Promise<void>;
+}
+
+export const waitForControllerUpgradePreparation = async (
+  optionsArg: IWaitForControllerUpgradePreparationOptions,
+): Promise<TUpgradeTransaction> => {
+  const now = optionsArg.now ?? Date.now;
+  const delay = optionsArg.delay
+    ?? (async (millisecondsArg: number) => new Promise((resolve) => (
+      setTimeout(resolve, millisecondsArg)
+    )));
+  const acceptanceReconciliationDeadline = now()
+    + upgradePreparationAcceptanceReconciliationMs;
+  let nextSourceCheckAt = 0;
+  while (true) {
+    const currentTime = now();
+    if (currentTime >= nextSourceCheckAt) {
+      if (!await optionsArg.controllerIsLive()) {
+        throw new Error('The source controller exited before upgrade preparation completed.');
+      }
+      nextSourceCheckAt = currentTime + upgradePreparationSourceCheckMs;
+    }
+    const transaction = await optionsArg.coordinator.readTransaction(optionsArg.token);
+    if (transaction.terminal) {
+      throw new Error(
+        transaction.terminal.error
+        ?? transaction.message
+        ?? 'The source controller rejected upgrade preparation.',
+      );
+    }
+    if (
+      transaction.preparationAcceptedAt === undefined
+      || transaction.preparationDeadlineAt === undefined
+    ) {
+      if (currentTime >= acceptanceReconciliationDeadline) {
+        throw new Error('The source controller did not durably accept upgrade preparation.');
+      }
+      await delay(upgradePreparationPollMs);
+      continue;
+    }
+    if (
+      transaction.targetVersion !== optionsArg.targetVersion
+      || transaction.gracePeriodMs !== optionsArg.gracePeriodMs
+      || transaction.preparationDeadlineAt
+        !== transaction.preparationAcceptedAt + optionsArg.gracePeriodMs
+    ) throw new Error('The durable upgrade preparation does not match the worker request.');
+    if (transaction.phase === 'stopping') {
+      if (
+        transaction.preparationCompletedAt === undefined
+        || transaction.preparationCompletedAt < transaction.preparationAcceptedAt
+        || transaction.preparationCompletedAt > transaction.preparationDeadlineAt
+      ) throw new Error('The durable upgrade preparation completion is invalid.');
+      return transaction;
+    }
+    if (currentTime > transaction.preparationDeadlineAt + upgradePreparationCleanupAllowanceMs) {
+      throw new Error('Timed out waiting for upgrade preparation cleanup to settle.');
+    }
+    await delay(upgradePreparationPollMs);
+  }
+};
+
+export interface IPrepareAndStopRunningControllerOptions {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  port: number;
+  targetVersion: string;
+  gracePeriodMs: number;
+  currentInstallation: IPnpmGlobalInstallation;
+  runningStatus: IControllerStatus;
+}
+
+export interface IPrepareAndStopRunningControllerDependencies {
+  requestPrepareBegin?: typeof requestControllerUpgradePrepareBegin;
+  stopController?: typeof stopVerifiedController;
+  controllerIsLive?: () => Promise<boolean>;
+  now?: () => number;
+  delay?: (millisecondsArg: number) => Promise<void>;
+}
+
+export const prepareAndStopRunningController = async (
+  optionsArg: IPrepareAndStopRunningControllerOptions,
+  dependenciesArg: IPrepareAndStopRunningControllerDependencies = {},
+): Promise<void> => {
+  await updateWorkerProgress(
+    optionsArg.coordinator,
+    optionsArg.token,
+    'preparing',
+    `Preparing sessions for ${optionsArg.currentInstallation.packageVersion} to ${optionsArg.targetVersion}.`,
+  );
+  await grantControllerAction(
+    optionsArg.coordinator,
+    optionsArg.token,
+    optionsArg.runningStatus,
+    'prepare',
+  );
+  let beginError: unknown;
+  try {
+    await (dependenciesArg.requestPrepareBegin ?? requestControllerUpgradePrepareBegin)(
+      optionsArg.port,
+      optionsArg.token,
+      optionsArg.targetVersion,
+      optionsArg.gracePeriodMs,
+    );
+  } catch (errorArg) {
+    beginError = errorArg;
+  } finally {
+    await optionsArg.coordinator.removeControllerActionGrant('prepare', optionsArg.token);
+  }
+  try {
+    await waitForControllerUpgradePreparation({
+      coordinator: optionsArg.coordinator,
+      token: optionsArg.token,
+      targetVersion: optionsArg.targetVersion,
+      gracePeriodMs: optionsArg.gracePeriodMs,
+      controllerIsLive: dependenciesArg.controllerIsLive ?? (async () => Boolean(
+        await inspectControllerProcess({
+          pid: optionsArg.runningStatus.controllerPid,
+          cliPath: optionsArg.currentInstallation.cliPath,
+          port: optionsArg.port,
+          expectedProcessGroupId: optionsArg.runningStatus.processGroupId,
+          expectedFingerprint: optionsArg.runningStatus.processFingerprint,
+          command: optionsArg.runningStatus.processMode === 'detached' ? '__serve' : 'foreground',
+        }),
+      )),
+      ...(dependenciesArg.now ? { now: dependenciesArg.now } : {}),
+      ...(dependenciesArg.delay ? { delay: dependenciesArg.delay } : {}),
+    });
+  } catch (errorArg) {
+    if (beginError === undefined) throw errorArg;
+    throw new AggregateError(
+      [beginError, errorArg],
+      'The source controller did not complete asynchronous upgrade preparation.',
+    );
+  }
+  await (dependenciesArg.stopController ?? stopVerifiedController)({
+    status: optionsArg.runningStatus,
+    cliPath: optionsArg.currentInstallation.cliPath,
+    port: optionsArg.port,
+  });
+};
+
+const restorePreviousInstallation = async (
+  installationArg: IPnpmGlobalInstallation,
+): Promise<IPnpmGlobalInstallation> => {
+  try {
+    const current = await resolvePnpmGlobalInstallation();
+    if (current.packageVersion === installationArg.packageVersion) return current;
+  } catch (errorArg) {
+    if (errorContainsCommandCleanupFailure(errorArg)) throw errorArg;
+    // Reinstalling the exact prior version is the authoritative rollback.
+  }
+  await installVersion(installationArg, installationArg.packageVersion);
+  const restored = await resolvePnpmGlobalInstallation();
+  if (restored.packageVersion !== installationArg.packageVersion) {
+    throw new Error('The previous pnpm-global package version was not restored.');
+  }
+  return restored;
+};
+
+const errorContainsCommandCleanupFailure = (errorArg: unknown): boolean => {
+  if (errorArg instanceof UpgradeCommandCleanupError) return true;
+  if (errorArg instanceof AggregateError) {
+    return errorArg.errors.some((nestedErrorArg) => (
+      errorContainsCommandCleanupFailure(nestedErrorArg)
+    ));
+  }
+  return errorArg instanceof Error
+    && errorArg.cause !== undefined
+    && errorContainsCommandCleanupFailure(errorArg.cause);
+};
+
+const sourceControllerIdentity = (transactionArg: TUpgradeTransaction): {
+  packageName: string;
+  packageVersion: string;
+  managementVersion: number;
+} => transactionArg.version === upgradeCoordinationVersion
+  ? {
+      packageName: controllerPackageName,
+      packageVersion: transactionArg.sourceVersion,
+      managementVersion: controllerUpgradeManagementVersion,
+    }
+  : {
+      packageName: transactionArg.sourcePackageName,
+      packageVersion: transactionArg.sourceVersion,
+      managementVersion: transactionArg.sourceManagementVersion,
+    };
+
+const requirePackageTransitionTransaction = (
+  transactionArg: TUpgradeTransaction,
+): IUpgradeTransactionV3 => {
+  if (transactionArg.version !== upgradePackageTransitionTransactionVersion) {
+    throw new Error('The package-transition transaction changed format.');
+  }
+  return transactionArg;
+};
+
+const targetControllerIdentity = (transactionArg: TUpgradeTransaction): {
+  packageName: string;
+  packageVersion: string;
+  managementVersion: number;
+} => transactionArg.version === upgradeCoordinationVersion
+  ? {
+      packageName: controllerPackageName,
+      packageVersion: transactionArg.targetVersion
+        ?? (() => { throw new Error('The upgrade target version is unavailable.'); })(),
+      managementVersion: controllerUpgradeManagementVersion,
+    }
+  : {
+      packageName: transactionArg.targetPackageName,
+      packageVersion: transactionArg.targetVersion,
+      managementVersion: transactionArg.targetManagementVersion,
+    };
+
+export const assertInheritedUpgradeTransaction = (
+  transactionArg: TUpgradeTransaction,
+  currentIdentityArg: {
+    packageName: string;
+    packageVersion: string;
+    managementVersion: number;
+    cliName: string;
+    cliRelativePath: string;
+  },
+): void => {
+  if (
+    !transactionArg.controllerWasRunning
+    || transactionArg.targetStartupInvoked !== true
+    || transactionArg.targetVersion !== currentIdentityArg.packageVersion
+  ) throw new Error('The inherited upgrade transaction did not authorize target startup.');
+  if (transactionArg.version === upgradeCoordinationVersion) {
+    if (
+      currentIdentityArg.packageName !== String(controllerPackageName)
+      || currentIdentityArg.managementVersion !== controllerUpgradeManagementVersion
+    ) throw new Error('The inherited v2 upgrade target identity is incompatible.');
+    return;
+  }
+  if (
+    transactionArg.targetPackageCommitted !== true
+    || transactionArg.targetPackageName !== currentIdentityArg.packageName
+    || transactionArg.targetManagementVersion !== currentIdentityArg.managementVersion
+    || transactionArg.targetCliName !== currentIdentityArg.cliName
+    || transactionArg.targetCliRelativePath !== currentIdentityArg.cliRelativePath
+  ) throw new Error('The inherited v3 upgrade target identity is incompatible.');
+};
+
+const runPackageTransitionUpgradeWorker = async (optionsArg: {
+  coordinator: UpgradeCoordinator;
+  payload: IUpgradeWorkerPayload;
+  transaction: IUpgradeTransactionV3;
+  currentInstallation: IPnpmGlobalInstallation;
+  registryUrl: string;
+}): Promise<void> => {
+  const {
+    coordinator,
+    payload,
+    transaction: initialTransaction,
+    currentInstallation,
+    registryUrl,
+  } = optionsArg;
+  if (
+    commitinfo.name !== initialTransaction.sourcePackageName
+    || commitinfo.version !== initialTransaction.sourceVersion
+    || currentInstallation.packageVersion !== initialTransaction.sourceVersion
+  ) throw new Error('The package-transition worker is not running from the exact bridge package.');
+  const context: IPackageTransitionContext = {
+    packageManagerPath: currentInstallation.packageManagerPath,
+    globalRoot: currentInstallation.globalRoot,
+    globalBinDirectory: currentInstallation.globalBinDirectory,
+  };
+
+  // Registry validation is deliberately complete before controller preparation or package mutation.
+  await resolveExactPackageTransitionTarget(context, registryUrl);
+  await coordinator.mutateTransaction(payload.token, (current) => {
+    if (current.version !== upgradePackageTransitionTransactionVersion) {
+      throw new Error('The package-transition transaction changed format.');
+    }
+    return {
+      ...current,
+      phase: 'checking',
+      message: `Resolved exact target ${current.targetPackageName}@${current.targetVersion}.`,
+    };
+  });
+  process.stdout.write(
+    `${initialTransaction.sourceCliName} upgrade: resolved ${initialTransaction.targetPackageName}@${initialTransaction.targetVersion}.\n`,
+  );
+
+  const controllerProcesses = await listControllerProcessesForCli(currentInstallation.cliPath);
+  let runningStatus: IControllerStatus | undefined;
+  if (payload.expectedController) {
+    runningStatus = await queryControllerStatus(payload.port, {
+      packageName: initialTransaction.sourcePackageName,
+      packageVersion: initialTransaction.sourceVersion,
+      protocolVersion: controllerProtocolVersion,
+      upgradeManagementVersion: initialTransaction.sourceManagementVersion,
+    });
+    assertExpectedController(runningStatus, payload.expectedController);
+    if (
+      controllerProcesses.length !== 1
+      || controllerProcesses[0].identity.pid !== runningStatus.controllerPid
+      || controllerProcesses[0].port !== payload.port
+    ) throw new Error('Additional or mismatched pnpm-global controller instances prevent upgrade.');
+  } else if (controllerProcesses.length > 0) {
+    throw new Error('A pnpm-global controller started after the upgrade request; upgrade aborted.');
+  } else if (await isLoopbackPortListening(payload.port)) {
+    throw new Error(
+      `The requested controller port became occupied while ${initialTransaction.sourceCliName} upgrade was starting.`,
+    );
+  }
+
+  if (runningStatus) {
+    await prepareAndStopRunningController({
+      coordinator,
+      token: payload.token,
+      port: payload.port,
+      targetVersion: initialTransaction.targetVersion,
+      gracePeriodMs: payload.gracePeriodMs,
+      currentInstallation,
+      runningStatus,
+    });
+    process.stdout.write(`${initialTransaction.sourceCliName} upgrade: bridge controller stopped cleanly.\n`);
+  }
+
+  let targetInstallation: IPnpmGlobalInstallation;
+  try {
+    await updateWorkerProgress(
+      coordinator,
+      payload.token,
+      'installing',
+      `Transitioning ${initialTransaction.sourcePackageName} to ${initialTransaction.targetPackageName}.`,
+    );
+    if (await isLoopbackPortListening(payload.port)) {
+      throw new Error('The controller port became occupied before package replacement.');
+    }
+    const sourceDataWriters = await listControllerDataWriterProcessesForCli(
+      currentInstallation.cliPath,
+    );
+    if (sourceDataWriters.length > 0) {
+      const writer = sourceDataWriters[0];
+      throw new Error(
+        `Package replacement is blocked by ${writer.kind} source writer PID ${writer.identity.pid}.`,
+      );
+    }
+
+    const sourceSpec = `${initialTransaction.sourcePackageName}@${initialTransaction.sourceVersion}`;
+    const targetSpec = `${initialTransaction.targetPackageName}@${initialTransaction.targetVersion}`;
+    const groupedSpec = `${sourceSpec},${targetSpec}`;
+    let current = requirePackageTransitionTransaction(
+      await coordinator.readTransaction(payload.token),
+    );
+
+    if (current.targetPackageCommitStarted !== true) {
+      if (current.groupedTargetVerified !== true) {
+        if (current.packageTransitionStarted === true) {
+          await addExactPackage(context, sourceSpec, registryUrl);
+          await verifyPackageTransitionTopology(context, 'source-only');
+        }
+        const groupedAdd = await preparePackageAdd(context, groupedSpec, registryUrl);
+        if (current.packageTransitionStarted !== true) {
+          current = requirePackageTransitionTransaction(await coordinator.mutateTransaction(payload.token, (transaction) => {
+            if (transaction.version !== upgradePackageTransitionTransactionVersion) {
+              throw new Error('The package-transition transaction changed format.');
+            }
+            return {
+              ...transaction,
+              packageTransitionStarted: true as const,
+              message: `Installing grouped ${sourceSpec},${targetSpec}.`,
+            };
+          }));
+        }
+        await runPreparedManagedCommand(groupedAdd);
+        await verifyPackageTransitionTopology(context, 'grouped');
+        current = requirePackageTransitionTransaction(await coordinator.mutateTransaction(payload.token, (transaction) => {
+          if (transaction.version !== upgradePackageTransitionTransactionVersion) {
+            throw new Error('The package-transition transaction changed format.');
+          }
+          return {
+            ...transaction,
+            groupedTargetVerified: true as const,
+            message: 'Verified the grouped bridge and target package topology.',
+          };
+        }));
+      } else {
+        await verifyPackageTransitionTopology(context, 'grouped');
+      }
+
+      const targetAdd = await preparePackageAdd(context, targetSpec, registryUrl);
+      current = requirePackageTransitionTransaction(await coordinator.mutateTransaction(payload.token, (transaction) => {
+        if (transaction.version !== upgradePackageTransitionTransactionVersion) {
+          throw new Error('The package-transition transaction changed format.');
+        }
+        return {
+          ...transaction,
+          targetPackageCommitStarted: true as const,
+          message: `Committing exact target ${targetSpec}.`,
+        };
+      }));
+      await runPreparedManagedCommand(targetAdd);
+    } else if (current.targetPackageCommitted !== true) {
+      await addExactPackage(context, targetSpec, registryUrl);
+    }
+
+    if (current.targetPackageCommitted !== true) {
+      const topology = await verifyPackageTransitionTopology(context, 'target-only');
+      if (!topology.target) throw new Error('The exact target package installation is unavailable.');
+      targetInstallation = topology.target;
+      await coordinator.mutateTransaction(payload.token, (transaction) => {
+        if (transaction.version !== upgradePackageTransitionTransactionVersion) {
+          throw new Error('The package-transition transaction changed format.');
+        }
+        return {
+          ...transaction,
+          targetPackageCommitted: true as const,
+          message: `Committed exact target ${targetSpec}.`,
+        };
+      });
+    } else {
+      const topology = await verifyPackageTransitionTopology(context, 'target-only');
+      if (!topology.target) throw new Error('The exact target package installation is unavailable.');
+      targetInstallation = topology.target;
+    }
+  } catch (upgradeErrorArg) {
+    if (errorContainsCommandCleanupFailure(upgradeErrorArg)) throw upgradeErrorArg;
+    const current = await coordinator.readTransaction(payload.token);
+    if (
+      current.version === upgradePackageTransitionTransactionVersion
+      && current.targetPackageCommitStarted === true
+    ) throw upgradeErrorArg;
+    const recoveryErrors: unknown[] = [upgradeErrorArg];
+    try {
+      const sourceSpec = `${initialTransaction.sourcePackageName}@${initialTransaction.sourceVersion}`;
+      if (
+        current.version === upgradePackageTransitionTransactionVersion
+        && current.packageTransitionStarted === true
+      ) await addExactPackage(context, sourceSpec, registryUrl);
+      const sourceTopology = await verifyPackageTransitionTopology(context, 'source-only');
+      if (!sourceTopology.source) throw new Error('The exact bridge package was not restored.');
+      if (runningStatus) {
+        await startController(sourceTopology.source, payload.port, payload.token);
+        const restoredStatus = await queryUpgradeManagedController(
+          payload.port,
+          sourceControllerIdentity(initialTransaction),
+        );
+        await finalizeControllerUpgrade(
+          coordinator,
+          payload.token,
+          restoredStatus,
+          'compensate',
+        );
+        process.stdout.write(
+          `${initialTransaction.sourceCliName} upgrade: bridge package restored and restarted.\n`,
+        );
+      }
+    } catch (recoveryErrorArg) {
+      recoveryErrors.push(recoveryErrorArg);
+    }
+    throw new AggregateError(
+      recoveryErrors,
+      `${initialTransaction.sourceCliName} upgrade failed before target package commit began.`,
+    );
+  }
+
+  process.stdout.write(
+    `${initialTransaction.sourceCliName} upgrade: committed ${initialTransaction.targetPackageName}@${initialTransaction.targetVersion}.\n`,
+  );
+  if (runningStatus) {
+    await updateWorkerProgress(
+      coordinator,
+      payload.token,
+      'restarting',
+      `Restarting ${initialTransaction.targetPackageName} ${initialTransaction.targetVersion}.`,
+    );
+    const preparedTargetStart = await prepareControllerStart(
+      targetInstallation,
+      payload.port,
+      payload.token,
+    );
+    await coordinator.mutateTransaction(payload.token, (current) => {
+      if (current.version !== upgradePackageTransitionTransactionVersion) {
+        throw new Error('The package-transition transaction changed format.');
+      }
+      return {
+        ...current,
+        targetStartupInvoked: true as const,
+        message: `Invoking ${current.targetPackageName} ${current.targetVersion}.`,
+      };
+    });
+    await runPreparedManagedCommand(preparedTargetStart);
+    const targetStatus = await queryUpgradeManagedController(
+      payload.port,
+      targetControllerIdentity(initialTransaction),
+    );
+    await updateWorkerProgress(
+      coordinator,
+      payload.token,
+      payload.continueSessions ? 'continuing' : 'restarting',
+      payload.continueSessions
+        ? 'Continuing sessions paused for the upgrade.'
+        : 'Reopening harness prompt admission.',
+    );
+    await finalizeControllerUpgrade(
+      coordinator,
+      payload.token,
+      targetStatus,
+      payload.continueSessions ? 'continue' : 'reopen',
+    );
+    process.stdout.write(
+      `${initialTransaction.sourceCliName} upgrade: target controller restarted on port ${payload.port}.\n`,
+    );
+  }
+  await coordinator.finishTransaction(
+    payload.token,
+    true,
+    `Upgrade to ${initialTransaction.targetPackageName}@${initialTransaction.targetVersion} completed.`,
+  );
+};
+
+interface IUpgradeWorkerInternalOptions {
+  registryUrl?: string;
+  recoveryContext?: string;
+  recoveryBody?: (optionsArg: {
+    coordinator: UpgradeCoordinator;
+    token: string;
+    transaction: TUpgradeTransaction;
+    installation: IPnpmGlobalInstallation;
+  }) => Promise<boolean>;
+  isCommandCleanupFailure?: (errorArg: unknown) => boolean;
+}
+
+const runRecoveryUpgradeWorker = async (
+  payloadArg: IUpgradeWorkerPayload,
+  internalOptionsArg: IUpgradeWorkerInternalOptions,
+): Promise<void> => {
+  const context = parseUpgradeRecoveryWorkerContext(internalOptionsArg.recoveryContext);
+  const coordinator = new UpgradeCoordinator(context.canonicalGlobalRoot);
+  let lock: Awaited<ReturnType<UpgradeCoordinator['acquireUpgradeLock']>> | undefined;
+  let releaseLock = true;
+  try {
+    await coordinator.waitForWorkerAcknowledgement(payloadArg.token, 10_000);
+    lock = await coordinator.acquireUpgradeLock({
+      token: payloadArg.token,
+      cliPath: context.cliPath,
+    });
+    await coordinator.waitForStartLeasesToDrain(lock);
+    const transaction = await coordinator.readTransaction(payloadArg.token);
+    if (transaction.terminal) return;
+    if (
+      transaction.port !== payloadArg.port
+      || transaction.gracePeriodMs !== payloadArg.gracePeriodMs
+      || transaction.continueSessions !== payloadArg.continueSessions
+    ) throw new Error('The recovery worker payload does not match its upgrade transaction.');
+    const identity = await readControllerProcessIdentity(process.pid);
+    if (
+      !identity
+      || !identity.processGroupLeader
+      || identity.processGroupId !== process.pid
+      || transaction.worker?.pid !== identity.pid
+      || transaction.worker.processGroupId !== identity.processGroupId
+      || transaction.worker.fingerprint !== identity.fingerprint
+      || transaction.worker.cliPath !== context.cliPath
+    ) throw new Error('The recovery worker transaction identity is incompatible.');
+    const installation = await resolveAuthoritativeRecoveryInstallation(transaction, {
+      packageManagerPath: context.packageManagerPath,
+      globalRoot: context.canonicalGlobalRoot,
+      globalBinDirectory: context.globalBinDirectory,
+      packageDirectory: plugins.path.dirname(context.cliPath),
+      cliPath: context.cliPath,
+      packageVersion: '',
+    });
+    if (installation.cliPath !== context.cliPath) {
+      throw new Error('The authoritative recovery CLI changed during handoff.');
+    }
+    upgradeWorkerCliPath = installation.cliPath;
+    await (internalOptionsArg.recoveryBody ?? recoverStalledUpgradeUnderLock)({
+      coordinator,
+      token: payloadArg.token,
+      transaction,
+      installation,
+    });
+  } catch (errorArg) {
+    const cleanupFailed = (internalOptionsArg.isCommandCleanupFailure
+      ?? errorContainsCommandCleanupFailure)(errorArg);
+    if (cleanupFailed) releaseLock = false;
+    await coordinator.mutateTransaction(payloadArg.token, (current) => ({
+      ...current,
+      message: errorArg instanceof Error ? errorArg.message : String(errorArg),
+    })).catch(() => undefined);
+    throw errorArg;
+  } finally {
+    if (releaseLock) await lock?.release();
+  }
+};
+
+export function runUpgradeWorker(payloadArg: IUpgradeWorkerPayload): Promise<void>;
+export async function runUpgradeWorker(
+  payloadArg: IUpgradeWorkerPayload,
+  internalOptionsArg: IUpgradeWorkerInternalOptions = {},
+): Promise<void> {
+  const environmentToken = process.env[upgradeTokenEnvironmentVariable];
+  if (environmentToken !== payloadArg.token) {
+    throw new Error(`The detached ${currentCliName} upgrade worker token binding is invalid.`);
+  }
+  delete process.env[upgradeTokenEnvironmentVariable];
+  if (internalOptionsArg.recoveryContext !== undefined) {
+    await runRecoveryUpgradeWorker(payloadArg, internalOptionsArg);
+    return;
+  }
+  const installation = await resolveCurrentPnpmGlobalInstallation();
+  upgradeWorkerCliPath = installation.cliPath;
+  const coordinator = new UpgradeCoordinator(installation.globalRoot);
+  let lock: Awaited<ReturnType<UpgradeCoordinator['acquireUpgradeLock']>> | undefined;
+  let releaseLock = true;
+  try {
+    await coordinator.registerWorker(payloadArg.token, installation.cliPath);
+    await coordinator.waitForWorkerAcknowledgement(payloadArg.token, 10_000);
+    lock = await coordinator.acquireUpgradeLock({
+      token: payloadArg.token,
+      cliPath: installation.cliPath,
+    });
+    await coordinator.waitForStartLeasesToDrain(lock);
+    const currentInstallation = await resolveCurrentPnpmGlobalInstallation();
+    if (currentInstallation.globalRoot !== installation.globalRoot) {
+      throw new Error(`The pnpm global root changed while ${currentCliName} upgrade was starting.`);
+    }
+    const transaction = await coordinator.readTransaction(payloadArg.token);
+    if (transaction.version === upgradePackageTransitionTransactionVersion) {
+      await runPackageTransitionUpgradeWorker({
+        coordinator,
+        payload: payloadArg,
+        transaction,
+        currentInstallation,
+        registryUrl: assertInternalRegistryUrl(internalOptionsArg.registryUrl ?? npmRegistryUrl),
+      });
+      return;
+    }
+    const latestVersion = await readLatestVersion(currentInstallation);
+    await coordinator.mutateTransaction(payloadArg.token, (current) => {
+      if (current.version !== upgradeCoordinationVersion) {
+        throw new Error('The same-package upgrade transaction changed format.');
+      }
+      return {
+        ...current,
+        targetVersion: latestVersion,
+        phase: 'checking',
+        message: `Installed ${currentInstallation.packageVersion}; npm latest is ${latestVersion}.`,
+      };
+    });
+    const versionComparison = compareSemver(latestVersion, currentInstallation.packageVersion);
+    process.stdout.write(
+      `${currentCliName} upgrade: installed ${currentInstallation.packageVersion}, npm latest ${latestVersion}.\n`,
+    );
+    if (versionComparison <= 0) {
+      process.stdout.write(
+        versionComparison === 0
+          ? `${currentCliName} upgrade: already up to date.\n`
+          : `${currentCliName} upgrade: installed version is newer than npm latest; refusing to downgrade.\n`,
+      );
+      await coordinator.finishTransaction(
+        payloadArg.token,
+        true,
+        versionComparison === 0
+          ? 'Already up to date.'
+          : 'Installed version is newer than npm latest; no downgrade was performed.',
+      );
+      return;
+    }
+
+    const controllerProcesses = await listControllerProcessesForCli(currentInstallation.cliPath);
+    let runningStatus: IControllerStatus | undefined;
+    if (payloadArg.expectedController) {
+      runningStatus = await queryControllerStatus(payloadArg.port, {
+        packageName: controllerPackageName,
+        packageVersion: currentInstallation.packageVersion,
+        protocolVersion: controllerProtocolVersion,
+        upgradeManagementVersion: controllerUpgradeManagementVersion,
+      });
+      assertExpectedController(runningStatus, payloadArg.expectedController);
+      if (
+        controllerProcesses.length !== 1
+        || controllerProcesses[0].identity.pid !== runningStatus.controllerPid
+        || controllerProcesses[0].port !== payloadArg.port
+      ) {
+        throw new Error('Additional or mismatched pnpm-global controller instances prevent upgrade.');
+      }
+    } else if (controllerProcesses.length > 0) {
+      throw new Error('A pnpm-global controller started after the upgrade request; upgrade aborted.');
+    } else if (await isLoopbackPortListening(payloadArg.port)) {
+      throw new Error(
+        `The requested controller port became occupied while ${currentCliName} upgrade was starting.`,
+      );
+    }
+
+    if (runningStatus) {
+      await prepareAndStopRunningController({
+        coordinator,
+        token: payloadArg.token,
+        port: payloadArg.port,
+        targetVersion: latestVersion,
+        gracePeriodMs: payloadArg.gracePeriodMs,
+        currentInstallation,
+        runningStatus,
+      });
+      process.stdout.write(`${currentCliName} upgrade: previous controller stopped cleanly.\n`);
+    }
+
+    let upgradedInstallation: IPnpmGlobalInstallation;
+    try {
+      await updateWorkerProgress(
+        coordinator,
+        payloadArg.token,
+        'installing',
+        `Installing ${controllerPackageName} ${latestVersion}.`,
+      );
+      if (await isLoopbackPortListening(payloadArg.port)) {
+        throw new Error('The controller port became occupied before package replacement.');
+      }
+      const sourceDataWriters = await listControllerDataWriterProcessesForCli(
+        currentInstallation.cliPath,
+      );
+      if (sourceDataWriters.length > 0) {
+        const writer = sourceDataWriters[0];
+        throw new Error(
+          `Package replacement is blocked by ${writer.kind} source writer PID ${writer.identity.pid}.`,
+        );
+      }
+      await installVersion(currentInstallation, latestVersion);
+      upgradedInstallation = await resolvePnpmGlobalInstallation();
+      if (upgradedInstallation.packageVersion !== latestVersion) {
+        throw new Error('pnpm completed without installing the requested npm latest version.');
+      }
+    } catch (upgradeErrorArg) {
+      if (errorContainsCommandCleanupFailure(upgradeErrorArg)) throw upgradeErrorArg;
+      const recoveryErrors: unknown[] = [upgradeErrorArg];
+      try {
+        const restored = await restorePreviousInstallation(currentInstallation);
+        if (runningStatus) {
+          await startController(restored, payloadArg.port, payloadArg.token);
+          const restoredStatus = await queryUpgradeManagedController(
+            payloadArg.port,
+            {
+              packageName: controllerPackageName,
+              packageVersion: restored.packageVersion,
+              managementVersion: controllerUpgradeManagementVersion,
+            },
+          );
+          await finalizeControllerUpgrade(
+            coordinator,
+            payloadArg.token,
+            restoredStatus,
+            'compensate',
+          );
+          process.stdout.write(
+            `${currentCliName} upgrade: previous controller version restored and restarted.\n`,
+          );
+        }
+      } catch (recoveryErrorArg) {
+        recoveryErrors.push(recoveryErrorArg);
+      }
+      throw new AggregateError(
+        recoveryErrors,
+        `${currentCliName} upgrade failed before the new controller started.`,
+      );
+    }
+
+    process.stdout.write(`${currentCliName} upgrade: installed ${latestVersion}.\n`);
+    if (runningStatus) {
+      // From this point onward rollback is unsafe: startup may run data migrations.
+      await updateWorkerProgress(
+        coordinator,
+        payloadArg.token,
+        'restarting',
+        `Restarting ${controllerPackageName} ${latestVersion}.`,
+      );
+      await coordinator.mutateTransaction(payloadArg.token, (current) => ({
+        ...current,
+        targetStartupInvoked: true,
+        message: `Invoking ${controllerPackageName} ${latestVersion}.`,
+      }));
+      await startController(upgradedInstallation, payloadArg.port, payloadArg.token);
+      const upgradedStatus = await queryUpgradeManagedController(payloadArg.port, {
+        packageName: controllerPackageName,
+        packageVersion: latestVersion,
+        managementVersion: controllerUpgradeManagementVersion,
+      });
+      await updateWorkerProgress(
+        coordinator,
+        payloadArg.token,
+        payloadArg.continueSessions ? 'continuing' : 'restarting',
+        payloadArg.continueSessions
+          ? 'Continuing sessions paused for the upgrade.'
+          : 'Reopening harness prompt admission.',
+      );
+      await finalizeControllerUpgrade(
+        coordinator,
+        payloadArg.token,
+        upgradedStatus,
+        payloadArg.continueSessions ? 'continue' : 'reopen',
+      );
+      process.stdout.write(
+        `${currentCliName} upgrade: controller restarted on port ${payloadArg.port}.\n`,
+      );
+    }
+    await coordinator.finishTransaction(
+      payloadArg.token,
+      true,
+      `Upgrade to ${latestVersion} completed.`,
+    );
+  } catch (errorArg) {
+    if (errorContainsCommandCleanupFailure(errorArg)) releaseLock = false;
+    const failedTransaction = await coordinator.readTransaction(payloadArg.token).catch(() => undefined);
+    if (
+      (failedTransaction?.version === upgradePackageTransitionTransactionVersion
+        ? failedTransaction.targetPackageCommitStarted === true
+        : failedTransaction?.targetStartupInvoked === true)
+      || errorContainsCommandCleanupFailure(errorArg)
+    ) {
+      await coordinator.mutateTransaction(payloadArg.token, (current) => ({
+        ...current,
+        message: errorArg instanceof Error ? errorArg.message : String(errorArg),
+      })).catch(() => undefined);
+      throw errorArg;
+    }
+    await coordinator.finishTransaction(
+      payloadArg.token,
+      false,
+      'Upgrade failed.',
+      errorArg instanceof Error ? errorArg.message : String(errorArg),
+    ).catch(() => undefined);
+    throw errorArg;
+  } finally {
+    if (releaseLock) await lock?.release();
+  }
+}
+
+const recoverPackageTransition = async (optionsArg: {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  transaction: IUpgradeTransactionV3;
+  installation: IPnpmGlobalInstallation;
+}): Promise<boolean> => {
+  const context: IPackageTransitionContext = {
+    packageManagerPath: optionsArg.installation.packageManagerPath,
+    globalRoot: optionsArg.installation.globalRoot,
+    globalBinDirectory: optionsArg.installation.globalBinDirectory,
+  };
+  const registryUrl = assertInternalRegistryUrl(npmRegistryUrl);
+  const transaction = optionsArg.transaction;
+  if (transaction.targetPackageCommitStarted === true) {
+    const targetSpec = `${transaction.targetPackageName}@${transaction.targetVersion}`;
+    let targetTopology: IPackageTransitionTopology;
+    if (transaction.targetPackageCommitted === true) {
+      try {
+        targetTopology = await verifyPackageTransitionTopology(context, 'target-only');
+      } catch (verificationErrorArg) {
+        try {
+          await addExactPackage(context, targetSpec, registryUrl);
+          targetTopology = await verifyPackageTransitionTopology(context, 'target-only');
+        } catch (normalizationErrorArg) {
+          throw new AggregateError(
+            [verificationErrorArg, normalizationErrorArg],
+            'The committed target package could not be normalized without restoring the bridge.',
+          );
+        }
+      }
+    } else {
+      await addExactPackage(context, targetSpec, registryUrl);
+      targetTopology = await verifyPackageTransitionTopology(context, 'target-only');
+      await optionsArg.coordinator.mutateTransaction(optionsArg.token, (current) => {
+        if (current.version !== upgradePackageTransitionTransactionVersion) {
+          throw new Error('The package-transition transaction changed format.');
+        }
+        return {
+          ...current,
+          targetPackageCommitted: true as const,
+          message: `Committed exact target ${targetSpec} during bounded recovery.`,
+        };
+      });
+    }
+    const targetInstallation = targetTopology.target;
+    if (!targetInstallation) throw new Error('The exact target package is unavailable.');
+    let current = requirePackageTransitionTransaction(
+      await optionsArg.coordinator.readTransaction(optionsArg.token),
+    );
+    if (current.controllerWasRunning) {
+      if (current.targetStartupInvoked !== true) {
+        const candidates = (await listControllerProcessesForCli(targetInstallation.cliPath))
+          .filter((candidateArg) => candidateArg.port === current.port);
+        if (candidates.length > 0 || await isLoopbackPortListening(current.port)) {
+          throw new Error(
+            'A target controller exists before its durable startup marker; refusing to adopt it.',
+          );
+        }
+        const preparedTargetStart = await prepareControllerStart(
+          targetInstallation,
+          current.port,
+          optionsArg.token,
+        );
+        current = requirePackageTransitionTransaction(await optionsArg.coordinator.mutateTransaction(optionsArg.token, (candidate) => {
+          if (candidate.version !== upgradePackageTransitionTransactionVersion) {
+            throw new Error('The package-transition transaction changed format.');
+          }
+          return {
+            ...candidate,
+            phase: 'restarting',
+            targetStartupInvoked: true as const,
+            message: `Invoking ${candidate.targetPackageName} during bounded recovery.`,
+          };
+        }));
+        await runPreparedManagedCommand(preparedTargetStart);
+      }
+      let status = await queryControllerStatus(current.port, {
+        packageName: current.targetPackageName,
+        packageVersion: current.targetVersion,
+        upgradeManagementVersion: current.targetManagementVersion,
+      }).catch(() => undefined);
+      if (!status) {
+        if (await retainedUpgradeTargetIsAuthoritative({
+          coordinator: optionsArg.coordinator,
+          token: optionsArg.token,
+        })) return false;
+        const targetCandidates = (await listControllerProcessesForCli(targetInstallation.cliPath))
+          .filter((candidateArg) => candidateArg.port === current.port);
+        if (targetCandidates.length > 0 || await isLoopbackPortListening(current.port)) {
+          throw new Error(
+            'A target controller is already starting or listening but cannot be adopted safely; refusing to launch a replacement.',
+          );
+        }
+        await startController(targetInstallation, current.port, optionsArg.token);
+        status = await queryUpgradeManagedController(
+          current.port,
+          targetControllerIdentity(current),
+        );
+      }
+      await finalizeControllerUpgrade(
+        optionsArg.coordinator,
+        optionsArg.token,
+        status,
+        current.continueSessions ? 'continue' : 'reopen',
+      );
+    }
+    await optionsArg.coordinator.finishTransaction(
+      optionsArg.token,
+      true,
+      `Upgrade to ${current.targetPackageName}@${current.targetVersion} completed during bounded recovery.`,
+    );
+    return true;
+  }
+
+  const sourceSpec = `${transaction.sourcePackageName}@${transaction.sourceVersion}`;
+  let sourceTopology: IPackageTransitionTopology;
+  if (transaction.packageTransitionStarted === true) {
+    await addExactPackage(context, sourceSpec, registryUrl);
+    sourceTopology = await verifyPackageTransitionTopology(context, 'source-only');
+  } else {
+    sourceTopology = await verifyPackageTransitionTopology(context, 'source-only');
+  }
+  const sourceInstallation = sourceTopology.source;
+  if (!sourceInstallation) throw new Error('The exact bridge package is unavailable.');
+  if (transaction.controllerWasRunning) {
+    let status = await queryControllerStatus(transaction.port, {
+      packageName: transaction.sourcePackageName,
+      packageVersion: transaction.sourceVersion,
+      upgradeManagementVersion: transaction.sourceManagementVersion,
+    }).catch(() => undefined);
+    if (!status) {
+      await startController(sourceInstallation, transaction.port, optionsArg.token);
+      status = await queryUpgradeManagedController(
+        transaction.port,
+        sourceControllerIdentity(transaction),
+      );
+    }
+    await finalizeControllerUpgrade(
+      optionsArg.coordinator,
+      optionsArg.token,
+      status,
+      'compensate',
+    );
+  }
+  await optionsArg.coordinator.finishTransaction(
+    optionsArg.token,
+    false,
+    'The stalled package transition restored the exact bridge package.',
+    `The upgrade stopped making progress during phase ${transaction.phase}.`,
+  );
+  return true;
+};
+
+const recoverStalledUpgradeUnderLock = async (optionsArg: {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  transaction: TUpgradeTransaction;
+  installation: IPnpmGlobalInstallation;
+}): Promise<boolean> => {
+  const transaction = optionsArg.transaction;
+  if (transaction.terminal) return true;
+  if (transaction.targetStartupInvoked === true && await retainedUpgradeTargetIsAuthoritative({
+    coordinator: optionsArg.coordinator,
+    token: optionsArg.token,
+  }, {
+    resolveInstallation: async () => optionsArg.installation,
+  })) return false;
+  if (transaction.version === upgradePackageTransitionTransactionVersion) {
+    return await recoverPackageTransition({
+      coordinator: optionsArg.coordinator,
+      token: optionsArg.token,
+      transaction,
+      installation: optionsArg.installation,
+    });
+  }
+  const afterTargetStartupBoundary = transaction.targetStartupInvoked === true;
+  if (afterTargetStartupBoundary) {
+    if (!transaction.targetVersion) {
+      throw new Error('The stalled upgrade has no retained target version.');
+    }
+    const targetInstallation = await resolvePnpmGlobalInstallation();
+    if (targetInstallation.packageVersion !== transaction.targetVersion) {
+      throw new Error(
+        'The package installation does not match the retained post-startup upgrade target.',
+      );
+    }
+    if (transaction.controllerWasRunning) {
+      let status = await queryControllerStatus(transaction.port, {
+        packageName: controllerPackageName,
+        packageVersion: targetInstallation.packageVersion,
+        upgradeManagementVersion: controllerUpgradeManagementVersion,
+      }).catch(() => undefined);
+      if (!status) {
+        if (await retainedUpgradeTargetIsAuthoritative({
+          coordinator: optionsArg.coordinator,
+          token: optionsArg.token,
+        })) return false;
+        const targetCandidates = (await listControllerProcessesForCli(targetInstallation.cliPath))
+          .filter((candidateArg) => candidateArg.port === transaction.port);
+        if (targetCandidates.length > 0 || await isLoopbackPortListening(transaction.port)) {
+          throw new Error(
+            'A target controller is already starting or listening but cannot be adopted safely; refusing to launch a replacement.',
+          );
+        }
+        await startController(targetInstallation, transaction.port, optionsArg.token);
+        status = await queryUpgradeManagedController(
+          transaction.port,
+          {
+            packageName: controllerPackageName,
+            packageVersion: targetInstallation.packageVersion,
+            managementVersion: controllerUpgradeManagementVersion,
+          },
+        );
+      }
+      await finalizeControllerUpgrade(
+        optionsArg.coordinator,
+        optionsArg.token,
+        status,
+        transaction.continueSessions ? 'continue' : 'reopen',
+      );
+    }
+    await optionsArg.coordinator.finishTransaction(
+      optionsArg.token,
+      true,
+      `Upgrade to ${transaction.targetVersion} completed during bounded recovery.`,
+    );
+    return true;
+  }
+
+  const sourceInstallation = await restorePreviousInstallation({
+    ...optionsArg.installation,
+    packageVersion: transaction.sourceVersion,
+  });
+  if (transaction.controllerWasRunning) {
+    let status = await queryControllerStatus(transaction.port, {
+      packageName: controllerPackageName,
+      packageVersion: sourceInstallation.packageVersion,
+      upgradeManagementVersion: controllerUpgradeManagementVersion,
+    }).catch(() => undefined);
+    if (!status) {
+      await startController(sourceInstallation, transaction.port, optionsArg.token);
+      status = await queryUpgradeManagedController(
+        transaction.port,
+        {
+          packageName: controllerPackageName,
+          packageVersion: sourceInstallation.packageVersion,
+          managementVersion: controllerUpgradeManagementVersion,
+        },
+      );
+    }
+    await finalizeControllerUpgrade(
+      optionsArg.coordinator,
+      optionsArg.token,
+      status,
+      'compensate',
+    );
+  }
+  await optionsArg.coordinator.finishTransaction(
+    optionsArg.token,
+    false,
+    'The stalled upgrade restored the source package.',
+    `The upgrade stopped making progress during phase ${transaction.phase}.`,
+  );
+  return true;
+};
+
+interface IRecoverStalledUpgradeOptions {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  transaction: TUpgradeTransaction;
+  installation: IPnpmGlobalInstallation;
+  command: '__serve' | 'foreground' | 'upgrade';
+}
+
+interface IRecoverStalledUpgradeDependencies {
+  launchRecoveryWorker?: typeof launchDetachedRecoveryWorker;
+  terminateWorkerCandidate?: (
+    candidateArg: IDetachedUpgradeWorker,
+  ) => Promise<void>;
+  candidateCleanup?: ICandidateCleanupRetryDependencies;
+}
+
+export function recoverStalledUpgrade(
+  optionsArg: IRecoverStalledUpgradeOptions,
+): Promise<boolean>;
+export async function recoverStalledUpgrade(
+  optionsArg: IRecoverStalledUpgradeOptions,
+  dependenciesArg: IRecoverStalledUpgradeDependencies = {},
+): Promise<boolean> {
+  await optionsArg.coordinator.terminateTransactionWorker(optionsArg.transaction);
+  let lock: Awaited<ReturnType<UpgradeCoordinator['acquireUpgradeLock']>>;
+  try {
+    lock = await optionsArg.coordinator.acquireUpgradeLock({
+      token: optionsArg.token,
+      cliPath: optionsArg.installation.cliPath,
+      command: optionsArg.command,
+    });
+  } catch (errorArg) {
+    if (
+      errorArg instanceof Error
+      && (errorArg.message.includes('already running')
+        || errorArg.message.includes('initializing'))
+    ) return false;
+    throw errorArg;
+  }
+
+  let candidate: IDetachedUpgradeWorker | undefined;
+  let lockTransferred = false;
+  try {
+    const transaction = await optionsArg.coordinator.readTransaction(optionsArg.token);
+    if (transaction.terminal) {
+      await lock.release();
+      return true;
+    }
+    const recoveryInstallation = await resolveAuthoritativeRecoveryInstallation(
+      transaction,
+      optionsArg.installation,
+    );
+    const payload: IUpgradeWorkerPayload = {
+      version: upgradeCoordinationVersion,
+      token: optionsArg.token,
+      port: transaction.port,
+      gracePeriodMs: transaction.gracePeriodMs,
+      continueSessions: transaction.continueSessions,
+    };
+    candidate = await (dependenciesArg.launchRecoveryWorker ?? launchDetachedRecoveryWorker)({
+      installation: recoveryInstallation,
+      payload,
+    });
+    const launchedTransaction = await optionsArg.coordinator.recordWorkerLaunch(
+      optionsArg.token,
+      candidate.pid,
+      candidate.cliPath,
+      candidate.logFilePath,
+    );
+    const worker = launchedTransaction.worker;
+    if (
+      !worker
+      || worker.pid !== candidate.pid
+      || worker.processGroupId !== candidate.processGroupId
+      || worker.fingerprint !== candidate.fingerprint
+      || worker.cliPath !== candidate.cliPath
+      || worker.logFilePath !== candidate.logFilePath
+    ) throw new Error('The recovery worker launch identity was not retained exactly.');
+    await optionsArg.coordinator.transferUpgradeLockToWorker({
+      lock,
+      token: optionsArg.token,
+      worker,
+    });
+    lockTransferred = true;
+    await optionsArg.coordinator.acknowledgeWorker(optionsArg.token);
+    return true;
+  } catch (errorArg) {
+    const errors: unknown[] = [errorArg];
+    if (candidate) {
+      await retryCandidateCleanupUntilDrained(
+        async () => await (dependenciesArg.terminateWorkerCandidate
+          ?? ((candidateArg) => optionsArg.coordinator.terminateUpgradeWorkerCandidate(candidateArg)))(
+          candidate!,
+        ),
+        dependenciesArg.candidateCleanup,
+        candidate.pid,
+      );
+    }
+    try {
+      if (!lockTransferred) {
+        try {
+          await lock.release();
+        } catch {
+          const replacementLock = await optionsArg.coordinator.acquireUpgradeLock({
+            token: optionsArg.token,
+            cliPath: optionsArg.installation.cliPath,
+            command: optionsArg.command,
+          });
+          await replacementLock.release();
+        }
+      } else {
+        const replacementLock = await optionsArg.coordinator.acquireUpgradeLock({
+          token: optionsArg.token,
+          cliPath: optionsArg.installation.cliPath,
+          command: optionsArg.command,
+        });
+        await replacementLock.release();
+      }
+    } catch (lockCleanupErrorArg) {
+      errors.push(lockCleanupErrorArg);
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(
+        errors,
+        'Stalled upgrade recovery handoff failed and cleanup was incomplete.',
+      );
+    }
+    throw errorArg;
+  }
+}
+
+export const createUpgradeWorkerPayload = (optionsArg: {
+  port: number;
+  gracePeriodMs: number;
+  continueSessions: boolean;
+  expectedController?: IUpgradeExpectedController;
+}): IUpgradeWorkerPayload => ({
+  version: upgradeCoordinationVersion,
+  token: createUpgradeToken(),
+  port: optionsArg.port,
+  gracePeriodMs: optionsArg.gracePeriodMs,
+  continueSessions: optionsArg.continueSessions,
+  ...(optionsArg.expectedController
+    ? { expectedController: optionsArg.expectedController }
+    : {}),
+});