agl 22.0.0 → 22.0.2

package/ts/classes.upgradecoordinator.ts

@@ -41,11 +41,17 @@ const initializationGraceMs = 30_000;
 const startLeaseDrainTimeoutMs = 60_000;
 const upgradeTokenPattern = /^[A-Za-z0-9_-]{43}$/;
 const upgradeTokenHashPattern = /^[a-f0-9]{64}$/;
+const upgradeSemverPattern = /^(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-]+)*)?$/;
 const leaseDirectoryPattern = /^[a-f0-9]{20}$/;
 const tokenMetadataPattern = /^(?:grant|ack|action-(?:prepare|finalize))-[a-f0-9]{20}\.json(?:\.consuming-[1-9][0-9]*-[a-f0-9]{8})?$/;
+const acknowledgementTemporaryPattern = /^ack-[a-f0-9]{20}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{8}$/;
+const ownerTransferTemporaryPattern = /^owner-transfer-[1-9][0-9]*-[a-f0-9]{8}\.json\.tmp$/;
 const transactionMetadataPattern = /^transaction-[a-f0-9]{20}\.json$/;
 const transactionTemporaryMetadataPattern = /^transaction-[a-f0-9]{20}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{8}$/;
 const transactionMutationDirectoryPattern = /^transaction-[a-f0-9]{20}\.json\.lock$/;
+const transactionAdoptionPattern = /^transaction-([a-f0-9]{20})\.json\.adopting-([a-f0-9]{20})$/;
+const transactionAdoptionAuditPattern = /^adoption-([a-f0-9]{20})-([a-f0-9]{20})\.json$/;
+const transactionAdoptionAuditTemporaryPattern = /^adoption-[a-f0-9]{20}-[a-f0-9]{20}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{8}$/;
 const ownershipGuardDirectoryPattern = /^[a-f0-9]{64}\.guard$/;
 const ownershipGuardTemporaryPattern = /^[a-f0-9]{64}\.guard\.tmp-[1-9][0-9]*-[a-f0-9]{32}$/;
 const ownerRemovalPattern = /^\.owner-removing-([1-9][0-9]*)-([a-f0-9]{64})-([a-f0-9]{16})$/;
@@ -60,6 +66,13 @@ const workerTerminationGraceMs = 5_000;
 
 type TUpgradeOwnerKind = 'upgrade' | 'start';
 
