blun-king-cli 9.1.624 → 9.1.625

package/bin/update-lease.js

@@ -1,599 +1,597 @@
-'use strict';
-
-const { createHash } = require('node:crypto');
-const fs = require('node:fs');
-const net = require('node:net');
-const os = require('node:os');
-const path = require('node:path');
-const { spawn } = require('node:child_process');
-
-const LEASE_ADOPT_MESSAGE = 'blun-update-lease-adopted';
-const LEASE_CANCEL_MESSAGE = 'blun-update-lease-cancel';
-const LEASE_COMMIT_MESSAGE = 'blun-update-lease-commit';
-const LEASE_HANDOFF_MESSAGE = 'blun-update-lease-handoff';
-const LEASE_BUSY_MESSAGE = 'blun-update-lease-busy';
-const LEASE_UNAVAILABLE_MESSAGE = 'blun-update-lease-unavailable';
-const LEASE_PROTOCOL_VERSION = 'BLUN_UPDATE_LEASE_V3';
-const LEASE_PROBE_TIMEOUT_MS = 500;
-const MAX_POSIX_SOCKET_PATH_BYTES = 96;
-const LEASE_CONNECTIONS = Symbol('blunLeaseConnections');
-
-function canonicalPackageIdentity(packageRoot, options = {}) {
-  if (typeof packageRoot !== 'string' || packageRoot.trim().length === 0) {
-    throw new Error('UPDATE_PACKAGE_ROOT_REQUIRED');
-  }
-  const fsImpl = options.fsImpl || fs;
-  const platform = options.platform || process.platform;
-  const realpath = fsImpl.realpathSync.native || fsImpl.realpathSync;
-  let canonical = realpath(path.resolve(packageRoot));
-  if (!fsImpl.statSync(canonical).isDirectory()) throw new Error('INVALID_UPDATE_PACKAGE_ROOT');
-  canonical = canonical.replaceAll('\\', '/');
-  if (platform === 'win32') canonical = canonical.toLowerCase();
-  return canonical;
-}
-
-function deriveUpdateLeaseEndpoint(packageRoot, options = {}) {
-  const platform = options.platform || process.platform;
-  const role = options.role === 'profile'
-    ? 'profile'
-    : options.role === 'install'
-    ? 'install'
-    : options.role === 'runtime'
-      ? 'runtime'
-      : 'notice';
-  const identity = canonicalPackageIdentity(packageRoot, options);
-  const digest = createHash('sha256')
-    .update(`blun-update-v3\0${role}\0${identity}`)
-    .digest('hex');
-  const magic = `${LEASE_PROTOCOL_VERSION} ${digest}\n`;
-  if (platform === 'win32') {
-    return Object.freeze({
-      magic,
-      path: `\\\\.\\pipe\\blun-update-v3-${digest.slice(0, 32)}`,
-      platform,
-    });
-  }
-
-  const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined);
-  const directoryName = `blun-update-${uid ?? digest.slice(0, 12)}`;
-  const requestedRoot = String(options.socketDirectory || options.tempDir || os.tmpdir())
-    .replaceAll('\\', '/');
-  let directory = options.socketDirectory
-    ? requestedRoot
-    : path.posix.join(requestedRoot, directoryName);
-  let socketPath = path.posix.join(directory, `lease-${digest.slice(0, 24)}.sock`);
-  if (Buffer.byteLength(socketPath, 'utf8') > MAX_POSIX_SOCKET_PATH_BYTES) {
-    directory = path.posix.join('/tmp', directoryName);
-    socketPath = path.posix.join(directory, `lease-${digest.slice(0, 24)}.sock`);
-  }
-  if (Buffer.byteLength(socketPath, 'utf8') > MAX_POSIX_SOCKET_PATH_BYTES) {
-    throw new Error('UPDATE_LEASE_SOCKET_PATH_TOO_LONG');
-  }
-  return Object.freeze({ directory, magic, path: socketPath, platform });
-}
-
-function connectRuntimeBroker(endpoint, options = {}) {
-  const netImpl = options.netImpl || net;
-  const timeoutMs = options.probeTimeoutMs || LEASE_PROBE_TIMEOUT_MS;
-  return new Promise((resolve) => {
-    let settled = false;
-    let received = '';
-    let socket;
-    const finish = (result) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (!result.acquired) {
-        try {
-          socket?.destroy();
-        } catch {}
-      }
-      resolve(result);
-    };
-    const timer = setTimeout(() => finish({ acquired: false, reason: 'unavailable' }), timeoutMs);
-    timer.unref?.();
-    try {
-      socket = netImpl.createConnection({ path: endpoint.path });
-      socket.setEncoding?.('utf8');
-      socket.once('connect', () => socket.write(endpoint.magic));
-      socket.on('data', (chunk) => {
-        received += String(chunk);
-        if (!received.includes('\n')) return;
-        if (received !== endpoint.magic) {
-          finish({ acquired: false, reason: 'unavailable' });
-          return;
-        }
-        let owned = true;
-        let released = false;
-        socket.once('close', () => { owned = false; });
-        socket.once('error', () => { owned = false; });
-        const lease = Object.freeze({
-          assertOwned() {
-            if (!owned || socket.destroyed) throw new Error('RUNTIME_LEASE_LOST');
-          },
-          async release() {
-            if (released) return;
-            released = true;
-            owned = false;
-            if (socket.destroyed) return;
-            socket.destroy();
-          },
-          unref() {
-            socket.unref?.();
-          },
-        });
-        finish({ acquired: true, lease });
-      });
-      socket.once('error', () => finish({ acquired: false, reason: 'unavailable' }));
-      socket.once('close', () => finish({ acquired: false, reason: 'unavailable' }));
-    } catch {
-      finish({ acquired: false, reason: 'unavailable' });
-    }
-  });
-}
-
-function spawnRuntimeBroker(packageRoot, options = {}) {
-  const spawnImpl = options.spawnImpl || spawn;
-  const child = spawnImpl(
-    options.execPath || process.execPath,
-    [__filename, '--runtime-broker'],
-    {
-      cwd: os.tmpdir(),
-      detached: true,
-      env: {
-        ...process.env,
-        BLUN_RUNTIME_BROKER_PACKAGE_ROOT: packageRoot,
-      },
-      stdio: 'ignore',
-      windowsHide: true,
-    },
-  );
-  child.unref?.();
-}
-
-async function acquireSharedRuntimeLease(options = {}) {
-  const packageRoot = canonicalPackageIdentity(options.packageRoot, options);
-  const endpoint = deriveUpdateLeaseEndpoint(packageRoot, { ...options, role: 'runtime' });
-  const deadline = Date.now() + (options.startTimeoutMs || 3_000);
-  let spawned = false;
-  while (Date.now() < deadline) {
-    const connected = await connectRuntimeBroker(endpoint, options);
-    if (connected.acquired) return connected;
-    if (!spawned) {
-      spawned = true;
-      spawnRuntimeBroker(packageRoot, options);
-    }
-    await new Promise((resolve) => setTimeout(resolve, 25));
-  }
-  const install = await tryAcquireUpdateLease({ ...options, packageRoot, role: 'install' });
-  if (install.acquired) {
-    await install.lease.release();
-    return { acquired: false, reason: 'unavailable' };
-  }
-  return { acquired: false, reason: install.reason };
-}
-
-async function runRuntimeBroker(options = {}) {
-  const packageRoot = options.packageRoot
-    || String(process.env.BLUN_RUNTIME_BROKER_PACKAGE_ROOT || '');
-  if (!path.isAbsolute(packageRoot)) throw new Error('RUNTIME_BROKER_PACKAGE_ROOT_REQUIRED');
-  const install = await tryAcquireUpdateLease({ packageRoot, role: 'install' });
-  if (!install.acquired) return false;
-
-  const endpoint = deriveUpdateLeaseEndpoint(packageRoot, { role: 'runtime' });
-  ensurePrivateSocketDirectory(endpoint);
-  const holders = new Set();
-  let idleTimer;
-  let closing = false;
-  let identity;
-  const closeBroker = async (server) => {
-    if (closing) return;
-    closing = true;
-    clearTimeout(idleTimer);
-    await closeServer(server);
-    removeOwnedSocket(endpoint, identity);
-    await install.lease.release();
-  };
-  const server = net.createServer((socket) => {
-    socket.setEncoding('utf8');
-    let received = '';
-    let admitted = false;
-    const reject = () => {
-      try {
-        socket.destroy();
-      } catch {}
-    };
-    const onData = (chunk) => {
-      if (admitted) return;
-      received += String(chunk);
-      if (Buffer.byteLength(received, 'utf8') > Buffer.byteLength(endpoint.magic, 'utf8')) {
-        reject();
-        return;
-      }
-      if (!received.includes('\n')) return;
-      if (received !== endpoint.magic) {
-        reject();
-        return;
-      }
-      admitted = true;
-      clearTimeout(idleTimer);
-      holders.add(socket);
-      socket.write(endpoint.magic);
-    };
-    socket.on('data', onData);
-    socket.on('error', () => {});
-    socket.once('close', () => {
-      holders.delete(socket);
-      if (holders.size === 0 && !closing) {
-        idleTimer = setTimeout(() => { void closeBroker(server); }, 0);
-      }
-    });
-  });
-  try {
-    await new Promise((resolve, reject) => {
-      const onError = (error) => {
-        server.removeListener('error', onError);
-        reject(error);
-      };
-      server.once('error', onError);
-      server.listen({ path: endpoint.path, exclusive: true }, () => {
-        server.removeListener('error', onError);
-        resolve();
-      });
-    });
-    identity = recordSocketIdentity(endpoint);
-  } catch {
-    await closeServer(server);
-    await install.lease.release();
-    return false;
-  }
-  install.lease.unref();
-  server.unref?.();
-  idleTimer = setTimeout(() => { void closeBroker(server); }, 5_000);
-  return true;
-}
-
-function closeServer(server) {
-  for (const socket of server[LEASE_CONNECTIONS] || []) {
-    try {
-      socket.destroy();
-    } catch {}
-  }
-  if (!server.listening) return Promise.resolve();
-  try {
-    server.close();
-    server.unref?.();
-  } catch {}
-  return Promise.resolve();
-}
-
-function ensurePrivateSocketDirectory(endpoint, options = {}) {
-  if (endpoint.platform === 'win32') return;
-  const fsImpl = options.fsImpl || fs;
-  fsImpl.mkdirSync(endpoint.directory, { recursive: true, mode: 0o700 });
-  const stat = fsImpl.lstatSync(endpoint.directory);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) {
-    throw new Error('INVALID_UPDATE_LEASE_DIRECTORY');
-  }
-  if (typeof process.getuid === 'function'
-    && Number.isInteger(stat.uid)
-    && stat.uid !== process.getuid()) {
-    throw new Error('INVALID_UPDATE_LEASE_DIRECTORY_OWNER');
-  }
-  fsImpl.chmodSync(endpoint.directory, 0o700);
-}
-
-function listenForLease(endpoint, options = {}) {
-  const netImpl = options.netImpl || net;
-  return new Promise((resolve, reject) => {
-    const server = netImpl.createServer((socket) => {
-      server[LEASE_CONNECTIONS].add(socket);
-      socket.once('close', () => server[LEASE_CONNECTIONS].delete(socket));
-      socket.on('error', () => {});
-      socket.end(endpoint.magic);
-    });
-    server[LEASE_CONNECTIONS] = new Set();
-    const onError = (error) => {
-      server.removeListener('error', onError);
-      reject(error);
-    };
-    server.once('error', onError);
-    server.listen({ path: endpoint.path, exclusive: true }, () => {
-      server.removeListener('error', onError);
-      resolve(server);
-    });
-  });
-}
-
-function probeExistingLease(endpoint, options = {}) {
-  const netImpl = options.netImpl || net;
-  const timeoutMs = options.probeTimeoutMs || LEASE_PROBE_TIMEOUT_MS;
-  return new Promise((resolve) => {
-    let settled = false;
-    let received = '';
-    let socket;
-    const finish = (state, error) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      try {
-        socket?.destroy();
-      } catch {}
-      // oxlint-disable-next-line promise/no-multiple-resolved -- settled is the idempotence guard.
-      resolve({ error, state });
-    };
-    const timer = setTimeout(() => finish('foreign'), timeoutMs);
-    timer.unref?.();
-    try {
-      socket = netImpl.createConnection({ path: endpoint.path });
-      socket.setEncoding?.('utf8');
-      socket.on('data', (chunk) => {
-        received += String(chunk);
-        if (Buffer.byteLength(received, 'utf8') > Buffer.byteLength(endpoint.magic, 'utf8')) {
-          finish('foreign');
-        }
-      });
-      socket.once('end', () => finish(received === endpoint.magic ? 'owner' : 'foreign'));
-      socket.once('error', (error) => {
-        const stale = error?.code === 'ECONNREFUSED' || error?.code === 'ENOENT';
-        finish(stale ? 'stale' : 'foreign', error);
-      });
-      socket.once('close', () => {
-        if (!settled) finish(received === endpoint.magic ? 'owner' : 'foreign');
-      });
-    } catch (error) {
-      const stale = error?.code === 'ECONNREFUSED' || error?.code === 'ENOENT';
-      finish(stale ? 'stale' : 'foreign', error);
-    }
-  });
-}
-
-function observeSocketPath(endpoint, options = {}) {
-  if (endpoint.platform === 'win32') return { state: 'not_applicable' };
-  const fsImpl = options.fsImpl || fs;
-  try {
-    const stat = fsImpl.lstatSync(endpoint.path);
-    if (!stat.isSocket() || stat.isSymbolicLink()) return { state: 'unsafe' };
-    return { dev: stat.dev, ino: stat.ino, state: 'socket' };
-  } catch (error) {
-    return error?.code === 'ENOENT' ? { state: 'missing' } : { state: 'unsafe' };
-  }
-}
-
-function removeObservedStaleSocket(endpoint, observed, options = {}) {
-  if (endpoint.platform === 'win32') return false;
-  const fsImpl = options.fsImpl || fs;
-  try {
-    const stat = fsImpl.lstatSync(endpoint.path);
-    if (observed.state !== 'socket'
-      || !stat.isSocket()
-      || stat.isSymbolicLink()
-      || stat.dev !== observed.dev
-      || stat.ino !== observed.ino) {
-      return false;
-    }
-    fsImpl.unlinkSync(endpoint.path);
-    return true;
-  } catch (error) {
-    return error?.code === 'ENOENT' && observed.state === 'missing';
-  }
-}
-
-function recordSocketIdentity(endpoint, options = {}) {
-  if (endpoint.platform === 'win32') return undefined;
-  const fsImpl = options.fsImpl || fs;
-  const stat = fsImpl.lstatSync(endpoint.path);
-  if (!stat.isSocket() || stat.isSymbolicLink()) throw new Error('INVALID_UPDATE_LEASE_SOCKET');
-  fsImpl.chmodSync(endpoint.path, 0o600);
-  return { dev: stat.dev, ino: stat.ino };
-}
-
-function removeOwnedSocket(endpoint, identity, options = {}) {
-  if (endpoint.platform === 'win32' || !identity) return;
-  const fsImpl = options.fsImpl || fs;
-  try {
-    const stat = fsImpl.lstatSync(endpoint.path);
-    if (stat.isSocket()
-      && !stat.isSymbolicLink()
-      && stat.dev === identity.dev
-      && stat.ino === identity.ino) {
-      fsImpl.unlinkSync(endpoint.path);
-    }
-  } catch {}
-}
-
-async function tryAcquireUpdateLease(options = {}) {
-  let endpoint;
-  try {
-    endpoint = deriveUpdateLeaseEndpoint(options.packageRoot, options);
-    ensurePrivateSocketDirectory(endpoint, options);
-  } catch {
-    return { acquired: false, reason: 'unavailable' };
-  }
-
-  let server;
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      server = await listenForLease(endpoint, options);
-      break;
-    } catch (error) {
-      if (error?.code !== 'EADDRINUSE') {
-        return { acquired: false, reason: 'unavailable' };
-      }
-      const observed = observeSocketPath(endpoint, options);
-      const probe = await probeExistingLease(endpoint, options);
-      if (probe.state === 'owner') return { acquired: false, reason: 'busy' };
-      if (probe.state !== 'stale' || attempt > 0) {
-        return { acquired: false, reason: 'unavailable' };
-      }
-      if (endpoint.platform === 'win32') continue;
-      if (!removeObservedStaleSocket(endpoint, observed, options)) {
-        return { acquired: false, reason: 'unavailable' };
-      }
-    }
-  }
-  if (!server) return { acquired: false, reason: 'unavailable' };
-
-  let identity;
-  try {
-    identity = recordSocketIdentity(endpoint, options);
-  } catch {
-    await closeServer(server);
-    removeOwnedSocket(endpoint, identity, options);
-    return { acquired: false, reason: 'unavailable' };
-  }
-
-  let owned = true;
-  let released = false;
-  server.on('error', () => {
-    owned = false;
-  });
-  server.on('close', () => {
-    owned = false;
-  });
-  const lease = Object.freeze({
-    assertOwned() {
-      if (!owned || !server.listening) throw new Error('UPDATE_LEASE_LOST');
-    },
-    async release() {
-      if (released) return;
-      released = true;
-      owned = false;
-      await closeServer(server);
-      removeOwnedSocket(endpoint, identity, options);
-    },
-    unref() {
-      server.unref?.();
-    },
-  });
-  return { acquired: true, lease };
-}
-
-function isInstallerMessage(message) {
-  if (!message || message.type !== LEASE_HANDOFF_MESSAGE) return false;
-  const installer = message.installer;
-  return installer
-    && typeof installer === 'object'
-    && typeof message.packageRoot === 'string'
-    && path.isAbsolute(message.packageRoot)
-    && typeof installer.npmCliPath === 'string'
-    && path.isAbsolute(installer.npmCliPath)
-    && Array.isArray(installer.npmArgs)
-    && installer.npmArgs.every((entry) => typeof entry === 'string')
-    && typeof installer.installCwd === 'string'
-    && path.isAbsolute(installer.installCwd);
-}
-
-function runInstallerWorker() {
-  let state = 'BOOT';
-  let started = false;
-  let installLease;
-  let installCwd;
-  const isControlMessage = (message, type) => message
-    && typeof message === 'object'
-    && Object.getPrototypeOf(message) === Object.prototype
-    && Reflect.ownKeys(message).length === 1
-    && message.type === type;
-  const exitWithoutInstall = async (code = 0) => {
-    if (state === 'DONE') return;
-    state = 'DONE';
-    try {
-      await installLease?.release();
-    } catch {}
-    process.exit(code);
-  };
-  const startInstaller = (installer) => {
-    if (started || state !== 'COMMITTED') return;
-    started = true;
-    try {
-      installLease.assertOwned();
-      process.chdir(installer.installCwd);
-      process.argv = [process.execPath, installer.npmCliPath, ...installer.npmArgs];
-      require(installer.npmCliPath);
-    } catch {
-      process.exit(1);
-    }
-  };
-
-  process.once('message', async (message) => {
-    if (state !== 'BOOT' || !isInstallerMessage(message)) {
-      process.exit(1);
-      return;
-    }
-    state = 'PREPARED';
-    installCwd = message.installer.installCwd;
-    process.once('exit', () => {
-      if (!installCwd) return;
-      try {
-        process.chdir(path.dirname(installCwd));
-        fs.rmSync(installCwd, { recursive: true, force: true });
-      } catch {}
-    });
-    const leaseResult = await tryAcquireUpdateLease({
-      packageRoot: message.packageRoot,
-      role: 'install',
-    });
-    if (!leaseResult.acquired) {
-      const type = leaseResult.reason === 'busy'
-        ? LEASE_BUSY_MESSAGE
-        : LEASE_UNAVAILABLE_MESSAGE;
-      if (process.connected) {
-        try {
-          process.send({ type }, () => process.exit(75));
-          return;
-        } catch {}
-      }
-      process.exit(75);
-      return;
-    }
-    installLease = leaseResult.lease;
-    state = 'LEASED';
-    if (!process.connected) {
-      await exitWithoutInstall();
-      return;
-    }
-    const onControl = (control) => {
-      if (state !== 'LEASED') {
-        void exitWithoutInstall(1);
-        return;
-      }
-      if (isControlMessage(control, LEASE_CANCEL_MESSAGE)) {
-        void exitWithoutInstall();
-        return;
-      }
-      if (!isControlMessage(control, LEASE_COMMIT_MESSAGE)) {
-        void exitWithoutInstall(1);
-        return;
-      }
-      state = 'COMMITTED';
-      setImmediate(() => startInstaller(message.installer));
-    };
-    process.once('message', onControl);
-    try {
-      process.send({ type: LEASE_ADOPT_MESSAGE });
-    } catch {
-      process.removeListener('message', onControl);
-      await exitWithoutInstall();
-    }
-  });
-  process.once('disconnect', () => {
-    if (state !== 'COMMITTED' && state !== 'DONE') void exitWithoutInstall();
-  });
-}
-
-if (require.main === module && process.argv[2] === '--installer-worker') {
-  runInstallerWorker();
-} else if (require.main === module && process.argv[2] === '--runtime-broker') {
-  void runRuntimeBroker().then((started) => {
-    if (!started) process.exitCode = 75;
-  }).catch(() => {
-    process.exitCode = 1;
-  });
-}
-
-module.exports = {
-  acquireSharedRuntimeLease,
-  deriveUpdateLeaseEndpoint,
-  runRuntimeBroker,
-  tryAcquireUpdateLease,
-};
+'use strict';
+
+const { createHash } = require('node:crypto');
+const fs = require('node:fs');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const LEASE_ADOPT_MESSAGE = 'blun-update-lease-adopted';
+const LEASE_CANCEL_MESSAGE = 'blun-update-lease-cancel';
+const LEASE_COMMIT_MESSAGE = 'blun-update-lease-commit';
+const LEASE_HANDOFF_MESSAGE = 'blun-update-lease-handoff';
+const LEASE_BUSY_MESSAGE = 'blun-update-lease-busy';
+const LEASE_UNAVAILABLE_MESSAGE = 'blun-update-lease-unavailable';
+const LEASE_PROTOCOL_VERSION = 'BLUN_UPDATE_LEASE_V3';
+const LEASE_PROBE_TIMEOUT_MS = 500;
+const MAX_POSIX_SOCKET_PATH_BYTES = 96;
+const LEASE_CONNECTIONS = Symbol('blunLeaseConnections');
+
+function canonicalPackageIdentity(packageRoot, options = {}) {
+  if (typeof packageRoot !== 'string' || packageRoot.trim().length === 0) {
+    throw new Error('UPDATE_PACKAGE_ROOT_REQUIRED');
+  }
+  const fsImpl = options.fsImpl || fs;
+  const platform = options.platform || process.platform;
+  const realpath = fsImpl.realpathSync.native || fsImpl.realpathSync;
+  let canonical = realpath(path.resolve(packageRoot));
+  if (!fsImpl.statSync(canonical).isDirectory()) throw new Error('INVALID_UPDATE_PACKAGE_ROOT');
+  canonical = canonical.replaceAll('\\', '/');
+  if (platform === 'win32') canonical = canonical.toLowerCase();
+  return canonical;
+}
+
+function deriveUpdateLeaseEndpoint(packageRoot, options = {}) {
+  const platform = options.platform || process.platform;
+  const role = options.role === 'install'
+    ? 'install'
+    : options.role === 'runtime'
+      ? 'runtime'
+      : 'notice';
+  const identity = canonicalPackageIdentity(packageRoot, options);
+  const digest = createHash('sha256')
+    .update(`blun-update-v3\0${role}\0${identity}`)
+    .digest('hex');
+  const magic = `${LEASE_PROTOCOL_VERSION} ${digest}\n`;
+  if (platform === 'win32') {
+    return Object.freeze({
+      magic,
+      path: `\\\\.\\pipe\\blun-update-v3-${digest.slice(0, 32)}`,
+      platform,
+    });
+  }
+
+  const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined);
+  const directoryName = `blun-update-${uid ?? digest.slice(0, 12)}`;
+  const requestedRoot = String(options.socketDirectory || options.tempDir || os.tmpdir())
+    .replaceAll('\\', '/');
+  let directory = options.socketDirectory
+    ? requestedRoot
+    : path.posix.join(requestedRoot, directoryName);
+  let socketPath = path.posix.join(directory, `lease-${digest.slice(0, 24)}.sock`);
+  if (Buffer.byteLength(socketPath, 'utf8') > MAX_POSIX_SOCKET_PATH_BYTES) {
+    directory = path.posix.join('/tmp', directoryName);
+    socketPath = path.posix.join(directory, `lease-${digest.slice(0, 24)}.sock`);
+  }
+  if (Buffer.byteLength(socketPath, 'utf8') > MAX_POSIX_SOCKET_PATH_BYTES) {
+    throw new Error('UPDATE_LEASE_SOCKET_PATH_TOO_LONG');
+  }
+  return Object.freeze({ directory, magic, path: socketPath, platform });
+}
+
+function connectRuntimeBroker(endpoint, options = {}) {
+  const netImpl = options.netImpl || net;
+  const timeoutMs = options.probeTimeoutMs || LEASE_PROBE_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    let settled = false;
+    let received = '';
+    let socket;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (!result.acquired) {
+        try {
+          socket?.destroy();
+        } catch {}
+      }
+      resolve(result);
+    };
+    const timer = setTimeout(() => finish({ acquired: false, reason: 'unavailable' }), timeoutMs);
+    timer.unref?.();
+    try {
+      socket = netImpl.createConnection({ path: endpoint.path });
+      socket.setEncoding?.('utf8');
+      socket.once('connect', () => socket.write(endpoint.magic));
+      socket.on('data', (chunk) => {
+        received += String(chunk);
+        if (!received.includes('\n')) return;
+        if (received !== endpoint.magic) {
+          finish({ acquired: false, reason: 'unavailable' });
+          return;
+        }
+        let owned = true;
+        let released = false;
+        socket.once('close', () => { owned = false; });
+        socket.once('error', () => { owned = false; });
+        const lease = Object.freeze({
+          assertOwned() {
+            if (!owned || socket.destroyed) throw new Error('RUNTIME_LEASE_LOST');
+          },
+          async release() {
+            if (released) return;
+            released = true;
+            owned = false;
+            if (socket.destroyed) return;
+            socket.destroy();
+          },
+          unref() {
+            socket.unref?.();
+          },
+        });
+        finish({ acquired: true, lease });
+      });
+      socket.once('error', () => finish({ acquired: false, reason: 'unavailable' }));
+      socket.once('close', () => finish({ acquired: false, reason: 'unavailable' }));
+    } catch {
+      finish({ acquired: false, reason: 'unavailable' });
+    }
+  });
+}
+
+function spawnRuntimeBroker(packageRoot, options = {}) {
+  const spawnImpl = options.spawnImpl || spawn;
+  const child = spawnImpl(
+    options.execPath || process.execPath,
+    [__filename, '--runtime-broker'],
+    {
+      cwd: os.tmpdir(),
+      detached: true,
+      env: {
+        ...process.env,
+        BLUN_RUNTIME_BROKER_PACKAGE_ROOT: packageRoot,
+      },
+      stdio: 'ignore',
+      windowsHide: true,
+    },
+  );
+  child.unref?.();
+}
+
+async function acquireSharedRuntimeLease(options = {}) {
+  const packageRoot = canonicalPackageIdentity(options.packageRoot, options);
+  const endpoint = deriveUpdateLeaseEndpoint(packageRoot, { ...options, role: 'runtime' });
+  const deadline = Date.now() + (options.startTimeoutMs || 3_000);
+  let spawned = false;
+  while (Date.now() < deadline) {
+    const connected = await connectRuntimeBroker(endpoint, options);
+    if (connected.acquired) return connected;
+    if (!spawned) {
+      spawned = true;
+      spawnRuntimeBroker(packageRoot, options);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  const install = await tryAcquireUpdateLease({ ...options, packageRoot, role: 'install' });
+  if (install.acquired) {
+    await install.lease.release();
+    return { acquired: false, reason: 'unavailable' };
+  }
+  return { acquired: false, reason: install.reason };
+}
+
+async function runRuntimeBroker(options = {}) {
+  const packageRoot = options.packageRoot
+    || String(process.env.BLUN_RUNTIME_BROKER_PACKAGE_ROOT || '');
+  if (!path.isAbsolute(packageRoot)) throw new Error('RUNTIME_BROKER_PACKAGE_ROOT_REQUIRED');
+  const install = await tryAcquireUpdateLease({ packageRoot, role: 'install' });
+  if (!install.acquired) return false;
+
+  const endpoint = deriveUpdateLeaseEndpoint(packageRoot, { role: 'runtime' });
+  ensurePrivateSocketDirectory(endpoint);
+  const holders = new Set();
+  let idleTimer;
+  let closing = false;
+  let identity;
+  const closeBroker = async (server) => {
+    if (closing) return;
+    closing = true;
+    clearTimeout(idleTimer);
+    await closeServer(server);
+    removeOwnedSocket(endpoint, identity);
+    await install.lease.release();
+  };
+  const server = net.createServer((socket) => {
+    socket.setEncoding('utf8');
+    let received = '';
+    let admitted = false;
+    const reject = () => {
+      try {
+        socket.destroy();
+      } catch {}
+    };
+    const onData = (chunk) => {
+      if (admitted) return;
+      received += String(chunk);
+      if (Buffer.byteLength(received, 'utf8') > Buffer.byteLength(endpoint.magic, 'utf8')) {
+        reject();
+        return;
+      }
+      if (!received.includes('\n')) return;
+      if (received !== endpoint.magic) {
+        reject();
+        return;
+      }
+      admitted = true;
+      clearTimeout(idleTimer);
+      holders.add(socket);
+      socket.write(endpoint.magic);
+    };
+    socket.on('data', onData);
+    socket.on('error', () => {});
+    socket.once('close', () => {
+      holders.delete(socket);
+      if (holders.size === 0 && !closing) {
+        idleTimer = setTimeout(() => { void closeBroker(server); }, 0);
+      }
+    });
+  });
+  try {
+    await new Promise((resolve, reject) => {
+      const onError = (error) => {
+        server.removeListener('error', onError);
+        reject(error);
+      };
+      server.once('error', onError);
+      server.listen({ path: endpoint.path, exclusive: true }, () => {
+        server.removeListener('error', onError);
+        resolve();
+      });
+    });
+    identity = recordSocketIdentity(endpoint);
+  } catch {
+    await closeServer(server);
+    await install.lease.release();
+    return false;
+  }
+  install.lease.unref();
+  server.unref?.();
+  idleTimer = setTimeout(() => { void closeBroker(server); }, 5_000);
+  return true;
+}
+
+function closeServer(server) {
+  for (const socket of server[LEASE_CONNECTIONS] || []) {
+    try {
+      socket.destroy();
+    } catch {}
+  }
+  if (!server.listening) return Promise.resolve();
+  try {
+    server.close();
+    server.unref?.();
+  } catch {}
+  return Promise.resolve();
+}
+
+function ensurePrivateSocketDirectory(endpoint, options = {}) {
+  if (endpoint.platform === 'win32') return;
+  const fsImpl = options.fsImpl || fs;
+  fsImpl.mkdirSync(endpoint.directory, { recursive: true, mode: 0o700 });
+  const stat = fsImpl.lstatSync(endpoint.directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error('INVALID_UPDATE_LEASE_DIRECTORY');
+  }
+  if (typeof process.getuid === 'function'
+    && Number.isInteger(stat.uid)
+    && stat.uid !== process.getuid()) {
+    throw new Error('INVALID_UPDATE_LEASE_DIRECTORY_OWNER');
+  }
+  fsImpl.chmodSync(endpoint.directory, 0o700);
+}
+
+function listenForLease(endpoint, options = {}) {
+  const netImpl = options.netImpl || net;
+  return new Promise((resolve, reject) => {
+    const server = netImpl.createServer((socket) => {
+      server[LEASE_CONNECTIONS].add(socket);
+      socket.once('close', () => server[LEASE_CONNECTIONS].delete(socket));
+      socket.on('error', () => {});
+      socket.end(endpoint.magic);
+    });
+    server[LEASE_CONNECTIONS] = new Set();
+    const onError = (error) => {
+      server.removeListener('error', onError);
+      reject(error);
+    };
+    server.once('error', onError);
+    server.listen({ path: endpoint.path, exclusive: true }, () => {
+      server.removeListener('error', onError);
+      resolve(server);
+    });
+  });
+}
+
+function probeExistingLease(endpoint, options = {}) {
+  const netImpl = options.netImpl || net;
+  const timeoutMs = options.probeTimeoutMs || LEASE_PROBE_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    let settled = false;
+    let received = '';
+    let socket;
+    const finish = (state, error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        socket?.destroy();
+      } catch {}
+      // oxlint-disable-next-line promise/no-multiple-resolved -- settled is the idempotence guard.
+      resolve({ error, state });
+    };
+    const timer = setTimeout(() => finish('foreign'), timeoutMs);
+    timer.unref?.();
+    try {
+      socket = netImpl.createConnection({ path: endpoint.path });
+      socket.setEncoding?.('utf8');
+      socket.on('data', (chunk) => {
+        received += String(chunk);
+        if (Buffer.byteLength(received, 'utf8') > Buffer.byteLength(endpoint.magic, 'utf8')) {
+          finish('foreign');
+        }
+      });
+      socket.once('end', () => finish(received === endpoint.magic ? 'owner' : 'foreign'));
+      socket.once('error', (error) => {
+        const stale = error?.code === 'ECONNREFUSED' || error?.code === 'ENOENT';
+        finish(stale ? 'stale' : 'foreign', error);
+      });
+      socket.once('close', () => {
+        if (!settled) finish(received === endpoint.magic ? 'owner' : 'foreign');
+      });
+    } catch (error) {
+      const stale = error?.code === 'ECONNREFUSED' || error?.code === 'ENOENT';
+      finish(stale ? 'stale' : 'foreign', error);
+    }
+  });
+}
+
+function observeSocketPath(endpoint, options = {}) {
+  if (endpoint.platform === 'win32') return { state: 'not_applicable' };
+  const fsImpl = options.fsImpl || fs;
+  try {
+    const stat = fsImpl.lstatSync(endpoint.path);
+    if (!stat.isSocket() || stat.isSymbolicLink()) return { state: 'unsafe' };
+    return { dev: stat.dev, ino: stat.ino, state: 'socket' };
+  } catch (error) {
+    return error?.code === 'ENOENT' ? { state: 'missing' } : { state: 'unsafe' };
+  }
+}
+
+function removeObservedStaleSocket(endpoint, observed, options = {}) {
+  if (endpoint.platform === 'win32') return false;
+  const fsImpl = options.fsImpl || fs;
+  try {
+    const stat = fsImpl.lstatSync(endpoint.path);
+    if (observed.state !== 'socket'
+      || !stat.isSocket()
+      || stat.isSymbolicLink()
+      || stat.dev !== observed.dev
+      || stat.ino !== observed.ino) {
+      return false;
+    }
+    fsImpl.unlinkSync(endpoint.path);
+    return true;
+  } catch (error) {
+    return error?.code === 'ENOENT' && observed.state === 'missing';
+  }
+}
+
+function recordSocketIdentity(endpoint, options = {}) {
+  if (endpoint.platform === 'win32') return undefined;
+  const fsImpl = options.fsImpl || fs;
+  const stat = fsImpl.lstatSync(endpoint.path);
+  if (!stat.isSocket() || stat.isSymbolicLink()) throw new Error('INVALID_UPDATE_LEASE_SOCKET');
+  fsImpl.chmodSync(endpoint.path, 0o600);
+  return { dev: stat.dev, ino: stat.ino };
+}
+
+function removeOwnedSocket(endpoint, identity, options = {}) {
+  if (endpoint.platform === 'win32' || !identity) return;
+  const fsImpl = options.fsImpl || fs;
+  try {
+    const stat = fsImpl.lstatSync(endpoint.path);
+    if (stat.isSocket()
+      && !stat.isSymbolicLink()
+      && stat.dev === identity.dev
+      && stat.ino === identity.ino) {
+      fsImpl.unlinkSync(endpoint.path);
+    }
+  } catch {}
+}
+
+async function tryAcquireUpdateLease(options = {}) {
+  let endpoint;
+  try {
+    endpoint = deriveUpdateLeaseEndpoint(options.packageRoot, options);
+    ensurePrivateSocketDirectory(endpoint, options);
+  } catch {
+    return { acquired: false, reason: 'unavailable' };
+  }
+
+  let server;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      server = await listenForLease(endpoint, options);
+      break;
+    } catch (error) {
+      if (error?.code !== 'EADDRINUSE') {
+        return { acquired: false, reason: 'unavailable' };
+      }
+      const observed = observeSocketPath(endpoint, options);
+      const probe = await probeExistingLease(endpoint, options);
+      if (probe.state === 'owner') return { acquired: false, reason: 'busy' };
+      if (probe.state !== 'stale' || attempt > 0) {
+        return { acquired: false, reason: 'unavailable' };
+      }
+      if (endpoint.platform === 'win32') continue;
+      if (!removeObservedStaleSocket(endpoint, observed, options)) {
+        return { acquired: false, reason: 'unavailable' };
+      }
+    }
+  }
+  if (!server) return { acquired: false, reason: 'unavailable' };
+
+  let identity;
+  try {
+    identity = recordSocketIdentity(endpoint, options);
+  } catch {
+    await closeServer(server);
+    removeOwnedSocket(endpoint, identity, options);
+    return { acquired: false, reason: 'unavailable' };
+  }
+
+  let owned = true;
+  let released = false;
+  server.on('error', () => {
+    owned = false;
+  });
+  server.on('close', () => {
+    owned = false;
+  });
+  const lease = Object.freeze({
+    assertOwned() {
+      if (!owned || !server.listening) throw new Error('UPDATE_LEASE_LOST');
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      owned = false;
+      await closeServer(server);
+      removeOwnedSocket(endpoint, identity, options);
+    },
+    unref() {
+      server.unref?.();
+    },
+  });
+  return { acquired: true, lease };
+}
+
+function isInstallerMessage(message) {
+  if (!message || message.type !== LEASE_HANDOFF_MESSAGE) return false;
+  const installer = message.installer;
+  return installer
+    && typeof installer === 'object'
+    && typeof message.packageRoot === 'string'
+    && path.isAbsolute(message.packageRoot)
+    && typeof installer.npmCliPath === 'string'
+    && path.isAbsolute(installer.npmCliPath)
+    && Array.isArray(installer.npmArgs)
+    && installer.npmArgs.every((entry) => typeof entry === 'string')
+    && typeof installer.installCwd === 'string'
+    && path.isAbsolute(installer.installCwd);
+}
+
+function runInstallerWorker() {
+  let state = 'BOOT';
+  let started = false;
+  let installLease;
+  let installCwd;
+  const isControlMessage = (message, type) => message
+    && typeof message === 'object'
+    && Object.getPrototypeOf(message) === Object.prototype
+    && Reflect.ownKeys(message).length === 1
+    && message.type === type;
+  const exitWithoutInstall = async (code = 0) => {
+    if (state === 'DONE') return;
+    state = 'DONE';
+    try {
+      await installLease?.release();
+    } catch {}
+    process.exit(code);
+  };
+  const startInstaller = (installer) => {
+    if (started || state !== 'COMMITTED') return;
+    started = true;
+    try {
+      installLease.assertOwned();
+      process.chdir(installer.installCwd);
+      process.argv = [process.execPath, installer.npmCliPath, ...installer.npmArgs];
+      require(installer.npmCliPath);
+    } catch {
+      process.exit(1);
+    }
+  };
+
+  process.once('message', async (message) => {
+    if (state !== 'BOOT' || !isInstallerMessage(message)) {
+      process.exit(1);
+      return;
+    }
+    state = 'PREPARED';
+    installCwd = message.installer.installCwd;
+    process.once('exit', () => {
+      if (!installCwd) return;
+      try {
+        process.chdir(path.dirname(installCwd));
+        fs.rmSync(installCwd, { recursive: true, force: true });
+      } catch {}
+    });
+    const leaseResult = await tryAcquireUpdateLease({
+      packageRoot: message.packageRoot,
+      role: 'install',
+    });
+    if (!leaseResult.acquired) {
+      const type = leaseResult.reason === 'busy'
+        ? LEASE_BUSY_MESSAGE
+        : LEASE_UNAVAILABLE_MESSAGE;
+      if (process.connected) {
+        try {
+          process.send({ type }, () => process.exit(75));
+          return;
+        } catch {}
+      }
+      process.exit(75);
+      return;
+    }
+    installLease = leaseResult.lease;
+    state = 'LEASED';
+    if (!process.connected) {
+      await exitWithoutInstall();
+      return;
+    }
+    const onControl = (control) => {
+      if (state !== 'LEASED') {
+        void exitWithoutInstall(1);
+        return;
+      }
+      if (isControlMessage(control, LEASE_CANCEL_MESSAGE)) {
+        void exitWithoutInstall();
+        return;
+      }
+      if (!isControlMessage(control, LEASE_COMMIT_MESSAGE)) {
+        void exitWithoutInstall(1);
+        return;
+      }
+      state = 'COMMITTED';
+      setImmediate(() => startInstaller(message.installer));
+    };
+    process.once('message', onControl);
+    try {
+      process.send({ type: LEASE_ADOPT_MESSAGE });
+    } catch {
+      process.removeListener('message', onControl);
+      await exitWithoutInstall();
+    }
+  });
+  process.once('disconnect', () => {
+    if (state !== 'COMMITTED' && state !== 'DONE') void exitWithoutInstall();
+  });
+}
+
+if (require.main === module && process.argv[2] === '--installer-worker') {
+  runInstallerWorker();
+} else if (require.main === module && process.argv[2] === '--runtime-broker') {
+  void runRuntimeBroker().then((started) => {
+    if (!started) process.exitCode = 75;
+  }).catch(() => {
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  acquireSharedRuntimeLease,
+  deriveUpdateLeaseEndpoint,
+  runRuntimeBroker,
+  tryAcquireUpdateLease,
+};