ruvnet-brain 4.0.8 → 4.0.24

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.0.8 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.8-updated_2026--07--30_03:24_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 4.0.24 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.24-updated_2026--07--30_03:24_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.**
 
@@ -445,7 +445,7 @@ The brain answers **both** kinds of questions. **Name the repo or ask something
 
 ## What it covers
 
-69 of rUv's repos in the [ruvnet](https://github.com/ruvnet) org — the reusable **building blocks** you'd actually compose into a system — each deep-walked into its own canonical RVF segment. The core blocks below also carry symbol indexes and capability cards (the 8 newest repos are findable by name; their capability cards are coming).
+71 of rUv's repos in the [ruvnet](https://github.com/ruvnet) org — the reusable **building blocks** you'd actually compose into a system — each deep-walked into its own canonical RVF segment. The core blocks below also carry symbol indexes and capability cards (the 8 newest repos are findable by name; their capability cards are coming).
 
 ![The RuvNet stack the brain covers](primer/assets/diagrams/ruvnet-stack.svg)
 
@@ -522,7 +522,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** — 63 public stores · 153,369 public source chunks (70 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 64 public stores · 138,140 public source chunks (71 built stores incl. private), 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–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -24,7 +24,10 @@ import {
   requiredEmbedderModels,
   missingEmbedderModels,
 } from '../kb/model-requirements.mjs';
-import { mergeManagedCatalog } from '../scripts/model-router-catalog.mjs';
+import { applyManagedCatalogUpdate } from '../scripts/model-router-catalog.mjs';
+import {
+  CONSOLE_RUNTIME_SURFACE, CONSOLE_RUNTIME_IDENTITY_FILE, consoleRuntimeDigest,
+} from '../scripts/console-runtime-identity.mjs';
 
 // SEC-0010 #6 — the Ed25519 PUBLIC key is EMBEDDED here (not a separate file) so the installer's
 // trust root travels with the installer code itself: an attacker who swaps the downloaded bundle
@@ -613,22 +616,17 @@ export function beginConsoleRuntimeTransaction(cacheDir, sourceRoot = REPO_ROOT)
   fs.rmSync(prior, { recursive: true, force: true });
   fs.mkdirSync(staged, { recursive: true, mode: 0o700 });
 
-  const required = [
-    ['console', 'console'],
-    ['scripts', 'scripts'],
-    ['plugin/scripts', 'plugin/scripts'],
-    ['data/model-catalog.json', 'data/model-catalog.json'],
-    ['kb/brain-profile.mjs', 'kb/brain-profile.mjs'],
-    ['bin/install.mjs', 'bin/install.mjs'],
-    ['package.json', 'package.json'],
-  ];
-  for (const [from, to] of required) {
-    const source = path.join(sourceRoot, from);
+  // The copy list IS the generation's digest input (scripts/console-runtime-identity.mjs). Adding a
+  // file the runtime needs adds it to the runtime's identity in the same edit, so an asset can never
+  // again travel separately from the executable that reads it (#76) and a candidate can never again
+  // be indistinguishable from the one it replaces (#79).
+  for (const relative of CONSOLE_RUNTIME_SURFACE) {
+    const source = path.join(sourceRoot, relative);
     if (!fs.existsSync(source)) {
       fs.rmSync(staged, { recursive: true, force: true });
-      throw new Error(`console runtime is incomplete: missing ${from}`);
+      throw new Error(`console runtime is incomplete: missing ${relative}`);
     }
-    const target = path.join(staged, to);
+    const target = path.join(staged, relative);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.cpSync(source, target, { recursive: true, force: true, preserveTimestamps: true });
   }
@@ -661,15 +659,28 @@ export function beginConsoleRuntimeTransaction(cacheDir, sourceRoot = REPO_ROOT)
       throw new Error(`console runtime failed syntax verification: ${path.relative(staged, syntaxTarget)}`);
     }
   }
