@lifeaitools/rdc-skills 0.25.5 → 0.25.10

package/hooks/lib/box-lock.js

@@ -0,0 +1,207 @@
+'use strict';
+/**
+ * Box-wide single-flight lock — ONE home for the rule.
+ *
+ * The global rdc-skills package and rdc-skills-mcp are BOX-WIDE (one per machine),
+ * but the SessionStart hook runs per session and per worktree. Without
+ * coordination, N sessions each conclude "unhealthy" and each run
+ * `npm install -g` against the same directory — and on Windows, against a
+ * directory a live process is sitting in.
+ *
+ * This lives in its own module because the verification probe MUST exercise the
+ * real implementation. It previously kept a private copy of these functions, and
+ * that copy silently drifted to the old algorithm — so the probe reported PASS for
+ * code that was not shipping, and later FAIL for code that was already fixed. A
+ * test that duplicates its subject tests nothing.
+ */
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const LOCK_PATH = path.join(os.tmpdir(), 'rdc-skills-environment-repair.lock');
+const LOCK_STALE_MS = 5 * 60 * 1000;
+
+let lockHeld = false;
+
+// How long to let a fresh acquisition settle before trusting it. Long enough to
+// cover the remove-then-create gap of a concurrent reclaim, short enough to be
+// invisible on a SessionStart path that already budgets minutes for repair.
+const SETTLE_MS = 60;
+
+/** Synchronous sleep — this module runs in a hook with no event loop to yield to. */
+function settle(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Is `pid` a live process?
+ *
+ * PID 0 is NOT a probe: process.kill(0, 0) signals the CURRENT PROCESS GROUP and
+ * succeeds, so a truncated lock written as {"pid":0} would read as alive forever.
+ * Reject non-positive/non-integer pids before asking the OS.
+ */
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return Boolean(err && err.code === 'EPERM'); // exists, not ours to signal
+  }
+}
+
+/**
+ * A lock we cannot reason about is stale.
+ *
+ * A parseable-but-corrupt body ({"pid":0,"ts":"garbage"}) threw nothing, so
+ * `NaN > LOCK_STALE_MS` was false and the lock was judged live FOREVER — wedging
+ * every session onto the follower path until the tmpdir file was deleted by hand.
+ */
+function lockIsStale(held) {
+  const pid = Number(held && held.pid);
+  const age = Date.now() - Date.parse(held && held.ts);
+  if (!Number.isInteger(pid) || pid <= 0 || !Number.isFinite(age)) return true;
+  return !processAlive(pid) || age > LOCK_STALE_MS;
+}
+
+/**
+ * Become the box's updater, or report that someone else already is.
+ *
+ * Stale locks are reclaimed by RENAME, never unlink-then-create. The naive
+ * sequence (read → judge stale → unlink → open 'wx') is a TOCTOU: two sessions can
+ * both read the same stale lock, both judge it stale, and the second's unlink can
+ * delete the FIRST's freshly created lock — leaving both convinced they own the
+ * box-wide update, which is the exact race this module exists to prevent.
+ * rename() is atomic, so only one racer can win, and only the winner proceeds.
+ */
+function acquireBoxLock() {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const body = JSON.stringify({ pid: process.pid, ts: new Date().toISOString() });
+      const fd = fs.openSync(LOCK_PATH, 'wx');
+      fs.writeSync(fd, body);
+      fs.closeSync(fd);
+
+      // POST-ACQUIRE VERIFICATION — the part that actually makes this single-flight.
+      //
+      // O_EXCL guarantees only one process can CREATE the file, but not one OWNER
+      // across a delete-and-recreate: reclaiming a stale lock necessarily leaves the
+      // path empty for an instant, and a racer arriving in that gap creates it
+      // legitimately. Both then believe they lead. No amount of care in the reclaim
+      // path closes that window — it is inherent to remove-then-create.
+      //
+      // So settle briefly and re-read: whoever's bytes are still there owns the box,
+      // and everyone else stands down. This converges on exactly one leader instead
+      // of trying to make the gap not exist. Without it the race was intermittent —
+      // 0/12, 1/12, 2/12 double-leader rounds across runs, which is the worst kind
+      // of bug to ship: it passes CI and fails on a busy machine.
+      settle(SETTLE_MS);
+      // Distinguish "someone else took it" from "the read failed". Standing down on
+      // a transient read error can elect ZERO leaders — nobody repairs the box while
+      // every session waits and then hard-blocks. Only a genuine byte MISMATCH means
+      // another session leads.
+      let observed = null;
+      let readOk = false;
+      for (let r = 0; r < 2 && !readOk; r++) {
+        try { observed = fs.readFileSync(LOCK_PATH, 'utf8'); readOk = true; } catch { settle(20); }
+      }
+      if (!readOk) continue;              // could not verify — retry the create
+      if (observed !== body) return false; // someone reclaimed it; they lead
+
+      lockHeld = true;
+      return true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') return false;
+
+      let heldRaw = null;
+      let held = null;
+      try {
+        heldRaw = fs.readFileSync(LOCK_PATH, 'utf8');
+        held = JSON.parse(heldRaw);
+      } catch {
+        held = null; // unreadable/corrupt → stale
+      }
+      if (!lockIsStale(held)) return false;
+
+      // Could not READ the file we are about to judge — it vanished (the winner is
+      // mid-reclaim, between its rename and its re-create) or is unreadable. We
+      // have no identity to verify against, so reclaiming here would rename away
+      // the winner's brand-new lock unverified and elect a second leader. Measured:
+      // this window alone produced 2/12 double-leader rounds. Retry the create
+      // instead; if the winner has re-created by then we will see a fresh, live
+      // lock and correctly stand down.
+      //
+      // A corrupt-but-readable body (e.g. "not json") still reclaims normally —
+      // heldRaw is non-null there, so this does not wedge a genuinely bad lock.
+      if (heldRaw === null) continue;
+
+      // Claim the RIGHT to reclaim. Losing this rename means another session got
+      // there first and now owns the update, so we are a follower.
+      const claim = `${LOCK_PATH}.${process.pid}.${attempt}.reclaim`;
+      try {
+        fs.renameSync(LOCK_PATH, claim);
+      } catch {
+        return false;
+      }
+
+      // VERIFY WE TOOK THE FILE WE JUDGED. rename() moves whatever is at the path,
+      // not the bytes we inspected. Without this check a slow racer renames away
+      // the WINNER'S BRAND-NEW lock — it judged the old stale body, then moved the
+      // fresh one — and both processes become leader. Measured: 12/12 rounds
+      // elected two leaders before this check existed (scripts/probe-box-lock.mjs).
+      if (heldRaw !== null) {
+        let claimRaw = null;
+        try { claimRaw = fs.readFileSync(claim, 'utf8'); } catch { claimRaw = null; }
+        if (claimRaw !== heldRaw) {
+          // Not ours to take — DISCARD the claim and stand down.
+          //
+          // Do NOT rename it back. renameSync silently OVERWRITES an existing
+          // destination, and the bytes we hold are the STALE ones (that is why we
+          // judged them reclaimable). Restoring them clobbers the live leader's
+          // fresh lock with a stale body, so the next session judges it
+          // reclaimable and becomes a SECOND LEADER while the true leader is
+          // mid `npm install -g` — the exact race this module exists to prevent,
+          // arriving through the restore path. Measured, and invisible to the
+          // concurrency probe because it seeds a dead-PID lock, so claimRaw
+          // always equals heldRaw and this branch never runs there.
+          //
+          // Whoever owns the path already owns the box. Losing the stale bytes
+          // costs nothing; putting them back can only mislead.
+          try { fs.unlinkSync(claim); } catch { /* already gone */ }
+          return false;
+        }
+      }
+      try { fs.unlinkSync(claim); } catch { /* already gone */ }
+    }
+  }
+  return false;
+}
+
+function releaseBoxLock() {
+  if (!lockHeld) return;
+  lockHeld = false;
+  try { fs.unlinkSync(LOCK_PATH); } catch { /* best effort */ }
+}
+
+function holdsBoxLock() {
+  return lockHeld;
+}
+
+// Safety net. The hook's block() calls process.exit(1), which terminates
+// IMMEDIATELY and does NOT unwind pending finally blocks — so the failure path (the
+// one most likely to run) leaked the lock. A leaked lock usually self-heals via the
+// dead-PID check, but Windows recycles PIDs aggressively: if a live process inherits
+// the dead owner's PID inside the 5-minute window, the lock reads as live and every
+// concurrent session waits then hard-blocks. 'exit' handlers DO run on
+// process.exit(), so this covers exit paths we did not anticipate.
+process.on('exit', releaseBoxLock);
+
+module.exports = {
+  LOCK_PATH,
+  LOCK_STALE_MS,
+  acquireBoxLock,
+  releaseBoxLock,
+  holdsBoxLock,
+  lockIsStale,
+  processAlive,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.25.5",
+  "version": "0.25.10",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",

package/scripts/install-rdc-skills.js

@@ -165,18 +165,78 @@ function copyDir(src, dst, ext) {
   return count;
 }
 
+/**
+ * Copy hook files, INCLUDING subdirectories.
+ *
+ * This was flat: readdirSync + a .js/.ps1 filter, skipping anything that was not a
+ * file. So `hooks/lib/` was never created at the destination, and a hook that did
+ * `require('./lib/box-lock')` died MODULE_NOT_FOUND — a SessionStart hook exiting
+ * non-zero with EMPTY stdout on every session, before any health check could run,
+ * meaning its own repair path could never recover it. The npm tarball shipped the
+ * file correctly; it was lost here, in the install step.
+ *
+ * `.mjs` is included because hooks/lib/run-evidence-gate.mjs has the same shape and
+ * was silently dropped by the old filter too.
+ */
 function copyHookFiles(src, dst) {
   if (!fs.existsSync(src)) { warn(`Source not found: ${src}`); return 0; }
   fs.mkdirSync(dst, { recursive: true });
-  const files = fs.readdirSync(src).filter(f => /\.(?:js|ps1)$/i.test(f));
   let count = 0;
-  for (const f of files) {
-    const s = path.join(src, f);
-    if (fs.statSync(s).isFile()) { fs.copyFileSync(s, path.join(dst, f)); count++; }
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      count += copyHookFiles(s, d);
+    } else if (/\.(?:js|mjs|ps1)$/i.test(entry.name)) {
+      fs.copyFileSync(s, d);
+      count++;
+    }
   }
   return count;
 }
 
