ruvnet-brain 2.5.1 → 2.8.0

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.8.0 — updated 2026-07-14 05:59 EDT](https://img.shields.io/badge/version_2.8.0-updated_2026--07--14_05:59_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.**
 
@@ -77,7 +77,7 @@ So 2.5.1 makes it a **wall, not advice**: a `PreToolUse` gate that **blocks any
 
 | | v1 (0.x–1.x) | v2.0 |
 |---|---|---|
-| **Corpus** | 24 repos built | **32 repos** built (of 197 live ruvnet repos), each verified by a live retrieval query |
+| **Corpus** | 24 repos built | **36 repos** built (of 197 live ruvnet repos), each verified by a live retrieval query |
 | **Depth** (flagship `ruvector`) | 18,491 passages · **0** full source bodies | **28,018 passages · 2,996 full bodies** — depth also restored to `agent-harness-generator` (8,896/715), `ruview` (7,434/765), `open-claude-code` (195/69) |
 | **Corpus QA gate** | none | every store must prove *embeds correctly + reads correctly* — vector count == passage count, depth floors, a 3-passage self-retrieval round-trip per store — **72/72 store-variants PASS**, wired fail-closed into the nightly publish |
 | **Retrieval eval** | 12 frozen questions | **120 frozen, hash-pinned questions** across 5 strata; promotion gated on Wilson lower bounds, fail-closed — it blocked a real release this morning, which is the feature working |
@@ -212,7 +212,7 @@ Plus: the **“take the wheel” behavioral pipeline** (below), a **4-level beha
 
 ## How it works
 
-The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **129,037 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
+The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **129,685 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
 
 ![RuvNet Brain architecture pipeline](assets/diagrams/architecture-pipeline.svg)
 
@@ -246,7 +246,7 @@ The brain answers **both** kinds of questions. **Name the repo or ask something
 
 ## What it covers
 
-32 of rUv's repos in the [ruvnet](https://github.com/ruvnet) org — the reusable **building blocks** you'd actually compose into a system — each deep-walked and embedded in both variants. The core blocks below also carry symbol indexes and capability cards (the 8 newest repos are findable by name; their capability cards are coming).
+36 of rUv's repos in the [ruvnet](https://github.com/ruvnet) org — the reusable **building blocks** you'd actually compose into a system — each deep-walked and embedded in both variants. The core blocks below also carry symbol indexes and capability cards (the 8 newest repos are findable by name; their capability cards are coming).
 
 ![The RuvNet stack the brain covers](primer/assets/diagrams/ruvnet-stack.svg)
 
@@ -322,7 +322,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 32 repos, 129,037 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 36 repos, 129,685 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L4 all pass; private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "version": "2.5.1",
-  "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.",
+  "version": "2.8.0",
+  "description": "One-command installer for RuvNet Brain — 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": {
     "ruvnet-brain": "bin/install.mjs"
@@ -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,231 @@
+#!/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: 'does-memory-actually-recall',
+    asked: '"Is AgentDB actually storing AND recalling, or is it just small bits?"',
+    why: 'I reported AgentDB as broken THREE times. It was never broken. I called `memory search` positionally when the CLI wants -q, then broke my own canary test with a bad grep, and reported MY test defects as PRODUCT defects. This check does the round trip so I can never again mistake my own sloppiness for a broken tool.',
+    run: () => {
+      // MEMORY_DB override exists so this check can be TESTED AGAINST A BROKEN STATE. A check nobody
+      // has watched fail is not a check. (My first two attempts to test it were themselves broken —
+      // which is the entire reason this check exists.)
+      const db = process.env.MEMORY_DB || path.join(ROOT, '.swarm', 'memory.db');
+      if (!fs.existsSync(db)) return { ok: false, detail: 'no memory.db — memory is not initialised' };
+
+      // 1. Is it COLLECTING? (rows, embedded, current)
+      const q = (sql) => (spawnSync('sqlite3', [db, sql], { encoding: 'utf8' }).stdout || '').trim();
+      const total = Number(q('SELECT COUNT(*) FROM memory_entries;'));
+      const embedded = Number(q("SELECT SUM(embedding IS NOT NULL AND LENGTH(embedding)>50) FROM memory_entries;"));
+      const ageH = (Date.now() - Number(q('SELECT MAX(created_at) FROM memory_entries;'))) / 3600_000;
+
+      // 2. Does it SURVIVE compaction / session end? (the whole point)
+      const pre = Number(q("SELECT COUNT(*) FROM memory_entries WHERE key LIKE 'session-precompact%';"));
+      const end = Number(q("SELECT COUNT(*) FROM memory_entries WHERE key LIKE 'session-sessionend%';"));
+
+      // 3. Does it RECALL? A real semantic round-trip through the REAL CLI — not a DB peek.
+      const r = spawnSync('npx', ['ruflo@latest', 'memory', 'search', '-q', 'nightly job supervision heartbeat receipts'], {
+        cwd: ROOT, encoding: 'utf8', timeout: 120_000,
+      });
+      const recalled = /Found\s+\d+\s+results/.test(r.stdout || '') && !/Found\s+0\s+results/.test(r.stdout || '');
+
+      const problems = [];
+      if (total < 10) problems.push(`only ${total} entries stored`);
+      if (embedded / Math.max(total, 1) < 0.9) problems.push(`only ${embedded}/${total} entries are embedded — semantic recall will be partial`);
+      if (ageH > 48) problems.push(`newest entry is ${ageH.toFixed(0)}h old — capture may have stopped`);
+      if (pre === 0) problems.push('ZERO PreCompact snapshots — context will NOT survive a compaction');
+      if (end === 0) problems.push('ZERO SessionEnd snapshots — context will NOT survive a session restart');
+      if (!recalled) problems.push('semantic search returned NOTHING — recall is dead');
+
+      return {
+        ok: problems.length === 0,
+        detail: problems.length
+          ? problems.join('; ')
+          : `${total} entries (${embedded} embedded), ${pre} PreCompact + ${end} SessionEnd snapshots, semantic recall returns results`,
+      };
+    },
+  },
+  {
+    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-receipts.mjs

@@ -43,22 +43,29 @@ export function loadReceipts(file) {
 }
 
 const fmt$ = (n) => `$${n < 0.01 ? n.toFixed(5) : n.toFixed(4)}`;
+// Measured wall-clock, human-readable. '-' when the receipt has no duration — never invented.
+const fmtT = (ms) => {
+  if (typeof ms !== 'number' || !(ms > 0)) return '-';
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m${String(Math.round((ms % 60_000) / 1000)).padStart(2, '0')}s`;
+};
 
 export function formatTable(rows) {
   if (!rows.length) return 'No routing receipts yet.\nRoute something cheap first:  node scripts/route-cheap.mjs --task "<text>"';
 
   // `channel` + `instead of` (2026-07-13): subagent receipts arrived with a per-row baseline — the
   // model that agent WOULD have inherited — so a single global "frontier" column would misreport them.
-  const header = ['date', 'channel', 'task class', 'model used', 'instead of', 'est. cost', 'est. baseline', 'saved'];
+  const header = ['date', 'channel', 'task class', 'model used', 'instead of', 'est. cost', 'est. baseline', 'saved', 'time'];
   const body = rows.map((r) => [
     (r.ts || '').replace('T', ' ').slice(0, 16),
-    r.source === 'claude-subagent' ? 'subagent' : 'openrouter',
+    r.source === 'claude-subagent' ? 'subagent' : r.source === 'calibration' ? 'calibrate' : 'openrouter',
     r.task_class || '?',
     r.model,
     r.frontier_ref || 'claude-opus-4.8',
     fmt$(r.est_cost ?? 0),
     fmt$(r.est_frontier_cost ?? 0),
     fmt$(r.saved),
+    fmtT(r.duration_ms), // measured, never estimated — '-' when absent
   ]);
   const widths = header.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length)));
   const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join('  ');
@@ -67,19 +74,58 @@ export function formatTable(rows) {
   const totalFrontier = rows.reduce((s, r) => s + (r.est_frontier_cost || 0), 0);
   const totalSaved = rows.reduce((s, r) => s + r.saved, 0);
   const ratio = totalCost > 0 ? (totalFrontier / totalCost).toFixed(1) : '?';
+  // Lead with the PERCENTAGE — "$1.83" reads as pocket change; "68% cheaper" is the actual
+  // message (Stuart, 2026-07-13). Dollars stay for auditability; percent carries the story.
+  const pct = totalFrontier > 0 ? Math.round((totalSaved / totalFrontier) * 100) : 0;
 
   // Baselines now vary per row; name them all rather than picking one and implying it covers everything.
   const baselines = [...new Set(rows.map((r) => r.frontier_ref || 'claude-opus-4.8'))].join(', ');
+  const timedTotal = rows.reduce((s, r) => s + (typeof r.duration_ms === 'number' && r.duration_ms > 0 ? r.duration_ms : 0), 0);
+  const timedRows = rows.filter((r) => typeof r.duration_ms === 'number' && r.duration_ms > 0).length;
+  // TIME as a percentage, like cost — "20 seconds" is trivia; "~40% faster" is the message
+  // (Stuart, 2026-07-13: cheaper AND faster = fundamentally more efficient). Only rows carrying a
+  // MEASURED baseline_duration_ms (written by the calibration harness) enter this comparison.
+  const paired = rows.filter((r) => r.duration_ms > 0 && r.baseline_duration_ms > 0);
+  const pairedRouted = paired.reduce((s, r) => s + r.duration_ms, 0);
+  const pairedBase = paired.reduce((s, r) => s + r.baseline_duration_ms, 0);
+  const fasterPct = pairedBase > 0 ? Math.round((1 - pairedRouted / pairedBase) * 100) : null;
+  // Say what the measurement actually says — FASTER, SLOWER, or parity. The 2026-07-13
+  // calibration measured cheap tiers at speed PARITY on micro-tasks (startup dominates);
+  // a card that only knows how to say "faster" would have lied.
+  const speedBadge = fasterPct === null ? ''
+    : fasterPct >= 5 ? `  ·  ⚡ ~${fasterPct}% FASTER (measured, n=${paired.length})`
+    : fasterPct <= -5 ? `  ·  ⏱ ~${-fasterPct}% slower on routed tier (measured, n=${paired.length})`
+    : `  ·  ⚡ speed parity (measured, n=${paired.length})`;
   const subagents = rows.filter((r) => r.source === 'claude-subagent').length;
 
+  // The card leads with the PERCENTAGE and a spent-vs-unrouted bar — "$1.83" reads as pocket
+  // change; "68% cheaper", drawn, is the message (Stuart, 2026-07-13). The dollar table stays
+  // below for auditability; every number still traces to a receipt row.
+  const BAR = 30;
+  const withBar = totalFrontier > 0 ? Math.min(BAR, Math.max(1, Math.round(BAR * (totalCost / totalFrontier)))) : BAR;
+  const drawBar = (n) => '█'.repeat(n) + '░'.repeat(BAR - n);
+  const rule = '─'.repeat(70);
   return [
+    rule,
+    `  💰 SAVED ~${pct}%${speedBadge}  ·  ~${ratio}× cheaper  ·  ${rows.length} routed task(s) (${subagents} subagent, ${rows.length - subagents} openrouter/calibration)`,
+    '',
+    `  without routing    ${drawBar(BAR)}  ${fmt$(totalFrontier)}`,
+    `  with MetaHarness   ${drawBar(withBar)}  ${fmt$(totalCost)}   → ~${fmt$(totalSaved)} kept`,
+    rule,
     line(header),
     line(widths.map((w) => '-'.repeat(w))),
     ...body.map(line),
     '',
-    `${rows.length} routed task(s) (${subagents} subagent, ${rows.length - subagents} openrouter) · est. spent ${fmt$(totalCost)} vs ${fmt$(totalFrontier)} unrouted (${baselines}) · saved ~${fmt$(totalSaved)} (~${ratio}x cheaper)`,
+    `Baselines: ${baselines} — the model each task would have run on if it had not been routed.`,
     'Pricing is live-verified. Token counts are measured OR estimated per row (each row records which, in token_source).',
-    'Baseline = the model the task would have run on if it had not been routed.',
+    // Time honesty: durations are MEASURED wall-clock of the routed run. A "time saved vs baseline"
+    // number requires a measured per-tier speed baseline (the calibration batch) — until that exists
+    // we state the gap instead of inventing the comparison.
+    fasterPct !== null
+      ? `Time, measured: routed ${fmtT(pairedRouted)} vs baseline ${fmtT(pairedBase)} on ${paired.length} calibrated task(s) → ${fasterPct >= 5 ? `~${fasterPct}% faster` : fasterPct <= -5 ? `~${-fasterPct}% slower (startup-dominated micro-tasks — speed wins come from parallel fan-out and long generations, measured from real dispatches)` : 'speed parity'}. Uncalibrated rows show routed time only.`
+      : timedTotal > 0
+        ? `Measured time on routed models: ${fmtT(timedTotal)} across ${timedRows} timed task(s). Time-SAVED vs baseline: not yet measured — appears after the per-tier calibration run.`
+        : 'No measured durations in these receipts yet. Time-saved reporting activates after the per-tier calibration run.',
   ].join('\n');
 }
 

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();

package/scripts/route-cheap.mjs

@@ -82,7 +82,9 @@ const fmt$ = (n) => `$${n < 0.01 ? n.toFixed(5) : n.toFixed(4)}`;
 
 export function receiptLine(model, costs) {
   const ref = costs.ref && costs.ref !== FRONTIER.name ? costs.ref : 'frontier';
-  return `\x1b[2m⚡ MetaHarness: routed to ${model} (est. ${fmt$(costs.cost)} vs ${fmt$(costs.frontier)} ${ref} — saved ~${fmt$(costs.saved)})\x1b[0m`;
+  // Percentage leads — "saved ~$0.005" reads as noise, "~97% cheaper" is the message (Stuart, 2026-07-13).
+  const pct = costs.frontier > 0 ? Math.round((costs.saved / costs.frontier) * 100) : 0;
+  return `\x1b[2m⚡ MetaHarness: routed to ${model} — ~${pct}% cheaper (est. ${fmt$(costs.cost)} vs ${fmt$(costs.frontier)} ${ref}, saved ~${fmt$(costs.saved)})\x1b[0m`;
 }
 
 // Load OPENROUTER_API_KEY from ruvnet-brain/.env if not already in env. Value never printed/logged.