agl 1.0.17 → 21.0.2

package/ts/classes.upgradecoordinator.ts

@@ -0,0 +1,2675 @@
+import * as plugins from './plugins.js';
+import {
+  controllerPackageName,
+  type IControllerRuntimeId,
+  type IControllerUpgradeStatus,
+} from '../ts_interfaces/index.js';
+import {
+  processIdentityHasCliCommand,
+  readControllerProcessIdentity,
+  readProcessGroupMemberPids,
+} from './classes.processinspection.js';
+
+export const upgradeCoordinationVersion = 2 as const;
+const coordinationVersion = upgradeCoordinationVersion;
+export const upgradePackageTransitionTransactionVersion = 3 as const;
+export const upgradePackageTransitionSource = {
+  packageName: '@modelprofile.com/harness-controller',
+  version: '20.0.3',
+  managementVersion: 1,
+  cliName: 'hcon',
+  cliRelativePath: './cli.js',
+} as const;
+export const upgradePackageTransitionTarget = {
+  packageName: 'agl',
+  version: '21.0.0',
+  managementVersion: 2,
+  cliName: 'agl',
+  cliRelativePath: './cli.js',
+} as const;
+const currentCliName = String(controllerPackageName) === upgradePackageTransitionSource.packageName
+  ? upgradePackageTransitionSource.cliName
+  : upgradePackageTransitionTarget.cliName;
+const ownerFileName = 'owner.json';
+const maximumMetadataBytes = 256 * 1024;
+const initializationGraceMs = 30_000;
+const startLeaseDrainTimeoutMs = 60_000;
+const upgradeTokenPattern = /^[A-Za-z0-9_-]{43}$/;
+const upgradeTokenHashPattern = /^[a-f0-9]{64}$/;
+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 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 ownershipGuardDirectoryPattern = /^[a-f0-9]{64}\.guard$/;
+const tokenMetadataRetentionMs = 10 * 60 * 1000;
+const transactionRetentionMs = 24 * 60 * 60 * 1000;
+const terminalStatusRetentionMs = 10 * 60 * 1000;
+const transactionMutationTimeoutMs = 10_000;
+const ownershipGuardTimeoutMs = 10_000;
+const workerTerminationGraceMs = 5_000;
+
+export const upgradeTokenEnvironmentVariable = 'HARNESS_CONTROLLER_UPGRADE_TOKEN';
+
+type TUpgradeOwnerKind = 'upgrade' | 'start';
+
+interface IUpgradeProcessOwner {
+  version: typeof coordinationVersion;
+  kind: TUpgradeOwnerKind;
+  uid: number;
+  tokenHash: string;
+  pid: number;
+  processGroupId: number;
+  fingerprint: string;
+  cliPath: string;
+  command: '__serve' | '__upgrade-worker' | 'upgrade' | 'start' | 'foreground' | 'temp-password';
+  createdAt: number;
+}
+
+export interface IUpgradeExpectedController {
+  pid: number;
+  processGroupId: number;
+  processFingerprint: string;
+}
+
+interface IUpgradeLaunchGrant {
+  version: typeof coordinationVersion;
+  tokenHash: string;
+  expiresAt: number;
+  port: number;
+  packageName: string;
+  packageVersion: string;
+  cliPath: string;
+  controller: IUpgradeExpectedController;
+}
+
+export interface IUpgradeWorkerPayload {
+  version: typeof coordinationVersion;
+  token: string;
+  port: number;
+  gracePeriodMs: number;
+  continueSessions: boolean;
+  expectedController?: IUpgradeExpectedController;
+}
+
+export type TUpgradeSessionTransitionState =
+  | 'pending'
+  | 'submitting'
+  | 'accepted'
+  | 'paused'
+  | 'outcomeUnknown'
+  | 'failed';
+
+export interface IUpgradeSessionState {
+  projectId: string;
+  sessionId: IControllerRuntimeId;
+  pauseState: TUpgradeSessionTransitionState;
+  pauseQueueId?: string;
+  cleanupState?: TUpgradeSessionTransitionState;
+  continueState?: TUpgradeSessionTransitionState;
+  error?: string;
+}
+
+interface IUpgradeTransactionBase {
+  tokenHash: string;
+  revision: number;
+  port: number;
+  controllerWasRunning: boolean;
+  continueSessions: boolean;
+  gracePeriodMs: number;
+  preparationAcceptedAt?: number;
+  preparationDeadlineAt?: number;
+  preparationCompletedAt?: number;
+  phase: IControllerUpgradeStatus['phase'] | 'starting' | 'checking' | 'stopping';
+  message: string;
+  createdAt: number;
+  phaseStartedAt: number;
+  updatedAt: number;
+  retainedUntil?: number;
+  worker?: {
+    pid: number;
+    processGroupId: number;
+    fingerprint: string;
+    cliPath: string;
+    logFilePath?: string;
+  };
+  controller?: {
+    pid: number;
+    processGroupId: number;
+    fingerprint: string;
+    cliPath: string;
+    command: '__serve' | 'foreground';
+  };
+  sessions: IUpgradeSessionState[];
+  terminal?: {
+    success: boolean;
+    error?: string;
+  };
+}
+
+export interface IUpgradeTransactionV2 extends IUpgradeTransactionBase {
+  version: typeof coordinationVersion;
+  sourceVersion: string;
+  targetVersion?: string;
+  targetStartupInvoked?: true;
+}
+
+export interface IUpgradeTransactionV3 extends IUpgradeTransactionBase {
+  version: typeof upgradePackageTransitionTransactionVersion;
+  sourcePackageName: typeof upgradePackageTransitionSource.packageName;
+  sourceVersion: typeof upgradePackageTransitionSource.version;
+  sourceManagementVersion: typeof upgradePackageTransitionSource.managementVersion;
+  sourceCliName: typeof upgradePackageTransitionSource.cliName;
+  sourceCliRelativePath: typeof upgradePackageTransitionSource.cliRelativePath;
+  targetPackageName: typeof upgradePackageTransitionTarget.packageName;
+  targetVersion: typeof upgradePackageTransitionTarget.version;
+  targetManagementVersion: typeof upgradePackageTransitionTarget.managementVersion;
+  targetCliName: typeof upgradePackageTransitionTarget.cliName;
+  targetCliRelativePath: typeof upgradePackageTransitionTarget.cliRelativePath;
+  packageTransitionStarted?: true;
+  groupedTargetVerified?: true;
+  targetPackageCommitStarted?: true;
+  targetPackageCommitted?: true;
+  targetStartupInvoked?: true;
+}
+
+export type TUpgradeTransaction = IUpgradeTransactionV2 | IUpgradeTransactionV3;
+
+export type TUpgradeControllerAction = 'prepare' | 'finalize';
+
+interface IUpgradeControllerActionGrant {
+  version: typeof coordinationVersion;
+  tokenHash: string;
+  action: TUpgradeControllerAction;
+  mode?: 'continue' | 'compensate' | 'reopen';
+  expiresAt: number;
+  packageVersion: string;
+  controller: IUpgradeExpectedController;
+}
+
+interface IUpgradeTransactionMutationOwner {
+  version: typeof coordinationVersion;
+  uid: number;
+  tokenHash: string;
+  pid: number;
+  fingerprint: string;
+  nonce: string;
+  createdAt: number;
+}
+
+interface IUpgradeOwnershipMutationGuardOwner {
+  version: typeof coordinationVersion;
+  uid: number;
+  targetHash: string;
+  pid: number;
+  fingerprint: string;
+  nonce: string;
+  createdAt: number;
+}
+
+const assertUid = (): number => {
+  if (typeof process.getuid !== 'function') {
+    throw new Error(`${currentCliName} upgrade requires a POSIX effective user identity.`);
+  }
+  const uid = process.getuid();
+  if (!Number.isSafeInteger(uid) || uid < 0) {
+    throw new Error('The effective user identity is invalid.');
+  }
+  return uid;
+};
+
+const assertToken = (tokenArg: unknown): string => {
+  if (typeof tokenArg !== 'string' || !upgradeTokenPattern.test(tokenArg)) {
+    throw new Error('The upgrade coordination token is invalid.');
+  }
+  return tokenArg;
+};
+
+const hashToken = (tokenArg: unknown): string => plugins.crypto
+  .createHash('sha256')
+  .update(assertToken(tokenArg), 'utf8')
+  .digest('hex');
+
+const tokensEqual = (leftArg: string, rightArg: string): boolean => {
+  const left = Buffer.from(leftArg, 'utf8');
+  const right = Buffer.from(rightArg, 'utf8');
+  return left.byteLength === right.byteLength && plugins.crypto.timingSafeEqual(left, right);
+};
+
+const assertPort = (portArg: unknown): number => {
+  if (!Number.isSafeInteger(portArg) || (portArg as number) < 1 || (portArg as number) > 65_535) {
+    throw new Error('The upgrade coordination port is invalid.');
+  }
+  return portArg as number;
+};
+
+const exactKeys = (valueArg: Record<string, unknown>, expectedArg: string[]): boolean => {
+  const actual = Object.keys(valueArg).sort();
+  const expected = [...expectedArg].sort();
+  return actual.length === expected.length
+    && actual.every((key, index) => key === expected[index]);
+};
+
+const assertPrivateDirectory = async (directoryArg: string): Promise<void> => {
+  const stats = await plugins.fs.promises.lstat(directoryArg);
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw new Error(`Upgrade coordination path must be a real directory: ${directoryArg}`);
+  }
+  if (typeof process.getuid === 'function' && stats.uid !== process.getuid()) {
+    throw new Error(`Upgrade coordination path is not owned by the current user: ${directoryArg}`);
+  }
+  if ((stats.mode & 0o077) !== 0) {
+    throw new Error(`Upgrade coordination path must not be group or world accessible: ${directoryArg}`);
+  }
+};
+
+const lstatIfPresent = async (filePathArg: string): Promise<plugins.fs.Stats | undefined> => {
+  try {
+    return await plugins.fs.promises.lstat(filePathArg);
+  } catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw errorArg;
+  }
+};
+
+const ensurePrivateDirectory = async (directoryArg: string): Promise<void> => {
+  try {
+    await plugins.fs.promises.mkdir(directoryArg, { mode: 0o700 });
+  } catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
+  }
+  await assertPrivateDirectory(directoryArg);
+};
+
+const syncDirectory = async (directoryArg: string): Promise<void> => {
+  const handle = await plugins.fs.promises.open(directoryArg, plugins.fs.constants.O_RDONLY);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+};
+
+const writePrivateJson = async (
+  filePathArg: string,
+  valueArg: unknown,
+  exclusiveArg = true,
+): Promise<void> => {
+  const flags = plugins.fs.constants.O_WRONLY
+    | plugins.fs.constants.O_CREAT
+    | plugins.fs.constants.O_NOFOLLOW
+    | (exclusiveArg ? plugins.fs.constants.O_EXCL : plugins.fs.constants.O_TRUNC);
+  const handle = await plugins.fs.promises.open(filePathArg, flags, 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(valueArg)}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(plugins.path.dirname(filePathArg));
+};
+
+const readPrivateJson = async (filePathArg: string): Promise<unknown> => {
+  const handle = await plugins.fs.promises.open(
+    filePathArg,
+    plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW,
+  );
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.size < 2 || stats.size > maximumMetadataBytes) {
+      throw new Error(`Upgrade coordination metadata is not a bounded regular file: ${filePathArg}`);
+    }
+    if (typeof process.getuid === 'function' && stats.uid !== process.getuid()) {
+      throw new Error(`Upgrade coordination metadata is not owned by the current user: ${filePathArg}`);
+    }
+    if ((stats.mode & 0o077) !== 0) {
+      throw new Error(`Upgrade coordination metadata is not private: ${filePathArg}`);
+    }
+    try {
+      return JSON.parse(await handle.readFile('utf8')) as unknown;
+    } catch (errorArg) {
+      const error = new Error(`Upgrade coordination metadata is malformed: ${filePathArg}`, {
+        cause: errorArg,
+      }) as NodeJS.ErrnoException;
+      error.code = 'HCON_INVALID_JSON';
+      throw error;
+    }
+  } finally {
+    await handle.close();
+  }
+};
+
+const parseOwner = (valueArg: unknown): IUpgradeProcessOwner => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('Upgrade owner metadata is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (!exactKeys(value, [
+    'version',
+    'kind',
+    'uid',
+    'tokenHash',
+    'pid',
+    'processGroupId',
+    'fingerprint',
+    'cliPath',
+    'command',
+    'createdAt',
+  ])) {
+    throw new Error('Upgrade owner metadata has unexpected fields.');
+  }
+  if (
+    value.version !== coordinationVersion
+    || (value.kind !== 'upgrade' && value.kind !== 'start')
+    || !Number.isSafeInteger(value.uid)
+    || (value.uid as number) < 0
+    || !Number.isSafeInteger(value.pid)
+    || (value.pid as number) < 2
+    || !Number.isSafeInteger(value.processGroupId)
+    || (value.processGroupId as number) < 2
+    || !Number.isSafeInteger(value.createdAt)
+    || (value.createdAt as number) < 1
+    || typeof value.fingerprint !== 'string'
+    || value.fingerprint.length < 8
+    || value.fingerprint.length > 256
+    || typeof value.cliPath !== 'string'
+    || !plugins.path.isAbsolute(value.cliPath)
+    || (value.command !== '__serve'
+      && value.command !== '__upgrade-worker'
+      && value.command !== 'start'
+      && value.command !== 'upgrade'
+      && value.command !== 'foreground'
+      && value.command !== 'temp-password')
+  ) {
+    throw new Error('Upgrade owner metadata is invalid.');
+  }
+  if (typeof value.tokenHash !== 'string' || !upgradeTokenHashPattern.test(value.tokenHash)) {
+    throw new Error('Upgrade owner metadata token binding is invalid.');
+  }
+  if (
+    (value.kind === 'upgrade'
+      && value.command !== '__serve'
+      && value.command !== '__upgrade-worker'
+      && value.command !== 'upgrade')
+    || (value.kind === 'start' && value.command === '__upgrade-worker')
+  ) {
+    throw new Error('Upgrade owner metadata kind and command do not match.');
+  }
+  return value as unknown as IUpgradeProcessOwner;
+};
+
+const parseExpectedController = (valueArg: unknown): IUpgradeExpectedController => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('The expected controller identity is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (
+    !exactKeys(value, ['pid', 'processGroupId', 'processFingerprint'])
+    || !Number.isSafeInteger(value.pid)
+    || (value.pid as number) < 2
+    || !Number.isSafeInteger(value.processGroupId)
+    || (value.processGroupId as number) < 2
+    || typeof value.processFingerprint !== 'string'
+    || value.processFingerprint.length < 8
+    || value.processFingerprint.length > 256
+  ) {
+    throw new Error('The expected controller identity is invalid.');
+  }
+  return value as unknown as IUpgradeExpectedController;
+};
+
+const assertBoundedText = (valueArg: unknown, nameArg: string, maximumBytesArg: number): string => {
+  if (
+    typeof valueArg !== 'string'
+    || valueArg.length === 0
+    || Buffer.byteLength(valueArg, 'utf8') > maximumBytesArg
+  ) {
+    throw new Error(`${nameArg} is invalid.`);
+  }
+  return valueArg;
+};
+
+const assertRuntimeId = (valueArg: unknown): IControllerRuntimeId => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('The upgrade session identity is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (
+    !exactKeys(value, ['harnessId', 'nativeId'])
+    || (value.harnessId !== 'opencode' && value.harnessId !== 'flex')
+  ) throw new Error('The upgrade session identity is invalid.');
+  return {
+    harnessId: value.harnessId,
+    nativeId: assertBoundedText(value.nativeId, 'The upgrade native session ID', 512),
+  };
+};
+
+const sessionTransitionStates: ReadonlySet<string> = new Set([
+  'pending',
+  'submitting',
+  'accepted',
+  'paused',
+  'outcomeUnknown',
+  'failed',
+]);
+
+const parseUpgradeSessionState = (valueArg: unknown): IUpgradeSessionState => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('Upgrade session state is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (!exactKeys(value, [
+    'projectId',
+    'sessionId',
+    'pauseState',
+    ...(value.pauseQueueId === undefined ? [] : ['pauseQueueId']),
+    ...(value.cleanupState === undefined ? [] : ['cleanupState']),
+    ...(value.continueState === undefined ? [] : ['continueState']),
+    ...(value.error === undefined ? [] : ['error']),
+  ])) throw new Error('Upgrade session state has unexpected fields.');
+  if (
+    typeof value.pauseState !== 'string'
+    || !sessionTransitionStates.has(value.pauseState)
+    || (value.cleanupState !== undefined && (
+      typeof value.cleanupState !== 'string' || !sessionTransitionStates.has(value.cleanupState)
+    ))
+    || (value.continueState !== undefined && (
+      typeof value.continueState !== 'string' || !sessionTransitionStates.has(value.continueState)
+    ))
+  ) throw new Error('Upgrade session transition state is invalid.');
+  const sessionId = assertRuntimeId(value.sessionId);
+  if (value.pauseQueueId !== undefined && sessionId.harnessId !== 'flex') {
+    throw new Error('Only Flex upgrade sessions may retain a pause queue ID.');
+  }
+  return {
+    projectId: assertBoundedText(value.projectId, 'The upgrade project ID', 512),
+    sessionId,
+    pauseState: value.pauseState as TUpgradeSessionTransitionState,
+    ...(value.pauseQueueId === undefined
+      ? {}
+      : { pauseQueueId: assertBoundedText(value.pauseQueueId, 'The Flex pause queue ID', 512) }),
+    ...(value.cleanupState === undefined
+      ? {}
+      : { cleanupState: value.cleanupState as TUpgradeSessionTransitionState }),
+    ...(value.continueState === undefined
+      ? {}
+      : { continueState: value.continueState as TUpgradeSessionTransitionState }),
+    ...(value.error === undefined
+      ? {}
+      : { error: assertBoundedText(value.error, 'The upgrade session error', 2_048) }),
+  };
+};
+
+const transactionPhases: ReadonlySet<string> = new Set([
+  'starting',
+  'checking',
+  'preparing',
+  'pausing',
+  'stopping',
+  'installing',
+  'restarting',
+  'continuing',
+  'completed',
+  'failed',
+]);
+
+const transactionPhaseOrder: Record<TUpgradeTransaction['phase'], number> = {
+  starting: 0,
+  checking: 1,
+  preparing: 2,
+  pausing: 3,
+  stopping: 4,
+  installing: 5,
+  restarting: 6,
+  continuing: 7,
+  completed: 8,
+  failed: 8,
+};
+
+const parseUpgradeTransactionV2 = (valueArg: unknown): IUpgradeTransactionV2 => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('Upgrade transaction metadata is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (!exactKeys(value, [
+    'version', 'tokenHash', 'revision', 'port', 'sourceVersion', 'controllerWasRunning',
+    'continueSessions', 'gracePeriodMs', 'phase', 'message', 'createdAt', 'updatedAt',
+    'phaseStartedAt', 'sessions',
+    ...(value.targetVersion === undefined ? [] : ['targetVersion']),
+    ...(value.targetStartupInvoked === undefined ? [] : ['targetStartupInvoked']),
+    ...(value.preparationAcceptedAt === undefined ? [] : ['preparationAcceptedAt']),
+    ...(value.preparationDeadlineAt === undefined ? [] : ['preparationDeadlineAt']),
+    ...(value.preparationCompletedAt === undefined ? [] : ['preparationCompletedAt']),
+    ...(value.retainedUntil === undefined ? [] : ['retainedUntil']),
+    ...(value.worker === undefined ? [] : ['worker']),
+    ...(value.controller === undefined ? [] : ['controller']),
+    ...(value.terminal === undefined ? [] : ['terminal']),
+  ])) throw new Error('Upgrade transaction metadata has unexpected fields.');
+  if (
+    value.version !== coordinationVersion
+    || typeof value.tokenHash !== 'string'
+    || !upgradeTokenHashPattern.test(value.tokenHash)
+    || !Number.isSafeInteger(value.revision)
+    || (value.revision as number) < 0
+    || typeof value.controllerWasRunning !== 'boolean'
+    || (value.targetStartupInvoked !== undefined && value.targetStartupInvoked !== true)
+    || typeof value.continueSessions !== 'boolean'
+    || !Number.isSafeInteger(value.gracePeriodMs)
+    || (value.gracePeriodMs as number) < 1_000
+    || (value.gracePeriodMs as number) > 60 * 60 * 1000
+    || ((value.preparationAcceptedAt === undefined)
+      !== (value.preparationDeadlineAt === undefined))
+    || (value.preparationAcceptedAt !== undefined && (
+      !Number.isSafeInteger(value.preparationAcceptedAt)
+      || (value.preparationAcceptedAt as number) < (value.createdAt as number)
+      || (value.preparationAcceptedAt as number) > (value.updatedAt as number)
+      || !Number.isSafeInteger(value.preparationDeadlineAt)
+      || (value.preparationDeadlineAt as number)
+        !== (value.preparationAcceptedAt as number) + (value.gracePeriodMs as number)
+    ))
+    || (value.preparationCompletedAt !== undefined && (
+      value.preparationAcceptedAt === undefined
+      || !Number.isSafeInteger(value.preparationCompletedAt)
+      || (value.preparationCompletedAt as number) < (value.preparationAcceptedAt as number)
+      || (value.preparationCompletedAt as number) > (value.preparationDeadlineAt as number)
+      || typeof value.phase !== 'string'
+      || (transactionPhaseOrder[value.phase as TUpgradeTransaction['phase']] ?? -1)
+        < transactionPhaseOrder.stopping
+    ))
+    || typeof value.phase !== 'string'
+    || !transactionPhases.has(value.phase)
+    || !Number.isSafeInteger(value.createdAt)
+    || (value.createdAt as number) < 1
+    || !Number.isSafeInteger(value.updatedAt)
+    || (value.updatedAt as number) < (value.createdAt as number)
+    || !Number.isSafeInteger(value.phaseStartedAt)
+    || (value.phaseStartedAt as number) < (value.createdAt as number)
+    || (value.phaseStartedAt as number) > (value.updatedAt as number)
+    || (value.retainedUntil !== undefined && (
+      !Number.isSafeInteger(value.retainedUntil)
+      || (value.retainedUntil as number) < (value.updatedAt as number)
+    ))
+    || !Array.isArray(value.sessions)
+    || value.sessions.length > 64
+  ) throw new Error('Upgrade transaction metadata is invalid.');
+  let worker: IUpgradeTransactionV2['worker'];
+  if (value.worker !== undefined) {
+    if (!value.worker || typeof value.worker !== 'object' || Array.isArray(value.worker)) {
+      throw new Error('Upgrade worker metadata is malformed.');
+    }
+    const rawWorker = value.worker as Record<string, unknown>;
+    if (
+      !exactKeys(rawWorker, [
+        'pid', 'processGroupId', 'fingerprint', 'cliPath',
+        ...(rawWorker.logFilePath === undefined ? [] : ['logFilePath']),
+      ])
+      || !Number.isSafeInteger(rawWorker.pid)
+      || (rawWorker.pid as number) < 2
+      || !Number.isSafeInteger(rawWorker.processGroupId)
+      || (rawWorker.processGroupId as number) < 2
+      || typeof rawWorker.cliPath !== 'string'
+      || !plugins.path.isAbsolute(rawWorker.cliPath)
+    ) throw new Error('Upgrade worker metadata is invalid.');
+    worker = {
+      pid: rawWorker.pid as number,
+      processGroupId: rawWorker.processGroupId as number,
+      fingerprint: assertBoundedText(rawWorker.fingerprint, 'The upgrade worker fingerprint', 256),
+      cliPath: rawWorker.cliPath,
+      ...(rawWorker.logFilePath === undefined
+        ? {}
+        : {
+            logFilePath: assertBoundedText(
+              rawWorker.logFilePath,
+              'The upgrade worker log path',
+              4_096,
+            ),
+          }),
+    };
+  }
+  let terminal: IUpgradeTransactionV2['terminal'];
+  if (value.terminal !== undefined) {
+    if (!value.terminal || typeof value.terminal !== 'object' || Array.isArray(value.terminal)) {
+      throw new Error('Upgrade terminal metadata is malformed.');
+    }
+    const rawTerminal = value.terminal as Record<string, unknown>;
+    if (
+      !exactKeys(rawTerminal, ['success', ...(rawTerminal.error === undefined ? [] : ['error'])])
+      || typeof rawTerminal.success !== 'boolean'
+    ) throw new Error('Upgrade terminal metadata is invalid.');
+    terminal = {
+      success: rawTerminal.success,
+      ...(rawTerminal.error === undefined
+        ? {}
+        : { error: assertBoundedText(rawTerminal.error, 'The upgrade terminal error', 4_096) }),
+    };
+  }
+  let controller: IUpgradeTransactionV2['controller'];
+  if (value.controller !== undefined) {
+    if (!value.controller || typeof value.controller !== 'object' || Array.isArray(value.controller)) {
+      throw new Error('Upgrade controller metadata is malformed.');
+    }
+    const rawController = value.controller as Record<string, unknown>;
+    if (
+      !exactKeys(rawController, [
+        'pid', 'processGroupId', 'fingerprint', 'cliPath', 'command',
+      ])
+      || !Number.isSafeInteger(rawController.pid)
+      || (rawController.pid as number) < 2
+      || !Number.isSafeInteger(rawController.processGroupId)
+      || (rawController.processGroupId as number) < 2
+      || typeof rawController.cliPath !== 'string'
+      || !plugins.path.isAbsolute(rawController.cliPath)
+      || (rawController.command !== '__serve' && rawController.command !== 'foreground')
+    ) throw new Error('Upgrade controller metadata is invalid.');
+    controller = {
+      pid: rawController.pid as number,
+      processGroupId: rawController.processGroupId as number,
+      fingerprint: assertBoundedText(
+        rawController.fingerprint,
+        'The upgrade controller fingerprint',
+        256,
+      ),
+      cliPath: rawController.cliPath,
+      command: rawController.command,
+    };
+  }
+  return {
+    version: coordinationVersion,
+    tokenHash: value.tokenHash,
+    revision: value.revision as number,
+    port: assertPort(value.port),
+    sourceVersion: assertBoundedText(value.sourceVersion, 'The upgrade source version', 128),
+    ...(value.targetVersion === undefined
+      ? {}
+      : { targetVersion: assertBoundedText(value.targetVersion, 'The upgrade target version', 128) }),
+    ...(value.targetStartupInvoked === true ? { targetStartupInvoked: true } : {}),
+    controllerWasRunning: value.controllerWasRunning,
+    continueSessions: value.continueSessions,
+    gracePeriodMs: value.gracePeriodMs as number,
+    ...(value.preparationAcceptedAt === undefined
+      ? {}
+      : {
+          preparationAcceptedAt: value.preparationAcceptedAt as number,
+          preparationDeadlineAt: value.preparationDeadlineAt as number,
+        }),
+    ...(value.preparationCompletedAt === undefined
+      ? {}
+      : { preparationCompletedAt: value.preparationCompletedAt as number }),
+    phase: value.phase as TUpgradeTransaction['phase'],
+    message: assertBoundedText(value.message, 'The upgrade transaction message', 4_096),
+    createdAt: value.createdAt as number,
+    phaseStartedAt: value.phaseStartedAt as number,
+    updatedAt: value.updatedAt as number,
+    ...(value.retainedUntil === undefined
+      ? {}
+      : { retainedUntil: value.retainedUntil as number }),
+    ...(worker ? { worker } : {}),
+    ...(controller ? { controller } : {}),
+    sessions: value.sessions.map(parseUpgradeSessionState),
+    ...(terminal ? { terminal } : {}),
+  };
+};
+
+const parseUpgradeTransactionV3 = (valueArg: unknown): IUpgradeTransactionV3 => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('Upgrade transaction metadata is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (!exactKeys(value, [
+    'version', 'tokenHash', 'revision', 'port',
+    'sourcePackageName', 'sourceVersion', 'sourceManagementVersion',
+    'sourceCliName', 'sourceCliRelativePath',
+    'targetPackageName', 'targetVersion', 'targetManagementVersion',
+    'targetCliName', 'targetCliRelativePath',
+    'controllerWasRunning', 'continueSessions', 'gracePeriodMs', 'phase', 'message',
+    'createdAt', 'updatedAt', 'phaseStartedAt', 'sessions',
+    ...(value.packageTransitionStarted === undefined ? [] : ['packageTransitionStarted']),
+    ...(value.groupedTargetVerified === undefined ? [] : ['groupedTargetVerified']),
+    ...(value.targetPackageCommitStarted === undefined ? [] : ['targetPackageCommitStarted']),
+    ...(value.targetPackageCommitted === undefined ? [] : ['targetPackageCommitted']),
+    ...(value.targetStartupInvoked === undefined ? [] : ['targetStartupInvoked']),
+    ...(value.preparationAcceptedAt === undefined ? [] : ['preparationAcceptedAt']),
+    ...(value.preparationDeadlineAt === undefined ? [] : ['preparationDeadlineAt']),
+    ...(value.preparationCompletedAt === undefined ? [] : ['preparationCompletedAt']),
+    ...(value.retainedUntil === undefined ? [] : ['retainedUntil']),
+    ...(value.worker === undefined ? [] : ['worker']),
+    ...(value.controller === undefined ? [] : ['controller']),
+    ...(value.terminal === undefined ? [] : ['terminal']),
+  ])) throw new Error('Upgrade transaction metadata has unexpected fields.');
+  if (
+    value.version !== upgradePackageTransitionTransactionVersion
+    || value.sourcePackageName !== upgradePackageTransitionSource.packageName
+    || value.sourceVersion !== upgradePackageTransitionSource.version
+    || value.sourceManagementVersion !== upgradePackageTransitionSource.managementVersion
+    || value.sourceCliName !== upgradePackageTransitionSource.cliName
+    || value.sourceCliRelativePath !== upgradePackageTransitionSource.cliRelativePath
+    || value.targetPackageName !== upgradePackageTransitionTarget.packageName
+    || value.targetVersion !== upgradePackageTransitionTarget.version
+    || value.targetManagementVersion !== upgradePackageTransitionTarget.managementVersion
+    || value.targetCliName !== upgradePackageTransitionTarget.cliName
+    || value.targetCliRelativePath !== upgradePackageTransitionTarget.cliRelativePath
+    || (value.packageTransitionStarted !== undefined && value.packageTransitionStarted !== true)
+    || (value.groupedTargetVerified !== undefined && value.groupedTargetVerified !== true)
+    || (value.targetPackageCommitStarted !== undefined
+      && value.targetPackageCommitStarted !== true)
+    || (value.targetPackageCommitted !== undefined && value.targetPackageCommitted !== true)
+    || (value.targetStartupInvoked !== undefined && value.targetStartupInvoked !== true)
+  ) throw new Error('Upgrade package-transition identity or checkpoint metadata is invalid.');
+  if (
+    (value.groupedTargetVerified === true && value.packageTransitionStarted !== true)
+    || (value.targetPackageCommitStarted === true && value.groupedTargetVerified !== true)
+    || (value.targetPackageCommitted === true && value.targetPackageCommitStarted !== true)
+    || (value.targetStartupInvoked === true && value.targetPackageCommitted !== true)
+    || (value.targetStartupInvoked === true && value.controllerWasRunning !== true)
+  ) throw new Error('Upgrade package-transition checkpoints violate their implication chain.');
+
+  const compatible = parseUpgradeTransactionV2({
+    version: coordinationVersion,
+    tokenHash: value.tokenHash,
+    revision: value.revision,
+    port: value.port,
+    sourceVersion: value.sourceVersion,
+    targetVersion: value.targetVersion,
+    ...(value.targetStartupInvoked === true ? { targetStartupInvoked: true } : {}),
+    controllerWasRunning: value.controllerWasRunning,
+    continueSessions: value.continueSessions,
+    gracePeriodMs: value.gracePeriodMs,
+    ...(value.preparationAcceptedAt === undefined
+      ? {}
+      : {
+          preparationAcceptedAt: value.preparationAcceptedAt,
+          preparationDeadlineAt: value.preparationDeadlineAt,
+        }),
+    ...(value.preparationCompletedAt === undefined
+      ? {}
+      : { preparationCompletedAt: value.preparationCompletedAt }),
+    phase: value.phase,
+    message: value.message,
+    createdAt: value.createdAt,
+    phaseStartedAt: value.phaseStartedAt,
+    updatedAt: value.updatedAt,
+    ...(value.retainedUntil === undefined ? {} : { retainedUntil: value.retainedUntil }),
+    ...(value.worker === undefined ? {} : { worker: value.worker }),
+    ...(value.controller === undefined ? {} : { controller: value.controller }),
+    sessions: value.sessions,
+    ...(value.terminal === undefined ? {} : { terminal: value.terminal }),
+  });
+  if (
+    compatible.terminal?.success === true
+    && (
+      value.targetPackageCommitted !== true
+      || (compatible.controllerWasRunning && value.targetStartupInvoked !== true)
+      || (!compatible.controllerWasRunning && value.targetStartupInvoked === true)
+    )
+  ) throw new Error('A successful package transition is missing its terminal checkpoint.');
+  return {
+    ...compatible,
+    version: upgradePackageTransitionTransactionVersion,
+    sourcePackageName: upgradePackageTransitionSource.packageName,
+    sourceVersion: upgradePackageTransitionSource.version,
+    sourceManagementVersion: upgradePackageTransitionSource.managementVersion,
+    sourceCliName: upgradePackageTransitionSource.cliName,
+    sourceCliRelativePath: upgradePackageTransitionSource.cliRelativePath,
+    targetPackageName: upgradePackageTransitionTarget.packageName,
+    targetVersion: upgradePackageTransitionTarget.version,
+    targetManagementVersion: upgradePackageTransitionTarget.managementVersion,
+    targetCliName: upgradePackageTransitionTarget.cliName,
+    targetCliRelativePath: upgradePackageTransitionTarget.cliRelativePath,
+    ...(value.packageTransitionStarted === true ? { packageTransitionStarted: true } : {}),
+    ...(value.groupedTargetVerified === true ? { groupedTargetVerified: true } : {}),
+    ...(value.targetPackageCommitStarted === true ? { targetPackageCommitStarted: true } : {}),
+    ...(value.targetPackageCommitted === true ? { targetPackageCommitted: true } : {}),
+    ...(value.targetStartupInvoked === true ? { targetStartupInvoked: true } : {}),
+  };
+};
+
+const parseUpgradeTransaction = (valueArg: unknown): TUpgradeTransaction => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('Upgrade transaction metadata is malformed.');
+  }
+  return (valueArg as Record<string, unknown>).version === coordinationVersion
+    ? parseUpgradeTransactionV2(valueArg)
+    : parseUpgradeTransactionV3(valueArg);
+};
+
+const parseTransactionMutationOwner = (valueArg: unknown): IUpgradeTransactionMutationOwner => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('The upgrade transaction mutation owner is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (
+    !exactKeys(value, [
+      'version', 'uid', 'tokenHash', 'pid', 'fingerprint', 'nonce', 'createdAt',
+    ])
+    || value.version !== coordinationVersion
+    || !Number.isSafeInteger(value.uid)
+    || (value.uid as number) < 0
+    || typeof value.tokenHash !== 'string'
+    || !upgradeTokenHashPattern.test(value.tokenHash)
+    || !Number.isSafeInteger(value.pid)
+    || (value.pid as number) < 2
+    || typeof value.nonce !== 'string'
+    || !/^[a-f0-9]{32}$/.test(value.nonce)
+    || !Number.isSafeInteger(value.createdAt)
+    || (value.createdAt as number) < 1
+  ) throw new Error('The upgrade transaction mutation owner is invalid.');
+  return {
+    version: coordinationVersion,
+    uid: value.uid as number,
+    tokenHash: value.tokenHash,
+    pid: value.pid as number,
+    fingerprint: assertBoundedText(
+      value.fingerprint,
+      'The upgrade transaction mutation fingerprint',
+      256,
+    ),
+    nonce: value.nonce,
+    createdAt: value.createdAt as number,
+  };
+};
+
+const parseOwnershipMutationGuardOwner = (
+  valueArg: unknown,
+): IUpgradeOwnershipMutationGuardOwner => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('The upgrade ownership mutation guard is malformed.');
+  }
+  const value = valueArg as Record<string, unknown>;
+  if (
+    !exactKeys(value, [
+      'version', 'uid', 'targetHash', 'pid', 'fingerprint', 'nonce', 'createdAt',
+    ])
+    || value.version !== coordinationVersion
+    || !Number.isSafeInteger(value.uid)
+    || (value.uid as number) < 0
+    || typeof value.targetHash !== 'string'
+    || !upgradeTokenHashPattern.test(value.targetHash)
+    || !Number.isSafeInteger(value.pid)
+    || (value.pid as number) < 2
+    || typeof value.nonce !== 'string'
+    || !/^[a-f0-9]{32}$/.test(value.nonce)
+    || !Number.isSafeInteger(value.createdAt)
+    || (value.createdAt as number) < 1
+  ) throw new Error('The upgrade ownership mutation guard is invalid.');
+  return {
+    version: coordinationVersion,
+    uid: value.uid as number,
+    targetHash: value.targetHash,
+    pid: value.pid as number,
+    fingerprint: assertBoundedText(
+      value.fingerprint,
+      'The upgrade ownership mutation guard fingerprint',
+      256,
+    ),
+    nonce: value.nonce,
+    createdAt: value.createdAt as number,
+  };
+};
+
+export const upgradeTransactionIsStalled = (
+  transactionArg: TUpgradeTransaction,
+  nowArg = Date.now(),
+): boolean => {
+  if (transactionArg.terminal) return false;
+  if (
+    transactionArg.preparationDeadlineAt !== undefined
+    && transactionArg.preparationCompletedAt === undefined
+    && (transactionArg.phase === 'preparing' || transactionArg.phase === 'pausing')
+  ) return nowArg > transactionArg.preparationDeadlineAt + 60_000;
+  const maximumPhaseDurationMs: Record<TUpgradeTransaction['phase'], number> = {
+    starting: 2 * 60 * 1000,
+    checking: 3 * 60 * 1000,
+    preparing: transactionArg.gracePeriodMs + 60_000,
+    pausing: transactionArg.gracePeriodMs + 60_000,
+    stopping: 90_000,
+    installing: 22 * 60 * 1000,
+    restarting: 3 * 60 * 1000,
+    continuing: 2 * 60 * 1000,
+    completed: Number.MAX_SAFE_INTEGER,
+    failed: Number.MAX_SAFE_INTEGER,
+  };
+  return nowArg - transactionArg.phaseStartedAt > maximumPhaseDurationMs[transactionArg.phase];
+};
+
+const ownerIsLive = async (ownerArg: IUpgradeProcessOwner): Promise<boolean> => {
+  if (ownerArg.uid !== assertUid()) return false;
+  const identity = await readControllerProcessIdentity(ownerArg.pid);
+  if (identity && identity.fingerprint === ownerArg.fingerprint) {
+    return await processIdentityHasCliCommand(
+      identity,
+      ownerArg.cliPath,
+      ownerArg.command,
+      { allowMissingAbsolutePath: true },
+    );
+  }
+  if (ownerArg.kind !== 'upgrade' || ownerArg.processGroupId !== ownerArg.pid) return false;
+  return (await readProcessGroupMemberPids(ownerArg.processGroupId))
+    .some((processIdArg) => processIdArg !== ownerArg.pid);
+};
+
+const ownerForCurrentProcess = async (
+  kindArg: TUpgradeOwnerKind,
+  tokenArg: string,
+  cliPathArg: string,
+  commandArg: IUpgradeProcessOwner['command'],
+): Promise<IUpgradeProcessOwner> => {
+  const identity = await readControllerProcessIdentity(process.pid);
+  if (!identity) throw new Error('Unable to establish upgrade process ownership.');
+  return {
+    version: coordinationVersion,
+    kind: kindArg,
+    uid: assertUid(),
+    tokenHash: hashToken(tokenArg),
+    pid: process.pid,
+    processGroupId: identity.processGroupId,
+    fingerprint: identity.fingerprint,
+    cliPath: cliPathArg,
+    command: commandArg,
+    createdAt: Date.now(),
+  };
+};
+
+const coordinationPathHash = (valueArg: string): string => plugins.crypto
+  .createHash('sha256')
+  .update(valueArg)
+  .digest('hex')
+  .slice(0, 20);
+
+const ownershipTargetHash = (valueArg: string): string => plugins.crypto
+  .createHash('sha256')
+  .update(valueArg)
+  .digest('hex');
+
+interface IOwnedDirectoryRemovalExpectation {
+  identity: { dev: number; ino: number };
+  assertOwner?: (valueArg: unknown) => void;
+  assertRemovalAuthorized?: () => void;
+}
+
+const sameOwnedDirectoryIdentity = (
+  statsArg: plugins.fs.Stats,
+  identityArg: IOwnedDirectoryRemovalExpectation['identity'],
+): boolean => statsArg.dev === identityArg.dev && statsArg.ino === identityArg.ino;
+
+const exactPrimitiveRecordMatches = (leftArg: object, rightArg: object): boolean => {
+  const left = leftArg as Record<string, unknown>;
+  const right = rightArg as Record<string, unknown>;
+  const keys = Object.keys(left);
+  return exactKeys(right, keys) && keys.every((keyArg) => left[keyArg] === right[keyArg]);
+};
+
+const removeExactOwnedDirectory = async (
+  directoryArg: string,
+  expectationArg: IOwnedDirectoryRemovalExpectation,
+): Promise<void> => {
+  const initialStats = await plugins.fs.promises.lstat(directoryArg);
+  if (!sameOwnedDirectoryIdentity(initialStats, expectationArg.identity)) {
+    throw new Error('Upgrade coordination ownership changed before removal.');
+  }
+  const entries = await plugins.fs.promises.readdir(directoryArg, { withFileTypes: true });
+  if (
+    entries.length > 1
+    || entries.some((entryArg) => (
+      entryArg.name !== ownerFileName
+      || !entryArg.isFile()
+      || entryArg.isSymbolicLink()
+    ))
+  ) throw new Error(`Upgrade coordination owner directory contains unsafe entries: ${directoryArg}`);
+  if (Boolean(entries.length) !== Boolean(expectationArg.assertOwner)) {
+    throw new Error('Upgrade coordination ownership changed before removal.');
+  }
+  if (entries.length === 1) {
+    const ownerPath = plugins.path.join(directoryArg, ownerFileName);
+    const tombstonePath = plugins.path.join(
+      directoryArg,
+      `.owner-removing-${process.pid}-${plugins.crypto.randomBytes(8).toString('hex')}`,
+    );
+    expectationArg.assertRemovalAuthorized?.();
+    await plugins.fs.promises.rename(ownerPath, tombstonePath);
+    try {
+      expectationArg.assertOwner!(await readPrivateJson(tombstonePath));
+    } catch (errorArg) {
+      let restoreError: unknown;
+      try {
+        await plugins.fs.promises.link(tombstonePath, ownerPath);
+        await plugins.fs.promises.unlink(tombstonePath);
+        await syncDirectory(directoryArg);
+      } catch (restoreErrorArg) {
+        restoreError = restoreErrorArg;
+      }
+      if (restoreError !== undefined) {
+        throw new AggregateError(
+          [errorArg, restoreError],
+          'Upgrade coordination ownership changed and could not be restored safely.',
+        );
+      }
+      throw errorArg;
+    }
+    await plugins.fs.promises.unlink(tombstonePath);
+    await syncDirectory(directoryArg);
+  }
+  const currentStats = await lstatIfPresent(directoryArg);
+  if (!currentStats || !sameOwnedDirectoryIdentity(currentStats, expectationArg.identity)) return;
+  try {
+    await plugins.fs.promises.rmdir(directoryArg);
+  } catch (errorArg) {
+    const code = (errorArg as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return;
+    if (code === 'ENOTEMPTY' || code === 'EEXIST') {
+      throw new Error('Upgrade coordination ownership changed during removal.', {
+        cause: errorArg,
+      });
+    }
+    throw errorArg;
+  }
+  await syncDirectory(plugins.path.dirname(directoryArg));
+};
+
+class UpgradeOwnershipMutationGuard {
+  private released = false;
+  private releaseTask?: Promise<void>;
+
+  constructor(
+    public readonly directory: string,
+    public readonly owner: IUpgradeOwnershipMutationGuardOwner,
+  ) {}
+
+  public release(): Promise<void> {
+    if (this.released) return Promise.resolve();
+    if (!this.releaseTask) {
+      let task: Promise<void>;
+      task = (async () => {
+        const stats = await plugins.fs.promises.lstat(this.directory);
+        const owner = parseOwnershipMutationGuardOwner(await readPrivateJson(
+          plugins.path.join(this.directory, ownerFileName),
+        ));
+        if (!exactPrimitiveRecordMatches(owner, this.owner)) {
+          throw new Error('Upgrade ownership mutation guard changed unexpectedly.');
+        }
+        await removeExactOwnedDirectory(this.directory, {
+          identity: { dev: stats.dev, ino: stats.ino },
+          assertOwner: (valueArg) => {
+            const removedOwner = parseOwnershipMutationGuardOwner(valueArg);
+            if (!exactPrimitiveRecordMatches(removedOwner, this.owner)) {
+              throw new Error('Upgrade ownership mutation guard changed during release.');
+            }
+          },
+        });
+        this.released = true;
+      })().finally(() => {
+        if (this.releaseTask === task && !this.released) this.releaseTask = undefined;
+      });
+      this.releaseTask = task;
+    }
+    return this.releaseTask;
+  }
+}
+
+class UpgradeOwnedDirectory {
+  private released = false;
+  private releaseTask?: Promise<void>;
+
+  constructor(
+    public readonly directory: string,
+    public readonly owner: IUpgradeProcessOwner,
+    private readonly releaseOwned: (
+      directoryArg: string,
+      ownerArg: IUpgradeProcessOwner,
+      shouldReleaseArg?: () => boolean,
+    ) => Promise<void>,
+  ) {}
+
+  public async assertOwned(): Promise<void> {
+    if (this.released) throw new Error('Upgrade coordination ownership has already been released.');
+    let owner: IUpgradeProcessOwner;
+    try {
+      owner = parseOwner(await readPrivateJson(plugins.path.join(this.directory, ownerFileName)));
+    } catch (errorArg) {
+      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new Error('Upgrade coordination ownership changed unexpectedly.', { cause: errorArg });
+      }
+      throw errorArg;
+    }
+    if (!exactPrimitiveRecordMatches(owner, this.owner) || !await ownerIsLive(owner)) {
+      throw new Error('Upgrade coordination ownership changed unexpectedly.');
+    }
+  }
+
+  public release(shouldReleaseArg?: () => boolean): Promise<void> {
+    if (this.released) return Promise.resolve();
+    if (!this.releaseTask) {
+      let task: Promise<void>;
+      task = this.releaseOwned(this.directory, this.owner, shouldReleaseArg).then(() => {
+        this.released = true;
+      }).finally(() => {
+        if (this.releaseTask === task && !this.released) this.releaseTask = undefined;
+      });
+      this.releaseTask = task;
+    }
+    return this.releaseTask;
+  }
+
+  public relinquishAfterTransfer(): void {
+    if (this.released) throw new Error('Upgrade coordination ownership has already been released.');
+    this.released = true;
+  }
+}
+
+export class UpgradeInstallationLock extends UpgradeOwnedDirectory {}
+export class UpgradeStartLease extends UpgradeOwnedDirectory {}
+
+export class UpgradeCoordinator {
+  public readonly uid: number;
+  public readonly baseDirectory: string;
+  public readonly upgradeLockDirectory: string;
+  public readonly startLeasesDirectory: string;
+  public readonly transactionsDirectory: string;
+  public readonly ownershipGuardsDirectory: string;
+  private initializationTask?: Promise<void>;
+
+  constructor(public readonly canonicalGlobalRoot: string) {
+    if (!plugins.path.isAbsolute(canonicalGlobalRoot)) {
+      throw new Error('The canonical pnpm global root must be absolute.');
+    }
+    this.uid = assertUid();
+    this.baseDirectory = plugins.path.join(
+      '/tmp',
+      `harness-controller-upgrade-${this.uid}-${coordinationPathHash(canonicalGlobalRoot)}`,
+    );
+    this.upgradeLockDirectory = plugins.path.join(this.baseDirectory, 'upgrade.lock');
+    this.startLeasesDirectory = plugins.path.join(this.baseDirectory, 'start-leases');
+    this.transactionsDirectory = plugins.path.join(this.baseDirectory, 'transactions');
+    this.ownershipGuardsDirectory = plugins.path.join(this.baseDirectory, 'ownership-guards');
+  }
+
+  public async init(): Promise<void> {
+    if (!this.initializationTask) {
+      let task: Promise<void>;
+      task = this.performInitialization().catch((errorArg) => {
+        if (this.initializationTask === task) this.initializationTask = undefined;
+        throw errorArg;
+      });
+      this.initializationTask = task;
+    }
+    await this.initializationTask;
+  }
+
+  private async performInitialization(): Promise<void> {
+    await ensurePrivateDirectory(this.baseDirectory);
+    await ensurePrivateDirectory(this.startLeasesDirectory);
+    await ensurePrivateDirectory(this.transactionsDirectory);
+    await ensurePrivateDirectory(this.ownershipGuardsDirectory);
+    for (const entry of await plugins.fs.promises.readdir(this.ownershipGuardsDirectory, {
+      withFileTypes: true,
+    })) {
+      const guardPath = plugins.path.join(this.ownershipGuardsDirectory, entry.name);
+      if (!entry.isDirectory() || !ownershipGuardDirectoryPattern.test(entry.name)) {
+        throw new Error(`Upgrade ownership guard directory contains an unexpected entry: ${guardPath}`);
+      }
+      await assertPrivateDirectory(guardPath);
+    }
+    const entries = await plugins.fs.promises.readdir(this.baseDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !tokenMetadataPattern.test(entry.name)) continue;
+      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 coordination metadata is unsafe: ${filePath}`);
+      }
+      if (Date.now() - stats.mtimeMs > tokenMetadataRetentionMs) {
+        await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
+          if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+        });
+      }
+    }
+    for (const entry of await plugins.fs.promises.readdir(this.transactionsDirectory, {
+      withFileTypes: true,
+    })) {
+      const filePath = plugins.path.join(this.transactionsDirectory, entry.name);
+      if (entry.isFile() && transactionTemporaryMetadataPattern.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 temporary metadata 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.isDirectory() && transactionMutationDirectoryPattern.test(entry.name)) {
+        const stats = await lstatIfPresent(filePath);
+        if (!stats) continue;
+        if (
+          !stats.isDirectory()
+          || stats.isSymbolicLink()
+          || stats.uid !== this.uid
+          || (stats.mode & 0o077) !== 0
+        ) throw new Error(`Upgrade transaction mutation metadata is unsafe: ${filePath}`);
+        if (Date.now() - stats.mtimeMs > transactionRetentionMs) {
+          await this.reclaimStaleTransactionMutationDirectory(filePath);
+        }
+        continue;
+      }
+      if (!entry.isFile() || !transactionMetadataPattern.test(entry.name)) continue;
+      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 || (!workerIsLive && !controllerIsLive)) {
+          await plugins.fs.promises.unlink(filePath).catch((errorArg) => {
+            if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+          });
+        }
+      }
+    }
+  }
+
+  private ownershipGuardDirectory(directoryArg: string): string {
+    return plugins.path.join(
+      this.ownershipGuardsDirectory,
+      `${ownershipTargetHash(directoryArg)}.guard`,
+    );
+  }
+
+  private async acquireOwnershipMutationGuard(
+    directoryArg: string,
+  ): Promise<UpgradeOwnershipMutationGuard> {
+    const targetHash = ownershipTargetHash(directoryArg);
+    const guardDirectory = this.ownershipGuardDirectory(directoryArg);
+    const identity = await readControllerProcessIdentity(process.pid);
+    if (!identity) throw new Error('Unable to establish upgrade ownership mutation guard identity.');
+    const owner: IUpgradeOwnershipMutationGuardOwner = {
+      version: coordinationVersion,
+      uid: this.uid,
+      targetHash,
+      pid: identity.pid,
+      fingerprint: identity.fingerprint,
+      nonce: plugins.crypto.randomBytes(16).toString('hex'),
+      createdAt: Date.now(),
+    };
+    const deadline = Date.now() + ownershipGuardTimeoutMs;
+    while (true) {
+      try {
+        await plugins.fs.promises.mkdir(guardDirectory, { mode: 0o700 });
+        try {
+          await writePrivateJson(plugins.path.join(guardDirectory, ownerFileName), owner);
+          await syncDirectory(this.ownershipGuardsDirectory);
+        } catch (errorArg) {
+          // A partially initialized guard is deliberately fail-closed. It must
+          // never be reclaimed automatically, or the guard would repeat the
+          // fixed-path ownership race that it exists to prevent.
+          throw errorArg;
+        }
+        return new UpgradeOwnershipMutationGuard(guardDirectory, owner);
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
+      }
+
+      const stats = await lstatIfPresent(guardDirectory);
+      if (!stats) continue;
+      if (
+        !stats.isDirectory()
+        || stats.isSymbolicLink()
+        || stats.uid !== this.uid
+        || (stats.mode & 0o077) !== 0
+      ) throw new Error(`Upgrade ownership mutation guard is unsafe: ${guardDirectory}`);
+
+      let existingOwner: IUpgradeOwnershipMutationGuardOwner;
+      try {
+        existingOwner = parseOwnershipMutationGuardOwner(await readPrivateJson(
+          plugins.path.join(guardDirectory, ownerFileName),
+        ));
+      } catch (errorArg) {
+        const refreshedStats = await lstatIfPresent(guardDirectory);
+        if (!refreshedStats || refreshedStats.dev !== stats.dev || refreshedStats.ino !== stats.ino) {
+          continue;
+        }
+        if (
+          Date.now() - refreshedStats.mtimeMs < initializationGraceMs
+          && Date.now() < deadline
+        ) {
+          await new Promise((resolve) => setTimeout(resolve, 25));
+          continue;
+        }
+        throw new Error(
+          `Upgrade ownership mutation guard is incomplete and cannot be reclaimed automatically: ${guardDirectory}. Inspect it after proving its owner is gone, or reboot the host to clear /tmp.`,
+          { cause: errorArg },
+        );
+      }
+      if (existingOwner.uid !== this.uid || existingOwner.targetHash !== targetHash) {
+        throw new Error(`Upgrade ownership mutation guard binding is invalid: ${guardDirectory}`);
+      }
+      let existingIdentity: Awaited<ReturnType<typeof readControllerProcessIdentity>>;
+      try {
+        existingIdentity = await readControllerProcessIdentity(existingOwner.pid);
+      } catch (errorArg) {
+        throw new Error(
+          `The existing upgrade ownership mutation guard cannot be verified safely: ${guardDirectory}`,
+          { cause: errorArg },
+        );
+      }
+      if (existingIdentity?.fingerprint !== existingOwner.fingerprint) {
+        throw new Error(
+          `Upgrade ownership mutation guard is stale and cannot be reclaimed automatically: ${guardDirectory}. Inspect it after proving its owner is gone, or reboot the host to clear /tmp.`,
+        );
+      }
+      if (Date.now() >= deadline) {
+        throw new Error('Timed out waiting for an upgrade ownership mutation guard.');
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+
+  private async withOwnershipMutationGuard<T>(
+    directoryArg: string,
+    operationArg: () => Promise<T>,
+  ): Promise<T> {
+    const guard = await this.acquireOwnershipMutationGuard(directoryArg);
+    let result: T | undefined;
+    let operationError: unknown;
+    try {
+      result = await operationArg();
+    } catch (errorArg) {
+      operationError = errorArg;
+    }
+    let releaseError: unknown;
+    try {
+      await guard.release();
+    } catch (errorArg) {
+      releaseError = errorArg;
+    }
+    if (operationError !== undefined && releaseError !== undefined) {
+      throw new AggregateError(
+        [operationError, releaseError],
+        'Upgrade ownership mutation failed and its guard could not be released.',
+      );
+    }
+    if (operationError !== undefined) throw operationError;
+    if (releaseError !== undefined) throw releaseError;
+    return result as T;
+  }
+
+  private async reclaimStaleOwnedDirectory(directoryArg: string): Promise<boolean> {
+    return await this.withOwnershipMutationGuard(directoryArg, async () => {
+      const current = await this.inspectOwnedDirectory(directoryArg);
+      if (current.state === 'absent') return false;
+      if (current.state === 'indeterminate') {
+        throw new Error(`The existing ${currentCliName} ownership cannot be verified safely.`);
+      }
+      if (current.state !== 'stale') return false;
+      await removeExactOwnedDirectory(directoryArg, {
+        identity: current.identity!,
+        ...(current.owner
+          ? {
+              assertOwner: (valueArg: unknown) => {
+                const removedOwner = parseOwner(valueArg);
+                if (!exactPrimitiveRecordMatches(removedOwner, current.owner!)) {
+                  throw new Error('Upgrade coordination ownership changed during stale removal.');
+                }
+              },
+            }
+          : {}),
+      });
+      return true;
+    });
+  }
+
+  private async releaseOwnedDirectory(
+    directoryArg: string,
+    expectedOwnerArg: IUpgradeProcessOwner,
+    shouldReleaseArg?: () => boolean,
+  ): Promise<void> {
+    await this.withOwnershipMutationGuard(directoryArg, async () => {
+      const stats = await plugins.fs.promises.lstat(directoryArg);
+      let currentOwner: IUpgradeProcessOwner;
+      try {
+        currentOwner = parseOwner(await readPrivateJson(
+          plugins.path.join(directoryArg, ownerFileName),
+        ));
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') {
+          throw new Error('Upgrade coordination ownership changed unexpectedly.', { cause: errorArg });
+        }
+        throw errorArg;
+      }
+      if (!exactPrimitiveRecordMatches(currentOwner, expectedOwnerArg)) {
+        throw new Error('Upgrade coordination ownership changed unexpectedly.');
+      }
+      await removeExactOwnedDirectory(directoryArg, {
+        identity: { dev: stats.dev, ino: stats.ino },
+        ...(shouldReleaseArg
+          ? {
+              assertRemovalAuthorized: () => {
+                if (!shouldReleaseArg()) {
+                  throw new Error('Upgrade coordination release is no longer authorized.');
+                }
+              },
+            }
+          : {}),
+        assertOwner: (valueArg) => {
+          const removedOwner = parseOwner(valueArg);
+          if (!exactPrimitiveRecordMatches(removedOwner, expectedOwnerArg)) {
+            throw new Error('Upgrade coordination ownership changed during release.');
+          }
+        },
+      });
+    });
+  }
+
+  private async inspectTransactionMutationDirectory(
+    directoryArg: string,
+    expectedTokenHashArg?: string,
+  ): Promise<{
+    state: 'absent' | 'live' | 'recent-invalid' | 'stale' | 'indeterminate';
+    identity?: { dev: number; ino: number };
+    owner?: IUpgradeTransactionMutationOwner;
+  }> {
+    const stats = await lstatIfPresent(directoryArg);
+    if (!stats) return { state: 'absent' };
+    if (
+      !stats.isDirectory()
+      || stats.isSymbolicLink()
+      || stats.uid !== this.uid
+      || (stats.mode & 0o077) !== 0
+    ) throw new Error('The upgrade transaction mutation lock is unsafe.');
+    let rawOwner: unknown;
+    try {
+      rawOwner = await readPrivateJson(plugins.path.join(directoryArg, ownerFileName));
+    } catch (errorArg) {
+      const code = (errorArg as NodeJS.ErrnoException).code;
+      if (code === 'HCON_INVALID_JSON') {
+        return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
+      }
+      if (code !== 'ENOENT') throw errorArg;
+      return {
+        state: Date.now() - stats.mtimeMs < initializationGraceMs
+          ? 'recent-invalid'
+          : 'stale',
+        identity: { dev: stats.dev, ino: stats.ino },
+      };
+    }
+    let owner: IUpgradeTransactionMutationOwner;
+    try {
+      owner = parseTransactionMutationOwner(rawOwner);
+    } catch {
+      return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
+    }
+    if (
+      owner.uid !== this.uid
+      || (expectedTokenHashArg !== undefined
+        && !tokensEqual(owner.tokenHash, expectedTokenHashArg))
+    ) throw new Error('The upgrade transaction mutation lock binding is invalid.');
+    try {
+      const ownerIdentity = await readControllerProcessIdentity(owner.pid);
+      return {
+        state: ownerIdentity?.fingerprint === owner.fingerprint ? 'live' : 'stale',
+        identity: { dev: stats.dev, ino: stats.ino },
+        owner,
+      };
+    } catch {
+      return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
+    }
+  }
+
+  private async reclaimStaleTransactionMutationDirectory(
+    directoryArg: string,
+    expectedTokenHashArg?: string,
+  ): Promise<boolean> {
+    return await this.withOwnershipMutationGuard(directoryArg, async () => {
+      const current = await this.inspectTransactionMutationDirectory(
+        directoryArg,
+        expectedTokenHashArg,
+      );
+      if (current.state === 'absent') return false;
+      if (current.state === 'indeterminate') {
+        throw new Error('The upgrade transaction mutation owner cannot be verified safely.');
+      }
+      if (current.state !== 'stale') return false;
+      await removeExactOwnedDirectory(directoryArg, {
+        identity: current.identity!,
+        ...(current.owner
+          ? {
+              assertOwner: (valueArg: unknown) => {
+                const removedOwner = parseTransactionMutationOwner(valueArg);
+                if (!exactPrimitiveRecordMatches(removedOwner, current.owner!)) {
+                  throw new Error(
+                    'The upgrade transaction mutation owner changed during stale removal.',
+                  );
+                }
+              },
+            }
+          : {}),
+      });
+      return true;
+    });
+  }
+
+  private async inspectOwnedDirectory(
+    directoryArg: string,
+  ): Promise<{
+    state: 'absent' | 'live' | 'recent-invalid' | 'stale' | 'indeterminate';
+    identity?: { dev: number; ino: number };
+    owner?: IUpgradeProcessOwner;
+  }> {
+    let stats: plugins.fs.Stats;
+    try {
+      stats = await plugins.fs.promises.lstat(directoryArg);
+    } catch (errorArg) {
+      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return { state: 'absent' };
+      throw errorArg;
+    }
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      throw new Error(`Upgrade coordination owner path is unsafe: ${directoryArg}`);
+    }
+    if (stats.uid !== this.uid || (stats.mode & 0o077) !== 0) {
+      throw new Error(`Upgrade coordination owner path is not private: ${directoryArg}`);
+    }
+    let ownerValue: unknown;
+    try {
+      ownerValue = await readPrivateJson(plugins.path.join(directoryArg, ownerFileName));
+    } catch (errorArg) {
+      const code = (errorArg as NodeJS.ErrnoException).code;
+      if (code === 'HCON_INVALID_JSON') {
+        return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
+      }
+      if (code !== 'ENOENT') throw errorArg;
+      return {
+        state: Date.now() - stats.mtimeMs < initializationGraceMs
+          ? 'recent-invalid'
+          : 'stale',
+        identity: { dev: stats.dev, ino: stats.ino },
+      };
+    }
+    let owner: IUpgradeProcessOwner;
+    try {
+      owner = parseOwner(ownerValue);
+    } catch {
+      return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
+    }
+    try {
+      return {
+        state: await ownerIsLive(owner) ? 'live' : 'stale',
+        identity: { dev: stats.dev, ino: stats.ino },
+        owner,
+      };
+    } catch {
+      return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
+    }
+  }
+
+  private async createOwnedDirectory(
+    directoryArg: string,
+    ownerArg: IUpgradeProcessOwner,
+  ): Promise<{ directory: string; owner: IUpgradeProcessOwner } | undefined> {
+    return await this.withOwnershipMutationGuard(directoryArg, async () => {
+      try {
+        await plugins.fs.promises.mkdir(directoryArg, { mode: 0o700 });
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code === 'EEXIST') return undefined;
+        throw errorArg;
+      }
+      try {
+        await writePrivateJson(plugins.path.join(directoryArg, ownerFileName), ownerArg);
+        await syncDirectory(plugins.path.dirname(directoryArg));
+        return { directory: directoryArg, owner: ownerArg };
+      } catch (errorArg) {
+        // Preserve a failed initialization directory. Contenders treat it as
+        // recent-invalid, then reclaim it only after the bounded grace period.
+        throw errorArg;
+      }
+    });
+  }
+
+  public async acquireUpgradeLock(optionsArg: {
+    token: string;
+    cliPath: string;
+    command?: '__serve' | '__upgrade-worker' | 'upgrade' | 'foreground';
+  }): Promise<UpgradeInstallationLock> {
+    await this.init();
+    const owner = await ownerForCurrentProcess(
+      'upgrade',
+      optionsArg.token,
+      optionsArg.cliPath,
+      optionsArg.command ?? '__upgrade-worker',
+    );
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const created = await this.createOwnedDirectory(this.upgradeLockDirectory, owner);
+      if (created) return new UpgradeInstallationLock(
+        created.directory,
+        created.owner,
+        (directoryArg, ownerArg, shouldReleaseArg) => this.releaseOwnedDirectory(
+          directoryArg,
+          ownerArg,
+          shouldReleaseArg,
+        ),
+      );
+      const state = await this.inspectOwnedDirectory(this.upgradeLockDirectory);
+      if (state.state === 'live') {
+        let currentOwner: IUpgradeProcessOwner;
+        try {
+          currentOwner = parseOwner(await readPrivateJson(
+            plugins.path.join(this.upgradeLockDirectory, ownerFileName),
+          ));
+        } catch (errorArg) {
+          if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') continue;
+          throw errorArg;
+        }
+        if (
+          currentOwner.pid === owner.pid
+          && currentOwner.fingerprint === owner.fingerprint
+          && tokensEqual(currentOwner.tokenHash, owner.tokenHash)
+        ) return new UpgradeInstallationLock(
+          this.upgradeLockDirectory,
+          currentOwner,
+          (directoryArg, ownerArg, shouldReleaseArg) => this.releaseOwnedDirectory(
+            directoryArg,
+            ownerArg,
+            shouldReleaseArg,
+          ),
+        );
+        throw new Error(`Another ${currentCliName} upgrade is already running.`);
+      }
+      if (state.state === 'recent-invalid') {
+        throw new Error(`Another ${currentCliName} upgrade is initializing; retry shortly.`);
+      }
+      if (state.state === 'stale') {
+        await this.reclaimStaleOwnedDirectory(this.upgradeLockDirectory);
+      }
+      if (state.state === 'indeterminate') {
+        throw new Error(`The existing ${currentCliName} upgrade owner cannot be verified safely.`);
+      }
+    }
+    throw new Error(`Unable to acquire exclusive ${currentCliName} upgrade ownership.`);
+  }
+
+  public async transferUpgradeLockToWorker(optionsArg: {
+    lock: UpgradeInstallationLock;
+    token: string;
+    worker: NonNullable<TUpgradeTransaction['worker']>;
+  }): Promise<void> {
+    const identity = await readControllerProcessIdentity(optionsArg.worker.pid);
+    if (
+      !identity
+      || identity.fingerprint !== optionsArg.worker.fingerprint
+      || identity.processGroupId !== optionsArg.worker.processGroupId
+      || !identity.processGroupLeader
+      || !await processIdentityHasCliCommand(
+        identity,
+        optionsArg.worker.cliPath,
+        '__upgrade-worker',
+        { allowMissingAbsolutePath: true },
+      )
+    ) throw new Error('The upgrade lock transfer worker identity is invalid.');
+    const owner: IUpgradeProcessOwner = {
+      version: coordinationVersion,
+      kind: 'upgrade',
+      uid: this.uid,
+      tokenHash: hashToken(optionsArg.token),
+      pid: identity.pid,
+      processGroupId: identity.processGroupId,
+      fingerprint: identity.fingerprint,
+      cliPath: optionsArg.worker.cliPath,
+      command: '__upgrade-worker',
+      createdAt: Date.now(),
+    };
+    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')}`;
+      try {
+        await writePrivateJson(temporaryPath, owner);
+        await plugins.fs.promises.rename(temporaryPath, ownerPath);
+        await syncDirectory(this.upgradeLockDirectory);
+        optionsArg.lock.relinquishAfterTransfer();
+      } finally {
+        await plugins.fs.promises.unlink(temporaryPath).catch(() => undefined);
+      }
+    });
+  }
+
+  private async readLiveUpgradeOwner(): Promise<IUpgradeProcessOwner | undefined> {
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const state = await this.inspectOwnedDirectory(this.upgradeLockDirectory);
+      if (state.state === 'absent') return undefined;
+      if (state.state === 'recent-invalid') {
+        throw new Error(`An ${currentCliName} upgrade is initializing; retry shortly.`);
+      }
+      if (state.state === 'indeterminate') {
+        throw new Error(`The existing ${currentCliName} upgrade owner cannot be verified safely.`);
+      }
+      if (state.state === 'stale') {
+        await this.reclaimStaleOwnedDirectory(this.upgradeLockDirectory);
+        continue;
+      }
+      try {
+        return parseOwner(await readPrivateJson(
+          plugins.path.join(this.upgradeLockDirectory, ownerFileName),
+        ));
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+      }
+    }
+    throw new Error(`The ${currentCliName} upgrade owner changed repeatedly during admission.`);
+  }
+
+  public async acquireStartLease(optionsArg: {
+    token: string;
+    cliPath: string;
+    command: 'start' | 'foreground' | 'temp-password';
+    upgradeToken?: string;
+  }): Promise<UpgradeStartLease> {
+    await this.init();
+    const owner = await ownerForCurrentProcess(
+      'start',
+      optionsArg.token,
+      optionsArg.cliPath,
+      optionsArg.command,
+    );
+    const upgradeOwnerBefore = await this.readLiveUpgradeOwner();
+    const authorized = upgradeOwnerBefore !== undefined
+      && optionsArg.upgradeToken !== undefined
+      && tokensEqual(upgradeOwnerBefore.tokenHash, hashToken(optionsArg.upgradeToken));
+    if (upgradeOwnerBefore && !authorized) {
+      throw new Error(`${currentCliName} cannot start while a global upgrade is in progress.`);
+    }
+    const leaseDirectory = plugins.path.join(
+      this.startLeasesDirectory,
+      coordinationPathHash(assertToken(optionsArg.token)),
+    );
+    const created = await this.createOwnedDirectory(leaseDirectory, owner);
+    if (!created) throw new Error(`The ${currentCliName} start admission token is already in use.`);
+    const lease = new UpgradeStartLease(
+      created.directory,
+      created.owner,
+      (directoryArg, ownerArg, shouldReleaseArg) => this.releaseOwnedDirectory(
+        directoryArg,
+        ownerArg,
+        shouldReleaseArg,
+      ),
+    );
+    try {
+      const upgradeOwnerAfter = await this.readLiveUpgradeOwner();
+      if (upgradeOwnerAfter) {
+        const remainsAuthorized = optionsArg.upgradeToken !== undefined
+          && tokensEqual(upgradeOwnerAfter.tokenHash, hashToken(optionsArg.upgradeToken));
+        if (!remainsAuthorized) {
+          throw new Error(`${currentCliName} upgrade began while startup was entering admission.`);
+        }
+      }
+      return lease;
+    } catch (errorArg) {
+      await lease.release();
+      throw errorArg;
+    }
+  }
+
+  public async waitForStartLeasesToDrain(lockArg: UpgradeInstallationLock): Promise<void> {
+    const deadline = Date.now() + startLeaseDrainTimeoutMs;
+    while (Date.now() < deadline) {
+      await lockArg.assertOwned();
+      const entries = await plugins.fs.promises.readdir(this.startLeasesDirectory, {
+        withFileTypes: true,
+      });
+      let blocked = false;
+      for (const entry of entries) {
+        if (!entry.isDirectory() || !leaseDirectoryPattern.test(entry.name)) {
+          throw new Error(`The ${currentCliName} start admission directory contains an unexpected entry.`);
+        }
+        const leaseDirectory = plugins.path.join(this.startLeasesDirectory, entry.name);
+        const state = await this.inspectOwnedDirectory(leaseDirectory);
+        if (state.state === 'live' || state.state === 'recent-invalid') {
+          blocked = true;
+          continue;
+        }
+        if (state.state === 'indeterminate') {
+          throw new Error(`An ${currentCliName} start admission owner cannot be verified safely.`);
+        }
+        if (state.state === 'stale') {
+          if (!await this.reclaimStaleOwnedDirectory(leaseDirectory)) blocked = true;
+        }
+      }
+      if (!blocked) return;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`Timed out waiting for an in-flight ${currentCliName} start to finish.`);
+  }
+
+  private tokenFilePath(kindArg: 'grant' | 'ack', tokenArg: string): string {
+    return plugins.path.join(
+      this.baseDirectory,
+      `${kindArg}-${coordinationPathHash(assertToken(tokenArg))}.json`,
+    );
+  }
+
+  private transactionFilePath(tokenArg: string): string {
+    return plugins.path.join(
+      this.transactionsDirectory,
+      `transaction-${coordinationPathHash(assertToken(tokenArg))}.json`,
+    );
+  }
+
+  private transactionMutationDirectory(tokenArg: string): string {
+    return `${this.transactionFilePath(tokenArg)}.lock`;
+  }
+
+  private async withTransactionMutation<T>(
+    tokenArg: string,
+    operationArg: () => Promise<T>,
+  ): Promise<T> {
+    await this.init();
+    const lockDirectory = this.transactionMutationDirectory(tokenArg);
+    const deadline = Date.now() + transactionMutationTimeoutMs;
+    const identity = await readControllerProcessIdentity(process.pid);
+    if (!identity) throw new Error('Unable to establish transaction mutation ownership.');
+    const owner: IUpgradeTransactionMutationOwner = {
+      version: coordinationVersion,
+      uid: this.uid,
+      tokenHash: hashToken(tokenArg),
+      pid: identity.pid,
+      fingerprint: identity.fingerprint,
+      nonce: plugins.crypto.randomBytes(16).toString('hex'),
+      createdAt: Date.now(),
+    };
+    while (true) {
+      try {
+        await plugins.fs.promises.mkdir(lockDirectory, { mode: 0o700 });
+        try {
+          await writePrivateJson(plugins.path.join(lockDirectory, ownerFileName), owner);
+        } catch (errorArg) {
+          // Leave partial initialization for the next contender's bounded stale check.
+          throw errorArg;
+        }
+        break;
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
+        const current = await this.inspectTransactionMutationDirectory(
+          lockDirectory,
+          owner.tokenHash,
+        );
+        if (current.state === 'absent') continue;
+        if (current.state === 'stale') {
+          await this.reclaimStaleTransactionMutationDirectory(
+            lockDirectory,
+            owner.tokenHash,
+          );
+          continue;
+        }
+        if (current.state === 'indeterminate') {
+          throw new Error('The upgrade transaction mutation owner cannot be verified safely.');
+        }
+        if (Date.now() >= deadline) {
+          throw new Error('Timed out waiting to update the upgrade transaction.');
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+    }
+    let result: T | undefined;
+    let operationError: unknown;
+    try {
+      result = await operationArg();
+    } catch (errorArg) {
+      operationError = errorArg;
+    }
+    let releaseError: unknown;
+    try {
+      await this.withOwnershipMutationGuard(lockDirectory, async () => {
+        const stats = await plugins.fs.promises.lstat(lockDirectory);
+        let currentOwner: IUpgradeTransactionMutationOwner;
+        try {
+          currentOwner = parseTransactionMutationOwner(await readPrivateJson(
+            plugins.path.join(lockDirectory, ownerFileName),
+          ));
+        } catch (errorArg) {
+          if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') {
+            throw new Error(
+              'The upgrade transaction mutation lock ownership changed unexpectedly.',
+              { cause: errorArg },
+            );
+          }
+          throw errorArg;
+        }
+        if (!exactPrimitiveRecordMatches(currentOwner, owner)) {
+          throw new Error('The upgrade transaction mutation lock ownership changed unexpectedly.');
+        }
+        await removeExactOwnedDirectory(lockDirectory, {
+          identity: { dev: stats.dev, ino: stats.ino },
+          assertOwner: (valueArg) => {
+            const removedOwner = parseTransactionMutationOwner(valueArg);
+            if (!exactPrimitiveRecordMatches(removedOwner, owner)) {
+              throw new Error(
+                'The upgrade transaction mutation lock ownership changed during release.',
+              );
+            }
+          },
+        });
+      });
+    } catch (errorArg) {
+      releaseError = errorArg;
+    }
+    if (operationError !== undefined && releaseError !== undefined) {
+      throw new AggregateError(
+        [operationError, releaseError],
+        'The upgrade transaction mutation failed and its ownership could not be released.',
+      );
+    }
+    if (operationError !== undefined) throw operationError;
+    if (releaseError !== undefined) throw releaseError;
+    return result as T;
+  }
+
+  public async createTransaction(optionsArg: {
+    token: string;
+    port: number;
+    sourceVersion: string;
+    controllerWasRunning: boolean;
+    continueSessions: boolean;
+    gracePeriodMs: number;
+  }): Promise<IUpgradeTransactionV2> {
+    await this.init();
+    const now = Date.now();
+    const transaction: IUpgradeTransactionV2 = {
+      version: coordinationVersion,
+      tokenHash: hashToken(optionsArg.token),
+      revision: 0,
+      port: assertPort(optionsArg.port),
+      sourceVersion: assertBoundedText(optionsArg.sourceVersion, 'The upgrade source version', 128),
+      controllerWasRunning: optionsArg.controllerWasRunning,
+      continueSessions: optionsArg.continueSessions,
+      gracePeriodMs: optionsArg.gracePeriodMs,
+      phase: 'starting',
+      message: 'Upgrade worker is starting.',
+      createdAt: now,
+      phaseStartedAt: now,
+      updatedAt: now,
+      sessions: [],
+    };
+    const validated = parseUpgradeTransactionV2(transaction);
+    await writePrivateJson(this.transactionFilePath(optionsArg.token), validated);
+    return validated;
+  }
+
+  public async createPackageTransitionTransaction(optionsArg: {
+    token: string;
+    port: number;
+    controllerWasRunning: boolean;
+    continueSessions: boolean;
+    gracePeriodMs: number;
+  }): Promise<IUpgradeTransactionV3> {
+    await this.init();
+    const now = Date.now();
+    const transaction: IUpgradeTransactionV3 = {
+      version: upgradePackageTransitionTransactionVersion,
+      tokenHash: hashToken(optionsArg.token),
+      revision: 0,
+      port: assertPort(optionsArg.port),
+      sourcePackageName: upgradePackageTransitionSource.packageName,
+      sourceVersion: upgradePackageTransitionSource.version,
+      sourceManagementVersion: upgradePackageTransitionSource.managementVersion,
+      sourceCliName: upgradePackageTransitionSource.cliName,
+      sourceCliRelativePath: upgradePackageTransitionSource.cliRelativePath,
+      targetPackageName: upgradePackageTransitionTarget.packageName,
+      targetVersion: upgradePackageTransitionTarget.version,
+      targetManagementVersion: upgradePackageTransitionTarget.managementVersion,
+      targetCliName: upgradePackageTransitionTarget.cliName,
+      targetCliRelativePath: upgradePackageTransitionTarget.cliRelativePath,
+      controllerWasRunning: optionsArg.controllerWasRunning,
+      continueSessions: optionsArg.continueSessions,
+      gracePeriodMs: optionsArg.gracePeriodMs,
+      phase: 'starting',
+      message: 'Upgrade worker is starting.',
+      createdAt: now,
+      phaseStartedAt: now,
+      updatedAt: now,
+      sessions: [],
+    };
+    const validated = parseUpgradeTransactionV3(transaction);
+    await writePrivateJson(this.transactionFilePath(optionsArg.token), validated);
+    return validated;
+  }
+
+  public async readTransaction(tokenArg: string): Promise<TUpgradeTransaction> {
+    await this.init();
+    const transaction = parseUpgradeTransaction(await readPrivateJson(
+      this.transactionFilePath(tokenArg),
+    ));
+    if (!tokensEqual(transaction.tokenHash, hashToken(tokenArg))) {
+      throw new Error('The upgrade transaction token binding is invalid.');
+    }
+    return transaction;
+  }
+
+  public async updateTransaction(
+    tokenArg: string,
+    expectedRevisionArg: number,
+    updateArg: (currentArg: TUpgradeTransaction) => TUpgradeTransaction,
+  ): Promise<TUpgradeTransaction> {
+    return await this.withTransactionMutation(tokenArg, async () => {
+      const current = await this.readTransaction(tokenArg);
+      if (current.revision !== expectedRevisionArg) {
+        throw new Error('The upgrade transaction changed concurrently.');
+      }
+      return await this.writeTransactionUpdate(tokenArg, current, updateArg(current));
+    });
+  }
+
+  public async mutateTransaction(
+    tokenArg: string,
+    updateArg: (currentArg: TUpgradeTransaction) => TUpgradeTransaction,
+  ): Promise<TUpgradeTransaction> {
+    return await this.withTransactionMutation(tokenArg, async () => {
+      const current = await this.readTransaction(tokenArg);
+      return await this.writeTransactionUpdate(tokenArg, current, updateArg(current));
+    });
+  }
+
+  private async writeTransactionUpdate(
+    tokenArg: string,
+    currentArg: TUpgradeTransaction,
+    updatedArg: TUpgradeTransaction,
+  ): Promise<TUpgradeTransaction> {
+    const updatedAt = Date.now();
+    const workerIdentityChanged = (
+      currentArg.worker?.pid !== updatedArg.worker?.pid
+      || currentArg.worker?.processGroupId !== updatedArg.worker?.processGroupId
+      || currentArg.worker?.fingerprint !== updatedArg.worker?.fingerprint
+      || currentArg.worker?.cliPath !== updatedArg.worker?.cliPath
+    );
+    const next = parseUpgradeTransaction({
+      ...updatedArg,
+      version: currentArg.version,
+      tokenHash: currentArg.tokenHash,
+      revision: currentArg.revision + 1,
+      createdAt: currentArg.createdAt,
+      phaseStartedAt: updatedArg.phase === currentArg.phase && !workerIdentityChanged
+        ? currentArg.phaseStartedAt
+        : updatedAt,
+      updatedAt,
+    });
+    if (transactionPhaseOrder[next.phase] < transactionPhaseOrder[currentArg.phase]) {
+      throw new Error('The upgrade transaction phase cannot regress.');
+    }
+    if (currentArg.version === upgradePackageTransitionTransactionVersion) {
+      if (next.version !== upgradePackageTransitionTransactionVersion) {
+        throw new Error('The upgrade transaction version cannot change.');
+      }
+      for (const checkpoint of [
+        'packageTransitionStarted',
+        'groupedTargetVerified',
+        'targetPackageCommitStarted',
+        'targetPackageCommitted',
+        'targetStartupInvoked',
+      ] as const) {
+        if (currentArg[checkpoint] === true && next[checkpoint] !== true) {
+          throw new Error(`The upgrade package-transition checkpoint ${checkpoint} cannot regress.`);
+        }
+      }
+    }
+    if (
+      (currentArg.preparationAcceptedAt !== undefined
+        && next.preparationAcceptedAt !== currentArg.preparationAcceptedAt)
+      || (currentArg.preparationDeadlineAt !== undefined
+        && next.preparationDeadlineAt !== currentArg.preparationDeadlineAt)
+      || (currentArg.preparationCompletedAt !== undefined
+        && next.preparationCompletedAt !== currentArg.preparationCompletedAt)
+      || (currentArg.preparationAcceptedAt === undefined
+        && currentArg.preparationDeadlineAt === undefined
+        && next.preparationCompletedAt !== undefined)
+    ) throw new Error('The upgrade preparation timeline cannot change after it is committed.');
+    const targetPath = this.transactionFilePath(tokenArg);
+    const temporaryPath = `${targetPath}.tmp-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}`;
+    try {
+      await writePrivateJson(temporaryPath, next);
+      await plugins.fs.promises.rename(temporaryPath, targetPath);
+      await syncDirectory(this.transactionsDirectory);
+    } finally {
+      await plugins.fs.promises.unlink(temporaryPath).catch(() => undefined);
+    }
+    return next;
+  }
+
+  public async registerWorker(tokenArg: string, cliPathArg: string): Promise<TUpgradeTransaction> {
+    const identity = await readControllerProcessIdentity(process.pid);
+    if (!identity) throw new Error('Unable to establish upgrade worker ownership.');
+    return await this.mutateTransaction(tokenArg, (current) => ({
+      ...current,
+      worker: {
+        pid: identity.pid,
+        processGroupId: identity.processGroupId,
+        fingerprint: identity.fingerprint,
+        cliPath: cliPathArg,
+        ...(current.worker?.logFilePath ? { logFilePath: current.worker.logFilePath } : {}),
+      },
+      phase: 'checking',
+      message: 'Checking the npm latest version.',
+    }));
+  }
+
+  public async recordWorkerLaunch(
+    tokenArg: string,
+    pidArg: number,
+    cliPathArg: string,
+    logFilePathArg: string,
+  ): Promise<TUpgradeTransaction> {
+    const identity = await readControllerProcessIdentity(pidArg);
+    if (
+      !identity
+      || !identity.processGroupLeader
+      || !await processIdentityHasCliCommand(
+        identity,
+        cliPathArg,
+        '__upgrade-worker',
+        { allowMissingAbsolutePath: true },
+      )
+    ) throw new Error('Unable to verify the launched upgrade worker identity.');
+    const logFilePath = assertBoundedText(logFilePathArg, 'The upgrade worker log path', 4_096);
+    if (!plugins.path.isAbsolute(logFilePath)) {
+      throw new Error('The upgrade worker log path must be absolute.');
+    }
+    return await this.mutateTransaction(tokenArg, (current) => ({
+      ...current,
+      worker: {
+        pid: identity.pid,
+        processGroupId: identity.processGroupId,
+        fingerprint: identity.fingerprint,
+        cliPath: cliPathArg,
+        logFilePath,
+      },
+    }));
+  }
+
+  public async recordController(
+    tokenArg: string,
+    controllerArg: TUpgradeTransaction['controller'],
+  ): Promise<TUpgradeTransaction> {
+    if (!controllerArg) throw new Error('The upgrade controller identity is required.');
+    const identity = await readControllerProcessIdentity(controllerArg.pid);
+    if (
+      !identity
+      || identity.fingerprint !== controllerArg.fingerprint
+      || identity.processGroupId !== controllerArg.processGroupId
+      || !await processIdentityHasCliCommand(
+        identity,
+        controllerArg.cliPath,
+        controllerArg.command,
+        { allowMissingAbsolutePath: true },
+      )
+    ) throw new Error('Unable to verify the upgrade controller identity.');
+    return await this.mutateTransaction(tokenArg, (current) => ({
+      ...current,
+      controller: { ...controllerArg },
+    }));
+  }
+
+  public async transactionControllerIsLive(transactionArg: TUpgradeTransaction): Promise<boolean> {
+    const controller = transactionArg.controller;
+    if (!controller) return false;
+    const identity = await readControllerProcessIdentity(controller.pid);
+    return Boolean(
+      identity?.fingerprint === controller.fingerprint
+      && identity.processGroupId === controller.processGroupId
+      && await processIdentityHasCliCommand(
+        identity,
+        controller.cliPath,
+        controller.command,
+        { allowMissingAbsolutePath: true },
+      )
+    );
+  }
+
+  public async transactionWorkerIsLive(transactionArg: TUpgradeTransaction): Promise<boolean> {
+    const worker = transactionArg.worker;
+    if (!worker) return false;
+    const identity = await readControllerProcessIdentity(worker.pid);
+    if (Boolean(
+      identity?.fingerprint === worker.fingerprint
+      && await processIdentityHasCliCommand(
+        identity,
+        worker.cliPath,
+        '__upgrade-worker',
+        { allowMissingAbsolutePath: true },
+      )
+    )) return true;
+    if (worker.processGroupId !== worker.pid) return false;
+    return (await readProcessGroupMemberPids(worker.processGroupId))
+      .some((processIdArg) => processIdArg !== worker.pid);
+  }
+
+  public async terminateTransactionWorker(
+    transactionArg: TUpgradeTransaction,
+  ): Promise<void> {
+    const worker = transactionArg.worker;
+    if (!worker) return;
+    await this.terminateUpgradeWorkerCandidate(worker);
+  }
+
+  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.');
+  }
+
+  public async readSanitizedUpgradeStatus(
+    tokenArg: string,
+  ): Promise<IControllerUpgradeStatus | undefined> {
+    const transaction = await this.readTransaction(tokenArg);
+    if (!transaction.targetVersion) return undefined;
+    if (transaction.retainedUntil !== undefined && transaction.retainedUntil < Date.now()) return undefined;
+    const phase = transaction.phase === 'starting'
+      || transaction.phase === 'checking'
+      || transaction.phase === 'stopping'
+      ? 'preparing'
+      : transaction.phase;
+    return {
+      fromVersion: transaction.sourceVersion,
+      toVersion: transaction.targetVersion,
+      phase,
+    };
+  }
+
+  public async finishTransaction(
+    tokenArg: string,
+    successArg: boolean,
+    messageArg: string,
+    errorArg?: string,
+  ): Promise<TUpgradeTransaction> {
+    return await this.mutateTransaction(tokenArg, (current) => {
+      if (current.terminal) return current;
+      return {
+        ...current,
+        phase: successArg ? 'completed' : 'failed',
+        message: assertBoundedText(messageArg, 'The upgrade terminal message', 4_096),
+        retainedUntil: Date.now() + terminalStatusRetentionMs,
+        terminal: {
+          success: successArg,
+          ...(errorArg === undefined
+            ? {}
+            : { error: assertBoundedText(errorArg, 'The upgrade terminal error', 4_096) }),
+        },
+      };
+    });
+  }
+
+  public async createLaunchGrant(optionsArg: {
+    token: string;
+    port: number;
+    packageName: string;
+    packageVersion: string;
+    cliPath: string;
+    controller: IUpgradeExpectedController;
+  }): Promise<void> {
+    await this.init();
+    if (
+      typeof optionsArg.packageName !== 'string'
+      || optionsArg.packageName.length < 1
+      || optionsArg.packageName.length > 256
+      || typeof optionsArg.packageVersion !== 'string'
+      || optionsArg.packageVersion.length < 1
+      || optionsArg.packageVersion.length > 128
+      || !plugins.path.isAbsolute(optionsArg.cliPath)
+    ) {
+      throw new Error(`The ${currentCliName} upgrade launch grant package binding is invalid.`);
+    }
+    const grant: IUpgradeLaunchGrant = {
+      version: coordinationVersion,
+      tokenHash: hashToken(optionsArg.token),
+      expiresAt: Date.now() + 30_000,
+      port: assertPort(optionsArg.port),
+      packageName: optionsArg.packageName,
+      packageVersion: optionsArg.packageVersion,
+      cliPath: optionsArg.cliPath,
+      controller: parseExpectedController(optionsArg.controller),
+    };
+    await writePrivateJson(this.tokenFilePath('grant', optionsArg.token), grant);
+  }
+
+  public async removeLaunchGrant(tokenArg: string): Promise<void> {
+    await plugins.fs.promises.unlink(this.tokenFilePath('grant', tokenArg)).catch((errorArg) => {
+      if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+    });
+    await syncDirectory(this.baseDirectory);
+  }
+
+  public async consumeLaunchGrant(optionsArg: {
+    token: string;
+    port: number;
+    packageName: string;
+    packageVersion: string;
+    cliPath: string;
+    controller: IUpgradeExpectedController;
+  }): Promise<void> {
+    await this.init();
+    const token = assertToken(optionsArg.token);
+    const grantPath = this.tokenFilePath('grant', token);
+    const consumedPath = `${grantPath}.consuming-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}`;
+    await plugins.fs.promises.rename(grantPath, consumedPath).catch((errorArg) => {
+      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new Error(`The ${currentCliName} upgrade launch grant is missing or already consumed.`);
+      }
+      throw errorArg;
+    });
+    try {
+      const value = await readPrivateJson(consumedPath);
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`The ${currentCliName} upgrade launch grant is malformed.`);
+      }
+      const grant = value as Record<string, unknown>;
+      if (!exactKeys(grant, [
+        'version',
+        'tokenHash',
+        'expiresAt',
+        'port',
+        'packageName',
+        'packageVersion',
+        'cliPath',
+        'controller',
+      ])) {
+        throw new Error(`The ${currentCliName} upgrade launch grant has unexpected fields.`);
+      }
+      const controller = parseExpectedController(grant.controller);
+      const expected = parseExpectedController(optionsArg.controller);
+      if (
+        grant.version !== coordinationVersion
+        || typeof grant.expiresAt !== 'number'
+        || !Number.isSafeInteger(grant.expiresAt)
+        || grant.expiresAt < Date.now()
+        || grant.port !== assertPort(optionsArg.port)
+        || grant.packageName !== optionsArg.packageName
+        || grant.packageVersion !== optionsArg.packageVersion
+        || grant.cliPath !== optionsArg.cliPath
+        || controller.pid !== expected.pid
+        || controller.processGroupId !== expected.processGroupId
+        || controller.processFingerprint !== expected.processFingerprint
+        || typeof grant.tokenHash !== 'string'
+        || !upgradeTokenHashPattern.test(grant.tokenHash)
+        || !tokensEqual(grant.tokenHash, hashToken(token))
+      ) {
+        throw new Error(`The ${currentCliName} upgrade launch grant binding is invalid or expired.`);
+      }
+    } finally {
+      await plugins.fs.promises.unlink(consumedPath).catch(() => undefined);
+      await syncDirectory(this.baseDirectory);
+    }
+  }
+
+  private actionGrantFilePath(actionArg: TUpgradeControllerAction, tokenArg: string): string {
+    return plugins.path.join(
+      this.baseDirectory,
+      `action-${actionArg}-${coordinationPathHash(assertToken(tokenArg))}.json`,
+    );
+  }
+
+  public async removeControllerActionGrant(
+    actionArg: TUpgradeControllerAction,
+    tokenArg: string,
+  ): Promise<void> {
+    await plugins.fs.promises.unlink(this.actionGrantFilePath(actionArg, tokenArg)).catch((errorArg) => {
+      if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+    });
+    await syncDirectory(this.baseDirectory);
+  }
+
+  public async createControllerActionGrant(optionsArg: {
+    token: string;
+    action: TUpgradeControllerAction;
+    mode?: 'continue' | 'compensate' | 'reopen';
+    packageVersion: string;
+    controller: IUpgradeExpectedController;
+  }): Promise<void> {
+    await this.init();
+    if (
+      (optionsArg.action === 'prepare' && optionsArg.mode !== undefined)
+      || (optionsArg.action === 'finalize' && optionsArg.mode === undefined)
+    ) throw new Error('The upgrade controller action mode is invalid.');
+    const grant: IUpgradeControllerActionGrant = {
+      version: coordinationVersion,
+      tokenHash: hashToken(optionsArg.token),
+      action: optionsArg.action,
+      ...(optionsArg.mode === undefined ? {} : { mode: optionsArg.mode }),
+      expiresAt: Date.now() + 30_000,
+      packageVersion: assertBoundedText(
+        optionsArg.packageVersion,
+        'The upgrade action package version',
+        128,
+      ),
+      controller: parseExpectedController(optionsArg.controller),
+    };
+    await writePrivateJson(
+      this.actionGrantFilePath(optionsArg.action, optionsArg.token),
+      grant,
+    );
+  }
+
+  public async consumeControllerActionGrant(optionsArg: {
+    token: string;
+    action: TUpgradeControllerAction;
+    mode?: 'continue' | 'compensate' | 'reopen';
+    packageVersion: string;
+    controller: IUpgradeExpectedController;
+  }): Promise<void> {
+    await this.init();
+    const grantPath = this.actionGrantFilePath(optionsArg.action, optionsArg.token);
+    const consumedPath = `${grantPath}.consuming-${process.pid}-${plugins.crypto.randomBytes(4).toString('hex')}`;
+    await plugins.fs.promises.rename(grantPath, consumedPath).catch((errorArg) => {
+      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new Error('The upgrade controller action grant is missing or already consumed.');
+      }
+      throw errorArg;
+    });
+    try {
+      const raw = await readPrivateJson(consumedPath);
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('The upgrade controller action grant is malformed.');
+      }
+      const grant = raw as Record<string, unknown>;
+      const expectedController = parseExpectedController(optionsArg.controller);
+      const controller = parseExpectedController(grant.controller);
+      if (
+        !exactKeys(grant, [
+          'version', 'tokenHash', 'action', 'expiresAt', 'packageVersion', 'controller',
+          ...(grant.mode === undefined ? [] : ['mode']),
+        ])
+        || grant.version !== coordinationVersion
+        || grant.action !== optionsArg.action
+        || grant.mode !== optionsArg.mode
+        || !Number.isSafeInteger(grant.expiresAt)
+        || (grant.expiresAt as number) < Date.now()
+        || grant.packageVersion !== optionsArg.packageVersion
+        || controller.pid !== expectedController.pid
+        || controller.processGroupId !== expectedController.processGroupId
+        || controller.processFingerprint !== expectedController.processFingerprint
+        || typeof grant.tokenHash !== 'string'
+        || !tokensEqual(grant.tokenHash, hashToken(optionsArg.token))
+      ) throw new Error('The upgrade controller action grant binding is invalid or expired.');
+    } finally {
+      await plugins.fs.promises.unlink(consumedPath).catch(() => undefined);
+      await syncDirectory(this.baseDirectory);
+    }
+  }
+
+  public async acknowledgeWorker(tokenArg: string): Promise<void> {
+    await this.init();
+    const acknowledgement = {
+      version: coordinationVersion,
+      tokenHash: hashToken(tokenArg),
+    };
+    const acknowledgementPath = this.tokenFilePath('ack', tokenArg);
+    try {
+      await writePrivateJson(acknowledgementPath, acknowledgement);
+    } 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.');
+    }
+  }
+
+  public async waitForWorkerAcknowledgement(
+    tokenArg: string,
+    timeoutMsArg = 10_000,
+  ): Promise<void> {
+    const token = assertToken(tokenArg);
+    const ackPath = this.tokenFilePath('ack', token);
+    const deadline = Date.now() + timeoutMsArg;
+    while (Date.now() < deadline) {
+      try {
+        const value = await readPrivateJson(ackPath);
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+          throw new Error(`The ${currentCliName} upgrade acknowledgement is malformed.`);
+        }
+        const ack = value as Record<string, unknown>;
+        if (
+          !exactKeys(ack, ['version', 'tokenHash'])
+          || ack.version !== coordinationVersion
+          || typeof ack.tokenHash !== 'string'
+          || !upgradeTokenHashPattern.test(ack.tokenHash)
+          || !tokensEqual(ack.tokenHash, hashToken(token))
+        ) {
+          throw new Error(`The ${currentCliName} upgrade acknowledgement binding is invalid.`);
+        }
+        await plugins.fs.promises.unlink(ackPath);
+        await syncDirectory(this.baseDirectory);
+        return;
+      } catch (errorArg) {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error(`The ${currentCliName} upgrade caller did not acknowledge the detached worker.`);
+  }
+}
+
+export const createUpgradeToken = (): string => plugins.crypto
+  .randomBytes(32)
+  .toString('base64url');
+
+export const serializeUpgradeWorkerPayload = (payloadArg: IUpgradeWorkerPayload): string => {
+  assertToken(payloadArg.token);
+  const payload = {
+    version: coordinationVersion,
+    port: assertPort(payloadArg.port),
+    gracePeriodMs: payloadArg.gracePeriodMs,
+    continueSessions: payloadArg.continueSessions,
+    ...(payloadArg.expectedController
+      ? { expectedController: parseExpectedController(payloadArg.expectedController) }
+      : {}),
+  };
+  return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+};
+
+export const parseUpgradeWorkerPayload = (
+  payloadArg: unknown,
+  tokenArg: unknown,
+): IUpgradeWorkerPayload => {
+  if (typeof payloadArg !== 'string' || payloadArg.length < 8 || payloadArg.length > 4096) {
+    throw new Error(`The ${currentCliName} upgrade worker payload is invalid.`);
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.from(payloadArg, 'base64url').toString('utf8')) as unknown;
+  } catch {
+    throw new Error(`The ${currentCliName} upgrade worker payload is malformed.`);
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`The ${currentCliName} upgrade worker payload is malformed.`);
+  }
+  const payload = value as Record<string, unknown>;
+  if (!exactKeys(payload, [
+    'version',
+    'port',
+    'gracePeriodMs',
+    'continueSessions',
+    ...(payload.expectedController === undefined ? [] : ['expectedController']),
+  ])) {
+    throw new Error(`The ${currentCliName} upgrade worker payload has unexpected fields.`);
+  }
+  if (payload.version !== coordinationVersion) {
+    throw new Error(`The ${currentCliName} upgrade worker payload version is unsupported.`);
+  }
+  return {
+    version: coordinationVersion,
+    token: assertToken(tokenArg),
+    port: assertPort(payload.port),
+    gracePeriodMs: (() => {
+      if (
+        !Number.isSafeInteger(payload.gracePeriodMs)
+        || (payload.gracePeriodMs as number) < 1_000
+        || (payload.gracePeriodMs as number) > 60 * 60 * 1000
+      ) throw new Error(`The ${currentCliName} upgrade grace period is invalid.`);
+      return payload.gracePeriodMs as number;
+    })(),
+    continueSessions: (() => {
+      if (typeof payload.continueSessions !== 'boolean') {
+        throw new Error(`The ${currentCliName} upgrade continuation option is invalid.`);
+      }
+      return payload.continueSessions;
+    })(),
+    ...(payload.expectedController
+      ? { expectedController: parseExpectedController(payload.expectedController) }
+      : {}),
+  };
+};