+  // #76: prove the installed What's New boundary from the staged bytes, not from a file listing. The
+  // executable exits nonzero when its version manifest or curated notes are absent, so a runtime that
+  // would have to tell the user "the notes are unavailable" never activates in the first place.
+  const stagedWhatsNew = path.join(staged, 'plugin', 'scripts', 'whats-new.mjs');
+  const whatsNew = spawnSync(process.execPath, [stagedWhatsNew], { encoding: 'utf8' });
+  if (whatsNew.error || whatsNew.status !== 0) {
+    const detail = (whatsNew.stderr || whatsNew.error?.message || `exit ${whatsNew.status}`).trim();
+    fs.rmSync(staged, { recursive: true, force: true });
+    throw new Error(`console runtime cannot report its own release notes: ${detail}`);
+  }
   const identity = {
     product: 'ruvnet-brain-console-runtime',
     schema: 1,
     apiContract: 1,
     runtimeVersion: packageManifest.version,
     entrypoint: 'scripts/onboarding-console.mjs',
-    sourceSha256: crypto.createHash('sha256').update(fs.readFileSync(stagedEntry)).digest('hex'),
+    // The WHOLE runtime, not just its entrypoint (#79). The launcher compares this against a live
+    // server's self-reported identity, so it has to change whenever anything the server executes or
+    // serves changes — otherwise a stale process passes as current.
+    sourceSha256: consoleRuntimeDigest(staged),
   };
-  fs.writeFileSync(path.join(staged, 'runtime-identity.json'), `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
+  fs.writeFileSync(path.join(staged, CONSOLE_RUNTIME_IDENTITY_FILE), `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
 
   let state = 'staged';
   const entry = path.join(runtime, identity.entrypoint);
@@ -2230,6 +2241,37 @@ const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').
 const cronExample = (kbDir) =>
   `47 3 * * *  cd ${kbDir} && ${process.execPath} forge-update.mjs --apply >> ${kbDir}/update.log 2>&1`;
 
+/**
+ * kb/forge-update.mjs exit 11 = "the download completed but the bundle on disk did NOT change"
+ * (its `EXIT_NOT_LANDED`). Duplicated as a literal on purpose: the updater lives in the KB BUNDLE,
+ * which versions and ships independently of this installer, so there is no import to share. The
+ * two are pinned together by tests/unit/update-not-landed-exit.test.mjs, which reads the constant
+ * out of kb/forge-update.mjs and fails if they ever drift.
+ */
+export const UPDATE_NOT_LANDED = 11;
+
+/**
+ * What `--update` does with the KB updater's exit code (issue #106).
+ *
+ * `--update` used to convert an honest failure into a reported success. The updater detected the
+ * problem itself and said so — "UPDATE MISMATCH: SOURCE.json on disk is IDENTICAL to before the
+ * update … REFUSING to report success" — and then the fresh-install FALLBACK below ran, succeeded
+ * at re-installing the very same bytes, and its exit 0 became the exit code of the whole command.
+ * A user's scheduled job read that as success while the corpus had not moved.
+ *
+ * The fallback exists for ONE thing: an old bundle whose canonical manifest URL 404s, where a fresh
+ * install genuinely rescues the user. "Nothing landed" is not that case — it is a TRUE verdict
+ * about an intact KB, and re-downloading the same bundle cannot change it. So that verdict is
+ * terminal and keeps its own exit code; every other failure keeps today's fallback behaviour.
+ */
+export function classifyUpdaterExit(status, { fallbackAllowed = true } = {}) {
+  if (status === 0) return { verdict: 'updated', fallback: false, exitCode: 0 };
+  if (status === UPDATE_NOT_LANDED) {
+    return { verdict: 'not-landed', fallback: false, exitCode: UPDATE_NOT_LANDED };
+  }
+  return { verdict: 'failed', fallback: fallbackAllowed, exitCode: status || 1 };
+}
+
 function missingUpdaterHelp(kbDir) {
   console.error(`\n${c.red('✗ can\'t update:')} ${c.bold('forge-update.mjs')} is missing from ${kbDir}.`);
   console.error(`  Either no brain is installed there, or the bundle predates the self-updater.`);
@@ -2366,12 +2408,29 @@ function runUpdate() {
   // 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) {
+  //
+  // Scoped again 2026-08-04 (issue #106): "nothing landed" is excluded, because for THAT verdict the
+  // fallback re-installed identical bytes and its exit 0 became the command's exit code, turning the
+  // updater's own correct refusal into a reported success.
+  const outcome = classifyUpdaterExit(updateStatus, {
+    fallbackAllowed: !process.env.RUVNET_BRAIN_NO_UPDATE_FALLBACK,
+  });
+  if (outcome.verdict === 'not-landed') {
+    console.error(`\n    ${c.red('✗ the knowledge bundle did not change.')} The updater downloaded a bundle and refused to`);
+    console.error(`      call it an update because the copy on disk is identical to the one it replaced.`);
+    console.error(`      Nothing is broken and nothing was lost — but this run is ${c.bold('not')} a success, so it exits`);
+    console.error(`      ${c.bold(String(UPDATE_NOT_LANDED))} rather than 0 and a scheduled job will see the failure (issue #106).`);
+    console.error(`      If you believe a newer build exists, check:  ${c.bold('node forge-update.mjs --check')}  in ${kbDir}`);
+    process.exit(outcome.exitCode);
+  }
+  if (outcome.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);
+  } else {
+    updateStatus = outcome.exitCode;
   }
   }
   if (updateStatus === 0) {
@@ -2382,6 +2441,25 @@ function runUpdate() {
       updateStatus = 1;
     }
   }
+  // Issue #87: a normal lifecycle update must also carry MANAGED MODEL additions to an existing
+  // user. This call used to live only in offerRouterProfile() — the fresh-install path — so someone
+  // who already had ~/.claude/model-router/catalog.json (i.e. every existing user, the only ones who
+  // can be behind) never received a newly shipped managed candidate no matter how often they
+  // updated. Additive and non-interactive; their overrides win, metered rows are never auto-enabled,
+  // and a failure here is reported but never fails an otherwise-good update.
+  if (updateStatus === 0) {
+    try {
+      const managed = applyManagedCatalogUpdate({
+        routerDir: path.join(os.homedir(), '.claude', 'model-router'),
+        packageRoot: REPO_ROOT,
+      });
+      if (managed.action === 'merged' && managed.added.length) {
+        ok(`model router: added ${managed.added.length} managed model(s) — ${managed.added.join(', ')} (your catalog edits were preserved)`);
+      }
+    } catch (e) {
+      warn(`managed model additions were not merged (${e.message}); your catalog was left unchanged`);
+    }
+  }
   // `--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).
@@ -2975,31 +3053,20 @@ export async function offerRouterProfile() {
   );
 
   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)) continue;