+interface IUpgradeSemver {
+  major: string;
+  minor: string;
+  patch: string;
+  prerelease: string[];
+}
+
 interface IUpgradeProcessOwner {
   version: typeof coordinationVersion;
   kind: TUpgradeOwnerKind;
@@ -90,6 +103,14 @@ interface IUpgradeLaunchGrant {
   controller: IUpgradeExpectedController;
 }
 
+interface IUpgradeWorkerAcknowledgement {
+  version: typeof coordinationVersion;
+  tokenHash: string;
+  pid: number;
+  processGroupId: number;
+  fingerprint: string;
+}
+
 export interface IUpgradeWorkerPayload {
   version: typeof coordinationVersion;
   token: string;
@@ -158,6 +179,7 @@ export interface IUpgradeTransactionV2 extends IUpgradeTransactionBase {
   version: typeof coordinationVersion;
   sourceVersion: string;
   targetVersion?: string;
+  registryUrl?: string;
   targetStartupInvoked?: true;
 }
 
@@ -173,6 +195,7 @@ export interface IUpgradeTransactionV3 extends IUpgradeTransactionBase {
   targetManagementVersion: typeof upgradePackageTransitionTarget.managementVersion;
   targetCliName: typeof upgradePackageTransitionTarget.cliName;
   targetCliRelativePath: typeof upgradePackageTransitionTarget.cliRelativePath;
+  recoveryTargetVersion?: string;
   packageTransitionStarted?: true;
   groupedTargetVerified?: true;
   targetPackageCommitStarted?: true;
@@ -182,6 +205,35 @@ export interface IUpgradeTransactionV3 extends IUpgradeTransactionBase {
 
 export type TUpgradeTransaction = IUpgradeTransactionV2 | IUpgradeTransactionV3;
 
+export interface IUpgradeTransactionInventoryEntry {
+  fileName: string;
+  state: 'active' | 'adopting';
+  transaction: TUpgradeTransaction;
+}
+
+export interface IUpgradeTransactionInventory {
+  transactions: IUpgradeTransactionInventoryEntry[];
+  tokenMetadataFileNames: string[];
+  mutationDirectoryNames: string[];
+}
+
+export interface IAdoptOrphanedUpgradeTransactionOptions {
+  lock: UpgradeInstallationLock;
+  token: string;
+  expectedTokenHash: string;
+  expectedRevision: number;
+  port: number;
+  installedVersion: string;
+  registryUrl?: string;
+}
+
+interface IUpgradeTransactionAdoptionAudit {
+  version: 1;
+  adoptedAt: number;
+  adoptedTargetVersion: string;
+  previousTransaction: TUpgradeTransaction;
+}
+
 export type TUpgradeControllerAction = 'prepare' | 'finalize';
 
 interface IUpgradeControllerActionGrant {
@@ -443,6 +495,82 @@ const assertBoundedText = (valueArg: unknown, nameArg: string, maximumBytesArg:
   return valueArg;
 };
 
+const parseUpgradeSemver = (valueArg: string): IUpgradeSemver => {
+  const match = upgradeSemverPattern.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 compareUpgradeNumericStrings = (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 compareUpgradeSemver = (leftArg: string, rightArg: string): number => {
+  const left = parseUpgradeSemver(leftArg);
+  const right = parseUpgradeSemver(rightArg);
+  for (const key of ['major', 'minor', 'patch'] as const) {
+    const comparison = compareUpgradeNumericStrings(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 compareUpgradeNumericStrings(leftIdentifier, rightIdentifier);
+    }
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftIdentifier < rightIdentifier ? -1 : 1;
+  }
+  return 0;
+};
+
+export const normalizeUpgradeRegistryUrl = (valueArg: unknown): string => {
+  const value = assertBoundedText(valueArg, 'The upgrade registry URL', 2_048);
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch (errorArg) {
+    throw new Error('The upgrade registry URL is invalid.', { cause: errorArg });
+  }
+  const loopbackHttp = parsed.protocol === 'http:' && new Set([
+    'localhost',
+    '127.0.0.1',
+    '[::1]',
+  ]).has(parsed.hostname);
+  if (
+    (parsed.protocol !== 'https:' && !loopbackHttp)
+    || parsed.hostname.length === 0
+    || parsed.username.length > 0
+    || parsed.password.length > 0
+    || parsed.search.length > 0
+    || parsed.hash.length > 0
+  ) throw new Error('The upgrade registry URL is unsafe.');
+  return parsed.toString();
+};
+
 const assertRuntimeId = (valueArg: unknown): IControllerRuntimeId => {
   if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
     throw new Error('The upgrade session identity is malformed.');
@@ -550,6 +678,7 @@ const parseUpgradeTransactionV2 = (valueArg: unknown): IUpgradeTransactionV2 =>
     'continueSessions', 'gracePeriodMs', 'phase', 'message', 'createdAt', 'updatedAt',
     'phaseStartedAt', 'sessions',
     ...(value.targetVersion === undefined ? [] : ['targetVersion']),
+    ...(value.registryUrl === undefined ? [] : ['registryUrl']),
     ...(value.targetStartupInvoked === undefined ? [] : ['targetStartupInvoked']),
     ...(value.preparationAcceptedAt === undefined ? [] : ['preparationAcceptedAt']),
     ...(value.preparationDeadlineAt === undefined ? [] : ['preparationDeadlineAt']),
@@ -696,6 +825,9 @@ const parseUpgradeTransactionV2 = (valueArg: unknown): IUpgradeTransactionV2 =>
     ...(value.targetVersion === undefined
       ? {}
       : { targetVersion: assertBoundedText(value.targetVersion, 'The upgrade target version', 128) }),
+    ...(value.registryUrl === undefined
+      ? {}
+      : { registryUrl: normalizeUpgradeRegistryUrl(value.registryUrl) }),
     ...(value.targetStartupInvoked === true ? { targetStartupInvoked: true } : {}),
     controllerWasRunning: value.controllerWasRunning,
     continueSessions: value.continueSessions,
@@ -737,6 +869,7 @@ const parseUpgradeTransactionV3 = (valueArg: unknown): IUpgradeTransactionV3 =>
     'targetCliName', 'targetCliRelativePath',
     'controllerWasRunning', 'continueSessions', 'gracePeriodMs', 'phase', 'message',
     'createdAt', 'updatedAt', 'phaseStartedAt', 'sessions',
+    ...(value.recoveryTargetVersion === undefined ? [] : ['recoveryTargetVersion']),
     ...(value.packageTransitionStarted === undefined ? [] : ['packageTransitionStarted']),
     ...(value.groupedTargetVerified === undefined ? [] : ['groupedTargetVerified']),
     ...(value.targetPackageCommitStarted === undefined ? [] : ['targetPackageCommitStarted']),
@@ -762,6 +895,14 @@ const parseUpgradeTransactionV3 = (valueArg: unknown): IUpgradeTransactionV3 =>
     || value.targetManagementVersion !== upgradePackageTransitionTarget.managementVersion
     || value.targetCliName !== upgradePackageTransitionTarget.cliName
     || value.targetCliRelativePath !== upgradePackageTransitionTarget.cliRelativePath
+    || (value.recoveryTargetVersion !== undefined && (
+      typeof value.recoveryTargetVersion !== 'string'
+      || compareUpgradeSemver(
+        value.recoveryTargetVersion,
+        upgradePackageTransitionTarget.version,
+      ) <= 0
+      || value.targetPackageCommitStarted !== true
+    ))
     || (value.packageTransitionStarted !== undefined && value.packageTransitionStarted !== true)
     || (value.groupedTargetVerified !== undefined && value.groupedTargetVerified !== true)
     || (value.targetPackageCommitStarted !== undefined
@@ -829,6 +970,15 @@ const parseUpgradeTransactionV3 = (valueArg: unknown): IUpgradeTransactionV3 =>
     targetManagementVersion: upgradePackageTransitionTarget.managementVersion,
     targetCliName: upgradePackageTransitionTarget.cliName,
     targetCliRelativePath: upgradePackageTransitionTarget.cliRelativePath,
+    ...(value.recoveryTargetVersion === undefined
+      ? {}
+      : {
+          recoveryTargetVersion: assertBoundedText(
+            value.recoveryTargetVersion,
+            'The package-transition recovery target version',
+            128,
+          ),
+        }),
     ...(value.packageTransitionStarted === true ? { packageTransitionStarted: true } : {}),
     ...(value.groupedTargetVerified === true ? { groupedTargetVerified: true } : {}),
     ...(value.targetPackageCommitStarted === true ? { targetPackageCommitStarted: true } : {}),
@@ -846,6 +996,34 @@ const parseUpgradeTransaction = (valueArg: unknown): TUpgradeTransaction => {
     : parseUpgradeTransactionV3(valueArg);
 };
 
+const parseUpgradeTransactionAdoptionAudit = (
+  valueArg: unknown,
+): IUpgradeTransactionAdoptionAudit => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('Upgrade transaction adoption metadata is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (!exactKeys(value, [
+    'version', 'adoptedAt', 'adoptedTargetVersion', 'previousTransaction',
+  ])) throw new Error('Upgrade transaction adoption metadata has unexpected fields.');
+  const previousTransaction = parseUpgradeTransaction(value.previousTransaction);
+  if (
+    value.version !== 1
+    || !Number.isSafeInteger(value.adoptedAt)
+    || (value.adoptedAt as number) < previousTransaction.createdAt
+  ) throw new Error('Upgrade transaction adoption metadata is invalid.');
+  return {
+    version: 1,
+    adoptedAt: value.adoptedAt as number,
+    adoptedTargetVersion: assertBoundedText(
+      value.adoptedTargetVersion,
+      'The adopted upgrade target version',
+      128,
+    ),
+    previousTransaction,
+  };
+};
+
 const parseTransactionMutationOwner = (valueArg: unknown): IUpgradeTransactionMutationOwner => {
   if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
     throw new Error('The upgrade transaction mutation owner is malformed.');
@@ -945,6 +1123,18 @@ export const upgradeTransactionIsStalled = (
   return nowArg - transactionArg.phaseStartedAt > maximumPhaseDurationMs[transactionArg.phase];
 };
 
+export const upgradeTransactionRequiresForwardRecovery = (
+  transactionArg: TUpgradeTransaction,
+): boolean => transactionArg.version === coordinationVersion
+  ? transactionArg.targetStartupInvoked === true
+  : transactionArg.targetPackageCommitStarted === true;
+
+export const upgradeTransactionTargetVersion = (
+  transactionArg: TUpgradeTransaction,
+): string | undefined => transactionArg.version === upgradePackageTransitionTransactionVersion
+  ? transactionArg.recoveryTargetVersion ?? transactionArg.targetVersion
+  : transactionArg.targetVersion;
+
 const ownerIsLive = async (ownerArg: IUpgradeProcessOwner): Promise<boolean> => {
   if (ownerArg.uid !== assertUid()) return false;
   const identity = await readControllerProcessIdentity(ownerArg.pid);
@@ -1357,6 +1547,104 @@ class UpgradeOwnedDirectory {
 export class UpgradeInstallationLock extends UpgradeOwnedDirectory {}
 export class UpgradeStartLease extends UpgradeOwnedDirectory {}
 
+export interface IVerifiedUpgradeWorkerProcessGroup {
+  pid: number;
+  processGroupId: number;
+  fingerprint: string;
+  cliPath: string;
+}
+
+export const terminateVerifiedUpgradeWorkerProcessGroup = async (
+  worker: IVerifiedUpgradeWorkerProcessGroup,
+): Promise<void> => {
+  const identity = await readControllerProcessIdentity(worker.pid);
+  const existingMembers = worker.processGroupId === worker.pid
+    ? await readProcessGroupMemberPids(worker.processGroupId)
+    : [];
+  if (!identity || identity.fingerprint !== worker.fingerprint) {
+    if (existingMembers.length === 0) return;
+    throw new Error(
+      'The stalled upgrade worker leader is unavailable; its remaining group cannot be signaled safely.',
+    );
+  }
+  if (
+    identity.processGroupId !== worker.processGroupId
+    || !identity.processGroupLeader
+    || !await processIdentityHasCliCommand(
+      identity,
+      worker.cliPath,
+      '__upgrade-worker',
+      { allowMissingAbsolutePath: true },
+    )
+  ) throw new Error('The stalled upgrade worker identity changed unexpectedly.');
+  const readStableMemberSnapshot = async (): Promise<NonNullable<Awaited<
+    ReturnType<typeof readControllerProcessIdentity>
+  >>[]> => {
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const processIdsBefore = await readProcessGroupMemberPids(worker.processGroupId);
+      const identities = await Promise.all(
+        processIdsBefore.map(async (processIdArg) => await readControllerProcessIdentity(processIdArg)),
+      );
+      const processIdsAfter = await readProcessGroupMemberPids(worker.processGroupId);
+      if (
+        processIdsBefore.length === processIdsAfter.length
+        && processIdsBefore.every((processIdArg, indexArg) => processIdArg === processIdsAfter[indexArg])
+        && identities.every((candidateArg) => (
+          candidateArg !== null && candidateArg.processGroupId === worker.processGroupId
+        ))
+        && identities.some((candidateArg) => (
+          candidateArg!.pid === worker.pid && candidateArg!.fingerprint === worker.fingerprint
+        ))
+      ) return identities as NonNullable<typeof identities[number]>[];
+    }
+    throw new Error('The stalled upgrade worker group could not be snapshotted safely.');
+  };
+  const members = await readStableMemberSnapshot();
+  const signalOwnedMembers = async (signalArg: NodeJS.Signals): Promise<void> => {
+    const orderedMembers = [...members].sort((leftArg, rightArg) => (
+      leftArg.pid === worker.pid ? 1 : rightArg.pid === worker.pid ? -1 : 0
+    ));
+    for (const member of orderedMembers) {
+      const current = await readControllerProcessIdentity(member.pid);
+      if (!current || current.fingerprint !== member.fingerprint) continue;
+      if (current.processGroupId !== worker.processGroupId) {
+        throw new Error('A captured upgrade worker process escaped its owned process group.');
+      }
+      try {
+        process.kill(member.pid, signalArg);
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'ESRCH') throw errorArg;
+      }
+    }
+  };
+  const waitForDrain = async (): Promise<boolean> => {
+    const deadline = Date.now() + workerTerminationGraceMs;
+    while (Date.now() < deadline) {
+      const [captured, group] = await Promise.all([
+        Promise.all(members.map(async (memberArg) => {
+          const current = await readControllerProcessIdentity(memberArg.pid);
+          return current?.fingerprint === memberArg.fingerprint;
+        })),
+        readProcessGroupMemberPids(worker.processGroupId),
+      ]);
+      if (!captured.some(Boolean) && group.length === 0) return true;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    const [captured, group] = await Promise.all([
+      Promise.all(members.map(async (memberArg) => {
+        const current = await readControllerProcessIdentity(memberArg.pid);
+        return current?.fingerprint === memberArg.fingerprint;
+      })),
+      readProcessGroupMemberPids(worker.processGroupId),
+    ]);
+    return !captured.some(Boolean) && group.length === 0;
+  };
+  await signalOwnedMembers('SIGTERM');
+  if (await waitForDrain()) return;
+  await signalOwnedMembers('SIGKILL');
+  if (!await waitForDrain()) throw new Error('The stalled upgrade worker group did not terminate.');
+};
+
 export class UpgradeCoordinator {
   public readonly uid: number;
   public readonly baseDirectory: string;
@@ -1424,6 +1712,14 @@ export class UpgradeCoordinator {
     await this.initializationTask;
   }
 
+  public async initializeExistingCanonicalState(): Promise<void> {
+    if (this.usesLegacyLocation || this.usesInheritedLocation) {
+      throw new Error('Canonical upgrade initialization cannot use an inherited root.');
+    }
+    if (!await lstatIfPresent(this.baseDirectory)) return;
+    await this.init();
+  }
+
   private async performInitialization(): Promise<void> {
     if (!this.usesLegacyLocation && !this.usesInheritedLocation) {
       const home = resolveAGLHomePaths();
@@ -1438,6 +1734,86 @@ export class UpgradeCoordinator {
     await this.cleanupOwnershipGuardDirectories();
     const entries = await plugins.fs.promises.readdir(this.baseDirectory, { withFileTypes: true });
     for (const entry of entries) {
+      if (entry.isFile() && transactionAdoptionAuditTemporaryPattern.test(entry.name)) {
+        const filePath = plugins.path.join(this.baseDirectory, entry.name);
+        const stats = await lstatIfPresent(filePath);
+        if (!stats) continue;
+        if (
+          !stats.isFile()
+          || stats.isSymbolicLink()
+          || stats.uid !== this.uid
+          || (stats.mode & 0o077) !== 0
+        ) throw new Error(`Upgrade transaction adoption temporary is unsafe: ${filePath}`);
+        if (Date.now() - stats.mtimeMs > initializationGraceMs) {
+          await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
+            if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+          });
+        }
+        continue;
+      }
+      if (entry.isFile() && transactionAdoptionAuditPattern.test(entry.name)) {
+        const filePath = plugins.path.join(this.baseDirectory, entry.name);
+        const stats = await lstatIfPresent(filePath);
+        if (!stats) continue;
+        if (
+          !stats.isFile()
+          || stats.isSymbolicLink()
+          || stats.uid !== this.uid
+          || (stats.mode & 0o077) !== 0
+        ) throw new Error(`Upgrade transaction adoption metadata is unsafe: ${filePath}`);
+        parseUpgradeTransactionAdoptionAudit(await readPrivateJson(filePath));
+        if (Date.now() - stats.mtimeMs > transactionRetentionMs) {
+          const lockState = await this.inspectOwnedDirectory(this.upgradeLockDirectory);
+          if (lockState.state === 'absent' || lockState.state === 'stale') {
+            await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
+              if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+            });
+          }
+        }
+        continue;
+      }
+      if (entry.isFile() && acknowledgementTemporaryPattern.test(entry.name)) {
+        const filePath = plugins.path.join(this.baseDirectory, entry.name);
+        const stats = await lstatIfPresent(filePath);
+        if (!stats) continue;
+        if (
+          !stats.isFile()
+          || stats.isSymbolicLink()
+          || stats.uid !== this.uid
+          || (stats.mode & 0o077) !== 0
+        ) throw new Error(`Upgrade acknowledgement temporary is unsafe: ${filePath}`);
+        if (Date.now() - stats.mtimeMs > initializationGraceMs) {
+          await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
+            if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+          });
+        }
+        continue;
+      }
+      if (entry.isFile() && ownerTransferTemporaryPattern.test(entry.name)) {
+        const filePath = plugins.path.join(this.baseDirectory, entry.name);
+        const stats = await lstatIfPresent(filePath);
+        if (!stats) continue;
+        if (
+          !stats.isFile()
+          || stats.isSymbolicLink()
+          || stats.uid !== this.uid
+          || (stats.mode & 0o077) !== 0
+          || stats.nlink !== 1
+        ) throw new Error(`Upgrade owner-transfer temporary is unsafe: ${filePath}`);
+        if (Date.now() - stats.mtimeMs > initializationGraceMs) {
+          await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
+            if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+          });
+          await syncDirectory(this.baseDirectory);
+        }
+        continue;
+      }
+      if (entry.name.startsWith('owner-transfer-')) {
+        throw new Error(`Upgrade owner-transfer temporary has an invalid name: ${entry.name}`);
+      }
+      if (entry.name.startsWith('adoption-')) {
+        throw new Error(`Upgrade transaction adoption metadata has an invalid name: ${entry.name}`);
+      }
       if (!entry.isFile() || !tokenMetadataPattern.test(entry.name)) continue;
       const filePath = plugins.path.join(this.baseDirectory, entry.name);
       const stats = await lstatIfPresent(filePath);
@@ -1460,6 +1836,18 @@ export class UpgradeCoordinator {
       withFileTypes: true,
     })) {
       const filePath = plugins.path.join(this.transactionsDirectory, entry.name);
+      if (entry.isFile() && transactionAdoptionPattern.test(entry.name)) {
+        const stats = await lstatIfPresent(filePath);
+        if (!stats) continue;
+        if (
+          !stats.isFile()
+          || stats.isSymbolicLink()
+          || stats.uid !== this.uid
+          || (stats.mode & 0o077) !== 0
+        ) throw new Error(`Upgrade transaction adoption state is unsafe: ${filePath}`);
+        parseUpgradeTransaction(await readPrivateJson(filePath));
+        continue;
+      }
       if (entry.isFile() && transactionTemporaryMetadataPattern.test(entry.name)) {
         const stats = await lstatIfPresent(filePath);
         if (!stats) continue;
@@ -1490,28 +1878,145 @@ export class UpgradeCoordinator {
         }
         continue;
       }
-      if (!entry.isFile() || !transactionMetadataPattern.test(entry.name)) continue;
-      const stats = await lstatIfPresent(filePath);
-      if (!stats) continue;
+      if (entry.isFile() && transactionMetadataPattern.test(entry.name)) {
+        const stats = await lstatIfPresent(filePath);
+        if (!stats) continue;
+        if (
+          !stats.isFile()
+          || stats.isSymbolicLink()
+          || stats.uid !== this.uid
+          || (stats.mode & 0o077) !== 0
+        ) throw new Error(`Upgrade transaction metadata is unsafe: ${filePath}`);
+        if (Date.now() - stats.mtimeMs > transactionRetentionMs) {
+          const transaction = parseUpgradeTransaction(await readPrivateJson(filePath));
+          const workerIsLive = await this.transactionWorkerIsLive(transaction).catch(() => true);
+          const controllerIsLive = transaction.controller
+            ? await this.transactionControllerIsLive(transaction).catch(() => true)
+            : false;
+          if (
+            transaction.terminal
+            || (
+              !upgradeTransactionRequiresForwardRecovery(transaction)
+              && !workerIsLive
+              && !controllerIsLive
+            )
+          ) {
+            await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
+              if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+            });
+          }
+        }
+        continue;
+      }
+      if (entry.name.startsWith('transaction-')) {
+        throw new Error(`Upgrade transaction metadata has an invalid name: ${entry.name}`);
+      }
+    }
+  }
+
+  public async inspectCanonicalTransactionInventory(): Promise<IUpgradeTransactionInventory> {
+    if (this.usesLegacyLocation || this.usesInheritedLocation) {
+      throw new Error('Canonical upgrade transaction inventory cannot use an inherited root.');
+    }
+    const empty = (): IUpgradeTransactionInventory => ({
+      transactions: [],
+      tokenMetadataFileNames: [],
+      mutationDirectoryNames: [],
+    });
+    const baseStats = await lstatIfPresent(this.baseDirectory);
+    if (!baseStats) return empty();
+    await assertPrivateDirectory(this.baseDirectory);
+
+    const tokenMetadataFileNames: string[] = [];
+    for (const entry of await plugins.fs.promises.readdir(this.baseDirectory, {
+      withFileTypes: true,
+    })) {
+      if (entry.isFile() && tokenMetadataPattern.test(entry.name)) {
+        const filePath = plugins.path.join(this.baseDirectory, entry.name);
+        await readPrivateJson(filePath);
+        tokenMetadataFileNames.push(entry.name);
+        continue;
+      }
+      if (entry.isFile() && acknowledgementTemporaryPattern.test(entry.name)) {
+        await readPrivateJson(plugins.path.join(this.baseDirectory, entry.name));
+        tokenMetadataFileNames.push(entry.name);
+        continue;
+      }
+      if (entry.isFile() && transactionAdoptionAuditPattern.test(entry.name)) {
+        parseUpgradeTransactionAdoptionAudit(
+          await readPrivateJson(plugins.path.join(this.baseDirectory, entry.name)),
+        );
+        continue;
+      }
       if (
-        !stats.isFile()
-        || stats.isSymbolicLink()
-        || stats.uid !== this.uid
-        || (stats.mode & 0o077) !== 0
-      ) throw new Error(`Upgrade transaction metadata is unsafe: ${filePath}`);
-      if (Date.now() - stats.mtimeMs > transactionRetentionMs) {
-        const transaction = parseUpgradeTransaction(await readPrivateJson(filePath));
-        const workerIsLive = await this.transactionWorkerIsLive(transaction).catch(() => true);
-        const controllerIsLive = transaction.controller
-          ? await this.transactionControllerIsLive(transaction).catch(() => true)
-          : false;
-        if (transaction.terminal || (!workerIsLive && !controllerIsLive)) {
-          await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
-            if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
-          });
+        entry.name.startsWith('grant-')
+        || entry.name.startsWith('ack-')
+        || entry.name.startsWith('action-')
+        || entry.name.startsWith('adoption-')
+      ) throw new Error(`Upgrade coordination metadata has an invalid name: ${entry.name}`);
+    }
+
+    const transactionsStats = await lstatIfPresent(this.transactionsDirectory);
+    if (!transactionsStats) {
+      return { transactions: [], tokenMetadataFileNames, mutationDirectoryNames: [] };
+    }
+    await assertPrivateDirectory(this.transactionsDirectory);
+    const transactions: IUpgradeTransactionInventoryEntry[] = [];
+    const mutationDirectoryNames: string[] = [];
+    for (const entry of await plugins.fs.promises.readdir(this.transactionsDirectory, {
+      withFileTypes: true,
+    })) {
+      if (entry.isDirectory() && transactionMutationDirectoryPattern.test(entry.name)) {
+        mutationDirectoryNames.push(entry.name);
+        continue;
+      }
+      if (entry.isFile() && transactionTemporaryMetadataPattern.test(entry.name)) continue;
+      const active = entry.isFile() && transactionMetadataPattern.test(entry.name);
+      const adoptionMatch = entry.isFile() ? transactionAdoptionPattern.exec(entry.name) : null;
+      if (!active && !adoptionMatch) {
+        if (entry.name.startsWith('transaction-')) {
+          throw new Error(`Upgrade transaction metadata has an invalid name: ${entry.name}`);
         }
+        continue;
+      }
+      const filePath = plugins.path.join(this.transactionsDirectory, entry.name);
+      const before = await lstatIfPresent(filePath);
+      if (!before) continue;
+      if (
+        !before.isFile()
+        || before.isSymbolicLink()
+        || before.uid !== this.uid
+        || (before.mode & 0o077) !== 0
+      ) throw new Error(`Upgrade transaction metadata is unsafe: ${filePath}`);
+      const transaction = parseUpgradeTransaction(await readPrivateJson(filePath));
+      const after = await lstatIfPresent(filePath);
+      if (
+        !after
+        || !sameOwnedDirectoryIdentity(after, { dev: before.dev, ino: before.ino })
+        || after.size !== before.size
+        || after.mtimeMs !== before.mtimeMs
+      ) throw new Error('Upgrade transaction metadata changed during inventory.');
+      const tokenPrefix = transaction.tokenHash.slice(0, 20);
+      if (active && entry.name !== `transaction-${tokenPrefix}.json`) {
+        throw new Error('Upgrade transaction filename and token binding do not match.');
+      }
+      if (adoptionMatch && tokenPrefix !== adoptionMatch[1] && tokenPrefix !== adoptionMatch[2]) {
+        throw new Error('Upgrade transaction adoption state has an invalid token binding.');
       }
+      transactions.push({
+        fileName: entry.name,
+        state: active ? 'active' : 'adopting',
+        transaction,
+      });
     }
