ruvnet-brain 3.9.134-dev → 4.0.2

package/scripts/signal-watch.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// scripts/signal-watch.mjs — the W2 POLLED half of the external-signal watch plane (ADR-058 §D3;
+// DDD-0013 Context 2, aggregate SignalDebt). A maintainer-only dev tool, same class as
+// scripts/ci-verdict.mjs and scripts/issue-watch.mjs — it is NOT part of the shipped plugin, so it
+// only ever runs in this checkout (this repo's own session-start.sh looks for it by repo-relative
+// path and simply finds nothing on a downloader's machine — see plugin/scripts/session-start.sh).
+//
+// THE FAILURE THIS CLOSES: 2026-07-27, GitHub CI was failing and the OWNER had to tell the model.
+// plugin/scripts/signal-watch.mjs (the PostToolUse observer, the OTHER half — "W1 OBSERVED") opens a
+// pending debt the moment a `git push` succeeds, keyed (repo, sha), appended to pending.jsonl. THIS
+// file resolves that debt via `gh run list` — READ-ONLY VERBS ONLY, never a mutating `gh` command —
+// and writes the result so plugin/scripts/session-start.sh can surface a transition with zero user
+// input. This is 2026-07-27 replayed with the human removed (ADR-058 §D3, mutant M-W1).
+//
+// REUSE, NOT REIMPLEMENTATION (explicit ADR-058 instruction, enforced by this repo's own
+// substitution:check gate): the success/refuse mapping is scripts/ci-verdict.mjs's assessCiGate —
+// the SAME "unknown is red" law the remote-CI ship gate already uses. This file does not carry a
+// second copy of that decision.
+//
+// SINGLE WRITER (DDD-0013 Context 2 invariant 3): this file is the ONLY writer of ci-status.json.
+// plugin/scripts/signal-watch.mjs (the observer) only ever APPENDS to pending.jsonl and never
+// touches ci-status.json — two files, two writers, on purpose (ADR-050's one-poisoned-predicate
+// lesson: channels that share a write path fail together).
+//
+// DEGRADATION LADDER (DDD-0013 Context 2 invariant 1, "UNKNOWN STAYS OPEN"):
+//   no `gh` binary          -> state 'unverifiable', reason names the fix. A typed CAPABILITY state,
+//                              never an error.
+//   `gh` unauthenticated    -> state 'unverifiable', reason names the fix. Same class as above.
+//   API error / rate-limit  -> state stays 'pending' — a transient hiccup, retried next poll. NEVER
+//                              invented as a green resolution (ci-verdict.mjs's law, reused, not
+//                              reimplemented: `assessCiGate(null)` refuses).
+//   no run found yet        -> state stays 'pending' (CI hasn't started; not a failure).
+// Never fakes green, never silently disables (DDD invariant 6) — every non-resolved state is a
+// distinct, named reason, not silence.
+//
+// FIXTURE INJECTION (ADR-058 §D3, mandatory): SIGNAL_WATCH_GH_FIXTURE points at a JSON file standing
+// in for a real `gh run list` call, so CI needs no network and no auth. See
+// tests/fixtures/signal-watch/gh-fixtures/*.json for the shapes:
+//   [ { "conclusion": "success" } ]   — a real `gh run list --json ...` array (first element used)
+//   { "apiError": true }              — simulates a rate-limit / network failure (state stays pending)
+//   { "unauthenticated": true }       — simulates `gh auth login required`
+//   { "notInstalled": true }          — simulates a missing `gh` binary
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { assessCiGate } from './ci-verdict.mjs';
+
+const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
+const SIGNAL_DIR = process.env.RUVNET_SIGNAL_DIR || path.join(BRAIN_HOME, 'external-signals');
+const GH_BIN = process.env.GH_BIN || 'gh';
+const GH_TIMEOUT_MS = 3000; // bounded — this poller may run synchronously inside session-start.sh's 5s hook budget
+
+export function pendingPath() { return process.env.SIGNAL_WATCH_PENDING || path.join(SIGNAL_DIR, 'pending.jsonl'); }
+export function statusPath() { return process.env.SIGNAL_WATCH_STATUS || path.join(SIGNAL_DIR, 'ci-status.json'); }
+
+export function debtKey(source, repo, ref) { return `${source}:${repo}:${ref}`; }
+
+/**
+ * Parse pending.jsonl (append-only event log, written ONLY by the PostToolUse observer) into the
+ * list of open git-push CI-verdict debts. Dedup keeps the LATEST event per (repo, ref) — a debt's
+ * resolution STATE lives entirely in ci-status.json, never here; this only answers "what exists to
+ * check". One malformed line is skipped, never crashes the poller (matches issue-watch.mjs's own
+ * defensiveness against a corrupt state file).
+ */
+export function readPushDebts(path_ = pendingPath()) {
+  let raw;
+  try { raw = fs.readFileSync(path_, 'utf8'); } catch { return []; }
+  const byKey = new Map();
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    let ev;
+    try { ev = JSON.parse(t); } catch { continue; }
+    if (ev && ev.kind === 'git-push' && ev.repo && ev.ref) {
+      byKey.set(debtKey('gh-ci', ev.repo, ev.ref), ev);
+    }
+  }
+  return [...byKey.entries()].map(([key, ev]) => ({ key, repo: ev.repo, ref: ev.ref, ts: ev.ts }));
+}
+
+function loadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return {}; }
+}
+
+function saveJson(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2));
+}
+
+/**
+ * Resolve ONE debt's CI verdict. READ-ONLY `gh` verbs only (`--version`, `run list`) — a
+ * state-changing verb here is the exact boundary violation DDD-0013's anti-corruption section names
+ * ("adapters carry a read-only verb whitelist; a state-changing verb ... is a boundary violation the
+ * mesh lint fails"). Returns { state: 'resolved'|'unverifiable'|'pending', conclusion?, reason?, workflowName? }.
+ */
+export function resolveVerdict({ repo, ref }, { ghBin = GH_BIN, fixturePath = process.env.SIGNAL_WATCH_GH_FIXTURE } = {}) {
+  let runs = null;
+  let capability = null;
+
+  if (fixturePath) {
+    let fixture;
+    try { fixture = JSON.parse(fs.readFileSync(fixturePath, 'utf8')); }
+    catch (e) { return { state: 'pending', reason: `unreadable SIGNAL_WATCH_GH_FIXTURE: ${e.message}` }; }
+    if (fixture && fixture.notInstalled) capability = 'not-installed';
+    else if (fixture && fixture.unauthenticated) capability = 'unauthenticated';
+    else if (fixture && fixture.apiError) runs = null;
+    else runs = Array.isArray(fixture) ? fixture : (fixture.runs || []);
+  } else {
+    let probe;
+    try { probe = spawnSync(ghBin, ['--version'], { encoding: 'utf8', timeout: GH_TIMEOUT_MS }); }
+    catch { probe = { error: { code: 'ENOENT' } }; }
+    if (probe.error && probe.error.code === 'ENOENT') {
+      capability = 'not-installed';
+    } else {
+      // READ-ONLY VERB: `gh run list`. Never anything that mutates (no `gh run rerun`, no `gh pr merge`, etc).
+      const r = spawnSync(ghBin, ['run', 'list', '--commit', ref, '--repo', repo, '--json', 'status,conclusion,workflowName'],
+        { encoding: 'utf8', timeout: GH_TIMEOUT_MS });
+      if (r.status === 0) {
+        try { runs = JSON.parse(r.stdout || '[]'); } catch { runs = null; }
+      } else {
+        const err = String(r.stderr || r.stdout || '');
+        if (/auth login|not logged in|authentication|401|unauthorized/i.test(err)) capability = 'unauthenticated';
+        else runs = null; // API error, rate-limit, offline — stays UNKNOWN, never invented as green
+      }
+    }
+  }
+
+  if (capability === 'not-installed') return { state: 'unverifiable', reason: 'gh not installed — install: brew install gh (or see https://cli.github.com)' };
+  if (capability === 'unauthenticated') return { state: 'unverifiable', reason: 'gh auth login required' };
+  if (!Array.isArray(runs)) return { state: 'pending', reason: 'gh API error or unreachable — verdict UNKNOWN, debt stays open' };
+  if (!runs.length) return { state: 'pending', reason: 'no CI run found yet for this SHA' };
+
+  const run = runs[0];
+  // The SAME unknown-is-red law the remote-CI ship gate uses, reused rather than reimplemented.
+  const gate = assessCiGate(run.conclusion ?? null);
+  if (gate === 'ship') return { state: 'resolved', conclusion: 'success', workflowName: run.workflowName };
+  return { state: 'resolved', conclusion: run.conclusion || 'unknown', workflowName: run.workflowName };
+}
+
+/**
+ * Poll every open, not-yet-resolved debt once and persist the result. Append-only in spirit
+ * (DDD-0013 Context 1 invariant 3, applied here): a debt already 'resolved' is never re-resolved —
+ * closing state is a SurfacingLedger-layer transition (session-start.sh), not a poller re-check.
+ */
+export function pollOnce({ pendingFile = pendingPath(), statusFile = statusPath(), ghBin = GH_BIN, fixturePath = process.env.SIGNAL_WATCH_GH_FIXTURE } = {}) {
+  const debts = readPushDebts(pendingFile);
+  const status = loadJson(statusFile);
+  for (const debt of debts) {
+    const prior = status[debt.key];
+    if (prior && prior.state === 'resolved') continue;
+    const verdict = resolveVerdict({ repo: debt.repo, ref: debt.ref }, { ghBin, fixturePath });
+    status[debt.key] = { ...verdict, repo: debt.repo, ref: debt.ref, checkedAt: new Date().toISOString() };
+  }
+  saveJson(statusFile, status);
+  return status;
+}
+
+function main() {
+  const status = pollOnce({});
+  process.stdout.write(JSON.stringify(status, null, 2) + '\n');
+}
+
+function isMain() {
+  try { return process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href; }
+  catch { return false; }
+}
+
+if (isMain()) main();

