ruvnet-brain 3.9.84-dev → 3.9.129-dev

package/scripts/selfcheck.mjs

@@ -0,0 +1,646 @@
+#!/usr/bin/env node
+/**
+ * selfcheck.mjs — THE POST-INSTALL SELF-CHECK THAT RUNS ON THE USER'S MACHINE AND CAN FAIL.
+ * (ADR-053 §2 "hooks-as-shipped battery", ADR-055 §8 / build item 2 "hook battery v2".)
+ *
+ * ── WHY THIS FILE EXISTS ────────────────────────────────────────────────────────────────────────
+ * An independent grader scored this repo 40/100 on one question: "is there any mechanical check
+ * that runs after install on a stranger's machine and can fail?" The answer was NO, for three
+ * reasons that were all real and all in bin/install.mjs:
+ *
+ *   1. `verifyInstall()` WARNS and returns a result object. The installer called it and threw the
+ *      result away (install.mjs, the `if (!FLAG_NO_VERIFY)` block). Zero stores, a missing reader,
+ *      or an absent MCP server printed a yellow line and the process still EXITED 0.
+ *   2. `smokeQuery()` — same shape, same discarded verdict.
+ *   3. `doctor()` printed "Healthy" / "Needs attention" honestly but returned `undefined` and set
+ *      no exit code, so `npx ruvnet-brain --doctor && echo ok` printed `ok` on a dead install.
+ *      Honest prose that no machine can read is not a check.
+ *
+ * Every one of those is a CONSUMPTION bug, not a detection bug: the facts were gathered and then
+ * dropped on the floor. This module supplies the missing half — a verdict with an exit code — and
+ * adds the one class of defect nothing in the repo could see at all: what the shipped hooks
+ * actually DO when a stranger's Claude Code fires them.
+ *
+ * ── ELEGANCE CONSTRAINT: DO NOT HAND-ROLL WHAT rUv ALREADY SHIPS ────────────────────────────────
+ * Grounded via the search_ruvnet MCP tool before writing a line. What was found, and what it means
+ * for this file:
+ *
+ *   REUSED (not reimplemented):
+ *   • `scripts/hook-registry.mjs` — THIS REPO's merged six-registry census (ADR-055 §7). It already
+ *     enumerates every registration a session loads across plugin / user / project / third-party /
+ *     plugin-installed / marketplace-clone, normalizes them, parses the shim's dispatch TABLE as the
+ *     authority for mode+offBehavior, loads hook-contracts.json for everything outside it, and ships
+ *     `lintM1` (double-registration from two code roots) and `lintM3` (timeout totality). The brief
+ *     asked for "enumerate the user's own hooks", "detect double-registration" and "assert against
+ *     hook-contracts.json + the shim TABLE (never a hand-copied list)" — that is `buildRegistry` +
+ *     `lintM1` + `shimTable` + `loadContracts`, verbatim. Writing a second enumerator here would
+ *     have recreated the exact "adjacent door" defect (F16) the registry exists to close: a gate and
+ *     its test as two different code paths.
+ *   • `ruflo metaharness mcp-scan` / `threat-model` — rUv's shipped static policy/permission audit
+ *     (ruflo/plugins/ruflo-metaharness/scripts/mcp-scan.mjs; its own header: "Static security scan of
+ *     the harness's declared MCP surface… Pure-read, no dispatch", exit 1 at/above --fail-on). We
+ *     SHELL OUT to it and report its verdict. We do not reimplement default-deny allowlist analysis
+ *     — see also ruvector/npm/packages/ruvector/bin/mcp-policy.js (ADR-256, the same posture as a
+ *     pure module). If ruflo is absent we say so in one line and score nothing.
+ *
+ *   HAND-ROLLED — the irreducible remainder, stated out loud:
+ *   • THE EXTERNAL PROCESS-GROUP WATCHDOG and the four stdin regimes (§battery below). Nothing in
+ *     the rUv ecosystem fires a Claude Code hook as a subprocess and reaps its process group:
+ *     mcp-scan and threat-model are STATIC by their own documentation ("no dispatch"), and
+ *     mcp-policy.js is explicitly "dependency-free and side-effect-free so it can be unit-tested
+ *     without spawning". Static analysis cannot observe a hook that hangs on held-open stdin,
+ *     because the hang is not in the JSON — it is in the process. This is the genuinely absent
+ *     capability, so it is the only thing written from scratch here.
+ *
+ * ── WHAT CAN MAKE THIS FAIL (the exit code IS the product) ──────────────────────────────────────
+ * `violations` are OURS — registrations this package ships and is therefore accountable for. The
+ * user's own hooks and third-party plugins are ENUMERATED AND REPORTED, never executed and never
+ * counted against them (inventing a verdict for someone else's hook is the fiction ADR-055 §6
+ * refuses by name). A stranger's broken machine must be able to make this exit non-zero; a
+ * stranger's DIFFERENT-but-fine machine must not.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// ── contract constants (ADR-053 §2.5 / §2.3) ────────────────────────────────────────────────────
+export const STDOUT_CAP_BYTES = 4096; // it lands in the user's context window
+export const TIMEOUT_MARGIN = 0.8; // wall-clock must finish inside 80% of the declared timeout
+export const WATCHDOG_GRACE_MS = 2000; // SIGTERM → this long → hard kill, then count survivors
+
+/** Advisory hooks may only ever exit 0. Blocking hooks may exit 0, 1 or 2 (ADR-023's table). */
+export const ALLOWED_EXITS = Object.freeze({ advisory: [0], blocking: [0, 1, 2] });
+
+/**
+ * Load hook-registry.mjs. It is a sibling in `scripts/`, shipped alongside this file — see the
+ * package.json `files` entry added with it. A dynamic import keeps this module importable by tests
+ * that stub the registry, and lets a missing sibling degrade to a NAMED failure rather than a
+ * module-load crash on someone's machine.
+ */
+async function loadRegistry() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return import(new URL(`file://${path.join(here, 'hook-registry.mjs')}`).href);
+}
+
+// ── §0 THE PERSISTED GROUNDING VERDICT (ADR-058 D8 — the "-20 grounding smoke never fatal" line) ──
+/**
+ * A failed grounding smoke stays NON-FATAL on a default install — a first-run model download or an
+ * air-gapped machine is not a broken install, and blocking there fails every offline user. What
+ * changes is that the verdict stops EVAPORATING the moment the process exits:
+ *
+ *   WRITER   bin/install.mjs, once, right after its own real smoke-query attempt.
+ *   READER   bin/install.mjs's `--doctor` (via groundingUnproven() below) — the one place this DOES
+ *            gate an exit code, because --doctor is the command someone runs specifically TO ASK
+ *            whether the install is healthy, unlike a fresh install which must never abort on this.
+ *   CLEARER  kb/forge-mcp-all.mjs, the moment a REAL search_ruvnet returns real cited passages —
+ *            "the first real search_ruvnet clears or confirms it" (ADR-058 §D8). That file cannot
+ *            import this one (it ships standalone inside the KB bundle, a different runtime root —
+ *            see its own header note on the OFF-switch check for the identical reasoning), so it
+ *            duplicates the tiny path+write logic rather than reaching across that boundary.
+ *   SURFACER plugin/scripts/session-start.sh reads the same file directly (no node dependency to
+ *            spare there either) — this JSON shape is the one contract all four sides share.
+ *
+ * Path matches the existing token-ledger convention (bin/install.mjs's meterSummaryLine() /
+ * scripts/token-report.mjs's CANONICAL_LEDGER): XDG_CACHE_HOME when set, else ~/.cache. Deliberately
+ * NOT under the (possibly RUVNET_BRAIN_KB-overridden) KB dir — this is a HOME-scoped fact, a sibling
+ * of health.json, not a KB artifact.
+ */
+export function installStatePath() {
+  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ruvnet-brain', 'install-state.json');
+}
+
+/** Never throws. Absence is a valid, common state (nothing has ever written here) — returns null. */
+export function readInstallState() {
+  try { return JSON.parse(fs.readFileSync(installStatePath(), 'utf8')); } catch { return null; }
+}
+
+/**
+ * Merge-write the verdict. Best-effort: a failed write must never break whichever caller (install,
+ * doctor, or the MCP server mid-query) is trying to record it. Write-beside-then-rename so a reader
+ * racing the writer never observes a torn/partial file.
+ */
+export function writeInstallState(patch) {
+  const p = installStatePath();
+  let prev = {};
+  try { prev = JSON.parse(fs.readFileSync(p, 'utf8')); } catch { /* first write */ }
+  const next = { ...prev, ...patch, at: new Date().toISOString() };
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2));
+    fs.renameSync(tmp, p);
+  } catch { /* best-effort — persisting the verdict must never break the caller */ }
+  return next;
+}
+
+/**
+ * true only when a verdict was actually recorded AND it says something other than 'proven'. No
+ * recorded state at all (a machine that has never run this install, or an install that predates
+ * this feature) is NOT "unproven" — it is unknown, and an unknown must never be charged as a fail.
+ */
+export function groundingUnproven(state) {
+  return Boolean(state) && state.grounding !== 'proven';
+}
+
+// ── §1 RESOLVE THE INSTALLED SURFACE (never the repo's) ─────────────────────────────────────────
+/**
+ * Find the plugin payload Claude Code actually BOOTED. Order matters and is not arbitrary:
+ * the packed install cache is what a stranger runs; the marketplace clone is what the user layer's
+ * own commands execute from; the checkout is the preimage and is only correct for a developer.
+ * Reading the wrong one is precisely the defect this check exists to catch, so the choice is
+ * reported in the output rather than assumed.
+ */
+export function resolveInstalledSurface({ home = os.homedir(), repo = null } = {}) {
+  const candidates = [];
+  const cache = path.join(home, '.claude', 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain');
+  try {
+    for (const v of fs.readdirSync(cache)) {
+      const root = path.join(cache, v);
+      if (fs.existsSync(path.join(root, 'hooks', 'hooks.json'))) {
+        candidates.push({ root, source: `installed:${v}`, mtime: fs.statSync(path.join(root, 'hooks', 'hooks.json')).mtimeMs });
+      }
+    }
+  } catch { /* no packed install on this machine */ }
+  candidates.sort((a, b) => b.mtime - a.mtime); // newest generation wins; several can coexist
+  const clone = path.join(home, '.claude', 'plugins', 'marketplaces', 'ruvnet-brain', 'plugin');
+  if (fs.existsSync(path.join(clone, 'hooks', 'hooks.json'))) {
+    candidates.push({ root: clone, source: 'marketplace-clone', mtime: 0 });
+  }
+  if (repo && fs.existsSync(path.join(repo, 'plugin', 'hooks', 'hooks.json'))) {
+    candidates.push({ root: path.join(repo, 'plugin'), source: 'checkout', mtime: 0 });
+  }
+  const chosen = candidates[0];
+  if (!chosen) return { ok: false, reason: 'no installed ruvnet-brain plugin payload found on this machine' };
+  return {
+    ok: true,
+    root: chosen.root,
+    source: chosen.source,
+    hooksFile: path.join(chosen.root, 'hooks', 'hooks.json'),
+    shimFile: path.join(chosen.root, 'scripts', 'hook-shim.mjs'),
+    alternates: candidates.slice(1).map((c) => c.source),
+  };
+}
+
+/** Every registration in the INSTALLED hooks.json, flat. Shape mirrors hook-registry's records. */
+export function readInstalledRegistrations(hooksFile) {
+  const doc = JSON.parse(fs.readFileSync(hooksFile, 'utf8'));
+  const node = doc.hooks ?? doc;
+  const out = [];
+  for (const [event, entries] of Object.entries(node)) {
+    if (!Array.isArray(entries)) continue;
+    for (const group of entries) {
+      for (const h of group?.hooks ?? []) {
+        if (typeof h?.command !== 'string') continue;
+        out.push({
+          event,
+          matcher: group.matcher ?? '',
+          command: h.command,
+          timeout: typeof h.timeout === 'number' ? h.timeout : null,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// ── §2 THE EXTERNAL PROCESS-GROUP WATCHDOG (hand-rolled — the irreducible remainder) ────────────
+/**
+ * THE FOUR STDIN REGIMES (ADR-053 §2.2). Claude Code hands a hook its event as JSON on stdin and
+ * closes the pipe. Three of these four are what happens when that contract is broken:
+ *
+ *   valid   — a real event JSON object, pipe closed. The normal path.
+ *   empty   — immediate EOF, zero bytes. A hook that blocks on a read it never gets hangs here.
+ *   garbage — 1MB of non-JSON. Catches parsers that buffer unboundedly or crash on bad input.
+ *   held    — bytes written, pipe DELIBERATELY LEFT OPEN past the hook's declared timeout. THE
+ *             CANONICAL HANG, and the reason an in-process timer is not acceptable evidence: the
+ *             hook is blocked in a synchronous read, so its own event loop is frozen and any timer
+ *             it set will never fire. Only a watchdog in a DIFFERENT process can observe it, and
+ *             only a PROCESS-GROUP kill can clean it up — SIGTERM to the direct child leaves the
+ *             grandchildren (a spawned `node`, a `bash` subshell) orphaned and running.
+ */
+export const STDIN_REGIMES = Object.freeze(['valid', 'empty', 'garbage', 'held']);
+
+const EVENT_JSON = (event) => JSON.stringify({
+  session_id: 'selfcheck', transcript_path: '', cwd: process.cwd(), hook_event_name: event,
+  prompt: 'selfcheck probe', tool_name: 'Read', tool_input: {},
+});
+
+/**
+ * Kill an entire process group and report whether anything survived.
+ *
+ * POSIX: the child is spawned `detached`, which makes its PID the process-group leader, so
+ * `kill(-pid)` reaches every descendant. `kill(-pid, 0)` then answers "does this group still have
+ * members?" without sending a signal — ESRCH means empty. That is a pure-Node descendant probe with
+ * no `ps` dependency and no output parsing.
+ *
+ * WIN32: there are no process groups in the POSIX sense and `kill(-pid)` throws EINVAL. `taskkill
+ * /T /F` is the platform's tree-kill and is authoritative, but it gives no "did anything survive"
+ * readout — so this reports `survivors: null` (NOT MEASURABLE) instead of `false`. A check must
+ * never report a clean result it did not actually observe; that is the fabrication this whole file
+ * exists to stop. The suite runs on windows-unit and asserts the honest null there.
+ */
+function killGroup(child) {
+  const pid = child.pid;
+  if (!pid) return { killed: false, survivors: false };
+  if (process.platform === 'win32') {
+    try { spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' }); } catch { /* already gone */ }
+    return { killed: true, survivors: null }; // honestly not measurable on this platform
+  }
+  try { process.kill(-pid, 'SIGTERM'); } catch { /* group already gone */ }
+  return { killed: true, survivors: undefined }; // resolved after the grace window by the caller
+}
+
+function groupAlive(pid) {
+  if (process.platform === 'win32' || !pid) return null;
+  try { process.kill(-pid, 0); return true; } catch { return false; }
+}
+
+/**
+ * HOW TO HAND A COMMAND STRING TO A SHELL — the one genuinely platform-specific step in firing a
+ * hook, and the one this file got wrong for its whole first release.
+ *
+ * MEASURED, NOT REASONED. On windows-latest (Actions run 30280922684, job windows-unit) EVERY
+ * firing of EVERY fixture came back `exited 1` with `node:internal/modules/cjs/loader:1433` on
+ * stderr — under all four stdin regimes, including `held`, where the hook is supposed to hang. The
+ * hooks never ran at all: node.exe was handed a filename it could not resolve. Two details in the
+ * win32 spawn were missing. They are NOT equally guilty and the comment says which is which,
+ * because "both are required" would be a guess and only one of them was measured red:
+ *
+ *   1. `windowsVerbatimArguments: true` — THE DEFECT. Without it libuv escapes each argument for
+ *      the MSVC command-line convention, so `node "C:\…\hook-shim.mjs" ground` goes on the wire as
+ *      `"node \"C:\…\hook-shim.mjs\" ground"`. cmd.exe does not understand `\"`; it passes the
+ *      backslashes through, node.exe's argv parser turns each `\"` back into a literal quote, and
+ *      node goes looking for a file whose name begins with a quote character.
+ *   2. The command wrapped in its OWN quotes — CORRECTNESS, not the current failure. `cmd /?` rule
+ *      2 (which applies whenever /S is given) is: "if the first character is a quote character then
+ *      strip the leading character and remove the last quote character on the command line". Every
+ *      registration we ship today begins `node …`, so rule 2 never fires and the wrap changes
+ *      nothing — but a command beginning with a quoted interpreter path
+ *      (`"C:\Program Files\nodejs\node.exe" …`) would have a PATH quote eaten instead. The wrap
+ *      gives rule 2 something of its own to consume. Proven by the §1b test named for that case.
+ *
+ * This is node's own answer to the identical problem — `normalizeSpawnArguments()` in
+ * lib/child_process.js does exactly this for `shell: true`, cmd-vs-other branch included. We cannot
+ * simply pass `shell: true` because the shell choice is part of what is under test (a hook must be
+ * fired the way the host fires it), so the rule is reproduced here and exported so it can be proven
+ * on ANY platform — it is a pure function of (command, platform), which is the only reason a
+ * Windows-only defect is testable on a mac.
+ */
+export function shellInvocation(command, platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return { file: '/bin/sh', args: ['-c', command], windowsVerbatimArguments: false };
+  const file = env.COMSPEC || 'cmd.exe';
+  // `/d /s /c` and the quote-wrapping are cmd.exe's contract specifically. A COMSPEC pointing at
+  // anything else (bash.exe, pwsh) takes the POSIX-shaped branch rather than being fed cmd syntax.
+  if (/^(?:.*\\)?cmd(?:\.exe)?$/i.test(file)) {
+    return { file, args: ['/d', '/s', '/c', `"${command}"`], windowsVerbatimArguments: true };
+  }
+  return { file, args: ['-c', command], windowsVerbatimArguments: false };
+}
+
+/**
+ * Fire ONE registration under ONE stdin regime, with the watchdog armed.
+ * Returns a measurement — never a verdict. Verdicts are assembled in assertContract() below, so
+ * that "what happened" and "what was required" stay two separate, separately-testable things.
+ */
+export function fireHook({ command, event, regime, timeoutSec, cwd, env = {}, graceMs = WATCHDOG_GRACE_MS }) {
+  return new Promise((resolve) => {
+    const budgetMs = Math.max(1, Math.round(timeoutSec * 1000));
+    // The literal registered command, run the way Claude Code runs it: through a shell, with
+    // ${CLAUDE_PLUGIN_ROOT} already substituted by the caller. Testing the module or the hook BODY
+    // instead of this string is the adjacent-door defect (ADR-053 §2.1) — the shim layer that
+    // actually runs on a stranger's machine would go untested.
+    const inv = shellInvocation(command);
+    const child = spawn(inv.file, inv.args, {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32', // own process group — required for the group kill
+      windowsHide: true,
+      windowsVerbatimArguments: inv.windowsVerbatimArguments, // ignored on Unix; load-bearing on win32
+    });
+
+    let stdout = Buffer.alloc(0);
+    let stderr = Buffer.alloc(0);
+    let stdoutTruncated = false;
+    const started = Date.now();
+    let settled = false;
+    // THE RACE THIS FLAG EXISTS TO LOSE-PROOF (found by the hang fixture, not by reasoning): SIGTERM
+    // kills the child almost instantly, so `close` fires while the watchdog is still inside its
+    // grace window waiting to probe for survivors. Without this flag the close handler wins and
+    // reports `timedOut: false` — i.e. a hook the watchdog had to KILL was recorded as having
+    // exited cleanly, and the single most important defect class in this file silently passed.
+    let watchdogFired = false;
+
+    // Bound our OWN memory: a flooding hook must not OOM the checker that is measuring it. We keep
+    // the first 64KB (enough to prove a >4KB cap violation many times over) and count the rest.
+    let stdoutBytes = 0;
+    child.stdout.on('data', (d) => {
+      stdoutBytes += d.length;
+      if (stdout.length < 65536) stdout = Buffer.concat([stdout, d.subarray(0, 65536 - stdout.length)]);
+      else stdoutTruncated = true;
+    });
+    child.stderr.on('data', (d) => { if (stderr.length < 65536) stderr = Buffer.concat([stderr, d]); });
+    child.stdout.on('error', () => {});
+    child.stderr.on('error', () => {});
+    child.stdin.on('error', () => {}); // EPIPE when the hook exits before reading — expected, not news
+
+    // ── the stdin regime ──
+    try {
+      if (regime === 'valid') { child.stdin.write(EVENT_JSON(event)); child.stdin.end(); }
+      else if (regime === 'empty') { child.stdin.end(); }
+      else if (regime === 'garbage') { child.stdin.write(Buffer.alloc(1024 * 1024, 0x41)); child.stdin.end(); }
+      else if (regime === 'held') { child.stdin.write(EVENT_JSON(event)); /* NEVER end() — this is the hang */ }
+    } catch { /* the child may already be gone */ }
+
+    const finish = (extra) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(watchdog);
+      try { child.stdin.destroy(); } catch { /* ignore */ }
+      resolve({
+        regime,
+        elapsedMs: Date.now() - started,
+        stdoutBytes,
+        stdout: stdout.toString('utf8'),
+        stderr: stderr.toString('utf8'),
+        stdoutTruncated,
+        ...extra,
+      });
+    };
+
+    // THE WATCHDOG. It lives in THIS process, which is external to the hook — that is the whole
+    // point. A timer the hook sets cannot fire while the hook is blocked in a synchronous read.
+    const watchdog = setTimeout(() => {
+      if (settled) return;
+      watchdogFired = true; // set BEFORE the kill — the close event can arrive on the next tick
+      const k = killGroup(child);
+      // Give the group the grace window to die, THEN ask whether anything is still alive. An
+      // immediate probe would report survivors that were merely mid-teardown.
+      setTimeout(() => {
+        const alive = k.survivors === null ? null : groupAlive(child.pid);
+        if (alive === true) { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }
+        finish({ status: null, timedOut: true, survivors: alive, signal: 'SIGTERM' });
+      }, graceMs);
+    }, budgetMs);
+
+    child.on('error', (e) => finish({ status: null, timedOut: false, spawnError: e.message, survivors: false }));
+    child.on('close', (status, signal) => {
+      if (settled || watchdogFired) return; // the watchdog owns the verdict once it has fired
+      // Even on a clean exit, ask whether the hook left descendants behind (ADR-053 §2.7). A hook
+      // that exits 0 while its spawned child keeps running is a leak the exit code cannot show.
+      const alive = groupAlive(child.pid);
+      if (alive === true) { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }
+      finish({ status, signal, timedOut: false, survivors: alive });
+    });
+  });
+}
+
+// ── §3 ASSERT THE CONTRACT (from the shim TABLE + hook-contracts.json — never a hand-copied list) ─
+/**
+ * Turn measurements into violations, using the DECLARED contract as the only source of truth.
+ *
+ * `mode` comes from hook-registry's `shimTable()` (which PARSES plugin/scripts/hook-shim.mjs's
+ * dispatch TABLE — the same authority ADR-054 §3 stores offBehavior in) or from the checked-in
+ * hook-contracts.json for anything registered outside the shim. There is deliberately no literal
+ * list of hook ids in this file: a hand-copied list drifts, and a drifted list turns a real
+ * regression into a green test. When NEITHER authority declares a mode, that is itself the finding
+ * (hook-registry's M6) — we do not guess one.
+ */
+export function assertContract({ rec, measurement, mode, timeoutSec }) {
+  const v = [];
+  const where = `${rec.event} ${rec.matcher || '*'} → ${rec.handler ?? rec.command}`;
+  const tag = `[${measurement.regime}]`;
+
+  if (measurement.spawnError) {
+    v.push({ kind: 'spawn-failed', where, regime: measurement.regime, detail: measurement.spawnError });
+    return v;
+  }
+
+  // 1. WALL CLOCK inside the declared timeout, with margin. A budget AT the timeout detects nothing
+  //    until users are already eating it on every prompt (ADR-053 §2.3).
+  const budgetMs = timeoutSec * 1000;
+  if (measurement.timedOut) {
+    v.push({ kind: 'hang', where, regime: measurement.regime, detail: `${tag} did not exit within its declared timeout of ${timeoutSec}s — the watchdog had to kill the process group` });
+  } else if (measurement.elapsedMs > budgetMs * TIMEOUT_MARGIN) {
+    v.push({ kind: 'slow', where, regime: measurement.regime, detail: `${tag} took ${measurement.elapsedMs}ms — over ${Math.round(TIMEOUT_MARGIN * 100)}% of its ${timeoutSec}s timeout (no margin left)` });
+  }
+
+  // 2. EXIT CODE within the declared contract for this mode.
+  if (!measurement.timedOut && mode) {
+    const allowed = ALLOWED_EXITS[mode];
+    if (allowed && measurement.status !== null && !allowed.includes(measurement.status)) {
+      v.push({ kind: 'exit-code', where, regime: measurement.regime, detail: `${tag} exited ${measurement.status}; a '${mode}' hook may only exit ${allowed.join(' or ')}` });
+    }
+  }
+
+  // 3. STDOUT CAP — it lands in the user's context window, so a flood is a real cost, not a nit.
+  if (measurement.stdoutBytes > STDOUT_CAP_BYTES) {
+    v.push({ kind: 'stdout-flood', where, regime: measurement.regime, detail: `${tag} wrote ${measurement.stdoutBytes} bytes to stdout; the cap is ${STDOUT_CAP_BYTES}` });
+  }
+
+  // 4. STDERR POLICY — an advisory hook putting a stack trace on a stranger's screen is a defect
+  //    even though it exits 0. Blocking hooks may explain a refusal on stderr, so they are exempt.
+  if (mode === 'advisory' && /^\s*(?:Error|TypeError|ReferenceError|SyntaxError)\b|^\s+at .+:\d+:\d+/m.test(measurement.stderr)) {
+    v.push({ kind: 'stderr-trace', where, regime: measurement.regime, detail: `${tag} printed what looks like a stack trace on stderr: ${measurement.stderr.trim().split('\n')[0].slice(0, 120)}` });
+  }
+
+  // 5. PROCESS-TREE HYGIENE — zero surviving descendants after SIGTERM. `null` is the honest
+  //    win32 "not measurable"; only an observed `true` is a violation.
+  if (measurement.survivors === true) {
+    v.push({ kind: 'orphan', where, regime: measurement.regime, detail: `${tag} left descendants alive after SIGTERM to its process group` });
+  }
+
+  return v;
+}
+
+// ── §4 THE BATTERY: every installed registration × every stdin regime ───────────────────────────
+export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tmpdir(), regimes = STDIN_REGIMES, surface = null, env = {} } = {}) {
+  const reg = await loadRegistry();
+  const s = surface ?? resolveInstalledSurface({ home, repo });
+  if (!s.ok) return { ok: false, reason: s.reason, violations: [], results: [] };
+
+  // THE AUTHORITIES, read from the INSTALLED tree — not from the repo, and not from a literal here.
+  const table = reg.shimTable(s.root);
+  const { contracts } = reg.loadContracts(s.root);
+
+  const registrations = readInstalledRegistrations(s.hooksFile);
+  const violations = [];
+  const results = [];
+
+  for (const r of registrations) {
+    const command = r.command.replaceAll('${CLAUDE_PLUGIN_ROOT}', s.root);
+    const shimId = reg.shimIdIn(r.command);
+    const entry = shimId ? table[shimId] : null;
+    const contract = entry ? null : contracts.find((c) => reg.contractMatches(c, { layer: 'plugin', event: r.event, matcher: r.matcher, command: r.command }));
+    const mode = entry?.mode ?? contract?.mode ?? null;
+    const handler = entry?.file ?? reg.basenamesIn(r.command).filter((b) => b !== 'hook-shim.mjs').pop() ?? null;
+    const rec = { ...r, handler, shimId, mode };
+
+    // A registration whose timeout is absent cannot be budget-checked honestly — the host default
+    // (600s) applies and that IS the finding. hook-registry's M3 already states it; we surface it
+    // here too because a hook with no timeout is the exact every-prompt-hang class this catches.
+    if (typeof r.timeout !== 'number') {
+      violations.push({ kind: 'no-timeout', where: `${r.event} ${r.matcher || '*'} → ${handler ?? r.command}`, detail: 'registration declares no timeout — the host default (600s) applies to a stranger\'s session' });
+    }
+    if (mode === null) {
+      violations.push({ kind: 'undeclared-mode', where: `${r.event} ${r.matcher || '*'} → ${handler ?? r.command}`, detail: 'neither the shim dispatch table nor hook-contracts.json declares a mode for this registration' });
+    }
+    const timeoutSec = typeof r.timeout === 'number' ? r.timeout : 5;
+
+    for (const regime of regimes) {
+      const measurement = await fireHook({ command, event: r.event, regime, timeoutSec, cwd, env });
+      results.push({ rec, measurement });
+      violations.push(...assertContract({ rec, measurement, mode, timeoutSec }));
+    }
+  }
+  return { ok: true, surface: s, registrations, results, violations };
+}
+
+// ── §5 COEXISTENCE: report the user's own hooks; never execute them ─────────────────────────────
+/**
+ * The user's machine is not ours. This ENUMERATES every other registration a session loads, checks
+ * that our hooks cannot collide with them on a written path, and reuses hook-registry's `lintM1` for
+ * double-registration. Three deliberate refusals:
+ *   • we never EXECUTE a foreign hook (it may bill an API, mutate state, or prompt);
+ *   • we never count a foreign finding as a violation (ADR-055 §6: inventing an offBehavior for
+ *     someone else's hook is fiction, and fiction rots into permission);
+ *   • we never claim their hooks are fine — only that ours do not clash with them.
+ */
+export async function checkCoexistence({ home = os.homedir(), repo = null } = {}) {
+  const reg = await loadRegistry();
+  const registry = reg.buildRegistry({ repo: repo ?? reg.REPO, home, includeMachine: true });
+  const ours = registry.records.filter((r) => r.layer === 'plugin' || r.layer === 'plugin-installed' || r.layer === 'marketplace-clone');
+  const foreign = registry.records.filter((r) => r.layer === 'user' || r.layer.startsWith('third-party:') || r.layer === 'project');
+
+  // DOUBLE REGISTRATION — reused wholesale from hook-registry (ADR-055 M1): one handler, an
+  // overlapping (event, tool), from two different code roots. Only pairs that INCLUDE one of ours
+  // are ours to answer for.
+  const m1 = reg.lintM1(registry.records).filter((f) => f.where.some((w) => /plugin|marketplace-clone|spine/.test(w)));
+
+  // WRITE-PATH COLLISION. Our hooks write under ~/.cache/ruvnet-brain and ~/.config/ruvnet-brain.
+  // A collision means another hook (or Claude Code itself) reads a path we write — which would make
+  // our output someone else's input. Detected by asking whether any FOREIGN command string names a
+  // path inside our write roots.
+  const OUR_WRITE_ROOTS = [
+    path.join(home, '.cache', 'ruvnet-brain'),
+    path.join(home, '.config', 'ruvnet-brain'),
+  ];
+  const collisions = [];
+  for (const f of foreign) {
+    for (const root of OUR_WRITE_ROOTS) {
+      if (f.command.includes(root)) collisions.push({ layer: f.layer, locator: f.locator, root, handler: f.handler });
+    }
+  }
+  return {
+    ourCount: ours.length,
+    foreign: foreign.map((r) => ({ layer: r.layer, locator: r.locator, event: r.event, matcher: r.matcher, handler: r.handler, timeout: r.timeout })),
+    doubleRegistered: m1,
+    collisions,
+    sources: registry.sources.filter((s) => s.present).map((s) => ({ layer: s.layer, file: s.file })),
+  };
+}
+
+// ── §6 SECURITY: rUv's own scanner against the user's own surface ───────────────────────────────
+/**
+ * REUSED, NOT REIMPLEMENTED. `ruflo metaharness mcp-scan` is rUv's shipped static policy/permission
+ * audit of a machine's declared MCP servers (verified locally: subcommand present, ~0.6s, free, no
+ * API key). `threat-model` is its categorized-severity sibling. We run them and REPORT WHAT THEY
+ * SAY. We never synthesize a verdict, and if ruflo is not installed we print one honest
+ * "not available" line and score nothing — a security check that invents a pass is worse than none.
+ */
+export function runSecurityScan({ cwd = process.cwd(), timeoutMs = 20000, env = process.env } = {}) {
+  const probe = spawnSync('ruflo', ['--version'], { encoding: 'utf8', timeout: 5000, env });
+  if (probe.error || probe.status !== 0) {
+    return { available: false, reason: 'ruflo not found on PATH — MCP surface not scanned (install: npm i -g ruflo)' };
+  }
+  const out = {};
+  for (const sub of ['mcp-scan', 'threat-model']) {
+    const r = spawnSync('ruflo', ['metaharness', sub, '--path', cwd], { encoding: 'utf8', timeout: timeoutMs, cwd, env });
+    out[sub] = r.error
+      ? { ran: false, detail: r.error.message }
+      // exit 1 is mcp-scan's INTENTIONAL alert exit (findings at/above --fail-on), not a crash;
+      // exit 2 is a config/input error. Reported verbatim — the caller decides what it means.
+      : { ran: true, exitCode: r.status, stdout: (r.stdout ?? '').trim().slice(0, 4000), stderr: (r.stderr ?? '').trim().slice(0, 1000) };
+  }
+  return { available: true, ...out };
+}
+
+// ── §7 THE VERDICT ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Compose everything into { lines, violations, exitCode }. THIS is the half bin/install.mjs was
+ * missing: a machine-readable verdict. `exitCode` is 0 only when nothing we ship is in violation.
+ */
+export async function selfCheck({ home = os.homedir(), repo = null, cwd = os.tmpdir(), regimes = STDIN_REGIMES, security = true, installState = null } = {}) {
+  const lines = [];
+  const violations = [];
+
+  // (a) INSTALL STATE — the facts bin/install.mjs already gathered and then discarded. Passed in by
+  //     the installer/doctor so there is exactly one gatherer (gatherInstallState) and one judge.
+  if (installState) {
+    if (!(installState.repos > 0)) violations.push({ kind: 'no-stores', where: 'install', detail: 'zero .rvf vector stores on disk — every search will fail' });
+    if (!installState.reader) violations.push({ kind: 'no-reader', where: 'install', detail: 'local reader deps missing — every search will fail' });
+    if (!installState.mcp) violations.push({ kind: 'no-mcp', where: 'install', detail: 'forge-mcp-all.mjs missing — Claude cannot reach the brain' });
+  }
+
+  // (b) THE BATTERY
+  const battery = await runBattery({ home, repo, cwd, regimes });
+  if (!battery.ok) {
+    lines.push(`hooks: ${battery.reason}`);
+    violations.push({ kind: 'no-plugin', where: 'hooks', detail: battery.reason });
+  } else {
+    violations.push(...battery.violations);
+    lines.push(`hooks: ${battery.registrations.length} registrations from ${battery.surface.source}, ${regimes.length} stdin regimes each (${battery.results.length} firings)`);
+  }
+
+  // (c) COEXISTENCE — reported, never charged to the user
+  let coexist = null;
+  try {
+    coexist = await checkCoexistence({ home, repo });
+    lines.push(`coexistence: ${coexist.foreign.length} other hook registrations on this machine (enumerated, not executed)`);
+    for (const d of coexist.doubleRegistered) {
+      violations.push({ kind: 'double-registration', where: d.key, detail: `registered from ${d.roots.length} different code roots: ${d.roots.join(', ')}` });
+    }
+    for (const c of coexist.collisions) {
+      violations.push({ kind: 'path-collision', where: `${c.layer} ${c.locator}`, detail: `another hook references a path inside our write root ${c.root}` });
+    }
+  } catch (e) {
+    lines.push(`coexistence: not determined (${e.message})`);
+  }
+
+  // (d) SECURITY — rUv's scanner, or an honest absence
+  let sec = null;
+  if (security) {
+    sec = runSecurityScan({ cwd: process.cwd() });
+    lines.push(sec.available
+      ? `security: ruflo metaharness mcp-scan exit ${sec['mcp-scan']?.exitCode ?? '?'}, threat-model exit ${sec['threat-model']?.exitCode ?? '?'}`
+      : `security: ${sec.reason}`);
+  }
+
+  return { lines, violations, battery, coexist, security: sec, exitCode: violations.length ? 1 : 0 };
+}
+
+/** One calm line on a healthy machine; the findings, plainly, on a broken one. */
+export function formatVerdict(result, { color = null } = {}) {
+  const c = color ?? { green: (s) => s, yellow: (s) => s, red: (s) => s, dim: (s) => s, bold: (s) => s };
+  const out = [];
+  for (const l of result.lines) out.push(`  ${c.dim(l)}`);
+  if (!result.violations.length) {
+    out.push(`  ${c.green('✓ Self-check passed.')} Every shipped hook answered inside its contract on this machine.`);
+    return out.join('\n');
+  }
+  out.push(`  ${c.red(`✗ Self-check FAILED — ${result.violations.length} contract violation(s):`)}`);
+  for (const v of result.violations) out.push(`    ${c.yellow('•')} ${c.bold(v.kind)} ${v.where}${v.detail ? ` — ${v.detail}` : ''}`);
+  return out.join('\n');
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────────────────────
+if (process.argv[1] && (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })()) {
+  const noSecurity = process.argv.includes('--no-security');
+  const json = process.argv.includes('--json');
+  const result = await selfCheck({ security: !noSecurity });
+  if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else process.stdout.write(`${formatVerdict(result)}\n`);
+  process.exit(result.exitCode);
+}