Function acquireLock

packages/server/src/lock.ts:193–246

(opts: AcquireLockOptions)

 * recorded pid is no longer running.
 */
export function acquireLock(opts: AcquireLockOptions): AcquireLockResult {
  const lockPath = opts.lockPath ?? DEFAULT_LOCK_PATH;
  const pid = opts.pid ?? process.pid;
  const startedAt = opts.nowIso ?? new Date().toISOString();
  const contents: LockContents = {
    pid,
    started_at: startedAt,
    host: opts.host,
    port: opts.port,
    ...(opts.hostVersion !== undefined ? { host_version: opts.hostVersion } : {}),
    ...(opts.entry !== undefined ? { entry: opts.entry } : {}),
  };

  mkdirSync(dirname(lockPath), { recursive: true });

  // First try: clean acquire.
  if (tryExclusiveCreate(lockPath, contents)) {
    return makeReleaseHandle(lockPath, pid);
  }

  // Lock exists — inspect.
  const existing = readLockContents(lockPath);
  if (existing && pidAlive(existing.pid)) {
    // Live owner — refuse to take over. Note that "same pid as ours" still
    // counts as live: callers that genuinely want to swap should release the
    // existing handle first, not stomp via acquireLock.
    throw new ServerLockedError(
      `server already running (pid=${existing.pid}, port=${existing.port}, started=${existing.started_at})`,
      existing,
    );
  }

  // Stale (dead pid) or unparseable — take over.
  try {
    unlinkSync(lockPath);
  } catch (err) {
    // EBUSY/ENOENT both acceptable — race with another concurrent acquirer.
    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
      throw err;
    }
  }

  if (!tryExclusiveCreate(lockPath, contents)) {
    // Someone slipped in. Re-read for diagnostic.
    const winner = readLockContents(lockPath);
    throw new ServerLockedError(
      winner
        ? `server already running (pid=${winner.pid}, port=${winner.port}, started=${winner.started_at})`
        : 'lock file present but unreadable',
      winner ?? { pid: -1, started_at: '', port: opts.port },
    );
  }
  return makeReleaseHandle(lockPath, pid);
}

function makeReleaseHandle(lockPath: string, ownerPid: number): AcquireLockResult {
  let released = false;