ruvnet-brain 2.4.3 → 2.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 2.4.3 — updated 2026-07-12 21:11 EDT](https://img.shields.io/badge/version_2.4.3-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.0 — updated 2026-07-12 21:11 EDT](https://img.shields.io/badge/version_2.5.0-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.**
 
@@ -36,17 +36,27 @@
 
 ---
 
-## What's new in 2.4 — it routes your money, and it can never break silently
+## What's new in 2.5 — it uses rUv's real tools, and every job proves it ran
 
-**Shipped 2026-07-12, every piece proven live before it was written down:**
+**Shipped 2026-07-13. Two hard lessons, both fixed at the root.**
 
-- **MetaHarness model router** — reviews each task and sends it to the cheapest model that can do the job, **your subscriptions first ($0)**: a harness-neutral decision engine (Claude Code *and* Codex), a verified-pricing catalog, and a cross-tier floor that never pays a metered API while a subscription model can do the work.
-- **Per-user subscription profiles** — setup detects what it can *prove* (Codex's ChatGPT login, from the auth file's shape, never its secrets), **asks** what it can't ("Claude Pro or Max?"), and records every answer with its evidence basis (`verified` / `user-attested` / `assumed`). Your $0 is never assumed from someone else's machine.
-- **The offer + the path** — one line ("want me to set up cost-optimal routing? yes/no"), two questions, then a live-derived display of your zero-cost options per harness and the cheapest verified paid-API fallbacks (DeepSeek V4 Flash at $0.077/MTok in — dispatch-proven, not just priced).
-- **Goldie** — a weekly scheduled research job: refreshes verified OpenRouter pricing, flags >20% drift, cross-checks the model registries, auto-reinstates models the moment live evidence appears, and runs a headless research pass on the standing questions (how many buckets, best model per bucket). Its **first run caught a false "verified" stamp in its own catalog**.
-- **The gong system** — a dark brain can never read as "(no results)" again: real-time screaming errors + an urgent phone push, a red banner in every new session, and a nightly canary — each layer proven by deliberately breaking the brain and watching it ring, then watching recovery clear it.
-- **Key + spend canaries** — every provider API key live-probed nightly through the real shell chain (a dead key pages you within a day; it found and healed one on day one), alongside the API-spend watchdog.
-- **An outcome log** — every routing decision and every human override is recorded as labeled data; the current documented-placeholder policy gets replaced by a learned one (per rUv's ADR-040/DRACO and ruflo ADR-149 evidence) once the labels accumulate.
+### 1. It stopped faking rUv's tools — and now a CI gate makes faking impossible
+
+The 2.4 router was **hand-rolled**: our own heuristic with a placeholder policy, presented as "the MetaHarness router." rUv had already shipped the real thing. 2.5 replaces it with **[`@metaharness/router`](https://www.npmjs.com/package/@metaharness/router)** — his actual learned cost-optimal router (k-NN over labelled embeddings, the productized DRACO Phase-2 finding, ADR-040/043).
+
+Our code now does **one honest job**: a price transform. A model your subscription already covers becomes `costPerMTok = 0`, and rUv's router does the rest natively — a $0 model that clears the quality bar simply *is* the cheapest sufficient candidate. Cost-optimal routing and "already paid for" compose; they never competed.
+
+> **`npm run substitution:check`** — a new CI gate that fails the build if any code implements a capability rUv already ships *and* wears his name without either using the real package or openly disclosing the hand-roll. **Verified to fire on the exact commit where we got this wrong.** You may hand-roll. You may never hand-roll *silently*.
+
+### 2. Every scheduled job must PROVE it ran — silence is no longer health
+
+`launchctl` reports **exit 0 for a job that has never run** — byte-identical to success. So "check the exit code" cannot tell triumph from total absence, and a nightly job sat unfired for its entire life while every surface read green.
+
+- **A registry** (`config/scheduled-jobs.json`) of what *must* run — so unloaded, deleted, or never-fired is a **violation**, not a silence.
+- **A wrapper** every job runs through — start receipt, end receipt, real exit code, urgent phone push on failure. Break-tested through all four death modes (including SIGKILL, which no trap can catch — the watchdog catches that one).
+- **A watchdog** that treats *absence of evidence as failure*, and which is **in its own registry** — because a supervisor nobody supervises just moves the blind spot up one level.
+
+Result: **11 jobs supervised, every one producing a fresh successful receipt.** One had been *totally blind* — writing zero bytes on a healthy day, so "ran fine" and "never ran" were indistinguishable. Cured without changing a line of its logic.
 
 ![MetaHarness routing — your subscriptions first, always](assets/diagrams/router-path.svg)
 
@@ -194,7 +204,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,011 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,034 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)
 
@@ -304,7 +314,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,011 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 32 repos, 129,034 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/bin/install.mjs

@@ -1151,7 +1151,11 @@ export async function offerRouterProfile() {
     if (fs.existsSync(s) && !fs.existsSync(d)) { fs.copyFileSync(s, d); ok(`installed ${dst} (edit freely — goldie keeps prices fresh where scheduled)`); }
   }
   let copied = 0;
-  for (const t of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'route-cheap.mjs', 'codex-routed.sh']) {
+  // dispatch-receipt + metaharness-receipts added 2026-07-13: without the LOGGER, subagent routing is
+  // invisible; without the VIEWER, the user has no scoreboard to hold it to. Shipping one without the
+  // other is how a router ends up "working" with three test pings in its log and nobody the wiser.
+  // (dispatch-receipt.mjs relative-imports route-cheap.mjs — they land in the same bin/ dir, so it resolves.)
+  for (const t of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'route-cheap.mjs', 'dispatch-receipt.mjs', 'metaharness-receipts.mjs', 'codex-routed.sh']) {
     const s = path.join(pkgRoot, 'scripts', t);
     if (fs.existsSync(s)) { fs.copyFileSync(s, path.join(routerDir, 'bin', t)); copied++; }
   }

package/config/ruvnet-autoupdate.sh.snapshot

@@ -0,0 +1,109 @@
+#!/bin/bash
+# Ruvnet Ecosystem Auto-Update
+# Updated: 2026-05-07
+#
+# Runs every night at 03:30 via ~/Library/LaunchAgents/com.stuartkerr.ruflo-autoupdate.plist
+# Discovers all currently-installed Ruvnet ecosystem packages and refreshes them.
+#
+# Tag policy:
+#   - ruflo, @claude-flow/cli       → @alpha (Stuart runs alpha track)
+#   - agentdb                       → RETIRED 2026-05-30: AgentDB is bundled inside
+#                                     @claude-flow/memory (Ruflo); no standalone install.
+#   - everything else (@ruvector/*, ruvector, @claude-flow/aidefence,
+#     agent-browser, agentic-flow, flow-nexus)
+#                                   → @latest
+
+set -uo pipefail
+
+LOG="$HOME/Library/Logs/ruflo-autoupdate.log"
+PATH="$HOME/.npm-global/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
+export PATH
+
+ts() { date -u +"[%Y-%m-%dT%H:%M:%SZ]"; }
+
+echo "$(ts) ──── Ruvnet ecosystem update starting ────" | tee -a "$LOG"
+
+# Packages known to fail on this platform — skipped from auto-update.
+# @ruvector/edge-net pulls wrtc which needs a darwin-arm64 prebuilt binary
+# from S3 that returns 404. Bug in upstream wrtc package, not actionable here.
+SKIP_PACKAGES="@ruvector/edge-net"
+
+is_skipped() {
+  local pkg="$1"
+  for sk in $SKIP_PACKAGES; do
+    [ "$pkg" = "$sk" ] && return 0
+  done
+  return 1
+}
+
+# Discover all currently-installed packages of interest
+# Discover all currently-installed RuvNet packages.
+# 2026-07-13: the old filter listed only 7 names/prefixes, so agentic-qe, @metaharness/*, qudag,
+# ruv-swarm, ruvbot, ruvi, ruvector-extensions and agentic-robotics were installed but NEVER updated
+# — silently frozen at whatever version they landed on. Live drift found that day: agentic-qe
+# 3.11.5 vs 3.12.0, ruvbot 0.3.1 vs 0.3.2, ruvector-extensions 0.1.1 vs 0.1.2.
+# Principle: if it is an installed RuvNet package, it gets kept current. No arbitrary allowlist.
+# (@marketing/ai-swarms is a LOCAL npm link — never npm-install over it; it is excluded by name.)
+PACKAGES=$(npm ls -g --depth=0 --json 2>/dev/null | jq -r '
+  .dependencies // {} | keys[] | select(
+    startswith("@ruvector/") or
+    startswith("@claude-flow/") or
+    startswith("@metaharness/") or
+    startswith("@agentic-robotics/") or
+    . == "ruflo" or
+    . == "ruvector" or
+    . == "ruvector-extensions" or
+    . == "agent-browser" or
+    . == "agentic-flow" or
+    . == "agentic-qe" or
+    . == "agentic-robotics" or
+    . == "flow-nexus" or
+    . == "qudag" or
+    . == "ruv-swarm" or
+    . == "ruvbot" or
+    . == "ruvi"
+  ) | select(startswith("@marketing/") | not)
+')
+
+if [ -z "$PACKAGES" ]; then
+  echo "$(ts) ERROR: no Ruvnet packages found via 'npm ls -g'" | tee -a "$LOG"
+  exit 1
+fi
+
+# Build install args with the right tag per package
+INSTALL_ARGS=""
+SKIPPED=""
+ALPHA_PACKAGES="ruflo @claude-flow/cli"
+for pkg in $PACKAGES; do
+  if is_skipped "$pkg"; then
+    SKIPPED="$SKIPPED $pkg"
+    continue
+  fi
+  TAG="@latest"
+  for alpha_pkg in $ALPHA_PACKAGES; do
+    if [ "$pkg" = "$alpha_pkg" ]; then
+      TAG="@alpha"
+      break
+    fi
+  done
+  INSTALL_ARGS="$INSTALL_ARGS ${pkg}${TAG}"
+done
+
+if [ -n "$SKIPPED" ]; then
+  echo "$(ts) Skipping known-broken packages:$SKIPPED" | tee -a "$LOG"
+fi
+
+echo "$(ts) Updating: $INSTALL_ARGS" | tee -a "$LOG"
+
+# Run the install — keep going even if one package fails
+npm install -g $INSTALL_ARGS 2>&1 | tee -a "$LOG"
+
+EXIT_CODE=$?
+if [ $EXIT_CODE -eq 0 ]; then
+  echo "$(ts) ✓ auto-update finished cleanly" | tee -a "$LOG"
+else
+  echo "$(ts) ⚠ auto-update finished with exit code $EXIT_CODE — check log for failed packages" | tee -a "$LOG"
+fi
+
+echo "" | tee -a "$LOG"
+exit $EXIT_CODE

package/config/scheduled-jobs.json

@@ -0,0 +1,93 @@
+{
+  "_why": "THE REGISTRY OF WHAT MUST BE RUNNING. Created 2026-07-13 after a failure that must never repeat: com.ruvnet.brain-nightly's launchd trigger had NEVER fired, and nothing noticed, because 'is it running?' was only ever answered by looking at a job's own exit code — and launchd reports exit 0 for a job that has never run, which is indistinguishable from success. Silence was being read as health.",
+  "_how_it_works": "scripts/job-heartbeat.sh wraps every job and writes start/end/exit receipts that a dying job cannot forge or skip (trap-protected). scripts/nightly-watchdog.mjs compares THIS registry against reality: a job listed here that is not loaded, or loaded but has no fresh receipt, or has a receipt with a non-zero exit, is a VIOLATION and gongs the phone. Absence of evidence is failure, never 'probably fine'.",
+  "_adding_a_job": "Add it here FIRST, then wrap its plist command in job-heartbeat.sh. A job not in this registry is unwatched by definition — that is the whole point of a registry rather than per-job good intentions.",
+  "heartbeatDir": "~/.cache/ruvnet-brain/heartbeats",
+  "jobs": [
+    {
+      "label": "com.ruvnet.brain-nightly",
+      "what": "Refreshes every RuvNet repo, rebuilds the brain, publishes the GitHub Release",
+      "schedule": "daily 03:15",
+      "maxAgeHours": 26,
+      "required": true,
+      "legacyLog": "logs/nightly.log"
+    },
+    {
+      "label": "com.ruvnet.brain-gists",
+      "what": "Pulls rUv's new gists into the brain and re-embeds when they change",
+      "schedule": "daily 21:47",
+      "maxAgeHours": 26,
+      "required": true,
+      "legacyLog": "logs/gists-nightly.log"
+    },
+    {
+      "label": "com.ruvnet.goldie-weekly",
+      "what": "Re-researches the cheapest/best models and refreshes the router catalog",
+      "schedule": "Mondays 07:30",
+      "maxAgeHours": 192,
+      "required": true,
+      "legacyLog": "logs/goldie.log"
+    },
+    {
+      "label": "com.ruvnet.model-refresh",
+      "what": "Refreshes the live model list (~/.claude/models.json) that the router prices against",
+      "schedule": "daily 09:00",
+      "maxAgeHours": 26,
+      "required": true
+    },
+    {
+      "label": "com.ruvnet.npm-token-renew",
+      "what": "Renews the npm publish token before it expires (silently lets publishing die if it stops)",
+      "schedule": "daily 03:33",
+      "maxAgeHours": 26,
+      "required": true,
+      "_was_blind": "THE PUREST CASE OF THE BUG. On a healthy day this script returns early and writes ZERO BYTES anywhere — its log and state file sat frozen 2+ days stale while it fired on schedule every night. 'Ran and did nothing (healthy)' was literally indistinguishable from 'never ran', ~76 days out of every 90. The heartbeat wrapper fixes this for free: the RECEIPT is written by the wrapper, so the job no longer has to remember to report."
+    },
+    {
+      "label": "com.stuartkerr.api-spend-watchdog",
+      "what": "Hourly guard against runaway API spend and agent bursts — the one that actually pages the phone",
+      "schedule": "hourly",
+      "maxAgeHours": 3,
+      "required": true,
+      "_note": "It has been pushing '4 scheduled jobs failing silently' every hour, correctly — but off launchctl's exit-code field, which CANNOT see a job that never ran. It alerts; it just can't see the hole. Now it is itself watched: nothing supervised the supervisor."
+    },
+    {
+      "label": "com.stuartkerr.ruflo-autoupdate",
+      "what": "Keeps the whole RuvNet/Ruflo npm stack current (npm i -g ~26 packages on @latest/@alpha)",
+      "schedule": "daily 03:30",
+      "maxAgeHours": 26,
+      "required": true,
+      "_note": "This is THE job that keeps rUv's stack fresh on this machine. It was unwatched until 2026-07-13 — the single most important update job here had no supervision at all."
+    },
+    {
+      "label": "io.ruv.auto-subscribe",
+      "what": "Hourly: installs RuvNet package updates the moment they publish",
+      "schedule": "hourly",
+      "maxAgeHours": 3,
+      "required": true
+    },
+    {
+      "label": "com.cognitum.ruvector-autoupdate",
+      "what": "Every 6h: git pull of ~/RuVector_Clean (the RuVector source the Rust crates build from)",
+      "schedule": "every 6h",
+      "maxAgeHours": 8,
+      "required": true,
+      "_note": "Its git stash pop has silently failed once (orphaned stash@{0} from 2026-06-28 — it swallowed local edits and nothing said so). The heartbeat now catches a non-zero exit; the orphaned stash still needs a human decision."
+    },
+    {
+      "label": "com.stuartkerr.clear-claude-tmp",
+      "what": "Every 3h: purges Claude Code task-output temp files older than 2 days (the dir hits ~800MB)",
+      "schedule": "every 3h",
+      "maxAgeHours": 5,
+      "required": true,
+      "_was_lying": "Its log line had the date BAKED IN at plist-write time — all 43 entries since 2026-04-06 were byte-identical. It worked; its log was a lie. Now a real script with a real $(date) and a real delete count."
+    },
+    {
+      "label": "com.ruvnet.nightly-watchdog",
+      "what": "Watches all of the above. Listed here so that IT is watched too — a watchdog nobody watches is the same blind spot one level up",
+      "schedule": "daily 09:00",
+      "maxAgeHours": 26,
+      "required": true
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "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": {
@@ -16,6 +16,7 @@
     "test:all": "npm run test:unit && npm run test:integration && npm test",
     "metaharness:receipts": "node scripts/metaharness-receipts.mjs",
     "route:cheap": "node scripts/route-cheap.mjs",
+    "route:receipt": "node scripts/dispatch-receipt.mjs",
     "metaharness:fix": "node scripts/fix-metaharness-memretrieve.mjs --apply",
     "metaharness:check": "node scripts/fix-metaharness-memretrieve.mjs --check",
     "eval": "node scripts/eval-brain.mjs",
@@ -25,7 +26,8 @@
     "embed:check": "node scripts/embed-verifier.mjs --check",
     "gists:index": "node scripts/ingest-gists.mjs --index-only",
     "gists:sync": "node scripts/ingest-gists.mjs && node kb/forge-big.mjs both --dir kb --name ruv-gists",
-    "test:integration": "vitest run tests/integration"
+    "test:integration": "vitest run tests/integration",
+    "substitution:check": "node scripts/no-silent-substitution.mjs"
   },
   "files": [
     "bin/install.mjs",
@@ -37,6 +39,8 @@
     "scripts/model-router-status.mjs",
     "scripts/model-router-outcome.mjs",
     "scripts/route-cheap.mjs",
+    "scripts/dispatch-receipt.mjs",
+    "scripts/metaharness-receipts.mjs",
     "scripts/codex-routed.sh"
   ],
   "engines": {
@@ -67,5 +71,8 @@
     "@metaharness/darwin": "~0.8.0",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "@metaharness/router": "^0.3.2"
   }
 }

package/scripts/dispatch-receipt.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// scripts/dispatch-receipt.mjs — make SUBAGENT routing visible.
+//
+// WHY THIS EXISTS (2026-07-13, Stuart: "the meta harness isn't really doing anything for me").
+// He was right, and the receipts log proved it: 3 entries, all of them test pings, $0.018 saved in
+// the router's entire life. Two separate faults hid behind that number:
+//   1. BEHAVIOR — mechanical work was being done inline in the main loop instead of dispatched.
+//   2. MEASUREMENT — the biggest lever wrote no receipt AT ALL. A Claude Code subagent INHERITS the
+//      main-loop model unless explicitly overridden, so a fan-out of five agents on a Fable session
+//      is five Fable agents. Overriding them to haiku is the single largest saving available — and
+//      route-cheap.mjs only logged OpenRouter calls, so that saving was invisible even when it happened.
+// This closes #2 so #1 becomes auditable: the receipts file either grows with real work, or the
+// hard rule in SKILL.md is being ignored and the log says so.
+//
+// The baseline is the INHERITED model, not "frontier" — that is the honest counterfactual. An
+// un-overridden subagent genuinely would have run on the session's model.
+//
+// Usage (call it right after the Agent/Task returns, with the REAL text sizes):
+//   node scripts/dispatch-receipt.mjs --model claude-haiku-4.5 --inherited claude-fable-5 \
+//        --task "sweep tests/ for machine-state deps" --in-chars 2400 --out-chars 9100
+//
+// Costs are estimates (chars/4 tokens x live-verified $/Mtok) and are labeled "est." everywhere.
+// Unknown model or unknown baseline → NO receipt, non-zero exit. Never invent a savings number.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CLAUDE_TIERS, PRICING, estTokens, estimateCosts, receiptLine, receiptsPath, priceOf } from './route-cheap.mjs';
+
+// Default input share when only a MEASURED TOTAL is known. A subagent's tokens are dominated by input
+// (it re-reads files and tool output on every turn); its final report is small. 0.9 is an assumption,
+// not a measurement, so it is NAMED in the receipt's token_source and overridable with --split.
+const DEFAULT_INPUT_SHARE = 0.9;
+
+export function parseArgs(argv) {
+  const args = { model: 'claude-haiku-4.5', inherited: 'claude-opus-4.8', class: 'mechanical' };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (['--model', '--inherited', '--task', '--class', '--in-chars', '--out-chars', '--label', '--total-tokens', '--split'].includes(k)) {
+      args[k.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = argv[++i];
+    }
+  }
+  return args;
+}
+
+/**
+ * Token sizing, in descending order of honesty:
+ *   1. --total-tokens N  → the harness REPORTED this agent's real usage. Split by --split (named).
+ *   2. --in-chars/--out-chars → chars/4 estimate of the text we actually sent/received.
+ *   3. the task text alone → weakest; use only when nothing else is known.
+ * Why this matters: a subagent that reads 40 files burns ~20x the tokens its prompt+report suggest.
+ * Sizing it from the prompt alone would UNDERSTATE the saving by that factor and make real routing
+ * look pointless — the same "it isn't doing anything" trap, just with the error flipped.
+ */
+export function sizeTokens(args) {
+  const total = Number(args.totalTokens);
+  if (total > 0) {
+    const share = Number(args.split) > 0 && Number(args.split) < 1 ? Number(args.split) : DEFAULT_INPUT_SHARE;
+    return {
+      inTok: Math.round(total * share),
+      outTok: Math.round(total * (1 - share)),
+      source: `measured total ${total} tok, assumed ${Math.round(share * 100)}/${Math.round((1 - share) * 100)} in/out split`,
+    };
+  }
+  if (Number(args.inChars) || Number(args.outChars)) {
+    return {
+      inTok: Number(args.inChars) ? estTokens('x'.repeat(Number(args.inChars))) : 0,
+      outTok: Number(args.outChars) ? estTokens('x'.repeat(Number(args.outChars))) : 0,
+      source: 'chars/4 est',
+    };
+  }
+  return { inTok: estTokens(args.task || ''), outTok: 0, source: 'chars/4 est (prompt only — likely an undercount)' };
+}
+
+/** Build the receipt row. Returns null when either model is unpriced — caller must not fabricate. */
+export function buildReceipt(args, now) {
+  if (!priceOf(args.model) || !priceOf(args.inherited)) return null;
+  const { inTok, outTok, source } = sizeTokens(args);
+  const costs = estimateCosts(args.model, inTok, outTok, args.inherited);
+  if (!costs) return null;
+  return {
+    ts: now,
+    task_class: args.class,
+    task: (args.task || args.label || '(unlabeled subagent dispatch)').slice(0, 200),
+    model: args.model,
+    inherited: args.inherited,
+    est_in_tokens: inTok,
+    est_out_tokens: outTok,
+    est_cost: costs.cost,
+    est_frontier_cost: costs.frontier, // same schema key as route-cheap receipts; here = inherited-model cost
+    saved: costs.saved,
+    frontier_ref: args.inherited,
+    token_source: source,
+    source: 'claude-subagent',
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const known = [...Object.keys(CLAUDE_TIERS), ...Object.keys(PRICING)].join(', ');
+  const receipt = buildReceipt(args, new Date().toISOString());
+  if (!receipt) {
+    console.error(`dispatch-receipt: unpriced model ("${args.model}") or baseline ("${args.inherited}") — refusing to invent savings. Known: ${known}`);
+    process.exit(2);
+  }
+  const file = receiptsPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(receipt) + '\n');
+  console.log(receiptLine(receipt.model, { cost: receipt.est_cost, frontier: receipt.est_frontier_cost, saved: receipt.saved, ref: receipt.inherited }));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/metaharness-receipts.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// scripts/metaharness-receipts.mjs — plain-language routing receipts: what MetaHarness cheap-routing
+// actually did and what it saved. Reads the REAL log written by scripts/route-cheap.mjs at
+// ~/.claude/metaharness/routing-receipts.jsonl (override: METAHARNESS_RECEIPTS env, used by tests).
+// No data → says so plainly. Never invents numbers (all costs are estimates from verified
+// OpenRouter pricing + chars/4 token estimates, and are labeled "est.").
+//
+// Usage: node scripts/metaharness-receipts.mjs
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+export function receiptsPath() {
+  return (
+    process.env.METAHARNESS_RECEIPTS ||
+    path.join(os.homedir(), '.claude', 'metaharness', 'routing-receipts.jsonl')
+  );
+}
+
+// Parse the JSONL log. Corrupt lines are skipped (counted), never guessed at.
+export function loadReceipts(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { rows: [], skipped: 0 };
+  }
+  const rows = [];
+  let skipped = 0;
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const r = JSON.parse(line);
+      if (typeof r.saved === 'number' && r.model) rows.push(r);
+      else skipped++;
+    } catch {
+      skipped++;
+    }
+  }
+  return { rows, skipped };
+}
+
+const fmt$ = (n) => `$${n < 0.01 ? n.toFixed(5) : n.toFixed(4)}`;
+
+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 body = rows.map((r) => [
+    (r.ts || '').replace('T', ' ').slice(0, 16),
+    r.source === 'claude-subagent' ? 'subagent' : '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),
+  ]);
+  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('  ');
+
+  const totalCost = rows.reduce((s, r) => s + (r.est_cost || 0), 0);
+  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) : '?';
+
+  // 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 subagents = rows.filter((r) => r.source === 'claude-subagent').length;
+
+  return [
+    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)`,
+    '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.',
+  ].join('\n');
+}
+
+function main() {
+  const file = receiptsPath();
+  const { rows, skipped } = loadReceipts(file);
+  console.log(`MetaHarness routing receipts — ${file}`);
+  console.log('');
+  console.log(formatTable(rows));
+  if (skipped) console.log(`(${skipped} corrupt line(s) skipped)`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/model-router-engine.mjs

@@ -39,7 +39,9 @@ import { estTokens } from './route-cheap.mjs'; // reuse the verified char/4 esti
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const CONFIG_DIR = path.join(os.homedir(), '.claude', 'model-router');
-const CATALOG_PATH = path.join(CONFIG_DIR, 'catalog.json');
+// Overridable for hermetic tests + CI (runners have no ~/.claude): the 2026-07-12 CI redness was
+// exactly this — tests that silently depended on one developer's machine state.
+const CATALOG_PATH = process.env.MODEL_ROUTER_CATALOG || path.join(CONFIG_DIR, 'catalog.json');
 const POLICY_USER = path.join(CONFIG_DIR, 'policy.mjs');
 const POLICY_DEFAULT = path.join(CONFIG_DIR, 'policy.default.mjs');
 const DECISIONS_LOG =

package/scripts/route-cheap.mjs

@@ -40,6 +40,22 @@ export const PRICING = {
 };
 export const FRONTIER = { name: 'claude-opus-4.8', in: 5.0, out: 25.0 };
 
+// Claude tiers — $/Mtok, verified live from the OpenRouter /models API 2026-07-13.
+// These are NOT routed through here (Claude Code's own Agent/Task tool spawns them). They are priced
+// so a SUBAGENT dispatch can get a real receipt: until 2026-07-13 the single biggest routing lever —
+// every subagent inherits the main-loop model unless told otherwise — wrote no receipt at all, so the
+// whole router looked unused. It WAS unused; it was also unmeasurable. Both had to be fixed.
+// The spread is the whole argument: fable-5 costs 10x haiku-4.5 for identical mechanical work.
+export const CLAUDE_TIERS = {
+  'claude-haiku-4.5': { in: 1.0, out: 5.0 },
+  'claude-sonnet-5': { in: 2.0, out: 10.0 },
+  'claude-opus-4.8': { in: 5.0, out: 25.0 },
+  'claude-fable-5': { in: 10.0, out: 50.0 },
+};
+
+/** Price lookup across both tables. Unknown model → null (never invent a savings number). */
+export const priceOf = (model) => PRICING[model] || CLAUDE_TIERS[model] || null;
+
 export function receiptsPath() {
   return (
     process.env.METAHARNESS_RECEIPTS ||
@@ -50,18 +66,23 @@ export function receiptsPath() {
 // Honest token estimate: ~4 chars/token. Labeled "est." everywhere — never presented as measured.
 export const estTokens = (text) => Math.max(1, Math.ceil((text || '').length / 4));
 
-export function estimateCosts(model, inTokens, outTokens) {
-  const p = PRICING[model];
-  if (!p) return null; // unknown model → no receipt rather than an invented number
+// `ref` = what this task WOULD have run on. For a cheap OpenRouter call that's the frontier default;
+// for a subagent it's the model the agent would have INHERITED (i.e. the main-loop model), which is
+// the only honest baseline — an un-overridden subagent really does run on whatever the session is on.
+export function estimateCosts(model, inTokens, outTokens, ref = FRONTIER.name) {
+  const p = priceOf(model);
+  const r = priceOf(ref);
+  if (!p || !r) return null; // unknown model → no receipt rather than an invented number
   const cost = (inTokens * p.in + outTokens * p.out) / 1e6;
-  const frontier = (inTokens * FRONTIER.in + outTokens * FRONTIER.out) / 1e6;
-  return { cost, frontier, saved: frontier - cost };
+  const frontier = (inTokens * r.in + outTokens * r.out) / 1e6;
+  return { cost, frontier, saved: frontier - cost, ref };
 }
 
 const fmt$ = (n) => `$${n < 0.01 ? n.toFixed(5) : n.toFixed(4)}`;
 
 export function receiptLine(model, costs) {
-  return `\x1b[2m⚡ MetaHarness: routed to ${model} (est. ${fmt$(costs.cost)} vs ${fmt$(costs.frontier)} frontier — saved ~${fmt$(costs.saved)})\x1b[0m`;
+  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`;
 }
 
 // Load OPENROUTER_API_KEY from ruvnet-brain/.env if not already in env. Value never printed/logged.