-    if (!fs.existsSync(d)) {
-      fs.copyFileSync(s, d);
-      ok(`installed ${dst} (edit freely — goldie keeps prices fresh where scheduled)`);
-      continue;
-    }
-    if (src === 'catalog.template.json') {
-      try {
-        const existing = JSON.parse(fs.readFileSync(d, 'utf8'));
-        const managed = JSON.parse(fs.readFileSync(s, 'utf8'));
-        const merged = mergeManagedCatalog(existing, managed);
-        if (merged !== existing) {
-          fs.copyFileSync(d, `${d}.pre-managed-merge`);
-          const tmp = `${d}.tmp-${process.pid}`;
-          fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, { mode: 0o600 });
-          fs.renameSync(tmp, d);
-          ok(`merged ${merged.candidates.length - existing.candidates.length} managed subscription model(s); your catalog overrides were preserved`);
-        }
-      } catch (error) {
-        warn(`managed model additions were not merged (${error.message}); your existing catalog was left unchanged`);
-      }
-    }
+  const policySrc = path.join(pkgRoot, 'config', 'model-router', 'policy.default.mjs');
+  const policyDst = path.join(routerDir, 'policy.default.mjs');
+  if (fs.existsSync(policySrc) && !fs.existsSync(policyDst)) {
+    fs.copyFileSync(policySrc, policyDst);
+    ok('installed policy.default.mjs (edit freely — goldie keeps prices fresh where scheduled)');
+  }
+  // ONE implementation of the managed-catalog step, shared with runUpdate() (issue #87). It used to
+  // live here only, which is exactly why existing users never received managed additions.
+  try {
+    const managed = applyManagedCatalogUpdate({ routerDir, packageRoot: pkgRoot });
+    if (managed.action === 'created') ok('installed catalog.json (edit freely — goldie keeps prices fresh where scheduled)');
+    if (managed.action === 'merged') ok(`merged ${managed.added.length} managed subscription model(s); your catalog overrides were preserved`);
+  } catch (error) {
+    warn(`managed model additions were not merged (${error.message}); your existing catalog was left unchanged`);
   }
   let copied = 0;
   // dispatch-receipt + metaharness-receipts added 2026-07-13: without the LOGGER, subagent routing is

package/console/app.js

@@ -2313,6 +2313,25 @@ function renderDistribution(u) {
     el('p', { class: 'fineprint' }, u.note));
 }
 
