@minhspark/codex-mcp-bridge 1.22.13 → 1.22.14

package/src/relay-wake.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+
+import { codexHome, resolveRelayThreadId } from "./native-relay.mjs";
+import { isCodexDesktopRunning, openThreadInCodexApp } from "./platform.mjs";
+import { captureProjectScope } from "./project-scope.mjs";
+import { readRolloutFirstRecord } from "./rollout-reader.mjs";
+
+const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ROLLOUT = /^rollout-.+-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl(?:\.zst)?$/i;
+export const RELAY_WAKE_WAIT_MS = 20000;
+export const RELAY_WAKE_COOLDOWN_MS = 60000;
+const MAX_DAY_DIRECTORIES = 14;
+const MAX_CANDIDATES = 40;
+
+export function relayWakeEnabled(env = process.env, platform = process.platform) {
+  const value = (env.CODEX_BRIDGE_RELAY_WAKE ?? "").toLowerCase();
+  if (["0", "off", "false"].includes(value)) return false;
+  return platform === "darwin" || platform === "win32";
+}
+
+function dayDirectories(sessions) {
+  const directories = [];
+  const children = (directory, pattern) => {
+    try { return fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && pattern.test(entry.name)).map((entry) => entry.name).sort().reverse(); }
+    catch { return []; }
+  };
+  for (const year of children(sessions, /^\d{4}$/)) {
+    for (const month of children(path.join(sessions, year), /^\d{2}$/)) {
+      for (const day of children(path.join(sessions, year, month), /^\d{2}$/)) {
+        directories.push(path.join(sessions, year, month, day));
+        if (directories.length >= MAX_DAY_DIRECTORIES) return directories;
+      }
+    }
+  }
+  return directories;
+}
+
+function sameProject(senderCwd, taskCwd) {
+  try { captureProjectScope(senderCwd, taskCwd); return true; }
+  catch { return false; }
+}
+
+export async function recentDesktopTaskFor(cwd, { env = process.env, sessions = path.join(codexHome(env), "sessions"), exclude = [] } = {}) {
+  if (typeof cwd !== "string" || !cwd) return null;
+  const excluded = new Set(exclude.filter(Boolean));
+  const candidates = [];
+  for (const directory of dayDirectories(sessions)) {
+    let entries;
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const match = entry.isFile() ? ROLLOUT.exec(entry.name) : null;
+      if (!match || excluded.has(match[1])) continue;
+      const file = path.join(directory, entry.name);
+      try { candidates.push({ file, threadId: match[1], mtimeMs: fs.lstatSync(file).mtimeMs }); } catch {}
+    }
+    if (candidates.length >= MAX_CANDIDATES) break;
+  }
+  candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+  for (const candidate of candidates.slice(0, MAX_CANDIDATES)) {
+    let record;
+    try { record = await readRolloutFirstRecord(candidate.file, { maxBytes: 256 * 1024 }); } catch { continue; }
+    const meta = record?.type === "session_meta" ? record.payload : null;
+    if (meta?.id !== candidate.threadId || meta.originator !== "Codex Desktop" || typeof meta.cwd !== "string") continue;
+    if (sameProject(cwd, meta.cwd)) return candidate.threadId;
+  }
+  return null;
+}
+
+export function endpointAnswers(socketPath, { timeoutMs = 1000 } = {}) {
+  if (typeof socketPath !== "string" || !socketPath) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const probe = net.connect({ path: socketPath });
+    const done = (answer) => {
+      globalThis.clearTimeout(timer);
+      probe.destroy();
+      resolve(answer);
+    };
+    const timer = globalThis.setTimeout(() => done(false), timeoutMs);
+    probe.once("connect", () => done(true));
+    probe.once("error", () => done(false));
+  });
+}
+
+export function createRelayWake({
+  env = process.env,
+  enabled = relayWakeEnabled(env),
+  desktopRunning = () => isCodexDesktopRunning(),
+  senderCwd = () => null,
+  findTask = (cwd, exclude) => recentDesktopTaskFor(cwd, { env, exclude }),
+  executorThreadId = () => { try { return resolveRelayThreadId(env).threadId; } catch { return null; } },
+  open = (threadId) => openThreadInCodexApp(threadId, { activate: false }),
+  answers = endpointAnswers,
+  waitMs = RELAY_WAKE_WAIT_MS,
+  cooldownMs = RELAY_WAKE_COOLDOWN_MS,
+  pollMs = 250,
+  now = Date.now,
+  sleep = (ms) => new Promise((resolve) => globalThis.setTimeout(resolve, ms)),
+  log = () => {},
+} = {}) {
+  let inFlight = null;
+  let failedAt = -Infinity;
+  const attempt = async ({ socketPath, threadId, deadline }) => {
+    if (!enabled || now() - failedAt < cooldownMs || !await desktopRunning()) return null;
+    const executor = executorThreadId();
+    const target = typeof threadId === "string" && THREAD_ID.test(threadId) && threadId !== executor
+      ? threadId : await findTask(senderCwd(), [executor]);
+    if (!target) return null;
+    try { await open(target); }
+    catch (error) {
+      failedAt = now();
+      log(`could not open Codex task ${target} to start the native relay: ${error.message}`);
+      return null;
+    }
+    const until = Math.min(now() + waitMs, deadline ?? Infinity);
+    while (now() < until) {
+      if (await answers(socketPath)) {
+        log(`started the Codex Desktop native relay by opening task ${target} in the background`);
+        return { threadId: target };
+      }
+      await sleep(pollMs);
+    }
+    failedAt = now();
+    log(`opened Codex task ${target}, but the native relay did not start within ${waitMs} ms`);
+    return null;
+  };
+  return (request) => inFlight ??= attempt(request).finally(() => { inFlight = null; });
+}

