ruvnet-brain 2.1.0 → 2.4.3

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 2.1.0 — updated 2026-07-10 08:15 EDT](https://img.shields.io/badge/version_2.1.0-updated_2026--07--10_08:15_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.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)
 
 **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.**
 
@@ -19,7 +19,7 @@
 > **Three independent things version separately here — by design, not drift. Every number below is live (read straight from its real source, never hand-typed), so none of them can go stale:**
 > - **`plugin`** (badge above) — the Claude Code plugin itself: SKILL.md, the grounding hooks, the MCP server. Read live from [`plugin/.claude-plugin/plugin.json`](plugin/.claude-plugin/plugin.json). Updates often — this is where behavior fixes land.
 > - **`installer (npm)`** (badge above) — the `npx ruvnet-brain` setup script. Read live from the [npm registry](https://www.npmjs.com/package/ruvnet-brain). Only moves when the installer script itself changes — rare.
-> - **Brain Release** (the downloadable 512MB knowledge bundle, linked from the "download" badge above) — always resolves to [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest), currently `v0.5.0-dev`. Only moves when the underlying knowledge base is rebuilt — separate again from the two above.
+> - **Brain Release** (the downloadable 512MB knowledge bundle, linked from the "download" badge above) — always resolves to [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest) (the nightly publishes fresh bundles as the corpus grows). Only moves when the underlying knowledge base is rebuilt — separate again from the two above.
 > - **Update an installed brain once:** `npx ruvnet-brain --update` — runs the bundle's own self-updater (backs up first, re-verifies, fails loud instead of half-applying).
 > - **Nightly auto-update is OFF by default:** `npx ruvnet-brain --enable-nightly` schedules it (macOS LaunchAgent, 03:47); `npx ruvnet-brain --disable-nightly` removes it; Linux/Windows get the cron line documented in the bundle's `forge-update.mjs`.
 > - **Either way, your copy only advances when a new Release is published** — the updater pulls `releases/latest`, so running it between releases is a safe no-op.
@@ -36,7 +36,24 @@
 
 ---
 
-## What's new in 2.0
+## What's new in 2.4 — it routes your money, and it can never break silently
+
+**Shipped 2026-07-12, every piece proven live before it was written down:**
+
+- **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.
+
+![MetaHarness routing — your subscriptions first, always](assets/diagrams/router-path.svg)
+
+<details>
+<summary><b>Earlier &#8212; what 2.0 proved</b> &#183; the release where the brain stopped taking its own word for anything: 32 verified repos, a 120-question fail-closed eval gate, ~90% cheaper per-turn injection, and an 8-dimension evidence-backed scorecard (55 &#8594; 83 in two days). <i>Expand for the receipts.</i></summary>
+
+### What's new in 2.0
 
 **2.0 is the release where the brain got bigger — and, more importantly, stopped taking its own word for anything.** Every number below regenerates from an artifact on disk; the claims ledger (`node scripts/claims-verify.mjs`) re-checks the advertised ones in CI:
 
@@ -57,7 +74,7 @@ The depth jump wasn't tuning — it was two pipeline root-causes fixed for good:
 
 ### The scorecard — 8 dimensions, self-scored /100, every deduction evidenced — 2026-07-10 (evening re-score)
 
-| Dimension | v1 (2026-07-09) | v2.0 (current) | Δ | What moved it |
+| Dimension | v1 (2026-07-09) | v2.0 (2026-07-10) | Δ | What moved it |
 |---|---:|---:|---:|---|
 | End-user experience | 54 | 83 | +29 | One-command install now offers nightly self-updates (default yes); the page lives on isovision.ai; publishing renews itself |
 | Knowledge corpus | 71 | 88 | +17 | 24→32 verified repos; a 72/72 embeds-and-reads QA gate; full source depth restored — flagship went 0→2,996 source bodies |
@@ -71,6 +88,8 @@ The depth jump wasn't tuning — it was two pipeline root-causes fixed for good:
 
 These are self-scores under a hard rule: **every deduction requires specific evidence, and a known architectural flaw caps a dimension at ≤70 until the flaw is fixed** — *acting like rUv* spent the morning capped for its memory-layer flaw; the flaw was root-caused and fixed with proofs, the cap lifted, and it re-scored 72. Overall **55 → 83 in two days**, each number regenerating from a stored receipt — and the same scoring that produced these blocked a release mid-day. **That's why they're credible: scores you can trust beat scores that flatter.**
 
+</details>
+
 **The honest small print, kept visible:** warm query is ~21 s on the large corpus (it grew with depth; candidate dedup/pruning is the next optimization) · the 8 newest repos are findable by name but don't yet have primers/capability cards for described-need routing (coming) · the Windows CI job is new and unproven until its first green run.
 
 ---
@@ -159,7 +178,7 @@ You install once. After that, three mechanisms keep you on the current brain wit
 
 ## ✨ What the knowledge bundle knows — the stack _down to the code_
 
-Earlier bundles knew only the **docs and architecture**. v0.5 began re-indexing the code-rich repos to **full function bodies**, against each repo's real source layout — so “how is this actually implemented?” returns the implementation, not a summary. The table below is that v0.5 depth jump, kept as the before/after receipt; **2.0 went further still** — flagship `ruvector` alone now carries 28,018 passages and 2,996 full bodies (see [What's new in 2.0](#whats-new-in-20)):
+Earlier bundles knew only the **docs and architecture**. v0.5 began re-indexing the code-rich repos to **full function bodies**, against each repo's real source layout — so “how is this actually implemented?” returns the implementation, not a summary. The table below is that v0.5 depth jump, kept as the before/after receipt; **2.0 went further still** — flagship `ruvector` alone now carries 28,018 passages and 2,996 full bodies (see the "what 2.0 proved" foldout near the top):
 
 | Repo | Full-body code passages (v0.5) | |
 |---|---:|---|
@@ -175,7 +194,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,012 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,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.
 
 ![RuvNet Brain architecture pipeline](assets/diagrams/architecture-pipeline.svg)
 
@@ -285,7 +304,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,012 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,011 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.
@@ -303,14 +322,22 @@ This project versions in the open (see the live badge up top for the exact plugi
 - `explainer/` — the source of the [live explainer](https://isovision.ai/ruvnet-brain/).
 - `SPEC.md` · `PROGRESS.md` — the master spec and the living, timestamped build log.
 
-The brain binaries ship via the [Release](https://github.com/stuinfla/ruvnet-brain/releases/tag/v0.5.0-dev), not git — a fresh clone is lightweight; `npx` fetches the 512 MB bundle.
+The brain binaries ship via the [Release](https://github.com/stuinfla/ruvnet-brain/releases/latest), not git — a fresh clone is lightweight; `npx` fetches the 512 MB bundle.
+
+---
+
+## Community
+
+- **Tell us how it went — one command:** `npx ruvnet-brain --feedback` prefills a [Discussion](https://github.com/stuinfla/ruvnet-brain/discussions) with your version + a 3-line health summary (you see exactly what's in it; never your queries, code, or paths) and opens it in your browser.
+- **Questions, ideas, show-and-tell:** [Discussions](https://github.com/stuinfla/ruvnet-brain/discussions) · bugs go to [issues](https://github.com/stuinfla/ruvnet-brain/issues) — new issues and PRs page the maintainer's phone in real time, so first response is typically within 1 business day.
+- **Contributors get credited:** merged PRs land in [`CONTRIBUTORS.md`](CONTRIBUTORS.md) — the two-signal hook gate and the `/brain-build` contract both started as user field reports. House rules: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md); build/test map: [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ---
 
 ## Links
 
 - **▶ Live explainer:** https://isovision.ai/ruvnet-brain/
-- **Download / Release:** https://github.com/stuinfla/ruvnet-brain/releases/tag/v0.5.0-dev
+- **Download / Release:** https://github.com/stuinfla/ruvnet-brain/releases/latest
 - **rUv's RuvNet org:** https://github.com/ruvnet
 - **Built by:** [Stuart Kerr — Isovision.ai](https://isovision.ai)
 

package/bin/install.mjs

@@ -65,6 +65,7 @@ const FLAG_DOCTOR = argv.includes('--doctor');
 const FLAG_NO_VERIFY = argv.includes('--no-verify');
 const FLAG_PIN = argv.includes('--pin'); // skip the latest-check, use the bundled default
 const FLAG_DEMO = argv.includes('--demo'); // guided, real (non-fabricated) walkthrough of the brain in action
+const FLAG_FEEDBACK = argv.includes('--feedback'); // prefill a GitHub Discussion (version + health, nothing private) and open it
 // ── freshness flags — invoke/schedule the SELF-UPDATER the bundle already ships (kb/forge-update.mjs) ──
 const FLAG_UPDATE = argv.includes('--update'); // one-shot: pull the latest Release bundle into the installed brain now
 const FLAG_ENABLE_NIGHTLY = argv.includes('--enable-nightly'); // schedule that update nightly (macOS LaunchAgent)
@@ -491,11 +492,9 @@ function wirePlugin() {
 }
 
 // ── step: verify the install is REAL (counts — never take "installed" on faith) ──────────────────
-function verifyInstall(cacheDir) {
-  step(
-    'Verifying the brain is real and reachable',
-    "you should never have to trust the word \"installed\" — here's the proof on disk",
-  );
+// Shared state-gatherer behind verifyInstall / --doctor / --feedback: what is REALLY on disk.
+// Pure read, never prints — callers decide how to narrate (or, for --feedback, how to report) it.
+function gatherInstallState(cacheDir) {
   let repos = 0;
   try {
     repos = fs
@@ -504,14 +503,29 @@ function verifyInstall(cacheDir) {
   } catch {
     /* ignore */
   }
+  return {
+    repos,
+    // A bare node_modules dir is not enough — on 2026-07-12 the dir test passed conceptually while
+    // the embedder was gone and every search failed. Check the two load-bearing packages directly.
+    reader:
+      fs.existsSync(path.join(cacheDir, 'node_modules', '@xenova', 'transformers', 'package.json'))
+      && fs.existsSync(path.join(cacheDir, 'node_modules', '@ruvector')),
+    mcp: fs.existsSync(path.join(cacheDir, 'forge-mcp-all.mjs')),
+  };
+}
+
+function verifyInstall(cacheDir) {
+  step(
+    'Verifying the brain is real and reachable',
+    "you should never have to trust the word \"installed\" — here's the proof on disk",
+  );
+  const { repos, reader, mcp } = gatherInstallState(cacheDir);
   if (repos > 0) ok(`${repos} RuvNet repos indexed (vector stores present on disk)`);
   else warn(`no .rvf stores found in ${cacheDir} — the brain may be incomplete (re-run with --force)`);
 
-  const reader = fs.existsSync(path.join(cacheDir, 'node_modules'));
   if (reader) ok('local reader installed (vector reads happen offline — no cloud, no API key)');
-  else warn('reader deps missing — re-run the installer');
+  else warn(`reader deps missing — every search WILL fail until fixed: cd ${cacheDir} && npm i`);
 
-  const mcp = fs.existsSync(path.join(cacheDir, 'forge-mcp-all.mjs'));
   if (mcp) ok('search_ruvnet server present (this is what Claude calls to ground answers)');
   else warn('forge-mcp-all.mjs missing — the brain unpacked incompletely');
 
@@ -759,6 +773,99 @@ async function doctor() {
   );
 }
 
+// ── `--feedback`: the easiest possible way to tell us how it went ────────────────────────────────
+// Composes a prefilled GitHub Discussion — brain version, platform, install age, and a 3-line
+// --doctor-style health summary — SHOWS the user exactly what's in it (that's all there is), prints
+// the URL, and opens the browser. Deliberately boring on privacy: no queries, no code, no paths,
+// no env — every field is generic. The user still writes and posts the actual feedback themselves.
+const DISCUSSIONS_URL = `https://github.com/${REPO}/discussions`;
+
+function installedBrainVersion(cacheDir) {
+  // Same read the telemetry ping uses: the bundle stamps its Release tag into SOURCE.json.
+  // "unknown" is honest for a locally-built or pre-stamping bundle — never guess a tag.
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(cacheDir, 'SOURCE.json'), 'utf8'));
+    const v = String(j.releaseTag || '');
+    if (/^[A-Za-z0-9._-]{1,32}$/.test(v)) return v;
+  } catch { /* fall through */ }
+  return 'unknown';
+}
+
+function installAgeLine(cacheDir) {
+  // SOURCE.json's mtime is when the bundle last landed here (install or self-update) — say which.
+  for (const f of ['SOURCE.json', 'forge-mcp-all.mjs']) {
+    try {
+      const days = Math.floor((Date.now() - fs.statSync(path.join(cacheDir, f)).mtimeMs) / 86400000);
+      return days === 0 ? 'installed/updated today' : `installed/updated ${days} day${days === 1 ? '' : 's'} ago`;
+    } catch { /* try the next anchor file */ }
+  }
+  return 'not installed here';
+}
+
+// The last-3-lines-of---doctor health summary, from the SAME state --doctor reads (gatherInstallState
+// + detectEnvironment) — counts and presence only, never a path.
+function feedbackHealthLines(cacheDir) {
+  const s = gatherInstallState(cacheDir);
+  const env = detectEnvironment();
+  const allGreen = s.repos > 0 && s.reader && s.mcp;
+  return [
+    `${s.repos} repo stores on disk · reader ${s.reader ? 'ok' : 'MISSING'} · search_ruvnet ${s.mcp ? 'ok' : 'MISSING'}`,
+    `toolkit: Ruflo ${env.ruflo ? 'present' : 'not found'} · RuVector ${env.ruvector ? 'present' : 'not found'} · claude CLI ${env.claude ? 'present' : 'not found'}`,
+    allGreen ? 'verdict: Healthy — installed and reachable' : 'verdict: Needs attention — re-run npx ruvnet-brain',
+  ];
+}
+
+function openInBrowser(url) {
+  if (TEST_MODE) return false; // tests: print the URL, never open anything
+  try {
+    // rundll32 on Windows (not `cmd /c start`): the URL's & would need cmd-metachar escaping there.
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]]
+      : IS_WIN ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : ['xdg-open', [url]];
+    const r = spawnSync(cmd, args, { stdio: 'ignore', shell: false });
+    return !r.error && r.status === 0;
+  } catch { return false; }
+}
+
+function runFeedback() {
+  printBanner('feedback');
+  const cacheDir = resolvedKbDir();
+  const brainV = installedBrainVersion(cacheDir);
+  let installerV = 'unknown';
+  try { installerV = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version || 'unknown'; } catch { /* honest */ }
+  const health = feedbackHealthLines(cacheDir);
+
+  const title = `Feedback: RuvNet Brain ${brainV} on ${process.platform}`;
+  const body = [
+    `**Brain version:** ${brainV} · installer ${installerV}`,
+    `**Platform:** ${process.platform}/${process.arch} · node ${process.version}`,
+    `**Install age:** ${installAgeLine(cacheDir)}`,
+    `**Health (--doctor, last 3 lines):**`,
+    '```',
+    ...health,
+    '```',
+    '',
+    '**What happened / what you\'d like:**',
+    '_(your words here — what you asked, what you got, what you wish it did)_',
+    '',
+  ].join('\n');
+
+  console.log(c.dim('\nThis prefills a public GitHub Discussion with the block below — and NOTHING else.'));
+  console.log(c.dim('No queries, no code, no paths. You review it on GitHub and post it yourself.\n'));
+  console.log(body.split('\n').map((l) => `    ${c.dim('│')} ${l}`).join('\n'));
+
+  const url = `${DISCUSSIONS_URL}/new?category=general&title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`;
+  console.log(`\n  ${c.bold('Prefilled Discussion URL')} ${c.dim('(open it anywhere if no browser pops up):')}`);
+  console.log(`  ${url}\n`);
+
+  if (TEST_MODE) {
+    warn('RUVNET_BRAIN_TEST=1 — not opening a browser (URL printed above)');
+    return;
+  }
+  if (openInBrowser(url)) ok('opened in your browser — say anything, even one line helps');
+  else info(`couldn't open a browser here — copy the URL above into any browser to post`);
+}
+
 // ── `--update` / `--enable-nightly` / `--disable-nightly`: end-user freshness controls ────────────
 // The brain bundle SHIPS its own self-updater (forge-update.mjs, right in the KB dir): it pulls the
 // canonical Release bundle, backs the current copy up, extracts, and re-verifies with forge-guard —
@@ -922,6 +1029,88 @@ function disableNightly() {
   info(`re-enable any time:  ${c.bold('npx ruvnet-brain --enable-nightly')}`);
 }
 
+// ── spend guard: the alarm that catches a runaway agentic fleet BEFORE it drains a card ───────────
+// WHY THIS SHIPS: on 2026-07-09 an automated QE fleet spawned 374+ headless agents, each billing the
+// Anthropic API on Sonnet, and burned ~$1,600 SILENTLY while a paid Max plan sat unused — nothing
+// alerted. That is the exact failure this guard makes impossible: a tiny hourly watchdog that trips
+// the moment automated agents flood a project (burst detector, no key needed) or — with
+// ANTHROPIC_ADMIN_KEY — daily API spend crosses a threshold. Alert-only; it NEVER spends. Same
+// non-fatal, TEST_MODE-aware, default-yes contract as the nightly updater above.
+const SPEND_GUARD_LABEL = 'com.ruvnet.spend-watchdog';
+const spendGuardScriptPath = () => path.join(os.homedir(), '.claude', 'scripts', 'api-spend-watchdog.mjs');
+const spendGuardPlistPath = () => path.join(os.homedir(), 'Library', 'LaunchAgents', `${SPEND_GUARD_LABEL}.plist`);
+
+function enableSpendGuard() {
+  // The npx checkout is ephemeral, so copy the bundled watchdog to a persistent home the launchd
+  // job can point at for good.
+  const src = path.join(__dirname, 'api-spend-watchdog.mjs');
+  const dst = spendGuardScriptPath();
+  if (!fs.existsSync(src)) { warn('spend-watchdog source missing from this bundle — skipping (non-fatal)'); return 'no-source'; }
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.copyFileSync(src, dst);
+  ok(`installed the spend watchdog → ${c.bold(dst)}`);
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SPEND_GUARD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${process.execPath}</string>
+    <string>${dst}</string>
+  </array>
+  <key>StartInterval</key><integer>3600</integer>
+  <key>RunAtLoad</key><true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>SPEND_ALERT_USD</key><string>50</string>
+    <key>SPEND_BURST_AGENTS</key><string>20</string>
+  </dict>
+</dict>
+</plist>
+`;
+  const plistPath = spendGuardPlistPath();
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  fs.writeFileSync(plistPath, plist);
+  ok(`wrote ${c.bold(plistPath)} — runs hourly, alert-only`);
+
+  if (TEST_MODE) { warn('RUVNET_BRAIN_TEST=1 — skipping launchctl (plist written only)'); return 'test'; }
+  const uid = process.getuid();
+  spawnSync('launchctl', ['bootout', `gui/${uid}/${SPEND_GUARD_LABEL}`], { stdio: 'ignore' });
+  const boot = spawnSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath], { encoding: 'utf8' });
+  if (boot.status === 0) ok('spend watchdog is live — it warns you the moment a fleet runs away');
+  else { warn(`launchctl bootstrap failed (${(boot.stderr || '').trim() || `exit ${boot.status}`}) — the plist is in place;`); info(`load it:  ${c.bold(`launchctl bootstrap gui/${uid} ${plistPath}`)}`); }
+  return 'enabled';
+}
+
+// Exported (testable under RUVNET_BRAIN_IMPORT_ONLY=1, like offerNightly). Never throws — the caller
+// also guards, because a finished install must never be broken by an optional safety offer.
+export async function offerSpendGuard() {
+  if (FLAG_NO_NIGHTLY_PROMPT || TEST_MODE) return 'suppressed';
+  if (process.platform !== 'darwin') return 'unsupported';
+  if (fs.existsSync(spendGuardPlistPath())) { ok('spend watchdog already installed — runaway API spend will alert you'); return 'already-on'; }
+
+  step(
+    'One more safety net — a spend watchdog',
+    'agentic tools can bill the paid API in the background; this alarm catches a runaway before it drains your card',
+  );
+  info(`${c.bold('Strongly recommended:')} an hourly check that alerts you the moment an automated agent`);
+  info('fleet floods a project — the pattern that has quietly burned real money. Alert-only, never spends.');
+
+  if (!process.stdin.isTTY && !FLAG_YES) { info(`No terminal to prompt on — install it any time by re-running  ${c.bold('npx ruvnet-brain')}`); return 'recommended'; }
+  let yes = true;
+  if (!FLAG_YES) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(`    ${c.cyan('?')} Install the spend watchdog? ${c.dim('[Y/n]')} `, resolve));
+    rl.close();
+    yes = parseNightlyAnswer(answer);
+  }
+  if (!yes) { info(`No problem — install it any time by re-running  ${c.bold('npx ruvnet-brain')}`); return 'declined'; }
+  try { enableSpendGuard(); } catch (e) { warn(`spend guard install skipped: ${e.message}`); return 'error'; }
+  return 'enabled';
+}
+
 // ── step: offer nightly auto-updates at the end of a successful install (recommended, default YES) ──
 // Requirement: a default `npx ruvnet-brain` run must never leave the user unaware of nightly
 // auto-updates — it VERY CLEARLY recommends them, asks, and DEFAULTS TO YES. Before this, the
@@ -938,6 +1127,92 @@ export function parseNightlyAnswer(answer) {
 // suppression flags) is testable in-process under RUVNET_BRAIN_IMPORT_ONLY=1 without a real install.
 // Returns a status string; never throws (the caller also guards — a finished install must never
 // be broken by an optional offer).
+// ── MetaHarness router: config materialization + THIS user's subscription profile (2026-07-12) ──
+// Stuart's mandate: subscription-awareness must be per-user. Detect what the machine can PROVE
+// (Codex auth mode from ~/.codex/auth.json's SHAPE — never its secrets), ASK what it can't (Claude
+// plan tiers aren't probeable from disk), and RECORD both with their basis, so the router's
+// $0-floor never assumes a plan this user doesn't have (billing them) or misses one they do
+// (wasting it). Config templates ship in the npm package's config/; router tools are copied to
+// ~/.claude/model-router/bin/ because the npx run dir vanishes after install. Never overwrites
+// user-edited files. Non-fatal like every offer.
+export async function offerRouterProfile() {
+  if (TEST_MODE) return 'suppressed';
+  const routerDir = path.join(os.homedir(), '.claude', 'model-router');
+  const pkgRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+  step(
+    'MetaHarness model router — the right model for each task, cheapest first',
+    "your subscription models are $0 marginal; the router just needs to know which ones YOU have",
+  );
+
+  fs.mkdirSync(path.join(routerDir, 'bin'), { recursive: true });
+  for (const [src, dst] of [['catalog.template.json', 'catalog.json'], ['policy.default.mjs', 'policy.default.mjs']]) {
+    const s = path.join(pkgRoot, 'config', 'model-router', src);
+    const d = path.join(routerDir, dst);
+    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']) {
+    const s = path.join(pkgRoot, 'scripts', t);
+    if (fs.existsSync(s)) { fs.copyFileSync(s, path.join(routerDir, 'bin', t)); copied++; }
+  }
+  if (copied) {
+    try { fs.chmodSync(path.join(routerDir, 'bin', 'codex-routed.sh'), 0o755); } catch { /* not fatal */ }
+    ok(`${copied} router tools at ~/.claude/model-router/bin/ (stable path — the npx dir vanishes)`);
+  }
+
+  const profilePath = path.join(routerDir, 'profile.json');
+  if (fs.existsSync(profilePath)) { ok('subscription profile already exists — routing already uses it'); return 'already'; }
+
+  // Codex is the one subscription we can PROVE: OAuth tokens in auth.json = signed in with ChatGPT
+  // (Plus/Pro/Business all include Codex). An API key instead = metered per-token.
+  let codexAuth = null;
+  try {
+    const a = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.codex', 'auth.json'), 'utf8'));
+    codexAuth = a.tokens ? 'chatgpt' : a.OPENAI_API_KEY ? 'api-key' : null;
+  } catch { /* codex absent or not authed */ }
+
+  const today = new Date().toISOString().slice(0, 10);
+  // This installer's audience is Claude Code users — claude-code is available by definition.
+  let claudeSub = true;
+  let claudeBasis = `assumed: installing the Claude Code brain (${today}); confirm with model-router-setup.mjs --show`;
+  let codexSub = codexAuth === 'chatgpt';
+  let codexBasis =
+    codexAuth === 'chatgpt' ? `verified: ~/.codex/auth.json ChatGPT OAuth tokens (${today})`
+    : codexAuth === 'api-key' ? `verified: ~/.codex/auth.json API key — METERED, not subscription (${today})`
+    : `detected: codex not authed on this machine (${today})`;
+
+  if (process.stdin.isTTY && !FLAG_YES) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const q = (text) => new Promise((resolve) => rl.question(text, resolve));
+    const a1 = await q(`    ${c.cyan('?')} Do you have a Claude subscription (Pro or Max) covering your Claude Code use? ${c.dim('[Y/n]')} `);
+    claudeSub = !/^n/i.test((a1 || '').trim());
+    claudeBasis = `user-attested ${today}`;
+    if (codexAuth === 'chatgpt') {
+      info(`Codex: verified signed in with ChatGPT — your ChatGPT plan covers it ($0). Nothing to ask.`);
+    } else {
+      const a2 = await q(`    ${c.cyan('?')} Do you also use OpenAI's Codex CLI signed in with a ChatGPT subscription? ${c.dim('[y/N]')} `);
+      codexSub = /^y/i.test((a2 || '').trim());
+      codexBasis = `user-attested ${today}${codexSub && codexAuth !== 'chatgpt' ? ' (auth.json does not show ChatGPT login yet — run `codex login`)' : ''}`;
+    }
+    rl.close();
+  } else {
+    info('No interactive terminal — recording detections with labeled assumptions. Refine any time:');
+    info(`  ${c.bold('node ~/.claude/model-router/bin/model-router-setup.mjs')}`);
+  }
+
+  const profile = {
+    updated: today,
+    harnesses: {
+      'claude-code': { available: true, subscription: claudeSub, plan: claudeSub ? 'pro-or-max' : 'api-billed', basis: claudeBasis },
+      codex: { available: codexAuth !== null, subscription: codexSub, plan: codexAuth, basis: codexBasis },
+    },
+    keys: Object.fromEntries(['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'OPENROUTER_API_KEY', 'GOOGLE_API_KEY', 'GEMINI_API_KEY', 'XAI_API_KEY'].map((k) => [k, !!process.env[k]])),
+  };
+  fs.writeFileSync(profilePath, JSON.stringify(profile, null, 2) + '\n');
+  ok(`subscription profile saved — Claude Code: ${claudeSub ? 'subscription ($0)' : 'API-billed'}; Codex: ${codexSub ? 'subscription ($0)' : codexAuth === 'api-key' ? 'METERED' : 'not in use'}`);
+  return 'created';
+}
+
 export async function offerNightly() {
   // Suppressed outright: --no-nightly-prompt (the user said don't ask) and RUVNET_BRAIN_TEST=1
   // (tests must stay non-interactive and must never schedule anything).
@@ -1326,7 +1601,7 @@ function success({ cacheDir, isCustom, plugin, env, nightly }) {
   // One tasteful ask, at the moment the value was just delivered — never repeated by the plugin
   // more than once ever (see session-start.sh's stamped one-liner).
   console.log(`\n  ${c.bold('If it earns it:')} a GitHub star helps other people find the brain —`);
-  console.log(`    ${c.bold('https://github.com/stuinfla/ruvnet-brain')}   ${c.dim('· feedback/ideas: https://github.com/stuinfla/ruvnet-brain/discussions')}`);
+  console.log(`    ${c.bold('https://github.com/stuinfla/ruvnet-brain')}   ${c.dim('· feedback in one command: npx ruvnet-brain --feedback')}`);
 
   console.log(`\n  ${c.dim('You can\'t break anything — the plugin is disable-able and only acts on RuvNet-shaped work.')}`);
   console.log('');
@@ -1344,6 +1619,9 @@ Usage:
   npx github:stuinfla/ruvnet-brain         Same, but from the bleeding-edge GitHub commit
   npx ruvnet-brain --doctor   Health-check an existing install (green/red per part)
   npx ruvnet-brain --demo     Guided walkthrough — 2 real questions, real cited answers
+  npx ruvnet-brain --feedback Tell us how it went — prefills a GitHub Discussion with your brain
+                              version, platform, and a 3-line health summary (you see exactly
+                              what's in it; never your queries, code, or paths), then opens it
   npx ruvnet-brain --update   One-shot: pull the latest Release bundle into your installed brain
                               (runs the bundle's own forge-update.mjs --apply: backup + re-verify)
   npx ruvnet-brain --enable-nightly    Schedule that update nightly at 03:47 — macOS LaunchAgent;
@@ -1379,6 +1657,7 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   if (FLAG_HELP) return showHelp();
   if (FLAG_DOCTOR) return await doctor();
   if (FLAG_DEMO) return runDemo();
+  if (FLAG_FEEDBACK) return runFeedback();
   if (FLAG_UPDATE) return runUpdate();
   if (FLAG_ENABLE_NIGHTLY) return enableNightly();
   if (FLAG_DISABLE_NIGHTLY) return disableNightly();
@@ -1462,6 +1741,13 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   // and asking, DEFAULTING TO YES (TTY + macOS + not already on). Non-fatal like every other offer.
   let nightly = 'skipped';
   try { nightly = await offerNightly(); } catch { /* never let the offer break a finished install */ }
+  // A spend watchdog, offered right after the updater: agentic tools can bill the paid API in the
+  // background (a real 2026-07-09 incident burned ~$1,600 silently). This alarm makes that loud.
+  // Non-fatal like every other offer — a safety net can never break a finished install.
+  try { await offerSpendGuard(); } catch { /* a safety offer must never break a finished install */ }
+  // Per-user subscription profile + router config (Stuart's mandate 2026-07-12: detect, ASK,
+  // verify, record — never assume this user's subscriptions match anyone else's).
+  try { await offerRouterProfile(); } catch { /* router setup must never break a finished install */ }
   // Anonymous usage counts — OPT-IN, asked once ever, right after the nightly offer. Same rule:
   // an optional offer can never break a finished install.
   try { await offerTelemetry(cacheDir); } catch { /* fail-private: unanswered = OFF */ }