+// One provider's key chip. THREE states, never two: found, not found, and NOT CHECKED. The third
+// exists because an instrument that could not run has found nothing — it has not found "no key"
+// (issue #86). Pure and total, so the not-checked branch cannot be reached by accident.
+function providerKeyChip(id, keys, keysVerified, names) {
+  const name = names[id] || id;
+  if (!keysVerified) {
+    return el('span', {
+      class: 'plan-key unknown',
+      title: `Not checked: Brain could not load its provider catalog, so it cannot tell whether an API key for ${name} is set on this machine`,
+    }, el('span', { class: 'plan-key-mark', 'aria-hidden': 'true' }, '?'), ` ${name}`);
+  }
+  const found = !!keys[id];
+  return el('span', {
+    class: `plan-key ${found ? 'yes' : 'no'}`,
+    title: found ? `An API key for ${name} is set on this machine`
+                 : `No API key for ${name} found on this machine`,
+  }, el('span', { class: 'plan-key-mark', 'aria-hidden': 'true' }, found ? '✓' : '✗'), ` ${name}`);
+}
+
 // Plan block (issue #24, applying sparkling's #21 redesign) — three genuinely different questions
 // used to render as one flat row of identical "chips": which subscription this runs on ("house" — a
 // word nobody outside the source knows), whether cheap-task routing is on, and which OTHER API keys
@@ -2339,19 +2358,21 @@ function renderProviders(sv) {
 
   // BOX 1 — YOUR PLAN. The one choice here that changes cost: which subscription MetaHarness treats
   // as $0. Footer checklist: which OTHER providers have a real API key on this machine — honest now.
+  //
+  // Issue #86: `keys` is only a MEASUREMENT while the verified provider catalog actually loaded. When
+  // that asset was missing from the packaged runtime, the server fell back to native detections and
+  // said so in providerCatalog — and this checklist ignored it, printing a confident "✗ … No API key
+  // for Gemini found on this machine" straight off `keys`. That turned an internal packaging failure
+  // into a stated fact about the user's credentials. Not-checked is now its own third state.
+  const catalogHealth = re.providerCatalog || null;
+  const keysVerified = !catalogHealth
+    || (catalogHealth.keysVerified !== false && catalogHealth.status !== 'degraded');
   const others = ['anthropic', 'openai', 'google', 'xai'].filter((id) => id !== house.provider);
   const checklist = el('div', { class: 'plan-keys' },
-    el('span', { class: 'plan-keys-lab' }, 'Other keys found:'),
-    ...others.map((id) => {
-      const ok = !!keys[id];
-      return el('span', {
-        class: `plan-key ${ok ? 'yes' : 'no'}`,
-        title: ok ? `An API key for ${KEY_NAME[id]} is set on this machine`
-                  : `No API key for ${KEY_NAME[id]} found on this machine`,
-      },
-        el('span', { class: 'plan-key-mark', 'aria-hidden': 'true' }, ok ? '✓' : '✗'),
-        ` ${KEY_NAME[id]}`);
-    }));
+    el('span', { class: 'plan-keys-lab' }, keysVerified ? 'Other keys found:' : 'Other keys:'),
+    ...others.map((id) => providerKeyChip(id, keys, keysVerified, KEY_NAME)),
+    ...(keysVerified ? [] : [el('span', { class: 'plan-keys-note' },
+      `Not checked — Brain could not load its provider catalog${catalogHealth && catalogHealth.detail ? ` (${catalogHealth.detail})` : ''}.`)]));
   const planBox = el('div', { class: 'plan-box' },
     el('span', { class: 'plan-label' }, 'Your plan', infoBtn('Your plan and OpenRouter', PROVIDERS_INFO)),
     head('is-house', houseName, action('Change', 'provider')),

package/console/style.css

@@ -1236,6 +1236,11 @@ details.sub .sub-body > *:first-child { margin-top: 4px; }
 .plan-key-mark { font-weight: 700; }
 .plan-key.yes .plan-key-mark { color: var(--green-text); }
 .plan-key.no, .plan-key.no .plan-key-mark { color: var(--faint); }
+/* Not checked (issue #86): visually distinct from "no key found" so a degraded catalog never reads
+   as a finding about the user's machine. */
+.plan-key.unknown { color: var(--muted); }
+.plan-key.unknown .plan-key-mark { color: var(--amber); }
+.plan-keys-note { flex-basis: 100%; color: var(--muted); font-size: 11.5px; line-height: 1.5; }
 
 /* WP2b — first-run empty state: confident, designed, not an apology */
 .mh-empty {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.0.8",
+  "version": "4.0.24",
   "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": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 69 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.0.8",
+  "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 71 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
+  "version": "4.0.24",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.0.8",
+  "version": "4.0.24",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"