package/src/release-snapshot.mjs

@@ -1,8 +1,10 @@
+import { execFile, execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { promisify } from "node:util";
 
 function digestFiles(root, files) {
   const hash = createHash("sha256");
@@ -239,7 +241,309 @@ function removeOwned(directory, cache) {
   fs.rmSync(directory, { recursive: true, force: true });
 }
 
-export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRevision = sourceRevision(root) } = {}) {
+const LEASES = ".leases";
+const LEASE_PATTERN = /^([a-f0-9]{64})\.(\d+)\.[0-9a-f-]{36}\.lease$/;
+const OWNED_TEMPORARY_PATTERN = /^\.(?:preparing|retired|linking)-(\d+)-[0-9a-f-]{36}$/;
+const DIGEST_TEMPORARY_PATTERN = /^\.(?:digests|prune-lock)-(\d+)-[0-9a-f-]{36}\.tmp$/;
+const DIGEST_FILE_PATTERN = /^\.digests-[a-f0-9]{64}\.json$/;
+const DIGEST_HEADER = /^\{"schema":1,"directory":("(?:[^"\\]|\\.)*")/;
+const PRUNE_LOCK = ".prune.lock";
+const PRUNE_STAMP = ".prune-stamp";
+const LEASE_HEARTBEAT_MS = 5 * 60 * 1000;
+const LEASE_FRESH_MS = 3 * LEASE_HEARTBEAT_MS;
+const LEASE_OWNER_MAX_MS = 7 * 24 * 60 * 60 * 1000;
+const PRUNE_LOCK_STALE_MS = 10 * 60 * 1000;
+const TEMPORARY_GRACE_MS = 60 * 60 * 1000;
+const CLONE_TIMEOUT_MS = 120000;
+const PROCESS_LIST_TIMEOUT_MS = 60000;
+const MAX_DIGEST_HEADERS = 256;
+const RUNTIME_RETENTION = Object.freeze({ retain: 3, graceMs: 24 * 60 * 60 * 1000, minIntervalMs: 60 * 60 * 1000, maxRemovals: 8 });
+
+const execFileAsync = promisify(execFile);
+const activeLeases = new Set();
+
+function processAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  if (pid === process.pid) return true;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === "EPERM"; }
+}
+
+function touch(target, now = new Date()) {
+  try { fs.utimesSync(target, now, now); return true; } catch { return false; }
+}
+
+function isDirectory(target) {
+  try { const info = fs.lstatSync(target); return info.isDirectory() && !info.isSymbolicLink(); } catch { return false; }
+}
+
+function removeIfFile(file) {
+  try {
+    const info = fs.lstatSync(file);
+    if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) return false;
+    fs.rmSync(file, { force: true });
+    return true;
+  } catch { return false; }
+}
+
+function releaseActiveLeases() {
+  for (const lease of activeLeases) lease.release();
+}
+
+function leaseSnapshot(cache, key, target) {
+  const directory = path.join(cache, LEASES);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (!isDirectory(directory)) throw new Error("The runtime lease directory is not a directory");
+  const file = path.join(directory, `${key}.${process.pid}.${randomUUID()}.lease`);
+  const write = () => fs.writeFileSync(file, `${JSON.stringify({ schema: 1, key, pid: process.pid })}\n`, { flag: "wx", mode: 0o600 });
+  write();
+  if (!activeLeases.size) process.once("exit", releaseActiveLeases);
+  const timer = setInterval(() => {
+    if (touch(file)) return;
+    try { write(); } catch {}
+  }, LEASE_HEARTBEAT_MS);
+  timer.unref?.();
+  const lease = {
+    file,
+    released: false,
+    release() {
+      if (lease.released) return;
+      lease.released = true;
+      clearInterval(timer);
+      activeLeases.delete(lease);
+      if (!activeLeases.size) process.removeListener("exit", releaseActiveLeases);
+      try { fs.rmSync(file, { force: true }); } catch {}
+      touch(target);
+    },
+  };
+  activeLeases.add(lease);
+  return lease;
+}
+
+function readLeases(cache, now) {
+  const directory = path.join(cache, LEASES);
+  if (!isDirectory(directory)) return [];
+  const leases = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const match = LEASE_PATTERN.exec(entry.name);
+    if (!match || !entry.isFile()) continue;
+    const file = path.join(directory, entry.name);
+    let info;
+    try { info = fs.lstatSync(file); } catch { continue; }
+    const age = now - info.mtimeMs;
+    const pid = Number(match[2]);
+    leases.push({ file, key: match[1], usedAt: info.mtimeMs, live: age < LEASE_FRESH_MS || (age < LEASE_OWNER_MAX_MS && processAlive(pid)) });
+  }
+  return leases;
+}
+
+export async function runningCommandLines() {
+  const options = { timeout: PROCESS_LIST_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024, windowsHide: true };
+  let stdout;
+  if (process.platform === "win32") {
+    const shell = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    ({ stdout } = await execFileAsync(shell, ["-NoProfile", "-NonInteractive", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { $_.CommandLine }"], options));
+  } else {
+    const ps = ["/bin/ps", "/usr/bin/ps"].find((candidate) => fs.existsSync(candidate));
+    if (!ps) throw new Error("No process listing tool is available");
+    ({ stdout } = await execFileAsync(ps, ["-A", "-ww", "-o", "args="], { ...options, env: { ...process.env, LC_ALL: "C" } }));
+  }
+  const lines = stdout.split(/\r?\n/).filter(Boolean);
+  if (!lines.length) throw new Error("The process listing is empty");
+  return lines;
+}
+
+function createPruneLock(cache, lock) {
+  const staged = path.join(cache, `.prune-lock-${process.pid}-${randomUUID()}.tmp`);
+  fs.writeFileSync(staged, `${process.pid}\n`, { flag: "wx", mode: 0o600 });
+  try { fs.linkSync(staged, lock); }
+  catch (error) {
+    if (error.code === "EEXIST") throw error;
+    fs.writeFileSync(lock, `${process.pid}\n`, { flag: "wx", mode: 0o600 });
+  } finally { fs.rmSync(staged, { force: true }); }
+}
+
+function takeOverStalePruneLock(cache, lock, now) {
+  const info = fs.lstatSync(lock, { bigint: true });
+  if (!info.isFile() || info.isSymbolicLink()) return false;
+  const text = fs.readFileSync(lock, "utf8").trim();
+  const owner = /^\d+$/.test(text) ? Number(text) : null;
+  if (now - Number(info.mtimeMs) < PRUNE_LOCK_STALE_MS && (owner === null || processAlive(owner))) return false;
+  const moved = path.join(cache, `.prune-lock-${process.pid}-${randomUUID()}.tmp`);
+  fs.renameSync(lock, moved);
+  let reclaimed = false;
+  try {
+    const descriptor = fs.openSync(moved, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+    try {
+      const examined = fs.fstatSync(descriptor, { bigint: true });
+      reclaimed = examined.isFile() && examined.dev === info.dev && examined.ino === info.ino && examined.mtimeNs === info.mtimeNs && examined.size === info.size
+        && fs.readFileSync(descriptor, "utf8").trim() === text;
+    } finally { fs.closeSync(descriptor); }
+  } catch { reclaimed = false; }
+  if (!reclaimed) { try { fs.linkSync(moved, lock); } catch {} }
+  fs.rmSync(moved, { force: true });
+  return reclaimed;
+}
+
+function acquirePruneLock(cache, now) {
+  const lock = path.join(cache, PRUNE_LOCK);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      createPruneLock(cache, lock);
+      return () => {
+        try { if (fs.readFileSync(lock, "utf8").trim() === String(process.pid)) fs.rmSync(lock, { force: true }); } catch {}
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST" || attempt) return null;
+      try { if (!takeOverStalePruneLock(cache, lock, now)) return null; } catch { return null; }
+    }
+  }
+  return null;
+}
+
+function claimPruneInterval(stamp, now, minIntervalMs) {
+  let info = null;
+  try { info = fs.lstatSync(stamp); } catch (error) { if (error.code !== "ENOENT") return "The prune stamp could not be read"; }
+  if (info && (!info.isFile() || info.isSymbolicLink())) return "The prune stamp is not a regular file";
+  if (info && now - info.mtimeMs < minIntervalMs) return "The runtime cache was pruned recently";
+  let descriptor;
+  try {
+    descriptor = fs.openSync(stamp, fs.constants.O_WRONLY | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    if (!fs.fstatSync(descriptor).isFile()) return "The prune stamp is not a regular file";
+    const time = new Date(now);
+    fs.futimesSync(descriptor, time, time);
+    return null;
+  } catch { return "The prune stamp could not be updated"; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+}
+
+function digestDirectory(file) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const buffer = Buffer.alloc(8192);
+    const count = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+    const match = DIGEST_HEADER.exec(buffer.subarray(0, count).toString("utf8"));
+    return match ? JSON.parse(match[1]) : null;
+  } catch { return null; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+}
+
+function sweepCacheFiles(cache, entries, now, report) {
+  let headers = 0;
+  for (const entry of entries) {
+    const target = path.join(cache, entry.name);
+    const temporary = OWNED_TEMPORARY_PATTERN.exec(entry.name) ?? DIGEST_TEMPORARY_PATTERN.exec(entry.name);
+    if (temporary) {
+      let info;
+      try { info = fs.lstatSync(target); } catch { continue; }
+      if (info.isSymbolicLink() || now - info.mtimeMs < TEMPORARY_GRACE_MS || processAlive(Number(temporary[1]))) continue;
+      if (info.isDirectory()) { try { removeOwned(target, cache); report.temporaries++; } catch {} }
+      else if (removeIfFile(target)) report.temporaries++;
+      continue;
+    }
+    if (!DIGEST_FILE_PATTERN.test(entry.name) || !entry.isFile() || headers >= MAX_DIGEST_HEADERS) continue;
+    headers++;
+    const directory = digestDirectory(target);
+    if (typeof directory === "string" && !isDirectory(directory) && removeIfFile(target)) report.digests++;
+  }
+}
+
+async function retireSnapshot(cache, key, usedAt) {
+  const target = path.join(cache, key);
+  const leased = () => readLeases(cache, Date.now()).some((lease) => lease.key === key && lease.live);
+  let info;
+  try { info = fs.lstatSync(target); } catch { return "kept"; }
+  if (!info.isDirectory() || info.isSymbolicLink() || info.mtimeMs > usedAt || leased()) return "kept";
+  const retired = path.join(cache, `.retired-${process.pid}-${randomUUID()}`);
+  try { fs.renameSync(target, retired); } catch { return "kept"; }
+  if (leased()) {
+    try { fs.renameSync(retired, target); }
+    catch { if (isDirectory(target) && isDirectory(retired)) removeOwned(retired, cache); }
+    return "kept";
+  }
+  if (!isDirectory(retired)) return "kept";
+  removeIfFile(path.join(cache, `.digests-${createHash("sha256").update(target).digest("hex")}.json`));
+  try { await fs.promises.rm(retired, { recursive: true, force: true }); } catch { return "incomplete"; }
+  return isDirectory(retired) ? "incomplete" : "removed";
+}
+
+function pruneCandidates(cache, entries, leases, { keep, retain, graceMs }, now) {
+  const live = new Set(leases.filter((lease) => lease.live).map((lease) => lease.key));
+  const snapshots = [];
+  for (const entry of entries) {
+    if (!DIGEST_PATTERN.test(entry.name) || !entry.isDirectory()) continue;
+    let info;
+    try { info = fs.lstatSync(path.join(cache, entry.name)); } catch { continue; }
+    if (!info.isDirectory() || info.isSymbolicLink()) continue;
+    const usedAt = Math.max(info.mtimeMs, ...leases.filter((lease) => lease.key === entry.name).map((lease) => lease.usedAt));
+    snapshots.push({ key: entry.name, usedAt });
+  }
+  snapshots.sort((left, right) => right.usedAt - left.usedAt || left.key.localeCompare(right.key, "en"));
+  const protectedKeys = new Set(keep);
+  const candidates = snapshots.filter((snapshot, index) => index >= retain && !protectedKeys.has(snapshot.key)
+    && !live.has(snapshot.key) && now - snapshot.usedAt >= graceMs).reverse();
+  return { snapshots, candidates };
+}
+
+export async function pruneReleaseSnapshots({ cache = snapshotRoot(), keep = [], retain = RUNTIME_RETENTION.retain, graceMs = RUNTIME_RETENTION.graceMs,
+  minIntervalMs = RUNTIME_RETENTION.minIntervalMs, maxRemovals = RUNTIME_RETENTION.maxRemovals, listProcesses = runningCommandLines } = {}) {
+  const report = { removed: [], kept: [], incomplete: [], leases: 0, temporaries: 0, digests: 0, skipped: null };
+  if (!isDirectory(cache)) { report.skipped = "The runtime cache is not a directory"; return report; }
+  cache = fs.realpathSync.native(cache);
+  const now = Date.now();
+  const unlock = acquirePruneLock(cache, now);
+  if (!unlock) { report.skipped = "Another prune is running"; return report; }
+  try {
+    const stamp = path.join(cache, PRUNE_STAMP);
+    report.skipped = claimPruneInterval(stamp, now, minIntervalMs);
+    if (report.skipped) return report;
+    const leases = readLeases(cache, now);
+    for (const lease of leases) if (!lease.live && removeIfFile(lease.file)) report.leases++;
+    const entries = fs.readdirSync(cache, { withFileTypes: true });
+    sweepCacheFiles(cache, entries, now, report);
+    const { snapshots, candidates } = pruneCandidates(cache, entries, leases, { keep, retain, graceMs }, now);
+    const bounded = candidates.slice(0, Math.max(0, maxRemovals));
+    report.kept = snapshots.filter((snapshot) => !bounded.includes(snapshot)).map((snapshot) => snapshot.key);
+    if (!bounded.length) return report;
+    let commandLines;
+    try { commandLines = (await listProcesses()).map((line) => String(line).toLowerCase()); }
+    catch (error) {
+      report.kept.push(...bounded.map((snapshot) => snapshot.key));
+      report.skipped = `Running processes could not be listed: ${error.message}`;
+      return report;
+    }
+    for (const { key, usedAt } of bounded) {
+      const outcome = commandLines.some((line) => line.includes(key)) ? "kept" : await retireSnapshot(cache, key, usedAt);
+      report[outcome].push(key);
+    }
+    return report;
+  } finally { unlock(); }
+}
+
+const cloneSupported = () => process.platform === "darwin" && fs.existsSync("/bin/cp");
+
+function cloneRelease(entries, temporary, cache) {
+  const farm = path.join(cache, `.linking-${process.pid}-${randomUUID()}`);
+  try {
+    fs.mkdirSync(farm, { mode: 0o700 });
+    const created = new Set();
+    for (const [file, source] of entries) {
+      const link = path.join(farm, file);
+      const parent = path.dirname(link);
+      if (!created.has(parent)) { fs.mkdirSync(parent, { recursive: true, mode: 0o700 }); created.add(parent); }
+      fs.symlinkSync(source, link);
+    }
+    execFileSync("/bin/cp", ["-c", "-R", "-L", "--", `${farm}${path.sep}`, temporary], { stdio: "ignore", timeout: CLONE_TIMEOUT_MS });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try { removeOwned(farm, cache); } catch {}
+  }
+}
+
+export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRevision = sourceRevision(root), lease = false } = {}) {
   root = fs.realpathSync.native(root);
   if (fs.existsSync(cache) && fs.lstatSync(cache).isSymbolicLink()) throw new Error("The runtime cache cannot be a symbolic link");
   const missing = [];
@@ -263,43 +567,66 @@ export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRe
     if (fs.lstatSync(directory).isSymbolicLink()) throw new Error("The release directory cannot be a symbolic link");
     return sourceRevision(directory) === expectedRevision && metadata.digest(directory, inventory(directory, "node_modules").sort((left, right) => left.localeCompare(right, "en"))) === dependencyRevision;
   };
-  if (fs.existsSync(target)) {
-    if (!validate(target)) throw new Error("An existing immutable runtime failed integrity verification");
-    const currentDependencies = dependencyFiles(root);
-    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision) {
-      throw new Error("The installation changed during snapshot verification");
-    }
-    metadata.flush();
-    return { directory: target, revision: expectedRevision, key };
-  }
-  const temporary = path.join(cache, `.preparing-${process.pid}-${randomUUID()}`);
-  try {
-    fs.mkdirSync(temporary, { mode: 0o700 });
-    const files = ["package.json", ...inventory(root, "src"), ...dependencies.keys()];
-    if (fs.existsSync(path.join(root, "package-lock.json"))) files.push("package-lock.json");
-    const directories = new Set(["src", "node_modules", ...files.map((file) => path.dirname(file))]);
-    for (const directory of directories) fs.mkdirSync(path.join(temporary, directory), { recursive: true, mode: 0o700 });
-    for (const file of files) {
-      fs.copyFileSync(dependencies.get(file) ?? path.join(root, file), path.join(temporary, file), fs.constants.COPYFILE_FICLONE);
-    }
-    fs.writeFileSync(path.join(temporary, INSTALLATION_LOCKS), installationLocks(root), { flag: "wx", mode: 0o600 });
-    const currentDependencies = dependencyFiles(root);
-    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision || !validate(temporary)) {
-      throw new Error("The installation changed while its immutable runtime was being prepared");
-    }
+  const prepare = () => {
+    const temporary = path.join(cache, `.preparing-${process.pid}-${randomUUID()}`);
     try {
-      fs.renameSync(temporary, target);
-      metadata.relocate(temporary, target);
-    }
-    catch (error) {
-      if (!fs.existsSync(target) || !validate(target)) throw error;
+      const files = ["package.json", ...inventory(root, "src"), ...dependencies.keys()];
+      if (fs.existsSync(path.join(root, "package-lock.json"))) files.push("package-lock.json");
+      const sources = files.map((file) => [file, dependencies.get(file) ?? path.join(root, file)]);
+      const directories = new Set(["src", "node_modules", ...files.map((file) => path.dirname(file))]);
+      const layout = () => {
+        fs.mkdirSync(temporary, { mode: 0o700 });
+        for (const directory of directories) fs.mkdirSync(path.join(temporary, directory), { recursive: true, mode: 0o700 });
+      };
+      layout();
+      let copy = "clonefile";
+      if (!cloneSupported() || !cloneRelease(sources, temporary, cache)) {
+        copy = "copyfile";
+        if (cloneSupported()) { removeOwned(temporary, cache); layout(); }
+        for (const [file, source] of sources) fs.copyFileSync(source, path.join(temporary, file), fs.constants.COPYFILE_FICLONE);
+      }
+      fs.writeFileSync(path.join(temporary, INSTALLATION_LOCKS), installationLocks(root), { flag: "wx", mode: 0o600 });
+      const currentDependencies = dependencyFiles(root);
+      if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision || !validate(temporary)) {
+        throw new Error("The installation changed while its immutable runtime was being prepared");
+      }
+      try {
+        fs.renameSync(temporary, target);
+        metadata.relocate(temporary, target);
+      }
+      catch (error) {
+        if (!fs.existsSync(target) || !validate(target)) throw error;
+        removeOwned(temporary, cache);
+        metadata.forget(temporary);
+      }
+      return copy;
+    } catch (error) {
       removeOwned(temporary, cache);
-      metadata.forget(temporary);
+      throw error;
     }
+  };
+  const held = lease ? leaseSnapshot(cache, key, target) : null;
+  const finish = (copy) => {
     metadata.flush();
-    return { directory: target, revision: expectedRevision, key };
+    touch(target);
+    return { directory: target, revision: expectedRevision, key, copy, ...(held ? { lease: held } : {}) };
+  };
+  try {
+    for (let attempt = 0; fs.existsSync(target); attempt++) {
+      try {
+        if (!validate(target)) throw new Error("An existing immutable runtime failed integrity verification");
+        const currentDependencies = dependencyFiles(root);
+        if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision) {
+          throw new Error("The installation changed during snapshot verification");
+        }
+        return finish("reused");
+      } catch (error) {
+        if (error?.code !== "ENOENT" || attempt >= 2) throw error;
+      }
+    }
+    return finish(prepare());
   } catch (error) {
-    removeOwned(temporary, cache);
+    held?.release();
     throw error;
   }
 }