agl 21.0.2 → 22.0.0

package/ts/classes.upgradecoordinator.ts

@@ -9,6 +9,11 @@ import {
   readControllerProcessIdentity,
   readProcessGroupMemberPids,
 } from './classes.processinspection.js';
+import { resolveAGLHomePaths } from './classes.aglhome.js';
+import {
+  upgradeCoordinationRootEnvironmentVariable,
+  upgradeTokenEnvironmentVariable,
+} from './constants.upgradeenvironment.js';
 
 export const upgradeCoordinationVersion = 2 as const;
 const coordinationVersion = upgradeCoordinationVersion;
@@ -42,15 +47,17 @@ 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 ownershipGuardTemporaryPattern = /^[a-f0-9]{64}\.guard\.tmp-[1-9][0-9]*-[a-f0-9]{32}$/;
+const ownerRemovalPattern = /^\.owner-removing-([1-9][0-9]*)-([a-f0-9]{64})-([a-f0-9]{16})$/;
+const legacyOwnerRemovalPattern = /^\.owner-removing-([1-9][0-9]*)-([a-f0-9]{16})$/;
 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 legacyOwnerRemovalGraceMs = 30_000;
 const workerTerminationGraceMs = 5_000;
 
-export const upgradeTokenEnvironmentVariable = 'HARNESS_CONTROLLER_UPGRADE_TOKEN';
-
 type TUpgradeOwnerKind = 'upgrade' | 'start';
 
 interface IUpgradeProcessOwner {
@@ -207,6 +214,13 @@ interface IUpgradeOwnershipMutationGuardOwner {
   createdAt: number;
 }
 
+interface IUpgradeOwnershipMutationGuardState {
+  state: 'absent' | 'empty' | 'live' | 'stale';
+  identity?: { dev: number; ino: number };
+  owner?: IUpgradeOwnershipMutationGuardOwner;
+  ownerMetadata?: IOwnedDirectoryOwnerMetadata<IUpgradeOwnershipMutationGuardOwner>;
+}
+
 const assertUid = (): number => {
   if (typeof process.getuid !== 'function') {
     throw new Error(`${currentCliName} upgrade requires a POSIX effective user identity.`);
@@ -986,6 +1000,16 @@ interface IOwnedDirectoryRemovalExpectation {
   assertRemovalAuthorized?: () => void;
 }
 
+interface IOwnedDirectoryOwnerMetadata<TOwner> {
+  owner: TOwner;
+  shape: 'owner' | 'removing' | 'restoring';
+  tombstoneName?: string;
+  tombstoneIdentity?: { dev: number; ino: number };
+  tombstoneCtimeMs?: number;
+  removalPid?: number;
+  removalFingerprintHash?: string;
+}
+
 const sameOwnedDirectoryIdentity = (
   statsArg: plugins.fs.Stats,
   identityArg: IOwnedDirectoryRemovalExpectation['identity'],
@@ -998,6 +1022,114 @@ const exactPrimitiveRecordMatches = (leftArg: object, rightArg: object): boolean
   return exactKeys(right, keys) && keys.every((keyArg) => left[keyArg] === right[keyArg]);
 };
 
+const parseOwnerRemovalName = (nameArg: string): {
+  pid: number;
+  fingerprintHash?: string;
+} | undefined => {
+  const current = ownerRemovalPattern.exec(nameArg);
+  if (current) return { pid: Number(current[1]), fingerprintHash: current[2] };
+  const legacy = legacyOwnerRemovalPattern.exec(nameArg);
+  return legacy ? { pid: Number(legacy[1]) } : undefined;
+};
+
+const inspectOwnedDirectoryOwnerMetadata = async <TOwner>(
+  directoryArg: string,
+  parseOwnerArg: (valueArg: unknown) => TOwner,
+): Promise<IOwnedDirectoryOwnerMetadata<TOwner> | undefined> => {
+  const entries = await plugins.fs.promises.readdir(directoryArg, { withFileTypes: true });
+  if (entries.length === 0) return undefined;
+  if (entries.length > 2) {
+    throw new Error(`Upgrade coordination owner directory contains unsafe entries: ${directoryArg}`);
+  }
+  const ownerEntry = entries.find((entryArg) => entryArg.name === ownerFileName);
+  const tombstoneEntry = entries.find((entryArg) => parseOwnerRemovalName(entryArg.name));
+  if (
+    entries.some((entryArg) => entryArg !== ownerEntry && entryArg !== tombstoneEntry)
+    || !ownerEntry && !tombstoneEntry
+  ) throw new Error(`Upgrade coordination owner directory contains unsafe entries: ${directoryArg}`);
+  for (const entry of entries) {
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+      throw new Error(`Upgrade coordination owner metadata is unsafe: ${directoryArg}`);
+    }
+  }
+  const ownerPath = ownerEntry ? plugins.path.join(directoryArg, ownerFileName) : undefined;
+  const tombstonePath = tombstoneEntry
+    ? plugins.path.join(directoryArg, tombstoneEntry.name)
+    : undefined;
+  const [ownerStats, tombstoneStats] = await Promise.all([
+    ownerPath ? plugins.fs.promises.lstat(ownerPath) : undefined,
+    tombstonePath ? plugins.fs.promises.lstat(tombstonePath) : undefined,
+  ]);
+  for (const metadata of [ownerStats, tombstoneStats]) {
+    if (!metadata) continue;
+    if (
+      !metadata.isFile()
+      || metadata.isSymbolicLink()
+      || (typeof process.getuid === 'function' && metadata.uid !== process.getuid())
+      || (metadata.mode & 0o077) !== 0
+    ) throw new Error(`Upgrade coordination owner metadata is unsafe: ${directoryArg}`);
+  }
+  let shape: IOwnedDirectoryOwnerMetadata<TOwner>['shape'];
+  if (ownerStats && tombstoneStats) {
+    if (
+      ownerStats.dev !== tombstoneStats.dev
+      || ownerStats.ino !== tombstoneStats.ino
+      || ownerStats.nlink !== 2
+      || tombstoneStats.nlink !== 2
+    ) throw new Error(`Upgrade coordination owner restoration is invalid: ${directoryArg}`);
+    shape = 'restoring';
+  } else if (ownerStats) {
+    if (ownerStats.nlink !== 1) {
+      throw new Error(`Upgrade coordination owner link count is invalid: ${directoryArg}`);
+    }
+    shape = 'owner';
+  } else {
+    if (tombstoneStats!.nlink !== 1) {
+      throw new Error(`Upgrade coordination owner tombstone link count is invalid: ${directoryArg}`);
+    }
+    shape = 'removing';
+  }
+  return {
+    owner: parseOwnerArg(await readPrivateJson(ownerPath ?? tombstonePath!)),
+    shape,
+    ...(tombstoneEntry
+      ? (() => {
+          const removal = parseOwnerRemovalName(tombstoneEntry.name)!;
+          return {
+          tombstoneName: tombstoneEntry.name,
+          tombstoneIdentity: { dev: tombstoneStats!.dev, ino: tombstoneStats!.ino },
+            tombstoneCtimeMs: tombstoneStats!.ctimeMs,
+            removalPid: removal.pid,
+            ...(removal.fingerprintHash
+              ? { removalFingerprintHash: removal.fingerprintHash }
+              : {}),
+          };
+        })()
+      : {}),
+  };
+};
+
+const restoreOwnedDirectoryOwnerMetadata = async <TOwner>(
+  directoryArg: string,
+  metadataArg: IOwnedDirectoryOwnerMetadata<TOwner>,
+): Promise<void> => {
+  if (metadataArg.shape === 'owner') return;
+  const tombstonePath = plugins.path.join(directoryArg, metadataArg.tombstoneName!);
+  const tombstoneStats = await plugins.fs.promises.lstat(tombstonePath);
+  if (!sameOwnedDirectoryIdentity(tombstoneStats, metadataArg.tombstoneIdentity!)) {
+    throw new Error('Upgrade coordination owner tombstone changed during recovery.');
+  }
+  if (metadataArg.shape === 'restoring') {
+    await plugins.fs.promises.unlink(tombstonePath);
+  } else {
+    await plugins.fs.promises.rename(
+      tombstonePath,
+      plugins.path.join(directoryArg, ownerFileName),
+    );
+  }
+  await syncDirectory(directoryArg);
+};
+
 const removeExactOwnedDirectory = async (
   directoryArg: string,
   expectationArg: IOwnedDirectoryRemovalExpectation,
@@ -1020,9 +1152,17 @@ const removeExactOwnedDirectory = async (
   }
   if (entries.length === 1) {
     const ownerPath = plugins.path.join(directoryArg, ownerFileName);
+    const removerIdentity = await readControllerProcessIdentity(process.pid);
+    if (!removerIdentity) {
+      throw new Error('Unable to establish upgrade ownership-removal identity.');
+    }
+    const removerFingerprintHash = plugins.crypto
+      .createHash('sha256')
+      .update(removerIdentity.fingerprint, 'utf8')
+      .digest('hex');
     const tombstonePath = plugins.path.join(
       directoryArg,
-      `.owner-removing-${process.pid}-${plugins.crypto.randomBytes(8).toString('hex')}`,
+      `.owner-removing-${process.pid}-${removerFingerprintHash}-${plugins.crypto.randomBytes(8).toString('hex')}`,
     );
     expectationArg.assertRemovalAuthorized?.();
     await plugins.fs.promises.rename(ownerPath, tombstonePath);
@@ -1065,6 +1205,51 @@ const removeExactOwnedDirectory = async (
   await syncDirectory(plugins.path.dirname(directoryArg));
 };
 
+const removeExactFailedOwnerPublication = async (
+  directoryArg: string,
+  identityArg: { dev: number; ino: number },
+): Promise<void> => {
+  const initialStats = await lstatIfPresent(directoryArg);
+  if (!initialStats) return;
+  if (!sameOwnedDirectoryIdentity(initialStats, identityArg)) {
+    throw new Error('Upgrade coordination publication changed before cleanup.');
+  }
+  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 publication contains unsafe entries: ${directoryArg}`);
+  if (entries.length === 1) {
+    const ownerPath = plugins.path.join(directoryArg, ownerFileName);
+    const ownerStats = await plugins.fs.promises.lstat(ownerPath);
+    if (
+      !ownerStats.isFile()
+      || ownerStats.isSymbolicLink()
+      || (typeof process.getuid === 'function' && ownerStats.uid !== process.getuid())
+      || (ownerStats.mode & 0o077) !== 0
+      || ownerStats.nlink !== 1
+    ) throw new Error(`Upgrade coordination publication metadata is unsafe: ${ownerPath}`);
+    await plugins.fs.promises.unlink(ownerPath);
+    await syncDirectory(directoryArg);
+  }
+  const currentStats = await lstatIfPresent(directoryArg);
+  if (!currentStats) return;
+  if (!sameOwnedDirectoryIdentity(currentStats, identityArg)) {
+    throw new Error('Upgrade coordination publication changed during cleanup.');
+  }
+  try {
+    await plugins.fs.promises.rmdir(directoryArg);
+  } catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw errorArg;
+  }
+  await syncDirectory(plugins.path.dirname(directoryArg));
+};
+
 class UpgradeOwnershipMutationGuard {
   private released = false;
   private releaseTask?: Promise<void>;
@@ -1072,6 +1257,7 @@ class UpgradeOwnershipMutationGuard {
   constructor(
     public readonly directory: string,
     public readonly owner: IUpgradeOwnershipMutationGuardOwner,
+    private readonly identity: { dev: number; ino: number },
   ) {}
 
   public release(): Promise<void> {
@@ -1079,21 +1265,34 @@ class UpgradeOwnershipMutationGuard {
     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)) {
+        const stats = await lstatIfPresent(this.directory);
+        if (!stats) {
+          this.released = true;
+          return;
+        }
+        if (!sameOwnedDirectoryIdentity(stats, this.identity)) {
+          throw new Error('Upgrade ownership mutation guard changed unexpectedly.');
+        }
+        const metadata = await inspectOwnedDirectoryOwnerMetadata(
+          this.directory,
+          parseOwnershipMutationGuardOwner,
+        );
+        if (metadata && !exactPrimitiveRecordMatches(metadata.owner, this.owner)) {
           throw new Error('Upgrade ownership mutation guard changed unexpectedly.');
         }
+        if (metadata) await restoreOwnedDirectoryOwnerMetadata(this.directory, metadata);
         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.');
-            }
-          },
+          identity: this.identity,
+          ...(metadata
+            ? {
+                assertOwner: (valueArg: unknown) => {
+                  const removedOwner = parseOwnershipMutationGuardOwner(valueArg);
+                  if (!exactPrimitiveRecordMatches(removedOwner, this.owner)) {
+                    throw new Error('Upgrade ownership mutation guard changed during release.');
+                  }
+                },
+              }
+            : {}),
         });
         this.released = true;
       })().finally(() => {
@@ -1165,17 +1364,48 @@ export class UpgradeCoordinator {
   public readonly startLeasesDirectory: string;
   public readonly transactionsDirectory: string;
   public readonly ownershipGuardsDirectory: string;
+  private readonly usesLegacyLocation: boolean;
+  private readonly usesInheritedLocation: boolean;
   private initializationTask?: Promise<void>;
 
-  constructor(public readonly canonicalGlobalRoot: string) {
+  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)}`,
+    const canonicalBaseDirectory = plugins.path.join(
+      resolveAGLHomePaths().upgrade,
+      `coordination-${this.uid}-${coordinationPathHash(canonicalGlobalRoot)}`,
     );
+    const inheritedBaseDirectory = process.env[upgradeCoordinationRootEnvironmentVariable];
+    if (inheritedBaseDirectory !== undefined) {
+      if (
+        !plugins.path.isAbsolute(inheritedBaseDirectory)
+        || plugins.path.normalize(inheritedBaseDirectory) !== inheritedBaseDirectory
+        || plugins.path.parse(inheritedBaseDirectory).root === inheritedBaseDirectory
+        || inheritedBaseDirectory.includes('\0')
+        || Buffer.byteLength(inheritedBaseDirectory, 'utf8') > 4096
+      ) throw new Error('The inherited AGL upgrade coordination root is invalid.');
+    }
+    const inheritedUpgradeToken = process.env[upgradeTokenEnvironmentVariable];
+    const usesLegacyLocation = inheritedUpgradeToken !== undefined
+      && process.env[upgradeCoordinationRootEnvironmentVariable] === undefined;
+    if (
+      usesLegacyLocation
+      && (inheritedUpgradeToken === undefined || !upgradeTokenPattern.test(inheritedUpgradeToken))
+    ) {
+      throw new Error('Legacy upgrade coordination requires the exact inherited upgrade token.');
+    }
+    this.usesLegacyLocation = usesLegacyLocation;
+    this.usesInheritedLocation = inheritedBaseDirectory !== undefined;
+    this.baseDirectory = this.usesLegacyLocation
+      ? plugins.path.join(
+          '/tmp',
+          `harness-controller-upgrade-${this.uid}-${coordinationPathHash(canonicalGlobalRoot)}`,
+        )
+      : inheritedBaseDirectory ?? canonicalBaseDirectory;
     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');
@@ -1195,19 +1425,17 @@ export class UpgradeCoordinator {
   }
 
   private async performInitialization(): Promise<void> {
+    if (!this.usesLegacyLocation && !this.usesInheritedLocation) {
+      const home = resolveAGLHomePaths();
+      await ensurePrivateDirectory(home.root);
+      await ensurePrivateDirectory(home.upgrade);
+    }
     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);
-    }
+    await this.cleanupOwnershipGuardTemporaryDirectories();
+    await this.cleanupOwnershipGuardDirectories();
     const entries = await plugins.fs.promises.readdir(this.baseDirectory, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isFile() || !tokenMetadataPattern.test(entry.name)) continue;
@@ -1293,6 +1521,205 @@ export class UpgradeCoordinator {
     );
   }
 
+  private async inspectOwnershipGuardDirectory(
+    directoryArg: string,
+    expectedTargetHashArg: string,
+    attemptArg = 0,
+  ): Promise<IUpgradeOwnershipMutationGuardState> {
+    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(`Upgrade ownership mutation guard is unsafe: ${directoryArg}`);
+    let ownerMetadata: IOwnedDirectoryOwnerMetadata<IUpgradeOwnershipMutationGuardOwner> | undefined;
+    try {
+      ownerMetadata = await inspectOwnedDirectoryOwnerMetadata(
+        directoryArg,
+        parseOwnershipMutationGuardOwner,
+      );
+    } catch (errorArg) {
+      const currentStats = await lstatIfPresent(directoryArg);
+      if (!currentStats) return { state: 'absent' };
+      if (!sameOwnedDirectoryIdentity(currentStats, { dev: stats.dev, ino: stats.ino })) {
+        if (attemptArg < 2) {
+          return await this.inspectOwnershipGuardDirectory(
+            directoryArg,
+            expectedTargetHashArg,
+            attemptArg + 1,
+          );
+        }
+        throw new Error(`Upgrade ownership mutation guard changed repeatedly: ${directoryArg}`, {
+          cause: errorArg,
+        });
+      }
+      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') {
+        return {
+          state: Date.now() - currentStats.mtimeMs < initializationGraceMs ? 'live' : 'empty',
+          identity: { dev: currentStats.dev, ino: currentStats.ino },
+        };
+      }
+      throw errorArg;
+    }
+    if (!ownerMetadata) {
+      return {
+        state: Date.now() - stats.mtimeMs < initializationGraceMs ? 'live' : 'empty',
+        identity: { dev: stats.dev, ino: stats.ino },
+      };
+    }
+    const owner = ownerMetadata.owner;
+    if (owner.uid !== this.uid || owner.targetHash !== expectedTargetHashArg) {
+      throw new Error(`Upgrade ownership mutation guard binding is invalid: ${directoryArg}`);
+    }
+    let processIdentity: Awaited<ReturnType<typeof readControllerProcessIdentity>>;
+    let removalProcessIdentity: Awaited<ReturnType<typeof readControllerProcessIdentity>>;
+    try {
+      processIdentity = await readControllerProcessIdentity(owner.pid);
+      removalProcessIdentity = ownerMetadata.removalPid === undefined
+        ? null
+        : ownerMetadata.removalPid === owner.pid
+          ? processIdentity
+          : await readControllerProcessIdentity(ownerMetadata.removalPid);
+    } catch (errorArg) {
+      throw new Error(`The upgrade ownership mutation guard cannot be verified safely: ${directoryArg}`, {
+        cause: errorArg,
+      });
+    }
+    const ownerIsStillLive = processIdentity?.fingerprint === owner.fingerprint;
+    const removerIsStillLive = ownerMetadata.removalFingerprintHash
+      ? removalProcessIdentity !== null
+        && plugins.crypto.createHash('sha256')
+          .update(removalProcessIdentity.fingerprint, 'utf8')
+          .digest('hex') === ownerMetadata.removalFingerprintHash
+      : ownerMetadata.removalPid !== undefined
+        && removalProcessIdentity !== null
+        && Date.now() - ownerMetadata.tombstoneCtimeMs! < legacyOwnerRemovalGraceMs;
+    return {
+      state: ownerIsStillLive || removerIsStillLive ? 'live' : 'stale',
+      identity: { dev: stats.dev, ino: stats.ino },
+      owner,
+      ownerMetadata,
+    };
+  }
+
+  private async reclaimOwnershipGuardDirectory(
+    directoryArg: string,
+    targetHashArg: string,
+  ): Promise<'retry' | 'live'> {
+    const inspected = await this.inspectOwnershipGuardDirectory(directoryArg, targetHashArg);
+    if (inspected.state === 'absent') return 'retry';
+    if (inspected.state === 'live') return 'live';
+    const identity = inspected.identity!;
+    if (inspected.state === 'empty') {
+      const current = await lstatIfPresent(directoryArg);
+      if (!current) return 'retry';
+      if (!sameOwnedDirectoryIdentity(current, identity)) {
+        throw new Error('Upgrade ownership mutation guard changed before empty recovery.');
+      }
+      if ((await plugins.fs.promises.readdir(directoryArg)).length !== 0) {
+        throw new Error('Upgrade ownership mutation guard changed during empty recovery.');
+      }
+      await plugins.fs.promises.rmdir(directoryArg).catch((errorArg) => {
+        if ((errorArg as NodeJS.ErrnoException).code !== 'ENOENT') throw errorArg;
+      });
+      await syncDirectory(this.ownershipGuardsDirectory);
+      return 'retry';
+    }
+    await restoreOwnedDirectoryOwnerMetadata(directoryArg, inspected.ownerMetadata!);
+    await removeExactOwnedDirectory(directoryArg, {
+      identity,
+      assertOwner: (valueArg) => {
+        const removedOwner = parseOwnershipMutationGuardOwner(valueArg);
+        if (!exactPrimitiveRecordMatches(removedOwner, inspected.owner!)) {
+          throw new Error('Upgrade ownership mutation guard changed during stale recovery.');
+        }
+      },
+    });
+    return 'retry';
+  }
+
+  private async cleanupOwnershipGuardDirectories(): Promise<void> {
+    const entries = await plugins.fs.promises.readdir(this.ownershipGuardsDirectory, {
+      withFileTypes: true,
+    });
+    for (const entry of entries) {
+      const path = plugins.path.join(this.ownershipGuardsDirectory, entry.name);
+      if (ownershipGuardTemporaryPattern.test(entry.name)) continue;
+      if (!entry.isDirectory() || !ownershipGuardDirectoryPattern.test(entry.name)) {
+        throw new Error(`Upgrade ownership guard directory contains an unexpected entry: ${path}`);
+      }
+      await this.reclaimOwnershipGuardDirectory(path, entry.name.slice(0, 64));
+    }
+  }
+
+  private async cleanupOwnershipGuardTemporaryDirectories(): Promise<void> {
+    const entries = await plugins.fs.promises.readdir(this.ownershipGuardsDirectory, {
+      withFileTypes: true,
+    });
+    for (const entry of entries) {
+      if (!ownershipGuardTemporaryPattern.test(entry.name)) continue;
+      const match = /^([a-f0-9]{64})\.guard\.tmp-([1-9][0-9]*)-([a-f0-9]{32})$/.exec(entry.name);
+      if (!match) throw new Error(`Upgrade ownership guard temporary name is invalid: ${entry.name}`);
+      const pid = Number(match[2]);
+      const path = plugins.path.join(this.ownershipGuardsDirectory, entry.name);
+      const stats = await lstatIfPresent(path);
+      if (
+        !stats
+        || !stats.isDirectory()
+        || stats.isSymbolicLink()
+        || stats.uid !== this.uid
+        || (stats.mode & 0o077) !== 0
+      ) throw new Error(`Upgrade ownership guard temporary is unsafe: ${path}`);
+      const ownerPath = plugins.path.join(path, ownerFileName);
+      const ownerStats = await lstatIfPresent(ownerPath);
+      let owner: IUpgradeOwnershipMutationGuardOwner | undefined;
+      if (ownerStats) {
+        if (
+          !ownerStats.isFile()
+          || ownerStats.isSymbolicLink()
+          || ownerStats.uid !== this.uid
+          || (ownerStats.mode & 0o077) !== 0
+          || ownerStats.nlink !== 1
+        ) throw new Error(`Upgrade ownership guard temporary owner is unsafe: ${ownerPath}`);
+        try {
+          owner = parseOwnershipMutationGuardOwner(await readPrivateJson(ownerPath));
+        } catch (errorArg) {
+          if (await readControllerProcessIdentity(pid)) {
+            throw new Error(`Upgrade ownership guard temporary is owned by live PID ${pid}.`, {
+              cause: errorArg,
+            });
+          }
+        }
+      }
+      const live = await readControllerProcessIdentity(pid);
+      if (live && (!owner || owner.pid !== pid || owner.fingerprint !== live.fingerprint)) {
+        throw new Error(`Upgrade ownership guard temporary is owned by live PID ${pid}.`);
+      }
+      if (live) continue;
+      if (owner && (owner.pid !== pid || owner.uid !== this.uid || owner.targetHash !== match[1])) {
+        throw new Error(`Upgrade ownership guard temporary binding is invalid: ${path}`);
+      }
+      const stable = await lstatIfPresent(path);
+      if (!stable || stable.dev !== stats.dev || stable.ino !== stats.ino) {
+        throw new Error(`Upgrade ownership guard temporary changed before cleanup: ${path}`);
+      }
+      if (ownerStats) {
+        const stableOwner = await lstatIfPresent(ownerPath);
+        if (!stableOwner || stableOwner.dev !== ownerStats.dev || stableOwner.ino !== ownerStats.ino) {
+          throw new Error(`Upgrade ownership guard temporary owner changed before cleanup: ${ownerPath}`);
+        }
+        await plugins.fs.promises.unlink(ownerPath);
+      }
+      if ((await plugins.fs.promises.readdir(path)).length !== 0) {
+        throw new Error(`Upgrade ownership guard temporary contains unexpected entries: ${path}`);
+      }
+      await plugins.fs.promises.rmdir(path);
+      await syncDirectory(this.ownershipGuardsDirectory);
+    }
+  }
+
   private async acquireOwnershipMutationGuard(
     directoryArg: string,
   ): Promise<UpgradeOwnershipMutationGuard> {
@@ -1310,70 +1737,63 @@ export class UpgradeCoordinator {
       createdAt: Date.now(),
     };
     const deadline = Date.now() + ownershipGuardTimeoutMs;
+    const temporaryDirectory = `${guardDirectory}.tmp-${owner.pid}-${owner.nonce}`;
     while (true) {
+      let temporaryCreated = false;
+      let publishedIdentity: { dev: number; ino: number } | undefined;
       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;
+        await plugins.fs.promises.mkdir(temporaryDirectory, { mode: 0o700 });
+        temporaryCreated = true;
+        await writePrivateJson(plugins.path.join(temporaryDirectory, ownerFileName), owner);
+        await syncDirectory(temporaryDirectory);
+        const temporaryStats = await plugins.fs.promises.lstat(temporaryDirectory);
+        const temporaryIdentity = { dev: temporaryStats.dev, ino: temporaryStats.ino };
+        await plugins.fs.promises.rename(temporaryDirectory, guardDirectory);
+        temporaryCreated = false;
+        publishedIdentity = temporaryIdentity;
+        const publishedStats = await plugins.fs.promises.lstat(guardDirectory);
+        if (!sameOwnedDirectoryIdentity(publishedStats, publishedIdentity)) {
+          throw new Error('Published upgrade ownership guard identity changed unexpectedly.');
         }
-        return new UpgradeOwnershipMutationGuard(guardDirectory, owner);
+        await syncDirectory(this.ownershipGuardsDirectory);
+        return new UpgradeOwnershipMutationGuard(guardDirectory, owner, publishedIdentity);
       } 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;
+        const cleanupErrors: unknown[] = [];
+        if (temporaryCreated) {
+          try {
+            await plugins.fs.promises.rm(temporaryDirectory, { recursive: true, force: true });
+          } catch (cleanupErrorArg) {
+            cleanupErrors.push(cleanupErrorArg);
+          }
         }
-        if (
-          Date.now() - refreshedStats.mtimeMs < initializationGraceMs
-          && Date.now() < deadline
-        ) {
-          await new Promise((resolve) => setTimeout(resolve, 25));
-          continue;
+        if (publishedIdentity) {
+          try {
+            await removeExactOwnedDirectory(guardDirectory, {
+              identity: publishedIdentity,
+              assertOwner: (valueArg) => {
+                const publishedOwner = parseOwnershipMutationGuardOwner(valueArg);
+                if (!exactPrimitiveRecordMatches(publishedOwner, owner)) {
+                  throw new Error('Published upgrade ownership guard changed during cleanup.');
+                }
+              },
+            });
+          } catch (cleanupErrorArg) {
+            cleanupErrors.push(cleanupErrorArg);
+          }
         }
-        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 (cleanupErrors.length > 0) {
+          throw new AggregateError(
+            [errorArg, ...cleanupErrors],
+            'Upgrade ownership guard publication failed and cleanup was incomplete.',
+            { cause: errorArg },
+          );
+        }
+        const code = (errorArg as NodeJS.ErrnoException).code;
+        if (code !== 'EEXIST' && code !== 'ENOTEMPTY') throw 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 (await this.reclaimOwnershipGuardDirectory(guardDirectory, targetHash) === 'retry') {
+        continue;
       }
       if (Date.now() >= deadline) {
         throw new Error('Timed out waiting for an upgrade ownership mutation guard.');
@@ -1419,6 +1839,9 @@ export class UpgradeCoordinator {
         throw new Error(`The existing ${currentCliName} ownership cannot be verified safely.`);
       }
       if (current.state !== 'stale') return false;
+      if (current.ownerMetadata) {
+        await restoreOwnedDirectoryOwnerMetadata(directoryArg, current.ownerMetadata);
+      }
       await removeExactOwnedDirectory(directoryArg, {
         identity: current.identity!,
         ...(current.owner
@@ -1439,41 +1862,35 @@ export class UpgradeCoordinator {
   private async releaseOwnedDirectory(
     directoryArg: string,
     expectedOwnerArg: IUpgradeProcessOwner,
+    expectedIdentityArg: { dev: number; ino: number },
     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;
+      const stats = await lstatIfPresent(directoryArg);
+      if (!stats) return;
+      if (!sameOwnedDirectoryIdentity(stats, expectedIdentityArg)) {
+        throw new Error('Upgrade coordination ownership changed unexpectedly.');
       }
-      if (!exactPrimitiveRecordMatches(currentOwner, expectedOwnerArg)) {
+      const metadata = await inspectOwnedDirectoryOwnerMetadata(directoryArg, parseOwner);
+      if (metadata && !exactPrimitiveRecordMatches(metadata.owner, expectedOwnerArg)) {
         throw new Error('Upgrade coordination ownership changed unexpectedly.');
       }
+      if (shouldReleaseArg && !shouldReleaseArg()) {
+        throw new Error('Upgrade coordination release is no longer authorized.');
+      }
+      if (metadata) await restoreOwnedDirectoryOwnerMetadata(directoryArg, metadata);
       await removeExactOwnedDirectory(directoryArg, {
-        identity: { dev: stats.dev, ino: stats.ino },
-        ...(shouldReleaseArg
+        identity: expectedIdentityArg,
+        ...(metadata
           ? {
-              assertRemovalAuthorized: () => {
-                if (!shouldReleaseArg()) {
-                  throw new Error('Upgrade coordination release is no longer authorized.');
+              assertOwner: (valueArg: unknown) => {
+                const removedOwner = parseOwner(valueArg);
+                if (!exactPrimitiveRecordMatches(removedOwner, expectedOwnerArg)) {
+                  throw new Error('Upgrade coordination ownership changed during release.');
                 }
               },
             }
           : {}),
-        assertOwner: (valueArg) => {
-          const removedOwner = parseOwner(valueArg);
-          if (!exactPrimitiveRecordMatches(removedOwner, expectedOwnerArg)) {
-            throw new Error('Upgrade coordination ownership changed during release.');
-          }
-        },
       });
     });
   }
@@ -1481,10 +1898,13 @@ export class UpgradeCoordinator {
   private async inspectTransactionMutationDirectory(
     directoryArg: string,
     expectedTokenHashArg?: string,
+    attemptArg = 0,
   ): Promise<{
     state: 'absent' | 'live' | 'recent-invalid' | 'stale' | 'indeterminate';
     identity?: { dev: number; ino: number };
     owner?: IUpgradeTransactionMutationOwner;
+    ownerMetadata?: IOwnedDirectoryOwnerMetadata<IUpgradeTransactionMutationOwner>;
+    inspectionError?: unknown;
   }> {
     const stats = await lstatIfPresent(directoryArg);
     if (!stats) return { state: 'absent' };
@@ -1494,15 +1914,54 @@ export class UpgradeCoordinator {
       || stats.uid !== this.uid
       || (stats.mode & 0o077) !== 0
     ) throw new Error('The upgrade transaction mutation lock is unsafe.');
-    let rawOwner: unknown;
+    let ownerMetadata: IOwnedDirectoryOwnerMetadata<IUpgradeTransactionMutationOwner> | undefined;
     try {
-      rawOwner = await readPrivateJson(plugins.path.join(directoryArg, ownerFileName));
+      ownerMetadata = await inspectOwnedDirectoryOwnerMetadata(
+        directoryArg,
+        parseTransactionMutationOwner,
+      );
     } catch (errorArg) {
+      const currentStats = await lstatIfPresent(directoryArg);
+      if (!currentStats) return { state: 'absent' };
+      if (!sameOwnedDirectoryIdentity(currentStats, { dev: stats.dev, ino: stats.ino })) {
+        if (attemptArg < 2) {
+          return await this.inspectTransactionMutationDirectory(
+            directoryArg,
+            expectedTokenHashArg,
+            attemptArg + 1,
+          );
+        }
+        return {
+          state: 'indeterminate',
+          identity: { dev: currentStats.dev, ino: currentStats.ino },
+          inspectionError: 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') {
+        return {
+          state: Date.now() - currentStats.mtimeMs < initializationGraceMs
+            ? 'recent-invalid'
+            : 'stale',
+          identity: { dev: currentStats.dev, ino: currentStats.ino },
+        };
       }
-      if (code !== 'ENOENT') throw errorArg;
+      if (
+        Date.now() - currentStats.mtimeMs < initializationGraceMs
+        && (code === undefined || code === 'HCON_INVALID_JSON')
+      ) {
+        return {
+          state: 'recent-invalid',
+          identity: { dev: currentStats.dev, ino: currentStats.ino },
+        };
+      }
+      return {
+        state: 'indeterminate',
+        identity: { dev: currentStats.dev, ino: currentStats.ino },
+        inspectionError: errorArg,
+      };
+    }
+    if (!ownerMetadata) {
       return {
         state: Date.now() - stats.mtimeMs < initializationGraceMs
           ? 'recent-invalid'
@@ -1510,12 +1969,7 @@ export class UpgradeCoordinator {
         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 } };
-    }
+    const owner = ownerMetadata.owner;
     if (
       owner.uid !== this.uid
       || (expectedTokenHashArg !== undefined
@@ -1527,9 +1981,14 @@ export class UpgradeCoordinator {
         state: ownerIdentity?.fingerprint === owner.fingerprint ? 'live' : 'stale',
         identity: { dev: stats.dev, ino: stats.ino },
         owner,
+        ownerMetadata,
+      };
+    } catch (errorArg) {
+      return {
+        state: 'indeterminate',
+        identity: { dev: stats.dev, ino: stats.ino },
+        inspectionError: errorArg,
       };
-    } catch {
-      return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
     }
   }
 
@@ -1544,9 +2003,14 @@ export class UpgradeCoordinator {
       );
       if (current.state === 'absent') return false;
       if (current.state === 'indeterminate') {
-        throw new Error('The upgrade transaction mutation owner cannot be verified safely.');
+        throw new Error('The upgrade transaction mutation owner cannot be verified safely.', {
+          cause: current.inspectionError,
+        });
       }
       if (current.state !== 'stale') return false;
+      if (current.ownerMetadata) {
+        await restoreOwnedDirectoryOwnerMetadata(directoryArg, current.ownerMetadata);
+      }
       await removeExactOwnedDirectory(directoryArg, {
         identity: current.identity!,
         ...(current.owner
@@ -1572,6 +2036,7 @@ export class UpgradeCoordinator {
     state: 'absent' | 'live' | 'recent-invalid' | 'stale' | 'indeterminate';
     identity?: { dev: number; ino: number };
     owner?: IUpgradeProcessOwner;
+    ownerMetadata?: IOwnedDirectoryOwnerMetadata<IUpgradeProcessOwner>;
   }> {
     let stats: plugins.fs.Stats;
     try {
@@ -1586,15 +2051,13 @@ export class UpgradeCoordinator {
     if (stats.uid !== this.uid || (stats.mode & 0o077) !== 0) {
       throw new Error(`Upgrade coordination owner path is not private: ${directoryArg}`);
     }
-    let ownerValue: unknown;
+    let ownerMetadata: IOwnedDirectoryOwnerMetadata<IUpgradeProcessOwner> | undefined;
     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;
+      ownerMetadata = await inspectOwnedDirectoryOwnerMetadata(directoryArg, parseOwner);
+    } catch {
+      return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
+    }
+    if (!ownerMetadata) {
       return {
         state: Date.now() - stats.mtimeMs < initializationGraceMs
           ? 'recent-invalid'
@@ -1602,17 +2065,13 @@ export class UpgradeCoordinator {
         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 } };
-    }
+    const owner = ownerMetadata.owner;
     try {
       return {
         state: await ownerIsLive(owner) ? 'live' : 'stale',
         identity: { dev: stats.dev, ino: stats.ino },
         owner,
+        ownerMetadata,
       };
     } catch {
       return { state: 'indeterminate', identity: { dev: stats.dev, ino: stats.ino } };
@@ -1622,7 +2081,11 @@ export class UpgradeCoordinator {
   private async createOwnedDirectory(
     directoryArg: string,
     ownerArg: IUpgradeProcessOwner,
-  ): Promise<{ directory: string; owner: IUpgradeProcessOwner } | undefined> {
+  ): Promise<{
+    directory: string;
+    owner: IUpgradeProcessOwner;
+    identity: { dev: number; ino: number };
+  } | undefined> {
     return await this.withOwnershipMutationGuard(directoryArg, async () => {
       try {
         await plugins.fs.promises.mkdir(directoryArg, { mode: 0o700 });
@@ -1630,13 +2093,26 @@ export class UpgradeCoordinator {
         if ((errorArg as NodeJS.ErrnoException).code === 'EEXIST') return undefined;
         throw errorArg;
       }
+      const stats = await plugins.fs.promises.lstat(directoryArg);
+      const identity = { dev: stats.dev, ino: stats.ino };
       try {
         await writePrivateJson(plugins.path.join(directoryArg, ownerFileName), ownerArg);
         await syncDirectory(plugins.path.dirname(directoryArg));
-        return { directory: directoryArg, owner: ownerArg };
+        return {
+          directory: directoryArg,
+          owner: ownerArg,
+          identity,
+        };
       } catch (errorArg) {
-        // Preserve a failed initialization directory. Contenders treat it as
-        // recent-invalid, then reclaim it only after the bounded grace period.
+        try {
+          await removeExactFailedOwnerPublication(directoryArg, identity);
+        } catch (cleanupErrorArg) {
+          throw new AggregateError(
+            [errorArg, cleanupErrorArg],
+            'Upgrade coordination owner publication failed and cleanup was incomplete.',
+            { cause: errorArg },
+          );
+        }
         throw errorArg;
       }
     });
@@ -1662,20 +2138,13 @@ export class UpgradeCoordinator {
         (directoryArg, ownerArg, shouldReleaseArg) => this.releaseOwnedDirectory(
           directoryArg,
           ownerArg,
+          created.identity,
           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;
-        }
+        const currentOwner = state.owner!;
         if (
           currentOwner.pid === owner.pid
           && currentOwner.fingerprint === owner.fingerprint
@@ -1686,6 +2155,7 @@ export class UpgradeCoordinator {
           (directoryArg, ownerArg, shouldReleaseArg) => this.releaseOwnedDirectory(
             directoryArg,
             ownerArg,
+            state.identity!,
             shouldReleaseArg,
           ),
         );
@@ -1763,13 +2233,7 @@ export class UpgradeCoordinator {
         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;
-      }
+      return state.owner!;
     }
     throw new Error(`The ${currentCliName} upgrade owner changed repeatedly during admission.`);
   }
@@ -1806,6 +2270,7 @@ export class UpgradeCoordinator {
       (directoryArg, ownerArg, shouldReleaseArg) => this.releaseOwnedDirectory(
         directoryArg,
         ownerArg,
+        created.identity,
         shouldReleaseArg,
       ),
     );
@@ -1893,37 +2358,54 @@ export class UpgradeCoordinator {
       createdAt: Date.now(),
     };
     while (true) {
-      try {
-        await plugins.fs.promises.mkdir(lockDirectory, { mode: 0o700 });
+      const acquisition = await this.withOwnershipMutationGuard(lockDirectory, async () => {
+        try {
+          await plugins.fs.promises.mkdir(lockDirectory, { mode: 0o700 });
+        } catch (errorArg) {
+          if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
+          const current = await this.inspectTransactionMutationDirectory(
+            lockDirectory,
+            owner.tokenHash,
+          );
+          return { state: 'contended' as const, current };
+        }
+        const lockStats = await plugins.fs.promises.lstat(lockDirectory);
+        const lockIdentity = { dev: lockStats.dev, ino: lockStats.ino };
         try {
           await writePrivateJson(plugins.path.join(lockDirectory, ownerFileName), owner);
+          return { state: 'acquired' as const };
         } catch (errorArg) {
-          // Leave partial initialization for the next contender's bounded stale check.
+          try {
+            await removeExactFailedOwnerPublication(lockDirectory, lockIdentity);
+          } catch (cleanupErrorArg) {
+            throw new AggregateError(
+              [errorArg, cleanupErrorArg],
+              'Upgrade transaction mutation owner publication failed and cleanup was incomplete.',
+              { cause: errorArg },
+            );
+          }
           throw errorArg;
         }
-        break;
-      } catch (errorArg) {
-        if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
-        const current = await this.inspectTransactionMutationDirectory(
+      });
+      if (acquisition.state === 'acquired') break;
+      const current = acquisition.current;
+      if (current.state === 'absent') continue;
+      if (current.state === 'stale') {
+        await this.reclaimStaleTransactionMutationDirectory(
           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));
+        continue;
       }
+      if (current.state === 'indeterminate') {
+        throw new Error('The upgrade transaction mutation owner cannot be verified safely.', {
+          cause: current.inspectionError,
+        });
+      }
+      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;
@@ -1936,23 +2418,18 @@ export class UpgradeCoordinator {
     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;
+        const metadata = await inspectOwnedDirectoryOwnerMetadata(
+          lockDirectory,
+          parseTransactionMutationOwner,
+        );
+        if (!metadata) {
+          throw new Error('The upgrade transaction mutation lock ownership changed unexpectedly.');
         }
+        const currentOwner = metadata.owner;
         if (!exactPrimitiveRecordMatches(currentOwner, owner)) {
           throw new Error('The upgrade transaction mutation lock ownership changed unexpectedly.');
         }
+        await restoreOwnedDirectoryOwnerMetadata(lockDirectory, metadata);
         await removeExactOwnedDirectory(lockDirectory, {
           identity: { dev: stats.dev, ino: stats.ino },
           assertOwner: (valueArg) => {