@mindrian_os/install 1.13.0-beta.21 → 1.13.0-beta.24

package/lib/core/npm-cli-resolve.cjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * MindrianOS Plugin -- portable npm CLI resolution (debug session
+ * mcp-servers-cache-missing-node-modules, escalated mandate 2026-05-21).
+ *
+ * THE PROBLEM (code review of the prior Option D fix, commit f6cafe74):
+ * The self-heal and the SessionStart reconcile hook both ran
+ * `spawnSync('npm', ['install', ...])`. That bare invocation is NOT
+ * cross-platform:
+ *   - WINDOWS: `npm` is `npm.cmd` (a batch file). spawnSync('npm') with no
+ *     shell:true and no .cmd suffix returns ENOENT -- the heal silently does
+ *     nothing. On Windows the node_modules gap then NEVER heals.
+ *   - MAC: even with the .cmd issue aside, spawnSync('npm') depends on `npm`
+ *     being on the child process PATH. A GUI-launched (Dock/Finder) Claude
+ *     Code gives child processes a minimal PATH that frequently excludes the
+ *     nvm / Homebrew bin directory where `npm` lives -- same ENOENT, different
+ *     cause. `shell:true` does NOT fix this (it does not add the missing dir
+ *     to PATH).
+ *
+ * THE FIX (this module): resolve npm to an ABSOLUTE path, independent of PATH
+ * and independent of the platform file extension.
+ *
+ * The key insight: npm ships in the SAME distribution as the `node` binary
+ * already executing this code. `process.execPath` is the absolute path to
+ * that node binary. npm's real entry point is a plain JavaScript file --
+ * `npm-cli.js` -- which lives at a fixed location relative to the node binary:
+ *   - POSIX  (Linux, Mac): <nodeBinDir>/../lib/node_modules/npm/bin/npm-cli.js
+ *   - WINDOWS:              <nodeBinDir>/node_modules/npm/bin/npm-cli.js
+ * Running `node <absolute npm-cli.js> install ...` invokes npm directly with
+ * the SAME node binary, sidestepping PATH, the .cmd extension, and shell:true
+ * entirely. This is correct by construction on Windows, Mac, and Linux.
+ *
+ * Fallback: if npm-cli.js cannot be located off process.execPath (an unusual
+ * layout -- a system-package node, a relocated install), the resolver returns
+ * a PATH-based spawn descriptor that DOES carry the Windows .cmd handling
+ * (shell:true on win32) so the backstop is still better than the bare
+ * pre-fix invocation.
+ *
+ * Canon Part 8: zero network surface. Pure node built-ins. This module only
+ * computes a spawn descriptor; the caller runs `npm install`.
+ *
+ * HARD RULE: no em-dashes anywhere in this file (hyphens only).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Candidate absolute locations of npm's JavaScript entry point (npm-cli.js),
+ * derived from the directory of the currently-running node binary.
+ *
+ * Node distributions place npm consistently:
+ *   - POSIX tarball / nvm / Homebrew / Volta:
+ *       bin/node  +  lib/node_modules/npm/bin/npm-cli.js
+ *   - Windows zip / installer:
+ *       node.exe  +  node_modules/npm/bin/npm-cli.js   (same dir as node.exe)
+ *
+ * Both layouts are probed on every platform (a defensive superset) so a
+ * non-standard packaging still resolves if npm is present anywhere npm
+ * normally ships.
+ *
+ * @param {string} [execPath] - override for process.execPath (tests)
+ * @returns {string[]} absolute candidate paths, most-likely first
+ */
+function npmCliCandidates(execPath) {
+  const nodeBin = path.dirname(execPath || process.execPath);
+  return [
+    // Windows-style: npm sits beside node.exe.
+    path.join(nodeBin, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    // POSIX-style: npm sits one level up under lib/.
+    path.join(nodeBin, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    // Some Windows installs nest under a node_modules/npm with a lib prefix.
+    path.join(nodeBin, '..', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+}
+
+/**
+ * Resolve a portable, absolute spawn descriptor for `npm install`.
+ *
+ * Preferred result (strategy 'node-npm-cli'):
+ *   { command: process.execPath, baseArgs: [<abs npm-cli.js>], shell: false }
+ * Run npm by feeding its JS entry point to the current node binary. No PATH
+ * dependency, no .cmd extension, no shell. Correct on Windows, Mac, Linux.
+ *
+ * Fallback result (strategy 'path-npm'):
+ *   { command: 'npm', baseArgs: [], shell: true on win32 else false }
+ * Used only when npm-cli.js is not found off process.execPath. shell:true is
+ * set on Windows so the OS resolves `npm` -> `npm.cmd` (still better than the
+ * pre-fix bare spawn, though it remains PATH-dependent).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.execPath] - override process.execPath (tests)
+ * @returns {{command:string, baseArgs:string[], shell:boolean, strategy:string, npmCli:(string|null)}}
+ */
+function resolveNpmCli(opts) {
+  opts = opts || {};
+  const candidates = npmCliCandidates(opts.execPath);
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        return {
+          command: opts.execPath || process.execPath,
+          baseArgs: [candidate],
+          shell: false,
+          strategy: 'node-npm-cli',
+          npmCli: candidate,
+        };
+      }
+    } catch (_) {
+      // stat failure on a candidate -- try the next one.
+    }
+  }
+  // Fallback: npm-cli.js not locatable. PATH-based spawn, with Windows .cmd
+  // handling via shell:true. Still an improvement over the bare pre-fix call.
+  return {
+    command: 'npm',
+    baseArgs: [],
+    shell: IS_WINDOWS,
+    strategy: 'path-npm',
+    npmCli: null,
+  };
+}
+
+/**
+ * Build the full argv for `npm install` (production-safe, quiet, no scripts
+ * surprises) given a resolved descriptor from resolveNpmCli().
+ *
+ * @param {{baseArgs:string[]}} descriptor
+ * @param {string[]} [installArgs] - npm args after `install`; defaults to the
+ *                                   quiet production set used by the heal path.
+ * @returns {string[]} argv to pass as the second arg of spawnSync(command, argv)
+ */
+function buildInstallArgs(descriptor, installArgs) {
+  const tail = Array.isArray(installArgs) && installArgs.length
+    ? installArgs
+    : ['--no-audit', '--no-fund', '--silent'];
+  return descriptor.baseArgs.concat(['install'], tail);
+}
+
+module.exports = {
+  resolveNpmCli,
+  buildInstallArgs,
+  npmCliCandidates,
+  IS_WINDOWS,
+};

package/lib/core/npm-cli-resolve.test.cjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Regression tests for lib/core/npm-cli-resolve.cjs -- portable npm CLI
+ * resolution (debug session mcp-servers-cache-missing-node-modules, escalated
+ * mandate 2026-05-21).
+ *
+ * The prior Option D fix (commit f6cafe74) ran a bare `spawnSync('npm', ...)`
+ * that was DEAD on Windows (npm is npm.cmd) and FRAGILE on Mac (PATH gap for
+ * GUI-launched Claude Code). These tests lock the cross-platform contract:
+ *
+ *   Test 1: resolveNpmCli on the test host returns the 'node-npm-cli' strategy
+ *           and the resolved npm-cli.js actually exists.
+ *   Test 2: the resolved command equals process.execPath (the current node
+ *           binary) -- NOT the literal string 'npm'. This is what makes it
+ *           PATH-independent.
+ *   Test 3: WINDOWS layout -- npmCliCandidates for a win32-style execPath puts
+ *           `<nodeBinDir>/node_modules/npm/bin/npm-cli.js` first (where the
+ *           Windows node installer ships npm). No `.cmd` anywhere in the argv.
+ *   Test 4: buildInstallArgs produces `[<npm-cli.js>] install --no-audit
+ *           --no-fund --silent` for the node-npm-cli strategy.
+ *   Test 5: the fallback descriptor (path-npm) sets shell:true ONLY on win32,
+ *           so even the fallback carries Windows .cmd handling.
+ *   Test 6: no em-dashes in npm-cli-resolve.cjs (HARD RULE).
+ *   Test 7: the argv never contains the bare token 'npm' as command on the
+ *           node-npm-cli strategy -- proves PATH is not relied upon.
+ *
+ * HARD RULE: no em-dashes.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MODULE_PATH = path.join(REPO_ROOT, 'lib', 'core', 'npm-cli-resolve.cjs');
+const { resolveNpmCli, buildInstallArgs, npmCliCandidates } = require(MODULE_PATH);
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  passed += 1;
+  process.stdout.write('  ok ' + name + '\n');
+}
+function fail(name, err) {
+  failed += 1;
+  process.stdout.write('  FAIL ' + name + '\n');
+  process.stdout.write('    ' + (err && err.message ? err.message : String(err)) + '\n');
+}
+function test(name, fn) {
+  try { fn(); ok(name); } catch (err) { fail(name, err); }
+}
+
+// Test 1 -- node-npm-cli strategy on the test host, npm-cli.js exists.
+test('resolveNpmCli returns node-npm-cli strategy with a real npm-cli.js', () => {
+  const r = resolveNpmCli();
+  assert.equal(r.strategy, 'node-npm-cli', 'expected node-npm-cli strategy on a normal node install');
+  assert.ok(r.npmCli, 'npmCli path should be set');
+  assert.ok(fs.existsSync(r.npmCli), 'resolved npm-cli.js must exist on disk: ' + r.npmCli);
+});
+
+// Test 2 -- command is the node binary, not the literal 'npm'.
+test('resolveNpmCli command is process.execPath (PATH-independent)', () => {
+  const r = resolveNpmCli();
+  assert.equal(r.command, process.execPath, 'command must be the current node binary');
+  assert.notEqual(r.command, 'npm', 'command must NOT be the bare PATH-dependent string npm');
+  assert.equal(r.shell, false, 'node-npm-cli strategy needs no shell');
+});
+
+// Test 3 -- Windows layout: npm-cli.js beside node.exe is the first candidate.
+test('npmCliCandidates puts the Windows-layout path first', () => {
+  // path.win32 mirrors what require('path') resolves to on a real Windows host.
+  const winExec = 'C:\\Program Files\\nodejs\\node.exe';
+  const cands = npmCliCandidates(winExec);
+  assert.ok(Array.isArray(cands) && cands.length >= 3, 'expected >= 3 candidates');
+  // The first candidate is the <nodeBinDir>/node_modules/npm/bin/npm-cli.js
+  // layout -- exactly where the Windows node installer ships npm.
+  assert.ok(
+    cands[0].indexOf('node_modules') !== -1 && cands[0].indexOf('npm-cli.js') !== -1,
+    'first candidate must target node_modules/npm/bin/npm-cli.js'
+  );
+  // No candidate is a .cmd file -- we always run the JS entry point directly.
+  for (const c of cands) {
+    assert.ok(c.indexOf('.cmd') === -1, 'no candidate may be a .cmd batch file: ' + c);
+  }
+});
+
+// Test 4 -- buildInstallArgs argv shape for the node-npm-cli strategy.
+test('buildInstallArgs produces [npm-cli.js] install ...quiet-flags', () => {
+  const r = resolveNpmCli();
+  const argv = buildInstallArgs(r);
+  assert.equal(argv[0], r.npmCli, 'first arg must be the npm-cli.js path');
+  assert.equal(argv[1], 'install', 'second arg must be install');
+  assert.deepEqual(
+    argv.slice(2),
+    ['--no-audit', '--no-fund', '--silent'],
+    'default install args must be the quiet production set'
+  );
+  // A custom install-args override is honored.
+  const custom = buildInstallArgs(r, ['--omit=dev']);
+  assert.deepEqual(custom.slice(1), ['install', '--omit=dev']);
+});
+
+// Test 5 -- fallback descriptor: shell:true only on Windows.
+test('path-npm fallback sets shell:true only on win32', () => {
+  // Force the fallback by pointing execPath at a freshly-created EMPTY temp
+  // directory tree deep enough that none of the candidate paths (including the
+  // `../lib/node_modules/...` POSIX-layout candidate) can escape onto a real
+  // system npm. The temp dir is isolated and known to contain no node_modules.
+  const os = require('node:os');
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mos-npm-resolve-test-'));
+  try {
+    // <tmpRoot>/x/y/z/bin/node -- candidates resolve under <tmpRoot>/x/y/z,
+    // which is empty, so resolveNpmCli must fall through to path-npm.
+    const fakeBin = path.join(tmpRoot, 'x', 'y', 'z', 'bin');
+    fs.mkdirSync(fakeBin, { recursive: true });
+    const r = resolveNpmCli({ execPath: path.join(fakeBin, 'node') });
+    assert.equal(r.strategy, 'path-npm', 'expected the path-npm fallback in an isolated empty tree');
+    assert.equal(r.command, 'npm', 'fallback command is the bare npm');
+    assert.equal(r.npmCli, null, 'fallback has no npmCli path');
+    assert.equal(
+      r.shell,
+      process.platform === 'win32',
+      'fallback shell must be true on Windows (npm.cmd handling) and false elsewhere'
+    );
+  } finally {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+});
+
+// Test 6 -- HARD RULE: no em-dashes. The em-dash is referenced via its Unicode
+// code point (U+2014) so this test file itself stays em-dash-clean.
+test('npm-cli-resolve.cjs has no em-dashes', () => {
+  const src = fs.readFileSync(MODULE_PATH, 'utf8');
+  const EM_DASH = String.fromCharCode(0x2014);
+  assert.ok(src.indexOf(EM_DASH) === -1, 'em-dash found in npm-cli-resolve.cjs');
+});
+
+// Test 7 -- the node-npm-cli argv never relies on a bare 'npm' token.
+test('node-npm-cli argv does not depend on PATH resolution of npm', () => {
+  const r = resolveNpmCli();
+  const fullArgv = [r.command].concat(buildInstallArgs(r));
+  assert.notEqual(fullArgv[0], 'npm', 'command position must not be the bare npm token');
+  // The npm-cli.js path is absolute -- not resolved against PATH or cwd.
+  assert.ok(path.isAbsolute(r.npmCli), 'npm-cli.js path must be absolute');
+});
+
+process.stdout.write('\nnpm-cli-resolve: ' + passed + ' passed, ' + failed + ' failed\n');
+process.exit(failed === 0 ? 0 : 1);

package/lib/core/npm-install-lock.cjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * MindrianOS Plugin -- one-shot npm-install lock (Option D, hybrid self-heal).
+ *
+ * Purpose: when a fresh plugin cache lands with NO node_modules, BOTH bundled
+ * MCP servers (mindrian-brain + mindrian-os) can spawn at the same instant and
+ * each independently discover MODULE_NOT_FOUND. If both ran `npm install`
+ * concurrently in the same directory they would corrupt node_modules. This lock
+ * guarantees that exactly ONE process runs the install while the other WAITS
+ * for it to finish, then proceeds.
+ *
+ * This is deliberately NOT lib/core/write-lock.cjs. write-lock is room-scoped,
+ * SQLite-scoped, has a 5s stale threshold, and THROWS on contention. The
+ * npm-install path needs the opposite contract: a longer stale window (a cold
+ * `npm install` can take 30s+) and a BLOCKING wait, not a throw -- the loser of
+ * the race must sit still until node_modules is populated.
+ *
+ * CORRECTNESS FIXES (remote code review, 2026-05-21 -- folded into beta.23):
+ *   - bug_004: lock creation is now ATOMIC via fs.linkSync (write a fully
+ *     populated temp file, then atomically link it into place). The pre-fix
+ *     openSync('wx') created a zero-byte file that a separate writeSync later
+ *     populated -- a racing peer could read the empty file mid-write, treat it
+ *     as corrupt, unlink the winner's live lock, and run a second concurrent
+ *     install. readLock + waitForUnlock additionally distinguish a transient
+ *     empty mid-write file from genuinely corrupt JSON.
+ *   - bug_001: STALE_THRESHOLD_MS is raised strictly above the 120s install
+ *     timeout, and the staleness checks use AND not OR -- a lock is reclaimed
+ *     only when it is BOTH old AND its owning pid is dead. A healthy install
+ *     legitimately running 90-120s is no longer declared abandoned.
+ *
+ * Canon Part 8: zero network surface in this file. Pure node built-ins. The
+ * `npm install` itself is run by the caller (mcp-dep-heal.cjs), not here.
+ *
+ * HARD RULE: no em-dashes anywhere in this file (hyphens only).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCK_FILENAME = '.mindrian-npm-install.lock';
+// A cold `npm install` of the plugin deps measured ~3s on a warm npm cache and
+// can exceed 30s on a cold cache / slow disk. runGuardedInstall's spawnSync
+// gives the install a 120000 ms (120s) timeout, so STALE_THRESHOLD_MS MUST sit
+// strictly ABOVE 120s -- otherwise a healthy install still legitimately running
+// at the 90-120s mark would be declared abandoned and a peer would start a
+// SECOND concurrent install (bug_001). 180s gives 60s of headroom over the
+// install timeout. Belt-and-suspenders: the staleness checks below also require
+// pidAlive to be false (AND, not OR), so an old-but-live lock is never reclaimed.
+const STALE_THRESHOLD_MS = 180 * 1000;
+// How long the loser of the race waits for the winner before giving up and
+// trying the install itself. Strictly above STALE so a genuine winner whose
+// lock has just gone stale still gets reclaimed-and-retried, not double-run.
+const WAIT_TIMEOUT_MS = 200 * 1000;
+const POLL_INTERVAL_MS = 200;
+// A mid-write lock file (created by openSync('wx') but not yet written by the
+// follow-up writeSync) is briefly empty. readLock distinguishes that transient
+// state from a genuinely corrupt file by polling a few short intervals before
+// declaring corruption (bug_004 defence-in-depth alongside the atomic linkSync
+// create path).
+const EMPTY_FILE_RETRY_ATTEMPTS = 5;
+const EMPTY_FILE_RETRY_INTERVAL_MS = 20;
+
+function lockPath(dir) {
+  return path.join(dir, LOCK_FILENAME);
+}
+
+/** Portable synchronous short sleep (no extra dependency, works everywhere). */
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch (_) {
+    // SharedArrayBuffer unavailable in some sandboxes -- busy-wait instead.
+    const until = Date.now() + ms;
+    while (Date.now() < until) { /* spin */ }
+  }
+}
+
+/**
+ * Read and parse a lock file.
+ *
+ * Returns one of three things so callers can distinguish a transient empty
+ * mid-write file from a genuinely corrupt one (bug_004):
+ *   - the parsed lock object        -> a valid, fully-written lock
+ *   - the string 'EMPTY'            -> the file exists but is empty / whitespace
+ *                                      only after a few short retries; this is
+ *                                      a mid-write race window OR a 0-byte
+ *                                      leftover. Caller should retry, not
+ *                                      assume the lock is dead.
+ *   - null                          -> the file is missing, unreadable, or
+ *                                      contains genuinely non-empty invalid
+ *                                      JSON (truly corrupt -- safe to clear).
+ *
+ * The atomic linkSync create path in acquireInstallLock means a winner's lock
+ * is never observed mid-write in practice; this empty/corrupt distinction is
+ * defence-in-depth for any lock that arrived via a non-atomic path.
+ *
+ * @param {string} p - lock file path
+ * @returns {object|'EMPTY'|null}
+ */
+function readLock(p) {
+  for (let attempt = 0; attempt < EMPTY_FILE_RETRY_ATTEMPTS; attempt++) {
+    let raw;
+    try {
+      raw = fs.readFileSync(p, 'utf8');
+    } catch (_) {
+      return null; // missing or unreadable
+    }
+    if (raw.trim() === '') {
+      // Empty / whitespace-only: possibly a mid-write window. Retry a few
+      // short intervals before giving up.
+      if (attempt < EMPTY_FILE_RETRY_ATTEMPTS - 1) {
+        sleepSync(EMPTY_FILE_RETRY_INTERVAL_MS);
+        continue;
+      }
+      return 'EMPTY';
+    }
+    try {
+      return JSON.parse(raw);
+    } catch (_) {
+      // Non-empty but not valid JSON -- genuinely corrupt.
+      return null;
+    }
+  }
+  return 'EMPTY';
+}
+
+function pidAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM means the process exists but is owned by another user -- still alive.
+    return e && e.code === 'EPERM';
+  }
+}
+
+/**
+ * Whether a lock described by `data` is reclaimable as abandoned.
+ *
+ * bug_001 fix: this uses AND, not OR. A lock is reclaimed ONLY when it is BOTH
+ * stale (older than STALE_THRESHOLD_MS) AND its owning pid is genuinely dead.
+ * The pre-fix OR form let a peer unlink a LIVE lock the instant `age` crossed
+ * the (too-short) threshold, even though the install was still running -- two
+ * concurrent `npm install`s, corrupted node_modules. With AND, a long-but-live
+ * install keeps its lock no matter how old it gets; a dead-owner lock that has
+ * not yet aged out keeps its lock too (the owner may have only just died and a
+ * sibling could still be mid-handoff). Reclaim needs both signals.
+ *
+ * @param {object} data - parsed lock contents (must be a valid lock object)
+ * @returns {boolean}
+ */
+function isReclaimable(data) {
+  const age = Date.now() - (data.timestamp || 0);
+  return age > STALE_THRESHOLD_MS && !pidAlive(data.pid);
+}
+
+/**
+ * Try to acquire the install lock for `dir`.
+ *
+ * bug_004 fix: lock creation is ATOMIC. The payload is written to a uniquely
+ * named temp file FIRST (fully populated, then closed), and only then is
+ * fs.linkSync(tmp, p) used to publish it at the canonical lock path. linkSync
+ * is atomic and fails with EEXIST if the target already exists, so a winner's
+ * lock is ALWAYS observed fully-written -- there is no zero-byte mid-write
+ * window for a racing peer to misread as corrupt. The pre-fix openSync('wx')
+ * created a 0-byte file that the follow-up writeSync populated in a SEPARATE
+ * syscall; a peer racing in between read an empty file, treated it as corrupt,
+ * unlinked the winner's live lock, and both processes ran `npm install`.
+ *
+ * @param {string} dir - directory the install will run in (CLAUDE_PLUGIN_ROOT)
+ * @returns {boolean} true if THIS process now holds the lock (it should run the
+ *                    install), false if another live process holds it (this
+ *                    process should call waitForUnlock instead).
+ */
+function acquireInstallLock(dir) {
+  const p = lockPath(dir);
+  const tmp = p + '.' + process.pid + '.tmp';
+  const payload = JSON.stringify({ pid: process.pid, timestamp: Date.now() });
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    // Write the payload to a private temp file, fully, before publishing it.
+    try {
+      fs.writeFileSync(tmp, payload);
+    } catch (e) {
+      // Cannot even write a temp file (read-only dir, etc). Caller falls back
+      // to running the install unguarded -- better than not healing.
+      return true;
+    }
+
+    try {
+      // Atomic publish: link is atomic and fails EEXIST if `p` already exists.
+      fs.linkSync(tmp, p);
+      // We won. The temp file has served its purpose; remove it.
+      try { fs.unlinkSync(tmp); } catch (_) {}
+      return true;
+    } catch (e) {
+      // Always drop our temp file before deciding what to do next.
+      try { fs.unlinkSync(tmp); } catch (_) {}
+      if (e.code !== 'EEXIST') {
+        // linkSync failed for a non-contention reason (filesystem without
+        // hardlink support, cross-device, permissions). Fall back to running
+        // the install unguarded -- better than not healing.
+        return true;
+      }
+      // The lock path is already held. Inspect it.
+      const data = readLock(p);
+      if (data === 'EMPTY') {
+        // Transient mid-write window (or a 0-byte leftover from a non-atomic
+        // path). Do NOT unlink -- a peer may be about to populate it. Wait a
+        // short interval and retry the acquire.
+        sleepSync(EMPTY_FILE_RETRY_INTERVAL_MS * EMPTY_FILE_RETRY_ATTEMPTS);
+        continue;
+      }
+      if (!data) {
+        // Genuinely corrupt (non-empty invalid JSON) or unreadable -- clear
+        // and retry.
+        try { fs.unlinkSync(p); } catch (_) {}
+        continue;
+      }
+      if (isReclaimable(data)) {
+        // Abandoned: BOTH stale AND its owner is dead. Reclaim it.
+        try { fs.unlinkSync(p); } catch (_) {}
+        continue;
+      }
+      // A live (or not-yet-reclaimable) process holds the lock -- this process
+      // is the loser and must wait for the winner.
+      return false;
+    }
+  }
+  // Pathological churn -- give up the guard and let the caller install.
+  return true;
+}
+
+/** Release the lock. Silent if it does not exist or is not ours. */
+function releaseInstallLock(dir) {
+  const p = lockPath(dir);
+  try {
+    const data = readLock(p);
+    // Only skip the unlink when we can positively confirm the lock belongs to
+    // a DIFFERENT live process. 'EMPTY' (transient) or null (corrupt) -- there
+    // is no owner pid to compare, so fall through and clear it.
+    if (data && data !== 'EMPTY' && data.pid && data.pid !== process.pid) {
+      return; // not ours
+    }
+    fs.unlinkSync(p);
+  } catch (_) {
+    // ENOENT or other -- silent.
+  }
+}
+
+/**
+ * Block until the lock for `dir` is released (winner finished its install),
+ * the lock goes stale, or WAIT_TIMEOUT_MS elapses.
+ *
+ * Synchronous by design: this runs at MCP server startup, before the server
+ * connects its transport, so a blocking spin is acceptable and correct.
+ *
+ * @param {string} dir
+ * @returns {boolean} true if the lock cleared (install presumably done),
+ *                    false on timeout.
+ */
+function waitForUnlock(dir) {
+  const p = lockPath(dir);
+  const deadline = Date.now() + WAIT_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (!fs.existsSync(p)) return true;
+    const data = readLock(p);
+    if (data === 'EMPTY') {
+      // bug_004 symmetric defect fix: an empty file is a transient mid-write
+      // window, NOT a cleared lock. The pre-fix `if (!data) return true` form
+      // declared the winner done the instant it saw an empty file -- the loser
+      // then ran its OWN install concurrently. Keep polling instead.
+      sleepSync(POLL_INTERVAL_MS);
+      continue;
+    }
+    if (!data) return true; // genuinely corrupt -- treat as cleared
+    // bug_001 fix: AND, not OR. Stop waiting only when the lock is BOTH stale
+    // AND its owner is dead. A long-but-live install keeps us waiting; we never
+    // race ahead with our own install while a healthy winner is still running.
+    if (isReclaimable(data)) return true;
+    // Poll a short slice via the portable synchronous sleep.
+    sleepSync(POLL_INTERVAL_MS);
+  }
+  return false;
+}
+
+module.exports = {
+  acquireInstallLock,
+  releaseInstallLock,
+  waitForUnlock,
+  readLock,
+  isReclaimable,
+  pidAlive,
+  LOCK_FILENAME,
+  STALE_THRESHOLD_MS,
+  WAIT_TIMEOUT_MS,
+};