@autodevjapan/godd-mcp-alpha 2.9.3 → 2.10.0

package/scripts/atomic-binary-install.js

@@ -0,0 +1,679 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  opendirSync,
+  readSync,
+  renameSync,
+  rmdirSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const LOCK_SCHEMA_VERSION = 1;
+const MAX_LOCK_BYTES = 512;
+const MAX_LOCK_BYTES_BIGINT = BigInt(MAX_LOCK_BYTES);
+const RECOVERY_SCHEMA_VERSION = 1;
+const MAX_RECOVERY_BYTES = 1024;
+const MAX_RECOVERY_BYTES_BIGINT = BigInt(MAX_RECOVERY_BYTES);
+const RECOVERY_RECORD_NAME = "recovery.json";
+const RETIRED_RECOVERY_SUFFIX = ".retired";
+const MAX_ACQUIRE_ATTEMPTS = 8;
+const OPERATION_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/** Deterministic test seam representing termination that cannot run rollback/finally. */
+export class AtomicInstallInterruption extends Error {}
+
+/** Publish failed and the previous verified state could not be restored. */
+export class AtomicInstallRollbackError extends Error {}
+
+/** The published bytes failed trusted verification after reaching the final path. */
+export class AtomicInstallIntegrityError extends Error {}
+
+/** Final bytes are verified, but the previous backup could not be removed. */
+export class AtomicInstallCleanupError extends Error {}
+
+function defaultIsProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !(error && typeof error === "object" && error.code === "ESRCH");
+  }
+}
+
+function readOwner(path) {
+  const pathStat = lstatSync(path, { bigint: true });
+  if (
+    pathStat.isSymbolicLink() ||
+    !pathStat.isFile() ||
+    pathStat.ino === 0n ||
+    pathStat.size > MAX_LOCK_BYTES_BIGINT
+  ) {
+    throw new Error("INSTALL_LOCK_INVALID");
+  }
+
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  const descriptor = openSync(path, constants.O_RDONLY | noFollow);
+  let bytes;
+  try {
+    const handleStat = fstatSync(descriptor, { bigint: true });
+    if (
+      !handleStat.isFile() ||
+      handleStat.ino === 0n ||
+      handleStat.size > MAX_LOCK_BYTES_BIGINT ||
+      handleStat.dev !== pathStat.dev ||
+      handleStat.ino !== pathStat.ino
+    ) {
+      throw new Error("INSTALL_LOCK_INVALID");
+    }
+    const boundedBuffer = Buffer.allocUnsafe(MAX_LOCK_BYTES + 1);
+    const byteLength = readSync(
+      descriptor,
+      boundedBuffer,
+      0,
+      boundedBuffer.byteLength,
+      0,
+    );
+    bytes = boundedBuffer.subarray(0, byteLength);
+  } finally {
+    closeSync(descriptor);
+  }
+  if (bytes.byteLength > MAX_LOCK_BYTES) {
+    throw new Error("INSTALL_LOCK_INVALID");
+  }
+  const owner = JSON.parse(bytes.toString("utf8"));
+  if (
+    !owner ||
+    typeof owner !== "object" ||
+    Array.isArray(owner) ||
+    JSON.stringify(Object.keys(owner).sort()) !==
+      JSON.stringify(["operationId", "pid", "schemaVersion", "tempName"]) ||
+    owner.schemaVersion !== LOCK_SCHEMA_VERSION ||
+    !Number.isSafeInteger(owner.pid) ||
+    owner.pid <= 0 ||
+    typeof owner.operationId !== "string" ||
+    !OPERATION_ID_PATTERN.test(owner.operationId) ||
+    typeof owner.tempName !== "string" ||
+    !new RegExp(`^\\.godd-tk-${owner.operationId}-[A-Za-z0-9_-]{1,64}$`).test(
+      owner.tempName,
+    )
+  ) {
+    throw new Error("INSTALL_LOCK_INVALID");
+  }
+  return owner;
+}
+
+function isAlreadyExists(error) {
+  return (
+    error &&
+    typeof error === "object" &&
+    ["EEXIST", "EPERM"].includes(error.code)
+  );
+}
+
+function ownersEqual(left, right) {
+  return (
+    left.schemaVersion === right.schemaVersion &&
+    left.pid === right.pid &&
+    left.operationId === right.operationId &&
+    left.tempName === right.tempName
+  );
+}
+
+function readBoundedDirectoryEntries(directoryPath) {
+  const gateStat = lstatSync(directoryPath, { bigint: true });
+  if (gateStat.isSymbolicLink() || !gateStat.isDirectory()) {
+    throw new Error("INSTALL_RECOVERY_INVALID");
+  }
+  const directory = opendirSync(directoryPath);
+  const entries = [];
+  try {
+    for (let index = 0; index < 2; index += 1) {
+      const entry = directory.readSync();
+      if (!entry) break;
+      entries.push(entry.name);
+    }
+  } finally {
+    directory.closeSync();
+  }
+  return entries.sort();
+}
+
+function readRecoveryRecord(recoveryPath) {
+  const entries = readBoundedDirectoryEntries(recoveryPath);
+  if (
+    entries.length !== 1 ||
+    entries[0] !== RECOVERY_RECORD_NAME
+  ) {
+    throw new Error("INSTALL_RECOVERY_ENTRIES_INVALID");
+  }
+  const recordPath = join(recoveryPath, RECOVERY_RECORD_NAME);
+  const pathStat = lstatSync(recordPath, { bigint: true });
+  if (
+    pathStat.isSymbolicLink() ||
+    !pathStat.isFile() ||
+    pathStat.ino === 0n ||
+    pathStat.size > MAX_RECOVERY_BYTES_BIGINT
+  ) {
+    throw new Error("INSTALL_RECOVERY_INVALID");
+  }
+  const descriptor = openSync(
+    recordPath,
+    constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
+  );
+  let bytes;
+  try {
+    const handleStat = fstatSync(descriptor, { bigint: true });
+    if (
+      !handleStat.isFile() ||
+      handleStat.ino === 0n ||
+      handleStat.size > MAX_RECOVERY_BYTES_BIGINT ||
+      handleStat.dev !== pathStat.dev ||
+      handleStat.ino !== pathStat.ino
+    ) {
+      throw new Error("INSTALL_RECOVERY_INVALID");
+    }
+    const boundedBuffer = Buffer.allocUnsafe(MAX_RECOVERY_BYTES + 1);
+    const byteLength = readSync(
+      descriptor,
+      boundedBuffer,
+      0,
+      boundedBuffer.byteLength,
+      0,
+    );
+    bytes = boundedBuffer.subarray(0, byteLength);
+  } finally {
+    closeSync(descriptor);
+  }
+  if (bytes.byteLength > MAX_RECOVERY_BYTES) {
+    throw new Error("INSTALL_RECOVERY_INVALID");
+  }
+  const record = JSON.parse(bytes.toString("utf8"));
+  if (
+    !record ||
+    typeof record !== "object" ||
+    Array.isArray(record) ||
+    JSON.stringify(Object.keys(record).sort()) !==
+      JSON.stringify(["owner", "phase", "retiredName", "schemaVersion"]) ||
+    record.schemaVersion !== RECOVERY_SCHEMA_VERSION ||
+    record.phase !== "owner-release" ||
+    typeof record.retiredName !== "string" ||
+    !record.owner ||
+    typeof record.owner !== "object" ||
+    Array.isArray(record.owner) ||
+    JSON.stringify(Object.keys(record.owner).sort()) !==
+      JSON.stringify(["operationId", "pid", "schemaVersion", "tempName"]) ||
+    record.owner.schemaVersion !== LOCK_SCHEMA_VERSION ||
+    !Number.isSafeInteger(record.owner.pid) ||
+    record.owner.pid <= 0 ||
+    typeof record.owner.operationId !== "string" ||
+    !OPERATION_ID_PATTERN.test(record.owner.operationId) ||
+    typeof record.owner.tempName !== "string" ||
+    !new RegExp(
+      `^\\.godd-tk-${record.owner.operationId}-[A-Za-z0-9_-]{1,64}$`,
+    ).test(record.owner.tempName)
+  ) {
+    throw new Error("INSTALL_RECOVERY_INVALID");
+  }
+  return record;
+}
+
+function cleanupRetiredRecoveryGate(
+  retiredRecoveryPath,
+  {
+    unlink = unlinkSync,
+    rmdir = rmdirSync,
+  } = {},
+) {
+  const entries = readBoundedDirectoryEntries(retiredRecoveryPath);
+  if (
+    entries.length > 1 ||
+    (entries.length === 1 && entries[0] !== RECOVERY_RECORD_NAME)
+  ) {
+    throw new Error("INSTALL_RECOVERY_ENTRIES_INVALID");
+  }
+  if (entries.length === 1) {
+    unlink(join(retiredRecoveryPath, RECOVERY_RECORD_NAME));
+  }
+  rmdir(retiredRecoveryPath);
+}
+
+/**
+ * Explicit operator recovery for a process that exited after retiring its
+ * stable owner lock. Unknown or mismatched artifacts are never removed.
+ */
+export function recoverInterruptedAtomicFinish({
+  binaryPath,
+  isProcessAlive = defaultIsProcessAlive,
+  operations = {},
+} = {}) {
+  const lockPath = `${binaryPath}.install-lock`;
+  const recoveryPath = `${lockPath}.recovery`;
+  const retiredRecoveryPath = `${recoveryPath}${RETIRED_RECOVERY_SUFFIX}`;
+  const activeGateExists = existsSync(recoveryPath);
+  const retiredGateExists = existsSync(retiredRecoveryPath);
+  if (!activeGateExists && !retiredGateExists) return { status: "not-needed" };
+  if (activeGateExists && retiredGateExists) {
+    return { status: "blocked", reason: "recovery-gate-ambiguous" };
+  }
+  const gatePath = activeGateExists ? recoveryPath : retiredRecoveryPath;
+  let entries;
+  try {
+    entries = readBoundedDirectoryEntries(gatePath);
+  } catch {
+    return { status: "blocked", reason: "recovery-record-invalid" };
+  }
+  if (entries.length === 0) {
+    if (activeGateExists) {
+      return { status: "blocked", reason: "recovery-record-invalid" };
+    }
+    try {
+      (operations.rmdir ?? rmdirSync)(retiredRecoveryPath);
+      return { status: "recovered" };
+    } catch {
+      return { status: "blocked", reason: "recovery-cleanup-failed" };
+    }
+  }
+  if (entries.length !== 1 || entries[0] !== RECOVERY_RECORD_NAME) {
+    return { status: "blocked", reason: "recovery-gate-entries-invalid" };
+  }
+  let record;
+  try {
+    record = readRecoveryRecord(gatePath);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message === "INSTALL_RECOVERY_ENTRIES_INVALID"
+    ) {
+      return { status: "blocked", reason: "recovery-gate-entries-invalid" };
+    }
+    return { status: "blocked", reason: "recovery-record-invalid" };
+  }
+  const expectedRetiredName = `${basename(lockPath)}.release-${record.owner.operationId}`;
+  if (record.retiredName !== expectedRetiredName) {
+    return { status: "blocked", reason: "recovery-record-mismatch" };
+  }
+  const resolvedRetiredOwnerPath = join(dirname(lockPath), record.retiredName);
+  const stableExists = existsSync(lockPath);
+  const retiredExists = existsSync(resolvedRetiredOwnerPath);
+  if (stableExists && retiredExists) {
+    return { status: "blocked", reason: "recovery-owner-ambiguous" };
+  }
+  if (!stableExists && !retiredExists && activeGateExists) {
+    return { status: "blocked", reason: "recovery-owner-mismatch" };
+  }
+  if (
+    (stableExists || retiredExists) &&
+    isProcessAlive(record.owner.pid)
+  ) {
+    return { status: "blocked", reason: "recovery-owner-live" };
+  }
+  try {
+    if (stableExists) {
+      if (!ownersEqual(readOwner(lockPath), record.owner)) {
+        return { status: "blocked", reason: "recovery-owner-mismatch" };
+      }
+    } else if (retiredExists) {
+      if (!ownersEqual(readOwner(resolvedRetiredOwnerPath), record.owner)) {
+        return { status: "blocked", reason: "recovery-owner-mismatch" };
+      }
+    }
+    if (activeGateExists) {
+      (operations.rename ?? renameSync)(recoveryPath, retiredRecoveryPath);
+    }
+    if (retiredExists) {
+      (operations.unlink ?? unlinkSync)(resolvedRetiredOwnerPath);
+    }
+    cleanupRetiredRecoveryGate(retiredRecoveryPath, operations);
+    return { status: "recovered" };
+  } catch {
+    return { status: "blocked", reason: "recovery-cleanup-failed" };
+  }
+}
+
+/**
+ * A complete owner record is hard-linked into the stable lock path. Unlike
+ * mkdir-then-write, there is no observable lock whose owner is only partially
+ * written when the process is interrupted.
+ */
+export function beginAtomicBinaryInstall({
+  installDir,
+  binaryPath,
+  operationId = randomUUID(),
+  ownerPid = process.pid,
+  isProcessAlive = defaultIsProcessAlive,
+  makeTempDir = (prefix) => mkdtempSync(prefix),
+  onRecoveryTransition = () => {},
+} = {}) {
+  if (!OPERATION_ID_PATTERN.test(operationId) || !Number.isSafeInteger(ownerPid) || ownerPid <= 0) {
+    throw new Error("INSTALL_OWNER_INVALID");
+  }
+  mkdirSync(installDir, { recursive: true });
+  const tempDir = makeTempDir(join(installDir, `.godd-tk-${operationId}-`));
+  const ownerCandidatePath = join(tempDir, "owner.json");
+  const lockPath = `${binaryPath}.install-lock`;
+  const backupPath = `${binaryPath}.install-backup`;
+  const recoveryPath = `${lockPath}.recovery`;
+  const retiredRecoveryPath = `${recoveryPath}${RETIRED_RECOVERY_SUFFIX}`;
+  const owner = {
+    schemaVersion: LOCK_SCHEMA_VERSION,
+    pid: ownerPid,
+    operationId,
+    tempName: basename(tempDir),
+  };
+  writeFileSync(ownerCandidatePath, `${JSON.stringify(owner)}\n`, {
+    encoding: "utf8",
+    flag: "wx",
+    mode: 0o600,
+  });
+
+  for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt += 1) {
+    if (existsSync(recoveryPath) || existsSync(retiredRecoveryPath)) {
+      rmSync(tempDir, { recursive: true, force: true });
+      return { status: "blocked", reason: "recovery-lock-present" };
+    }
+
+    try {
+      linkSync(ownerCandidatePath, lockPath);
+      if (existsSync(recoveryPath) || existsSync(retiredRecoveryPath)) {
+        try {
+          const current = readOwner(lockPath);
+          if (ownersEqual(current, owner)) unlinkSync(lockPath);
+        } catch {
+          // The recovery owner controls this boundary. Never remove an unknown lock.
+        }
+        rmSync(tempDir, { recursive: true, force: true });
+        return { status: "blocked", reason: "recovery-lock-present" };
+      }
+      return {
+        status: "acquired",
+        binaryPath,
+        backupPath,
+        lockPath,
+        owner,
+        recoveryPath,
+        retiredRecoveryPath,
+        tempDir,
+      };
+    } catch (error) {
+      if (!isAlreadyExists(error)) {
+        rmSync(tempDir, { recursive: true, force: true });
+        throw error;
+      }
+    }
+
+    let incumbent;
+    try {
+      incumbent = readOwner(lockPath);
+    } catch {
+      rmSync(tempDir, { recursive: true, force: true });
+      return { status: "blocked", reason: "lock-invalid" };
+    }
+    if (isProcessAlive(incumbent.pid)) {
+      rmSync(tempDir, { recursive: true, force: true });
+      return { status: "busy" };
+    }
+
+    try {
+      mkdirSync(recoveryPath);
+      onRecoveryTransition("recovery-locked");
+    } catch (error) {
+      rmSync(tempDir, { recursive: true, force: true });
+      if (isAlreadyExists(error)) {
+        return { status: "blocked", reason: "recovery-lock-present" };
+      }
+      throw error;
+    }
+
+    const staleOwnerPath = join(tempDir, `stale-owner-${attempt}.json`);
+    let releaseRecovery = true;
+    try {
+      const current = readOwner(lockPath);
+      if (!ownersEqual(current, incumbent)) {
+        rmdirSync(recoveryPath);
+        releaseRecovery = false;
+        continue;
+      }
+      if (isProcessAlive(current.pid)) {
+        rmdirSync(recoveryPath);
+        releaseRecovery = false;
+        rmSync(tempDir, { recursive: true, force: true });
+        return { status: "busy" };
+      }
+      renameSync(lockPath, staleOwnerPath);
+      const retired = readOwner(staleOwnerPath);
+      if (!ownersEqual(retired, incumbent)) throw new Error("INSTALL_LOCK_CHANGED");
+      rmSync(join(installDir, incumbent.tempName), { recursive: true, force: true });
+      unlinkSync(staleOwnerPath);
+      onRecoveryTransition("stale-retired");
+      try {
+        linkSync(ownerCandidatePath, lockPath);
+      } catch (error) {
+        rmdirSync(recoveryPath);
+        releaseRecovery = false;
+        rmSync(tempDir, { recursive: true, force: true });
+        if (isAlreadyExists(error)) {
+          return { status: "blocked", reason: "lock-contention" };
+        }
+        throw error;
+      }
+      try {
+        rmdirSync(recoveryPath);
+        releaseRecovery = false;
+      } catch {
+        return { status: "blocked", reason: "recovery-lock-stuck" };
+      }
+      return {
+        status: "acquired",
+        binaryPath,
+        backupPath,
+        lockPath,
+        owner,
+        recoveryPath,
+        retiredRecoveryPath,
+        tempDir,
+      };
+    } catch (error) {
+      if (existsSync(staleOwnerPath) && !existsSync(lockPath)) {
+        try {
+          renameSync(staleOwnerPath, lockPath);
+        } catch {
+          // A competing recovery may already own the stable lock. Never remove it.
+        }
+      }
+      if (error && typeof error === "object" && error.code === "ENOENT") continue;
+      rmSync(tempDir, { recursive: true, force: true });
+      throw error;
+    } finally {
+      if (releaseRecovery && existsSync(recoveryPath)) {
+        try {
+          rmdirSync(recoveryPath);
+        } catch {
+          // A stuck recovery gate is intentionally fail-closed.
+        }
+      }
+    }
+  }
+
+  rmSync(tempDir, { recursive: true, force: true });
+  return { status: "blocked", reason: "lock-contention" };
+}
+
+/**
+ * Resolve the only two interrupted publish states:
+ * backup-only restores the previous binary; binary+backup keeps the candidate
+ * only when it still passes the caller's trusted digest verifier.
+ */
+export function recoverAtomicBinaryInstall(transaction, verify, operations = {}) {
+  const rename = operations.rename ?? renameSync;
+  const unlink = operations.unlink ?? unlinkSync;
+  if (!existsSync(transaction.backupPath)) return;
+  if (!existsSync(transaction.binaryPath)) {
+    verify(transaction.backupPath);
+    rename(transaction.backupPath, transaction.binaryPath);
+    return;
+  }
+  try {
+    verify(transaction.binaryPath);
+  } catch {
+    verify(transaction.backupPath);
+    unlink(transaction.binaryPath);
+    rename(transaction.backupPath, transaction.binaryPath);
+    return;
+  }
+  unlink(transaction.backupPath);
+}
+
+export function publishAtomicBinary(
+  transaction,
+  candidatePath,
+  verify,
+  onTransition = () => {},
+  operations = {},
+) {
+  const pathExists = operations.exists ?? existsSync;
+  const rename = operations.rename ?? renameSync;
+  const unlink = operations.unlink ?? unlinkSync;
+  verify(candidatePath);
+  if (pathExists(transaction.backupPath)) {
+    throw new Error("INSTALL_BACKUP_UNRESOLVED");
+  }
+
+  let originalMoved = false;
+  let candidatePublished = false;
+  let postPublishIntegrityFailure = false;
+  let publishedVerified = false;
+  try {
+    if (pathExists(transaction.binaryPath)) {
+      rename(transaction.binaryPath, transaction.backupPath);
+      originalMoved = true;
+      onTransition("backup-created");
+    }
+    rename(candidatePath, transaction.binaryPath);
+    candidatePublished = true;
+    onTransition("candidate-published");
+    try {
+      verify(transaction.binaryPath);
+    } catch (error) {
+      postPublishIntegrityFailure = true;
+      throw error;
+    }
+    publishedVerified = true;
+    if (originalMoved) unlink(transaction.backupPath);
+  } catch (error) {
+    if (error instanceof AtomicInstallInterruption) throw error;
+    if (publishedVerified) {
+      throw new AtomicInstallCleanupError("INSTALL_PUBLISH_CLEANUP_PENDING", {
+        cause: error,
+      });
+    }
+    try {
+      if (candidatePublished && pathExists(transaction.binaryPath)) {
+        unlink(transaction.binaryPath);
+      }
+      if (originalMoved && pathExists(transaction.backupPath)) {
+        rename(transaction.backupPath, transaction.binaryPath);
+      }
+    } catch {
+      throw new AtomicInstallRollbackError("INSTALL_ROLLBACK_FAILED", {
+        cause: error,
+      });
+    }
+    if (postPublishIntegrityFailure) {
+      throw new AtomicInstallIntegrityError("INSTALL_POST_PUBLISH_INTEGRITY_FAILED", {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}
+
+export function finishAtomicBinaryInstall(
+  transaction,
+  {
+    removeTree = (path) => rmSync(path, { recursive: true, force: true }),
+    onReleaseTransition = () => {},
+    recoveryOperations = {},
+  } = {},
+) {
+  try {
+    mkdirSync(transaction.recoveryPath);
+  } catch {
+    return { ok: false, reason: "cleanup-failed" };
+  }
+  const retiredOwnerPath = `${transaction.lockPath}.release-${transaction.owner.operationId}`;
+  const recoveryRecordPath = join(transaction.recoveryPath, RECOVERY_RECORD_NAME);
+  try {
+    writeFileSync(
+      recoveryRecordPath,
+      `${JSON.stringify({
+        schemaVersion: RECOVERY_SCHEMA_VERSION,
+        phase: "owner-release",
+        owner: transaction.owner,
+        retiredName: basename(retiredOwnerPath),
+      })}\n`,
+      { encoding: "utf8", flag: "wx", mode: 0o600 },
+    );
+  } catch {
+    try {
+      rmdirSync(transaction.recoveryPath);
+    } catch {
+      // An unremovable gate remains fail-closed.
+    }
+    return { ok: false, reason: "cleanup-failed" };
+  }
+  try {
+    removeTree(transaction.tempDir);
+  } catch {
+    try {
+      (recoveryOperations.rename ?? renameSync)(
+        transaction.recoveryPath,
+        transaction.retiredRecoveryPath,
+      );
+      cleanupRetiredRecoveryGate(
+        transaction.retiredRecoveryPath,
+        recoveryOperations,
+      );
+    } catch {
+      // A complete recovery record remains for explicit operator recovery.
+    }
+    return { ok: false, reason: "cleanup-failed" };
+  }
+  let cleanupFailed = false;
+  try {
+    renameSync(transaction.lockPath, retiredOwnerPath);
+    onReleaseTransition("owner-retired");
+    const owner = readOwner(retiredOwnerPath);
+    if (
+      !ownersEqual(owner, transaction.owner) ||
+      existsSync(transaction.lockPath)
+    ) {
+      return { ok: false, reason: "cleanup-failed" };
+    }
+    readRecoveryRecord(transaction.recoveryPath);
+    (recoveryOperations.rename ?? renameSync)(
+      transaction.recoveryPath,
+      transaction.retiredRecoveryPath,
+    );
+    (recoveryOperations.unlink ?? unlinkSync)(retiredOwnerPath);
+    cleanupRetiredRecoveryGate(
+      transaction.retiredRecoveryPath,
+      recoveryOperations,
+    );
+  } catch (error) {
+    if (error instanceof AtomicInstallInterruption) throw error;
+    cleanupFailed = true;
+  }
+  return cleanupFailed ? { ok: false, reason: "cleanup-failed" } : { ok: true };
+}