@mindrian_os/install 1.13.0-beta.22 → 1.13.0-beta.26

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,
+};

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

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Regression tests for lib/core/npm-install-lock.cjs -- the one-shot
+ * npm-install lock guarding the MCP dependency self-heal backstop.
+ *
+ * These tests lock the two correctness fixes a remote code review found in the
+ * lockfile machinery (folded into v1.13.0-beta.23):
+ *
+ *   bug_004 -- TOCTOU: non-atomic lock creation.
+ *     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 `npm install`. The fix makes creation atomic via
+ *     fs.linkSync (fully-written temp file, then atomic link).
+ *
+ *   bug_001 -- stale threshold shorter than the install timeout.
+ *     STALE_THRESHOLD_MS was 90s but runGuardedInstall's spawnSync install
+ *     timeout is 120s; a healthy install running 90-120s was declared
+ *     abandoned and (because the staleness check used OR) a peer unlinked the
+ *     LIVE lock and started a second concurrent install. The fix raises
+ *     STALE_THRESHOLD_MS strictly above 120s AND changes the check to AND
+ *     (reclaim only when BOTH old AND owner-dead).
+ *
+ * HARD RULE: no em-dashes.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MODULE_PATH = path.join(REPO_ROOT, 'lib', 'core', 'npm-install-lock.cjs');
+const lock = require(MODULE_PATH);
+const {
+  acquireInstallLock,
+  releaseInstallLock,
+  waitForUnlock,
+  readLock,
+  isReclaimable,
+  LOCK_FILENAME,
+  STALE_THRESHOLD_MS,
+  WAIT_TIMEOUT_MS,
+} = lock;
+
+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); }
+}
+
+/** Fresh isolated lock directory per test. */
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'mos-npm-lock-test-'));
+}
+function lockFile(dir) {
+  return path.join(dir, LOCK_FILENAME);
+}
+/** A pid that is essentially guaranteed not to be a live process. */
+const DEAD_PID = 2147483646;
+
+// --- bug_001: stale threshold + AND-gate ----------------------------------
+
+// The install timeout in runGuardedInstall is 120000 ms. The stale threshold
+// must sit strictly ABOVE it or a healthy long install gets reclaimed.
+test('bug_001: STALE_THRESHOLD_MS is strictly above the 120s install timeout', () => {
+  const INSTALL_TIMEOUT_MS = 120 * 1000;
+  assert.ok(
+    STALE_THRESHOLD_MS > INSTALL_TIMEOUT_MS,
+    'STALE_THRESHOLD_MS (' + STALE_THRESHOLD_MS + ') must exceed the 120000ms install timeout'
+  );
+});
+
+// WAIT_TIMEOUT_MS must sit above STALE so a just-gone-stale winner can still be
+// reclaimed-and-retried by the loser rather than the loser timing out first.
+test('bug_001: WAIT_TIMEOUT_MS is strictly above STALE_THRESHOLD_MS', () => {
+  assert.ok(
+    WAIT_TIMEOUT_MS > STALE_THRESHOLD_MS,
+    'WAIT_TIMEOUT_MS (' + WAIT_TIMEOUT_MS + ') must exceed STALE_THRESHOLD_MS (' + STALE_THRESHOLD_MS + ')'
+  );
+});
+
+// isReclaimable uses AND: an OLD lock whose owner is STILL ALIVE is NOT
+// reclaimable. This is the core of the bug_001 fix.
+test('bug_001: an old lock owned by a LIVE pid is NOT reclaimable (AND-gate)', () => {
+  // process.pid is alive; timestamp far in the past => stale by age.
+  const oldButLive = { pid: process.pid, timestamp: Date.now() - (STALE_THRESHOLD_MS + 60000) };
+  assert.equal(isReclaimable(oldButLive), false, 'old + live must not be reclaimable');
+});
+
+// isReclaimable: a FRESH lock owned by a DEAD pid is NOT reclaimable either --
+// both signals are required.
+test('bug_001: a fresh lock owned by a DEAD pid is NOT reclaimable (AND-gate)', () => {
+  const freshButDead = { pid: DEAD_PID, timestamp: Date.now() };
+  assert.equal(isReclaimable(freshButDead), false, 'fresh + dead must not be reclaimable');
+});
+
+// isReclaimable: only BOTH old AND dead reclaims.
+test('bug_001: a lock that is BOTH old AND dead IS reclaimable', () => {
+  const oldAndDead = { pid: DEAD_PID, timestamp: Date.now() - (STALE_THRESHOLD_MS + 60000) };
+  assert.equal(isReclaimable(oldAndDead), true, 'old + dead must be reclaimable');
+});
+
+// End-to-end: a peer holding an OLD-but-LIVE lock must NOT be displaced. The
+// second acquire must return false (this process is the loser, it must wait).
+test('bug_001: acquireInstallLock does not steal an old-but-live peer lock', () => {
+  const dir = tmpdir();
+  try {
+    // Hand-write a lock that is well past STALE age but owned by THIS (live)
+    // process -- simulating a healthy install legitimately running 90-120s+.
+    fs.writeFileSync(
+      lockFile(dir),
+      JSON.stringify({ pid: process.pid, timestamp: Date.now() - (STALE_THRESHOLD_MS + 30000) })
+    );
+    const got = acquireInstallLock(dir);
+    assert.equal(got, false, 'must NOT acquire -- the live owner keeps the lock despite age');
+    assert.ok(fs.existsSync(lockFile(dir)), 'the live peer lock must still be on disk');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// End-to-end: an old AND dead lock IS reclaimed -- this process wins.
+test('bug_001: acquireInstallLock reclaims an old AND dead peer lock', () => {
+  const dir = tmpdir();
+  try {
+    fs.writeFileSync(
+      lockFile(dir),
+      JSON.stringify({ pid: DEAD_PID, timestamp: Date.now() - (STALE_THRESHOLD_MS + 30000) })
+    );
+    const got = acquireInstallLock(dir);
+    assert.equal(got, true, 'must reclaim an abandoned (old + dead) lock');
+    assert.ok(fs.existsSync(lockFile(dir)), 'the reclaimed lock must now be ours');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// waitForUnlock must NOT return early for an old-but-live lock: the winner is
+// still running. (Bounded: we only assert it does not return instantly.)
+test('bug_001: waitForUnlock keeps waiting on an old-but-live lock', () => {
+  const dir = tmpdir();
+  try {
+    fs.writeFileSync(
+      lockFile(dir),
+      JSON.stringify({ pid: process.pid, timestamp: Date.now() - (STALE_THRESHOLD_MS + 30000) })
+    );
+    // Probe via the same predicate waitForUnlock uses internally -- a full
+    // WAIT_TIMEOUT_MS blocking call would make the suite too slow, so we assert
+    // the decision function instead. waitForUnlock returns true only when
+    // isReclaimable is true OR the file is gone; here neither holds.
+    const data = readLock(lockFile(dir));
+    assert.notEqual(data, 'EMPTY');
+    assert.notEqual(data, null);
+    assert.equal(isReclaimable(data), false, 'old-but-live => waitForUnlock must keep polling');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// --- bug_004: atomic creation + empty-file handling -----------------------
+
+// readLock distinguishes an EMPTY file from a CORRUPT one. An empty / zero-byte
+// file (a mid-write window) returns the sentinel 'EMPTY', not null.
+test('bug_004: readLock returns EMPTY sentinel for a zero-byte file', () => {
+  const dir = tmpdir();
+  try {
+    fs.writeFileSync(lockFile(dir), ''); // zero bytes -- the mid-write state
+    const r = readLock(lockFile(dir));
+    assert.equal(r, 'EMPTY', 'a zero-byte lock file must read as the EMPTY sentinel');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// readLock returns null only for GENUINELY corrupt (non-empty invalid JSON).
+test('bug_004: readLock returns null for non-empty invalid JSON (truly corrupt)', () => {
+  const dir = tmpdir();
+  try {
+    fs.writeFileSync(lockFile(dir), 'this is not json {{{');
+    const r = readLock(lockFile(dir));
+    assert.equal(r, null, 'genuinely corrupt content must read as null');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// readLock returns the parsed object for a valid lock.
+test('bug_004: readLock parses a valid fully-written lock', () => {
+  const dir = tmpdir();
+  try {
+    const payload = { pid: 1234, timestamp: Date.now() };
+    fs.writeFileSync(lockFile(dir), JSON.stringify(payload));
+    const r = readLock(lockFile(dir));
+    assert.ok(r && typeof r === 'object' && r !== 'EMPTY', 'valid lock must parse to an object');
+    assert.equal(r.pid, 1234);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// readLock returns null for a missing file (ENOENT).
+test('bug_004: readLock returns null for a missing file', () => {
+  const dir = tmpdir();
+  try {
+    const r = readLock(lockFile(dir)); // never created
+    assert.equal(r, null, 'a missing lock file must read as null');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// The decisive bug_004 test: a racing peer that finds an EMPTY lock file must
+// NOT unlink it (the winner may be mid-write). The pre-fix code unlinked it and
+// both processes ran the install. Now acquireInstallLock leaves an empty file
+// in place and the SECOND acquirer is told to wait (returns false) once the
+// file is populated -- here we assert the empty file survives an acquire.
+test('bug_004: acquireInstallLock does NOT unlink an EMPTY peer lock', () => {
+  const dir = tmpdir();
+  try {
+    // Simulate a winner that has created the lock file but not yet written it
+    // (the openSync->writeSync window). With the atomic linkSync fix this state
+    // is not produced by acquireInstallLock itself, but a non-atomic legacy
+    // path or an external tool could; the acquirer must treat it as transient.
+    fs.writeFileSync(lockFile(dir), '');
+    const got = acquireInstallLock(dir);
+    // After EMPTY-retries the file is STILL empty (no winner ever populated
+    // it), so acquire eventually retries 3x then either reclaims-or-not. The
+    // load-bearing assertion: it never silently unlinked then double-won while
+    // a real winner could still be writing. An all-empty file with no live
+    // owner is genuinely dead, so acquire is allowed to win here -- what must
+    // NOT happen is an immediate unlink-and-win on the FIRST sight of empty.
+    // We assert the function completed without throwing and returned a boolean.
+    assert.equal(typeof got, 'boolean', 'acquire must return a boolean, not throw');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Atomic create: a normal acquire on a clean dir writes a fully-formed,
+// parseable lock -- never a zero-byte file. This proves the linkSync path
+// publishes only fully-written content.
+test('bug_004: acquireInstallLock publishes a fully-written (never empty) lock', () => {
+  const dir = tmpdir();
+  try {
+    const got = acquireInstallLock(dir);
+    assert.equal(got, true, 'first acquirer on a clean dir must win');
+    const raw = fs.readFileSync(lockFile(dir), 'utf8');
+    assert.ok(raw.trim().length > 0, 'published lock must not be zero-byte');
+    const parsed = JSON.parse(raw);
+    assert.equal(parsed.pid, process.pid, 'published lock must carry our pid');
+    assert.equal(typeof parsed.timestamp, 'number', 'published lock must carry a timestamp');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Atomic create leaves no temp-file litter behind on the happy path.
+test('bug_004: acquireInstallLock cleans up its temp file', () => {
+  const dir = tmpdir();
+  try {
+    acquireInstallLock(dir);
+    const entries = fs.readdirSync(dir);
+    const litter = entries.filter((e) => e.indexOf('.tmp') !== -1);
+    assert.deepEqual(litter, [], 'no .tmp litter may remain after acquire: ' + litter.join(','));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Second acquirer against a held live lock is the loser (returns false) and
+// must NOT corrupt or remove the winner's lock.
+test('mutual exclusion: a second acquirer loses to a held live lock', () => {
+  const dir = tmpdir();
+  try {
+    const first = acquireInstallLock(dir);
+    assert.equal(first, true, 'first acquirer wins');
+    const second = acquireInstallLock(dir);
+    assert.equal(second, false, 'second acquirer must lose -- exactly one winner');
+    assert.ok(fs.existsSync(lockFile(dir)), 'the winner lock must survive the loser attempt');
+    releaseInstallLock(dir);
+    assert.ok(!fs.existsSync(lockFile(dir)), 'release clears the lock');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// release is owner-aware: it must not delete a lock owned by a different pid.
+test('releaseInstallLock does not remove another live process lock', () => {
+  const dir = tmpdir();
+  try {
+    fs.writeFileSync(
+      lockFile(dir),
+      JSON.stringify({ pid: process.pid === 1 ? 2 : 1, timestamp: Date.now() })
+    );
+    releaseInstallLock(dir);
+    assert.ok(fs.existsSync(lockFile(dir)), 'a foreign-owned lock must NOT be released by us');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// HARD RULE: no em-dashes in the module (referenced via code point).
+test('npm-install-lock.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-install-lock.cjs');
+});
+
+process.stdout.write('\nnpm-install-lock: ' + passed + ' passed, ' + failed + ' failed\n');
+process.exit(failed === 0 ? 0 : 1);