+/**
+ * A SessionStart hook that cannot even LOAD must never ship.
+ *
+ * Verifies the installed tree by actually running the hook, because file-presence
+ * checks would not have caught this: the source was fine, the tarball was fine, and
+ * only the copied result was broken. A MODULE_NOT_FOUND here is fatal on every
+ * session, so it is worth one subprocess at install time.
+ */
+function assertHooksLoadable(hooksDst, copiedCount) {
+  // A missing hook is FATAL, not a warning. Warn-and-return let the install
+  // "succeed" with NO SessionStart hook at all — the one genuinely vacuous pass in
+  // this guard, and the copy step is exactly where the last critical was lost.
+  if (!copiedCount) throw new Error(`no hook files were copied to ${hooksDst}`);
+  const entry = path.join(hooksDst, 'check-rdc-environment.js');
+  if (!fs.existsSync(entry)) throw new Error(`entry hook missing after copy: ${entry}`);
+
+  const res = require('child_process').spawnSync(process.execPath, ['--check', entry], {
+    encoding: 'utf8', timeout: 20000,
+  });
+  const combined = `${res.stdout || ''}${res.stderr || ''}`;
+  if (res.status !== 0) throw new Error(`installed hook fails to parse: ${combined.trim().slice(0, 300)}`);
+
+  // RESOLVE the dependency graph without EXECUTING it. `require(entry)` ran the
+  // WHOLE hook during install — a real `npm install -g` plus pm2 stop/restart, and
+  // on an unhealthy box a recursive install -> repair -> install loop.
+  // require.resolve answers the only question that matters here ("can it find
+  // ./lib/box-lock?") with no side effects.
+  const probe = [
+    'const { createRequire } = require("node:module");',
+    `const r = createRequire(${JSON.stringify(entry.replace(/\\/g, '/'))});`,
+    'for (const dep of ["./lib/box-lock", "./hook-logger"]) r.resolve(dep);',
+    'process.stdout.write("RESOLVED");',
+  ].join('\n');
+  const load = require('child_process').spawnSync(process.execPath, ['-e', probe], {
+    encoding: 'utf8', input: '', timeout: 20000,
+  });
+  const loadOut = `${load.stdout || ''}${load.stderr || ''}`;
+  if (!/RESOLVED/.test(loadOut)) {
+    throw new Error(`installed hook cannot resolve its imports: ${loadOut.trim().slice(0, 300)}`);
+  }
+}
+
 function copyDirRecursive(src, dst) {
   if (!fs.existsSync(src)) return;
   fs.mkdirSync(dst, { recursive: true });
@@ -896,14 +956,31 @@ function buildZip(version) {
 }
 
 // ── Hook config ───────────────────────────────────────────────────────────────
+
+/**
+ * SessionStart budget for check-rdc-environment.js, DERIVED from the per-step
+ * timeouts in hooks/check-rdc-environment.js repair() rather than restated, so the
+ * two cannot drift apart.
+ *
+ * At the harness default (60s) a genuine cold repair was killed mid-install — the
+ * leader's own steps alone exceed it — and every follower read that as a crash.
+ * The +60s headroom matters: a budget equal to the exact sum kills a leader that
+ * legitimately uses its full per-step allowance right at the boundary.
+ */
+const REPAIR_NPM_SEC = 120;      // npm install -g
+const REPAIR_INSTALL_SEC = 180;  // rdc-skills-install
+const REPAIR_PM2_SEC = 60;       // pm2 stop + restart
+const RDC_ENV_HOOK_TIMEOUT_SEC = REPAIR_NPM_SEC + REPAIR_INSTALL_SEC + REPAIR_PM2_SEC + 60;
+
 function buildHooksConfig(hooksDir, profile = 'core') {
   const base = hooksDir.replace(/\\/g, '/');
-  const cmd  = (file, msg) => {
+  const cmd  = (file, msg, timeoutSec) => {
     const command = process.platform === 'win32'
       ? `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "${base}/run-hidden-hook.ps1" "${base}/${file}"`
       : `node "${base}/${file}"`;
     const entry = { type: 'command', command };
     if (msg) entry.statusMessage = msg;
+    if (timeoutSec) entry.timeout = timeoutSec;
     return entry;
   };
   const config = {
@@ -937,7 +1014,7 @@ function buildHooksConfig(hooksDir, profile = 'core') {
 
   if (profile === 'lifeai') {
     config.SessionStart = [{ hooks: [
-      cmd('check-rdc-environment.js', 'Checking RDC skills runtime...'),
+      cmd('check-rdc-environment.js', 'Checking RDC skills runtime...', RDC_ENV_HOOK_TIMEOUT_SEC),
       cmd('check-cwd.js'),
       cmd('check-stale-work-items.js', 'Checking for stale work items...'),
       // Truth Gate 3.0 Layer 6 — gate watchdog (ADVISORY; SessionStart cannot block).
@@ -1280,7 +1357,11 @@ async function main() {
 
   // 3. Hook files
   const hookCount = copyHookFiles(hooksSrc, hooksDst);
-  ok(`[3/6] Hook files — ${hookCount} file(s) → ${hooksDst}`);
+  // Fail the INSTALL rather than every future session: a hook that cannot load
+  // exits non-zero with empty stdout on SessionStart, before its own repair path
+  // can run.
+  assertHooksLoadable(hooksDst, hookCount);
+  ok(`[3/6] Hook files — ${hookCount} file(s) → ${hooksDst} (load-verified)`);
 
   // 4. Hook wiring
   if (skipHooks) {
@@ -1398,4 +1479,12 @@ async function main() {
   console.log('');
 }
 
-main().catch(e => { fail(e.message); process.exit(1); });
+// Run ONLY when invoked directly. Exporting the copy helpers lets
+// scripts/probe-installed-hooks.mjs verify the real install path instead of
+// re-implementing it — a probe that copies its own way proves nothing about what
+// ships. Without this guard, requiring the module would run a full install.
+module.exports = { copyHookFiles, assertHooksLoadable, RDC_ENV_HOOK_TIMEOUT_SEC };
+
+if (require.main === module) {
+  main().catch(e => { fail(e.message); process.exit(1); });
+}

package/scripts/local-install-with-stop.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Install rdc-skills globally FROM LOCAL SOURCE, using the stop-first sequence.
+#
+# This is the empirical test of the fix: the same `npm install -g` that produced
+# EBUSY should now succeed because the lock holder is stopped first. It is a LOCAL
+# install (a path, not the registry) — nothing is published.
+#
+# The restart is unconditional: leaving the MCP down after a failed install would
+# be worse than the failure being repaired.
+set -u
+
+HOLDER=rdc-skills-mcp
+
+echo "== before =="
+pm2 jlist | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const p=JSON.parse(s).find(x=>x.name===process.argv[1]);console.log('  '+process.argv[1]+': '+(p?p.pm2_env.status:'absent'));})" "$HOLDER"
+npm ls -g '@lifeaitools/rdc-skills' --depth=0 2>/dev/null | tail -1
+
+echo "== stop the lock holder =="
+pm2 stop "$HOLDER" >/dev/null 2>&1 && echo "  stopped $HOLDER" || echo "  could not stop (may be absent)"
+
+echo "== npm install -g from local source =="
+set +e
+npm install -g "C:/Dev/rdc-skills" 2>&1 | tail -5
+INSTALL_RC=${PIPESTATUS[0]}
+set -e
+echo "  install exit=$INSTALL_RC"
+
+echo "== restart (always) =="
+pm2 restart "$HOLDER" >/dev/null 2>&1 && echo "  restarted $HOLDER" || echo "  restart FAILED"
+
+echo "== after =="
+npm ls -g '@lifeaitools/rdc-skills' --depth=0 2>/dev/null | tail -1
+for i in 1 2 3 4 5 6 7 8; do
+  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 http://127.0.0.1:3110/health 2>/dev/null)
+  [ "$code" = "200" ] && break
+  sleep 1
+done
+echo "  health 3110 -> HTTP ${code:-none}"
+curl -s --max-time 3 http://127.0.0.1:3110/health 2>/dev/null | head -c 200
+echo
+exit "$INSTALL_RC"

package/scripts/probe-box-lock.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * Prove the box-wide update is SINGLE-FLIGHT under concurrent session starts.
+ *
+ * The bug this guards: rdc-skills is one box-wide npm package and one PM2 process,
+ * but every session/worktree runs the SessionStart hook. Without a lock, N sessions
+ * each conclude "unhealthy" and each run `npm install -g` on the same directory.
+ *
+ * Imports the REAL implementation from hooks/lib/box-lock.js. An earlier version
+ * kept its own copy of these functions, which drifted to the old algorithm — so it
+ * reported PASS for code that was not shipping. A test that duplicates its subject
+ * tests nothing.
+ */
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const HOOK_LIB = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'hooks', 'lib', 'box-lock.js');
+const { acquireBoxLock, releaseBoxLock, LOCK_PATH, LOCK_STALE_MS } = require(HOOK_LIB);
+
+const release = () => { try { fs.unlinkSync(LOCK_PATH); } catch { /* ignore */ } };
+
+release(); // clean slate
+let fail = 0;
+const check = (name, ok) => { console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}`); if (!ok) fail++; };
+
+// 1. Happy path. SEQUENTIAL and in-process, so it proves only that a held lock is
+//    not handed out twice — it cannot exercise interleaving. Test 7 does that.
+const winners = Array.from({ length: 10 }, () => acquireBoxLock()).filter(Boolean).length;
+check(`sequential starts: exactly 1 updater of 10 (got ${winners})`, winners === 1);
+
+// 2. A live holder is respected — a follower must NOT steal the lock.
+check('live lock respected', acquireBoxLock() === false);
+
+// 3. Release hands the box to the next session.
+releaseBoxLock();
+check('after release, next session leads', acquireBoxLock() === true);
+releaseBoxLock();
+
+// 4. A dead owner must not wedge every future session forever.
+fs.writeFileSync(LOCK_PATH, JSON.stringify({ pid: 999999, ts: new Date().toISOString() }));
+check('dead owner reclaimed', acquireBoxLock() === true);
+releaseBoxLock();
+
+// 5. A stale-but-live lock (crashed mid-install, PID reused) is reclaimed by age.
+fs.writeFileSync(LOCK_PATH, JSON.stringify({
+  pid: process.pid, ts: new Date(Date.now() - LOCK_STALE_MS - 1000).toISOString(),
+}));
+check('stale lock reclaimed by age', acquireBoxLock() === true);
+releaseBoxLock();
+
+// 6. Corrupt bodies must not wedge the box. `pid: 0` is the sharp one:
+//    process.kill(0, 0) signals the CURRENT PROCESS GROUP and succeeds, so a naive
+//    liveness check reads it as alive forever; paired with an unparseable ts, the
+//    age check is NaN and never trips either.
+for (const body of ['not json', '{"pid":0,"ts":"garbage"}', '{"pid":-1,"ts":null}', '{}']) {
+  fs.writeFileSync(LOCK_PATH, body);
+  check(`corrupt lock reclaimed: ${body.slice(0, 26)}`, acquireBoxLock() === true);
+  releaseBoxLock();
+}
+
+// 7. REAL concurrency against a STALE lock — the reclaim TOCTOU.
+//
+//    The naive reclaim (read -> judge stale -> unlink -> open 'wx') lets two racers
+//    both judge the lock stale, and the loser's unlink deletes the WINNER's fresh
+//    lock, so both become leader and both run `npm install -g`. Sequential calls in
+//    one process can never surface this; only real processes racing can.
+{
+  // A leader HOLDS the lock briefly before exiting. Without the hold, a winner
+  // exits (releasing on 'exit') before the next racer even calls acquire, so every
+  // racer wins in turn and the result looks like a race that never happened.
+  const racer = `
+    const { acquireBoxLock } = require(${JSON.stringify(HOOK_LIB)});
+    const go = Number(process.argv[2]);
+    while (Date.now() < go) { /* spin to a shared start instant */ }
+    const won = acquireBoxLock();
+    process.stdout.write(won ? 'LEADER' : 'follower');
+    if (won) { const until = Date.now() + 600; while (Date.now() < until) {} }
+  `;
+
+  // spawn(), NOT spawnSync(): spawnSync BLOCKS until each child exits, so the
+  // "racers" ran strictly one after another and never overlapped. That flaw made
+  // this test report 12/12 double-leaders against correct code.
+  const runRound = () => new Promise((resolve) => {
+    fs.writeFileSync(LOCK_PATH, JSON.stringify({ pid: 999999, ts: new Date().toISOString() }));
+    const go = Date.now() + 400;
+    const out = [];
+    let done = 0;
+    for (let i = 0; i < 4; i++) {
+      const kid = spawn(process.execPath, ['-e', racer, String(go)], { stdio: ['ignore', 'pipe', 'ignore'] });
+      let buf = '';
+      kid.stdout.on('data', (d) => { buf += d; });
+      kid.on('close', () => {
+        out.push(buf);
+        if (++done === 4) resolve(out.filter((o) => o.includes('LEADER')).length);
+      });
+    }
+  });
+
+  const ROUNDS = 12;
+  let doubleLeader = 0;
+  let noLeader = 0;
+  for (let r = 0; r < ROUNDS; r++) {
+    const leaders = await runRound();
+    if (leaders > 1) doubleLeader++;
+    if (leaders === 0) noLeader++;
+    release();
+  }
+  check(`concurrent reclaim: no round elected 2 leaders (${doubleLeader}/${ROUNDS} bad)`, doubleLeader === 0);
+  // Every racer bailing would be "safe" but useless — nobody would repair the box.
+  check(`concurrent reclaim: a leader was elected each round (${noLeader}/${ROUNDS} empty)`, noLeader === 0);
+}
+release();
+
+// 8. NEGATIVE CONTROL — does test 7 actually have teeth?
+//
+// This suite has already produced two false verdicts: a copy of the implementation
+// that drifted (reported PASS for code that was not shipping), and a spawnSync
+// harness whose "racers" never overlapped (reported FAIL for code that was fine).
+// A concurrency test that cannot fail is worse than no test, so run the SAME
+// harness against a deliberately naive lock and require that it catches it.
+{
+  const naivePath = path.join(os.tmpdir(), `naive-box-lock-${process.pid}.js`);
+  fs.writeFileSync(naivePath, `
+    const fs = require('node:fs');
+    const LOCK_PATH = ${JSON.stringify(`${LOCK_PATH}.naive`)};
+    // The original algorithm: read -> judge stale -> unlink -> open('wx').
+    // No rename, no identity check. This is what shipped before the fix.
+    function acquireBoxLock() {
+      for (let a = 0; a < 2; a++) {
+        try { const fd = fs.openSync(LOCK_PATH, 'wx');
+          fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: new Date().toISOString() }));
+          fs.closeSync(fd); return true;
+        } catch (err) {
+          if (err.code !== 'EEXIST') return false;
+          try { fs.unlinkSync(LOCK_PATH); } catch { return false; }
+        }
+      }
+      return false;
+    }
+    module.exports = { acquireBoxLock, LOCK_PATH };
+  `);
+  const naiveLock = `${LOCK_PATH}.naive`;
+  const naiveRacer = `
+    const { acquireBoxLock } = require(${JSON.stringify(naivePath)});
+    const go = Number(process.argv[2]);
+    while (Date.now() < go) {}
+    const won = acquireBoxLock();
+    process.stdout.write(won ? 'LEADER' : 'follower');
+    if (won) { const until = Date.now() + 600; while (Date.now() < until) {} }
+  `;
+  const naiveRound = () => new Promise((resolve) => {
+    fs.writeFileSync(naiveLock, JSON.stringify({ pid: 999999, ts: new Date().toISOString() }));
+    const go = Date.now() + 400;
+    const out = []; let done = 0;
+    for (let i = 0; i < 4; i++) {
+      const kid = spawn(process.execPath, ['-e', naiveRacer, String(go)], { stdio: ['ignore', 'pipe', 'ignore'] });
+      let buf = '';
+      kid.stdout.on('data', (d) => { buf += d; });
+      kid.on('close', () => { out.push(buf); if (++done === 4) resolve(out.filter((o) => o.includes('LEADER')).length); });
+    }
+  });
+  let caught = 0;
+  const ROUNDS = 12;
+  for (let r = 0; r < ROUNDS; r++) {
+    if (await naiveRound() > 1) caught++;
+    try { fs.unlinkSync(naiveLock); } catch { /* ignore */ }
+  }
+  check(`negative control: harness DETECTS the naive lock (${caught}/${ROUNDS} rounds caught)`, caught > 0);
+  try { fs.unlinkSync(naivePath); } catch { /* ignore */ }
+  try { fs.unlinkSync(naiveLock); } catch { /* ignore */ }
+}
+
+console.log(fail ? `\n${fail} FAILURE(S)` : '\nall box-lock invariants hold');
+process.exit(fail ? 1 : 0);

package/scripts/probe-installed-hooks.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Prove the INSTALLED hook tree can actually load.
+ *
+ * The source was fine, the npm tarball was fine, and only the copied result was
+ * broken: copyHookFiles() was flat, so hooks/lib/ was never created at the
+ * destination and require('./lib/box-lock') died MODULE_NOT_FOUND — a SessionStart
+ * hook exiting non-zero with EMPTY stdout on every session, before any health check
+ * could run, so its own repair path could never recover it.
+ *
+ * File-presence checks in the repo would not have caught that. This replays the
+ * real copy into a scratch dir and LOADS the result.
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { copyHookFiles } = require(path.join(ROOT, 'scripts', 'install-rdc-skills.js'));
+
+let fail = 0;
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`);
+  if (!ok) fail++;
+};
+
+const dst = fs.mkdtempSync(path.join(os.tmpdir(), 'rdc-hooks-install-'));
+const count = copyHookFiles(path.join(ROOT, 'hooks'), dst);
+check(`copied hook files (${count})`, count > 0);
+
+// The exact loss: a nested dir the flat copy skipped.
+check('hooks/lib/ exists at destination', fs.existsSync(path.join(dst, 'lib')));
+check('hooks/lib/box-lock.js copied', fs.existsSync(path.join(dst, 'lib', 'box-lock.js')));
+check('hooks/lib/run-evidence-gate.mjs copied (.mjs was filtered out too)',
+  fs.existsSync(path.join(dst, 'lib', 'run-evidence-gate.mjs')));
+
+// Load every top-level hook for real. --check only parses; it does not resolve
+// require(), which is precisely what broke.
+const hooks = fs.readdirSync(dst).filter((f) => f.endsWith('.js'));
+const unresolved = [];
+for (const h of hooks) {
+  const entry = path.join(dst, h).replace(/\\/g, '/');
+  const res = spawnSync(process.execPath, ['-e', `require(${JSON.stringify(entry)})`], {
+    encoding: 'utf8', input: '', timeout: 20000,
+  });
+  const out = `${res.stdout || ''}${res.stderr || ''}`;
+  if (/MODULE_NOT_FOUND|Cannot find module/.test(out)) {
+    unresolved.push(`${h}: ${(out.match(/Cannot find module '[^']+'/) || [''])[0]}`);
+  }
+}
+check(`all ${hooks.length} installed hooks resolve their imports`, unresolved.length === 0,
+  unresolved.slice(0, 3).join(' | '));
+
+fs.rmSync(dst, { recursive: true, force: true });
+console.log(fail ? `\n${fail} FAILURE(S)` : '\ninstalled hook tree loads cleanly');
+process.exit(fail ? 1 : 0);