ruvnet-brain 4.4.1 → 4.5.0

package/kb/brain-profile.mjs

@@ -31,6 +31,7 @@ export function discoverStoreFamilies(dir) {
   let entries = [];
   try { entries = fs.readdirSync(dir); } catch { return []; }
   for (const entry of entries) {
+    if (entry.startsWith('._')) continue; // macOS AppleDouble from an exFAT/FAT volume, never a store
     const match = entry.match(/^(.+?)(?:\.big)?\.rvf$/);
     if (match && !/\.(?:idmap|embed)\b/.test(entry)) names.add(match[1]);
   }

package/kb/corpus-release-identity.mjs

@@ -58,7 +58,7 @@ export const CORPUS_TAG_PATTERN = /^corpus-sha256-[0-9a-f]{64}$/;
 // CORPUS_TAG_PATTERN above is already duplicated this same way for the same reason. Keep both copies
 // byte-identical in behavior; tests/unit/corpus-release-identity-channel-parity.test.mjs pins that.
 
-/** Owner-approved product release: a plain semver tag. */
+/** Product (code) release: a plain semver tag. */
 export const CODE_TAG_PATTERN = /^v\d+\.\d+\.\d+$/;
 
 export function releaseKind(tag) {

package/kb/forge-update.mjs

@@ -25,10 +25,10 @@ import os from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
-import { extractZip } from './zip-extract.mjs';
+import { extractZip, zipDeclaredBytes } from './zip-extract.mjs';
 import { applyBrainProfile, discoverStoreFamilies, readBrainProfile } from './brain-profile.mjs';
 import { acquireRefreshLock, releaseRefreshLock } from './refresh-run.mjs';
-import { runStorageTransaction, treeIdentity, managedStorageInventory, storageDelta } from './update-storage-transaction.mjs';
+import { runStorageTransaction, treeIdentity, managedStorageInventory, storageDelta, checkDiskSpace, directoryBytes } from './update-storage-transaction.mjs';
 import { pruneLifecycleEvidence } from './lifecycle-evidence-retention.mjs';
 import {
   isCorpusReleaseTag, assertCorpusReleaseCompatible, readInstalledRuntime,
@@ -1003,7 +1003,10 @@ function storeInventory(dir) {
   }
   try {
     // Inventory only: tolerate ordinary tooling symlinks (npm .bin). A symlinked .rvf still throws.
-    const files = relativeFiles(dir, '', { strict: false });
+    // macOS volume metadata (AppleDouble `._x.rvf`, .DS_Store) from an exFAT/FAT round trip is neither a
+    // store nor an unclassified file: counting it kept every such backup as "holding a unique store".
+    const files = relativeFiles(dir, '', { strict: false })
+      .filter((name) => !/^(?:\._|\.DS_Store$)/.test(path.basename(name)));
     for (const relative of files.filter((name) => name.endsWith('.rvf'))) {
       if (!declaredFiles.has(relative)) {
         stores.set(path.normalize(relative), relative);
@@ -1059,7 +1062,12 @@ function assertRedundantBackup(backup, live) {
         throw new Error(`unclassified or different symbolic link: ${prior}`);
       }
     } else if (a.isDirectory() && b.isDirectory()) {
-      for (const name of fs.readdirSync(prior)) compare(path.join(prior, name), path.join(current, name));
+      // macOS volume metadata (AppleDouble `._x` = x's extended attributes, .DS_Store = Finder view state)
+      // written by an exFAT/FAT round trip is not Brain data, so it is never what makes a copy unique.
+      for (const name of fs.readdirSync(prior)) {
+        if (/^(?:\._|\.DS_Store$)/.test(name)) continue;
+        compare(path.join(prior, name), path.join(current, name));
+      }
     } else if (a.isFile() && b.isFile()) {
       if (a.size !== b.size || sha256File(prior) !== sha256File(current)) {
         throw new Error(`different bytes: ${prior}`);
@@ -1107,19 +1115,6 @@ function writeSnapshotReceipt(backupPath, { state, reason = null, recoveryComman
   return receipt;
 }
 
-/**
- * Release rollback copies after the new KB has verified (issue #35, Dr. Mark Allen).
- *
- * Exported and pure-ish because it DELETES MULTI-GIGABYTE DIRECTORIES — a bug here destroys user
- * data, so it is tested directly rather than exercised only through a full update run.
- *
- * Refuses to delete any backup holding a `.rvf` store the live KB does not have. That is the
- * private/local-store case: the public bundle does not ship those, the update replaces the directory,
- * and forge-guard still passes because it verifies the store it was asked about — not what went
- * missing. In that situation the backup is the only surviving copy, so it is kept and reported.
- *
- * @returns {{removed: string[], kept: [string, string][], freed: number}}
- */
 /**
  * WHY a guard run failed. forge-guard prints its `[FAIL] ...` lines to STDOUT, and execFileSync puts only
  * STDERR in error.message, so a refused store used to read "Command failed: node .../forge-guard.mjs --name X"
@@ -1137,6 +1132,19 @@ export function describeGuardFailure(error) {
   return `${message.slice(0, 1600)}${cause}`;
 }
 
+/**
+ * Release rollback copies after the new KB has verified (issue #35, Dr. Mark Allen).
+ *
+ * Exported and pure-ish because it DELETES MULTI-GIGABYTE DIRECTORIES — a bug here destroys user
+ * data, so it is tested directly rather than exercised only through a full update run.
+ *
+ * Refuses to delete any backup holding a `.rvf` store the live KB does not have. That is the
+ * private/local-store case: the public bundle does not ship those, the update replaces the directory,
+ * and forge-guard still passes because it verifies the store it was asked about — not what went
+ * missing. In that situation the backup is the only surviving copy, so it is kept and reported.
+ *
+ * @returns {{removed: string[], kept: [string, string][], freed: number}}
+ */
 export function reclaimBackups({
   kbDir,
   backupsMade = [],
@@ -1710,6 +1718,22 @@ async function main() {
   const signature = verifyDownloadedBundle(zipPath, sigPath);
   if (!signature.ok) { fs.rmSync(tmp, { recursive: true, force: true }); die(`✗ SIGNATURE VERIFICATION FAILED: ${signature.reason}`, 4); }
   console.log(`  ✓ signature verified — ${signature.reason}`);
+  // DISK-SPACE PREFLIGHT, before a single byte is unpacked: the bundle unpacks in temp, then a whole
+  // candidate generation is built beside the live one: the bundle, plus what prepareCandidate carries into
+  // it from live — node_modules, and every private/local-ingest store file (restorePrivateFilesIntoCandidate
+  // copies them, so a brain with a large private store needs that much more; review S6). The downloaded
+  // zip itself is already on disk at this point, so free space already reflects it.
+  let space;
+  try {
+    const unpacked = zipDeclaredBytes(zipPath);
+    const privateBytes = Object.values(privateOverlay?.files || {}).reduce((sum, file) => sum + (Number(file?.bytes) || 0), 0);
+    space = checkDiskSpace([
+      { dir: extractDir, bytes: unpacked, purpose: 'unpacked bundle', brain: false },
+      { dir: path.dirname(KB_DIR), bytes: unpacked + directoryBytes(path.join(KB_DIR, 'node_modules')), purpose: 'new generation' },
+      ...(privateBytes ? [{ dir: path.dirname(KB_DIR), bytes: privateBytes, purpose: 'private stores carried into it' }] : []),
+    ]);
+  } catch (error) { space = { ok: true, skipped: error.message }; } // unmeasurable: extraction's own limits still apply
+  if (!space.ok) { fs.rmSync(tmp, { recursive: true, force: true }); die(space.message, 6); }
   try { await extractZip(zipPath, extractDir); }
   catch (error) { fs.rmSync(tmp, { recursive: true, force: true }); die(`extraction failed: ${error.message} — local files untouched.`); }
   // ── TIER 3: the staged bundle names the runtime that built it; this client names the runtime it

package/kb/model-requirements.mjs

@@ -3,6 +3,9 @@ import path from 'node:path';
 
 export const MINILM_MODEL = 'Xenova/all-MiniLM-L6-v2';
 export const BGE_MODEL = 'Xenova/bge-base-en-v1.5';
+// The default cross-encoder every reranked answer loads (forge-rerank.mjs). Named here so the
+// doctor can tell a cold cache from a broken reader without importing the ONNX stack.
+export const RERANKER_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
 
 export function modelPath(modelCache, model) {
   return path.join(modelCache, ...model.split('/'));
@@ -71,7 +74,7 @@ export function requiredEmbedderModels(kbDir) {
   const models = new Set();
   try {
     for (const file of fs.readdirSync(kbDir)) {
-      if (!file.endsWith('.rvf.embed.json')) continue;
+      if (!file.endsWith('.rvf.embed.json') || file.startsWith('._')) continue; // ._: AppleDouble, not a sidecar
       const rvf = file.slice(0, -'.embed.json'.length);
       if (!fs.existsSync(path.join(kbDir, rvf))) continue;
       if (!rvf.endsWith('.big.rvf')) {

package/kb/update-storage-transaction.mjs

@@ -17,6 +17,85 @@ const STATES = Object.freeze([
   'RECOVERY_REQUIRED',
 ]);
 
+// ── DISK-SPACE PREFLIGHT ──────────────────────────────────────────────────────────────────────────
+// An apply needs room for the unpacked bundle (temp), the candidate generation beside the live one
+// (the bundle plus the live node_modules carried into it) and its receipts; measured ~3.3 GB growth and
+// ~5 GB peak per apply on a 1.3 GB brain. Running out half-way leaves a half-built candidate and a
+// confusing ENOSPC, so every install/update measures first and refuses cleanly — nothing touched.
+export const DISK_HEADROOM_BYTES = 256 * 1024 ** 2;
+
+function nearestExisting(dir) {
+  let current = path.resolve(dir);
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return current;
+}
+
+/** Free bytes available to this user on the filesystem holding `dir` (or its nearest existing parent). */
+export function availableBytes(dir, env = process.env, statfs = fs.statfsSync) {
+  // Test seam, honoured only under RUVNET_BRAIN_TEST=1: a full disk cannot be produced on demand.
+  if (env.RUVNET_BRAIN_TEST === '1' && /^\d+$/.test(String(env.RUVNET_TEST_FREE_BYTES || ''))) return Number(env.RUVNET_TEST_FREE_BYTES);
+  // fs.statfsSync arrived in Node 18.15; the package supports node >= 18. Say so plainly instead of a TypeError.
+  if (typeof statfs !== 'function') throw new Error(`this Node (${process.version}) cannot measure free disk space (no fs.statfsSync; needs 18.15+)`);
+  const stat = statfs(nearestExisting(dir));
+  return Number(stat.bavail) * Number(stat.bsize);
+}
+
+/** Bytes of every regular file under `dir`; symlinks are not followed; an absent dir is 0. */
+export function directoryBytes(dir) {
+  let total = 0;
+  const walk = (current) => {
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) { try { total += fs.lstatSync(full).size; } catch { /* vanished */ } }
+    }
+  };
+  walk(dir);
+  return total;
+}
+
+const gb = (bytes) => `${(bytes / 1024 ** 3).toFixed(2)} GB`;
+
+// The ONE supported way to put the Brain on a bigger disk (CONTRIBUTING.md, "Putting the Brain on another
+// disk"). Not RUVNET_BRAIN_HOME: an env var never reaches GUI-launched hosts or launchd, and the installer
+// ignores it while the MCP server honours it — a split brain.
+export const MOVE_BRAIN_HINT = 'move the Brain to a bigger disk with  npx ruvnet-brain --move-brain <folder on that disk>';
+
+/**
+ * `requirements`: [{ dir, bytes, purpose, brain? }]. Requirements on the same filesystem add up. A group
+ * holds the Brain unless every requirement in it says `brain: false` (e.g. a temp-dir unpack), and only
+ * such a group is offered `bigger` as the alternative to freeing space. Returns
+ * { ok, shortfalls: [{ dir, needBytes, freeBytes, shortBytes, purposes }], message }.
+ */
+export function checkDiskSpace(requirements, { available = availableBytes, deviceOf = (dir) => fs.statSync(nearestExisting(dir)).dev,
+  headroom = DISK_HEADROOM_BYTES, what = 'apply this update', bigger = MOVE_BRAIN_HINT } = {}) {
+  const byDevice = new Map();
+  for (const { dir, bytes, purpose, brain = true } of requirements) {
+    const device = deviceOf(dir);
+    const group = byDevice.get(device) || { dir: nearestExisting(dir), bytes: 0, purposes: [], brain: false };
+    group.bytes += bytes;
+    group.purposes.push(`${purpose} ${gb(bytes)}`);
+    group.brain ||= brain !== false;
+    byDevice.set(device, group);
+  }
+  const shortfalls = [];
+  for (const group of byDevice.values()) {
+    const needBytes = group.bytes + headroom;
+    const freeBytes = available(group.dir);
+    if (freeBytes < needBytes) shortfalls.push({ dir: group.dir, needBytes, freeBytes, shortBytes: needBytes - freeBytes, purposes: group.purposes, brain: group.brain });
+  }
+  const message = shortfalls.map((s) => `not enough free disk space to ${what}: ${s.dir} has ${gb(s.freeBytes)} free and needs `
+    + `${gb(s.needBytes)} (${s.purposes.join(' + ')} + ${gb(headroom)} headroom). Free ${gb(s.shortBytes)} on that disk`
+    + `${s.brain && bigger ? `, or ${bigger}` : ''}. Nothing was changed.`).join('\n');
+  return { ok: shortfalls.length === 0, shortfalls, message };
+}
+
 function assertDirectory(dir, label) {
   const stat = fs.lstatSync(dir);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`${label} is not a trusted directory: ${dir}`);

package/kb/zip-extract.mjs

@@ -184,6 +184,28 @@ function safeJoin(destDir, name) {
   return target;
 }
 
+/**
+ * The archive's declared total uncompressed bytes, read from its central directory only (no
+ * extraction) — what the disk-space preflight needs before anything is unpacked. The same safety
+ * limits as extractZip apply, so a hostile archive cannot make the preflight lie small.
+ */
+export function zipDeclaredBytes(zipPath) {
+  const fd = fs.openSync(zipPath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    if (size === 0) throw new Error('archive is empty (0 bytes)');
+    const { cdSize, cdOffset } = centralDirectoryLocation(fd, size);
+    if (cdSize > ZIP_LIMITS.centralDirectoryBytes || cdOffset + cdSize > size) throw new Error('central directory is out of bounds');
+    let total = 0;
+    for (const entry of parseCentralDirectory(readAt(fd, cdSize, cdOffset))) {
+      if (!Number.isSafeInteger(entry.uncompSize) || entry.uncompSize < 0) throw new Error(`entry "${entry.name}" has an unsafe uncompressed size`);
+      total += entry.uncompSize;
+      if (total > ZIP_LIMITS.totalBytes) throw new Error(`archive claims more than ${ZIP_LIMITS.totalBytes} uncompressed bytes`);
+    }
+    return total;
+  } finally { fs.closeSync(fd); }
+}
+
 /**
  * Extract `zipPath` into `destDir`, overwriting existing files (idempotent — the `-o` of
  * `unzip -q -o`). Returns { entries, entryNames, files, bytes, crcChecked }.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "One-command installer for RuvNet Brain \u2014 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 77 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 a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/commands/brain-console.md

@@ -1,10 +1,11 @@
 ---
-description: "Brain Console — RuvNet Brain Console (same console as /rvbc, /brain-console, and /ruvnet-brain:configure — every spelling works). Opens the live console page: your whole RuvNet stack on one page. Read-only until you click."
-updated: 2026-07-20
+description: "Brain Console — the RuvNet Brain Console, also opened by /rnbc (same console as /rnb, /rvbc, /rvcb and /ruvnet-brain:configure — every spelling works). Your whole RuvNet stack on one page. Read-only until you click."
+updated: 2026-10-01
 ---
 
-Launch the **RuvNet Brain Console** for the user. Same console as `/ruvnet-brain:configure`,
-`/rvcb`, and `/brain-console` — every spelling lands here, so never tell the user they typed it wrong.
+Launch the **RuvNet Brain Console** (RNBC) for the user. `/rnbc` is its name; `/rnb`, `/rvbc`,
+`/rvcb`, `/brain-console` and `/ruvnet-brain:configure` open the very same console — every spelling
+lands here, so never tell the user they typed it wrong.
 
 ## The contract you are keeping
 

package/plugin/commands/configure.md

@@ -1,10 +1,11 @@
 ---
-description: Open the RuvNet Brain Onboarding Console — a local web page that mirrors YOUR machine's RuvNet setup, explains it in plain English, and lets you safely configure and fix it. Read-only until you click; every machine change is explained first and is reversible.
-updated: 2026-07-20
+description: Open the RuvNet Brain Console (/rnbc) — a local web page that mirrors YOUR machine's RuvNet setup, explains it in plain English, and lets you safely configure and fix it. Read-only until you click; every machine change is explained first and is reversible.
+updated: 2026-10-01
 ---
 
-Launch the **RuvNet Brain Console** for the user. Same console as `/ruvnet-brain:configure`,
-`/rvcb`, and `/brain-console` — every spelling lands here, so never tell the user they typed it wrong.
+Launch the **RuvNet Brain Console** (RNBC) for the user. `/rnbc` is its name; `/rnb`, `/rvbc`,
+`/rvcb`, `/brain-console` and `/ruvnet-brain:configure` open the very same console — every spelling
+lands here, so never tell the user they typed it wrong.
 
 ## The contract you are keeping
 

package/plugin/commands/rnb-brief.md

@@ -0,0 +1,41 @@
+---
+description: "Come up to speed on this project from AgentDB: the brief (state, what changed, decisions, standing rules, open items, gate outcomes, agent findings) and, on request, the full recorded history. Also records a decision, lesson or open item explicitly, with a read-back receipt."
+updated: 2026-10-01
+---
+
+# RuvNet-Brain: rnb-brief
+
+The user wants to know **what has happened on this project**, from the record — not from your memory.
+
+## Do this
+
+**1. Show the brief.** Run it and show the output as-is:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/continuity-brief.mjs"
+```
+
+**2. If they asked for more** (history, "everything", one kind of thing, a time window), pull it:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/continuity-brief.mjs" --full [--kind decision|lesson|commit|release|gate|finding|open-item] [--since 7d] [--limit 200]
+```
+
+Every line carries its provenance (the AgentDB key and time, or the commit SHA). Quote it when you
+rely on an item. A line marked `detected` was inferred from the transcript, not stated explicitly —
+say so. A line marked `PENDING` is durable in the outbox but not yet committed to AgentDB.
+
+**3. If they asked you to record something** (a decision, a standing rule, an open item):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/continuity-brief.mjs" --record --kind decision|lesson|open-item --text "<exactly what was decided>" [--owner "<who>"]
+```
+
+Report it as stored only when it prints `stored-and-read-back`. `durable-pending` means it is safe in the
+outbox and will commit at the next capture boundary — say exactly that, not "stored".
+
+## What NOT to do
+
+- Do not summarize the history from memory or from the conversation instead of running the command.
+- Do not hand-write rows into `.swarm/memory.db` or call `ruflo memory store` for these yourself.
+- If the last line says `AgentDB: recording stuck`, tell the user that line verbatim before anything else.

package/plugin/commands/rnb.md

@@ -0,0 +1,80 @@
+---
+description: "RNB — opens the RuvNet Brain Console (same console as /rnbc, /rvbc, /brain-console and /ruvnet-brain:configure — every spelling works). Your whole RuvNet stack on one page. Read-only until you click."
+updated: 2026-10-01
+---
+
+Launch the **RuvNet Brain Console** (RNBC) for the user. `/rnbc` is its name; `/rnb`, `/rvbc`,
+`/rvcb`, `/brain-console` and `/ruvnet-brain:configure` open the very same console — every spelling
+lands here, so never tell the user they typed it wrong.
+
+## The contract you are keeping
+
+The page **opens immediately and scans itself while they watch.** The server never blocks: a cold or
+new-project read is answered in milliseconds with "measuring…", the page keeps its skeletons and
+narrates the wait, and each card fills in as its own measurement lands. A chip in the header says how
+old the picture is and re-measures when clicked.
+
+So there is nothing to wait for and nothing to warn them about. **Your entire job is: say one
+sentence, start the server in the background, hand over the URL, and get out of the way.**
+
+## 1. SPEAK FIRST — one short sentence, before any tool call
+
+Your FIRST output — before any tool call, any file read, any search — is one warm line saying you are
+opening it now and it will scan itself live in their browser. Something in the spirit of:
+
+> "Opening your console now — it'll come up right away and scan your setup live while you watch."
+
+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 installed runtime
+
+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
+
+```
+node <repo>/scripts/onboarding-console.mjs --serve --open
+```
+
+**`run_in_background: true`, ALWAYS — never in the foreground.** This is a server: it does not exit,
+so a foreground run hangs the tool call until the 120-second timeout and turns an instant page into
+two minutes of dead air. It binds `127.0.0.1` only and prints `http://127.0.0.1:7411/` within about a
+third of a second.
+
+**Then post the URL immediately.** Do not poll the log, do not wait for a scan, do not check whether
+the data has landed — the page reports its own progress and none of it is visible from here.
+
+**If it reports it is already running**, that is a success, not an error: open the URL yourself with
+`open "http://127.0.0.1:<port>/"`. One honest caveat, worth half a sentence if it comes up — a
+console that is already running is serving the project it was *launched* from, so if they want this
+project's view they can stop that one (`^C` in its terminal) and run this again.
+
+## 4. Hand it over and stop
+
+Give them the URL as a clickable line, and one warm sentence: the page is **read-only until you
+click**, every machine change is **explained first and reversible**, and Settings save at the user
+level only. Worth naming once: the brain's on/off switch is the first card on the page, and the
+header chip says how fresh the reading is and re-measures if they click it.
+
+## 5. If it errors
+
+Report it plainly — the real error, not a guess — and offer to fix it. Never leave them staring at
+a dead tab wondering whether it is still loading.
+
+---
+
+## Things NOT to do before the page is open
+
+Each of these has cost a real user real minutes of silence, and not one of them is needed to open a
+local web page:
+
+- **No knowledge search, no memory recall, no source grounding, no repo exploration.** A cold
+  embedding-model load alone is allowed up to 180 seconds.
+- **No model selection or routing work.**
+- **No reading this repo to "check" anything first.** Find the script, run it.
+
+Do **not** narrate the machine yourself afterwards; the page is the mirror. Your job is to open it,
+say one sentence, and get out of the way.

package/plugin/commands/rnbc.md

@@ -0,0 +1,80 @@
+---
+description: "RNBC — RuvNet Brain Console. Opens the live console page: your whole RuvNet stack on one page — what's installed, what your AI learned, one-click reversible fixes. Read-only until you click. (Also: /rnb, /rvbc, /rvcb, /brain-console — all the same thing.)"
+updated: 2026-10-01
+---
+
+Launch the **RuvNet Brain Console** (RNBC) for the user. `/rnbc` is its name; `/rnb`, `/rvbc`,
+`/rvcb`, `/brain-console` and `/ruvnet-brain:configure` open the very same console — every spelling
+lands here, so never tell the user they typed it wrong.
+
+## The contract you are keeping
+
+The page **opens immediately and scans itself while they watch.** The server never blocks: a cold or
+new-project read is answered in milliseconds with "measuring…", the page keeps its skeletons and
+narrates the wait, and each card fills in as its own measurement lands. A chip in the header says how
+old the picture is and re-measures when clicked.
+
+So there is nothing to wait for and nothing to warn them about. **Your entire job is: say one
+sentence, start the server in the background, hand over the URL, and get out of the way.**
+
+## 1. SPEAK FIRST — one short sentence, before any tool call
+
+Your FIRST output — before any tool call, any file read, any search — is one warm line saying you are
+opening it now and it will scan itself live in their browser. Something in the spirit of:
+
+> "Opening your console now — it'll come up right away and scan your setup live while you watch."
+
+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 installed runtime
+
+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
+
+```
+node <repo>/scripts/onboarding-console.mjs --serve --open
+```
+
+**`run_in_background: true`, ALWAYS — never in the foreground.** This is a server: it does not exit,
+so a foreground run hangs the tool call until the 120-second timeout and turns an instant page into
+two minutes of dead air. It binds `127.0.0.1` only and prints `http://127.0.0.1:7411/` within about a
+third of a second.
+
+**Then post the URL immediately.** Do not poll the log, do not wait for a scan, do not check whether
+the data has landed — the page reports its own progress and none of it is visible from here.
+
+**If it reports it is already running**, that is a success, not an error: open the URL yourself with
+`open "http://127.0.0.1:<port>/"`. One honest caveat, worth half a sentence if it comes up — a
+console that is already running is serving the project it was *launched* from, so if they want this
+project's view they can stop that one (`^C` in its terminal) and run this again.
+
+## 4. Hand it over and stop
+
+Give them the URL as a clickable line, and one warm sentence: the page is **read-only until you
+click**, every machine change is **explained first and reversible**, and Settings save at the user
+level only. Worth naming once: the brain's on/off switch is the first card on the page, and the
+header chip says how fresh the reading is and re-measures if they click it.
+
+## 5. If it errors
+
+Report it plainly — the real error, not a guess — and offer to fix it. Never leave them staring at
+a dead tab wondering whether it is still loading.
+
+---
+
+## Things NOT to do before the page is open
+
+Each of these has cost a real user real minutes of silence, and not one of them is needed to open a
+local web page:
+
+- **No knowledge search, no memory recall, no source grounding, no repo exploration.** A cold
+  embedding-model load alone is allowed up to 180 seconds.
+- **No model selection or routing work.**
+- **No reading this repo to "check" anything first.** Find the script, run it.
+
+Do **not** narrate the machine yourself afterwards; the page is the mirror. Your job is to open it,
+say one sentence, and get out of the way.

package/plugin/commands/rvbc.md

@@ -1,10 +1,11 @@
 ---
-description: "RvBC — RuvNet Brain Console. Opens the live console page: your whole RuvNet stack on one page — what's installed, what your AI learned, one-click reversible fixes. Read-only until you click. (Also: /rvcb, /brain-console — all the same thing.)"
-updated: 2026-07-20
+description: "RvBC — the older spelling of /rnbc, the RuvNet Brain Console (same console as /rnbc, /rnb, /brain-console and /ruvnet-brain:configure — every spelling works). Your whole RuvNet stack on one page. Read-only until you click."
+updated: 2026-10-01
 ---
 
-Launch the **RuvNet Brain Console** for the user. Same console as `/ruvnet-brain:configure`,
-`/rvcb`, and `/brain-console` — every spelling lands here, so never tell the user they typed it wrong.
+Launch the **RuvNet Brain Console** (RNBC) for the user. `/rnbc` is its name; `/rnb`, `/rvbc`,
+`/rvcb`, `/brain-console` and `/ruvnet-brain:configure` open the very same console — every spelling
+lands here, so never tell the user they typed it wrong.
 
 ## The contract you are keeping
 

package/plugin/commands/rvcb.md

@@ -1,10 +1,11 @@
 ---
-description: "RvCB — RuvNet Brain Console (same console as /rvbc, /brain-console, and /ruvnet-brain:configure — every spelling works). Opens the live console page: your whole RuvNet stack on one page. Read-only until you click."
-updated: 2026-07-20
+description: "RvCB — another spelling of /rnbc, the RuvNet Brain Console (same console as /rnbc, /rnb, /rvbc, /brain-console and /ruvnet-brain:configure — every spelling works). Read-only until you click."
+updated: 2026-10-01
 ---
 
-Launch the **RuvNet Brain Console** for the user. Same console as `/ruvnet-brain:configure`,
-`/rvcb`, and `/brain-console` — every spelling lands here, so never tell the user they typed it wrong.
+Launch the **RuvNet Brain Console** (RNBC) for the user. `/rnbc` is its name; `/rnb`, `/rvbc`,
+`/rvcb`, `/brain-console` and `/ruvnet-brain:configure` open the very same console — every spelling
+lands here, so never tell the user they typed it wrong.
 
 ## The contract you are keeping
 

package/plugin/commands/whats-new.md

@@ -1,6 +1,6 @@
 ---
 description: "What's new in RuvNet Brain — the big things in the current MAJOR release (4.0), in plain English. Not the point-release churn — the headline changes since 3.x. Ends by offering to open the Console so you can see it live."
-updated: 2026-07-25
+updated: 2026-10-01
 ---
 
 # RuvNet-Brain: what's new
@@ -24,7 +24,7 @@ The user wants the headline story of the **major** release they're on — the 4.
 The 4.0 line is where the brain got **honest, legible, fast, and self-measuring** — landing now in the
 3.9.x releases. The big things:
 
-- **The Console is the front door.** One live local page (type `/rvbc`) — your whole RuvNet stack on
+- **The Console is the front door.** One live local page (type `/rnbc`) — your whole RuvNet stack on
   one screen: 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, each
@@ -46,8 +46,8 @@ The 4.0 line is where the brain got **honest, legible, fast, and self-measuring*
 **Then offer the Console (the point of the whole thing):**
 
 End by offering to open it: *"Want me to open the Console so you can see all of this live? Just say the
-word — or type `/rvbc`."* If they say yes, follow `rvbc.md` in this same directory exactly (including the
-warm heads-up about the ~20s scan).
+word — or type `/rnbc`."* If they say yes, follow `rnbc.md` in this same directory exactly (one warm sentence, then
+start it in the background — the page opens at once and scans itself live; never promise a duration).
 
 **Honesty rules for this command (same as the product):**
 - If the installed executable fails, report its failure and do not fabricate a highlight.

package/plugin/mcp/server.mjs

@@ -35,6 +35,7 @@ import os from 'node:os';
 import readline from 'node:readline';
 import { writeOwn as writeOwnReadiness } from '../scripts/mcp-readiness.mjs';
 import { callManagedCli, MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
+import { unmountedNotice } from '../scripts/brain-location.mjs';
 
 const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
 const KB = process.env.RUVNET_BRAIN_KB || path.join(BRAIN_HOME, 'kb');
@@ -272,10 +273,14 @@ async function ensureChild() {
         recordStartupFailure({ phase, startedAt, generation: c.generation, error: e });
         throw new Error(`brain worker failed to initialize: ${e.message}`);
       }
+      // kbDir: WHICH knowledge base this worker opened (ADR-0098 positive confirmation "In use") — the
+      // physical path, so a worker still serving a replaced or second copy is visible, not assumed.
+      let openedKb = KB;
+      try { openedKb = fs.realpathSync(KB); } catch { /* reported as spelled */ }
       writeReadiness({
         state: 'ready', phase, generation: c.generation,
         workerPid: c.proc.pid, elapsedMs: Date.now() - startedAt,
-        retryable: false, retryState: 'none',
+        retryable: false, retryState: 'none', kbDir: openedKb,
       });
       armChildIdleTimer(c);
       return c;
@@ -366,7 +371,10 @@ async function handleClient(msg) {
         });
       }
       if (!c) {
-        return clientOk(id, { content: [{ type: 'text', text: `search_ruvnet error: the brain bundle is unavailable at ${KB}. Diagnose the active installation and KB path before choosing a repair.` }], isError: true });
+        // Moved to a disk that is not plugged in: one plain line, never 'diagnose the installation'.
+        const unmounted = unmountedNotice({ brainHome: BRAIN_HOME });
+        return clientOk(id, { content: [{ type: 'text', text: unmounted ? `search_ruvnet error: ${unmounted}`
+          : `search_ruvnet error: the brain bundle is unavailable at ${KB}. Diagnose the active installation and KB path before choosing a repair.` }], isError: true });
       }
       pendingCount++;
       try {