@hraness/ghostget 0.17.2

package/src/scripts/recover-install-stages.ts

@@ -0,0 +1,1491 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  opendirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+  type BigIntStats,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+import {
+  captureProcessOwnerIdentity,
+  processOwnerStatus,
+  type ProcessOwnerIdentity,
+} from "../process-identity";
+
+const maximumDirectoryEntries = 10_000;
+const maximumInstallStages = 64;
+const maximumInstallStageBytes = 64 * 1024;
+const maximumMutationClaims = 64;
+const TEST_BARRIER_TIMEOUT_MS = 90_000;
+const installStageNamePattern = /^\.(wrench|oh)-install\.[A-Za-z0-9]{6}$/u;
+const installLeaseName = ".wrench-install.lease";
+const installLeaseMarker = "wrench-install-lease-v1:";
+const installLeaseTokenPattern = /^[A-Za-z0-9_-]{32}$/u;
+const installMutationClaimPrefix = ".wrench-install.claim-";
+const installMutationClaimMarker = "wrench-install-claim-v1:";
+const installMutationRetiredClaimPrefix = ".wrench-install.retired-claim-";
+const installMutationClaimNamePattern =
+  /^\.wrench-install\.claim-(waiting|candidate|held)-([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/u;
+const installMutationRetiredClaimNamePattern =
+  /^\.wrench-install\.retired-claim-([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})-([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/u;
+const ghostgetManagedMarker =
+  "# Generated by the Ghostget local installer; safe to replace.";
+const predecessorManagedMarker =
+  "# Generated by skills/oh/scripts/install-local.sh; safe to replace.";
+
+type InstallStageSnapshot = {
+  readonly bytes: Buffer;
+  readonly name: string;
+  readonly path: string;
+  readonly stats: BigIntStats;
+};
+
+type ManagedWrapperSnapshot = {
+  readonly bytes: Buffer;
+  readonly path: string;
+  readonly stats: BigIntStats;
+};
+
+type InstallLeaseRecord = {
+  readonly schemaVersion: 1;
+  readonly owner: ProcessOwnerIdentity;
+  readonly token: string;
+};
+
+type InstallLeaseSnapshot = {
+  readonly path: string;
+  readonly record: InstallLeaseRecord;
+  readonly stats: BigIntStats;
+  readonly target: string;
+};
+
+type InstallMutationClaimPhase = "waiting" | "candidate" | "held";
+
+type InstallMutationClaimRecord = {
+  readonly schemaVersion: 1;
+  readonly kind: "wrench-install-lease-mutation-claim";
+  readonly claimId: string;
+  readonly owner: ProcessOwnerIdentity;
+};
+
+type InstallMutationClaimSnapshot = {
+  readonly path: string;
+  readonly phase: InstallMutationClaimPhase;
+  readonly record: InstallMutationClaimRecord;
+  readonly stats: BigIntStats;
+  readonly target: string;
+};
+
+type RetiredInstallMutationClaimSnapshot = Omit<
+  InstallMutationClaimSnapshot,
+  "phase"
+>;
+
+type HeldInstallMutationClaim = {
+  readonly directory: string;
+  readonly rootStats: BigIntStats;
+  readonly release: () => void;
+};
+
+class InstallMutationClaimChangedError extends Error {}
+
+export type InstallMutationClaimSnapshotFileSystemForTest = {
+  readonly lstat: (path: string) => BigIntStats;
+  readonly readlink: (path: string) => string;
+};
+
+const installMutationClaimSnapshotFileSystem:
+  InstallMutationClaimSnapshotFileSystemForTest = Object.freeze({
+  lstat: (path: string) => lstatSync(path, { bigint: true }),
+  readlink: (path: string) => readlinkSync(path, "utf8"),
+});
+
+function sameFileIdentity(left: BigIntStats, right: BigIntStats): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.size === right.size
+    && left.mode === right.mode
+    && left.uid === right.uid
+    && left.gid === right.gid
+    && left.nlink === right.nlink
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs;
+}
+
+function sameDirectoryObject(left: BigIntStats, right: BigIntStats): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.uid === right.uid
+    && left.gid === right.gid;
+}
+
+function ownedByCurrentUser(stats: BigIntStats): boolean {
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  return uid === undefined || stats.uid === BigInt(uid);
+}
+
+function requireStableInstallMutationClaimSymlink(
+  path: string,
+  before: BigIntStats,
+  label: "mutation claim" | "retired mutation claim",
+  fileSystem: InstallMutationClaimSnapshotFileSystemForTest,
+): void {
+  if (
+    before.isSymbolicLink()
+    && ownedByCurrentUser(before)
+    && before.nlink === 1n
+  ) {
+    return;
+  }
+  // APFS can expose a final transient lstat result while another owner unlinks
+  // the retired pathname. Confirm the invalid shape is stable before treating
+  // it as hostile state. A stable regular file or non-exact symlink still
+  // rejects; a vanished or changed object asks the bounded caller to rescan.
+  let after: BigIntStats;
+  try {
+    after = fileSystem.lstat(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      throw new InstallMutationClaimChangedError(
+        `local installer ${label} changed during inspection`,
+      );
+    }
+    throw error;
+  }
+  if (!sameFileIdentity(before, after)) {
+    throw new InstallMutationClaimChangedError(
+      `local installer ${label} changed during inspection`,
+    );
+  }
+  throw new Error(
+    `local installer ${label} must be an owned exact symbolic claim`,
+  );
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error instanceof Error && "code" in error
+    ? String(error.code)
+    : undefined;
+}
+
+function expectedMarker(name: string): string {
+  return name.startsWith(".wrench-install.")
+    ? ghostgetManagedMarker
+    : predecessorManagedMarker;
+}
+
+function validateRecoveryDirectory(directoryValue: string): {
+  readonly directory: string;
+  readonly stats: BigIntStats;
+} {
+  if (!directoryValue.startsWith("/")) {
+    throw new Error("local installer recovery directory must be absolute");
+  }
+  const directory = resolve(directoryValue);
+  if (basename(directory) === "") {
+    throw new Error("local installer recovery directory cannot be a filesystem root");
+  }
+  const stats = lstatSync(directory, { bigint: true });
+  if (
+    stats.isSymbolicLink()
+    || !stats.isDirectory()
+    || !ownedByCurrentUser(stats)
+  ) {
+    throw new Error("local installer recovery directory must be an owned real directory");
+  }
+  return Object.freeze({ directory, stats });
+}
+
+function encodeInstallLease(record: InstallLeaseRecord): string {
+  return `${installLeaseMarker}${Buffer.from(JSON.stringify(record), "utf8").toString("base64url")}`;
+}
+
+function parseInstallLease(target: string): InstallLeaseRecord {
+  if (!target.startsWith(installLeaseMarker) || target.length > 1_024) {
+    throw new Error("local installer lease has an invalid exact marker");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(
+      Buffer.from(target.slice(installLeaseMarker.length), "base64url").toString("utf8"),
+    );
+  } catch {
+    throw new Error("local installer lease has invalid owner metadata");
+  }
+  if (
+    typeof value !== "object"
+    || value === null
+    || Array.isArray(value)
+    || Object.keys(value).sort().join("\0")
+      !== ["owner", "schemaVersion", "token"].join("\0")
+  ) {
+    throw new Error("local installer lease has invalid owner metadata");
+  }
+  const candidate = value as Record<string, unknown>;
+  const owner = candidate["owner"];
+  if (
+    candidate["schemaVersion"] !== 1
+    || typeof owner !== "object"
+    || owner === null
+    || Array.isArray(owner)
+    || Object.keys(owner).sort().join("\0")
+      !== ["bootId", "pid", "processStartId"].join("\0")
+    || typeof candidate["token"] !== "string"
+    || !installLeaseTokenPattern.test(candidate["token"])
+  ) {
+    throw new Error("local installer lease has invalid owner metadata");
+  }
+  const ownerCandidate = owner as Record<string, unknown>;
+  if (
+    !Number.isSafeInteger(ownerCandidate["pid"])
+    || (ownerCandidate["pid"] as number) <= 0
+    || (ownerCandidate["pid"] as number) > 2_147_483_647
+    || typeof ownerCandidate["bootId"] !== "string"
+    || !/^[a-f0-9]{64}$/u.test(ownerCandidate["bootId"])
+    || typeof ownerCandidate["processStartId"] !== "string"
+    || !/^[a-f0-9]{64}$/u.test(ownerCandidate["processStartId"])
+  ) {
+    throw new Error("local installer lease has invalid owner metadata");
+  }
+  const record: InstallLeaseRecord = Object.freeze({
+    schemaVersion: 1,
+    owner: Object.freeze({
+      pid: ownerCandidate["pid"] as number,
+      bootId: ownerCandidate["bootId"],
+      processStartId: ownerCandidate["processStartId"],
+    }),
+    token: candidate["token"],
+  });
+  if (encodeInstallLease(record) !== target) {
+    throw new Error("local installer lease owner metadata is not canonical");
+  }
+  return record;
+}
+
+function installMutationClaimPath(
+  directory: string,
+  phase: InstallMutationClaimPhase,
+  claimId: string,
+): string {
+  return join(directory, `${installMutationClaimPrefix}${phase}-${claimId}`);
+}
+
+function parseInstallMutationClaimName(name: string): {
+  readonly phase: InstallMutationClaimPhase;
+  readonly claimId: string;
+} {
+  const match = installMutationClaimNamePattern.exec(name);
+  if (match === null) {
+    throw new Error("local installer mutation claim filename is invalid");
+  }
+  return Object.freeze({
+    phase: match[1] as InstallMutationClaimPhase,
+    claimId: match[2]!,
+  });
+}
+
+function encodeInstallMutationClaim(record: InstallMutationClaimRecord): string {
+  return `${installMutationClaimMarker}${Buffer.from(JSON.stringify(record), "utf8").toString("base64url")}`;
+}
+
+function parseInstallMutationClaim(
+  target: string,
+  expectedClaimId: string,
+): InstallMutationClaimRecord {
+  if (!target.startsWith(installMutationClaimMarker) || target.length > 1_024) {
+    throw new Error("local installer mutation claim has an invalid exact marker");
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(
+      Buffer.from(
+        target.slice(installMutationClaimMarker.length),
+        "base64url",
+      ).toString("utf8"),
+    );
+  } catch {
+    throw new Error("local installer mutation claim has invalid owner metadata");
+  }
+  if (
+    typeof value !== "object"
+    || value === null
+    || Array.isArray(value)
+    || Object.keys(value).sort().join("\0")
+      !== ["claimId", "kind", "owner", "schemaVersion"].join("\0")
+  ) {
+    throw new Error("local installer mutation claim has invalid owner metadata");
+  }
+  const candidate = value as Record<string, unknown>;
+  const owner = candidate["owner"];
+  if (
+    candidate["schemaVersion"] !== 1
+    || candidate["kind"] !== "wrench-install-lease-mutation-claim"
+    || candidate["claimId"] !== expectedClaimId
+    || typeof owner !== "object"
+    || owner === null
+    || Array.isArray(owner)
+    || Object.keys(owner).sort().join("\0")
+      !== ["bootId", "pid", "processStartId"].join("\0")
+  ) {
+    throw new Error("local installer mutation claim has invalid owner metadata");
+  }
+  const ownerCandidate = owner as Record<string, unknown>;
+  if (
+    !Number.isSafeInteger(ownerCandidate["pid"])
+    || (ownerCandidate["pid"] as number) <= 0
+    || (ownerCandidate["pid"] as number) > 2_147_483_647
+    || typeof ownerCandidate["bootId"] !== "string"
+    || !/^[a-f0-9]{64}$/u.test(ownerCandidate["bootId"])
+    || typeof ownerCandidate["processStartId"] !== "string"
+    || !/^[a-f0-9]{64}$/u.test(ownerCandidate["processStartId"])
+  ) {
+    throw new Error("local installer mutation claim has invalid owner metadata");
+  }
+  const record: InstallMutationClaimRecord = Object.freeze({
+    schemaVersion: 1,
+    kind: "wrench-install-lease-mutation-claim",
+    claimId: expectedClaimId,
+    owner: Object.freeze({
+      pid: ownerCandidate["pid"] as number,
+      bootId: ownerCandidate["bootId"],
+      processStartId: ownerCandidate["processStartId"],
+    }),
+  });
+  if (encodeInstallMutationClaim(record) !== target) {
+    throw new Error("local installer mutation claim metadata is not canonical");
+  }
+  return record;
+}
+
+function snapshotInstallMutationClaim(
+  directory: string,
+  name: string,
+  fileSystem: InstallMutationClaimSnapshotFileSystemForTest =
+    installMutationClaimSnapshotFileSystem,
+): InstallMutationClaimSnapshot | undefined {
+  const parsedName = parseInstallMutationClaimName(name);
+  const path = join(directory, name);
+  let before: BigIntStats;
+  try {
+    before = fileSystem.lstat(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+  requireStableInstallMutationClaimSymlink(
+    path,
+    before,
+    "mutation claim",
+    fileSystem,
+  );
+  let target: string;
+  let after: BigIntStats;
+  try {
+    target = fileSystem.readlink(path);
+    after = fileSystem.lstat(path);
+    if (
+      !sameFileIdentity(before, after)
+      || fileSystem.readlink(path) !== target
+    ) {
+      throw new InstallMutationClaimChangedError(
+        "local installer mutation claim changed during inspection",
+      );
+    }
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    if (errorCode(error) === "EINVAL") {
+      throw new InstallMutationClaimChangedError(
+        "local installer mutation claim changed during inspection",
+      );
+    }
+    throw error;
+  }
+  return Object.freeze({
+    path,
+    phase: parsedName.phase,
+    record: parseInstallMutationClaim(target, parsedName.claimId),
+    stats: after,
+    target,
+  });
+}
+
+function removeExactInstallMutationClaim(
+  snapshot: InstallMutationClaimSnapshot,
+): boolean {
+  let current: InstallMutationClaimSnapshot | undefined;
+  try {
+    current = snapshotInstallMutationClaim(
+      resolve(snapshot.path, ".."),
+      basename(snapshot.path),
+    );
+  } catch (error) {
+    if (error instanceof InstallMutationClaimChangedError) return false;
+    throw error;
+  }
+  if (current === undefined) return false;
+  if (
+    !sameFileIdentity(snapshot.stats, current.stats)
+    || snapshot.target !== current.target
+  ) {
+    return false;
+  }
+
+  // Claim pathnames are never reused. Moving the exact inode to a fresh,
+  // non-claim pathname before unlinking means two stale reclaimers can race
+  // without either one ever unlinking a later claimant at the old pathname.
+  const retiredPath = join(
+    resolve(snapshot.path, ".."),
+    `${installMutationRetiredClaimPrefix}${snapshot.record.claimId}-${randomUUID()}`,
+  );
+  try {
+    renameSync(snapshot.path, retiredPath);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return false;
+    throw error;
+  }
+  const retiredStats = lstatSync(retiredPath, { bigint: true });
+  if (
+    retiredStats.dev !== snapshot.stats.dev
+    || retiredStats.ino !== snapshot.stats.ino
+    || readlinkSync(retiredPath, "utf8") !== snapshot.target
+  ) {
+    throw new Error("local installer mutation claim changed during retirement");
+  }
+  pauseAfterRetiringInstallMutationClaimForTest();
+  const finalStats = lstatSync(retiredPath, { bigint: true });
+  if (
+    !sameFileIdentity(retiredStats, finalStats)
+    || readlinkSync(retiredPath, "utf8") !== snapshot.target
+  ) {
+    throw new Error("local installer retired mutation claim changed before removal");
+  }
+  unlinkSync(retiredPath);
+  return true;
+}
+
+function snapshotRetiredInstallMutationClaim(
+  directory: string,
+  name: string,
+  fileSystem: InstallMutationClaimSnapshotFileSystemForTest =
+    installMutationClaimSnapshotFileSystem,
+): RetiredInstallMutationClaimSnapshot | undefined {
+  const match = installMutationRetiredClaimNamePattern.exec(name);
+  if (match === null) {
+    throw new Error("local installer retired mutation claim filename is invalid");
+  }
+  const claimId = match[1]!;
+  const path = join(directory, name);
+  let before: BigIntStats;
+  try {
+    before = fileSystem.lstat(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+  requireStableInstallMutationClaimSymlink(
+    path,
+    before,
+    "retired mutation claim",
+    fileSystem,
+  );
+  let target: string;
+  let after: BigIntStats;
+  try {
+    target = fileSystem.readlink(path);
+    after = fileSystem.lstat(path);
+    if (
+      !sameFileIdentity(before, after)
+      || fileSystem.readlink(path) !== target
+    ) {
+      throw new InstallMutationClaimChangedError(
+        "local installer retired mutation claim changed during inspection",
+      );
+    }
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    if (errorCode(error) === "EINVAL") {
+      throw new InstallMutationClaimChangedError(
+        "local installer retired mutation claim changed during inspection",
+      );
+    }
+    throw error;
+  }
+  return Object.freeze({
+    path,
+    record: parseInstallMutationClaim(target, claimId),
+    stats: after,
+    target,
+  });
+}
+
+export function snapshotRetiredInstallMutationClaimForTest(
+  directory: string,
+  name: string,
+  fileSystem: InstallMutationClaimSnapshotFileSystemForTest,
+): "absent" | "changed" | "present" {
+  try {
+    return snapshotRetiredInstallMutationClaim(directory, name, fileSystem)
+      === undefined
+      ? "absent"
+      : "present";
+  } catch (error) {
+    if (error instanceof InstallMutationClaimChangedError) return "changed";
+    throw error;
+  }
+}
+
+function removeExactRetiredInstallMutationClaim(
+  snapshot: RetiredInstallMutationClaimSnapshot,
+): boolean {
+  let current: RetiredInstallMutationClaimSnapshot | undefined;
+  try {
+    current = snapshotRetiredInstallMutationClaim(
+      resolve(snapshot.path, ".."),
+      basename(snapshot.path),
+    );
+  } catch (error) {
+    if (error instanceof InstallMutationClaimChangedError) return false;
+    throw error;
+  }
+  if (current === undefined) return false;
+  if (
+    !sameFileIdentity(snapshot.stats, current.stats)
+    || snapshot.target !== current.target
+  ) {
+    return false;
+  }
+  try {
+    unlinkSync(snapshot.path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return false;
+    throw error;
+  }
+  return true;
+}
+
+function boundedInstallMutationEntryNames(
+  directory: string,
+  prefix: string,
+): readonly string[] {
+  const names: string[] = [];
+  const handle = opendirSync(directory);
+  try {
+    let entryCount = 0;
+    for (;;) {
+      const entry = handle.readSync();
+      if (entry === null) break;
+      entryCount += 1;
+      if (entryCount > maximumDirectoryEntries) {
+        throw new Error(
+          `local installer recovery directory exceeds ${maximumDirectoryEntries} entries`,
+        );
+      }
+      if (entry.name.startsWith(prefix)) names.push(entry.name);
+    }
+  } finally {
+    handle.closeSync();
+  }
+  return names.sort();
+}
+
+function recoverRetiredInstallMutationClaims(directory: string): void {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const names = boundedInstallMutationEntryNames(
+      directory,
+      installMutationRetiredClaimPrefix,
+    );
+    let retry = false;
+    let removed = false;
+    let liveCount = 0;
+    for (const name of names) {
+      let snapshot: RetiredInstallMutationClaimSnapshot | undefined;
+      try {
+        snapshot = snapshotRetiredInstallMutationClaim(directory, name);
+      } catch (error) {
+        if (error instanceof InstallMutationClaimChangedError) {
+          retry = true;
+          break;
+        }
+        throw error;
+      }
+      if (snapshot === undefined) {
+        retry = true;
+        break;
+      }
+      const status = processOwnerStatus(snapshot.record.owner);
+      if (status === "unknown") {
+        throw new Error(
+          "local installer retired mutation claim owner identity cannot be determined safely",
+        );
+      }
+      if (status === "exact-live-owner") {
+        liveCount += 1;
+        continue;
+      }
+      if (removeExactRetiredInstallMutationClaim(snapshot)) {
+        removed = true;
+      } else {
+        retry = true;
+        break;
+      }
+    }
+    if (retry || removed) continue;
+    if (liveCount > maximumMutationClaims) {
+      throw new Error(
+        `local installer live retired mutation claim count exceeds ${maximumMutationClaims}`,
+      );
+    }
+    return;
+  }
+  throw new Error(
+    "local installer retired mutation claims did not reach a stable snapshot",
+  );
+}
+
+function listLiveInstallMutationClaims(
+  directory: string,
+): readonly InstallMutationClaimSnapshot[] {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    recoverRetiredInstallMutationClaims(directory);
+    const names = boundedInstallMutationEntryNames(
+      directory,
+      installMutationClaimPrefix,
+    );
+    let retry = false;
+    let removedStaleClaim = false;
+    const live: InstallMutationClaimSnapshot[] = [];
+    for (const name of names) {
+      let snapshot: InstallMutationClaimSnapshot | undefined;
+      try {
+        snapshot = snapshotInstallMutationClaim(directory, name);
+      } catch (error) {
+        if (error instanceof InstallMutationClaimChangedError) {
+          retry = true;
+          break;
+        }
+        throw error;
+      }
+      if (snapshot === undefined) {
+        retry = true;
+        break;
+      }
+      const status = processOwnerStatus(snapshot.record.owner);
+      if (status === "unknown") {
+        throw new Error(
+          "local installer mutation claim owner identity cannot be determined safely",
+        );
+      }
+      if (status === "different-or-dead") {
+        if (removeExactInstallMutationClaim(snapshot)) {
+          removedStaleClaim = true;
+        } else {
+          retry = true;
+          break;
+        }
+        continue;
+      }
+      live.push(snapshot);
+    }
+    if (retry || removedStaleClaim) continue;
+    if (live.length > maximumMutationClaims) {
+      throw new Error(
+        `local installer live mutation claim count exceeds ${maximumMutationClaims}`,
+      );
+    }
+    return live;
+  }
+  throw new Error("local installer mutation claims did not reach a stable snapshot");
+}
+
+function waitAtInstallMutationClaimTestBarrier(
+  readyPath: string,
+  releasePath: string,
+  label: string,
+): void {
+  try {
+    writeFileSync(readyPath, `${process.pid}\n`, { flag: "wx", mode: 0o600 });
+  } catch (error) {
+    if (errorCode(error) !== "EEXIST") throw error;
+  }
+  const deadline = Date.now() + TEST_BARRIER_TIMEOUT_MS;
+  while (!existsSync(releasePath)) {
+    if (Date.now() >= deadline) {
+      throw new Error(`local installer ${label} test barrier timed out`);
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+  }
+}
+
+function pauseAfterWaitingInstallMutationClaimForTest(claimId: string): void {
+  if (process.env.NODE_ENV !== "test") return;
+  const readyDirectory =
+    (process.env.GHOSTGET_TEST_INSTALL_MUTATION_WAITING_READY_DIRECTORY ?? process.env.WRENCH_TEST_INSTALL_MUTATION_WAITING_READY_DIRECTORY);
+  const releasePath =
+    (process.env.GHOSTGET_TEST_INSTALL_MUTATION_WAITING_RELEASE ?? process.env.WRENCH_TEST_INSTALL_MUTATION_WAITING_RELEASE);
+  if (readyDirectory === undefined || releasePath === undefined) return;
+  waitAtInstallMutationClaimTestBarrier(
+    join(readyDirectory, `${claimId}.ready`),
+    releasePath,
+    "waiting-claim",
+  );
+}
+
+function pauseAfterHeldInstallMutationClaimForTest(): void {
+  if (process.env.NODE_ENV !== "test") return;
+  const readyPath = (process.env.GHOSTGET_TEST_INSTALL_MUTATION_HELD_READY ?? process.env.WRENCH_TEST_INSTALL_MUTATION_HELD_READY);
+  const releasePath = (process.env.GHOSTGET_TEST_INSTALL_MUTATION_HELD_RELEASE ?? process.env.WRENCH_TEST_INSTALL_MUTATION_HELD_RELEASE);
+  if (readyPath === undefined || releasePath === undefined) return;
+  waitAtInstallMutationClaimTestBarrier(
+    readyPath,
+    releasePath,
+    "held-claim",
+  );
+}
+
+function pauseBeforeInstallLeaseRemovalForTest(): void {
+  if (process.env.NODE_ENV !== "test") return;
+  const readyPath = (process.env.GHOSTGET_TEST_INSTALL_RELEASE_READY ?? process.env.WRENCH_TEST_INSTALL_RELEASE_READY);
+  const releasePath = (process.env.GHOSTGET_TEST_INSTALL_RELEASE_RELEASE ?? process.env.WRENCH_TEST_INSTALL_RELEASE_RELEASE);
+  if (readyPath === undefined || releasePath === undefined) return;
+  waitAtInstallMutationClaimTestBarrier(
+    readyPath,
+    releasePath,
+    "lease-release",
+  );
+}
+
+function pauseAfterRetiringInstallMutationClaimForTest(): void {
+  if (process.env.NODE_ENV !== "test") return;
+  const readyPath = (process.env.GHOSTGET_TEST_INSTALL_MUTATION_RETIRED_READY ?? process.env.WRENCH_TEST_INSTALL_MUTATION_RETIRED_READY);
+  const releasePath = (process.env.GHOSTGET_TEST_INSTALL_MUTATION_RETIRED_RELEASE ?? process.env.WRENCH_TEST_INSTALL_MUTATION_RETIRED_RELEASE);
+  if (readyPath === undefined || releasePath === undefined) return;
+  waitAtInstallMutationClaimTestBarrier(
+    readyPath,
+    releasePath,
+    "retired-claim",
+  );
+}
+
+function pauseBeforeManagedWrapperMutationForTest(): void {
+  if (process.env.NODE_ENV !== "test") return;
+  const readyPath = (process.env.GHOSTGET_TEST_INSTALL_TARGET_MUTATION_READY ?? process.env.WRENCH_TEST_INSTALL_TARGET_MUTATION_READY);
+  const releasePath = (process.env.GHOSTGET_TEST_INSTALL_TARGET_MUTATION_RELEASE ?? process.env.WRENCH_TEST_INSTALL_TARGET_MUTATION_RELEASE);
+  if (readyPath === undefined || releasePath === undefined) return;
+  waitAtInstallMutationClaimTestBarrier(
+    readyPath,
+    releasePath,
+    "managed-wrapper-mutation",
+  );
+}
+
+function renameOwnedInstallMutationClaim(
+  directory: string,
+  fromPhase: InstallMutationClaimPhase,
+  toPhase: InstallMutationClaimPhase,
+  claimId: string,
+  expectedTarget: string,
+): string {
+  const fromPath = installMutationClaimPath(directory, fromPhase, claimId);
+  const before = snapshotInstallMutationClaim(directory, basename(fromPath));
+  if (before === undefined || before.target !== expectedTarget) {
+    throw new Error("local installer mutation claim changed before promotion");
+  }
+  const toPath = installMutationClaimPath(directory, toPhase, claimId);
+  renameSync(fromPath, toPath);
+  const after = snapshotInstallMutationClaim(directory, basename(toPath));
+  if (
+    after === undefined
+    || after.target !== expectedTarget
+    || after.stats.dev !== before.stats.dev
+    || after.stats.ino !== before.stats.ino
+  ) {
+    throw new Error("local installer mutation claim changed during promotion");
+  }
+  return toPath;
+}
+
+function acquireInstallMutationClaim(
+  directoryValue: string,
+): HeldInstallMutationClaim | undefined {
+  const { directory, stats: rootStats } = validateRecoveryDirectory(directoryValue);
+  const claimId = randomUUID();
+  const record: InstallMutationClaimRecord = Object.freeze({
+    schemaVersion: 1,
+    kind: "wrench-install-lease-mutation-claim",
+    claimId,
+    owner: captureProcessOwnerIdentity(process.pid),
+  });
+  const target = encodeInstallMutationClaim(record);
+  let phase: InstallMutationClaimPhase = "waiting";
+  let claimPath = installMutationClaimPath(directory, phase, claimId);
+  symlinkSync(target, claimPath);
+  let released = false;
+  const release = (): void => {
+    if (released) return;
+    const snapshot = snapshotInstallMutationClaim(directory, basename(claimPath));
+    if (snapshot === undefined || snapshot.target !== target) {
+      throw new Error("local installer mutation claim changed before release");
+    }
+    if (!removeExactInstallMutationClaim(snapshot)) {
+      throw new Error("local installer mutation claim changed during release");
+    }
+    released = true;
+  };
+  try {
+    pauseAfterWaitingInstallMutationClaimForTest(claimId);
+    const waiting = listLiveInstallMutationClaims(directory);
+    if (
+      waiting.some((candidate) =>
+        candidate.record.claimId !== claimId
+        && (
+          candidate.phase !== "waiting"
+          || candidate.record.claimId < claimId
+        )
+      )
+    ) {
+      release();
+      return undefined;
+    }
+
+    claimPath = renameOwnedInstallMutationClaim(
+      directory,
+      phase,
+      "candidate",
+      claimId,
+      target,
+    );
+    phase = "candidate";
+    const candidates = listLiveInstallMutationClaims(directory);
+    if (
+      candidates.some((candidate) =>
+        candidate.record.claimId !== claimId
+        && (
+          candidate.phase === "held"
+          || candidate.record.claimId < claimId
+        )
+      )
+    ) {
+      release();
+      return undefined;
+    }
+
+    claimPath = renameOwnedInstallMutationClaim(
+      directory,
+      phase,
+      "held",
+      claimId,
+      target,
+    );
+    phase = "held";
+    const held = listLiveInstallMutationClaims(directory);
+    if (
+      held.some((candidate) =>
+        candidate.record.claimId !== claimId && candidate.phase === "held"
+      )
+    ) {
+      throw new Error("local installer mutation arbitration admitted two owners");
+    }
+    const rootAfter = lstatSync(directory, { bigint: true });
+    if (!sameDirectoryObject(rootStats, rootAfter)) {
+      throw new Error("local installer recovery directory changed during arbitration");
+    }
+    pauseAfterHeldInstallMutationClaimForTest();
+    return Object.freeze({ directory, rootStats, release });
+  } catch (error) {
+    if (!released) release();
+    throw error;
+  }
+}
+
+function snapshotInstallLease(directory: string): InstallLeaseSnapshot | undefined {
+  const path = join(directory, installLeaseName);
+  let before: BigIntStats;
+  try {
+    before = lstatSync(path, { bigint: true });
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+  if (
+    !before.isSymbolicLink()
+    || !ownedByCurrentUser(before)
+    || before.nlink !== 1n
+  ) {
+    throw new Error("local installer lease must be an owned exact symbolic lease");
+  }
+  const target = readlinkSync(path, "utf8");
+  const after = lstatSync(path, { bigint: true });
+  if (!sameFileIdentity(before, after) || readlinkSync(path, "utf8") !== target) {
+    throw new Error("local installer lease changed during inspection");
+  }
+  return Object.freeze({
+    path,
+    record: parseInstallLease(target),
+    stats: after,
+    target,
+  });
+}
+
+function assertLeaseUnchanged(snapshot: InstallLeaseSnapshot): void {
+  const current = lstatSync(snapshot.path, { bigint: true });
+  if (
+    !sameFileIdentity(snapshot.stats, current)
+    || readlinkSync(snapshot.path, "utf8") !== snapshot.target
+  ) {
+    throw new Error("local installer lease changed before removal");
+  }
+}
+
+function leaseIsStale(snapshot: InstallLeaseSnapshot): boolean {
+  const status = processOwnerStatus(snapshot.record.owner);
+  if (status === "unknown") {
+    throw new Error("local installer lease owner identity cannot be determined safely");
+  }
+  return status === "different-or-dead";
+}
+
+function snapshotManagedInstallStage(
+  directory: string,
+  name: string,
+): InstallStageSnapshot {
+  const path = join(directory, name);
+  const lexical = lstatSync(path, { bigint: true });
+  const permissions = lexical.mode & 0o777n;
+  const hasAcceptedStageMode = permissions === 0o600n
+    || permissions === 0o700n
+    || (name.startsWith(".oh-install.") && permissions === 0o755n);
+  if (
+    lexical.isSymbolicLink()
+    || !lexical.isFile()
+    || !ownedByCurrentUser(lexical)
+    || lexical.nlink !== 1n
+    || !hasAcceptedStageMode
+    || lexical.size < 0n
+    || lexical.size > BigInt(maximumInstallStageBytes)
+  ) {
+    throw new Error(
+      `abandoned local installer stage ${name} is not an owned private bounded regular file`,
+    );
+  }
+
+  const descriptor = openSync(
+    path,
+    constants.O_RDONLY
+      | (constants.O_NOFOLLOW ?? 0)
+      | (constants.O_NONBLOCK ?? 0),
+  );
+  try {
+    const before = fstatSync(descriptor, { bigint: true });
+    if (!sameFileIdentity(lexical, before)) {
+      throw new Error(`abandoned local installer stage ${name} changed before inspection`);
+    }
+    const bytes = readFileSync(descriptor);
+    const after = fstatSync(descriptor, { bigint: true });
+    const finalLexical = lstatSync(path, { bigint: true });
+    if (
+      bytes.byteLength > maximumInstallStageBytes
+      || !sameFileIdentity(before, after)
+      || !sameFileIdentity(after, finalLexical)
+    ) {
+      throw new Error(`abandoned local installer stage ${name} changed during inspection`);
+    }
+    let content: string;
+    try {
+      content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } catch {
+      throw new Error(`abandoned local installer stage ${name} is not valid UTF-8`);
+    }
+    const marker = expectedMarker(name);
+    const managedHeader = `#!/bin/sh\n${marker}\n`;
+    const isInterruptedManagedPrefix = managedHeader.startsWith(content);
+    if (
+      !isInterruptedManagedPrefix
+      && !content.split("\n").includes(marker)
+    ) {
+      throw new Error(`abandoned local installer stage ${name} is not managed by Ghostget`);
+    }
+    return Object.freeze({
+      bytes: Buffer.from(bytes),
+      name,
+      path,
+      stats: finalLexical,
+    });
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function snapshotManagedWrapperIfPresent(
+  directory: string,
+  name: "oh" | "wrench",
+  marker: string,
+): ManagedWrapperSnapshot | undefined {
+  const path = join(directory, name);
+  let lexical: BigIntStats;
+  try {
+    lexical = lstatSync(path, { bigint: true });
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+  const permissions = lexical.mode & 0o777n;
+  if (
+    lexical.isSymbolicLink()
+    || !lexical.isFile()
+    || !ownedByCurrentUser(lexical)
+    || lexical.nlink !== 1n
+    || (permissions !== 0o700n && permissions !== 0o755n)
+    || lexical.size < 0n
+    || lexical.size > BigInt(maximumInstallStageBytes)
+  ) {
+    throw new Error(
+      `managed ${name} wrapper must be an owned, singly linked, bounded executable file`,
+    );
+  }
+  const descriptor = openSync(
+    path,
+    constants.O_RDONLY
+      | (constants.O_NOFOLLOW ?? 0)
+      | (constants.O_NONBLOCK ?? 0),
+  );
+  try {
+    const before = fstatSync(descriptor, { bigint: true });
+    if (!sameFileIdentity(lexical, before)) {
+      throw new Error(`managed ${name} wrapper changed before inspection`);
+    }
+    const bytes = readFileSync(descriptor);
+    const after = fstatSync(descriptor, { bigint: true });
+    const finalLexical = lstatSync(path, { bigint: true });
+    if (
+      bytes.byteLength > maximumInstallStageBytes
+      || !sameFileIdentity(before, after)
+      || !sameFileIdentity(after, finalLexical)
+    ) {
+      throw new Error(`managed ${name} wrapper changed during inspection`);
+    }
+    let content: string;
+    try {
+      content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } catch {
+      throw new Error(`managed ${name} wrapper is not valid UTF-8`);
+    }
+    if (!content.split("\n").includes(marker)) {
+      throw new Error(`managed ${name} wrapper ownership marker is missing`);
+    }
+    return Object.freeze({
+      bytes: Buffer.from(bytes),
+      path,
+      stats: finalLexical,
+    });
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function assertManagedWrapperUnchanged(
+  snapshot: ManagedWrapperSnapshot,
+): void {
+  const current = lstatSync(snapshot.path, { bigint: true });
+  if (!sameFileIdentity(snapshot.stats, current)) {
+    throw new Error("managed local wrapper changed before mutation");
+  }
+}
+
+function validateOwnedLiveInstallLease(
+  directory: string,
+  ownerPid: number,
+  token: string,
+): InstallLeaseSnapshot {
+  if (!Number.isSafeInteger(ownerPid) || ownerPid <= 0 || ownerPid > 2_147_483_647) {
+    throw new Error("local installer lease owner PID is invalid");
+  }
+  if (!installLeaseTokenPattern.test(token)) {
+    throw new Error("local installer lease token is invalid");
+  }
+  const lease = snapshotInstallLease(directory);
+  if (
+    lease === undefined
+    || lease.record.owner.pid !== ownerPid
+    || lease.record.token !== token
+  ) {
+    throw new Error("local installer lease is not owned by this installer");
+  }
+  if (processOwnerStatus(lease.record.owner) !== "exact-live-owner") {
+    throw new Error("local installer lease owner is no longer live");
+  }
+  return lease;
+}
+
+/**
+ * Publish the exact staged wrapper inside the helper that owns mutation
+ * arbitration. If the parent shell dies, this helper either completes its one
+ * atomic rename before releasing arbitration or is itself proven dead before a
+ * successor may proceed; no orphaned mv process exists.
+ */
+export function publishManagedInstallWrapper(
+  directoryValue: string,
+  ownerPid: number,
+  token: string,
+  stageValue: string,
+): "already-installed" | "installed" {
+  const claim = acquireInstallMutationClaim(directoryValue);
+  if (claim === undefined) {
+    throw new Error("another Ghostget installer lease mutation helper is active");
+  }
+  try {
+    const lease = validateOwnedLiveInstallLease(
+      claim.directory,
+      ownerPid,
+      token,
+    );
+    if (!stageValue.startsWith("/")) {
+      throw new Error("local installer wrapper stage must be absolute");
+    }
+    const stagePath = resolve(stageValue);
+    const stageName = basename(stagePath);
+    if (
+      stagePath !== join(claim.directory, stageName)
+      || !stageName.startsWith(".wrench-install.")
+      || !installStageNamePattern.test(stageName)
+    ) {
+      throw new Error("local installer wrapper stage is not an exact Ghostget stage");
+    }
+    const stage = snapshotManagedInstallStage(claim.directory, stageName);
+    const target = snapshotManagedWrapperIfPresent(
+      claim.directory,
+      "wrench",
+      ghostgetManagedMarker,
+    );
+    pauseBeforeManagedWrapperMutationForTest();
+    assertLeaseUnchanged(lease);
+    const rootBeforeMutation = lstatSync(claim.directory, { bigint: true });
+    if (!sameDirectoryObject(claim.rootStats, rootBeforeMutation)) {
+      throw new Error("local installer recovery directory changed before publication");
+    }
+    const stageBeforeMutation = lstatSync(stage.path, { bigint: true });
+    if (!sameFileIdentity(stage.stats, stageBeforeMutation)) {
+      throw new Error("local installer wrapper stage changed before publication");
+    }
+    if (target !== undefined) assertManagedWrapperUnchanged(target);
+
+    if (target !== undefined && target.bytes.equals(stage.bytes)) {
+      unlinkSync(stage.path);
+      return "already-installed";
+    }
+    renameSync(stage.path, join(claim.directory, "wrench"));
+    const published = snapshotManagedWrapperIfPresent(
+      claim.directory,
+      "wrench",
+      ghostgetManagedMarker,
+    );
+    if (
+      published === undefined
+      || published.stats.dev !== stage.stats.dev
+      || published.stats.ino !== stage.stats.ino
+      || !published.bytes.equals(stage.bytes)
+    ) {
+      throw new Error("managed Ghostget wrapper changed during atomic publication");
+    }
+    return "installed";
+  } finally {
+    claim.release();
+  }
+}
+
+/** Remove one exact managed wrapper without delegating unlink to a child. */
+export function removeManagedInstallWrapper(
+  directoryValue: string,
+  ownerPid: number,
+  token: string,
+  name: "oh" | "wrench",
+): void {
+  const claim = acquireInstallMutationClaim(directoryValue);
+  if (claim === undefined) {
+    throw new Error("another Ghostget installer lease mutation helper is active");
+  }
+  try {
+    const lease = validateOwnedLiveInstallLease(
+      claim.directory,
+      ownerPid,
+      token,
+    );
+    const target = snapshotManagedWrapperIfPresent(
+      claim.directory,
+      name,
+      name === "wrench" ? ghostgetManagedMarker : predecessorManagedMarker,
+    );
+    if (target === undefined) {
+      throw new Error(`managed ${name} wrapper disappeared before removal`);
+    }
+    pauseBeforeManagedWrapperMutationForTest();
+    assertLeaseUnchanged(lease);
+    const rootBeforeMutation = lstatSync(claim.directory, { bigint: true });
+    if (!sameDirectoryObject(claim.rootStats, rootBeforeMutation)) {
+      throw new Error("local installer recovery directory changed before wrapper removal");
+    }
+    assertManagedWrapperUnchanged(target);
+    unlinkSync(target.path);
+  } finally {
+    claim.release();
+  }
+}
+
+function recoverInstallStagesUnderClaim(directoryValue: string): number {
+  const { directory, stats: rootBefore } = validateRecoveryDirectory(directoryValue);
+  const lease = snapshotInstallLease(directory);
+  let removeLease = false;
+  if (lease !== undefined) {
+    if (!leaseIsStale(lease)) {
+      throw new Error(
+        `another Ghostget installer is active with process ${lease.record.owner.pid}`,
+      );
+    }
+    removeLease = true;
+  }
+
+  const candidateNames: string[] = [];
+  const handle = opendirSync(directory);
+  try {
+    let entryCount = 0;
+    for (;;) {
+      const entry = handle.readSync();
+      if (entry === null) break;
+      entryCount += 1;
+      if (entryCount > maximumDirectoryEntries) {
+        throw new Error(
+          `local installer recovery directory exceeds ${maximumDirectoryEntries} entries`,
+        );
+      }
+      if (!installStageNamePattern.test(entry.name)) continue;
+      candidateNames.push(entry.name);
+      if (candidateNames.length > maximumInstallStages) {
+        throw new Error(
+          `local installer recovery found more than ${maximumInstallStages} exact stages`,
+        );
+      }
+    }
+  } finally {
+    handle.closeSync();
+  }
+
+  candidateNames.sort();
+  const snapshots = candidateNames.map((name) =>
+    snapshotManagedInstallStage(directory, name)
+  );
+  const rootAfterValidation = lstatSync(directory, { bigint: true });
+  if (!sameDirectoryObject(rootBefore, rootAfterValidation)) {
+    throw new Error("local installer recovery directory changed during inspection");
+  }
+  if (lease !== undefined) {
+    assertLeaseUnchanged(lease);
+    if (!leaseIsStale(lease)) {
+      throw new Error(
+        `another Ghostget installer is active with process ${lease.record.owner.pid}`,
+      );
+    }
+  }
+  for (const snapshot of snapshots) {
+    const current = lstatSync(snapshot.path, { bigint: true });
+    if (!sameFileIdentity(snapshot.stats, current)) {
+      throw new Error(
+        `abandoned local installer stage ${snapshot.name} changed before removal`,
+      );
+    }
+  }
+  for (const snapshot of snapshots) unlinkSync(snapshot.path);
+  if (removeLease && lease !== undefined) {
+    assertLeaseUnchanged(lease);
+    unlinkSync(lease.path);
+  }
+  return snapshots.length;
+}
+
+/**
+ * Acquire the exact installation lease and recover stages whose prior owner is
+ * proven dead. The symbolic lease makes its complete owner record visible in
+ * one atomic filesystem operation, so no empty-marker race exists.
+ */
+export function acquireInstallLease(directoryValue: string, ownerPid: number): string {
+  if (!Number.isSafeInteger(ownerPid) || ownerPid <= 0 || ownerPid > 2_147_483_647) {
+    throw new Error("local installer lease owner PID is invalid");
+  }
+  const claim = acquireInstallMutationClaim(directoryValue);
+  if (claim === undefined) {
+    throw new Error("another Ghostget installer lease mutation helper is active");
+  }
+  const { directory, rootStats } = claim;
+  let publishedLease: InstallLeaseSnapshot | undefined;
+  try {
+    const owner = captureProcessOwnerIdentity(ownerPid);
+    if (processOwnerStatus(owner) !== "exact-live-owner") {
+      throw new Error("local installer lease owner is no longer live");
+    }
+    recoverInstallStagesUnderClaim(directory);
+    const token = randomBytes(24).toString("base64url");
+    const record: InstallLeaseRecord = Object.freeze({
+      schemaVersion: 1,
+      owner,
+      token,
+    });
+    const path = join(directory, installLeaseName);
+    symlinkSync(encodeInstallLease(record), path);
+    const rootAfter = lstatSync(directory, { bigint: true });
+    if (!sameDirectoryObject(rootStats, rootAfter)) {
+      throw new Error("local installer recovery directory changed during lease acquisition");
+    }
+    const lease = snapshotInstallLease(directory);
+    if (
+      lease === undefined
+      || lease.record.owner.pid !== ownerPid
+      || lease.record.token !== token
+      || lease.record.owner.bootId !== owner.bootId
+      || lease.record.owner.processStartId !== owner.processStartId
+    ) {
+      throw new Error("local installer lease changed during acquisition");
+    }
+    publishedLease = lease;
+    if (processOwnerStatus(owner) !== "exact-live-owner") {
+      throw new Error("local installer lease owner died during acquisition");
+    }
+    return token;
+  } catch (error) {
+    if (publishedLease !== undefined) {
+      assertLeaseUnchanged(publishedLease);
+      unlinkSync(publishedLease.path);
+    }
+    throw error;
+  } finally {
+    claim.release();
+  }
+}
+
+/** Release only the exact lease still owned by this live installer process. */
+export function releaseInstallLease(
+  directoryValue: string,
+  ownerPid: number,
+  token: string,
+): void {
+  if (!Number.isSafeInteger(ownerPid) || ownerPid <= 0 || ownerPid > 2_147_483_647) {
+    throw new Error("local installer lease owner PID is invalid");
+  }
+  if (!installLeaseTokenPattern.test(token)) {
+    throw new Error("local installer lease release token is invalid");
+  }
+  const claim = acquireInstallMutationClaim(directoryValue);
+  if (claim === undefined) {
+    throw new Error("another Ghostget installer lease mutation helper is active");
+  }
+  try {
+    const lease = snapshotInstallLease(claim.directory);
+    if (
+      lease === undefined
+      || lease.record.owner.pid !== ownerPid
+      || lease.record.token !== token
+    ) {
+      throw new Error("local installer lease is not owned by this installer");
+    }
+    if (processOwnerStatus(lease.record.owner) !== "exact-live-owner") {
+      throw new Error("local installer lease release owner is no longer live");
+    }
+    pauseBeforeInstallLeaseRemovalForTest();
+    assertLeaseUnchanged(lease);
+    if (processOwnerStatus(lease.record.owner) !== "exact-live-owner") {
+      throw new Error("local installer lease release owner died before removal");
+    }
+    const rootBeforeRemoval = lstatSync(claim.directory, { bigint: true });
+    if (!sameDirectoryObject(claim.rootStats, rootBeforeRemoval)) {
+      throw new Error("local installer recovery directory changed before lease release");
+    }
+    unlinkSync(lease.path);
+  } finally {
+    claim.release();
+  }
+}
+
+/**
+ * Remove only exact, inode-stable stages left by a killed Ghostget or Oh local
+ * installer. A live exact installer lease always prevents stage removal.
+ */
+export function recoverAbandonedInstallStages(directoryValue: string): number {
+  const claim = acquireInstallMutationClaim(directoryValue);
+  if (claim === undefined) {
+    throw new Error("another Ghostget installer lease mutation helper is active");
+  }
+  try {
+    return recoverInstallStagesUnderClaim(claim.directory);
+  } finally {
+    claim.release();
+  }
+}
+
+function parseOwnerPid(value: string): number {
+  if (!/^[1-9]\d{0,9}$/u.test(value)) {
+    throw new Error("local installer lease owner PID must be an exact positive integer");
+  }
+  return Number(value);
+}
+
+function parseManagedWrapperName(value: string): "oh" | "wrench" {
+  if (value !== "oh" && value !== "wrench") {
+    throw new Error("managed local wrapper name must be exactly oh or wrench");
+  }
+  return value;
+}
+
+if (import.meta.main) {
+  try {
+    const arguments_ = process.argv.slice(2);
+    if (arguments_.length === 1) {
+      recoverAbandonedInstallStages(arguments_[0] ?? "");
+    } else if (arguments_.length === 3 && arguments_[0] === "acquire") {
+      const token = acquireInstallLease(
+        arguments_[1] ?? "",
+        parseOwnerPid(arguments_[2] ?? ""),
+      );
+      process.stdout.write(`${token}\n`);
+    } else if (arguments_.length === 4 && arguments_[0] === "release") {
+      releaseInstallLease(
+        arguments_[1] ?? "",
+        parseOwnerPid(arguments_[2] ?? ""),
+        arguments_[3] ?? "",
+      );
+    } else if (arguments_.length === 5 && arguments_[0] === "publish") {
+      const status = publishManagedInstallWrapper(
+        arguments_[1] ?? "",
+        parseOwnerPid(arguments_[2] ?? ""),
+        arguments_[3] ?? "",
+        arguments_[4] ?? "",
+      );
+      process.stdout.write(`${status}\n`);
+    } else if (arguments_.length === 5 && arguments_[0] === "remove") {
+      removeManagedInstallWrapper(
+        arguments_[1] ?? "",
+        parseOwnerPid(arguments_[2] ?? ""),
+        arguments_[3] ?? "",
+        parseManagedWrapperName(arguments_[4] ?? ""),
+      );
+      process.stdout.write("removed\n");
+    } else {
+      throw new Error(
+        "expected recovery directory or exact acquire/release/publish/remove arguments",
+      );
+    }
+  } catch (error) {
+    process.stderr.write(
+      `ghostget installer: ${error instanceof Error ? error.message : "unknown stage recovery failure"}\n`,
+    );
+    process.exitCode = 1;
+  }
+}