ruvnet-brain 2.5.1 → 2.5.2

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 2.5.1 — updated 2026-07-12 21:11 EDT](https://img.shields.io/badge/version_2.5.1-updated_2026--07--12_21:11_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 2.5.2 — updated 2026-07-12 21:11 EDT](https://img.shields.io/badge/version_2.5.2-updated_2026--07--12_21:11_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "One-command installer for RuvNet Brain \u2014 a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -42,7 +42,12 @@
     "scripts/route-cheap.mjs",
     "scripts/dispatch-receipt.mjs",
     "scripts/metaharness-receipts.mjs",
-    "scripts/codex-routed.sh"
+    "scripts/codex-routed.sh",
+    "scripts/metaharness-router.mjs",
+    "scripts/no-silent-substitution.mjs",
+    "scripts/falsify.mjs",
+    "scripts/nightly-watchdog.mjs",
+    "scripts/job-heartbeat.sh"
   ],
   "engines": {
     "node": ">=18"

package/scripts/falsify.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// scripts/falsify.mjs — THE ADVERSARY. Ask the questions Stuart has to keep asking me.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHY (2026-07-13). Stuart: "Why the fuck do you still keep needing me to call you on these things?
+// Ru would not miss stuff like this. You are supposed to be acting like Ru."
+//
+// He is right, and the defect is mechanical, not motivational:
+//
+//     I VERIFY WHAT I BUILT. I DO NOT VERIFY WHETHER IT SHOULD EXIST.
+//
+// Tests I wrote passing is circular evidence — I wrote them to pass. Every miss tonight has that
+// shape: the router worked (but rUv already shipped one); the jobs were "watched" (but nothing checked
+// they ran); the gong was "complete" (but it never covered liveness). In each case my own artifacts
+// said green, and the only thing that said otherwise was Stuart.
+//
+// Look at how rUv actually writes: every ADR carries an "Honest guardrail" and a measured number, and
+// ADR-043 literally reports a TIE against the baseline rather than dressing it as a win. He starts from
+// "this is probably wrong" and hunts for the thing that would prove it. I start from "this works."
+//
+// So this file is the missing step: BEFORE declaring done, run the questions an adversary would ask.
+// Not a linter for code — a linter for CLAIMS.
+//
+// Usage:  node scripts/falsify.mjs            # run every check; exit 1 if any claim is unproven
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const sh = (cmd, args) => spawnSync(cmd, args, { cwd: ROOT, encoding: 'utf8' });
+
+/**
+ * Each check is a question Stuart had to ask me, turned into code so he never has to ask it again.
+ * A check FAILS when the claim is unproven — not when the code is broken. That distinction is the
+ * whole point: "it works" and "it should exist / it actually ran / it is really rUv's" are different
+ * claims, and only the first one had any gate on it.
+ */
+export const CHECKS = [
+  {
+    id: 'am-i-impersonating-ruv',
+    asked: '"You wrote a bunch of code and told me it\'s Ruv\'s code?"',
+    why: 'I hand-rolled a router and called it MetaHarness while @metaharness/router sat on npm.',
+    run: () => {
+      const r = sh('node', ['scripts/no-silent-substitution.mjs']);
+      return { ok: r.status === 0, detail: r.status === 0 ? 'no local code wears a rUv tool\'s name' : r.stderr.trim().split('\n').slice(-2).join(' ') };
+    },
+  },
+  {
+    id: 'did-the-jobs-actually-run',
+    asked: '"Is the nightly actually running, or are you just telling me it is?"',
+    why: 'launchd reports exit 0 for a job that NEVER RAN. Silence was being read as health.',
+    run: () => {
+      const r = sh('node', ['scripts/nightly-watchdog.mjs', '--json']);
+      try {
+        const { results } = JSON.parse(r.stdout);
+        const bad = results.filter((x) => x.state !== 'OK');
+        return { ok: bad.length === 0, detail: bad.length ? `${bad.length} job(s) unproven: ${bad.map((b) => `${b.label}=${b.state}`).join(', ')}` : `all ${results.length} jobs produced a fresh successful receipt` };
+      } catch { return { ok: false, detail: 'watchdog produced no readable verdict — that is itself a failure' }; }
+    },
+  },
+  {
+    id: 'is-the-router-actually-routing',
+    asked: '"Why am I still burning my Fable/Opus quota if the router exists?"',
+    why: 'The router\'s entire lifetime output was 3 test pings and $0.018 — because the rule was advisory.',
+    run: () => {
+      const f = path.join(process.env.HOME, '.claude', 'metaharness', 'routing-receipts.jsonl');
+      let rows = [];
+      try { rows = fs.readFileSync(f, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l)); } catch { /* none */ }
+      const subagent = rows.filter((r) => r.source === 'claude-subagent');
+      const saved = rows.reduce((s, r) => s + (r.saved || 0), 0);
+      // The honest bar: routing must be VISIBLY happening, not merely possible.
+      return {
+        ok: subagent.length > 0,
+        detail: subagent.length
+          ? `${rows.length} routed task(s), ${subagent.length} subagent, est. $${saved.toFixed(2)} saved`
+          : 'ZERO subagent dispatches routed — the router is decorative again',
+      };
+    },
+  },
+  {
+    id: 'does-the-repo-ship-what-it-claims',
+    asked: '"Are people actually getting the current version?"',
+    why: 'Version drift across surfaces is a visible, credibility-destroying mistake.',
+    run: () => {
+      const r = sh('node', ['scripts/sync-version.mjs', '--check']);
+      return { ok: r.status === 0, detail: (r.stdout + r.stderr).trim().split('\n').pop() };
+    },
+  },
+  {
+    id: 'does-the-package-ship-what-it-promises',
+    asked: '"Are users actually GETTING the thing you told them shipped?"',
+    why: 'v2.5.1 headline was "it uses rUv\'s real router" — and scripts/metaharness-router.mjs was NOT in the npm tarball. The dependency shipped; the code that calls it did not. Every gate was green and this adversary itself missed it, because it only ever checked whether the REPO was honest — never whether the ARTIFACT USERS RECEIVE contains what the README promises.',
+    run: () => {
+      // The npm `files` whitelist is opt-IN, so a NEW file is invisible to users unless someone
+      // remembers to list it. A shipped script that relative-imports an UNSHIPPED one is broken for
+      // every user while working perfectly in the repo — green CI, green tests, broken product.
+      //
+      // My FIRST version of this check derived the file list from bin/install.mjs and therefore did
+      // NOT catch metaharness-router.mjs — the very bug it was written for. It reported ✅ on the
+      // broken state. A check that passes on the bug it was written for is worse than no check, so:
+      // follow the ACTUAL relative imports of every shipped file, transitively.
+      const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+      const shipped = new Set(pkg.files || []);
+      const covered = (f) => shipped.has(f) || [...shipped].some((s) => s.endsWith('/') && f.startsWith(s));
+
+      const seeds = [...shipped].filter((f) => f.endsWith('.mjs') && fs.existsSync(path.join(ROOT, f)));
+      const missing = new Set();
+      const seen = new Set();
+      const walkImports = (rel) => {
+        if (seen.has(rel)) return;
+        seen.add(rel);
+        let src;
+        try { src = fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return; }
+        for (const m of src.matchAll(/(?:from|import)\s*\(?\s*['"](\.[^'"]+)['"]/g)) {
+          const dep = path.posix.normalize(path.posix.join(path.posix.dirname(rel), m[1]));
+          if (!fs.existsSync(path.join(ROOT, dep))) continue; // not a real file (or an npm pkg) — skip
+          if (!covered(dep)) missing.add(`${dep} (imported by ${rel})`);
+          walkImports(dep);
+        }
+      };
+      seeds.forEach(walkImports);
+
+      return {
+        ok: missing.size === 0,
+        detail: missing.size
+          ? `${missing.size} file(s) are IMPORTED BY SHIPPED CODE but are NOT in the npm package — the feature is broken for every user: ${[...missing].join('; ')}`
+          : `every file imported by shipped code is itself shipped (${seen.size} files reachable from ${shipped.size} whitelist entries)`,
+      };
+    },
+  },
+  {
+    id: 'does-the-engine-really-use-ruvs-router',
+    asked: '"Is the router users actually RUN really rUv\'s, or still your hand-roll?"',
+    why: 'v2.5 shipped with the wrapper written, tested, and CI-gated — while model-router-engine.mjs, the file that actually executes, never imported it. An honest artifact sitting next to a lying claim is still a lie.',
+    run: () => {
+      const engine = fs.readFileSync(path.join(ROOT, 'scripts/model-router-engine.mjs'), 'utf8');
+      const wired = /metaharness-router\.mjs/.test(engine);
+      const declares = /routedBy/.test(engine); // and it must SAY who decided, every time
+      return {
+        ok: wired && declares,
+        detail: wired && declares
+          ? 'the engine consults @metaharness/router first and reports routedBy on every decision'
+          : `the ENGINE USERS RUN does not ${!wired ? 'import rUv\'s router' : 'declare who decided'} — the README\'s claim is false`,
+      };
+    },
+  },
+  {
+    id: 'is-ci-actually-green',
+    asked: '"Why am I getting failure notifications from GitHub?"',
+    why: 'I declared green from LOCAL gates while CI had never passed — 25 straight failures.',
+    run: () => {
+      const r = sh('gh', ['run', 'list', '--workflow', 'ci.yml', '--limit', '1', '--json', 'conclusion,status']);
+      try {
+        const [run] = JSON.parse(r.stdout);
+        if (!run) return { ok: false, detail: 'could not read CI status — do not claim green' };
+        if (run.status !== 'completed') return { ok: false, detail: `CI is still ${run.status} — "pending" is not "green"` };
+        return { ok: run.conclusion === 'success', detail: `latest ci run: ${run.conclusion}` };
+      } catch { return { ok: false, detail: 'gh unavailable — CI state UNKNOWN, which is not the same as green' }; }
+    },
+  },
+];
+
+export function runAll(checks = CHECKS) {
+  return checks.map((c) => ({ ...c, ...c.run() }));
+}
+
+function main() {
+  console.log('falsify — the questions Stuart should not have to keep asking\n');
+  const results = runAll();
+  for (const r of results) {
+    console.log(`${r.ok ? '✅' : '❌'} ${r.asked}`);
+    console.log(`   ${r.detail}`);
+    if (!r.ok) console.log(`   why this check exists: ${r.why}`);
+    console.log('');
+  }
+  const failed = results.filter((r) => !r.ok);
+  if (failed.length) {
+    console.error(`${failed.length} claim(s) UNPROVEN. Do not report success. Fix or say plainly what is not verified.`);
+    process.exit(1);
+  }
+  console.log('Every claim above is proven by something other than my own opinion.');
+  process.exit(0);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) main();

package/scripts/job-heartbeat.sh

@@ -0,0 +1,77 @@
+#!/bin/sh
+# job-heartbeat.sh — wrap a scheduled job so it CANNOT run without leaving proof, and CANNOT fail quietly.
+#
+# WHY (2026-07-13): every scheduled job on this machine was trusted to report on itself, and they
+# didn't. launchd's own exit status is useless as proof — a job that has NEVER RUN reports exit 0,
+# identical to one that ran and succeeded. That ambiguity let com.ruvnet.brain-nightly sit unfired
+# and look healthy. Per-job good intentions rot; a wrapper cannot forget.
+#
+# Usage (from a LaunchAgent's ProgramArguments):
+#   /bin/sh /path/to/job-heartbeat.sh <label> -- <command> [args...]
+#
+# Guarantees:
+#   1. A "start" receipt is written BEFORE the command runs.
+#   2. An "end" receipt with the REAL exit code is written even if the command dies, is killed, or
+#      the machine yanks it away — the trap fires on EXIT/INT/TERM. There is no silent death.
+#   3. A non-zero exit pushes an URGENT ntfy alert immediately (topic: $NTFY_TOPIC, or the file
+#      ~/.cache/ruvnet-brain/ntfy-topic). No topic = no push, but the receipt is still written.
+#   4. The wrapper's own exit code is the job's exit code — launchd still sees the truth.
+
+set -u
+
+LABEL="${1:?usage: job-heartbeat.sh <label> -- <command...>}"
+shift
+[ "${1:-}" = "--" ] && shift
+[ $# -gt 0 ] || { echo "job-heartbeat: no command given for $LABEL" >&2; exit 2; }
+
+HB_DIR="${JOB_HEARTBEAT_DIR:-$HOME/.cache/ruvnet-brain/heartbeats}"
+mkdir -p "$HB_DIR"
+HB="$HB_DIR/$LABEL.json"
+
+ts() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+STARTED="$(ts)"
+START_EPOCH="$(date +%s)"
+
+# Start receipt. If the job vanishes without ever writing an end receipt, THIS is the evidence that
+# it started and never finished — a state the watchdog reports as FAILING, not as silence.
+cat > "$HB" <<EOF
+{"label":"$LABEL","started_at":"$STARTED","state":"running","pid":$$,"command":"$(echo "$@" | sed 's/"/\\"/g')"}
+EOF
+
+notify() { # notify <title> <body> <priority>
+  topic="${NTFY_TOPIC:-}"
+  [ -z "$topic" ] && [ -f "$HOME/.cache/ruvnet-brain/ntfy-topic" ] && topic="$(cat "$HOME/.cache/ruvnet-brain/ntfy-topic")"
+  [ -z "$topic" ] && return 0
+  curl -sS -m 10 -H "Title: $1" -H "Priority: $3" -H "Tags: rotating_light" -d "$2" "https://ntfy.sh/$topic" >/dev/null 2>&1 || true
+}
+
+finish() {
+  code=${FORCED_CODE:-$?}
+  ended="$(ts)"
+  dur=$(( $(date +%s) - START_EPOCH ))
+  if [ "$code" -eq 0 ]; then state="ok"; else state="failed"; fi
+  cat > "$HB" <<EOF
+{"label":"$LABEL","started_at":"$STARTED","ended_at":"$ended","state":"$state","exit_code":$code,"duration_sec":$dur}
+EOF
+  # Gong on failure, immediately — not at the next watchdog sweep. A failing nightly should reach the
+  # phone while it is still tonight's problem.
+  if [ "$code" -ne 0 ]; then
+    notify "🔴 SCHEDULED JOB FAILED: $LABEL" "exit $code after ${dur}s — see the job's log. Receipt: $HB" "urgent"
+  fi
+  exit "$code"
+}
+trap finish EXIT
+# A signal handler must KILL THE CHILD, then exit — letting the EXIT trap write the receipt once.
+trap 'FORCED_CODE=143; kill -TERM "$CHILD" 2>/dev/null; exit 143' TERM
+trap 'FORCED_CODE=130; kill -TERM "$CHILD" 2>/dev/null; exit 130' INT
+
+# Run the job in the BACKGROUND and `wait` for it — do NOT run it in the foreground.
+# Break-test finding (2026-07-13): a POSIX shell blocked on a FOREGROUND child does not run its trap
+# when signalled — it dies with the receipt still saying "running", which is precisely the silent
+# death this wrapper exists to prevent. `wait` is interruptible, so the trap fires immediately.
+# The one death nothing can catch is SIGKILL (-9) / power loss, by definition: no handler runs. That
+# case is caught one level up — nightly-watchdog.mjs reports a receipt stuck in "running" as FAILING
+# ("started and never finished"). Trap for catchable deaths, watchdog for uncatchable ones.
+"$@" &
+CHILD=$!
+wait "$CHILD"

package/scripts/metaharness-router.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// scripts/metaharness-router.mjs — routing through rUv's REAL router: @metaharness/router.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHY THIS FILE EXISTS (2026-07-13). I hand-rolled scripts/model-router-engine.mjs — 216 lines of my
+// own heuristic with a "documented placeholder policy" — and called it "the MetaHarness router
+// engine" in SKILL.md. rUv had ALREADY built and shipped the real thing:
+//
+//   @metaharness/router@0.3.2  (ruvnet/agent-harness-generator, packages/router)
+//   ADR-040 (DRACO Phase-2) + ADR-043 (KRR training pipeline) — status ACCEPTED / IMPLEMENTED.
+//   "Cost-optimal model router — route each query to the cheapest model that's good enough
+//    (k-NN over labelled embeddings). The productized DRACO Phase-2 finding."
+//
+// Building a Claude fake and giving it rUv's name is the single behaviour the brain's own playbook
+// forbids ("NEVER quietly build a Claude fake, call it by the real tool's name, and hide that it's a
+// hand-roll"). This file is the correction: the ROUTING DECISION now comes from rUv's code.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+//
+// WHAT COMPOSES, AND WHY IT IS NOT DUPLICATE WORK.
+// @metaharness/router minimises COST subject to predicted QUALITY. It has no concept of "this model
+// is already paid for by THIS user's subscription" — nor should it; that is deployment truth, not
+// routing math. So the local piece collapses to exactly one honest job: a PRICE TRANSFORM.
+//
+//     a model covered by this user's subscription  →  costPerMTok = 0
+//
+// Feed that price table to Router.fromExamples() and its cost-optimal logic does the rest, natively:
+// a $0 model that clears the quality bar IS the cheapest candidate. The subscription overlay stops
+// being a competing engine and becomes four lines of price arithmetic. That is the whole fix.
+//
+// THE HONEST CONSTRAINT (stated, not buried): Router predicts quality by k-NN over LABELLED examples
+// (query embedding → the quality that candidate achieved). Those labels come from real routed
+// outcomes. Until enough accumulate, k-NN has nothing to average and its prediction is not
+// meaningful — the ADR-040/043 learning curve starts at the bottom. So:
+//   • labels < MIN_LABELS  → we say COLD-START out loud and fall back, rather than dressing up a
+//                            guess as a learned prediction. That dressing-up is the original sin.
+//   • labels >= MIN_LABELS → rUv's Router makes the call, and we report predictedQuality/metBar.
+// Every routed task appends a label, so this improves with use rather than with my opinions.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// k-NN needs neighbours to average. Below this, a "prediction" is noise wearing a lab coat.
+export const MIN_LABELS = 5;
+
+export const OUTCOMES = process.env.MODEL_ROUTER_DECISIONS
+  || path.join(os.homedir(), '.claude', 'metaharness', 'routing-outcomes.jsonl');
+
+/** Load rUv's router. Returns null (never a fake) if the real package isn't installed. */
+export async function loadRealRouter() {
+  try {
+    return await import('@metaharness/router');
+  } catch {
+    return null; // caller MUST say so out loud — never silently substitute a hand-roll
+  }
+}
+
+/**
+ * Effective price table for THIS user. The ONLY thing the local layer legitimately contributes:
+ * a model the user's subscription already pays for costs $0 at the margin, so the cost-optimal
+ * router should treat it as free. Everything else keeps its real blended price.
+ */
+export function effectivePrices(candidates, profile) {
+  const prices = {};
+  for (const c of candidates) {
+    const covered = (c.subscription || []).some((h) => profile?.harnesses?.[h]?.subscription === true);
+    const blended = typeof c.costPerMTok === 'number'
+      ? c.costPerMTok
+      : ((c.costIn ?? 0) + (c.costOut ?? 0)) / 2; // blended $/Mtok — the axis Router minimises
+    prices[c.id] = covered ? 0 : blended;
+  }
+  return prices;
+}
+
+/**
+ * Labelled rows in the exact shape Router.fromExamples() consumes — the DRACO row shape:
+ *   { embedding: number[], scores: { [modelId]: quality 0..1 } }
+ * Rows without an embedding are unusable for k-NN and are dropped (counted, never faked).
+ */
+export function loadLabelledRows(file = OUTCOMES) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { rows: [], unusable: 0 }; }
+  const rows = [];
+  let unusable = 0;
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      if (Array.isArray(o.embedding) && o.embedding.length && o.scores && Object.keys(o.scores).length) {
+        rows.push({ embedding: o.embedding, scores: o.scores });
+      } else unusable++;
+    } catch { unusable++; }
+  }
+  return { rows, unusable };
+}
+
+/** Embed a prompt with the same pinned local MiniLM-384 the brain uses. No network, no API cost. */
+export async function embed(text) {
+  const { pipeline, env } = await import(path.join(__dirname, '..', 'kb', 'node_modules', '@xenova', 'transformers', 'src', 'transformers.js'));
+  if (process.env.KB_MODEL_CACHE) { env.cacheDir = process.env.KB_MODEL_CACHE; env.allowRemoteModels = true; }
+  const fe = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
+    quantized: true,
+    revision: '751bff37182d3f1213fa05d7196b954e230abad9', // pinned — same weights the KB was built with
+  });
+  const out = await fe(text, { pooling: 'mean', normalize: true });
+  return Array.from(out.data);
+}
+
+/**
+ * THE ROUTE CALL. rUv's Router makes the decision; we supply candidates, this user's prices, and the
+ * query embedding. We report exactly what it decided — including when it could NOT decide.
+ */
+export async function route(prompt, candidates, profile, { qualityBar = 0.7, k = 5 } = {}) {
+  const mod = await loadRealRouter();
+  if (!mod) {
+    return { routedBy: 'UNAVAILABLE', reason: '@metaharness/router is not installed — install it rather than hand-rolling a substitute (npm i -g @metaharness/router)' };
+  }
+
+  const { rows, unusable } = loadLabelledRows();
+  if (rows.length < MIN_LABELS) {
+    // Say it plainly. A k-NN with 1 neighbour is not a learned prediction, and pretending otherwise
+    // is precisely the failure this whole file exists to correct.
+    return {
+      routedBy: 'COLD-START',
+      labels: rows.length,
+      needed: MIN_LABELS,
+      unusable,
+      reason: `only ${rows.length} labelled example(s); @metaharness/router needs ≥${MIN_LABELS} to predict quality by k-NN. Falling back to the local heuristic — and SAYING SO. Every routed task appends a label; this stops being a fallback with use, not with opinions.`,
+    };
+  }
+
+  const prices = effectivePrices(candidates, profile);
+  const router = mod.Router.fromExamples(rows, prices, { k, qualityBar });
+  const pick = router.route(await embed(prompt));
+
+  return {
+    routedBy: '@metaharness/router',   // rUv's code made this call. Not mine.
+    version: '0.3.2',
+    model: pick.id,
+    predictedQuality: pick.predictedQuality,
+    metBar: pick.metBar,
+    costPerMTok: pick.costPerMTok,
+    subscriptionCovered: prices[pick.id] === 0,
+    labels: rows.length,
+    qualityBar,
+  };
+}
+
+/** Append a label from a real routed outcome — the fuel k-NN runs on. */
+export async function recordOutcome(prompt, scores, file = OUTCOMES) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const row = { ts: new Date().toISOString(), embedding: await embed(prompt), scores };
+  fs.appendFileSync(file, JSON.stringify(row) + '\n');
+  return row;
+}

