agl 22.0.1 → 22.0.2

package/ts/classes.upgradetransaction.ts

@@ -17,36 +17,43 @@ import {
 import {
   inspectControllerProcess,
   listControllerDataWriterProcessesForCli,
+  listControllerDataWriterProcessesForCliPaths,
   listControllerProcessesForCli,
   processIdentityHasCliCommand,
   readControllerProcessIdentity,
   readProcessGroupMemberPids,
+  type IControllerProcessIdentity,
 } from './classes.processinspection.js';
 import {
   createUpgradeToken,
+  compareUpgradeSemver,
   type TUpgradeTransaction,
+  type IUpgradeTransactionInventoryEntry,
   type IUpgradeTransactionV3,
   type IUpgradeExpectedController,
   type IUpgradeWorkerPayload,
+  normalizeUpgradeRegistryUrl,
   UpgradeCoordinator,
+  type UpgradeInstallationLock,
   upgradeCoordinationVersion,
   upgradePackageTransitionTransactionVersion,
   upgradePackageTransitionSource,
   upgradePackageTransitionTarget,
+  upgradeTransactionIsStalled,
+  upgradeTransactionTargetVersion,
   serializeUpgradeWorkerPayload,
+  terminateVerifiedUpgradeWorkerProcessGroup,
 } from './classes.upgradecoordinator.js';
 import {
   upgradeCoordinationRootEnvironmentVariable,
   upgradeTokenEnvironmentVariable,
 } from './constants.upgradeenvironment.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;
@@ -59,7 +66,6 @@ const scrubUpgradeCoordinationEnvironment = (): void => {
   delete process.env[upgradeCoordinationRootEnvironmentVariable];
 };
 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
@@ -67,6 +73,10 @@ const currentPackageIdentity = String(controllerPackageName)
   : upgradePackageTransitionTarget;
 const currentCliName = currentPackageIdentity.cliName;
 
+const registryArguments = (registryUrlArg?: string): string[] => registryUrlArg
+  ? [`--registry=${registryUrlArg}`]
+  : [];
+
 const packageManagerEnvironmentAllowlist = new Set([
   'CI',
   'COREPACK_HOME',
@@ -81,6 +91,7 @@ const packageManagerEnvironmentAllowlist = new Set([
   'NPM_CONFIG_REGISTRY',
   'NPM_CONFIG_USERCONFIG',
   'PATH',
+  'PNPM_CONFIG_REGISTRY',
   'PNPM_HOME',
   'SHELL',
   'SSL_CERT_DIR',
@@ -98,13 +109,6 @@ const packageManagerEnvironmentAllowlist = new Set([
   'XDG_STATE_HOME',
 ]);
 
-interface IParsedSemver {
-  major: string;
-  minor: string;
-  patch: string;
-  prerelease: string[];
-}
-
 class UpgradeCommandCleanupError extends Error {}
 
 interface IGlobalListDependency {
@@ -134,6 +138,74 @@ export interface IDetachedUpgradeWorker {
   logFilePath: string;
 }
 
+export interface IUpgradeWorkerLaunchCandidate {
+  pid: number;
+  cliPath: string;
+  logFilePath: string;
+  processGroupId?: number;
+  fingerprint?: string;
+}
+
+export class UpgradeWorkerHandoffError extends Error {
+  constructor(
+    messageArg: string,
+    causeArg: unknown,
+    public readonly recoveryLock: UpgradeInstallationLock,
+  ) {
+    super(messageArg, { cause: causeArg });
+    this.name = 'UpgradeWorkerHandoffError';
+  }
+}
+
+export class UpgradeWorkerCandidateDrainageError extends Error {
+  constructor(messageArg: string, causeArg: unknown) {
+    super(messageArg, { cause: causeArg });
+    this.name = 'UpgradeWorkerCandidateDrainageError';
+  }
+}
+
+export interface ITerminalizeUpgradeWorkerHandoffFailureOptions {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  error: UpgradeWorkerHandoffError;
+}
+
+export const terminalizeUpgradeWorkerHandoffFailure = async (
+  optionsArg: ITerminalizeUpgradeWorkerHandoffFailureOptions,
+): Promise<never> => {
+  const handoffFailure = optionsArg.error.cause ?? optionsArg.error;
+  let terminalizationError: unknown;
+  let terminalized = false;
+  try {
+    await optionsArg.error.recoveryLock.assertOwned();
+    await optionsArg.coordinator.finishTransaction(
+      optionsArg.token,
+      false,
+      'The upgrade worker handoff failed before package work began.',
+      handoffFailure instanceof Error ? handoffFailure.message : String(handoffFailure),
+    );
+    terminalized = true;
+  } catch (errorArg) {
+    terminalizationError = errorArg;
+  }
+  let releaseError: unknown;
+  if (terminalized) {
+    try {
+      await optionsArg.error.recoveryLock.release();
+    } catch (errorArg) {
+      releaseError = errorArg;
+    }
+  }
+  const failures = [optionsArg.error, terminalizationError, releaseError]
+    .filter((failureArg) => failureArg !== undefined);
+  throw failures.length > 1
+    ? new AggregateError(
+        failures,
+        'The upgrade worker handoff failed and its transaction cleanup was incomplete.',
+      )
+    : optionsArg.error;
+};
+
 const proxyEnvironmentValueIsSafe = (valueArg: string): boolean => {
   try {
     const parsed = new URL(valueArg);
@@ -158,6 +230,13 @@ export const createPackageManagerEnvironment = (
       (normalizedName === 'HTTP_PROXY' || normalizedName === 'HTTPS_PROXY')
       && !proxyEnvironmentValueIsSafe(value)
     ) continue;
+    if (normalizedName === 'NPM_CONFIG_REGISTRY' || normalizedName === 'PNPM_CONFIG_REGISTRY') {
+      try {
+        normalizeUpgradeRegistryUrl(value);
+      } catch {
+        continue;
+      }
+    }
     environment[name] = value;
   }
   return environment;
@@ -787,7 +866,12 @@ const resolveAuthoritativeRecoveryInstallation = async (
           : upgradePackageTransitionSource;
         return {
           packageName: identity.packageName,
-          versions: [identity.version],
+          versions: transactionArg.targetPackageCommitStarted === true
+            ? [...new Set([
+                identity.version,
+                transactionArg.recoveryTargetVersion ?? capturedInstallationArg.packageVersion,
+              ])]
+            : [identity.version],
           managementVersion: identity.managementVersion,
           cliName: identity.cliName,
           cliRelativePath: identity.cliRelativePath,
@@ -865,6 +949,7 @@ const resolveAuthoritativeRecoveryInstallation = async (
 const verifyPackageTransitionTopology = async (
   contextArg: IPackageTransitionContext,
   expectedArg: TPackageTransitionTopology,
+  targetVersionArg: string = upgradePackageTransitionTarget.version,
 ): Promise<IPackageTransitionTopology> => {
   const output = await runCapturedCommand(
     contextArg.packageManagerPath,
@@ -894,7 +979,10 @@ const verifyPackageTransitionTopology = async (
       ? readExactGlobalPackage(contextArg, sourceDependency, upgradePackageTransitionSource)
       : undefined,
     targetDependency
-      ? readExactGlobalPackage(contextArg, targetDependency, upgradePackageTransitionTarget)
+      ? readExactGlobalPackage(contextArg, targetDependency, {
+          ...upgradePackageTransitionTarget,
+          version: targetVersionArg,
+        })
       : undefined,
   ]);
   if (expectedArg === 'grouped' && source?.groupDirectory !== target?.groupDirectory) {
@@ -944,6 +1032,7 @@ export const resolveInheritedUpgradeTargetInstallation = async (
   const topology = await verifyPackageTransitionTopology(
     await resolvePackageManagerContext(),
     'target-only',
+    upgradeTransactionTargetVersion(transactionArg)!,
   );
   if (!topology.target) throw new Error('The committed target package is unavailable.');
   return topology.target;
@@ -983,66 +1072,143 @@ export const tryResolveCurrentPnpmGlobalInstallation = async (
   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}`);
+export const compareSemver = compareUpgradeSemver;
+
+export interface IInspectOrphanedUpgradeForAdoptionOptions {
+  coordinator: UpgradeCoordinator;
+  installation: IPnpmGlobalInstallation;
+  port: number;
+  registryUrl?: string;
+}
+
+export const inspectOrphanedUpgradeForAdoption = async (
+  optionsArg: IInspectOrphanedUpgradeForAdoptionOptions,
+): Promise<IUpgradeTransactionInventoryEntry | undefined> => {
+  const inventory = await optionsArg.coordinator.inspectCanonicalTransactionInventory();
+  const nonterminal = inventory.transactions.filter((entryArg) => !entryArg.transaction.terminal);
+  if (nonterminal.length === 0) return undefined;
+  if (nonterminal.length !== 1) {
+    throw new Error('Multiple nonterminal upgrade transactions block a fresh upgrade.');
+  }
+  const entry = nonterminal[0];
+  const transaction = entry.transaction;
+  const eligibleV2 = transaction.version === upgradeCoordinationVersion
+    && transaction.controllerWasRunning === true
+    && transaction.targetStartupInvoked === true
+    && transaction.targetVersion !== undefined
+    && transaction.preparationCompletedAt !== undefined
+    && (transaction.phase === 'restarting' || transaction.phase === 'continuing')
+    && compareSemver(transaction.sourceVersion, upgradePackageTransitionTarget.version) >= 0
+    && compareSemver(transaction.sourceVersion, transaction.targetVersion) < 0
+    && compareSemver(transaction.targetVersion, optionsArg.installation.packageVersion) <= 0;
+  const eligibleV3 = transaction.version === upgradePackageTransitionTransactionVersion
+    && currentPackageIdentity.packageName === upgradePackageTransitionTarget.packageName
+    && transaction.targetPackageCommitStarted === true
+    && (!transaction.controllerWasRunning || transaction.preparationCompletedAt !== undefined)
+    && (
+      transaction.phase === 'installing'
+      || transaction.phase === 'restarting'
+      || transaction.phase === 'continuing'
+    )
+    && compareSemver(
+      upgradeTransactionTargetVersion(transaction)!,
+      optionsArg.installation.packageVersion,
+    ) <= 0;
+  if (
+    transaction.port !== optionsArg.port
+    || (!eligibleV2 && !eligibleV3)
+    || !upgradeTransactionIsStalled(transaction)
+  ) throw new Error('A nonterminal upgrade transaction blocks a fresh upgrade.');
+  if (transaction.version === upgradePackageTransitionTransactionVersion && optionsArg.registryUrl) {
+    throw new Error(
+      'Legacy package-transition recovery uses pnpm registry configuration and cannot retain --registry.',
+    );
   }
-  return {
-    major: match[1],
-    minor: match[2],
-    patch: match[3],
-    prerelease,
-  };
+  if (
+    transaction.version === upgradeCoordinationVersion
+    && transaction.registryUrl !== undefined
+    && optionsArg.registryUrl !== undefined
+    && transaction.registryUrl !== optionsArg.registryUrl
+  ) throw new Error('The orphaned upgrade registry conflicts with the requested registry.');
+  if (await optionsArg.coordinator.transactionWorkerIsLive(transaction)) {
+    throw new Error('A nonterminal upgrade worker is still running.');
+  }
+  if (
+    transaction.controller
+    && await optionsArg.coordinator.transactionControllerIsLive(transaction)
+  ) throw new Error('A nonterminal upgrade controller is still running.');
+  const adoptionMatch = /^transaction-([a-f0-9]{20})\.json\.adopting-([a-f0-9]{20})$/
+    .exec(entry.fileName);
+  const prefixes = new Set([
+    transaction.tokenHash.slice(0, 20),
+    ...(adoptionMatch ? [adoptionMatch[1], adoptionMatch[2]] : []),
+  ]);
+  if (inventory.tokenMetadataFileNames.some((fileNameArg) => (
+    [...prefixes].some((prefixArg) => fileNameArg.includes(`-${prefixArg}.json`))
+  ))) throw new Error('The orphaned upgrade retains token-bound coordination metadata.');
+  return entry;
 };
 
-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 interface IAdoptOrphanedUpgradeUnderLockOptions
+  extends IInspectOrphanedUpgradeForAdoptionOptions {
+  lock: UpgradeInstallationLock;
+  token: string;
+  expected: IUpgradeTransactionInventoryEntry;
+}
 
-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;
+export const adoptOrphanedUpgradeUnderLock = async (
+  optionsArg: IAdoptOrphanedUpgradeUnderLockOptions,
+): Promise<TUpgradeTransaction> => {
+  await optionsArg.lock.assertOwned();
+  const candidate = await inspectOrphanedUpgradeForAdoption(optionsArg);
+  if (
+    !candidate
+    || candidate.transaction.tokenHash !== optionsArg.expected.transaction.tokenHash
+    || candidate.transaction.revision !== optionsArg.expected.transaction.revision
+  ) throw new Error('The orphaned upgrade transaction changed before adoption.');
+  const cliPaths = [
+    optionsArg.installation.cliPath,
+    ...(candidate.transaction.worker ? [candidate.transaction.worker.cliPath] : []),
+    ...(candidate.transaction.controller ? [candidate.transaction.controller.cliPath] : []),
+  ];
+  const assertNoRuntimeWriters = async (): Promise<void> => {
+    if (await isLoopbackPortListening(optionsArg.port)) {
+      throw new Error('The orphaned upgrade port became occupied before recovery.');
+    }
+    const writers = await listControllerDataWriterProcessesForCliPaths(cliPaths, {
+      includeInstalledPackagePaths: true,
+    });
+    if (writers.length > 0) {
+      throw new Error(`A ${writers[0].kind} data writer prevents orphaned upgrade recovery.`);
+    }
+  };
+  await assertNoRuntimeWriters();
+  await optionsArg.lock.assertOwned();
+  const adopted = await optionsArg.coordinator.adoptOrphanedTransaction({
+    lock: optionsArg.lock,
+    token: optionsArg.token,
+    expectedTokenHash: candidate.transaction.tokenHash,
+    expectedRevision: candidate.transaction.revision,
+    port: optionsArg.port,
+    installedVersion: optionsArg.installation.packageVersion,
+    ...(optionsArg.registryUrl === undefined ? {} : { registryUrl: optionsArg.registryUrl }),
+  });
+  await assertNoRuntimeWriters();
+  await optionsArg.lock.assertOwned();
+  return adopted;
 };
 
-const readLatestVersion = async (installationArg: IPnpmGlobalInstallation): Promise<string> => {
+const readLatestVersion = async (
+  installationArg: IPnpmGlobalInstallation,
+  registryUrlArg?: string,
+): Promise<string> => {
   const output = await runCapturedCommand(
     installationArg.packageManagerPath,
     [
       'view',
       controllerPackageName,
       'dist-tags.latest',
-      `--registry=${npmRegistryUrl}`,
+      ...registryArguments(registryUrlArg),
       '--json',
     ],
     createPackageManagerEnvironment(),
@@ -1051,40 +1217,25 @@ const readLatestVersion = async (installationArg: IPnpmGlobalInstallation): Prom
   try {
     version = JSON.parse(output) as unknown;
   } catch {
-    throw new Error('pnpm view returned malformed JSON for the npm latest tag.');
+    throw new Error('pnpm view returned malformed JSON for the registry latest tag.');
   }
   if (typeof version !== 'string') {
-    throw new Error('The npm latest tag did not resolve to one package version.');
+    throw new Error('The registry latest tag did not resolve to one package version.');
   }
-  parseSemver(version);
+  compareUpgradeSemver(version, 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,
+  registryUrlArg?: string,
 ): Promise<void> => {
   const output = await runCapturedCommand(
     contextArg.packageManagerPath,
     [
       'view',
       `${upgradePackageTransitionTarget.packageName}@${upgradePackageTransitionTarget.version}`,
-      `--registry=${registryUrlArg}`,
+      ...registryArguments(registryUrlArg),
       '--json',
     ],
     createPackageManagerEnvironment(),
@@ -1226,63 +1377,42 @@ const parseUpgradeRecoveryWorkerContext = (
   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.');
-  }
-};
+const terminateSpawnedDetachedWorker = async (
+  identityArg: IControllerProcessIdentity,
+  cliPathArg: string,
+): Promise<void> => await terminateVerifiedUpgradeWorkerProcessGroup({
+  pid: identityArg.pid,
+  processGroupId: identityArg.processGroupId,
+  fingerprint: identityArg.fingerprint,
+  cliPath: cliPathArg,
+});
 
-interface ICandidateCleanupRetryDependencies {
+export interface ICandidateCleanupDependencies {
   beforeAttempt?: (processIdArg?: number) => Promise<void>;
-  delay?: (millisecondsArg: number) => Promise<void>;
 }
 
-const retryCandidateCleanupUntilDrained = async (
+const cleanupCandidateUntilDrained = async (
   cleanupArg: () => Promise<void>,
-  dependenciesArg: ICandidateCleanupRetryDependencies = {},
+  dependenciesArg: ICandidateCleanupDependencies = {},
   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);
-    }
-  }
+  await dependenciesArg.beforeAttempt?.(processIdArg);
+  await cleanupArg();
 };
 
+export const terminateUpgradeWorkerCandidateUntilDrained = async (
+  coordinatorArg: UpgradeCoordinator,
+  candidateArg: IDetachedUpgradeWorker,
+): Promise<void> => await cleanupCandidateUntilDrained(
+  async () => await coordinatorArg.terminateUpgradeWorkerCandidate(candidateArg),
+  {},
+  candidateArg.pid,
+);
+
 interface IDetachedUpgradeWorkerProcessDependencies {
   readProcessIdentity?: typeof readControllerProcessIdentity;
   processHasCliCommand?: typeof processIdentityHasCliCommand;
-  candidateCleanup?: ICandidateCleanupRetryDependencies;
+  candidateCleanup?: ICandidateCleanupDependencies;
 }
 
 const launchDetachedUpgradeWorkerProcess = async (optionsArg: {
@@ -1296,6 +1426,7 @@ const launchDetachedUpgradeWorkerProcess = async (optionsArg: {
   }
   const log = await openUpgradeLog(optionsArg.payload.token);
   let child: plugins.childProcess.ChildProcess | undefined;
+  let spawnedIdentity: IControllerProcessIdentity | undefined;
   let logClosed = false;
   try {
     const workerEnvironment = { ...(optionsArg.environment ?? process.env) };
@@ -1333,13 +1464,15 @@ const launchDetachedUpgradeWorkerProcess = async (optionsArg: {
       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.`);
     }
+    spawnedIdentity = await readControllerProcessIdentity(launchedChild.pid) ?? undefined;
+    await log.handle.close();
+    logClosed = true;
     const identity = await (dependenciesArg.readProcessIdentity
-      ?? readControllerProcessIdentity)(launchedChild.pid);
+      ? dependenciesArg.readProcessIdentity(launchedChild.pid)
+      : spawnedIdentity);
     if (
       !identity
       || !identity.processGroupLeader
@@ -1360,6 +1493,7 @@ const launchDetachedUpgradeWorkerProcess = async (optionsArg: {
     };
   } catch (errorArg) {
     const errors: unknown[] = [errorArg];
+    let candidateCleanupError: unknown;
     if (!logClosed) {
       try {
         await log.handle.close();
@@ -1369,16 +1503,33 @@ const launchDetachedUpgradeWorkerProcess = async (optionsArg: {
       }
     }
     if (child?.pid) {
-      await retryCandidateCleanupUntilDrained(
-        async () => terminateSpawnedDetachedWorker(child!.pid!),
-        dependenciesArg.candidateCleanup,
-        child.pid,
+      try {
+        if (!spawnedIdentity) {
+          throw new Error('The detached upgrade worker cleanup identity was not established.');
+        }
+        await cleanupCandidateUntilDrained(
+          async () => terminateSpawnedDetachedWorker(
+            spawnedIdentity!,
+            optionsArg.installation.cliPath,
+          ),
+          dependenciesArg.candidateCleanup,
+          child.pid,
+        );
+      } catch (cleanupErrorArg) {
+        candidateCleanupError = cleanupErrorArg;
+        errors.push(cleanupErrorArg);
+      }
+    }
+    if (candidateCleanupError !== undefined) {
+      throw new UpgradeWorkerCandidateDrainageError(
+        'The detached upgrade worker launch failed and candidate drainage is unproven.',
+        new AggregateError(errors, 'Detached upgrade worker launch cleanup was incomplete.'),
       );
     }
     if (errors.length > 1) {
       throw new AggregateError(
         errors,
-        'The detached upgrade worker launch and log cleanup both failed.',
+        'The detached upgrade worker launch failed and cleanup was incomplete.',
       );
     }
     throw errorArg;
@@ -1433,6 +1584,7 @@ const runLoggedCommand = async (optionsArg: {
 const installVersion = async (
   installationArg: IPnpmGlobalInstallation,
   versionArg: string,
+  registryUrlArg?: string,
 ): Promise<void> => {
   await runLoggedCommand({
     executable: installationArg.packageManagerPath,
@@ -1444,7 +1596,7 @@ const installVersion = async (
       '--reporter=append-only',
       '--allow-build=node-pty',
       '--allow-build=fs-ext-extra-prebuilt',
-      `--registry=${npmRegistryUrl}`,
+      ...registryArguments(registryUrlArg),
       `${controllerPackageName}@${versionArg}`,
     ],
     environment: createPackageManagerEnvironment(),
@@ -1452,7 +1604,7 @@ const installVersion = async (
   });
 };
 
-const packageAddArguments = (packageSpecArg: string, registryUrlArg: string): string[] => [
+const packageAddArguments = (packageSpecArg: string, registryUrlArg?: string): string[] => [
   'add',
   '--global',
   '--save-exact',
@@ -1460,14 +1612,14 @@ const packageAddArguments = (packageSpecArg: string, registryUrlArg: string): st
   '--reporter=append-only',
   '--allow-build=node-pty',
   '--allow-build=fs-ext-extra-prebuilt',
-  `--registry=${registryUrlArg}`,
+  ...registryArguments(registryUrlArg),
   packageSpecArg,
 ];
 
 const preparePackageAdd = async (
   contextArg: IPackageTransitionContext,
   packageSpecArg: string,
-  registryUrlArg: string,
+  registryUrlArg?: string,
 ): Promise<IPreparedManagedCommand> => await prepareManagedCommand({
   executable: contextArg.packageManagerPath,
   arguments: packageAddArguments(packageSpecArg, registryUrlArg),
@@ -1480,7 +1632,7 @@ const preparePackageAdd = async (
 const addExactPackage = async (
   contextArg: IPackageTransitionContext,
   packageSpecArg: string,
-  registryUrlArg: string,
+  registryUrlArg?: string,
 ): Promise<void> => {
   await runPreparedManagedCommand(
     await preparePackageAdd(contextArg, packageSpecArg, registryUrlArg),
@@ -1505,12 +1657,14 @@ const prepareControllerStart = async (
   installationArg: IPnpmGlobalInstallation,
   portArg: number,
   tokenArg: string,
+  coordinatorArg: UpgradeCoordinator,
 ): Promise<IPreparedManagedCommand> => await prepareManagedCommand({
     executable: process.execPath,
     arguments: [installationArg.cliPath, 'start', '--port', String(portArg)],
     environment: {
       ...process.env,
       [upgradeTokenEnvironmentVariable]: tokenArg,
+      [upgradeCoordinationRootEnvironmentVariable]: coordinatorArg.baseDirectory,
     },
     timeoutMs: controllerRestartTimeoutMs,
     captureOutput: false,
@@ -1521,8 +1675,9 @@ const startController = async (
   installationArg: IPnpmGlobalInstallation,
   portArg: number,
   tokenArg: string,
+  coordinatorArg: UpgradeCoordinator,
 ): Promise<void> => await runPreparedManagedCommand(
-  await prepareControllerStart(installationArg, portArg, tokenArg),
+  await prepareControllerStart(installationArg, portArg, tokenArg, coordinatorArg),
 ).then(() => undefined);
 
 const retainedTargetTransactionMatches = (
@@ -1539,7 +1694,7 @@ const retainedTargetTransactionMatches = (
   && (transactionArg.version === upgradeCoordinationVersion
     || transactionArg.targetPackageCommitted === true)
   && (transactionArg.phase === 'restarting' || transactionArg.phase === 'continuing')
-  && transactionArg.targetVersion === installationArg.packageVersion
+  && upgradeTransactionTargetVersion(transactionArg) === installationArg.packageVersion
   && transactionArg.controller?.command === '__serve'
   && transactionArg.controller.cliPath === installationArg.cliPath
   && transactionArg.controller.pid === transactionArg.controller.processGroupId
@@ -1816,6 +1971,7 @@ export const prepareAndStopRunningController = async (
 
 const restorePreviousInstallation = async (
   installationArg: IPnpmGlobalInstallation,
+  registryUrlArg?: string,
 ): Promise<IPnpmGlobalInstallation> => {
   try {
     const current = await resolvePnpmGlobalInstallation();
@@ -1824,7 +1980,7 @@ const restorePreviousInstallation = async (
     if (errorContainsCommandCleanupFailure(errorArg)) throw errorArg;
     // Reinstalling the exact prior version is the authoritative rollback.
   }
-  await installVersion(installationArg, installationArg.packageVersion);
+  await installVersion(installationArg, installationArg.packageVersion, registryUrlArg);
   const restored = await resolvePnpmGlobalInstallation();
   if (restored.packageVersion !== installationArg.packageVersion) {
     throw new Error('The previous pnpm-global package version was not restored.');
@@ -1882,7 +2038,7 @@ const targetControllerIdentity = (transactionArg: TUpgradeTransaction): {
     }
   : {
       packageName: transactionArg.targetPackageName,
-      packageVersion: transactionArg.targetVersion,
+      packageVersion: upgradeTransactionTargetVersion(transactionArg)!,
       managementVersion: transactionArg.targetManagementVersion,
     };
 
@@ -1899,7 +2055,7 @@ export const assertInheritedUpgradeTransaction = (
   if (
     !transactionArg.controllerWasRunning
     || transactionArg.targetStartupInvoked !== true
-    || transactionArg.targetVersion !== currentIdentityArg.packageVersion
+    || upgradeTransactionTargetVersion(transactionArg) !== currentIdentityArg.packageVersion
   ) throw new Error('The inherited upgrade transaction did not authorize target startup.');
   if (transactionArg.version === upgradeCoordinationVersion) {
     if (
@@ -1922,7 +2078,7 @@ const runPackageTransitionUpgradeWorker = async (optionsArg: {
   payload: IUpgradeWorkerPayload;
   transaction: IUpgradeTransactionV3;
   currentInstallation: IPnpmGlobalInstallation;
-  registryUrl: string;
+  registryUrl?: string;
 }): Promise<void> => {
   const {
     coordinator,
@@ -2109,7 +2265,7 @@ const runPackageTransitionUpgradeWorker = async (optionsArg: {
       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);
+        await startController(sourceTopology.source, payload.port, payload.token, coordinator);
         const restoredStatus = await queryUpgradeManagedController(
           payload.port,
           sourceControllerIdentity(initialTransaction),
@@ -2147,6 +2303,7 @@ const runPackageTransitionUpgradeWorker = async (optionsArg: {
       targetInstallation,
       payload.port,
       payload.token,
+      coordinator,
     );
     await coordinator.mutateTransaction(payload.token, (current) => {
       if (current.version !== upgradePackageTransitionTransactionVersion) {
@@ -2318,11 +2475,13 @@ export async function runUpgradeWorker(
         payload: payloadArg,
         transaction,
         currentInstallation,
-        registryUrl: assertInternalRegistryUrl(internalOptionsArg.registryUrl ?? npmRegistryUrl),
+        registryUrl: internalOptionsArg.registryUrl === undefined
+          ? undefined
+          : normalizeUpgradeRegistryUrl(internalOptionsArg.registryUrl),
       });
       return;
     }
-    const latestVersion = await readLatestVersion(currentInstallation);
+    const latestVersion = await readLatestVersion(currentInstallation, transaction.registryUrl);
     await coordinator.mutateTransaction(payloadArg.token, (current) => {
       if (current.version !== upgradeCoordinationVersion) {
         throw new Error('The same-package upgrade transaction changed format.');
@@ -2331,25 +2490,25 @@ export async function runUpgradeWorker(
         ...current,
         targetVersion: latestVersion,
         phase: 'checking',
-        message: `Installed ${currentInstallation.packageVersion}; npm latest is ${latestVersion}.`,
+        message: `Installed ${currentInstallation.packageVersion}; registry latest is ${latestVersion}.`,
       };
     });
     const versionComparison = compareSemver(latestVersion, currentInstallation.packageVersion);
     process.stdout.write(
-      `${currentCliName} upgrade: installed ${currentInstallation.packageVersion}, npm latest ${latestVersion}.\n`,
+      `${currentCliName} upgrade: installed ${currentInstallation.packageVersion}, registry 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`,
+          : `${currentCliName} upgrade: installed version is newer than registry 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.',
+          : 'Installed version is newer than registry latest; no downgrade was performed.',
       );
       return;
     }
@@ -2412,18 +2571,21 @@ export async function runUpgradeWorker(
           `Package replacement is blocked by ${writer.kind} source writer PID ${writer.identity.pid}.`,
         );
       }
-      await installVersion(currentInstallation, latestVersion);
+      await installVersion(currentInstallation, latestVersion, transaction.registryUrl);
       upgradedInstallation = await resolvePnpmGlobalInstallation();
       if (upgradedInstallation.packageVersion !== latestVersion) {
-        throw new Error('pnpm completed without installing the requested npm latest version.');
+        throw new Error('pnpm completed without installing the requested registry version.');
       }
     } catch (upgradeErrorArg) {
       if (errorContainsCommandCleanupFailure(upgradeErrorArg)) throw upgradeErrorArg;
       const recoveryErrors: unknown[] = [upgradeErrorArg];
       try {
-        const restored = await restorePreviousInstallation(currentInstallation);
+        const restored = await restorePreviousInstallation(
+          currentInstallation,
+          transaction.registryUrl,
+        );
         if (runningStatus) {
-          await startController(restored, payloadArg.port, payloadArg.token);
+          await startController(restored, payloadArg.port, payloadArg.token, coordinator);
           const restoredStatus = await queryUpgradeManagedController(
             payloadArg.port,
             {
@@ -2465,7 +2627,7 @@ export async function runUpgradeWorker(
         targetStartupInvoked: true,
         message: `Invoking ${controllerPackageName} ${latestVersion}.`,
       }));
-      await startController(upgradedInstallation, payloadArg.port, payloadArg.token);
+      await startController(upgradedInstallation, payloadArg.port, payloadArg.token, coordinator);
       const upgradedStatus = await queryUpgradeManagedController(payloadArg.port, {
         packageName: controllerPackageName,
         packageVersion: latestVersion,
@@ -2532,18 +2694,27 @@ const recoverPackageTransition = async (optionsArg: {
     globalRoot: optionsArg.installation.globalRoot,
     globalBinDirectory: optionsArg.installation.globalBinDirectory,
   };
-  const registryUrl = assertInternalRegistryUrl(npmRegistryUrl);
+  const registryUrl = undefined;
   const transaction = optionsArg.transaction;
   if (transaction.targetPackageCommitStarted === true) {
-    const targetSpec = `${transaction.targetPackageName}@${transaction.targetVersion}`;
+    const targetVersion = upgradeTransactionTargetVersion(transaction)!;
+    const targetSpec = `${transaction.targetPackageName}@${targetVersion}`;
     let targetTopology: IPackageTransitionTopology;
     if (transaction.targetPackageCommitted === true) {
       try {
-        targetTopology = await verifyPackageTransitionTopology(context, 'target-only');
+        targetTopology = await verifyPackageTransitionTopology(
+          context,
+          'target-only',
+          targetVersion,
+        );
       } catch (verificationErrorArg) {
         try {
           await addExactPackage(context, targetSpec, registryUrl);
-          targetTopology = await verifyPackageTransitionTopology(context, 'target-only');
+          targetTopology = await verifyPackageTransitionTopology(
+            context,
+            'target-only',
+            targetVersion,
+          );
         } catch (normalizationErrorArg) {
           throw new AggregateError(
             [verificationErrorArg, normalizationErrorArg],
@@ -2553,7 +2724,11 @@ const recoverPackageTransition = async (optionsArg: {
       }
     } else {
       await addExactPackage(context, targetSpec, registryUrl);
-      targetTopology = await verifyPackageTransitionTopology(context, 'target-only');
+      targetTopology = await verifyPackageTransitionTopology(
+        context,
+        'target-only',
+        targetVersion,
+      );
       await optionsArg.coordinator.mutateTransaction(optionsArg.token, (current) => {
         if (current.version !== upgradePackageTransitionTransactionVersion) {
           throw new Error('The package-transition transaction changed format.');
@@ -2583,6 +2758,7 @@ const recoverPackageTransition = async (optionsArg: {
           targetInstallation,
           current.port,
           optionsArg.token,
+          optionsArg.coordinator,
         );
         current = requirePackageTransitionTransaction(await optionsArg.coordinator.mutateTransaction(optionsArg.token, (candidate) => {
           if (candidate.version !== upgradePackageTransitionTransactionVersion) {
@@ -2599,7 +2775,7 @@ const recoverPackageTransition = async (optionsArg: {
       }
       let status = await queryControllerStatus(current.port, {
         packageName: current.targetPackageName,
-        packageVersion: current.targetVersion,
+        packageVersion: upgradeTransactionTargetVersion(current)!,
         upgradeManagementVersion: current.targetManagementVersion,
       }).catch(() => undefined);
       if (!status) {
@@ -2614,7 +2790,12 @@ const recoverPackageTransition = async (optionsArg: {
             '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);
+        await startController(
+          targetInstallation,
+          current.port,
+          optionsArg.token,
+          optionsArg.coordinator,
+        );
         status = await queryUpgradeManagedController(
           current.port,
           targetControllerIdentity(current),
@@ -2630,7 +2811,7 @@ const recoverPackageTransition = async (optionsArg: {
     await optionsArg.coordinator.finishTransaction(
       optionsArg.token,
       true,
-      `Upgrade to ${current.targetPackageName}@${current.targetVersion} completed during bounded recovery.`,
+      `Upgrade to ${current.targetPackageName}@${upgradeTransactionTargetVersion(current)} completed during bounded recovery.`,
     );
     return true;
   }
@@ -2652,7 +2833,12 @@ const recoverPackageTransition = async (optionsArg: {
       upgradeManagementVersion: transaction.sourceManagementVersion,
     }).catch(() => undefined);
     if (!status) {
-      await startController(sourceInstallation, transaction.port, optionsArg.token);
+      await startController(
+        sourceInstallation,
+        transaction.port,
+        optionsArg.token,
+        optionsArg.coordinator,
+      );
       status = await queryUpgradeManagedController(
         transaction.port,
         sourceControllerIdentity(transaction),
@@ -2725,7 +2911,12 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
             '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);
+        await startController(
+          targetInstallation,
+          transaction.port,
+          optionsArg.token,
+          optionsArg.coordinator,
+        );
         status = await queryUpgradeManagedController(
           transaction.port,
           {
@@ -2753,7 +2944,7 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
   const sourceInstallation = await restorePreviousInstallation({
     ...optionsArg.installation,
     packageVersion: transaction.sourceVersion,
-  });
+  }, transaction.version === upgradeCoordinationVersion ? transaction.registryUrl : undefined);
   if (transaction.controllerWasRunning) {
     let status = await queryControllerStatus(transaction.port, {
       packageName: controllerPackageName,
@@ -2761,7 +2952,12 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
       upgradeManagementVersion: controllerUpgradeManagementVersion,
     }).catch(() => undefined);
     if (!status) {
-      await startController(sourceInstallation, transaction.port, optionsArg.token);
+      await startController(
+        sourceInstallation,
+        transaction.port,
+        optionsArg.token,
+        optionsArg.coordinator,
+      );
       status = await queryUpgradeManagedController(
         transaction.port,
         {
@@ -2795,45 +2991,188 @@ interface IRecoverStalledUpgradeOptions {
   command: '__serve' | 'foreground' | 'upgrade';
 }
 
-interface IRecoverStalledUpgradeDependencies {
-  launchRecoveryWorker?: typeof launchDetachedRecoveryWorker;
+export interface IUpgradeWorkerHandoffDependencies {
   terminateWorkerCandidate?: (
     candidateArg: IDetachedUpgradeWorker,
   ) => Promise<void>;
-  candidateCleanup?: ICandidateCleanupRetryDependencies;
+  candidateCleanup?: ICandidateCleanupDependencies;
 }
 
-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']>>;
+interface IRecoverStalledUpgradeDependencies extends IUpgradeWorkerHandoffDependencies {
+  launchRecoveryWorker?: typeof launchDetachedRecoveryWorker;
+}
+
+export interface IHandoffLaunchedUpgradeWorkerUnderLockOptions {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  installation: IPnpmGlobalInstallation;
+  command: '__serve' | 'foreground' | 'upgrade';
+  lock: UpgradeInstallationLock;
+  candidate: IUpgradeWorkerLaunchCandidate;
+  retainLockOnFailure?: boolean;
+}
+
+export const handoffLaunchedUpgradeWorkerUnderLock = async (
+  optionsArg: IHandoffLaunchedUpgradeWorkerUnderLockOptions,
+  dependenciesArg: IUpgradeWorkerHandoffDependencies = {},
+): Promise<IDetachedUpgradeWorker> => {
+  let worker: IDetachedUpgradeWorker | undefined;
   try {
-    lock = await optionsArg.coordinator.acquireUpgradeLock({
+    await optionsArg.coordinator.removeWorkerAcknowledgement(optionsArg.token);
+    const launchedTransaction = await optionsArg.coordinator.recordWorkerLaunch(
+      optionsArg.token,
+      optionsArg.candidate.pid,
+      optionsArg.candidate.cliPath,
+      optionsArg.candidate.logFilePath,
+    );
+    const retainedWorker = launchedTransaction.worker;
+    if (
+      !retainedWorker
+      || retainedWorker.pid !== optionsArg.candidate.pid
+      || retainedWorker.cliPath !== optionsArg.candidate.cliPath
+      || retainedWorker.logFilePath !== optionsArg.candidate.logFilePath
+      || (optionsArg.candidate.processGroupId !== undefined
+        && retainedWorker.processGroupId !== optionsArg.candidate.processGroupId)
+      || (optionsArg.candidate.fingerprint !== undefined
+        && retainedWorker.fingerprint !== optionsArg.candidate.fingerprint)
+    ) throw new Error('The upgrade worker launch identity was not retained exactly.');
+    worker = {
+      pid: retainedWorker.pid,
+      processGroupId: retainedWorker.processGroupId,
+      fingerprint: retainedWorker.fingerprint,
+      cliPath: retainedWorker.cliPath,
+      logFilePath: optionsArg.candidate.logFilePath,
+    };
+    await optionsArg.coordinator.transferUpgradeLockToWorker({
+      lock: optionsArg.lock,
       token: optionsArg.token,
-      cliPath: optionsArg.installation.cliPath,
-      command: optionsArg.command,
+      worker,
     });
+    await optionsArg.coordinator.acknowledgeWorker(optionsArg.token, worker);
+    return {
+      pid: worker.pid,
+      processGroupId: worker.processGroupId,
+      fingerprint: worker.fingerprint,
+      cliPath: worker.cliPath,
+      logFilePath: worker.logFilePath!,
+    };
   } catch (errorArg) {
-    if (
-      errorArg instanceof Error
-      && (errorArg.message.includes('already running')
-        || errorArg.message.includes('initializing'))
-    ) return false;
+    const errors: unknown[] = [errorArg];
+    if (!worker) {
+      const current = await optionsArg.coordinator.readTransaction(optionsArg.token).catch(() => undefined);
+      if (
+        current?.worker
+        && current.worker.pid === optionsArg.candidate.pid
+        && current.worker.cliPath === optionsArg.candidate.cliPath
+        && current.worker.logFilePath === optionsArg.candidate.logFilePath
+      ) worker = {
+        pid: current.worker.pid,
+        processGroupId: current.worker.processGroupId,
+        fingerprint: current.worker.fingerprint,
+        cliPath: current.worker.cliPath,
+        logFilePath: optionsArg.candidate.logFilePath,
+      };
+    }
+    if (!worker && (
+      optionsArg.candidate.processGroupId !== undefined
+      && optionsArg.candidate.fingerprint !== undefined
+    )) {
+      worker = {
+        pid: optionsArg.candidate.pid,
+        processGroupId: optionsArg.candidate.processGroupId,
+        fingerprint: optionsArg.candidate.fingerprint,
+        cliPath: optionsArg.candidate.cliPath,
+        logFilePath: optionsArg.candidate.logFilePath,
+      };
+    }
+    if (!worker) {
+      throw new UpgradeWorkerCandidateDrainageError(
+        'The upgrade worker handoff failed before its cleanup identity could be retained.',
+        errorArg,
+      );
+    }
+    const cleanupWorker = worker;
+    try {
+      await cleanupCandidateUntilDrained(
+        async () => await (dependenciesArg.terminateWorkerCandidate
+          ?? ((candidateArg) => optionsArg.coordinator.terminateUpgradeWorkerCandidate(candidateArg)))(
+          cleanupWorker,
+        ),
+        dependenciesArg.candidateCleanup,
+        cleanupWorker.pid,
+      );
+    } catch (cleanupErrorArg) {
+      errors.push(cleanupErrorArg);
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(
+        errors,
+        'Upgrade worker handoff failed and candidate drainage is unproven; ownership was retained.',
+      );
+    }
+    const acquireCallerLock = async (): Promise<UpgradeInstallationLock> => {
+      try {
+        await optionsArg.lock.assertOwned();
+        return optionsArg.lock;
+      } catch {
+        return await optionsArg.coordinator.acquireUpgradeLock({
+          token: optionsArg.token,
+          cliPath: optionsArg.installation.cliPath,
+          command: optionsArg.command,
+        });
+      }
+    };
+    if (optionsArg.retainLockOnFailure) {
+      try {
+        const recoveryLock = await acquireCallerLock();
+        await recoveryLock.assertOwned();
+        throw new UpgradeWorkerHandoffError(
+          'The upgrade worker handoff failed; exclusive ownership was retained for recovery.',
+          errors.length === 1
+            ? errorArg
+            : new AggregateError(errors, 'Upgrade worker handoff and candidate cleanup failed.'),
+          recoveryLock,
+        );
+      } catch (lockRetentionErrorArg) {
+        if (lockRetentionErrorArg instanceof UpgradeWorkerHandoffError) {
+          throw lockRetentionErrorArg;
+        }
+        errors.push(lockRetentionErrorArg);
+      }
+    }
+    try {
+      await (await acquireCallerLock()).release();
+    } catch (lockCleanupErrorArg) {
+      errors.push(lockCleanupErrorArg);
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(
+        errors,
+        'Upgrade worker handoff failed and cleanup was incomplete.',
+      );
+    }
     throw errorArg;
   }
+};
+
+export interface IHandoffStalledUpgradeRecoveryUnderLockOptions {
+  coordinator: UpgradeCoordinator;
+  token: string;
+  installation: IPnpmGlobalInstallation;
+  command: '__serve' | 'foreground' | 'upgrade';
+  lock: UpgradeInstallationLock;
+}
 
-  let candidate: IDetachedUpgradeWorker | undefined;
-  let lockTransferred = false;
+export const handoffStalledUpgradeRecoveryUnderLock = async (
+  optionsArg: IHandoffStalledUpgradeRecoveryUnderLockOptions,
+  dependenciesArg: IRecoverStalledUpgradeDependencies = {},
+): Promise<IDetachedUpgradeWorker | undefined> => {
+  let candidate: IDetachedUpgradeWorker;
   try {
     const transaction = await optionsArg.coordinator.readTransaction(optionsArg.token);
     if (transaction.terminal) {
-      await lock.release();
-      return true;
+      await optionsArg.lock.release();
+      return undefined;
     }
     const recoveryInstallation = await resolveAuthoritativeRecoveryInstallation(
       transaction,
@@ -2846,76 +3185,61 @@ export async function recoverStalledUpgrade(
       gracePeriodMs: transaction.gracePeriodMs,
       continueSessions: transaction.continueSessions,
     };
+    await optionsArg.coordinator.removeWorkerAcknowledgement(optionsArg.token);
     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,
-      );
-    }
+    if (errorArg instanceof UpgradeWorkerCandidateDrainageError) throw errorArg;
     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();
-      }
+      await optionsArg.lock.release();
     } catch (lockCleanupErrorArg) {
-      errors.push(lockCleanupErrorArg);
-    }
-    if (errors.length > 1) {
       throw new AggregateError(
-        errors,
-        'Stalled upgrade recovery handoff failed and cleanup was incomplete.',
+        [errorArg, lockCleanupErrorArg],
+        'Stalled upgrade recovery launch failed and its lock could not be released.',
       );
     }
     throw errorArg;
   }
+  return await handoffLaunchedUpgradeWorkerUnderLock({
+    ...optionsArg,
+    candidate,
+  }, dependenciesArg);
+};
+
+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;
+  }
+
+  await handoffStalledUpgradeRecoveryUnderLock({
+    coordinator: optionsArg.coordinator,
+    token: optionsArg.token,
+    installation: optionsArg.installation,
+    command: optionsArg.command,
+    lock,
+  }, dependenciesArg);
+  return true;
 }
 
 export const createUpgradeWorkerPayload = (optionsArg: {