Function acquireLock

src/utils/file-lock.ts:35–72

(lockPath: string, opts: LockOptions = {})

 * can't be acquired within the retry budget.
 */
export async function acquireLock(lockPath: string, opts: LockOptions = {}): Promise<LockHandle> {
  const retries = opts.retries ?? 50;
  const intervalMs = opts.intervalMs ?? 100;
  const staleMs = opts.staleMs ?? 30_000;

  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      const fh = await fs.open(lockPath, 'wx'); // O_CREAT|O_EXCL → fails if held
      try {
        await fh.writeFile(`${process.pid} ${new Date().toISOString()}`);
      } finally {
        await fh.close();
      }
      let released = false;
      return {
        release: async () => {
          if (released) return;
          released = true;
          await fs.unlink(lockPath).catch(() => {});
        },
      };
    } catch (err: any) {
      if (err?.code !== 'EEXIST') throw err;
      // Held by someone else — reclaim if stale, else wait and retry.
      try {
        const st = await fs.stat(lockPath);
        if (Date.now() - st.mtimeMs > staleMs) {
          await fs.unlink(lockPath).catch(() => {});
          continue; // retry immediately after reclaiming a stale lock
        }
      } catch {
        /* lock vanished between open and stat — just retry */
      }
      if (attempt < retries) await sleep(intervalMs);
    }
  }
  throw new Error(`Could not acquire lock ${lockPath} after ${retries} retries (held by another process?)`);
}

/** Run `fn` while holding `lockPath`; always releases, even on throw. */
export async function withLock<T>(lockPath: string, fn: () => Promise<T>, opts?: LockOptions): Promise<T> {