package/scripts/stack-sync.mjs

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+// stack-sync.mjs — THE one rule for the RuvNet stack. One global copy. Correct. Provable.
+//
+// WHY THIS EXISTS (found live 2026-07-14, because Stuart noticed an update nag pointing BACKWARDS):
+//
+//   TWO installers were fighting on this machine:
+//     com.stuartkerr.ruflo-autoupdate   nightly 03:30   npm install -g <38 pkgs>, core on @alpha
+//     io.ruv.auto-subscribe             HOURLY          npm install -g <4 pkgs>  on @latest
+//   The moment rUv publishes an alpha ahead of latest — the entire point of an alpha track — the
+//   nightly puts you on alpha and the hourly drags you back down. Every hour. Forever.
+//
+//   Meanwhile ~190 hook invocations across 16 projects call `npx <pkg>@latest` on every Edit, Bash
+//   and prompt. npx runs its OWN private copy from ~/.npm/_npx, which can be badly stale (rvf sat
+//   at 0.1.9 in that cache while the global was 0.2.3). npx does not merely fail to catch drift —
+//   it MANUFACTURES THE ILLUSION OF CURRENCY: every command works, every --version prints the new
+//   number, and the binary the MCP server actually executes quietly rots.
+//
+// THE ROOT CAUSE, stated once: currency is an ORDERING question, not an EQUALITY one.
+// Three separate files compared installed vs latest with `!=`, which fires in EITHER direction:
+//     plugin/scripts/ground-ruvnet.sh              -> advised a DOWNGRADE every prompt (fixed 2.7.2)
+//     ~/.claude/hooks/ruflo-upgrade-awareness.sh   -> same bug, same bad advice
+//     ~/.claude/scripts/ruvnet-auto-subscribe.sh   -> same bug, but it EXECUTES npm install -g
+// `!=` only ever LOOKS right because installed is normally <= latest. Nothing asserted direction.
+//
+// So this file has exactly ONE comparator, and it is the only place ordering is decided.
+// A downgrade is not "policy-forbidden" here — it is STRUCTURALLY UNREACHABLE: the only install
+// gate is isBehind(), and AHEAD is an explicitly allowed, untouched state.
+//
+// GROUNDING (search_ruvnet across 37 repos): rUv ships no machine-wide package updater. His docs
+// present `npm install -g` and `npx` as equally valid with no ruling on which wins — which is
+// exactly where the drift lives. Closest precedent: ruflo/plugins/ruflo-ruvector ADR-0001
+// (ACCEPTED) — pin, verify against a smoke test, bump deliberately. This is OUR operator script
+// honoring that discipline. It is not an rUv product and does not wear rUv's name.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = os.homedir();
+
+// ISSUE #18 (Henrik Pettersen): PREFIX used to be hardcoded to ~/.npm-global. That path is Stuart's
+// own convention, not an npm default — on any machine managing Node via mise/nvm/volta/fnm, npm's
+// real global prefix lives somewhere else entirely (e.g. ~/.local/share/mise/installs/node/24.14.1),
+// so the hardcoded path never existed there and this tool reported "0 packages on your global
+// stack" with the full stack actually installed under the real prefix — reporting health while
+// blind, the exact failure ADR-0013 (Onboarding Console) exists to kill.
+// Fix: ask npm itself where its prefix is, at runtime, and resolve it ONCE at module load (not per
+// call — `npm config get prefix` is a subprocess spawn, not free). Fall back to ~/.npm-global only
+// if npm can't tell us anything usable.
+function resolveNpmPrefix() {
+  const r = spawnSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8', timeout: 10000 });
+  const out = r.status === 0 && r.stdout ? r.stdout.trim() : '';
+  return out || path.join(HOME, '.npm-global');
+}
+
+// npm's on-disk layout for global packages differs by platform: macOS/Linux nest an extra `lib/`
+// segment (<prefix>/lib/node_modules), Windows does not (<prefix>/node_modules). Rather than assume
+// either, prefer whichever actually exists on disk so one code path works on both.
+function resolveGlobalLib(prefix) {
+  const withLib = path.join(prefix, 'lib', 'node_modules');
+  const withoutLib = path.join(prefix, 'node_modules');
+  if (fs.existsSync(withLib)) return withLib;
+  if (fs.existsSync(withoutLib)) return withoutLib;
+  return withLib; // neither exists yet (e.g. a fresh/empty prefix) — keep the more common shape
+}
+
+const PREFIX = resolveNpmPrefix();
+const GLOBAL_LIB = resolveGlobalLib(PREFIX);
+const NPX_CACHE = path.join(HOME, '.npm/_npx');
+const RECEIPT = path.join(HOME, '.cache/ruvnet-brain/stack-sync-receipt.json');
+// ISSUE #22: rUv tools installed through the Claude Code plugin MARKETPLACE (not `npm install -g`)
+// live here, and were invisible to this auditor — so plugin-only users saw a permanently undercounted
+// stack, and any plugin they DID have could never be reported "installed". Claude Code writes the
+// authoritative install list (which plugin, which marketplace, which cached version dir is active) to
+// installed_plugins.json under this dir; we read THAT rather than guessing among the dozens of stale
+// version folders the cache keeps around.
+const PLUGINS_DIR = path.join(HOME, '.claude', 'plugins');
+
+// The tag policy. ONE table — the single source of truth for "what SHOULD be installed".
+// The orchestration core tracks alpha (rUv ships fast: 3.26 -> 3.28 inside one 18-hour window).
+// Everything else tracks latest. Unlisted packages get DEFAULT_TAG.
+export const TAG_POLICY = { ruflo: 'alpha', '@claude-flow/cli': 'alpha' };
+export const DEFAULT_TAG = 'latest';
+
+// Resolve a package's TARGET version to the NEWEST of its candidate tags — the policy tag AND latest —
+// not blindly the policy tag. TAG_POLICY names the tag the orchestration core USUALLY leads on (@alpha,
+// because rUv ships fast). But the reverse happens: on 2026-07-18 the core's @latest was 3.32.7 while
+// its @alpha sat at 3.32.0, so "track @alpha" alone pinned the install 7 releases behind the newest
+// published build — and the nightly reported SUCCESS doing it (installed 3.32.2 read as AHEAD of the
+// 3.32.0 @alpha target, so it correctly refused to downgrade and never chased 3.32.7). Considering both
+// tags and taking the higher version fixes that in EITHER direction: alpha-leads → track alpha;
+// latest-leads → track latest. You are never left behind the newest thing rUv actually published.
+export function pickTargetTag(tags, want, defaultTag = DEFAULT_TAG) {
+  if (!tags) return { tag: null, target: null };
+  const candidates = [...new Set([want, defaultTag])].filter((t) => tags[t]);
+  let tag = null, target = null;
+  for (const t of candidates) {
+    if (target === null || cmpVersion(tags[t], target) > 0) { tag = t; target = tags[t]; }
+  }
+  return { tag, target };
+}
+
+// What counts as "the stack": an explicit allow-list pattern, not a loose scope match, so a stray
+// package can never be swept into a global install by accident.
+export const FAMILY = /^(ruflo|ruvector|ruvector-extensions|ruvi|ruvbot|qudag|flow-nexus|agent-browser|agent-browser-mcp|agentic-flow|agentic-qe|agentic-robotics|agentic-payments|ruv-swarm|@ruvector\/|@claude-flow\/|@metaharness\/|@agentic-robotics\/)/;
+
+// The plugin side of the same allow-list intent (ISSUE #22). Plugin identifiers are marketplace
+// names (`ruflo-core`, `ruvnet-brain`, `cog-beehive-monitor`), NOT npm package names, so FAMILY
+// alone cannot classify them — `ruvnet-brain` and cognitum's plugins never match it. The reliable
+// signal is the MARKETPLACE a plugin came from: these four are rUv/ruvnet marketplaces (verified in
+// ~/.claude/plugins/known_marketplaces.json → ruvnet/ruflo, ruvnet/RuView, stuinfla/ruvnet-brain,
+// cognitum.one). An explicit set, mirroring FAMILY's "allow-list, never a loose scope match" so a
+// stray third-party plugin can never be swept into the RuvNet stack by accident. FAMILY is still
+// applied as a secondary matcher, so a future rUv plugin shipped through a different marketplace is
+// still counted.
+export const PLUGIN_MARKETPLACES = new Set(['ruflo', 'ruview', 'ruvnet-brain', 'cognitum']);
+
+const log = (m) => console.log(m);
+const die = (m) => { console.error(`\n  FAILED: ${m}`); process.exit(1); };
+
+// THE COMPARATOR. The only place ordering is decided anywhere in this system.
+// Prerelease-aware per semver: a prerelease sorts BEFORE its release (3.28.0-alpha.1 < 3.28.0),
+// and numeric identifiers compare numerically — alpha.9 < alpha.10, which a string compare gets
+// backwards, and a string compare is precisely the bug this whole file exists to kill.
+export function cmpVersion(a, b) {
+  const split = (v) => {
+    const [core, pre] = String(v).split('-');
+    return [core.split('.').map((n) => parseInt(n, 10) || 0), pre ? pre.split('.') : null];
+  };
+  const [ac, ap] = split(a);
+  const [bc, bp] = split(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (ac[i] || 0) - (bc[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  if (!ap && !bp) return 0;
+  if (ap && !bp) return -1;
+  if (!ap && bp) return 1;
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    const x = ap[i], y = bp[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
+    if (nx && ny) { const d = parseInt(x, 10) - parseInt(y, 10); if (d) return d < 0 ? -1 : 1; }
+    else if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+export const isBehind = (installed, target) => cmpVersion(installed, target) < 0;
+
+export function installedVersion(pkg, lib = GLOBAL_LIB) {
+  const pj = path.join(lib, pkg, 'package.json');
+  if (!fs.existsSync(pj)) return null;
+  try { return JSON.parse(fs.readFileSync(pj, 'utf8')).version || null; } catch { return null; }
+}
+
+// ISSUE #22 — the version of an installed Claude Code plugin is its plugin.json `version`, read from
+// the exact cached version dir Claude Code marked active (installPath). Injectable exactly like
+// installedVersion(pkg, lib) so it is unit-testable against a temp dir.
+export function pluginVersion(installPath) {
+  const pj = path.join(installPath, '.claude-plugin', 'plugin.json');
+  try { return JSON.parse(fs.readFileSync(pj, 'utf8')).version || null; } catch { return null; }
+}
+
+// ISSUE #22 — scan the Claude Code plugin cache for rUv-family plugins. Source of truth is
+// installed_plugins.json (Claude Code's own record of what is installed, its marketplace, and which
+// cached version dir is active) — NOT a raw walk of the cache, which keeps dozens of stale version
+// folders per plugin. `pluginsDir` is injectable, mirroring the lib=GLOBAL_LIB pattern, so tests can
+// point it at a fixture. Returns the same {name, installed} shape as the npm scan, tagged source:'plugin'.
+export function listInstalledPlugins(pluginsDir = PLUGINS_DIR) {
+  const manifest = path.join(pluginsDir, 'installed_plugins.json');
+  if (!fs.existsSync(manifest)) return [];
+  let data;
+  try { data = JSON.parse(fs.readFileSync(manifest, 'utf8')); } catch { return []; }
+  const plugins = data && typeof data.plugins === 'object' ? data.plugins : {};
+  const out = [];
+  for (const [key, records] of Object.entries(plugins)) {
+    // key = "<plugin>@<marketplace>"; the marketplace is the last @-segment.
+    const at = key.lastIndexOf('@');
+    const name = at > 0 ? key.slice(0, at) : key;
+    const marketplace = at > 0 ? key.slice(at + 1) : '';
+    if (!(PLUGIN_MARKETPLACES.has(marketplace) || FAMILY.test(name))) continue;
+    // A plugin can have several install records (user + per-project scope). Pick the highest readable
+    // version so a stale project-scoped copy can never mask a newer user-scoped one — same "ordering,
+    // not equality" discipline as the rest of this file. Fall back to the manifest's own version field
+    // if the on-disk plugin.json is unreadable, so a present plugin is NEVER reported "not installed".
+    let installed = null;
+    for (const rec of Array.isArray(records) ? records : []) {
+      const v = (rec && rec.installPath ? pluginVersion(rec.installPath) : null)
+        || (rec && rec.version && rec.version !== 'unknown' ? rec.version : null);
+      if (!v) continue;
+      if (installed === null || cmpVersion(v, installed) > 0) installed = v;
+    }
+    out.push({ name, installed, source: 'plugin', marketplace });
+  }
+  return out;
+}
+
+function listInstalled({ lib = GLOBAL_LIB, pluginsDir = PLUGINS_DIR } = {}) {
+  const out = [];
+  const scan = (dir, scope = '') => {
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir)) {
+      if (e.startsWith('.')) continue;
+      if (e.startsWith('@') && !scope) { scan(path.join(dir, e), e + '/'); continue; }
+      const name = scope + e;
+      if (FAMILY.test(name)) out.push({ name, installed: installedVersion(name, lib), source: 'npm-global' });
+    }
+  };
+  scan(lib);
+  // Merge in plugin-sourced tools (ISSUE #22). Dedup by name: a tool present BOTH globally and as a
+  // plugin appears once, and the global-npm copy wins — it is the one classify() can compare against
+  // npm dist-tags. A plugin-only tool is added, so it can never be reported "not installed".
+  const seen = new Set(out.map((r) => r.name));
+  for (const p of listInstalledPlugins(pluginsDir)) {
+    if (seen.has(p.name)) continue;
+    seen.add(p.name);
+    out.push(p);
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function registryTags(pkg) {
+  const r = spawnSync('npm', ['view', pkg, 'dist-tags', '--json'], { encoding: 'utf8', timeout: 30000 });
+  if (r.status !== 0 || !r.stdout) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+// A second copy of a stack package in the npx cache can only ever SHADOW the global one.
+// It is never useful. This is how "two ruflos" happens.
+export function findShadows(npxCache = NPX_CACHE, lib = GLOBAL_LIB) {
+  const shadows = [];
+  if (!fs.existsSync(npxCache)) return shadows;
+  for (const d of fs.readdirSync(npxCache)) {
+    const nm = path.join(npxCache, d, 'node_modules');
+    if (!fs.existsSync(nm)) continue;
+    const scan = (dir, scope = '') => {
+      for (const e of fs.readdirSync(dir)) {
+        if (e.startsWith('.')) continue;
+        if (e.startsWith('@') && !scope) { scan(path.join(dir, e), e + '/'); continue; }
+        const name = scope + e;
+        if (!FAMILY.test(name)) continue;
+        try {
+          const v = JSON.parse(fs.readFileSync(path.join(dir, e, 'package.json'), 'utf8')).version;
+          shadows.push({ name, version: v, dir: path.join(npxCache, d), global: installedVersion(name, lib) });
+        } catch { /* unreadable copy: still a shadow, but we cannot name its version */ }
+      }
+    };
+    try { scan(nm); } catch { /* unreadable cache dir */ }
+  }
+  return shadows;
+}
+
+// Classify installed packages against the registry. Ordering is STILL decided only in cmpVersion/
+// isBehind — this function assigns a state label, it does not compare versions itself except through
+// the single comparator. Extracted so audit() (CLI, may exit) and auditModel() (embedders, never
+// exits) share ONE classification, never two that can drift.
+export function classify(pkgs) {
+  return pkgs.map((p) => {
+    // ISSUE #22 — a Claude Code plugin tracks ITS MARKETPLACE's update cadence, not npm semver. There
+    // is no npm dist-tag oracle for it (querying `npm view <plugin>` would compare against an unrelated
+    // package or 404), so we do not manufacture a drift signal. It is present and installed ⇒ CURRENT;
+    // a plugin is only BROKEN if we could not read any version at all. Either way it is COUNTED and is
+    // never reported "not installed". This also keeps the npm-registry "blind tool" guard scoped to
+    // real npm rows (see audit()/auditModel()).
+    if (p.source === 'plugin') {
+      return { ...p, tag: 'plugin', target: p.installed, state: p.installed ? 'CURRENT' : 'BROKEN' };
+    }
+    const want = TAG_POLICY[p.name] || DEFAULT_TAG;
+    const tags = registryTags(p.name);
+    // Newest of {policy tag, latest} — see pickTargetTag: "track @alpha" alone pinned the core behind
+    // @latest on 2026-07-18. A package with no alpha tag falls through to latest.
+    const { tag, target } = pickTargetTag(tags, want);
+    let state;
+    if (!p.installed) state = 'BROKEN';
+    else if (!target) state = 'UNRESOLVED';
+    else if (isBehind(p.installed, target)) state = 'BEHIND';
+    else if (cmpVersion(p.installed, target) > 0) state = 'AHEAD';
+    else state = 'CURRENT';
+    return { ...p, tag, target, state };
+  });
+}
+
+function audit() {
+  const pkgs = listInstalled();
+  if (!pkgs.length) die(`no stack packages under ${GLOBAL_LIB} — is the npm prefix right?`);
+
+  // A BLIND TOOL MUST NOT REPORT HEALTH. (Adversarial review, 2026-07-14 — a real bug in the first
+  // version of this file.) If the registry is unreachable, EVERY package resolves UNRESOLVED, the
+  // drift count is 0+0+0, and --audit used to print "all current" and exit 0 — a currency claim
+  // that was never measured. That is the exact failure this whole file exists to kill, reproduced
+  // inside the fix for it. Silence is not health.
+  const rows = classify(pkgs);
+  const unresolved = rows.filter((r) => r.state === 'UNRESOLVED');
+  // Guard scoped to npm rows (ISSUE #22): plugin rows are CURRENT by construction, so counting them
+  // here would let a fully-unreachable registry hide behind a couple of installed plugins — the exact
+  // "blind tool reports health" bug this guard exists to kill, reintroduced. Denominator = npm rows.
+  const npmRows = rows.filter((r) => r.source !== 'plugin');
+  if (npmRows.length && unresolved.length === npmRows.length) {
+    die(`could not reach the npm registry for ANY of ${npmRows.length} npm packages.\n` +
+        `   This tool refuses to report on a stack it could not measure. Check the network and re-run.`);
+  }
+
+  const shadows = findShadows();
+  return { rows, unresolved, shadows, stale: shadows.filter((s) => s.global && s.version !== s.global) };
+}
+
+// Non-exiting audit for embedders (the Onboarding Console). Same measurement as audit(), but returns
+// a model with an `error` field instead of calling process.exit — a long-lived server must never be
+// killed by a transient registry blip. Honours the SAME "a blind tool must not report health" rule:
+// if the registry was unreachable for EVERY package, that is surfaced as an error, not as "all current".
+export function auditModel() {
+  const pkgs = listInstalled();
+  if (!pkgs.length) return { error: `no stack packages under ${GLOBAL_LIB}`, rows: [], unresolved: [], shadows: [], stale: [] };
+  const rows = classify(pkgs);
+  const unresolved = rows.filter((r) => r.state === 'UNRESOLVED');
+  const shadows = findShadows();
+  const stale = shadows.filter((s) => s.global && s.version !== s.global);
+  // Same npm-scoped guard as audit() (ISSUE #22): plugin rows never count toward "registry unreachable".
+  const npmRows = rows.filter((r) => r.source !== 'plugin');
+  const error = npmRows.length && unresolved.length === npmRows.length
+    ? `could not reach the npm registry for any of ${npmRows.length} npm packages` : null;
+  return { rows, unresolved, shadows, stale, error };
+}
+
+function report({ rows, shadows, stale }) {
+  const w = Math.max(...rows.map((r) => r.name.length));
+  const nPlugin = rows.filter((r) => r.source === 'plugin').length;
+  const nNpm = rows.length - nPlugin;
+  log(`\n  RuvNet stack — ${rows.length} packages (${nNpm} npm-global, ${nPlugin} Claude Code plugin)\n`);
+  for (const r of rows) {
+    const mark = { CURRENT: '  ok  ', BEHIND: 'BEHIND', AHEAD: ' ahead', BROKEN: 'BROKEN', UNRESOLVED: '  ??  ' }[r.state];
+    const detail = r.state === 'BEHIND' ? `${r.installed} -> ${r.target}  (@${r.tag})`
+      : r.state === 'AHEAD' ? `${r.installed}  (ahead of @${r.tag} ${r.target} — alpha track; left alone)`
+      : r.state === 'BROKEN' ? `no readable version on disk; registry has ${r.target ?? '?'}`
+      : r.source === 'plugin' ? `${r.installed}  (plugin · ${r.marketplace} marketplace)`
+      : r.installed;
+    log(`  [${mark}] ${r.name.padEnd(w)}  ${detail}`);
+  }
+  if (shadows.length) {
+    log(`\n  npx shadow copies:`);
+    for (const s of shadows) {
+      log(`    ${s.name}@${s.version}${s.global && s.version !== s.global ? `   STALE — global is ${s.global}` : ''}`);
+    }
+  }
+  log('');
+  return { behind: rows.filter((r) => r.state === 'BEHIND'), broken: rows.filter((r) => r.state === 'BROKEN'), stale };
+}
+
+function writeReceipt(a, installed, purged) {
+  fs.mkdirSync(path.dirname(RECEIPT), { recursive: true });
+  fs.writeFileSync(RECEIPT, JSON.stringify({
+    at: new Date().toISOString(), installed, purged,
+    packages: a.rows.map((r) => ({ name: r.name, version: r.installed, state: r.state })),
+  }, null, 2));
+}
+
+// EXCLUSIVE LOCK. (Adversarial review, 2026-07-14.) Nothing stopped the nightly job and a manual
+// run (or two Claude Code windows) from both running `npm install -g` on the same package at the
+// same instant. Two concurrent installs interleaving in one node_modules dir is how you get a
+// half-written package — which is almost certainly how @ruvector/edge-net ended up present-but-
+// versionless with an orphaned `sharp` inside it. O_EXCL is atomic; a stale lock from a crashed
+// run is reclaimed after 20 minutes (longer than the npm timeout).
+const LOCK = path.join(HOME, '.cache/ruvnet-brain/stack-sync.lock');
+function acquireLock() {
+  fs.mkdirSync(path.dirname(LOCK), { recursive: true });
+  try {
+    fs.writeFileSync(LOCK, JSON.stringify({ pid: process.pid, at: Date.now() }), { flag: 'wx' });
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    let held = {};
+    try { held = JSON.parse(fs.readFileSync(LOCK, 'utf8')); } catch { /* unparseable = stale */ }
+    const ageMin = (Date.now() - (held.at ?? 0)) / 60000;
+    if (ageMin < 20) {
+      die(`another stack-sync is running (pid ${held.pid}, started ${ageMin.toFixed(1)}m ago).\n` +
+          `   Refusing to run two installers at once — that is how packages get half-written.`);
+    }
+    fs.writeFileSync(LOCK, JSON.stringify({ pid: process.pid, at: Date.now() }));
+  }
+  const release = () => { try { fs.unlinkSync(LOCK); } catch { /* already gone */ } };
+  process.on('exit', release);
+  process.on('SIGINT', () => { release(); process.exit(130); });
+  process.on('SIGTERM', () => { release(); process.exit(143); });
+}
+
+function sync({ dryRun = false } = {}) {
+  if (!dryRun) acquireLock();
+  const a = audit();
+  const { behind, broken, stale } = report(a);
+  const toInstall = [...behind, ...broken.filter((r) => r.target)].map((r) => `${r.name}@${r.target}`);
+
+  if (!toInstall.length && !stale.length) {
+    log('  one copy of everything, all current, no shadows. Nothing to do.');
+    writeReceipt(a, [], []);
+    return;
+  }
+  if (dryRun) {
+    if (toInstall.length) log(`  would install: ${toInstall.join(' ')}`);
+    if (stale.length) log(`  would purge ${stale.length} stale npx shadow(s)`);
+    return;
+  }
+
+  // INSTALL FIRST, PURGE SECOND. (Adversarial review, 2026-07-14.) The first version purged the
+  // shadows before installing — so a failed install left the user with their shadows gone AND the
+  // global not yet fixed: strictly WORSE than when they started, with no way back. A repair step
+  // that can leave you worse off than not running it is not a repair.
+  if (toInstall.length) {
+    log(`  installing: ${toInstall.join(' ')}`);
+    const r = spawnSync('npm', ['install', '-g', '--prefix', PREFIX, ...toInstall],
+      { stdio: 'inherit', timeout: 15 * 60 * 1000 });
+    if (r.status !== 0) die(`npm install -g exited ${r.status}; the stack is NOT synced. Shadows left untouched.`);
+  }
+
+  const purged = [];
+  for (const s of stale) {
+    // Purge the whole npx dir: it is a disposable resolution cache (npm re-creates it on demand),
+    // and a mixed-version dir is exactly how a stale transitive copy survives a targeted delete.
+    try { fs.rmSync(s.dir, { recursive: true, force: true }); purged.push(`${s.name}@${s.version}`); } catch { /* best effort */ }
+  }
+  if (purged.length) log(`  purged ${purged.length} stale shadow(s): ${purged.join(', ')}`);
+
+  // VERIFY AGAINST THE DISK. An installer that trusts its own exit code is a hope, not a guarantee:
+  // the old nightly printed "auto-update finished cleanly" from npm's status alone, which is exactly
+  // how a stack rots while every log line insists it is healthy.
+  const wrong = [];
+  for (const r of [...behind, ...broken]) {
+    if (!r.target) continue;
+    const now = installedVersion(r.name);
+    if (now !== r.target) wrong.push(`${r.name}: expected ${r.target}, disk says ${now ?? 'MISSING'}`);
+  }
+  if (wrong.length) die(`npm reported success but THE DISK DISAGREES:\n   - ${wrong.join('\n   - ')}`);
+
+  writeReceipt(audit(), toInstall, purged);
+  log(`\n  synced ${toInstall.length} package(s); purged ${purged.length} shadow(s); verified against disk.`);
+}
+
+// Importable as a module by the tests; only acts when run as a CLI.
+if (process.argv[1] && path.resolve(process.argv[1]).endsWith('stack-sync.mjs')) {
+  const args = process.argv.slice(2);
+  if (args.includes('--audit')) {
+    const a = audit();
+    const { behind, broken, stale } = report(a);
+    // UNRESOLVED counts as drift, not as health: a package we could not measure is a package we
+    // cannot vouch for. Reporting "current" for something we never checked is the lie this tool exists to stop.
+    const unres = a.unresolved.length;
+    const bad = behind.length + broken.length + stale.length + unres;
+    if (bad) {
+      log(`  DRIFT: ${behind.length} behind, ${broken.length} broken, ${stale.length} stale shadow(s)` +
+          (unres ? `, ${unres} UNMEASURED (registry unreachable)` : '') + '.');
+      log(`  Fix:   node scripts/stack-sync.mjs --sync\n`);
+      process.exit(1); // non-zero: a watchdog must never call a drifted stack "green"
+    }
+    log('  one copy of everything, all current, no shadows.\n');
+  } else if (args.includes('--sync')) {
+    sync({ dryRun: args.includes('--dry-run') });
+  } else {
+    log(`
+  stack-sync — one global copy of the RuvNet stack. Correct. Provable.
+
+    --audit     report drift; exit 1 if anything is behind, broken, or shadowed
+    --sync      install what is BEHIND (never downgrades), purge npx shadows, verify against disk
+    --dry-run   with --sync: say what it would do, change nothing
+
+  Tag policy: ${JSON.stringify(TAG_POLICY)}; everything else @${DEFAULT_TAG}
+  Receipt:    ${RECEIPT}
+`);
+  }
+}