@pygmalionjs/pygmalion 0.6.32 → 0.6.34

package/node/dev-mirror.mjs

@@ -29,6 +29,8 @@ const LEASE_HEARTBEAT_MS = 2_000;
 // costs a checkout and a dependency install, so the reaper errs toward keeping.
 const DEFAULT_MIRROR_GRACE_MS = 6 * 60 * 60 * 1_000;
 const LEASE_WAIT_TIMEOUT_MS = 180_000;
+const MAX_INVENTORY_RUNTIME_INPUTS = 64;
+const MAX_INVENTORY_RUNTIME_INPUT_BYTES = 16 * 1024 * 1024;
 // A serving editor holds this for its whole session. It marks the checkout as in
 // use for the reaper; it must never stand in the way of a sync.
 const SERVE_LEASE_LABEL = 'serve';
@@ -37,6 +39,64 @@ export function resolveDevMirrorInventoryOutputRoot(inventory, mirrorAppRoot) {
   return path.resolve(inventory?.outputRoot ?? mirrorAppRoot);
 }
 
+export function resolveDevMirrorInventoryArgs(inventory, context) {
+  if (typeof inventory?.args === 'function') return inventory.args(context);
+  if (inventory?.args != null) return inventory.args;
+  return [
+    inventory?.script,
+    '--source-root',
+    context.sourceRoot,
+    '--out-root',
+    context.outputRoot,
+    '--commit',
+    context.commit,
+  ];
+}
+
+/**
+ * Resolves an application root only when it belongs to the same Git worktree
+ * and commit as the checkout whose identity is being leased.
+ */
+export async function resolveExactCheckoutSourceRoot({
+  checkoutRoot,
+  sourceRoot,
+  expectedRevision,
+}) {
+  if (
+    typeof checkoutRoot !== 'string' ||
+    !checkoutRoot.trim() ||
+    typeof sourceRoot !== 'string' ||
+    !sourceRoot.trim() ||
+    typeof expectedRevision !== 'string' ||
+    !expectedRevision.trim()
+  ) {
+    return null;
+  }
+  try {
+    const [checkoutTop, sourceTop, checkoutRevision, sourceRevision] =
+      await Promise.all([
+        git(checkoutRoot, 'rev-parse', '--show-toplevel'),
+        git(sourceRoot, 'rev-parse', '--show-toplevel'),
+        git(checkoutRoot, 'rev-parse', 'HEAD'),
+        git(sourceRoot, 'rev-parse', 'HEAD'),
+      ]);
+    if (
+      checkoutRevision !== expectedRevision ||
+      sourceRevision !== expectedRevision
+    ) {
+      return null;
+    }
+    const [realCheckoutTop, realSourceTop, realSourceRoot] = await Promise.all([
+      fsp.realpath(checkoutTop),
+      fsp.realpath(sourceTop),
+      fsp.realpath(sourceRoot),
+    ]);
+    return realCheckoutTop === realSourceTop ? realSourceRoot : null;
+  } catch {
+    return null;
+  }
+}
+
 /** A running preview belongs to one immutable app root for its whole process. */
 export function devPreviewNeedsRestart({
   force = false,
@@ -357,28 +417,27 @@ export async function reapDevMirrorWorktrees({
   keep = [],
   graceMs = DEFAULT_MIRROR_GRACE_MS,
   now = Date.now(),
+  removeWorktree = (candidate) =>
+    git(repoRoot, 'worktree', 'remove', '--force', candidate),
 }) {
   // git reports worktrees by their real path, so a configured path that crosses a
   // symlink (macOS `/tmp` and `/var` both do) would never match by string alone.
   // The base itself is a naming prefix, not necessarily a directory that exists,
   // so fall back to resolving it inside its parent — otherwise the prefix stays
   // in `/var` while every listed worktree comes back as `/private/var`.
-  const real = async (target) => {
-    const resolved = path.resolve(target);
-    const direct = await fsp.realpath(resolved).catch(() => null);
-    if (direct) return direct;
-    const parent = await fsp.realpath(path.dirname(resolved)).catch(() => null);
-    return parent ? path.join(parent, path.basename(resolved)) : resolved;
-  };
-  const base = await real(mirrorBaseRoot);
-  const kept = new Set(await Promise.all(keep.filter(Boolean).map(real)));
+  const base = await canonicalDevMirrorPath(mirrorBaseRoot);
+  const kept = new Set(
+    await Promise.all(keep.filter(Boolean).map(canonicalDevMirrorPath)),
+  );
   const raw = await git(repoRoot, 'worktree', 'list', '--porcelain').catch(() => '');
   const candidates = (
     await Promise.all(
       raw
         .split('\n')
         .filter((line) => line.startsWith('worktree '))
-        .map((line) => real(line.slice('worktree '.length).trim())),
+        .map((line) =>
+          canonicalDevMirrorPath(line.slice('worktree '.length).trim()),
+        ),
     )
   )
     // Only this project's mirrors. A sibling directory that merely starts with
@@ -389,26 +448,38 @@ export async function reapDevMirrorWorktrees({
   const removed = [];
   const skipped = [];
   for (const candidate of candidates) {
-    const leases = await freshLeases(repoRoot, candidate);
-    if (leases.length > 0) {
-      skipped.push({ path: candidate, reason: 'leased', labels: leases.map((l) => l.label) });
-      continue;
-    }
-    const stat = await fsp.stat(candidate).catch(() => null);
-    if (stat && now - stat.mtimeMs < graceMs) {
-      skipped.push({ path: candidate, reason: 'recent' });
-      continue;
-    }
-    try {
-      await git(repoRoot, 'worktree', 'remove', '--force', candidate);
-      removed.push(candidate);
-    } catch (error) {
-      skipped.push({
-        path: candidate,
-        reason: 'remove-failed',
-        error: error instanceof Error ? error.message.split('\n')[0] : String(error),
-      });
-    }
+    await withDevMirrorSyncLock(repoRoot, async () => {
+      // Exact source lease acquisition uses this same lock. Keeping the final
+      // lease check and removal in one critical section prevents a reader from
+      // appearing after the check but before `git worktree remove`.
+      const leases = await freshLeases(repoRoot, candidate);
+      if (leases.length > 0) {
+        skipped.push({
+          path: candidate,
+          reason: 'leased',
+          labels: leases.map((lease) => lease.label),
+        });
+        return;
+      }
+      const stat = await fsp.stat(candidate).catch(() => null);
+      if (stat && now - stat.mtimeMs < graceMs) {
+        skipped.push({ path: candidate, reason: 'recent' });
+        return;
+      }
+      try {
+        await removeWorktree(candidate);
+        removed.push(candidate);
+      } catch (error) {
+        skipped.push({
+          path: candidate,
+          reason: 'remove-failed',
+          error:
+            error instanceof Error
+              ? error.message.split('\n')[0]
+              : String(error),
+        });
+      }
+    });
   }
   return { removed, skipped };
 }
@@ -418,6 +489,176 @@ async function pygmalionStateDirectory(repoRoot) {
   return path.join(path.resolve(repoRoot, rawCommonGitDir), 'pygmalion');
 }
 
+async function canonicalDevMirrorPath(target) {
+  const resolved = path.resolve(target);
+  const direct = await fsp.realpath(resolved).catch(() => null);
+  if (direct) return direct;
+  const parent = await fsp.realpath(path.dirname(resolved)).catch(() => null);
+  return parent ? path.join(parent, path.basename(resolved)) : resolved;
+}
+
+function processIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'ESRCH' ? false : true;
+  }
+}
+
+async function acquireDevMirrorReclaimMutex(lockPath, deadline) {
+  const reclaimPath = `${lockPath}.reclaim`;
+  const token = `${process.pid}:${randomUUID()}`;
+  const owner = `${JSON.stringify({
+    token,
+    pid: process.pid,
+    createdAt: new Date().toISOString(),
+  })}\n`;
+  while (true) {
+    const candidatePath = `${reclaimPath}.candidate-${randomUUID()}`;
+    try {
+      await fsp.writeFile(candidatePath, owner, { flag: 'wx' });
+      await fsp.link(candidatePath, reclaimPath);
+      return async () => {
+        const current = await fsp
+          .readFile(reclaimPath, 'utf8')
+          .then((raw) => JSON.parse(raw)?.token)
+          .catch(() => null);
+        if (current === token) {
+          await fsp.unlink(reclaimPath).catch(() => undefined);
+        }
+      };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      // This guard is deliberately never stale-stolen. If its owner dies, the
+      // primary lock remains fail-closed until the guard is removed manually.
+      if (Date.now() >= deadline) {
+        throw new Error(
+          'dev screen refresh on another editor server is not finished',
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    } finally {
+      await fsp.rm(candidatePath, { force: true }).catch(() => undefined);
+    }
+  }
+}
+
+async function reclaimStaleDevMirrorSyncLock({
+  lockPath,
+  deadline,
+  onStaleLockConfirmed,
+}) {
+  const releaseReclaim = await acquireDevMirrorReclaimMutex(lockPath, deadline);
+  try {
+    const staleOwner = async () => {
+      const stat = await fsp.stat(lockPath).catch(() => null);
+      if (!stat || Date.now() - stat.mtimeMs <= SHARED_LOCK_STALE_MS) {
+        return false;
+      }
+      const ownerState = await fsp
+        .readFile(lockPath, 'utf8')
+        .then((raw) => processIsAlive(JSON.parse(raw)?.pid))
+        .catch(() => null);
+      return ownerState !== true;
+    };
+    if (!(await staleOwner())) return false;
+    await onStaleLockConfirmed?.({ lockPath });
+    // The callback models a delayed reclaimer. Re-read under the mutex so an
+    // observation made before another recovery can never delete its new lock.
+    if (!(await staleOwner())) return false;
+    await fsp.unlink(lockPath).catch(() => undefined);
+    return true;
+  } finally {
+    await releaseReclaim();
+  }
+}
+
+/** Serializes mirror mutation and exact read-lease acquisition across processes. */
+export async function withDevMirrorSyncLock(
+  repoRoot,
+  task,
+  {
+    onLockCandidateReady,
+    onStaleLockConfirmed,
+    lockTimeoutMs = SHARED_LOCK_TIMEOUT_MS,
+  } = {},
+) {
+  const directory = await pygmalionStateDirectory(repoRoot);
+  const lockPath = path.join(directory, 'dev-mirror-sync.lock');
+  const token = `${process.pid}:${randomUUID()}`;
+  const owner = `${JSON.stringify({
+    token,
+    pid: process.pid,
+    createdAt: new Date().toISOString(),
+  })}\n`;
+  const deadline = Date.now() + lockTimeoutMs;
+  await fsp.mkdir(path.dirname(lockPath), { recursive: true });
+
+  while (true) {
+    const candidatePath = `${lockPath}.candidate-${randomUUID()}`;
+    try {
+      // Write ownership completely before the fixed lock path becomes visible.
+      // If this process sleeps between file creation and the write, contenders
+      // see only a private candidate rather than an apparently abandoned lock.
+      await fsp.writeFile(candidatePath, owner, { flag: 'wx' });
+      await onLockCandidateReady?.({ candidatePath, lockPath });
+      await fsp.link(candidatePath, lockPath);
+      break;
+    } catch (error) {
+      if (
+        !(
+          error &&
+          typeof error === 'object' &&
+          'code' in error &&
+          error.code === 'EEXIST'
+        )
+      ) {
+        throw error;
+      }
+      const stale = await fsp
+        .stat(lockPath)
+        .then((stat) => Date.now() - stat.mtimeMs > SHARED_LOCK_STALE_MS)
+        .catch(() => false);
+      if (stale) {
+        const reclaimed = await reclaimStaleDevMirrorSyncLock({
+          lockPath,
+          deadline,
+          onStaleLockConfirmed,
+        });
+        if (reclaimed) {
+          continue;
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          'dev screen refresh on another editor server is not finished',
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    } finally {
+      await fsp.rm(candidatePath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  const heartbeat = setInterval(() => {
+    const now = new Date();
+    void fsp.utimes(lockPath, now, now).catch(() => undefined);
+  }, 2_000);
+  heartbeat.unref();
+  try {
+    return await task();
+  } finally {
+    clearInterval(heartbeat);
+    const owner = await fsp
+      .readFile(lockPath, 'utf8')
+      .then((raw) => JSON.parse(raw).token)
+      .catch(() => null);
+    if (owner === token) await fsp.unlink(lockPath).catch(() => undefined);
+  }
+}
+
 /**
  * Downgrades a ready status whose checkout no longer holds the commit it claims.
  *
@@ -455,35 +696,39 @@ async function freshLeases(repoRoot, mirrorRoot) {
     return [];
   }
   const held = [];
+  const canonicalMirrorRoot = mirrorRoot
+    ? await canonicalDevMirrorPath(mirrorRoot)
+    : null;
   for (const entry of entries) {
     if (!entry.endsWith('.json')) continue;
     const file = path.join(directory, entry);
     const stat = await fsp.stat(file).catch(() => null);
     if (!stat) continue;
-    if (Date.now() - stat.mtimeMs > LEASE_STALE_MS) {
-      await fsp.rm(file, { force: true }).catch(() => undefined);
-      continue;
-    }
     const lease = await fsp
       .readFile(file, 'utf8')
       .then((raw) => JSON.parse(raw))
       .catch(() => null);
+    if (Date.now() - stat.mtimeMs > LEASE_STALE_MS) {
+      const ownerState = processIsAlive(lease?.pid);
+      if (ownerState !== true) {
+        await fsp.rm(file, { force: true }).catch(() => undefined);
+        continue;
+      }
+    }
     if (!lease) continue;
-    if (mirrorRoot && path.resolve(lease.mirrorRoot ?? '') !== path.resolve(mirrorRoot)) continue;
+    if (canonicalMirrorRoot) {
+      if (typeof lease.mirrorRoot !== 'string' || !lease.mirrorRoot.trim()) {
+        continue;
+      }
+      const canonicalLeaseRoot = await canonicalDevMirrorPath(lease.mirrorRoot);
+      if (canonicalLeaseRoot !== canonicalMirrorRoot) continue;
+    }
     held.push({ ...lease, file });
   }
   return held;
 }
 
-/**
- * Marks a mirror checkout as being read, so a sync cannot switch it away.
- *
- * A screen capture reads the checkout for minutes at a time while the sync lock
- * is free, which is exactly when another server could move it. The lease is a
- * heartbeat file: it expires on its own if the reader dies, so a crash cannot
- * wedge the mirror.
- */
-export async function acquireDevMirrorLease({ repoRoot, mirrorRoot, label = 'capture' }) {
+async function writeDevMirrorLease({ repoRoot, mirrorRoot, label = 'capture' }) {
   const directory = path.join(await pygmalionStateDirectory(repoRoot), 'dev-mirror-leases');
   await fsp.mkdir(directory, { recursive: true });
   const file = path.join(directory, `${randomUUID()}.json`);
@@ -513,6 +758,103 @@ export async function acquireDevMirrorLease({ repoRoot, mirrorRoot, label = 'cap
   };
 }
 
+/**
+ * Marks a mirror checkout as being read, so a sync or reaper cannot move it.
+ *
+ * Creation is serialized with mirror mutation. The lease remains a heartbeat
+ * file after acquisition, so the shared lock is free while the reader works and
+ * a crashed reader cannot wedge the checkout permanently.
+ */
+export async function acquireDevMirrorLease(options) {
+  return withDevMirrorSyncLock(options.repoRoot, () =>
+    writeDevMirrorLease(options),
+  );
+}
+
+/**
+ * Acquires a read lease and proves that its root still carries the requested
+ * commit after the lease exists. `readCurrent` is sampled on both sides so a
+ * sync that started first is rejected, while a sync that starts afterwards is
+ * held by the lease.
+ */
+export async function acquireExactDevMirrorSourceLease({
+  repoRoot,
+  expectedRevision,
+  readCurrent,
+  withSyncLock,
+  label = 'source reader',
+}) {
+  if (
+    typeof expectedRevision !== 'string' ||
+    !expectedRevision.trim() ||
+    expectedRevision !== expectedRevision.trim() ||
+    typeof readCurrent !== 'function' ||
+    typeof withSyncLock !== 'function'
+  ) {
+    return null;
+  }
+  return withSyncLock(async () => {
+    const before = readCurrent();
+    if (
+      before?.state !== 'ready' ||
+      before.sourceRevision !== expectedRevision ||
+      typeof before.mirrorRoot !== 'string' ||
+      typeof before.appRoot !== 'string'
+    ) {
+      return null;
+    }
+    const capturedMirrorRoot = path.resolve(before.mirrorRoot);
+    const capturedAppRoot = path.resolve(before.appRoot);
+    // The caller already owns the same cross-process lock used by the public
+    // lease API. Writing directly avoids a nested acquisition deadlock.
+    const lease = await writeDevMirrorLease({
+      repoRoot,
+      mirrorRoot: capturedMirrorRoot,
+      label,
+    });
+    const release = async () => lease.release();
+    try {
+      const afterLease = readCurrent();
+      if (
+        afterLease?.state !== 'ready' ||
+        afterLease.sourceRevision !== expectedRevision ||
+        path.resolve(afterLease.mirrorRoot ?? '') !== capturedMirrorRoot ||
+        path.resolve(afterLease.appRoot ?? '') !== capturedAppRoot
+      ) {
+        await release();
+        return null;
+      }
+      const exactSourceRoot = await resolveExactCheckoutSourceRoot({
+        checkoutRoot: capturedMirrorRoot,
+        sourceRoot: capturedAppRoot,
+        expectedRevision,
+      });
+      const afterRead = readCurrent();
+      if (
+        !exactSourceRoot ||
+        afterRead?.state !== 'ready' ||
+        afterRead.sourceRevision !== expectedRevision ||
+        path.resolve(afterRead.mirrorRoot ?? '') !== capturedMirrorRoot ||
+        path.resolve(afterRead.appRoot ?? '') !== capturedAppRoot
+      ) {
+        await release();
+        return null;
+      }
+      return {
+        sourceRoot: exactSourceRoot,
+        sourceRevision: expectedRevision,
+        // Synchronization and reaping honor the heartbeat lease until release,
+        // so retention may safely inspect this root while the caller holds it.
+        sourceRootStable: true,
+        release,
+      };
+    } catch (error) {
+      await release();
+      throw error;
+    }
+  });
+}
+
 /**
  * Leases that a sync must wait out.
  *
@@ -622,6 +964,127 @@ function normalizeManagedOutputPaths(value) {
   ];
 }
 
+function normalizeInventoryRuntimeInputPaths(value) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error('Pygmalion inventory runtimeInputs must be an array');
+  }
+  if (value.length > MAX_INVENTORY_RUNTIME_INPUTS) {
+    throw new Error(
+      `Pygmalion inventory runtimeInputs cannot contain more than ${MAX_INVENTORY_RUNTIME_INPUTS} entries`,
+    );
+  }
+  return [
+    ...new Set(
+      value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+          throw new Error(
+            `Pygmalion inventory runtime input ${index} must be a non-empty string`,
+          );
+        }
+        const candidate = entry.trim().replaceAll('\\', '/');
+        const segments = candidate.split('/');
+        if (
+          path.posix.isAbsolute(candidate) ||
+          /^[a-z]:\//iu.test(candidate) ||
+          segments.includes('..')
+        ) {
+          throw new Error(
+            `Pygmalion inventory runtime input must stay inside the application root: ${entry}`,
+          );
+        }
+        const normalized = path.posix.normalize(candidate).replace(/^\.\//u, '');
+        if (normalized === '.' || normalized === '') {
+          throw new Error(
+            'Pygmalion inventory runtime input cannot target the application root',
+          );
+        }
+        return normalized;
+      }),
+    ),
+  ].sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Fingerprints only explicitly declared runtime input files. This protects
+ * ignored configuration without walking large unrelated trees such as .git or
+ * node_modules.
+ */
+export async function fingerprintDevMirrorRuntimeInputs(
+  appRoot,
+  runtimeInputs = [],
+) {
+  const resolvedRoot = path.resolve(appRoot);
+  const realRoot = await fsp.realpath(resolvedRoot);
+  const inputs = normalizeInventoryRuntimeInputPaths(runtimeInputs);
+  const digest = createHash('sha256');
+  digest.update('pygmalion-inventory-runtime-inputs-v1\0');
+  let totalBytes = 0;
+  for (const input of inputs) {
+    const file = path.resolve(resolvedRoot, input);
+    let entry;
+    try {
+      entry = await fsp.lstat(file);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      digest.update(`${input}\0missing\0`);
+      continue;
+    }
+    const realFile = await fsp.realpath(file);
+    if (
+      realFile !== realRoot &&
+      !realFile.startsWith(`${realRoot}${path.sep}`)
+    ) {
+      throw new Error(
+        `Pygmalion inventory runtime input must stay inside the application root: ${input}`,
+      );
+    }
+    const target = entry.isSymbolicLink() ? await fsp.stat(realFile) : entry;
+    if (!target.isFile()) {
+      throw new Error(
+        `Pygmalion inventory runtime input must be a file, not a directory: ${input}`,
+      );
+    }
+    totalBytes += target.size;
+    if (totalBytes > MAX_INVENTORY_RUNTIME_INPUT_BYTES) {
+      throw new Error(
+        `Pygmalion inventory runtime inputs exceed ${MAX_INVENTORY_RUNTIME_INPUT_BYTES} bytes`,
+      );
+    }
+    const contents = await fsp.readFile(realFile);
+    if (contents.byteLength !== target.size) {
+      throw new Error(
+        `Pygmalion inventory runtime input changed while it was read: ${input}`,
+      );
+    }
+    digest.update(input);
+    digest.update('\0file\0');
+    if (entry.isSymbolicLink()) {
+      digest.update(await fsp.readlink(file));
+      digest.update('\0');
+    }
+    digest.update(contents);
+    digest.update('\0');
+  }
+  return digest.digest('hex');
+}
+
+/** Changes outside generator-owned paths make a checkout inexact. */
+export async function devMirrorUnexpectedChanges(mirrorRoot, managedPaths = []) {
+  const exclusions = normalizeManagedOutputPaths(managedPaths).map(
+    (entry) => `:(top,exclude,literal)${entry}`,
+  );
+  return git(
+    path.resolve(mirrorRoot),
+    'status',
+    '--porcelain',
+    '--untracked-files=all',
+    '--',
+    '.',
+    ...exclusions,
+  );
+}
+
 const MAX_REFRESH_BODY_BYTES = 4096;
 
 /**
@@ -866,6 +1329,20 @@ export function pygmalionDevMirrorPlugin(options) {
   const previewMode = normalizeViteMode(options.previewMode);
   const inventory = options.inventory;
   const inventoryOutputs = normalizeManagedOutputPaths(inventory?.outputs);
+  const inventoryRuntimeInputs = normalizeInventoryRuntimeInputPaths(
+    inventory?.runtimeInputs,
+  );
+  for (const input of inventoryRuntimeInputs) {
+    if (
+      inventoryOutputs.some(
+        (output) => input === output || input.startsWith(`${output}/`),
+      )
+    ) {
+      throw new Error(
+        `Pygmalion inventory runtime input must stay outside inventory.outputs: ${input}`,
+      );
+    }
+  }
   let managedPaths = [];
   const applyMirrorPathsForRef = (activeRef) => {
     const resolved = resolveDevMirrorWorktreePaths({
@@ -920,7 +1397,6 @@ export function pygmalionDevMirrorPlugin(options) {
   let previewPort = null;
   let previewAppRoot = null;
   let syncPromise = null;
-  let sharedLockPathPromise = null;
   // Assigned once the server is configured. A capture asks for the checkout
   // through the composition handle below, and that demand has to reach the same
   // starter the preview-origin requests use.
@@ -939,62 +1415,7 @@ export function pygmalionDevMirrorPlugin(options) {
     appOrigin: null,
   };
 
-  const sharedLockPath = async () => {
-    if (!sharedLockPathPromise) {
-      sharedLockPathPromise = (async () => {
-        const rawCommonGitDir = await git(repoRoot, 'rev-parse', '--git-common-dir');
-        const commonGitDir = path.resolve(repoRoot, rawCommonGitDir);
-        return path.join(commonGitDir, 'pygmalion', 'dev-mirror-sync.lock');
-      })();
-    }
-    return sharedLockPathPromise;
-  };
-
-  const withSharedSyncLock = async (task) => {
-    const lockPath = await sharedLockPath();
-    const token = `${process.pid}:${randomUUID()}`;
-    const deadline = Date.now() + SHARED_LOCK_TIMEOUT_MS;
-    await fsp.mkdir(path.dirname(lockPath), { recursive: true });
-
-    while (true) {
-      try {
-        const handle = await fsp.open(lockPath, 'wx');
-        await handle.writeFile(`${JSON.stringify({ token, pid: process.pid, createdAt: new Date().toISOString() })}\n`);
-        await handle.close();
-        break;
-      } catch (error) {
-        if (!(error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST')) throw error;
-        const stale = await fsp
-          .stat(lockPath)
-          .then((stat) => Date.now() - stat.mtimeMs > SHARED_LOCK_STALE_MS)
-          .catch(() => false);
-        if (stale) {
-          await fsp.unlink(lockPath).catch(() => undefined);
-          continue;
-        }
-        if (Date.now() >= deadline) {
-          throw new Error('dev screen refresh on another editor server is not finished');
-        }
-        await new Promise((resolve) => setTimeout(resolve, 250));
-      }
-    }
-
-    const heartbeat = setInterval(() => {
-      const now = new Date();
-      void fsp.utimes(lockPath, now, now).catch(() => undefined);
-    }, 2_000);
-    heartbeat.unref();
-    try {
-      return await task();
-    } finally {
-      clearInterval(heartbeat);
-      const owner = await fsp
-        .readFile(lockPath, 'utf8')
-        .then((raw) => JSON.parse(raw).token)
-        .catch(() => null);
-      if (owner === token) await fsp.unlink(lockPath).catch(() => undefined);
-    }
-  };
+  const withSharedSyncLock = (task) => withDevMirrorSyncLock(repoRoot, task);
 
   /**
    * Confirms the served checkout still is the commit the status claims.
@@ -1023,6 +1444,27 @@ export function pygmalionDevMirrorPlugin(options) {
     return status;
   };
 
+  /**
+   * Acquires one coherent checkout identity for readers such as the revision
+   * catalog endpoint. The second status check closes the reader/sync race: a
+   * sync announces `syncing` before it waits for leases, while a sync starting
+   * after this check must observe the lease before it can move the checkout.
+   */
+  const acquireSourceLease = async (expectedRevision, label = 'source reader') => {
+    return acquireExactDevMirrorSourceLease({
+      repoRoot,
+      expectedRevision,
+      label,
+      withSyncLock: withSharedSyncLock,
+      readCurrent: () => ({
+        state: status.state,
+        sourceRevision: status.commit,
+        mirrorRoot,
+        appRoot: mirrorAppRoot,
+      }),
+    });
+  };
+
   const stopPreview = async () => {
     const child = previewChild;
     previewChild = null;
@@ -1093,17 +1535,7 @@ export function pygmalionDevMirrorPlugin(options) {
     }
     if (!inventory.script && !inventory.command) return;
     const command = inventory.command ?? process.execPath;
-    const args =
-      typeof inventory.args === 'function'
-        ? inventory.args(context)
-        : inventory.args ??
-          [
-            inventory.script,
-            '--source-root',
-            context.sourceRoot,
-            '--out-root',
-            context.outputRoot,
-          ];
+    const args = resolveDevMirrorInventoryArgs(inventory, context);
     await run(command, args, { cwd: path.resolve(inventory.cwd ?? editorRoot) });
   };
 
@@ -1231,7 +1663,29 @@ export function pygmalionDevMirrorPlugin(options) {
           const { previous, commit, shortCommit } = mirrorState;
           await claimDevMirror(repoRoot, mirrorRoot, ownerToken);
           const dependenciesChanged = await syncDependencies();
+          const runtimeInputsBefore = await fingerprintDevMirrorRuntimeInputs(
+            mirrorAppRoot,
+            inventoryRuntimeInputs,
+          );
           await generateInventory(commit);
+          const runtimeInputsAfter = await fingerprintDevMirrorRuntimeInputs(
+            mirrorAppRoot,
+            inventoryRuntimeInputs,
+          );
+          if (runtimeInputsAfter !== runtimeInputsBefore) {
+            throw new Error(
+              'Inventory generation changed a declared inventory.runtimeInputs file.',
+            );
+          }
+          const unexpectedChanges = await devMirrorUnexpectedChanges(
+            mirrorRoot,
+            managedPaths,
+          );
+          if (unexpectedChanges) {
+            throw new Error(
+              `Inventory generation changed a path outside inventory.outputs: ${unexpectedChanges.split('\n')[0]}`,
+            );
+          }
           await startPreview(dependenciesChanged, commit);
 
           revision += 1;
@@ -1271,6 +1725,7 @@ export function pygmalionDevMirrorPlugin(options) {
     // Pygmalion's own plugins compose through it.
     pygmalion: {
       acquireLease: (label) => acquireDevMirrorLease({ repoRoot, mirrorRoot, label }),
+      acquireSourceLease,
       activeMirrorRoot: () => mirrorRoot,
       activeAppRoot: () => mirrorAppRoot,
       // A capture needs the checkout as much as a live frame does, but it asks