ruvnet-brain 2.0.0 → 2.4.1

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 2.0.0 — updated 2026-07-10 08:15 EDT](https://img.shields.io/badge/version_2.0.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.1 — updated 2026-07-12 20:50 EDT](https://img.shields.io/badge/version_2.4.1-updated_2026--07--12_20:50_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,6 +36,18 @@
 
 ---
 
+## What's new in 2.3–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 (2.3)** — 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 2.2's 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.
+
 ## 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:
@@ -48,7 +60,7 @@
 | **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 |
 | **Token cost** | 6,183 bytes injected per hook turn · zero self-measurement | **684 bytes (~90% cut)** with an eval-PASS proving zero quality loss · a live token meter measuring real bytes/tokens per prompt class · ~27% faster repeat queries via the KB cache |
 | **rUv's gists** | not indexed | **437 gists** indexed with per-chunk freshness/provenance banners, refreshed nightly with cost-disciplined skip |
-| **Reliability** | claims were prose | **claims ledger** (5 marketing claims mechanically re-verified in CI) · integration tests in CI incl. Linux · a Windows CI job · an honest coverage denominator (all source files) |
+| **Reliability** | claims were prose | **claims ledger** (6 marketing claims mechanically re-verified in CI) · integration tests in CI incl. Linux · a Windows CI job · an honest coverage denominator (all source files) |
 | **Autonomy** | hooks asked questions to an empty room — the #1 real-user complaint | **`/loop` contract** — checkpoint / resume / done-criteria; hooks detect autonomous mode and stop asking — 10 mutation-verified tests |
 | **Publishing** | manual npm token · a nightly release PATH bug | **self-renewing npm token** (launchd daemon, proven end-to-end) · PATH bug root-caused and cured |
 | **Memory layer** | silent SQLite corruption · searches returning 0 · invisible flywheel patterns | **3 root-caused fixes** (an ABI-mismatched binary falling back to WAL-blind whole-file overwrites; keys that were never scored; a split-store display bug) — plus **6 exact patches queued upstream to ruflo** |
@@ -126,6 +138,8 @@ That single command runs the whole setup, narrating _what it's doing and why_ at
 
 > Want the bleeding-edge installer, even ahead of the last npm publish? `npx github:stuinfla/ruvnet-brain` always runs straight off the latest GitHub commit.
 
+> **Anonymous usage counts — opt-in, counts only.** At the end of the install you're asked once: _"Share anonymous usage counts (installs/searches — never your queries or code)?"_ If you say yes, the only things ever transmitted are event counts (`install` / `search` / `session`) plus the bundle version — batched to at most one ping per machine per day. **Never** your queries, code, repo names, or paths; the entire client is one readable file (`kb/telemetry-ping.mjs`). Your answer is a plain-text file you can read or flip any time (`~/.cache/ruvnet-brain/.telemetry-consent`), and `npx ruvnet-brain --no-telemetry` declines without being asked. Found it useful? [Star the repo](https://github.com/stuinfla/ruvnet-brain) or [leave feedback in Discussions](https://github.com/stuinfla/ruvnet-brain/discussions).
+
 <details><summary>Manual install (what the one-liner automates)</summary>
 
 ```bash
@@ -149,7 +163,7 @@ You install once. After that, three mechanisms keep you on the current brain wit
 
 - **Consent-gated auto-update heartbeat** (the `SessionStart` hook, `plugin/scripts/session-start.sh`). The **first** time the plugin runs on a machine it asks you **once** whether it may keep itself updated in the background — a security-conscious opt-in, because self-update can change the model's own instructions. Your answer is remembered (`~/.cache/ruvnet-brain/.auto-update-pref`) and never asked again. On each session start it does a rate-limited (~15 min) 3s-capped check of the live GitHub `plugin.json`. If a newer plugin version exists **and** you opted in, it downloads it in the background through Claude Code's own trusted marketplace path — but the new version is **staged, not active**: Claude Code only loads plugins at process start, so **this session keeps running the version it started with** until you restart (`claude --continue` brings your conversation right back on the new version). If you declined, it just tells you the command to run. The 512 MB knowledge bundle is handled more conservatively — **detect + notify only**, never auto-applied, because the bundle isn't cryptographically signed yet and applying it would overwrite executable tool files (SEC-0010 #6).
 
-- **Stack watchdog status footer** (the `UserPromptSubmit` hook's always-on Gate 0, `plugin/scripts/ground-ruvnet.sh`). Every response ends with one dim status line — e.g. `🧠 RuvNet Brain v2.0.0 · Ruflo: yes · AgentDB memory: on` — read from **filesystem ground truth**, not impressions. The version shown is always the one **actually loaded in memory** for this session; if a newer version is staged awaiting a restart, the line says so plainly (`… vX staged, restart to load`). So you never have to wonder whether the brain is on, which version is acting, or whether project memory is wired.
+- **Stack watchdog status footer** (the `UserPromptSubmit` hook's always-on Gate 0, `plugin/scripts/ground-ruvnet.sh`). Every response ends with one dim status line — e.g. `🧠 RuvNet Brain v2.0.1 · Ruflo: yes · AgentDB memory: on` — read from **filesystem ground truth**, not impressions. The version shown is always the one **actually loaded in memory** for this session; if a newer version is staged awaiting a restart, the line says so plainly (`… vX staged, restart to load`). So you never have to wonder whether the brain is on, which version is acting, or whether project memory is wired.
 
 - **Nightly publish → `releases/latest` chain** (`scripts/self-update.mjs --publish`, run by the `deploy/com.ruvnet.brain-nightly.plist` LaunchAgent at 03:15). The nightly rebuilds only the repos whose upstream changed, and **if anything was rebuilt** it bumps the product version, cuts a GitHub Release, and advances [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest). Plugin and knowledge bundle move under **one** version number, so the heartbeat above picks up both automatically. (The LaunchAgent is not auto-installed — enabling a system scheduler needs explicit owner approval.)
 
@@ -173,7 +187,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 **128,994 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)
 
@@ -283,7 +297,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, 128,994 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.
@@ -305,6 +319,14 @@ The brain binaries ship via the [Release](https://github.com/stuinfla/ruvnet-bra
 
 ---
 
+## 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/

package/bin/install.mjs

@@ -65,11 +65,13 @@ 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)
 const FLAG_DISABLE_NIGHTLY = argv.includes('--disable-nightly'); // remove the nightly schedule
 const FLAG_NO_NIGHTLY_PROMPT = argv.includes('--no-nightly-prompt'); // don't offer nightly auto-updates at the end of an install
+const FLAG_NO_TELEMETRY = argv.includes('--no-telemetry'); // decline anonymous usage counts without being asked
 // ── onboarding-experience flags (all optional; every offer is safe to decline) ──
 const FLAG_YES = argv.includes('--yes') || argv.includes('-y'); // accept every optional offer non-interactively
 const FLAG_WITH_STACK = argv.includes('--with-stack'); // add missing Ruflo/RuVector without prompting
@@ -490,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
@@ -503,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');
 
@@ -758,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 —
@@ -921,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
@@ -937,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).
@@ -992,6 +1268,96 @@ export async function offerNightly() {
   return 'enabled';
 }
 
+// ── step: offer OPT-IN anonymous usage counts (asked once ever; explicit yes required) ────────────
+// The whole contract, honestly: counts ONLY (installs / searches / sessions + version) — NEVER the
+// user's queries, code, repo names, or paths. Consent is a plain yes/no file the user can read and
+// flip (~/.cache/ruvnet-brain/.telemetry-consent); nothing is ever sent without the literal "yes".
+// Fail-private everywhere: no TTY → not asked → not enabled; TEST mode → suppressed entirely.
+const telemetryStateDir = () => path.join(os.homedir(), '.cache', 'ruvnet-brain');
+const telemetryConsentPath = () => path.join(telemetryStateDir(), '.telemetry-consent');
+
+// Same default-yes contract as parseNightlyAnswer, exported under its own name so the telemetry
+// tests read as telemetry tests: ENTER/y/yes accept; ONLY an explicit n/no declines.
+export const parseTelemetryAnswer = parseNightlyAnswer;
+
+// Fire-and-forget install ping — 3s cap, all failures swallowed, payload is { event, v } and
+// nothing else. Exported (with injectable fetch) so tests can assert the payload without a network.
+export async function sendInstallPing({
+  version = 'unknown',
+  fetchFn = globalThis.fetch,
+  pingUrl = process.env.RUVNET_BRAIN_PING_URL || 'https://ruvnet-brain.vercel.app/api/ping',
+} = {}) {
+  try {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), 3000);
+    await fetchFn(pingUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ event: 'install', v: version }),
+      signal: ctl.signal,
+    }).catch(() => {});
+    clearTimeout(timer);
+  } catch { /* a lost count is nothing; a broken install step would be everything */ }
+}
+
+// Exported decision matrix (testable under RUVNET_BRAIN_IMPORT_ONLY=1, like offerNightly).
+// Returns a status string; never throws — a finished install must never be broken by an offer.
+export async function offerTelemetry(cacheDir) {
+  if (TEST_MODE) return 'suppressed'; // tests: never prompt, never write, NEVER send
+  const consentPath = telemetryConsentPath();
+  if (fs.existsSync(consentPath)) return 'already-set'; // asked once ever — respect the answer
+  if (FLAG_NO_TELEMETRY) {
+    try { fs.mkdirSync(telemetryStateDir(), { recursive: true }); fs.writeFileSync(consentPath, 'no\n'); } catch { /* best-effort */ }
+    return 'declined-flag';
+  }
+
+  step(
+    'Optional: anonymous usage counts',
+    'a simple count of installs/searches tells Stuart the brain is actually helping people — nothing about WHAT you ask',
+  );
+  info(`Counts only — installs, searches, sessions, version. ${c.bold('Never your queries, code, repo names, or paths.')}`);
+  info(c.dim(`Your answer is a plain-text file you can read or flip any time: ${consentPath}`));
+
+  if (!process.stdin.isTTY && !FLAG_YES) {
+    // No terminal to ask on → fail PRIVATE: no consent recorded, so nothing will ever be sent.
+    info(`No interactive terminal here, so I won't assume — usage counts stay ${c.bold('OFF')}.`);
+    info(`Opt in any time:  echo yes > ${consentPath}`);
+    return 'not-asked';
+  }
+
+  let yes = true; // --yes accepts every optional offer, this one included
+  if (!FLAG_YES) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) =>
+      rl.question(`    ${c.cyan('?')} Share anonymous usage counts (installs/searches — never your queries or code)? ${c.dim('[Y/n]')} `, resolve),
+    );
+    rl.close();
+    yes = parseTelemetryAnswer(answer);
+  }
+
+  try {
+    fs.mkdirSync(telemetryStateDir(), { recursive: true });
+    fs.writeFileSync(consentPath, yes ? 'yes\n' : 'no\n');
+  } catch (e) {
+    warn(`couldn't record the answer (${e.message}) — defaulting to OFF (nothing will be sent)`);
+    return 'error';
+  }
+  if (!yes) {
+    ok('usage counts are OFF — nothing will ever be sent');
+    return 'declined';
+  }
+  ok('thanks — anonymous counters only, batched to at most one ping a day');
+  // Count this install (the one event the brain itself can't see). Version = the bundle we
+  // just put on disk, read live from its own SOURCE.json — never guessed.
+  let v = 'unknown';
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(cacheDir, 'SOURCE.json'), 'utf8'));
+    if (typeof j.releaseTag === 'string' && /^[A-Za-z0-9._-]{1,32}$/.test(j.releaseTag)) v = j.releaseTag;
+  } catch { /* unknown is honest */ }
+  await sendInstallPing({ version: v });
+  return 'enabled';
+}
+
 // ── tiny interactive yes/no — SAFE in non-TTY (returns the default; never blocks a piped install) ──
 function ask(question, def = false) {
   if (FLAG_YES) return Promise.resolve(true);
@@ -1232,6 +1598,11 @@ function success({ cacheDir, isCustom, plugin, env, nightly }) {
     console.log(`    ${c.dim('Either way, your copy only advances when a new Release is actually published.')}`);
   }
 
+  // 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 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('');
 }
@@ -1248,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;
@@ -1255,6 +1629,10 @@ Usage:
   npx ruvnet-brain --disable-nightly   Remove the nightly schedule (safe to run any time)
                               (a default install RECOMMENDS nightly and asks, defaulting to yes)
   node bin/install.mjs --no-nightly-prompt Don't offer nightly auto-updates at the end of the install
+  node bin/install.mjs --no-telemetry      Decline anonymous usage counts without being asked
+                              (counts of installs/searches ONLY — never queries, code, or paths;
+                              opt-in prompt appears once at install; answer lives in a plain file:
+                              ~/.cache/ruvnet-brain/.telemetry-consent)
   node bin/install.mjs --version <tag>     Install a specific Release tag (e.g. --version v0.5.0-dev)
   node bin/install.mjs --pin               Skip the latest-check; use the bundled known-good version
   node bin/install.mjs --local             Install from a repo clone's dist/ruvnet-brain.zip
@@ -1279,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();
@@ -1362,6 +1741,16 @@ 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 */ }
 
   success({ cacheDir, isCustom, plugin, env, nightly });
 })().catch((e) => {