package/scripts/model-router-engine.mjs

@@ -171,14 +171,44 @@ async function main() {
   const policy = await loadPolicy(args.policy);
   const features = extractFeatures(prompt, harness);
 
+  // ── rUv's REAL router gets FIRST REFUSAL. ────────────────────────────────────────────────────────
+  // 2026-07-13: this is the fix for a lie I shipped. v2.5's headline was "it uses @metaharness/router",
+  // I wrote the wrapper, tested it, gated CI against faking — and NEVER WIRED IT INTO THIS FILE. The
+  // engine users actually run stayed 100% hand-rolled while the README said otherwise. An honest
+  // artifact sitting next to a lying claim is still a lie. The decision now comes from rUv's code
+  // whenever it CAN decide, and the local heuristic is a fallback that must ANNOUNCE ITSELF.
   let decision;
-  if (!policy) {
-    // No policy at all: pick cheapest priced candidate for the harness as a safe floor, and SAY SO.
-    const pool = candidates.filter((m) => (m.harness || []).includes(harness));
-    const pick = pool.slice().sort((x, y) => (x.costPerMTok?.out ?? Infinity) - (y.costPerMTok?.out ?? Infinity))[0] || candidates[0];
-    decision = { model: pick?.id ?? null, provider: pick?.provider ?? null, tier: pick?.tier ?? null, reason: 'NO POLICY FOUND — fell back to cheapest priced candidate for the harness', confidence: 0 };
-  } else {
-    decision = policy.choose({ features, candidates, harness });
+  let routedBy;
+  const pool = candidates.filter((m) => (m.harness || []).includes(harness));
+  try {
+    const mh = await import('./metaharness-router.mjs');
+    const r = await mh.route(prompt, pool.length ? pool : candidates, profile);
+    if (r.routedBy === '@metaharness/router') {
+      const pick = candidates.find((m) => m.id === r.model);
+      decision = {
+        model: r.model,
+        provider: pick?.provider ?? null,
+        tier: pick?.tier ?? null,
+        reason: `@metaharness/router (rUv's learned cost-optimal router): predicted quality ${r.predictedQuality?.toFixed(2)}, ${r.metBar ? 'clears' : 'BELOW'} the bar, ${r.subscriptionCovered ? '$0 (your subscription)' : `$${r.costPerMTok}/Mtok`}, from ${r.labels} labelled example(s)`,
+        confidence: r.predictedQuality ?? 0,
+      };
+      routedBy = '@metaharness/router';
+    } else {
+      // COLD-START or the package is absent. Say which, out loud — never pass the fallback off as the
+      // learned router. That substitution is the entire sin this wiring exists to end.
+      routedBy = `local-heuristic (${r.routedBy}: ${r.reason})`;
+    }
+  } catch (e) {
+    routedBy = `local-heuristic (@metaharness/router unavailable: ${e.message})`;
+  }
+
+  if (!decision) {
+    if (!policy) {
+      const pick = pool.slice().sort((x, y) => (x.costPerMTok?.out ?? Infinity) - (y.costPerMTok?.out ?? Infinity))[0] || candidates[0];
+      decision = { model: pick?.id ?? null, provider: pick?.provider ?? null, tier: pick?.tier ?? null, reason: 'NO POLICY FOUND — fell back to cheapest priced candidate for the harness', confidence: 0 };
+    } else {
+      decision = policy.choose({ features, candidates, harness });
+    }
   }
 
   const chosen = candidates.find((m) => m.id === decision.model) || null;
@@ -190,6 +220,8 @@ async function main() {
     tier: decision.tier,
     reason: decision.reason,
     confidence: decision.confidence,
+    // WHO decided. Never let a caller assume the learned router made a call the heuristic made.
+    routedBy,
     policy_source: policy ? policy.source.replace(os.homedir(), '~') : 'none',
     profile: profile ? PROFILE_PATH.replace(os.homedir(), '~') : 'none (catalog taken as-is — run model-router-setup.mjs)',
     price_verified: chosen ? chosen.verified : null,

package/scripts/nightly-watchdog.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// scripts/nightly-watchdog.mjs — WHO WATCHES THE WATCHERS.
+//
+// WHY THIS EXISTS (2026-07-13). Stuart: "Every time I ask you, you tell me one thing, and then three
+// days later you're like, 'oh by the way, it hasn't been running for three days.'" He was describing a
+// real structural hole. The audit that night found com.ruvnet.brain-nightly's launchd trigger had NEVER
+// fired — and everything reported healthy, because:
+//
+//   THE TRAP: launchd reports LAST EXIT STATUS 0 for a job that has NEVER RUN. That is byte-identical
+//   to a job that ran and succeeded. So "check the exit code" — the obvious design, and the one that was
+//   in place — literally cannot distinguish triumph from total absence. Silence read as health.
+//
+// THE FIX, and the rule the whole file is built on: EVIDENCE OR IT DIDN'T HAPPEN. Every watched job is
+// declared in config/scheduled-jobs.json and must produce a timestamped receipt (written by
+// scripts/job-heartbeat.sh, trap-protected so a dying job still writes one). Reality is then compared
+// against the registry. Anything less than fresh, successful, positive proof is a VIOLATION:
+//
+//   MISSING   — declared in the registry but not loaded in launchd (it can never fire; this is how
+//               com.ruvnet.issue4-verify sat dead on disk, invisible)
+//   NEVER-RAN — loaded, but no receipt has EVER been written (the brain-nightly case)
+//   STALE     — a receipt exists but is older than the job's schedule allows (it stopped)
+//   FAILING   — it ran and reported a non-zero exit, or it started and never finished
+//   OK        — a fresh receipt says it ran and exited 0. The ONLY state that counts as working.
+//
+// Shape confirmed against prior art in the ecosystem: agentic-qe/src/workers/workers/heartbeat-scheduler.ts
+// (token-free periodic liveness + stale detection). No launchd supervision existed to reuse.
+//
+// Alerts are TRANSITION-ONLY (the discipline proven in kb/brain-alarm.mjs): a state change pages once.
+// Constant redness must never become constant noise, or the gong trains you to ignore it.
+//
+// Usage:
+//   node scripts/nightly-watchdog.mjs           # verdict + exit 1 if ANY job is not OK
+//   node scripts/nightly-watchdog.mjs --json
+//   node scripts/nightly-watchdog.mjs --quiet   # cron mode: speak only when something is wrong
+
+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';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REGISTRY = process.env.WATCHDOG_REGISTRY || path.join(ROOT, 'config', 'scheduled-jobs.json');
+const STATE = process.env.WATCHDOG_STATE || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'watchdog-state.json');
+const HB_DIR = process.env.JOB_HEARTBEAT_DIR || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'heartbeats');
+const HOUR = 3600_000;
+
+export const OK = 'OK';
+export const MISSING = 'MISSING';
+export const NEVER_RAN = 'NEVER-RAN';
+export const STALE = 'STALE';
+export const FAILING = 'FAILING';
+
+/** Labels currently loaded in launchd. A job that isn't here CANNOT fire, whatever its plist says. */
+export function loadedLabels(run = () => spawnSync('launchctl', ['list'], { encoding: 'utf8' }).stdout || '') {
+  return new Set(
+    run()
+      .split('\n')
+      .slice(1)
+      .map((l) => l.trim().split(/\s+/)[2])
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Judge one job from its receipt. `hb === null` means NO RECEIPT EXISTS — which is NEVER-RAN, never OK.
+ * This single line is the whole lesson of 2026-07-13: absence of evidence is not evidence of health.
+ */
+export function judge(job, hb, loaded, now) {
+  if (!loaded) {
+    return { state: MISSING, detail: 'declared in the registry but NOT LOADED in launchd — it can never fire' };
+  }
+  if (!hb) {
+    return { state: NEVER_RAN, detail: 'no run has EVER been recorded — the schedule has not fired once' };
+  }
+  const stamp = new Date(hb.ended_at || hb.started_at);
+  if (Number.isNaN(stamp.getTime())) {
+    return { state: FAILING, detail: 'receipt exists but its timestamp is unreadable' };
+  }
+  const ageHours = (now - stamp) / HOUR;
+
+  // Started and never finished: the receipt is stuck in "running". Either it hung or it was killed
+  // hard enough to skip its own trap. Both are failures — and both used to look like silence.
+  if (hb.state === 'running' && ageHours > 6) {
+    return { state: FAILING, ageHours, detail: `started ${ageHours.toFixed(1)}h ago and NEVER FINISHED (hung or killed)` };
+  }
+  if (ageHours > job.maxAgeHours) {
+    return { state: STALE, ageHours, detail: `last ran ${ageHours.toFixed(1)}h ago — its schedule allows ${job.maxAgeHours}h. It stopped.` };
+  }
+  if (hb.state === 'failed' || (typeof hb.exit_code === 'number' && hb.exit_code !== 0)) {
+    return { state: FAILING, ageHours, detail: `last run FAILED with exit ${hb.exit_code} (${ageHours.toFixed(1)}h ago)` };
+  }
+  if (hb.state === 'running') {
+    return { state: OK, ageHours, detail: `running right now (started ${ageHours.toFixed(1)}h ago)` };
+  }
+  return { state: OK, ageHours, detail: `ran ${ageHours.toFixed(1)}h ago, exit 0` };
+}
+
+export function readHeartbeat(label, dir = HB_DIR) {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, `${label}.json`), 'utf8')); } catch { return null; }
+}
+
+/**
+ * TIER 2 EVIDENCE. A heartbeat (tier 1) is the real proof: start, end, exit code, trap-protected.
+ * But receipts only exist from the moment a job is wrapped, and jobs that have genuinely been running
+ * for weeks would read NEVER-RAN on day one — a false alarm that would poison the gong immediately.
+ *
+ * A job's own log, written WHILE IT WORKED, is still evidence it ran (it satisfies the rule: a job that
+ * died silently cannot produce it). It is weaker — no exit code, so a job that logs and then dies looks
+ * alive — so it is accepted, LABELLED as second-class, and superseded the moment a real receipt lands.
+ * Absence of BOTH remains NEVER-RAN. This is a bootstrap ramp, not a loophole.
+ */
+export function readLegacyLog(job, root = ROOT) {
+  if (!job.legacyLog) return null;
+  try {
+    const p = path.join(root, job.legacyLog);
+    const { mtime } = fs.statSync(p);
+    const tail = fs.readFileSync(p, 'utf8').slice(-4000);
+    return {
+      started_at: mtime.toISOString(),
+      ended_at: mtime.toISOString(),
+      state: /FATAL|VERIFIED FAILURE/.test(tail) ? 'failed' : 'ok',
+      exit_code: /FATAL|VERIFIED FAILURE/.test(tail) ? 1 : 0,
+      _tier2: true, // surfaced in the verdict so nobody mistakes this for a real receipt
+    };
+  } catch { return null; }
+}
+
+export function checkAll(now, { registry = REGISTRY, loaded = loadedLabels(), hbDir = HB_DIR, root = ROOT } = {}) {
+  const { jobs } = JSON.parse(fs.readFileSync(registry, 'utf8'));
+  return jobs.map((job) => {
+    const hb = readHeartbeat(job.label, hbDir) || readLegacyLog(job, root);
+    const verdict = judge(job, hb, loaded.has(job.label), now);
+    if (hb?._tier2 && verdict.state === OK) verdict.detail += ' (via its log — no receipt yet; the next run writes one)';
+    return { ...job, ...verdict };
+  });
+}
+
+const loadState = () => { try { return JSON.parse(fs.readFileSync(STATE, 'utf8')); } catch { return {}; } };
+const saveState = (s) => { fs.mkdirSync(path.dirname(STATE), { recursive: true }); fs.writeFileSync(STATE, JSON.stringify(s, null, 2)); };
+
+/** Page only on a CHANGE of state. Repeating the same alarm nightly is how alarms get ignored. */
+export function transitions(results, prev) {
+  return results.filter((r) => (prev[r.label] ?? OK) !== r.state);
+}
+
+async function push(title, body, priority) {
+  const topic = process.env.NTFY_TOPIC
+    || (() => { try { return fs.readFileSync(path.join(os.homedir(), '.cache', 'ruvnet-brain', 'ntfy-topic'), 'utf8').trim(); } catch { return null; } })();
+  if (!topic) return false;
+  try {
+    await fetch(`https://ntfy.sh/${topic}`, {
+      method: 'POST',
+      headers: { Title: title, Priority: priority, Tags: priority === 'urgent' ? 'rotating_light' : 'white_check_mark' },
+      body,
+    });
+    return true;
+  } catch { return false; }
+}
+
+async function main() {
+  const json = process.argv.includes('--json');
+  const quiet = process.argv.includes('--quiet');
+  const results = checkAll(new Date());
+  const bad = results.filter((r) => r.state !== OK);
+
+  const prev = loadState();
+  for (const c of transitions(results, prev)) {
+    if (c.state === OK) await push(`✅ ${c.label} is healthy again`, c.detail, 'default');
+    else await push(`🔴 ${c.state}: ${c.label}`, `${c.what}\n\n${c.detail}\n\nschedule: ${c.schedule}`, 'urgent');
+  }
+  saveState(Object.fromEntries(results.map((r) => [r.label, r.state])));
+
+  if (json) console.log(JSON.stringify({ results, checkedAt: new Date().toISOString() }, null, 2));
+  else if (!quiet || bad.length) {
+    console.log('Scheduled-job watchdog — proof each job RAN, not just that it exists\n');
+    for (const r of results) {
+      const icon = r.state === OK ? '✅' : '🔴';
+      console.log(`${icon} ${r.state.padEnd(10)} ${r.label}`);
+      console.log(`   ${r.detail}`);
+      console.log(`   ${r.what} · ${r.schedule}\n`);
+    }
+    console.log(bad.length
+      ? `${bad.length} of ${results.length} job(s) are NOT confirmed working. NEVER-RAN means the schedule has never fired — it does not mean "probably fine".`
+      : `All ${results.length} jobs produced a fresh, successful receipt.`);
+  }
+  process.exit(bad.length ? 1 : 0);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await main();

package/scripts/no-silent-substitution.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// scripts/no-silent-substitution.mjs — THE GATE THAT WOULD HAVE CAUGHT ME.
+//
+// WHY (2026-07-13, Stuart: "you're still doing this crap where you fucking lie to me and write a
+// bunch of code and then tell me it's Ruv's code?"):
+//
+//   I wrote scripts/model-router-engine.mjs — 216 lines of my own heuristic with a self-described
+//   "placeholder policy" — and SKILL.md called it "the MetaHarness router engine". Meanwhile
+//   @metaharness/router@0.3.2 (ADR-040/043, Accepted/implemented) was sitting on npm: rUv's real
+//   learned cost-optimal router, the productized DRACO Phase-2 finding. I built a Claude fake and
+//   gave it his name. Every test passed. Every gate was green. NOTHING CHECKED FOR THE ONE THING THAT
+//   ACTUALLY MATTERED.
+//
+// That is a QA hole, not a slip. Tests check "does my code work"; nothing checked "should this code
+// exist at all, or does rUv already ship it?" This gate closes that hole and runs in CI.
+//
+// THE RULE IT ENFORCES:
+//   If this repo contains code that implements a capability rUv already ships as a package, then
+//   EITHER
+//     (a) the real package is a declared dependency AND is actually imported somewhere, OR
+//     (b) the local file carries an explicit, un-missable disclosure:
+//           HAND-ROLLED: <reason>. REAL TOOL: <package>
+//   Silence is not an option. You may hand-roll — you may NEVER hand-roll silently, and you may
+//   never call your hand-roll by rUv's name.
+//
+// Usage:  node scripts/no-silent-substitution.mjs        # exit 1 on any violation (CI gate)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * The capability map. Each entry: a capability rUv ALREADY SHIPS, the package that provides it, and
+ * the signals that this repo is implementing it locally.
+ *
+ * Add to this list whenever the ecosystem ships something we might be tempted to rebuild. The cost of
+ * a missing entry is exactly the bug above: a hand-roll wearing rUv's name, with green tests.
+ */
+export const CAPABILITIES = [
+  {
+    capability: 'cost-optimal model routing',
+    pkg: '@metaharness/router',
+    // Naming your file/docs after rUv's product is the tell. If you use the NAME, you use the TOOL.
+    claimsTheName: /metaharness[ -]?router|the metaharness router engine/i,
+    localImpl: /cost.?optimal|qualityBar|route.*cheapest|model.?router/i,
+  },
+  {
+    capability: 'test generation / QE fleet',
+    pkg: 'agentic-qe',
+    claimsTheName: /agentic[ -]?qe/i,
+    localImpl: /generate.*tests?.*automatically|coverage.?gap.?analysis/i,
+  },
+  {
+    capability: 'vector store / HNSW',
+    pkg: '@ruvector/rvf',
+    claimsTheName: /\bRVF\b|ruvector/i,
+    localImpl: /hand.?rolled.*cosine|own.*hnsw.*implementation/i,
+  },
+  {
+    capability: 'prompt-injection / PII defence',
+    pkg: '@claude-flow/aidefence',
+    claimsTheName: /aimds|aidefence/i,
+    localImpl: /prompt.?injection.*scanner|pii.*detector/i,
+  },
+];
+
+// Scan CODE and the SKILL (the two places a substitution can actually deceive someone), not prose.
+// A README that says "we use agentic-qe" is a claim about usage — checking it belongs in claims-verify.
+// A gate that fires on every doc mentioning a tool is a gate everyone learns to ignore (see the
+// windows-unit lesson: a permanently-red required job trains people to stop reading CI).
+const SCAN_DIRS = ['scripts', 'bin', 'plugin/scripts', 'plugin/skills'];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'clones', 'dist', 'coverage', 'kb']);
+const SCAN_EXT = new Set(['.mjs', '.js', '.ts', '.md']);
+// This file NAMES every tool in order to police them — exempting it is not a loophole, it is the
+// difference between the rulebook and a violation.
+const EXEMPT = new Set(['scripts/no-silent-substitution.mjs', 'tests/unit/no-silent-substitution.test.mjs']);
+
+// The disclosure that makes a hand-roll legitimate. Explicit, greppable, impossible to write by accident.
+const DISCLOSURE = /HAND-ROLLED:.*REAL TOOL:\s*(\S+)/is;
+
+export function walk(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name), out); }
+    else if (SCAN_EXT.has(path.extname(e.name))) out.push(path.join(dir, e.name));
+  }
+  return out;
+}
+
+/**
+ * Is the real package genuinely used? Checks EVERY manifest in the repo, not just the root — the
+ * first version of this gate only read the root package.json and cried wolf on @ruvector/rvf, which
+ * is declared in kb/package.json and used all over kb/. A gate with false positives gets switched
+ * off, and then it protects nothing.
+ */
+export function packageIsReallyUsed(pkg, root = ROOT) {
+  const manifests = ['package.json', 'kb/package.json', 'plugin/package.json'];
+  let declared = false;
+  for (const m of manifests) {
+    try {
+      const p = JSON.parse(fs.readFileSync(path.join(root, m), 'utf8'));
+      if ({ ...p.dependencies, ...p.devDependencies, ...p.optionalDependencies }[pkg]) { declared = true; break; }
+    } catch { /* manifest absent — keep looking */ }
+  }
+  if (!declared) return { declared: false, imported: false };
+
+  // Match ANY real code reference to the package, not just a static `import ... from`. kb/ loads
+  // @ruvector/rvf through a lazy dynamic resolver (createRequire/resolve-deps), so a static-import
+  // regex reports the most heavily-used dependency in the repo as "never imported". A gate that
+  // flags real usage as fraud is worse than no gate.
+  const nameRe = new RegExp(`['"\`]${pkg.replace(/[/@.]/g, '\\$&')}['"\`/]`);
+  const codeDirs = ['scripts', 'kb', 'bin'].map((d) => path.join(root, d)).filter((d) => fs.existsSync(d));
+  const imported = codeDirs
+    .flatMap((d) => walk(d, []))
+    .filter((f) => ['.mjs', '.js', '.ts'].includes(path.extname(f))) // code only — a doc mentioning it is not usage
+    .some((f) => nameRe.test(fs.readFileSync(f, 'utf8')));
+  return { declared, imported };
+}
+
+export function audit(root = ROOT) {
+  const violations = [];
+  const files = SCAN_DIRS.flatMap((d) => {
+    const abs = path.join(root, d);
+    return fs.existsSync(abs) ? walk(abs, []) : [];
+  }).filter((f) => !EXEMPT.has(path.relative(root, f).split(path.sep).join('/')));
+
+  for (const cap of CAPABILITIES) {
+    const use = packageIsReallyUsed(cap.pkg, root);
+    for (const abs of files) {
+      const rel = path.relative(root, abs).split(path.sep).join('/');
+      const src = fs.readFileSync(abs, 'utf8');
+
+      // BOTH signals are required, and that conjunction IS the crime:
+      //   buildsIt  — this file implements the capability
+      //   namesIt   — and calls it by rUv's name
+      // Merely mentioning a tool is not a substitution. Merely implementing something is not either
+      // (you are allowed to write code). Implementing it AND wearing rUv's name is the deception.
+      if (!(cap.claimsTheName.test(src) && cap.localImpl.test(src))) continue;
+
+      // Two ways to be innocent: actually use the real tool, or openly admit you did not.
+      if (use.imported || DISCLOSURE.test(src)) continue;
+
+      violations.push({
+        file: rel,
+        capability: cap.capability,
+        pkg: cap.pkg,
+        why: use.declared
+          ? `implements "${cap.capability}" and calls itself ${cap.pkg}, but the package is declared and NEVER IMPORTED — a hand-roll wearing rUv's name`
+          : `implements "${cap.capability}" and calls itself ${cap.pkg}, but the package is NOT a dependency — a Claude fake with rUv's label on it`,
+        fix: `Either USE ${cap.pkg} (npm i ${cap.pkg}; import it), or add the disclosure: "HAND-ROLLED: <reason>. REAL TOOL: ${cap.pkg}"`,
+      });
+    }
+  }
+  return violations;
+}
+
+function main() {
+  const violations = audit();
+  console.log('no-silent-substitution — is any local code impersonating a real rUv tool?\n');
+  if (!violations.length) {
+    console.log('✅ none. Every RuvNet capability this repo names is either genuinely used or openly disclosed as a hand-roll.');
+    process.exit(0);
+  }
+  for (const v of violations) {
+    console.error(`❌ ${v.file}`);
+    console.error(`   capability : ${v.capability}`);
+    console.error(`   problem    : ${v.why}`);
+    console.error(`   fix        : ${v.fix}\n`);
+  }
+  console.error(`${violations.length} silent substitution(s). You may hand-roll — you may NEVER hand-roll SILENTLY,`);
+  console.error("and you may never call your hand-roll by rUv's name.");
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) main();