+    return {
+      transactions: transactions.sort((leftArg, rightArg) => (
+        leftArg.transaction.createdAt - rightArg.transaction.createdAt
+        || leftArg.fileName.localeCompare(rightArg.fileName)
+      )),
+      tokenMetadataFileNames: tokenMetadataFileNames.sort(),
+      mutationDirectoryNames: mutationDirectoryNames.sort(),
+    };
   }
 
   private ownershipGuardDirectory(directoryArg: string): string {
@@ -2207,14 +2712,24 @@ export class UpgradeCoordinator {
     await this.withOwnershipMutationGuard(this.upgradeLockDirectory, async () => {
       await optionsArg.lock.assertOwned();
       const ownerPath = plugins.path.join(this.upgradeLockDirectory, ownerFileName);
-      const temporaryPath = `${ownerPath}.transfer-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}`;
+      const temporaryPath = plugins.path.join(
+        this.baseDirectory,
+        `owner-transfer-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}.json.tmp`,
+      );
       try {
         await writePrivateJson(temporaryPath, owner);
         await plugins.fs.promises.rename(temporaryPath, ownerPath);
         await syncDirectory(this.upgradeLockDirectory);
+        await syncDirectory(this.baseDirectory);
         optionsArg.lock.relinquishAfterTransfer();
       } finally {
-        await plugins.fs.promises.unlink(temporaryPath).catch(() => undefined);
+        let removed = false;
+        await plugins.fs.promises.unlink(temporaryPath).then(() => {
+          removed = true;
+        }).catch((errorArg) => {
+          if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+        });
+        if (removed) await syncDirectory(this.baseDirectory);
       }
     });
   }
@@ -2456,10 +2971,263 @@ export class UpgradeCoordinator {
     return result as T;
   }
 
+  private async cleanupUncommittedAdoptionAuditsUnderLock(
+    lockArg: UpgradeInstallationLock,
+  ): Promise<void> {
+    await lockArg.assertOwned();
+    for (const entry of await plugins.fs.promises.readdir(this.baseDirectory, {
+      withFileTypes: true,
+    })) {
+      const match = entry.isFile() ? transactionAdoptionAuditPattern.exec(entry.name) : null;
+      if (!match) continue;
+      const auditPath = plugins.path.join(this.baseDirectory, entry.name);
+      const audit = parseUpgradeTransactionAdoptionAudit(await readPrivateJson(auditPath));
+      const sourcePath = plugins.path.join(
+        this.transactionsDirectory,
+        `transaction-${match[1]}.json`,
+      );
+      const intermediatePath = `${sourcePath}.adopting-${match[2]}`;
+      const targetPath = plugins.path.join(
+        this.transactionsDirectory,
+        `transaction-${match[2]}.json`,
+      );
+      await this.withOwnershipMutationGuard(sourcePath, async () => {
+        await lockArg.assertOwned();
+        const [sourceStats, intermediateStats, targetStats] = await Promise.all([
+          lstatIfPresent(sourcePath),
+          lstatIfPresent(intermediatePath),
+          lstatIfPresent(targetPath),
+        ]);
+        if (!sourceStats || intermediateStats || targetStats) return;
+        const source = parseUpgradeTransaction(await readPrivateJson(sourcePath));
+        if (!plugins.util.isDeepStrictEqual(source, audit.previousTransaction)) return;
+        await plugins.fs.promises.unlink(auditPath);
+        await syncDirectory(this.baseDirectory);
+      });
+    }
+    await lockArg.assertOwned();
+  }
+
+  public async adoptOrphanedTransaction(
+    optionsArg: IAdoptOrphanedUpgradeTransactionOptions,
+  ): Promise<TUpgradeTransaction> {
+    await optionsArg.lock.assertOwned();
+    await this.waitForStartLeasesToDrain(optionsArg.lock);
+    await this.cleanupUncommittedAdoptionAuditsUnderLock(optionsArg.lock);
+    const inventory = await this.inspectCanonicalTransactionInventory();
+    const nonterminal = inventory.transactions.filter((entryArg) => !entryArg.transaction.terminal);
+    if (nonterminal.length !== 1) {
+      throw new Error('Exactly one orphaned upgrade transaction is required for adoption.');
+    }
+    const entry = nonterminal[0];
+    const transaction = entry.transaction;
+    const eligibleV2 = transaction.version === coordinationVersion
+      && transaction.controllerWasRunning === true
+      && transaction.targetStartupInvoked === true
+      && transaction.targetVersion !== undefined
+      && transaction.preparationCompletedAt !== undefined
+      && (transaction.phase === 'restarting' || transaction.phase === 'continuing');
+    const eligibleV3 = transaction.version === upgradePackageTransitionTransactionVersion
+      && transaction.targetPackageCommitStarted === true
+      && (!transaction.controllerWasRunning || transaction.preparationCompletedAt !== undefined)
+      && (
+        transaction.phase === 'installing'
+        || transaction.phase === 'restarting'
+        || transaction.phase === 'continuing'
+      );
+    if (
+      transaction.port !== optionsArg.port
+      || transaction.tokenHash !== optionsArg.expectedTokenHash
+      || transaction.revision !== optionsArg.expectedRevision
+      || (!eligibleV2 && !eligibleV3)
+      || !upgradeTransactionIsStalled(transaction)
+    ) throw new Error('The retained upgrade transaction is not eligible for adoption.');
+    if (transaction.version === upgradePackageTransitionTransactionVersion && optionsArg.registryUrl) {
+      throw new Error(
+        'Legacy package-transition recovery uses pnpm registry configuration and cannot retain --registry.',
+      );
+    }
+    if (await this.transactionWorkerIsLive(transaction)) {
+      throw new Error('The retained upgrade worker is still running.');
+    }
+    if (transaction.controller && await this.transactionControllerIsLive(transaction)) {
+      throw new Error('The retained upgrade controller is still running.');
+    }
+
+    const adoptionMatch = transactionAdoptionPattern.exec(entry.fileName);
+    const tokenPrefixes = new Set([
+      transaction.tokenHash.slice(0, 20),
+      ...(adoptionMatch ? [adoptionMatch[1], adoptionMatch[2]] : []),
+    ]);
+    for (const fileName of inventory.tokenMetadataFileNames) {
+      if ([...tokenPrefixes].some((prefixArg) => fileName.includes(`-${prefixArg}.json`))) {
+        throw new Error('The orphaned upgrade retains token-bound coordination metadata.');
+      }
+    }
+    for (const directoryName of inventory.mutationDirectoryNames) {
+      const prefix = [...tokenPrefixes].find((candidateArg) => (
+        directoryName === `transaction-${candidateArg}.json.lock`
+      ));
+      if (!prefix) continue;
+      const directory = plugins.path.join(this.transactionsDirectory, directoryName);
+      const state = await this.inspectTransactionMutationDirectory(
+        directory,
+        transaction.tokenHash,
+      );
+      if (state.state === 'stale') {
+        await this.reclaimStaleTransactionMutationDirectory(directory, transaction.tokenHash);
+        continue;
+      }
+      if (state.state !== 'absent') {
+        throw new Error('The orphaned upgrade transaction still has mutation ownership.');
+      }
+    }
+
+    const installedVersion = assertBoundedText(
+      optionsArg.installedVersion,
+      'The installed upgrade version',
+      128,
+    );
+    compareUpgradeSemver(installedVersion, installedVersion);
+    if (
+      transaction.version === upgradePackageTransitionTransactionVersion
+      && compareUpgradeSemver(
+        installedVersion,
+        upgradeTransactionTargetVersion(transaction)!,
+      ) < 0
+    ) throw new Error('The installed package-transition recovery target would downgrade AGL.');
+    const registryUrl = transaction.version === coordinationVersion
+      ? transaction.registryUrl ?? optionsArg.registryUrl
+      : undefined;
+    if (
+      transaction.version === coordinationVersion
+      && transaction.registryUrl !== undefined
+      && optionsArg.registryUrl !== undefined
+      && transaction.registryUrl !== optionsArg.registryUrl
+    ) throw new Error('The orphaned upgrade registry cannot change during adoption.');
+    const newTokenHash = hashToken(optionsArg.token);
+    const sourcePath = plugins.path.join(this.transactionsDirectory, entry.fileName);
+    const sourcePrefix = transaction.tokenHash.slice(0, 20);
+    const targetPrefix = newTokenHash.slice(0, 20);
+    if (sourcePrefix === targetPrefix) {
+      throw new Error('The adopted upgrade token collided with the retained token.');
+    }
+    const intermediatePath = plugins.path.join(
+      this.transactionsDirectory,
+      `transaction-${sourcePrefix}.json.adopting-${targetPrefix}`,
+    );
+    const targetPath = plugins.path.join(
+      this.transactionsDirectory,
+      `transaction-${targetPrefix}.json`,
+    );
+    const auditPath = plugins.path.join(
+      this.baseDirectory,
+      `adoption-${sourcePrefix}-${targetPrefix}.json`,
+    );
+    const auditTemporaryPath = `${auditPath}.tmp-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}`;
+    for (const path of [intermediatePath, targetPath, auditPath, auditTemporaryPath]) {
+      if (await lstatIfPresent(path)) {
+        throw new Error(`Upgrade transaction adoption destination already exists: ${path}`);
+      }
+    }
+    const now = Date.now();
+    const {
+      worker: _worker,
+      controller: _controller,
+      retainedUntil: _retainedUntil,
+      ...retained
+    } = transaction;
+    const adopted = transaction.version === coordinationVersion
+      ? parseUpgradeTransactionV2({
+          ...retained,
+          tokenHash: newTokenHash,
+          revision: transaction.revision + 1,
+          targetVersion: installedVersion,
+          ...(registryUrl === undefined ? {} : { registryUrl }),
+          phaseStartedAt: now,
+          updatedAt: now,
+          message: `Recovering orphaned upgrade ${transaction.sourceVersion} -> ${transaction.targetVersion} with installed ${installedVersion}.`,
+        })
+      : parseUpgradeTransactionV3({
+          ...retained,
+          tokenHash: newTokenHash,
+          revision: transaction.revision + 1,
+          ...(installedVersion === transaction.targetVersion
+            ? {}
+            : { recoveryTargetVersion: installedVersion }),
+          phaseStartedAt: now,
+          updatedAt: now,
+          message: `Recovering orphaned package transition to installed ${transaction.targetPackageName}@${installedVersion}.`,
+        });
+    const audit = parseUpgradeTransactionAdoptionAudit({
+      version: 1,
+      adoptedAt: now,
+      adoptedTargetVersion: installedVersion,
+      previousTransaction: transaction,
+    });
+    const temporaryPath = `${targetPath}.tmp-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}`;
+
+    await optionsArg.lock.assertOwned();
+    try {
+      await this.withOwnershipMutationGuard(sourcePath, async () => {
+        await this.withOwnershipMutationGuard(intermediatePath, async () => {
+          await this.withOwnershipMutationGuard(targetPath, async () => {
+            const sourceStats = await lstatIfPresent(sourcePath);
+            if (!sourceStats) throw new Error('The orphaned upgrade transaction disappeared.');
+            const current = parseUpgradeTransaction(await readPrivateJson(sourcePath));
+            if (
+              current.tokenHash !== transaction.tokenHash
+              || current.revision !== transaction.revision
+            ) throw new Error('The orphaned upgrade transaction changed before adoption.');
+            try {
+              await writePrivateJson(auditTemporaryPath, audit);
+              await plugins.fs.promises.rename(auditTemporaryPath, auditPath);
+              await syncDirectory(this.baseDirectory);
+              await plugins.fs.promises.rename(sourcePath, intermediatePath);
+              await syncDirectory(this.transactionsDirectory);
+              await writePrivateJson(temporaryPath, adopted);
+              const intermediateStats = await lstatIfPresent(intermediatePath);
+              if (
+                !intermediateStats
+                || !sameOwnedDirectoryIdentity(intermediateStats, {
+                  dev: sourceStats.dev,
+                  ino: sourceStats.ino,
+                })
+              ) throw new Error('The upgrade adoption source identity changed unexpectedly.');
+              await plugins.fs.promises.rename(temporaryPath, intermediatePath);
+              await syncDirectory(this.transactionsDirectory);
+              await plugins.fs.promises.rename(intermediatePath, targetPath);
+              await syncDirectory(this.transactionsDirectory);
+            } finally {
+              await plugins.fs.promises.unlink(auditTemporaryPath).catch(() => undefined);
+              await plugins.fs.promises.unlink(temporaryPath).catch(() => undefined);
+            }
+          });
+        });
+      });
+    } catch (errorArg) {
+      const [sourceStats, intermediateStats, targetStats] = await Promise.all([
+        lstatIfPresent(sourcePath),
+        lstatIfPresent(intermediatePath),
+        lstatIfPresent(targetPath),
+      ]);
+      if (sourceStats && !intermediateStats && !targetStats) {
+        await plugins.fs.promises.unlink(auditPath).catch((cleanupErrorArg) => {
+          if ((cleanupErrorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw cleanupErrorArg;
+        });
+        await syncDirectory(this.baseDirectory);
+      }
+      throw errorArg;
+    }
+    await optionsArg.lock.assertOwned();
+    return parseUpgradeTransaction(await readPrivateJson(targetPath));
+  }
+
   public async createTransaction(optionsArg: {
     token: string;
     port: number;
     sourceVersion: string;
+    registryUrl?: string;
     controllerWasRunning: boolean;
     continueSessions: boolean;
     gracePeriodMs: number;
@@ -2472,6 +3240,9 @@ export class UpgradeCoordinator {
       revision: 0,
       port: assertPort(optionsArg.port),
       sourceVersion: assertBoundedText(optionsArg.sourceVersion, 'The upgrade source version', 128),
+      ...(optionsArg.registryUrl === undefined
+        ? {}
+        : { registryUrl: normalizeUpgradeRegistryUrl(optionsArg.registryUrl) }),
       controllerWasRunning: optionsArg.controllerWasRunning,
       continueSessions: optionsArg.continueSessions,
       gracePeriodMs: optionsArg.gracePeriodMs,
@@ -2602,7 +3373,15 @@ export class UpgradeCoordinator {
           throw new Error(`The upgrade package-transition checkpoint ${checkpoint} cannot regress.`);
         }
       }
+      if (currentArg.recoveryTargetVersion !== next.recoveryTargetVersion) {
+        throw new Error('The package-transition recovery target cannot change after adoption.');
+      }
     }
+    if (
+      currentArg.version === coordinationVersion
+      && next.version === coordinationVersion
+      && currentArg.registryUrl !== next.registryUrl
+    ) throw new Error('The upgrade registry cannot change after the transaction is created.');
     if (
       (currentArg.preparationAcceptedAt !== undefined
         && next.preparationAcceptedAt !== currentArg.preparationAcceptedAt)
@@ -2639,7 +3418,7 @@ export class UpgradeCoordinator {
         ...(current.worker?.logFilePath ? { logFilePath: current.worker.logFilePath } : {}),
       },
       phase: 'checking',
-      message: 'Checking the npm latest version.',
+      message: 'Checking the registry latest version.',
     }));
   }
 
@@ -2744,44 +3523,7 @@ export class UpgradeCoordinator {
   public async terminateUpgradeWorkerCandidate(
     worker: NonNullable<TUpgradeTransaction['worker']>,
   ): Promise<void> {
-    const identity = await readControllerProcessIdentity(worker.pid);
-    if (identity) {
-      if (
-        identity.fingerprint !== worker.fingerprint
-        || identity.processGroupId !== worker.processGroupId
-        || !identity.processGroupLeader
-        || !await processIdentityHasCliCommand(
-          identity,
-          worker.cliPath,
-          '__upgrade-worker',
-          { allowMissingAbsolutePath: true },
-        )
-      ) throw new Error('The stalled upgrade worker identity changed unexpectedly.');
-    } else if (
-      worker.processGroupId !== worker.pid
-      || (await readProcessGroupMemberPids(worker.processGroupId)).length === 0
-    ) {
-      return;
-    }
-    const signalOwnedWorker = (signalArg: NodeJS.Signals): void => {
-      try {
-        process.kill(-worker.processGroupId, signalArg);
-      } catch (errorArg) {
-        if ((errorArg as NodeJS.ErrnoException).code !== 'ESRCH') throw errorArg;
-      }
-    };
-    const waitForDrain = async (): Promise<boolean> => {
-      const deadline = Date.now() + workerTerminationGraceMs;
-      while (Date.now() < deadline) {
-        if ((await readProcessGroupMemberPids(worker.processGroupId)).length === 0) return true;
-        await new Promise((resolve) => setTimeout(resolve, 50));
-      }
-      return (await readProcessGroupMemberPids(worker.processGroupId)).length === 0;
-    };
-    signalOwnedWorker('SIGTERM');
-    if (await waitForDrain()) return;
-    signalOwnedWorker('SIGKILL');
-    if (!await waitForDrain()) throw new Error('The stalled upgrade worker group did not terminate.');
+    await terminateVerifiedUpgradeWorkerProcessGroup(worker);
   }
 
   public async readSanitizedUpgradeStatus(
@@ -2797,7 +3539,7 @@ export class UpgradeCoordinator {
       : transaction.phase;
     return {
       fromVersion: transaction.sourceVersion,
-      toVersion: transaction.targetVersion,
+      toVersion: upgradeTransactionTargetVersion(transaction)!,
       phase,
     };
   }
@@ -3022,26 +3764,81 @@ export class UpgradeCoordinator {
     }
   }
 
-  public async acknowledgeWorker(tokenArg: string): Promise<void> {
+  public async removeWorkerAcknowledgement(tokenArg: string): Promise<void> {
+    await this.init();
+    let removed = false;
+    await plugins.fs.promises.unlink(this.tokenFilePath('ack', tokenArg)).then(() => {
+      removed = true;
+    }).catch((errorArg) => {
+      if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+    });
+    if (removed) await syncDirectory(this.baseDirectory);
+  }
+
+  public async acknowledgeWorker(
+    tokenArg: string,
+    workerArg: Pick<IVerifiedUpgradeWorkerProcessGroup, 'pid' | 'processGroupId' | 'fingerprint'>,
+  ): Promise<void> {
     await this.init();
-    const acknowledgement = {
+    const identity = await readControllerProcessIdentity(workerArg.pid);
+    if (
+      !identity
+      || identity.fingerprint !== workerArg.fingerprint
+      || identity.processGroupId !== workerArg.processGroupId
+    ) throw new Error('The upgrade acknowledgement worker identity is no longer current.');
+    const acknowledgement: IUpgradeWorkerAcknowledgement = {
       version: coordinationVersion,
       tokenHash: hashToken(tokenArg),
+      pid: identity.pid,
+      processGroupId: identity.processGroupId,
+      fingerprint: identity.fingerprint,
     };
     const acknowledgementPath = this.tokenFilePath('ack', tokenArg);
+    const temporaryPath = `${acknowledgementPath}.tmp-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}`;
+    let published = false;
     try {
-      await writePrivateJson(acknowledgementPath, acknowledgement);
+      await writePrivateJson(temporaryPath, acknowledgement);
+      try {
+        await plugins.fs.promises.link(temporaryPath, acknowledgementPath);
+        published = true;
+        await syncDirectory(this.baseDirectory);
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') {
+          if (published) return;
+          throw errorArg;
+        }
+        let existing: unknown;
+        try {
+          existing = await readPrivateJson(acknowledgementPath);
+        } catch (readErrorArg) {
+          if ((readErrorArg as NodeJS.ErrnoException).code === 'ENOENT') {
+            published = true;
+            return;
+          }
+          throw readErrorArg;
+        }
+        if (
+          !existing
+          || typeof existing !== 'object'
+          || Array.isArray(existing)
+          || !exactKeys(existing as Record<string, unknown>, [
+            'version', 'tokenHash', 'pid', 'processGroupId', 'fingerprint',
+          ])
+          || (existing as Record<string, unknown>).version !== coordinationVersion
+          || (existing as Record<string, unknown>).tokenHash !== acknowledgement.tokenHash
+          || (existing as Record<string, unknown>).pid !== acknowledgement.pid
+          || (existing as Record<string, unknown>).processGroupId !== acknowledgement.processGroupId
+          || (existing as Record<string, unknown>).fingerprint !== acknowledgement.fingerprint
+        ) throw new Error('The existing upgrade acknowledgement is invalid.');
+        published = true;
+      }
     } catch (errorArg) {
-      if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
-      const existing = await readPrivateJson(acknowledgementPath);
-      if (
-        !existing
-        || typeof existing !== 'object'
-        || Array.isArray(existing)
-        || !exactKeys(existing as Record<string, unknown>, ['version', 'tokenHash'])
-        || (existing as Record<string, unknown>).version !== coordinationVersion
-        || (existing as Record<string, unknown>).tokenHash !== acknowledgement.tokenHash
-      ) throw new Error('The existing upgrade acknowledgement is invalid.');
+      if (published) return;
+      throw errorArg;
+    } finally {
+      await plugins.fs.promises.unlink(temporaryPath).catch((errorArg) => {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT' && !published) throw errorArg;
+      });
     }
   }
 
@@ -3050,6 +3847,8 @@ export class UpgradeCoordinator {
     timeoutMsArg = 10_000,
   ): Promise<void> {
     const token = assertToken(tokenArg);
+    const identity = await readControllerProcessIdentity(process.pid);
+    if (!identity) throw new Error('The upgrade worker acknowledgement identity is unavailable.');
     const ackPath = this.tokenFilePath('ack', token);
     const deadline = Date.now() + timeoutMsArg;
     while (Date.now() < deadline) {
@@ -3060,11 +3859,14 @@ export class UpgradeCoordinator {
         }
         const ack = value as Record<string, unknown>;
         if (
-          !exactKeys(ack, ['version', 'tokenHash'])
+          !exactKeys(ack, ['version', 'tokenHash', 'pid', 'processGroupId', 'fingerprint'])
           || ack.version !== coordinationVersion
           || typeof ack.tokenHash !== 'string'
           || !upgradeTokenHashPattern.test(ack.tokenHash)
           || !tokensEqual(ack.tokenHash, hashToken(token))
+          || ack.pid !== identity.pid
+          || ack.processGroupId !== identity.processGroupId
+          || ack.fingerprint !== identity.fingerprint
         ) {
           throw new Error(`The ${currentCliName} upgrade acknowledgement binding is invalid.`);
         }