ruvnet-brain 2.9.1 → 3.4.6-dev

package/README.md

@@ -4,13 +4,13 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 2.9.1 — updated 2026-07-14 05:59 EDT](https://img.shields.io/badge/version_2.9.1-updated_2026--07--14_05:59_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 3.4.6-dev — updated 2026-07-17 09:40 EDT](https://img.shields.io/badge/version_3.4.6--dev-updated_2026--07--17_09:40_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.**
 
 [![plugin version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstuinfla%2Fruvnet-brain%2Fmain%2Fplugin%2F.claude-plugin%2Fplugin.json&query=%24.version&label=plugin&color=e8a13a&style=flat-square)](plugin/.claude-plugin/plugin.json)
 [![installer version](https://img.shields.io/npm/v/ruvnet-brain?label=installer%20%28npm%29&color=2e7d32&style=flat-square)](https://www.npmjs.com/package/ruvnet-brain)
-[![download](https://img.shields.io/badge/download-512MB%20brain-2e7d32?style=flat-square)](https://github.com/stuinfla/ruvnet-brain/releases/latest)
+[![download](https://img.shields.io/badge/download-latest%20brain-2e7d32?style=flat-square)](https://github.com/stuinfla/ruvnet-brain/releases/latest)
 [![explainer](https://img.shields.io/badge/▶%20see%20it%20live-isovision.ai%2Fruvnet--brain-e8a13a?style=flat-square)](https://isovision.ai/ruvnet-brain/)
 [![license](https://img.shields.io/badge/license-MIT-8ecae6?style=flat-square)](LICENSE)
 [![grounded](https://img.shields.io/badge/answers-cited%20rUv%20source-333?style=flat-square)](#testing--proof)
@@ -19,10 +19,14 @@
 > **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) (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.
+> - **Brain Release** (the downloadable 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.
+> - **On an old version? One line makes you current — and, with `--auto`, keeps you current forever:**
+>   ```
+>   npx ruvnet-brain@latest --update --auto
+>   ```
+>   `--update` pulls the latest plugin + knowledge (backs up first, re-verifies, fails loud instead of half-applying). Adding `--auto` enrolls you in **Evergreen** — the brain keeps itself up to date from then on, so you never run this again. Drop `--auto` for a one-time update: `npx ruvnet-brain@latest --update`.
+> - **Turn Evergreen off any time:** `npx ruvnet-brain --disable-nightly` (Linux/Windows get the cron line documented in the bundle's `forge-update.mjs`).
+> - **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.
 
 <sub>Built by **[Stuart Kerr](https://isovision.ai)** at [Isovision.ai](https://isovision.ai) · free & fair use, to help everyone leverage the high end of agentic coding.</sub>
 
@@ -36,7 +40,57 @@
 
 ---
 
-## What's new in 2.5 — it uses rUv's real tools, and every job proves it ran
+## What's new in 3.4 — the invisible work, made visible (and readable)
+
+**Shipped 2026-07-17.** 3.3 made every card lead with a point. Then Stuart looked at the two pages meant to *teach* the stack and scored them 55/100: the graphics were mediocre, the one page that should show how the pieces fit was a wall of text, and two diagrams were literally unreadable. 3.4 is the fix — the harness's invisible work, finally drawn, and drawn so you can actually read it.
+
+- **The animation that shows the whole argument** — one prompt, sent two ways. Plain Claude Code: a bare wire to one expensive model, no grounding, no memory, no gates. The same model **wrapped in the harness**: it grounds the prompt, routes it to the cheapest model that can do the job, hands back what your project already decided, **inspects the write and can refuse it**, and checks it on the way out. The left lane finishes first — and that's the problem.
+- **MetaHarness, as a picture** — the old card was rectangles with words in them. It's now the thesis at a glance: the model a **frozen** cyan crystal that never moves, seven policy surfaces evolving in a warm orbit around it, the kept branch merging back and the pruned one dying mid-air. *Freeze the model, evolve the harness.* Every number traces to an accepted ADR (28.5% cheaper at 98.1% bar-compliance — ADR-073/075/076).
+- **Diagrams you can actually read** — two of them shipped with labels rendering at **8px and 3px**: present, un-clipped, and invisible. An SVG sized in one coordinate system, crushed into a narrower column, silently shrinks its own text and no error ever fires. There's now a gate for exactly that (`scripts/check-legibility.mjs`) — it measures the *effective* pixel size in the live page, proven to catch the known-bad case before it was trusted. Every diagram label now clears 12px on a phone.
+- **The tips page has a door** — its only link wore the same style as a status readout beside it, and on a phone was hidden entirely — the page was **unreachable under 640px**. There's now an unmissable button where it belongs.
+- **Real generated imagery** — three commissioned stills built from the console's own palette, so they belong to the page instead of sitting on top of it.
+
+<details>
+<summary><b>Earlier &#8212; what 3.3 proved</b> &#183; it stopped reciting facts and started making a point. <i>Expand for the receipts.</i></summary>
+
+## 3.3 — it stopped reciting facts and started making a point
+
+**Shipped 2026-07-17.** 3.2 made the stack visible. Visible turned out not to be the same as *useful*: the console could tell you 21 things and leave you no smarter. Stuart, looking at his own product: *"I have no idea what message it's supposed to tell me… it seems to be facts without purpose."* 3.3 is the answer to that — every card now leads with a **verdict**, not a census.
+
+- **A second page — [how to actually use this](console/tips.html)** — the question nobody could answer: *there are plugins, there are commands, and there's just… typing. Which am I supposed to use?* One page, three depths, and the first depth is **doing nothing**. Built on rUv's own doctrine: *"I don't have to load 350 skills that 99% of which I never use — the system is smart enough to know which one this task needs."*
+- **MetaHarness, explained where you decide** — the card asked you to switch on a word you'd never seen. It now shows the architecture instead: the model **frozen** at the centre, seven policy surfaces evolving around it, four pillars underneath. rUv called this exact risk in ADR-076 (*"'Meta-harness' is a newer term… must define it in the first screen so it doesn't read as jargon"*); we'd shipped the jargon and skipped the mitigation. Every element traces to an accepted ADR.
+- **The wiring card was lying to you** — it warned about 21 npx call sites. 18 were inside *clones of rUv's own repos* (one a `tests/init-test` fixture), and two were `echo` strings printing advice. Real exposure: **zero**. It now says so: *"Every rUv tool here resolves to one known version."* A card that shows amber for a problem you don't have is worse than no card.
+- **The money leads** — the router card buried *$15.17 saved* as the dimmest text on the row while `FRONTIER — 0` read like missing data. It's the punchline: the expensive model never had to fire. Now it says that, in that order.
+- **What caught Claude** — a new card. 21 gates read every move before it lands; 6 can stop one. The walls now record what they *catch*, not just what they pass — because the ledger held 13 receipts, 13 passing, while the design wall had refused a commit minutes earlier and written nothing down.
+- **The console loads in 0.2s** (was ~14s) — a fleet-wide scan of 107 memory stores sat on the critical path of first paint. It hydrates late now.
+
+</details>
+
+<details>
+<summary><b>Earlier &#8212; what 3.2 proved</b> &#183; the invisible stack, made visible. <i>Expand for the receipts.</i></summary>
+
+## 3.2 — the invisible stack, made visible
+
+**Shipped 2026-07-16.** rUv's tools do their best work invisibly — which meant nobody could see them working, working stale, or working in conflict. The 3.x line makes the machinery visible, and everything it shows you is measured, never projected.
+
+- **A living console** — `/rvbc` puts your whole stack on one page: what's installed, how it's wired, what your AI learned. Every warning arrives paired with a one-click, undoable fix, and the page re-checks itself after every change so you always see the *after* state.
+- **Your brain, visible** — a live **Brain Activity** card: every memory stored, every lesson distilled, clickable down to the verbatim task → what-failed → what-works cards from your own AgentDB (ADR-0018).
+- **Receipts, not estimates** — the routing dashboard recomputes from real routing receipts against *your* frontier; subscriptions price at $0; a providers row shows exactly which license pays for what.
+- **No model fact ships from memory** — the 3.0 live-verification wall: every model/version claim checks the live catalog in CI (ADR-0016), and router profiles self-optimize from rUv's bench plus live prices (ADR-0015).
+- **It learns YOU** — a recursive per-user learning loop (ADR-017): patterns from how you actually work, shared across your projects, isolated where they must be.
+
+![The RuvNet Brain Console — your invisible AI stack, made visible: live Brain Activity card, real memories and lessons, one-click reversible fixes](assets/console-v31.png)
+
+**Open it any time with `/rvbc`** (RuvNet Brain Console) — and the first time you load the Brain, it offers to open it for you.
+
+> New gate with this release: **narrative versions are tested.** If any public page says "What's new in X" where X isn't the shipping version, CI fails — because this README sat on 2.5 while 3.1 shipped, and nobody's eyes are a gate.
+
+</details>
+
+<details>
+<summary><b>Earlier &#8212; what 2.5 proved</b> &#183; it uses rUv's real tools (a CI gate makes silent hand-rolls impossible), every scheduled job must prove it ran, and no subagent inherits an expensive model by accident. <i>Expand for the receipts.</i></summary>
+
+## 2.5 — the receipts
 
 **Shipped 2026-07-13. Two hard lessons, both fixed at the root.**
 
@@ -68,10 +122,12 @@ So 2.5.1 makes it a **wall, not advice**: a `PreToolUse` gate that **blocks any
 
 ![MetaHarness routing — your subscriptions first, always](assets/diagrams/router-path.svg)
 
+</details>
+
 <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 — the receipts
 
 **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:
 
@@ -159,7 +215,7 @@ WITHOUT the brain — drift          |   WITH RuvNet Brain — grounded
 npx ruvnet-brain
 ```
 
-That single command runs the whole setup, narrating _what it's doing and why_ at each step: it downloads the brain (~512 MB) from the [latest GitHub Release](https://github.com/stuinfla/ruvnet-brain/releases/latest), unpacks it to `~/.cache/ruvnet-brain/kb`, installs its local reader (no cloud calls, no API keys), and wires the Claude Code plugin — the `search_ruvnet` MCP tool + the `UserPromptSubmit` grounding hook — at user scope. The installer and the `search_ruvnet` tool run on **macOS, Linux, and Windows**; the grounding/enforcement **hooks are POSIX shell**, so they fire on macOS, Linux, and Windows-via-WSL/Git-Bash (on native Windows without WSL the search tool still works, but the auto-grounding hooks don't fire — a Node port of the hooks is on the roadmap). It's safe to re-run, and the brain itself always fetches the current Release regardless of which install path you use — you install once; you don't keep re-downloading.
+That single command runs the whole setup, narrating _what it's doing and why_ at each step: it downloads the brain from the [latest GitHub Release](https://github.com/stuinfla/ruvnet-brain/releases/latest), unpacks it to `~/.cache/ruvnet-brain/kb`, installs its local reader (no cloud calls, no API keys), and wires the Claude Code plugin — the `search_ruvnet` MCP tool + the `UserPromptSubmit` grounding hook — at user scope. The installer and the `search_ruvnet` tool run on **macOS, Linux, and Windows**; the grounding/enforcement **hooks are POSIX shell**, so they fire on macOS, Linux, and Windows-via-WSL/Git-Bash (on native Windows without WSL the search tool still works, but the auto-grounding hooks don't fire — a Node port of the hooks is on the roadmap). It's safe to re-run, and the brain itself always fetches the current Release regardless of which install path you use — you install once; you don't keep re-downloading.
 
 > 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.
 
@@ -186,9 +242,12 @@ Registers the `search_ruvnet` MCP tool, the grounding skill, and the `UserPrompt
 
 You install once. After that, three mechanisms keep you on the current brain without you having to remember an update command.
 
-- **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).
+- **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 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.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.
+- **Grounding receipt line** (the `UserPromptSubmit` gate, `plugin/scripts/ground-ruvnet.sh`). When the brain engages on a prompt, the answer ends with one dim line stating what it actually did — either it read rUv's real source and **names the file**, or it says plainly that it didn't:
+  `🧠 RuvNet Brain jumped in · cited agentic-flow/docs/adr/ADR-076-reposition-agentic-flow-as-agentic-meta-harness.md · v3.2.16`
+  `🧠 RuvNet Brain jumped in · guidance only, no source read · v3.2.16`
+  An unearned citation is worse than no citation, so the line may only name a path the tools genuinely returned — and on a prompt where nothing fires, it stays silent rather than manufacture a receipt. The version shown is the one **actually loaded in memory** for this session; if a newer one 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 an answer was grounded or guessed.
 
 - **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.)
 
@@ -212,7 +271,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,685 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
+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 **132,131 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)
 
@@ -260,7 +319,7 @@ The brain answers **both** kinds of questions. **Name the repo or ask something
 | [`ruv-fann`](https://github.com/ruvnet/ruv-FANN) | Fast neural nets (Rust/WASM) + ruv-swarm | [`daa`](https://github.com/ruvnet/daa) | Decentralized autonomous agents |
 | [`synthlang`](https://github.com/ruvnet/synthlang) | Prompt compression (~75% token cut) | [`rupixel`](https://github.com/ruvnet/rupixel) | On-device visual embeddings |
 | [`dspy.ts`](https://github.com/ruvnet/dspy.ts) | DSPy-style programmable LLM pipelines in TS | [`fact`](https://github.com/ruvnet/fact) | Fast-Access Cached Tools + circuit breaker |
-| [`cve-bench`](https://github.com/ruvnet/cve-bench) | Security-fix benchmark | [`agent-harness-generator`](https://github.com/ruvnet/agent-harness-generator) | Harness scaffolding / metaharness |
+| [`cve-bench`](https://github.com/ruvnet/cve-bench) | Security-fix benchmark | [`metaharness`](https://github.com/ruvnet/metaharness) | Harness scaffolding / metaharness |
 | [`rvm`](https://github.com/ruvnet/rvm) | Proof-gated capability microhypervisor | [`rUv-dev`](https://github.com/ruvnet/rUv-dev) · [`open-claude-code`](https://github.com/ruvnet/open-claude-code) | Dev workflow + agent tooling |
 
 > **Not in the public brain:** rUv's private **Cognitum One** repos (seed, v0-appliance, platform-docs) are fenced out of the download by design — verified zero-leak in every build. **Helix** (rUv's local-first health app) is a finished product, not a building block, so it's out too.
@@ -284,7 +343,7 @@ node plugin/test/run-tests.mjs                    # full plugin QA over real JSO
 | **Context-scenario routing** | **7 / 8 (88%)** | full-scenario prompts route correctly |
 | **L1–L4 behavioral harness** | **all pass** | route · deep-recall (returns _code_) · implement (cites the API) · orchestrate (the hook drives the full pipeline) |
 | **Plugin QA** | **26 / 26** | manifests, hook firing, MCP `initialize`/`tools/list`, capability battery |
-| **Clean-room install** | **3 / 3** | download the published 512 MB bundle fresh → unzip → query → grounded, cited answers |
+| **Clean-room install** | **3 / 3** | download the published bundle fresh → unzip → query → grounded, cited answers |
 | **Unit tests** | **257 passing** · 10% of ALL source covered | `npm run test:cov` — the floor fails CI if it slips. 10% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
 | **Grounding proof** | `npx ruvnet-brain --doctor` | asks a real question, then checks the cited path really exists in the on-disk store; a citation that doesn't resolve is reported as **NOT grounded** |
 | **Held-out eval** | **grounded 100/100** · routed 63/80 | `npm run eval` — 120 frozen, hash-pinned questions across 5 strata, never used for tuning, graded on ground truth, never by a model |
@@ -322,7 +381,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** — 36 repos, 129,685 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 36 repos, 132,131 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.
@@ -340,7 +399,7 @@ 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/latest), 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 full bundle.
 
 ---
 

package/bin/install.mjs

@@ -68,6 +68,7 @@ const FLAG_DEMO = argv.includes('--demo'); // guided, real (non-fabricated) walk
 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_AUTO = argv.includes('--auto'); // with --update: also enroll in Evergreen auto-update, so it's never run by hand again
 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
@@ -78,6 +79,8 @@ const FLAG_WITH_STACK = argv.includes('--with-stack'); // add missing Ruflo/RuVe
 const FLAG_NO_STACK = argv.includes('--no-stack'); // skip the toolkit offer entirely
 const FLAG_ENHANCE_CLAUDE_MD = argv.includes('--enhance-claude-md'); // add the CLAUDE.md section without prompting
 const FLAG_NO_ENHANCE = argv.includes('--no-enhance'); // skip the CLAUDE.md offer entirely
+const FLAG_STATUSLINE = argv.includes('--statusline'); // opt in to the status-bar version segment, non-interactively
+const FLAG_NO_STATUSLINE = argv.includes('--no-statusline'); // decline the status-bar offer without prompting
 // --version <tag> forces a specific Release tag (e.g. --version v0.5.0-dev)
 const versionIdx = argv.indexOf('--version');
 const FORCED_VERSION =
@@ -904,19 +907,34 @@ function runUpdate() {
   printBanner('update');
   const kbDir = resolvedKbDir();
   info(`brain dir: ${c.bold(kbDir)}`);
-  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
-    missingUpdaterHelp(kbDir);
-    process.exit(1);
+  let updateStatus = 1;
+  if (fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+    info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
+    // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
+    // streams the updater's narration live and unedited.
+    const r = spawnSync(process.execPath, ['forge-update.mjs', '--apply'], { cwd: kbDir, stdio: 'inherit' });
+    updateStatus = r.error ? 1 : (r.status === null ? 1 : r.status);
   }
-  info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
-  // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
-  // streams the updater's narration live and unedited.
-  const r = spawnSync(process.execPath, ['forge-update.mjs', '--apply'], { cwd: kbDir, stdio: 'inherit' });
-  if (r.error) {
-    console.error(`\n${c.red('✗ update failed to launch:')} ${r.error.message}`);
-    process.exit(1);
+  // FALLBACK (2026-07-17). The bundle's self-updater is missing OR failed — e.g. an OLDER bundle whose
+  // canonicalManifestUrl points at the dead main/kb/.last-built.json path and 404s (the exact break a
+  // real user, Jan Lafko, hit). NEVER leave the user stranded at a 404: re-run THIS installer as a
+  // fresh install, which pulls the latest Release DIRECTLY (releases/latest) and never touches the
+  // manifest — so --update always succeeds and self-heals the stale SOURCE.json in one shot.
+  if (updateStatus !== 0 && !process.env.RUVNET_BRAIN_NO_UPDATE_FALLBACK) {
+    warn("\nthe bundle's own updater couldn't complete — falling back to a fresh install of the latest Release (this always works)…\n");
+    const self = fileURLToPath(import.meta.url);
+    const fr = spawnSync(process.execPath, [self, '--force'], { stdio: 'inherit',
+      env: { ...process.env, RUVNET_BRAIN_NO_UPDATE_FALLBACK: '1' } });
+    updateStatus = fr.error ? 1 : (fr.status === null ? 1 : fr.status);
   }
-  process.exit(r.status === null ? 1 : r.status); // exit with the updater's own verdict
+  // `--update --auto` = update now AND enroll in Evergreen, so this is the LAST time it's ever run by
+  // hand. Only enroll if the update itself succeeded — never promise "you're set forever" on a failed
+  // update. enableNightly() prints its own real verification (plist path + launchctl result).
+  if (updateStatus === 0 && FLAG_AUTO) {
+    info(c.dim("\n--auto set: enrolling in Evergreen auto-update so you never run this again…\n"));
+    enableNightly(); // exits on its own with verified output; if it returns, fall through to the update verdict
+  }
+  process.exit(updateStatus); // exit with the updater's own verdict
 }
 
 function enableNightly() {
@@ -1532,6 +1550,180 @@ async function offerClaudeMd() {
   }
 }
 
+// ── step: OPT-IN status-bar version segment — "which RuvNet Brain am I on?" at a glance ───────────
+// Claude Code renders its status bar from `statusLine.command` in ~/.claude/settings.json (verified
+// live: code.claude.com/docs/en/statusline — `{ type: "command", command: "<script>", padding? }`;
+// Claude Code pipes JSON session data to the command's stdin, and whatever it prints to stdout
+// becomes the line). Users often already have a rich statusline (git branch, context %, other tool
+// versions) — silently replacing it would be exactly the clobber this installer refuses to do
+// anywhere else. So: detect first, and only ADD a statusLine when NONE exists. If one is already
+// wired, settings.json is never touched — we hand back the helper's path so it can be folded into
+// their own script instead. Asked once ever (pref file, same contract as .telemetry-consent): a
+// "no", or a silent non-interactive run with no explicit flag, never gets re-asked or half-applied.
+// .cjs (CommonJS), not .mjs: measured live on this machine (Node 22) — the ESM loader costs the
+// statusline ~4-5ms extra per invocation versus a plain `require()` script (median 50.4ms vs
+// 46.7ms across 30 interleaved runs of otherwise-identical logic), which is the difference between
+// sitting under the <50ms budget and blowing past it on every single prompt. `.cjs` forces
+// CommonJS unambiguously regardless of any stray package.json a user's HOME might contain.
+const STATUSLINE_HELPER_NAME = 'ruvnet-brain-statusline.cjs';
+const statuslineHelperPath = () => path.join(telemetryStateDir(), STATUSLINE_HELPER_NAME);
+const statuslinePrefPath = () => path.join(telemetryStateDir(), '.statusline-pref');
+const settingsJsonPath = () => path.join(os.homedir(), '.claude', 'settings.json');
+
+// Self-contained, dependency-free script Claude Code's statusLine command runs on EVERY prompt — it
+// must stay well under budget, so it's a single sync read with no imports beyond node builtins.
+// Reads the version LIVE from the installed bundle's SOURCE.json (releaseTag) — never hardcoded, so
+// it always matches whatever is actually on disk. Degrades to silent empty output on ANY failure
+// (brain not installed, file unreadable, malformed JSON) — a missing/broken brain must never break
+// the rest of the user's statusline.
+const STATUSLINE_HELPER_SRC = `#!/usr/bin/env node
+// ruvnet-brain-statusline.cjs — one segment for Claude Code's statusLine command.
+// See https://code.claude.com/docs/en/statusline. Written by the installer's --statusline offer.
+// Prints "RuvNet Brain v<version>" read LIVE from the installed bundle's SOURCE.json — never
+// hardcoded. Any failure (brain missing, unreadable, malformed JSON) degrades to empty output so
+// a broken or missing brain can never break the rest of the status line. CommonJS on purpose —
+// measurably faster to start than ESM for a script this runs on every single prompt.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+try {
+  const kbDir = process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
+  const j = JSON.parse(fs.readFileSync(path.join(kbDir, 'SOURCE.json'), 'utf8'));
+  const raw = String(j.releaseTag || '');
+  if (/^[A-Za-z0-9._-]{1,32}$/.test(raw)) {
+    process.stdout.write('RuvNet Brain ' + (raw.startsWith('v') ? raw : 'v' + raw));
+  }
+} catch { /* not installed / unreadable — print nothing, never break the statusline */ }
+`;
+
+function writeStatuslineHelper() {
+  const dst = statuslineHelperPath();
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.writeFileSync(dst, STATUSLINE_HELPER_SRC, { mode: 0o755 });
+  return dst;
+}
+
+// Pure read — NEVER writes. Exported so detection is independently testable
+// (RUVNET_BRAIN_IMPORT_ONLY=1) with zero risk of mutating a real settings.json.
+export function detectStatusLine(settingsPath = settingsJsonPath()) {
+  let raw;
+  try {
+    raw = fs.readFileSync(settingsPath, 'utf8');
+  } catch {
+    return { path: settingsPath, exists: false, hasStatusLine: false, command: null, parseError: false, json: {} };
+  }
+  try {
+    const j = raw.trim() ? JSON.parse(raw) : {};
+    const sl = j && typeof j === 'object' ? j.statusLine : null;
+    const command = sl && typeof sl.command === 'string' ? sl.command : null;
+    return { path: settingsPath, exists: true, hasStatusLine: Boolean(command), command, parseError: false, json: j };
+  } catch {
+    return { path: settingsPath, exists: true, hasStatusLine: false, command: null, parseError: true, json: null };
+  }
+}
+
+// Same `.bak-<ISO timestamp>` convention used elsewhere in this project (see onboarding-console.mjs's
+// config backup) — always taken before an EXISTING file is touched, never before a brand-new one.
+function backupSettingsJson(settingsPath) {
+  const backup = `${settingsPath}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  fs.copyFileSync(settingsPath, backup);
+  return backup;
+}
+
+function writeSettingsStatusLine(detected, command) {
+  const backup = detected.exists ? backupSettingsJson(detected.path) : null;
+  const next = { ...(detected.json || {}), statusLine: { type: 'command', command } };
+  fs.mkdirSync(path.dirname(detected.path), { recursive: true });
+  fs.writeFileSync(detected.path, JSON.stringify(next, null, 2) + '\n');
+  return backup;
+}
+
+// Only called after explicit consent. NEVER overwrites an existing statusLine — detectStatusLine()
+// is the single source of truth for "is one already there", checked fresh right before any write.
+function applyStatusline() {
+  const helperPath = writeStatuslineHelper();
+  ok(`installed the version-segment script → ${c.bold(helperPath)}`);
+  const command = `node "${helperPath}"`;
+
+  const detected = detectStatusLine();
+
+  if (detected.parseError) {
+    warn(`${detected.path} isn't valid JSON — leaving it untouched (never merging into a file I can't parse).`);
+    info(`Add this to it yourself once it's fixed:`);
+    info(`  ${c.bold(`"statusLine": { "type": "command", "command": "${command}" }`)}`);
+    return 'manual-parse-error';
+  }
+
+  if (detected.hasStatusLine) {
+    ok(`you already have a status line (${c.dim(detected.command)}) — leaving it exactly as is.`);
+    info(`To fold the brain version in, have your own script also run this and print the result:`);
+    info(`  ${c.bold(command)}`);
+    return 'existing-preserved';
+  }
+
+  try {
+    const backup = writeSettingsStatusLine(detected, command);
+    if (backup) ok(`backed up your settings to ${c.bold(backup)} before editing`);
+    ok(`status line set in ${c.bold(detected.path)} — restart Claude Code to see it`);
+    return 'set';
+  } catch (e) {
+    warn(`couldn't write ${detected.path} (${e.message}) — add it yourself:`);
+    info(`  ${c.bold(`"statusLine": { "type": "command", "command": "${command}" }`)}`);
+    return 'write-error';
+  }
+}
+
+// Exported (testable under RUVNET_BRAIN_IMPORT_ONLY=1, like offerTelemetry). Never throws — the
+// caller also guards, because a finished install must never be broken by an optional offer.
+export async function offerStatusline() {
+  if (TEST_MODE) return 'suppressed'; // tests: never prompt, never write, never touch settings.json
+  const prefPath = statuslinePrefPath();
+  if (fs.existsSync(prefPath)) {
+    // asked once ever — respect the answer, never re-ask. (Delete the file to be asked again.)
+    let pref = '';
+    try { pref = fs.readFileSync(prefPath, 'utf8').trim().toLowerCase(); } catch { /* treat as declined */ }
+    return pref === 'yes' ? 'already-on' : 'already-set';
+  }
+
+  if (FLAG_NO_STATUSLINE) {
+    try { fs.mkdirSync(telemetryStateDir(), { recursive: true }); fs.writeFileSync(prefPath, 'no\n'); } catch { /* best-effort */ }
+    return 'declined-flag';
+  }
+
+  step(
+    'Optional: show the brain version in your status bar',
+    "so you can always tell at a glance which RuvNet Brain version you're on",
+  );
+  info(`Adds a small ${c.bold('"RuvNet Brain vX.Y.Z"')} segment, read live from your installed brain — it`);
+  info(`updates itself the moment the brain updates. ${c.bold('Never overwrites an existing status line.')}`);
+
+  const interactive = process.stdin.isTTY || FLAG_YES || FLAG_STATUSLINE;
+  if (!interactive) {
+    // No terminal to ask on, and no explicit flag either — skip WITHOUT recording an answer, so a
+    // future interactive (or flagged) run still gets a real chance to ask.
+    info(`No interactive terminal here, so I won't assume — skipping for now.`);
+    info(`Add it any time:  ${c.bold('npx ruvnet-brain --statusline')}`);
+    return 'not-asked';
+  }
+
+  const yes = FLAG_STATUSLINE || (await ask('Add a RuvNet Brain version segment to your Claude Code status bar?', false));
+
+  try {
+    fs.mkdirSync(telemetryStateDir(), { recursive: true });
+    fs.writeFileSync(prefPath, yes ? 'yes\n' : 'no\n');
+  } catch (e) {
+    warn(`couldn't record the answer (${e.message})`);
+  }
+
+  if (!yes) {
+    info(`No problem — add it any time:  ${c.bold('npx ruvnet-brain --statusline')}`);
+    return 'declined';
+  }
+
+  return applyStatusline();
+}
+
 // ── final success block ──────────────────────────────────────────────────────────────────────────
 function success({ cacheDir, isCustom, plugin, env, nightly }) {
   const line = '─'.repeat(64);
@@ -1646,6 +1838,10 @@ Usage:
   node bin/install.mjs --no-stack          Don't offer to add Ruflo / RuVector
   node bin/install.mjs --enhance-claude-md Add a RuvNet-Brain section to ~/.claude/CLAUDE.md (no prompt)
   node bin/install.mjs --no-enhance        Don't offer the CLAUDE.md section
+  node bin/install.mjs --statusline        Add a "RuvNet Brain vX.Y.Z" segment to your Claude Code
+                              status bar (no prompt). Never overwrites an existing status line — if
+                              you already have one, this only prints a snippet to fold it into yours.
+  node bin/install.mjs --no-statusline     Don't offer the status-bar segment
   node bin/install.mjs --yes, -y           Accept every optional offer (good for scripted installs)
 
 Env:
@@ -1755,6 +1951,9 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   // 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 */ }
+  // Status-bar version segment — OPT-IN, asked once ever, never clobbers an existing statusline.
+  // Same rule: an optional offer can never break a finished install.
+  try { await offerStatusline(); } catch { /* non-fatal — a status-bar nicety must never break the install */ }
 
   success({ cacheDir, isCustom, plugin, env, nightly });
 })().catch((e) => {

package/config/scheduled-jobs.json

@@ -88,6 +88,26 @@
       "schedule": "daily 09:00",
       "maxAgeHours": 26,
       "required": true
+    },
+    {
+      "label": "com.ruvnet.issue-watch",
+      "what": "Hourly GitHub-issues SLA watcher (stuinfla/ruvnet-brain) — pages ntfy when an open issue sits >4h with no comment from the repo owner",
+      "schedule": "hourly",
+      "maxAgeHours": 3,
+      "required": true
+    },
+    {
+      "label": "com.ruvnet.issue-fix",
+      "what": "Every 10 min: auto-fixes newly opened GitHub issues (stuinfla/ruvnet-brain) — bounded headless `claude -p` per issue in a disposable git worktree, pushes an issue-fix/<N> branch + comment or posts an honest triage comment, never touches main, never closes an issue",
+      "schedule": "every 10 min",
+      "maxAgeHours": 1,
+      "required": true
+    },
+    {
+      "label": "com.ruvnet.routing-flywheel",
+      "schedule": "nightly 04:45",
+      "maxAgeHours": 26,
+      "what": "nightly bounded live flywheel over routing policy (candidate+receipt only, never live routing)"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "2.9.1",
+  "version": "3.4.6-dev",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -28,7 +28,10 @@
     "gists:sync": "node scripts/ingest-gists.mjs && node kb/forge-big.mjs both --dir kb --name ruv-gists",
     "test:integration": "vitest run tests/integration",
     "substitution:check": "node scripts/no-silent-substitution.mjs",
-    "falsify": "node scripts/falsify.mjs"
+    "catalog:verify": "node scripts/verify-model-catalog.mjs",
+    "catalog:refresh": "node scripts/refresh-model-catalog.mjs",
+    "falsify": "node scripts/falsify.mjs",
+    "sbom": "npx --yes @cyclonedx/cyclonedx-npm --omit dev --output-file sbom/ruvnet-brain.cdx.json --mc-type application --validate"
   },
   "files": [
     "bin/install.mjs",
@@ -79,6 +82,7 @@
     "vitest": "^4.1.10"
   },
   "dependencies": {
+    "@metaharness/flywheel": "^0.1.7",
     "@metaharness/router": "^0.3.2"
   }
 }

package/scripts/metaharness-router.mjs

@@ -67,9 +67,18 @@ export function effectivePrices(candidates, profile) {
   const prices = {};
   for (const c of candidates) {
     const covered = (c.subscription || []).some((h) => profile?.harnesses?.[h]?.subscription === true);
-    const blended = typeof c.costPerMTok === 'number'
-      ? c.costPerMTok
-      : ((c.costIn ?? 0) + (c.costOut ?? 0)) / 2; // blended $/Mtok — the axis Router minimises
+    // Blended $/Mtok — the axis Router minimises. The catalog stores prices as costPerMTok:{in,out}
+    // (see ~/.claude/model-router/catalog.json); this function originally only understood a bare
+    // number or costIn/costOut, so every {in,out}-priced metered model blended to $0 and the
+    // cost-optimal router was choosing over all-zero prices (found 2026-07-16 when the console
+    // panel showed DeepSeek as "$0 · yours"). All three shapes are handled now; an unpriced
+    // candidate is Infinity, never a fake $0 — a missing price must not read as free.
+    const p = c.costPerMTok;
+    const blended =
+      typeof p === 'number' ? p
+      : p && typeof p.in === 'number' && typeof p.out === 'number' ? (p.in + p.out) / 2
+      : typeof c.costIn === 'number' && typeof c.costOut === 'number' ? (c.costIn + c.costOut) / 2
+      : Infinity;
     prices[c.id] = covered ? 0 : blended;
   }
   return prices;

package/scripts/route-cheap.mjs

@@ -38,7 +38,10 @@ export const PRICING = {
   'deepseek/deepseek-v4-flash': { in: 0.077, out: 0.154 }, // verified 2026-07-12 OpenRouter /models live; successor to deepseek-chat (which resolves to legacy V3)
   'x-ai/grok-4.5': { in: 2.0, out: 6.0 }, // verified 2026-07-12 OpenRouter /models live; mid-priced frontier-adjacent
 };
-export const FRONTIER = { name: 'claude-opus-4.8', in: 5.0, out: 25.0 };
+// Frontier = the most capable model you'd otherwise reach for. Fable 5 leads the Claude 5 family
+// (2× Opus 4.8 per token — see CLAUDE_TIERS below), so it is the honest "instead of" baseline: every
+// $ the cascade saves is measured against what Fable 5 would have cost on the same tokens.
+export const FRONTIER = { name: 'claude-fable-5', in: 10.0, out: 50.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