ruvnet-brain 4.0.1 → 4.0.2

package/console/tips.js

@@ -0,0 +1,128 @@
+/* RuvNet Brain — How to use it (page two).
+   Two behaviors, both progressive enhancement — with JS off the page reads exactly as before:
+   1. The same theme toggle as the console (same 'rbc-theme' key, same data-theme mechanism).
+   2. Collapsible sections (owner, 2026-07-24: the page "gets too overwhelming as a wall of
+      text"). Every .depth.card collapses behind its own header; only the inventory — the
+      section that IS the page — starts open. Open state persists per browser; a #hash
+      deep-link always opens its target. */
+(function () {
+  'use strict';
+
+  /* ── theme toggle (unchanged) ─────────────────────────────────────────────── */
+  var KEY = 'rbc-theme';
+  var btn = document.getElementById('theme-toggle');
+  function applyTheme(t) {
+    document.documentElement.dataset.theme = t;
+    try { localStorage.setItem(KEY, t); } catch (e) { /* private mode is fine */ }
+  }
+  if (btn) {
+    btn.addEventListener('click', function () {
+      applyTheme(document.documentElement.dataset.theme === 'light' ? 'dark' : 'light');
+    });
+  }
+
+  /* ── collapsible sections ─────────────────────────────────────────────────── */
+  var OPEN_KEY = 'rbc-tips-open';
+  var DEFAULT_OPEN = ['inventory']; // the lead section IS the page; everything else waits
+  var sections = Array.prototype.slice.call(document.querySelectorAll('section.depth.card'));
+  if (!sections.length) return;
+
+  function savedOpen() {
+    try {
+      var raw = localStorage.getItem(OPEN_KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch (e) { return null; }
+  }
+  function persist() {
+    try {
+      var open = sections.filter(function (s) { return !s.classList.contains('is-collapsed'); })
+        .map(function (s) { return s.id; });
+      localStorage.setItem(OPEN_KEY, JSON.stringify(open));
+    } catch (e) { /* private mode is fine */ }
+  }
+
+  function setOpen(sec, open) {
+    sec.classList.toggle('is-collapsed', !open);
+    var head = sec.querySelector(':scope > .depth-head');
+    if (head) head.setAttribute('aria-expanded', open ? 'true' : 'false');
+  }
+
+  var open = savedOpen() || DEFAULT_OPEN;
+  sections.forEach(function (sec) {
+    var head = sec.querySelector(':scope > .depth-head');
+    if (!head || !sec.id) return;
+
+    // Wrap EVERYTHING after the header — several sections carry an art <figure> as a sibling of
+    // .depth-body, and a collapsed section that still shows its full-bleed art has not collapsed.
+    // grid-template-rows animates the height without measuring it (no reflow jank).
+    var dc = document.createElement('div'); dc.className = 'dc';
+    var dci = document.createElement('div'); dci.className = 'dci';
+    var after = [];
+    var walk = head.nextElementSibling;
+    while (walk) { after.push(walk); walk = walk.nextElementSibling; }
+    if (!after.length) return;
+    sec.appendChild(dc); dc.appendChild(dci);
+    after.forEach(function (n) { dci.appendChild(n); });
+
+    // The header is the disclosure control: chevron, ARIA, keyboard.
+    var chev = document.createElement('span');
+    chev.className = 'dc-chev';
+    chev.setAttribute('aria-hidden', 'true');
+    var svgNS = 'http://www.w3.org/2000/svg';
+    var csvg = document.createElementNS(svgNS, 'svg'); csvg.setAttribute('viewBox', '0 0 24 24');
+    var cpath = document.createElementNS(svgNS, 'path'); cpath.setAttribute('d', 'M6 9l6 6 6-6');
+    csvg.appendChild(cpath); chev.appendChild(csvg);
+    head.appendChild(chev);
+    head.setAttribute('role', 'button');
+    head.setAttribute('tabindex', '0');
+    head.setAttribute('aria-controls', sec.id + '-body');
+    dc.id = sec.id + '-body';
+    sec.classList.add('dc-ready');
+
+    function toggle() { setOpen(sec, sec.classList.contains('is-collapsed')); persist(); }
+    head.addEventListener('click', function (e) {
+      if (e.target.closest && e.target.closest('a, button')) return; // links in headers stay links
+      toggle();
+    });
+    head.addEventListener('keydown', function (e) {
+      if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); toggle(); }
+    });
+
+    setOpen(sec, open.indexOf(sec.id) !== -1);
+  });
+
+  // One small master switch, right-aligned above the first section.
+  var all = document.createElement('p');
+  all.className = 'dc-all';
+  var allBtn = document.createElement('button');
+  allBtn.type = 'button';
+  function anyCollapsed() {
+    return sections.some(function (s) { return s.classList.contains('is-collapsed'); });
+  }
+  function labelAll() { allBtn.textContent = anyCollapsed() ? 'expand all' : 'collapse all'; }
+  allBtn.addEventListener('click', function () {
+    var opening = anyCollapsed();
+    sections.forEach(function (s) { setOpen(s, opening); });
+    persist(); labelAll();
+  });
+  all.appendChild(allBtn);
+  sections[0].parentNode.insertBefore(all, sections[0]);
+  labelAll();
+  sections.forEach(function (s) {
+    var h = s.querySelector(':scope > .depth-head');
+    if (!h) return;
+    h.addEventListener('click', function () { setTimeout(labelAll, 0); });
+    h.addEventListener('keydown', function () { setTimeout(labelAll, 0); });
+  });
+
+  // A #hash deep-link must always land on an OPEN section — from the console's cards, the
+  // metaharness cross-reference, or a shared URL.
+  function openHashTarget() {
+    var id = (location.hash || '').replace(/^#/, '');
+    if (!id) return;
+    var sec = document.getElementById(id);
+    if (sec && sec.classList.contains('depth')) { setOpen(sec, true); persist(); labelAll(); }
+  }
+  window.addEventListener('hashchange', openHashTarget);
+  openHashTarget();
+}());

package/docs/RELEASE-NOTES-4.0.md

@@ -0,0 +1,88 @@
+# RuvNet-Brain 4.0 line — what's new (the major-release highlights)
+
+Updated: 2026-07-30
+
+> **Source of truth** for the `/whats-new` command and the first-run upgrade message. Curated, honest,
+> major-only — not the point-release churn. If a claim here isn't true of the shipping build, it does not
+> belong here. The self-measurement claims are deliberately hedged: they are *new and filling*, not
+> *proven*.
+>
+> **VERSION STATUS:** the public release line is now 4.x. Publication does not erase the remaining
+> acceptance obligations: the exact public artifact must still pass the fail-closed release contract
+> through fresh Claude Code and Codex hosts. Anything not proven through that boundary is listed as a
+> limitation, never converted into a capability claim.
+
+**One line:** the 4.0 line is where the brain got **honest, legible, fast, and self-measuring** — and
+it's landing now.
+
+## The big things
+
+### Release proof is fail-closed
+The 4.0 release path now separates a clean candidate seal from a post-publication seal. Dirty
+lineage, zero/skipped/todo tests, open issues, red or pending exact-SHA workflows, a missing
+`ruvnet-brain` self-RVF store, weak query-deadline margin, missing independent graders,
+host/artifact mismatches, and public-byte drift are release failures rather than warnings.
+`npm run release:proof -- --status --quick` shows the current live blockers.
+
+### 1. The Console is the front door
+Type `/rvbc` and your whole RuvNet stack is on one live local page: what's installed, what the AI has
+actually learned from *your* projects (real memories + distilled lessons, drill-down to the verbatim
+cards), which subscription pays for what, and one-click **reversible** fixes for anything stale. New in
+4.0:
+- a plain-English **explainer on every card** (no more guessing what "trust & provenance" means),
+- every suggestion carries its **blast radius** — *just this project* vs *every project · this machine*,
+- **safe on/off checkboxes** that appear *only* where the undo is proven,
+- a **terminal-first install** — the granular "here's exactly what I'll do, uncheck any of it" flow runs
+  in your terminal, where an `npx` user expects it.
+
+### 2. It will not lie about your machine
+Every number is measured live from your setup. **"We couldn't check" never renders as "off."** One
+project's state can never leak into another project's view (a real bug 4.0 fixed in the console itself).
+Empty-first, honest-always.
+
+### 3. Fast — and it tells you when it's ready
+The console and tips page paint in **well under a second** (measured, with a QE suite that runs every
+time). On a first scan it shows a **countdown** and then says *"it's live — take a look at your page,"*
+so you're never staring at a blank screen wondering if it hung.
+
+### 4. It measures itself now
+The brain records when it offered help and whether you acted on it — so over time it can **prove** it's
+improving instead of asserting it. **Honest caveat:** this instrumentation is *new* and has only just
+started collecting. 4.0 is not a claim of "proven better in the field" — it is the release that makes
+that proof *possible*, and the evidence accrues as you use it.
+
+### 5. It learns across your projects
+A lesson proven in one project can be **promoted to your global brain** and applied everywhere — and it
+now **survives an update** (tested against the real updater, not argued).
+
+### 6. Runs on your account, cheapest capable model
+The QE suite and model routing use **your Claude account, not an API key**, at the least-powerful model
+that does the job. Nothing bills silently.
+
+### 7. Claude Code and Codex share one active runtime
+Both hosts are wired to the same Stable Spine generation: the MCP search shell, lifecycle hooks,
+skills and update behavior advance as one versioned runtime instead of being installed as unrelated
+copies.
+
+### 8. Source grounding is an RVF-native product surface
+The Brain searches per-repository RuVector RVF stores, joins hits to their source passages, and
+returns cited repository paths. Model memory is not accepted as evidence for rUv-stack claims.
+
+### 9. Quality and harness workflows are explicit
+Agentic-QE is the testing fleet. Harness scoring evaluates the orchestration layer, and cost-aware
+routing can select cheaper capable models when the required provider access is configured. These are
+named workflows a user can request, not silent substitutes.
+
+## What 4.0 deliberately does NOT claim
+Stated up front because overclaiming is the one thing this product cannot do:
+- **Not** "proven X% better" — the outcome ledger is still filling (see #4).
+- **Not** "fully proactive / anticipatory" — the brain still mostly speaks when you open the console or
+  ask; the in-session, unprompted surface is the next frontier, not a shipped 4.0 guarantee.
+- **Not** independently graded ≥95 on the exact public artifact. A score is not a release substitute.
+- **Not** fully accepted while any critical exact-artifact, host, retrieval, version-convergence or
+  recovery invariant is FAIL, UNKNOWN, skipped or mocked-only.
+
+## For upgraders
+On the first real major-version transition, the installer/session experience presents the concise
+highlights once. Run `npx ruvnet-brain --whats-new` at any time to read this full list again, or
+`npx ruvnet-brain --what-changed` to inspect the exact machine footprint and undo path for each piece.

package/kb/model-requirements.mjs

@@ -19,19 +19,50 @@ export function modelCacheReady(modelCache, model, revision = null) {
   ].every((file) => fs.existsSync(file));
 }
 
+function acquireMaterializeLock(destination, timeoutMs = 30_000) {
+  const lock = `${destination}.materialize-lock`;
+  const started = Date.now();
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  while (true) {
+    try {
+      fs.mkdirSync(lock);
+      return () => fs.rmSync(lock, { recursive: true, force: true });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        const ageMs = Date.now() - fs.statSync(lock).mtimeMs;
+        if (ageMs > timeoutMs) {
+          fs.rmSync(lock, { recursive: true, force: true });
+          continue;
+        }
+      } catch { /* another process released it between checks */ }
+      if (Date.now() - started >= timeoutMs) {
+        throw new Error(`timed out waiting to materialize model cache: ${destination}`);
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+}
+
 // Revision-pinned downloads live below <model>/<revision>/, while strict offline reads resolve
 // <model>/ directly. Promote only the exact pinned files into that canonical offline location.
 export function materializeModelRevision(modelCache, model, revision) {
   if (!revision || !modelCacheReady(modelCache, model, revision)) return false;
   const source = path.join(modelPath(modelCache, model), revision);
   const destination = modelPath(modelCache, model);
-  for (const entry of fs.readdirSync(source)) {
-    fs.cpSync(path.join(source, entry), path.join(destination, entry), {
-      recursive: true,
-      force: true,
-    });
+  const release = acquireMaterializeLock(destination);
+  try {
+    if (modelCacheReady(modelCache, model)) return true;
+    for (const entry of fs.readdirSync(source)) {
+      fs.cpSync(path.join(source, entry), path.join(destination, entry), {
+        recursive: true,
+        force: true,
+      });
+    }
+    return modelCacheReady(modelCache, model);
+  } finally {
+    release();
   }
-  return modelCacheReady(modelCache, model);
 }
 
 // The RVF sidecar is the source of truth for the query embedder. Only sidecars with a matching

package/keys/ruvnet-brain-signing.pub.pem

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAgse9TAtehXUvUfTrJFY2CCHiCbmelR8yCgS//sen5/w=
+-----END PUBLIC KEY-----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "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": {
@@ -8,6 +8,9 @@
   },
   "scripts": {
     "test": "node plugin/test/run-tests.mjs",
+    "release:proof": "node scripts/release-proof.mjs",
+    "benchmark:brain50": "node scripts/brain-latency-50.mjs",
+    "benchmark:novice50": "node scripts/brain-novice-50.mjs",
     "version:check": "node scripts/sync-version.mjs --check",
     "claims:verify": "node scripts/claims-verify.mjs",
     "claims:fix": "node scripts/claims-verify.mjs --fix",
@@ -61,33 +64,16 @@
     "!plugin/scripts/.ruvnet-brain/",
     "!plugin/test/",
     "README.md",
+    "docs/RELEASE-NOTES-4.0.md",
     "LICENSE",
+    "console/",
     "config/model-router/",
+    "scripts/",
     "kb/verify-citation.mjs",
     "kb/zip-extract.mjs",
     "kb/brain-profile.mjs",
     "kb/model-requirements.mjs",
-    "scripts/model-router-engine.mjs",
-    "scripts/model-router-setup.mjs",
-    "scripts/model-router-status.mjs",
-    "scripts/model-router-outcome.mjs",
-    "scripts/subscription-hosts.mjs",
-    "scripts/dual-host-deliberation.mjs",
-    "scripts/dual-host-suggest.mjs",
-    "scripts/route-cheap.mjs",
-    "scripts/dispatch-receipt.mjs",
-    "scripts/metaharness-receipts.mjs",
-    "scripts/codex-routed.sh",
-    "scripts/metaharness-router.mjs",
-    "scripts/no-silent-substitution.mjs",
-    "scripts/user-settings.mjs",
-    "scripts/selfcheck.mjs",
-    "scripts/hook-registry.mjs",
-    "scripts/install-scope.mjs",
-    "scripts/upgrade-notice.mjs",
-    "scripts/falsify.mjs",
-    "scripts/nightly-watchdog.mjs",
-    "scripts/job-heartbeat.sh"
+    "keys/ruvnet-brain-signing.pub.pem"
   ],
   "engines": {
     "node": ">=18"

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

@@ -1,5 +1,6 @@
 {
   "name": "ruvnet-brain",
+  "description": "Source-grounded RuvNet Brain integrations for Claude Code and Codex.",
   "owner": {
     "name": "Stuart Kerr"
   },

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.1",
+  "version": "4.0.2",
   "author": {
     "name": "Stuart Kerr"
   },
@@ -18,6 +18,5 @@
     "brain",
     "mcp",
     "claude-code"
-  ],
-  "updated": "2026-07-30"
+  ]
 }

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

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

package/plugin/commands/brain-console.md

@@ -7,8 +7,8 @@ updated: 2026-07-20
 correct the user's spelling.
 
 1. Say: "Opening it now; it scans live while you watch."
-2. Locate `scripts/onboarding-console.mjs` in the current repository, then
-   `~/Code/ruvnet-brain/scripts/onboarding-console.mjs`. Do not invent another path.
+2. Use `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository copy is allowed only for an explicit developer checkout.
 3. Run `node <resolved-script> --serve --open` in the background.
 4. Give the URL immediately. Never promise a duration; the page reports its own progress.
 

package/plugin/commands/configure.md

@@ -8,8 +8,9 @@ their actual machine and lets them configure and (with consent) fix it.
 
 Do this:
 
-1. **Find the repo.** Prefer `~/Code/ruvnet-brain`. If `$CLAUDE_PLUGIN_ROOT` is set, the repo may be
-   its parent directory. Use whichever path contains `scripts/onboarding-console.mjs`.
+1. **Find the installed runtime.** Use
+   `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository copy is allowed only for an explicit developer checkout.
 
 2. **Start the server in the BACKGROUND** (it is a long-running process) so this turn keeps going, and
    open the browser:

package/plugin/commands/rvbc.md

@@ -26,10 +26,11 @@ opening it now and it will scan itself live in their browser. Something in the s
 Say it like a person, not a status bar. **Do not** promise 20 seconds, a minute, or any duration: the
 page carries its own timing now, and a number invented here is a number the page will contradict.
 
-## 2. Find the repo
+## 2. Find the installed runtime
 
-Prefer `~/Code/ruvnet-brain`. If `$CLAUDE_PLUGIN_ROOT` is set, the repo may be its parent
-directory. Use whichever path actually contains `scripts/onboarding-console.mjs`.
+Use `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+A current-repository copy is allowed only in an explicit developer checkout. Never guess a
+`~/Code/ruvnet-brain` path: the installer persists this runtime for clean users.
 
 ## 3. Start it in the BACKGROUND and open the browser
 

package/plugin/commands/rvcb.md

@@ -7,8 +7,8 @@ updated: 2026-07-20
 correct the user's spelling.
 
 1. Say: "Opening it now; it scans live while you watch."
-2. Locate `scripts/onboarding-console.mjs` in the current repository, then
-   `~/Code/ruvnet-brain/scripts/onboarding-console.mjs`. Do not invent another path.
+2. Use `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository copy is allowed only for an explicit developer checkout.
 3. Run `node <resolved-script> --serve --open` in the background.
 4. Give the URL immediately. Never promise a duration; the page reports its own progress.
 

package/plugin/hooks/hooks.json

@@ -1,6 +1,5 @@
 {
-  "_note": "STABLE SPINE (ADR-023): every hook routes through hook-shim.mjs, which resolves the ACTIVE generation from ~/.cache/ruvnet-brain/active.json per invocation. This file is boot-frozen, so matcher, command, and dispatch-mode changes require restart classification. Advisory hooks keep `|| true` and can never block a turn. FOUR blocking hooks remain unguarded because their exit codes are their contract: route-dispatch, design-wall, unprompted-speech, and protect-state. Issue #48 demoted verify-interface to advisory-only: raw shell reconstruction may suggest the structured ruvnet_cli_help/ruvnet_cli_run boundary but can never authorize or deny execution. protect-state remains a blocking offBehavior:'run' consent guard. continuation-gate remains advisory with offBehavior:'run'.",
-  "_platform": "posix",
+  "description": "POSIX Stable Spine (ADR-023): every hook routes through hook-shim.mjs, which resolves the active generation per invocation. Advisory hooks fail open; blocking hooks preserve their exit-code contract.",
   "hooks": {
     "SessionStart": [
       {

package/plugin/mcp/managed-cli-interface.mjs

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { loadRuntimePreferences, runtimeChildEnv } from '../scripts/runtime-preferences.mjs';
 
 export const MANAGED_EXECUTABLES = Object.freeze([
   'ruflo',
@@ -142,9 +143,21 @@ function writeStamps(executable, argv, env) {
   }
 }
 
+export function resolveManagedExecutable(executable, env = process.env) {
+  if (executable !== 'ruflo') return executable;
+  const home = env.HOME || os.homedir();
+  const canonical = path.join(home, '.npm-global', 'bin', 'ruflo');
+  try {
+    fs.accessSync(canonical, fs.constants.X_OK);
+    return canonical;
+  } catch {
+    return executable;
+  }
+}
+
 function execute(executable, argv, env) {
   return new Promise((resolve) => {
-    const child = spawn(executable, argv, {
+    const child = spawn(resolveManagedExecutable(executable, env), argv, {
       env,
       shell: false,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -186,8 +199,9 @@ function execute(executable, argv, env) {
 
 function resultOf(executable, argv, result) {
   const output = [result.stdout, result.stderr].filter(Boolean).join(result.stdout && result.stderr ? '\n' : '');
-  if (result.error || result.code !== 0) {
-    const reason = result.error || `exit ${result.code}`;
+  const contradictoryFailure = /(?:^|\n)\s*(?:❌|\[ERROR\])|invalid pragma command|key not found/i.test(output);
+  if (result.error || result.code !== 0 || contradictoryFailure) {
+    const reason = result.error || (contradictoryFailure ? 'fatal output despite exit 0' : `exit ${result.code}`);
     return {
       content: [{ type: 'text', text: output || `${executable} ${argv.join(' ')} failed: ${reason}` }],
       isError: true,
@@ -220,7 +234,36 @@ export async function callManagedCli(toolName, args, env = process.env) {
           isError: true,
         };
       }
-      return resultOf(executable, argv, await execute(executable, argv, env));
+      const policy = loadRuntimePreferences({ env, cwd: env.RUVNET_BRAIN_PROJECT_DIR || process.cwd() });
+      if (executable === 'agentic-flow' && policy.values.routing !== 'auto') {
+        return {
+          content: [{
+            type: 'text',
+            text: policy.values.routing === 'off'
+              ? 'Token-smart routing is off in RuvNet Brain Console; agentic-flow was not started.'
+              : 'Token-smart routing has not been enabled in RuvNet Brain Console; agentic-flow was not started.',
+          }],
+          isError: true,
+        };
+      }
+      const isFleetMutation = executable === 'agentic-qe'
+        && argv[0] === 'fleet'
+        && ['init', 'spawn', 'run'].includes(argv[1]);
+      if (isFleetMutation && policy.values.qeFleet !== true) {
+        return {
+          content: [{
+            type: 'text',
+            text: policy.values.qeFleet === false
+              ? 'The Agentic-QE fleet is off in RuvNet Brain Console; no QE agents were started.'
+              : 'The Agentic-QE fleet has not been enabled in RuvNet Brain Console; no QE agents were started.',
+          }],
+          isError: true,
+        };
+      }
+      const childEnv = (executable === 'agentic-flow' || executable === 'agentic-qe')
+        ? runtimeChildEnv({ env, cwd: env.RUVNET_BRAIN_PROJECT_DIR || process.cwd() })
+        : env;
+      return resultOf(executable, argv, await execute(executable, argv, childEnv));
     }
 
     return {

package/plugin/mcp/server.mjs

@@ -147,6 +147,10 @@ function killChild(reason) {
 async function ensureChild() {
   const gen = currentGeneration();
   if (child && child.generation !== gen && pendingCount === 0) await killChild('superseded by a newer generation');
+  // A concurrent initialize/tools-list/tools-call must join the same readiness promise. Returning
+  // `child` while its private initialize or model warmup is still running advertises a half-ready
+  // worker and charges cold-start to the first user call.
+  if (childStartup) return childStartup;
   if (child) return child;
   await childRetirement;
   if (!fs.existsSync(CHILD_MCP)) return null;
@@ -177,6 +181,17 @@ async function ensureChild() {
           capabilities: {},
           clientInfo: { name: 'ruvnet-brain-shell', version: SERVER_INFO.version },
         }, CHILD_INIT_TIMEOUT_MS);
+        const warmed = await childRequest(c, 'brain/warmup', {}, CHILD_INIT_TIMEOUT_MS);
+        // Rolling-upgrade compatibility: 4.0.1 workers predate the private warmup extension. The
+        // stable shell is installed before the 700MB KB swap completes, so rejecting -32601 here
+        // makes every query fail during the exact in-place upgrade window the shell exists to hide.
+        // An older initialized worker is usable (its first query may be cold); any other warmup
+        // failure still fails closed.
+        const warmupUnsupported = warmed.error?.code === -32601
+          || /method not found/i.test(String(warmed.error?.message || ''));
+        if (!warmupUnsupported && (warmed.error || warmed.result?.ready !== true)) {
+          throw new Error(warmed.error?.message || 'brain worker did not confirm warm readiness');
+        }
       } catch (e) {
         await killChild('failed initialize');
         throw new Error(`brain worker failed to initialize: ${e.message}`);
@@ -241,6 +256,12 @@ async function handleClient(msg) {
   if (id === undefined || id === null) return; // notifications need no answer
   switch (method) {
     case 'initialize':
+      // MCP initialize itself stays protocol-fast; normal clients request tools/list immediately
+      // afterwards, which joins this readiness promise and does not receive the tool declaration
+      // until the worker's query embedder and cross-encoder are warm.
+      void ensureChild().catch((e) => {
+        console.error(`[ruvnet-brain] worker warmup failed during initialize: ${e.message}`);
+      });
       return clientOk(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });
     case 'ping':
       return clientOk(id, {});

package/plugin/scripts/detach.mjs

@@ -107,11 +107,25 @@ if (!SUPERVISOR) {
         ? path.join(process.env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
         : 'powershell.exe';
       const quotePs = (value) => `'${String(value).replaceAll("'", "''")}'`;
+      // Start-Process has its own standard-stream boundary. On GitHub's packed PowerShell install
+      // path the SessionStart body finished but the external checker never received `close` before
+      // its 5s watchdog — consistent with a descendant retaining a capture handle, though that job
+      // did not instrument exact handle ownership. Redirect both streams to distinct files at the
+      // native boundary so the supervisor cannot inherit the hook's capture streams; redirecting
+      // only this short Node wrapper's stdio does not establish that contract for its grandchild.
+      const supervisorOut = logPath && logPath !== '-'
+        ? `${logPath}.supervisor.stdout`
+        : path.join(os.tmpdir(), `ruvnet-brain-detach-supervisor-${process.pid}.stdout`);
+      const supervisorErr = logPath && logPath !== '-'
+        ? `${logPath}.supervisor.stderr`
+        : path.join(os.tmpdir(), `ruvnet-brain-detach-supervisor-${process.pid}.stderr`);
       const launch = [
         'Start-Process',
         '-FilePath', quotePs(process.execPath),
         '-ArgumentList', `@(${quotePs(SELF)},${quotePs('--payload-env')})`,
         '-WindowStyle', 'Hidden',
+        '-RedirectStandardOutput', quotePs(supervisorOut),
+        '-RedirectStandardError', quotePs(supervisorErr),
       ].join(' ');
       child = spawn(powershell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', launch], {
         detached: true,

package/plugin/scripts/first-session-worker.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// One detached first-session lifecycle worker: seed the Stable Spine, then perform the update
+// heartbeat the seed used to race. Keeping both operations in one worker preserves ADR-054's
+// "Brain OFF still receives fixes" contract without making SessionStart launch two detachers.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const [updateApply, hostUpdate, versionLog] = process.argv.slice(2);
+if (![updateApply, hostUpdate, versionLog].every((value) => typeof value === 'string' && value)) {
+  process.stderr.write('usage: first-session-worker.mjs <update-apply.mjs> <host-update.mjs> <version-log>\n');
+  process.exit(2);
+}
+
+const seed = spawnSync(process.execPath, [updateApply, '--seed'], {
+  env: process.env,
+  stdio: 'inherit',
+});
+if (seed.error || seed.status !== 0) {
+  process.stderr.write(`[ruvnet-brain] first-session seed failed: ${seed.error?.message || `exit ${seed.status}`}\n`);
+  process.exit(1);
+}
+
+const check = spawnSync(process.execPath, [hostUpdate, '--check'], {
+  env: process.env,
+  encoding: 'utf8',
+});
+const version = String(check.stdout || '').trim();
+if (!check.error && check.status === 0 && /^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/.test(version)) {
+  fs.mkdirSync(path.dirname(versionLog), { recursive: true });
+  const temporary = `${versionLog}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, `${version}\n`);
+  fs.renameSync(temporary, versionLog);
+}
+
+// Network failure must not undo a successful seed. The 15-minute heartbeat stamp lets the normal
+// SessionStart path retry later, while the current runtime remains valid and usable.
+process.exit(0);