ruvnet-brain 4.0.1 → 4.0.4

package/.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/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.0.1 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.1-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.4 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.4-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.**
 
@@ -30,7 +30,7 @@
 [![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)
-[![coverage](https://img.shields.io/badge/coverage-32%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
+[![coverage](https://img.shields.io/badge/coverage-34%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
 
 > **One Brain generation everywhere.** npm, the GitHub tag/release, bundle manifests, source metadata, and checksum-bound RVF generations must share the same product version. Headline claims are regenerated and checked by the claims ledger (`scripts/claims-verify.mjs`); other numbers below are hand-stamped and dated:
 > - **`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.
@@ -485,7 +485,7 @@ node plugin/test/run-tests.mjs                    # full plugin QA over real JSO
 | **L4 "orchestrate"** | **downgraded — measures speech, not obedience** | L4 asserts the hook's own injected prose contains required words (`must: ['take the wheel','SPARC','swarm',…]`). That proves **the brain spoke**. It cannot fail when the advice is read and ignored — which is the failure this product exists to prevent. Counterfactual replay against a brain-off control (ADR-058 §D4) is what will earn this row back |
 | **Plugin QA** | **60 / 60** | manifests, hook firing, MCP `initialize`/`tools/list`, capability battery |
 | **Clean-room install** | **3 / 3** | download the published bundle fresh → unzip → query → grounded, cited answers |
-| **Unit tests** | **2,327 passing, 169 todo** · 32% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 32% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
+| **Unit tests** | **2,327 passing, 169 todo** · 34% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 34% 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 |
 
@@ -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** — 62 public stores · 151,033 public source chunks (69 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** — 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.
 - ✅ **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

@@ -95,6 +95,7 @@ const FLAG_ENABLE_SPEND_GUARD = argv.includes('--enable-spend-guard');
 const FLAG_DISABLE_SPEND_GUARD = argv.includes('--disable-spend-guard'); // the missing undo
 const FLAG_UNINSTALL = argv.includes('--uninstall'); // reverse everything, in one command
 const FLAG_WHAT_CHANGED = argv.includes('--what-changed'); // show our footprint on this machine
+const FLAG_WHATS_NEW = argv.includes('--whats-new'); // show curated major-release highlights
 // ── onboarding-experience flags (all optional; every offer is safe to decline) ──
 const FLAG_YES = argv.includes('--yes') || argv.includes('-y'); // accept every optional offer non-interactively
 const FLAG_PLAN = argv.includes('--plan') || argv.includes('--dry-run'); // show the interactive checklist, then exit — install NOTHING
@@ -598,6 +599,137 @@ function installReader(cacheDir) {
   ok('reader installed');
 }
 
+// The Console must survive the temporary npm/npx extraction directory. Before 4.0.2 its skills
+// searched a developer checkout, so `/rvbc` worked for maintainers and failed for clean users even
+// though installation was green. Persist the exact runtime shipped by the installer underneath the
+// installed KB: Node then resolves optional reader dependencies from `<cacheDir>/node_modules`, and
+// both Claude Code and Codex get one stable path with no source clone or second package install.
+export function beginConsoleRuntimeTransaction(cacheDir, sourceRoot = REPO_ROOT) {
+  const runtime = path.join(cacheDir, '.console-runtime');
+  const staged = `${runtime}.tmp-${process.pid}`;
+  const prior = `${runtime}.prior-${process.pid}`;
+  fs.rmSync(staged, { recursive: true, force: true });
+  fs.rmSync(prior, { recursive: true, force: true });
+  fs.mkdirSync(staged, { recursive: true, mode: 0o700 });
+
+  const required = [
+    ['console', 'console'],
+    ['scripts', 'scripts'],
+    ['plugin/scripts', 'plugin/scripts'],
+    ['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);
+    if (!fs.existsSync(source)) {
+      fs.rmSync(staged, { recursive: true, force: true });
+      throw new Error(`console runtime is incomplete: missing ${from}`);
+    }
+    const target = path.join(staged, to);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.cpSync(source, target, { recursive: true, force: true, preserveTimestamps: true });
+  }
+
+  let packageManifest;
+  try {
+    packageManifest = JSON.parse(fs.readFileSync(path.join(staged, 'package.json'), 'utf8'));
+  } catch (error) {
+    fs.rmSync(staged, { recursive: true, force: true });
+    throw new Error(`console runtime identity is invalid: ${error.message}`);
+  }
+  if (!packageManifest.version || packageManifest.version !== PACKAGE_VERSION) {
+    fs.rmSync(staged, { recursive: true, force: true });
+    throw new Error(`console runtime version ${packageManifest.version || '(missing)'} does not match candidate ${PACKAGE_VERSION}`);
+  }
+  const stagedEntry = path.join(staged, 'scripts', 'onboarding-console.mjs');
+  for (const syntaxTarget of [stagedEntry, path.join(staged, 'bin', 'install.mjs')]) {
+    const checked = spawnSync(process.execPath, ['--check', syntaxTarget], { encoding: 'utf8' });
+    if (checked.error || checked.status !== 0) {
+      fs.rmSync(staged, { recursive: true, force: true });
+      throw new Error(`console runtime failed syntax verification: ${path.relative(staged, syntaxTarget)}`);
+    }
+  }
+  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'),
+  };
+  fs.writeFileSync(path.join(staged, 'runtime-identity.json'), `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
+
+  let state = 'staged';
+  const entry = path.join(runtime, identity.entrypoint);
+  return {
+    identity,
+    entry,
+    activate() {
+      if (state !== 'staged') throw new Error(`console runtime transaction cannot activate from ${state}`);
+      if (fs.existsSync(runtime)) fs.renameSync(runtime, prior);
+      try {
+        fs.renameSync(staged, runtime);
+        state = 'active';
+        return entry;
+      } catch (error) {
+        if (fs.existsSync(prior) && !fs.existsSync(runtime)) fs.renameSync(prior, runtime);
+        fs.rmSync(staged, { recursive: true, force: true });
+        state = 'rolled-back';
+        throw error;
+      }
+    },
+    commit() {
+      if (state !== 'active') throw new Error(`console runtime transaction cannot commit from ${state}`);
+      fs.rmSync(prior, { recursive: true, force: true });
+      state = 'committed';
+      return entry;
+    },
+    rollback() {
+      if (state === 'staged') fs.rmSync(staged, { recursive: true, force: true });
+      if (state === 'active') {
+        fs.rmSync(runtime, { recursive: true, force: true });
+        if (fs.existsSync(prior)) fs.renameSync(prior, runtime);
+      }
+      fs.rmSync(staged, { recursive: true, force: true });
+      fs.rmSync(prior, { recursive: true, force: true });
+      state = 'rolled-back';
+    },
+  };
+}
+
+export function installConsoleRuntime(cacheDir, sourceRoot = REPO_ROOT) {
+  const transaction = beginConsoleRuntimeTransaction(cacheDir, sourceRoot);
+  try {
+    transaction.activate();
+    return transaction.commit();
+  } catch (error) {
+    transaction.rollback();
+    throw error;
+  }
+}
+
+export function consoleRestartState(identity, {
+  receiptDir = path.join(process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'), 'console-instances'),
+} = {}) {
+  let receipts = [];
+  try {
+    receipts = fs.readdirSync(receiptDir)
+      .filter((name) => name.endsWith('.json'))
+      .map((name) => {
+        try { return JSON.parse(fs.readFileSync(path.join(receiptDir, name), 'utf8')); }
+        catch { return null; }
+      })
+      .filter((receipt) => receipt?.product === 'ruvnet-brain-console' && receipt.schema === 1);
+  } catch { /* no running Console receipts is the ordinary ready state */ }
+  const staleInstances = receipts.filter((receipt) => receipt.sourceSha256 !== identity.sourceSha256).length;
+  return {
+    state: staleInstances > 0 ? 'pending-console-restart' : 'ready',
+    instanceReceipts: receipts.length,
+    staleInstances,
+  };
+}
+
 // ── plugin presence: the ONLY reliable proof the slash commands will exist ───────────────────────
 // Reported by a user on 3.4.21-dev whose install was otherwise healthy: `/rvbc` returned
 // "Unknown command: /rvbc. Did you mean /rvf?". search_ruvnet worked, the KB was current — the
@@ -753,6 +885,7 @@ function codexManagedBlock(serverPath) {
     '[mcp_servers.ruvnet-brain]',
     'command = "node"',
     `args = [${JSON.stringify(serverPath)}]`,
+    'startup_timeout_sec = 30',
     CODEX_BLOCK_END,
   ].join('\n');
 }
@@ -810,7 +943,11 @@ function removeCodexWiring() {
 // What the doctor asserts from disk — never from the fact that we once ran. "Wired" means our entry
 // is in the config AND the server.mjs it points at is really there, because a registration pointing
 // at a deleted file is worse than no registration: Codex fails at spawn time with nothing to read.
-export function codexStatus({ configPath = codexConfigPath(), codexDir = codexHomeDir() } = {}) {
+export function codexStatus({
+  configPath = codexConfigPath(),
+  codexDir = codexHomeDir(),
+  brainHome = path.join(path.dirname(codexDir), '.cache', 'ruvnet-brain'),
+} = {}) {
   let host = false;
   try { host = fs.existsSync(codexDir); } catch { /* unreadable — treat as absent */ }
   if (!host) return { host: false, wired: false, serverPath: null, serverExists: false };
@@ -821,7 +958,63 @@ export function codexStatus({ configPath = codexConfigPath(), codexDir = codexHo
   try { serverPath = m ? JSON.parse(m[1]) : null; } catch { /* malformed entry — treat as absent */ }
   let serverExists = false;
   try { serverExists = serverPath ? fs.existsSync(serverPath) : false; } catch { /* unreadable */ }
-  return { host: true, wired: Boolean(serverPath) && serverExists, serverPath, serverExists };
+  const section = m ? text.slice(m.index).split(/\n[ \t]*\[/, 1)[0] : '';
+  const timeoutMatch = /(?:^|\n)[ \t]*startup_timeout_sec\s*=\s*(\d+)/.exec(section);
+  const startupTimeoutSec = timeoutMatch ? Number(timeoutMatch[1]) : null;
+  const readinessReceipt = (() => {
+    try { return JSON.parse(fs.readFileSync(path.join(brainHome, 'mcp-readiness.json'), 'utf8')); }
+    catch { return null; }
+  })();
+  let live = false;
+  if (readinessReceipt?.state === 'ready'
+      && Number.isInteger(readinessReceipt.pid)
+      && Number.isInteger(readinessReceipt.workerPid)) {
+    try {
+      process.kill(readinessReceipt.pid, 0);
+      process.kill(readinessReceipt.workerPid, 0);
+      live = true;
+    } catch { /* stale process or worker receipt */ }
+  }
+  const readiness = live ? 'ready' : readinessReceipt?.state === 'degraded' ? 'degraded' : 'registered';
+  return {
+    host: true,
+    wired: Boolean(serverPath) && serverExists,
+    serverPath,
+    serverExists,
+    startupTimeoutSec,
+    readiness,
+    live,
+    readinessReceipt,
+  };
+}
+
+export function codexMcpGuidance(status) {
+  if (!status?.wired) {
+    return { healthy: false, blocking: true, summary: 'Codex MCP is not registered to a usable server.', detail: null };
+  }
+  if (status.live && status.readiness === 'ready') {
+    return {
+      healthy: true,
+      blocking: false,
+      summary: `Codex MCP ready and live; discovery uses a ${status.startupTimeoutSec ?? 'configured'}s startup deadline.`,
+      detail: 'A running MCP shell completed worker initialize and warmup.',
+    };
+  }
+  if (status.readiness === 'degraded') {
+    const receipt = status.readinessReceipt || {};
+    return {
+      healthy: false,
+      blocking: true,
+      summary: 'Codex MCP is registered but degraded.',
+      detail: `${receipt.phase || 'startup'}: ${receipt.error || 'worker readiness failed'}`,
+    };
+  }
+  return {
+    healthy: false,
+    blocking: false,
+    summary: `Codex MCP is registered with a ${status.startupTimeoutSec ?? 'missing'}s startup deadline; live readiness is not yet proven.`,
+    detail: 'The first real search establishes worker readiness without removing search_ruvnet from discovery.',
+  };
 }
 
 // Atomic file replacement: produce the new bytes BESIDE the target, then rename() over it. Against
@@ -856,6 +1049,7 @@ export function wireCodexHost({
   serverDir = codexServerDir(),
   source = path.join(__dirname, '..', 'plugin', 'mcp', 'server.mjs'),
   hookWrapperSource = path.join(__dirname, '..', 'plugin', 'scripts', 'codex-hook-wrapper.mjs'),
+  runtimePreferencesSource = path.join(__dirname, '..', 'plugin', 'scripts', 'runtime-preferences.mjs'),
   hookWrapperPath = codexHookWrapperPath(codexDir),
   announce = true,
 } = {}) {
@@ -876,14 +1070,21 @@ export function wireCodexHost({
     if (announce) warn('MCP structured-interface module missing from this bundle — Codex left untouched (non-fatal)');
     return { host: true, action: 'no-source' };
   }
+  if (!fs.existsSync(runtimePreferencesSource)) {
+    if (announce) warn('MCP runtime-preferences module missing from this bundle — Codex left untouched (non-fatal)');
+    return { host: true, action: 'no-source' };
+  }
   const serverPath = path.join(serverDir, 'server.mjs');
   const managedCliPath = path.join(serverDir, 'managed-cli-interface.mjs');
+  const runtimePreferencesPath = path.join(path.dirname(serverDir), 'scripts', 'runtime-preferences.mjs');
   fs.mkdirSync(serverDir, { recursive: true });
   // Write-beside-then-rename, both here and for the config below (issue #43): an interrupted plain
   // copy leaves a TORN server.mjs at the exact path a prior install's config already points at, so
   // Codex spawns half a file. rename() over the target is atomic; a failure leaves the old bytes.
   // Copy the dependency first. If the later server swap fails, the previously registered server
   // remains byte-intact and continues to import a backward-compatible module at the same path.
+  fs.mkdirSync(path.dirname(runtimePreferencesPath), { recursive: true });
+  atomicReplace(runtimePreferencesPath, (tmp) => fs.copyFileSync(runtimePreferencesSource, tmp));
   atomicReplace(managedCliPath, (tmp) => fs.copyFileSync(managedCliSource, tmp));
   atomicReplace(serverPath, (tmp) => fs.copyFileSync(source, tmp));
   if (fs.existsSync(hookWrapperSource)) {
@@ -899,7 +1100,7 @@ export function wireCodexHost({
       ok('Codex already declares ruvnet-brain in your own config — left exactly as you wrote it');
       info(`  to hand it to us instead, delete that ${c.bold('[mcp_servers.ruvnet-brain]')} block and re-run this installer`);
     }
-    return { host: true, action, serverPath, managedCliPath, hookWrapperPath };
+    return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath, hookWrapperPath };
   }
   if (text !== before) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
@@ -910,7 +1111,7 @@ export function wireCodexHost({
     info(`  server: ${serverPath} ${c.dim('(persistent copy — the npx dir vanishes)')}`);
     info(`  ${c.dim('only our marked block is written; every other section is byte-preserved')}`);
   }
-  return { host: true, action, serverPath, managedCliPath, hookWrapperPath, changed: text !== before };
+  return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath, hookWrapperPath, changed: text !== before };
 }
 
 const CODEX_PLUGIN_ID = 'ruvnet-brain@ruvnet-brain';
@@ -1553,7 +1754,9 @@ async function doctor() {
   if (env.ruflo) {
     rufloOperational = probeRufloOperationalHealth();
     if (rufloOperational.healthy) {
-      ok('Ruflo operational — runtime, memory, and learning signals agree');
+      ok(rufloOperational.directMode
+        ? 'Ruflo direct mode ready — daemon/swarm is stopped by design; AgentDB remains CLI-backed'
+        : 'Ruflo operational — runtime, memory, and learning signals agree');
     } else {
       warn('Ruflo CLI is present, but operational learning is DEGRADED — availability is not enforcement.');
       if (rufloOperational.stopped) warn('  live status reports STOPPED / swarm not running');
@@ -1623,11 +1826,14 @@ async function doctor() {
   // from disk (our entry present AND the server.mjs it names really there), never asserted from the
   // fact that an install once ran.
   const cx = codexStatus();
+  let codexMcp = null;
   let codexLifecycle = null;
   if (!cx.host) {
     console.log(`  ${c.dim('Codex: no host detected (no ~/.codex) — nothing to wire.')}`);
   } else if (cx.wired) {
-    console.log(`  ${c.green('✓ Codex: wired.')} search_ruvnet is registered in ~/.codex/config.toml and its server exists.`);
+    codexMcp = codexMcpGuidance(cx);
+    console.log(`  ${codexMcp.healthy ? c.green('✓') : codexMcp.blocking ? c.yellow('!') : c.dim('○')} ${codexMcp.summary}`);
+    if (codexMcp.detail) console.log(`    ${codexMcp.detail}`);
     codexLifecycle = await codexLifecycleStatus();
     printCodexLifecycle(codexLifecycle);
   } else {
@@ -1696,10 +1902,12 @@ async function doctor() {
     && !codexLifecycleGuidance(codexLifecycle).intentional,
   );
   const codexWiringFailed = Boolean(cx.host && !cx.wired);
+  const codexReadinessFailed = Boolean(codexMcp?.blocking);
   const failed = (hookResult ? hookResult.exitCode !== 0 : !allGreen)
     || groundingUnprovenPersisted
     || codexLifecycleFailed
     || codexWiringFailed
+    || codexReadinessFailed
     || Boolean(rufloOperational && !rufloOperational.healthy);
   if (failed && !hookResult && !groundingUnprovenPersisted) {
     console.log(`  ${c.red('✗ FAILING')} — the warnings above are real. Re-run  ${c.bold('npx ruvnet-brain')}  to repair.`);
@@ -1963,32 +2171,61 @@ function missingUpdaterHelp(kbDir) {
   console.error(`  — the current bundle ships forge-update.mjs; then this command will work.`);
 }
 
-function syncHostsAfterUpdate() {
+export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
+  sourceRoot = REPO_ROOT,
+  brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'),
+  consoleReceiptDir = path.join(brainHome, 'console-instances'),
+  wireClaude = wirePlugin,
+  wireCodexHost: detectCodexHost = wireCodexHost,
+  wireCodexPlugin: installCodexPlugin = wireCodexPlugin,
+  runStableSpine = (apply) => spawnSync(
+    process.execPath,
+    [apply, '--auto', '--expected-version', PACKAGE_VERSION],
+    { stdio: 'inherit', env: process.env },
+  ),
+} = {}) {
   const results = {};
-  results.claude = wirePlugin({ expectedVersion: PACKAGE_VERSION, requireManaged: true });
-  if (results.claude.host && !results.claude.wired) return { ok: false, results };
+  let runtimeTransaction;
   try {
-    results.codexHost = wireCodexHost();
+    runtimeTransaction = beginConsoleRuntimeTransaction(cacheDir, sourceRoot);
+  } catch (error) {
+    return { ok: false, results, error: `Console runtime staging failed: ${error.message}` };
+  }
+  const fail = (detail = {}) => {
+    runtimeTransaction.rollback();
+    return { ok: false, results, ...detail };
+  };
+
+  try {
+    results.claude = wireClaude === wirePlugin
+      ? wirePlugin({ expectedVersion: PACKAGE_VERSION, requireManaged: true })
+      : wireClaude({ expectedVersion: PACKAGE_VERSION, requireManaged: true });
+    if (results.claude.host && !results.claude.wired) return fail();
+    results.codexHost = detectCodexHost();
     if (results.codexHost.host) {
-      results.codex = wireCodexPlugin({ expectedVersion: PACKAGE_VERSION });
+      results.codex = installCodexPlugin({ expectedVersion: PACKAGE_VERSION });
       if (!['unchanged', 'installed', 'updated', 'disabled'].includes(results.codex.action)) {
-        return { ok: false, results };
+        return fail();
       }
     }
   } catch (error) {
     results.codex = { action: 'failed', error: error?.message || String(error) };
-    return { ok: false, results };
+    return fail();
   }
 
-  const apply = path.join(__dirname, '..', 'plugin', 'scripts', 'update-apply.mjs');
-  if (!fs.existsSync(apply)) return { ok: false, results, error: 'Stable Spine updater missing from package' };
-  const applied = spawnSync(process.execPath, [apply, '--auto', '--expected-version', PACKAGE_VERSION], { stdio: 'inherit', env: process.env });
+  const apply = path.join(sourceRoot, 'plugin', 'scripts', 'update-apply.mjs');
+  if (!fs.existsSync(apply)) return fail({ error: 'Stable Spine updater missing from package' });
+  const applied = runStableSpine(apply);
   const okApplied = !applied.error && applied.status === 0;
   if (okApplied) {
-    const home = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
-    const receiptPath = path.join(home, 'host-convergence.json');
+    const receiptPath = path.join(brainHome, 'host-convergence.json');
     try {
-      fs.mkdirSync(home, { recursive: true });
+      runtimeTransaction.activate();
+      results.consoleRuntime = {
+        ...runtimeTransaction.identity,
+        ...consoleRestartState(runtimeTransaction.identity, { receiptDir: consoleReceiptDir }),
+      };
+      fs.mkdirSync(brainHome, { recursive: true });
       const tmp = `${receiptPath}.tmp-${process.pid}`;
       fs.writeFileSync(tmp, JSON.stringify({
         desiredVersion: PACKAGE_VERSION,
@@ -1997,13 +2234,16 @@ function syncHostsAfterUpdate() {
           claude: { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null },
           codex: { state: results.codex?.action === 'disabled' ? 'disabled' : (results.codexHost?.host ? 'ready' : 'absent'), version: results.codex?.version || null },
         },
+        consoleRuntime: results.consoleRuntime,
       }, null, 2));
       fs.renameSync(tmp, receiptPath);
+      runtimeTransaction.commit();
     } catch (error) {
-      return { ok: false, results, applyStatus: applied.status, error: `host convergence receipt failed: ${error.message}` };
+      return fail({ applyStatus: applied.status, error: `Console runtime convergence failed: ${error.message}` });
     }
   }
-  return { ok: okApplied, results, applyStatus: applied.status };
+  if (!okApplied) return fail({ applyStatus: applied.status, error: applied.error?.message || 'Stable Spine activation failed' });
+  return { ok: true, results, applyStatus: applied.status };
 }
 
 function runUpdate() {
@@ -2048,7 +2288,7 @@ function runUpdate() {
   }
   if (updateStatus === 0) {
     info(c.dim('\nsynchronizing every detected host to this exact published version…\n'));
-    const convergence = syncHostsAfterUpdate();
+    const convergence = syncHostsAfterUpdate(kbDir);
     if (!convergence.ok) {
       warn(`host synchronization is incomplete — runtime stays on the prior verified generation${convergence.error ? ` (${convergence.error})` : ''}`);
       updateStatus = 1;
@@ -2421,6 +2661,17 @@ function printFootprint({ heading = 'What this put on your machine' } = {}) {
   return items;
 }
 
+function showWhatsNew() {
+  const executable = path.join(REPO_ROOT, 'plugin', 'scripts', 'whats-new.mjs');
+  const result = spawnSync(process.execPath, [executable], { stdio: 'inherit' });
+  if (result.error) {
+    console.error(`RuvNet Brain What's New failed: ${result.error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  process.exitCode = result.status === 0 ? 0 : 1;
+}
+
 /**
  * Surgically remove ONLY our block from CLAUDE.md, leaving every other line exactly as it was.
  * Backed up and written atomically, same as when it was added — taking something away is at least
@@ -3070,8 +3321,15 @@ export function classifyRufloOperationalHealth({ status = '', memory = '', metri
     && /Total Routes\s*[|:]?\s*0\b/i.test(metrics)
     && /Total Executed\s*[|:]?\s*0\b/i.test(metrics);
   const memoryContradiction = statusSaysNoMemory && memoryEntries > 0;
+  // Brain 4 is explicitly zero-daemon: `ruflo memory store/search` open the per-project
+  // AgentDB directly. A stopped orchestration daemon therefore makes daemon-owned status
+  // and metrics non-authoritative; treating that intentional state as degraded made Doctor
+  // exit 1 immediately after proving source-grounded retrieval worked. Keep the strict
+  // contradiction/learning checks when a daemon is actually running.
+  const directMode = stopped;
   return {
-    healthy: !stopped && !memoryContradiction && !zeroLearning,
+    healthy: directMode || (!memoryContradiction && !zeroLearning),
+    directMode,
     stopped,
     zeroLearning,
     memoryContradiction,
@@ -3653,6 +3911,7 @@ Usage:
   npx ruvnet-brain --disable-nightly   Remove the nightly schedule (safe to run any time)
   npx ruvnet-brain --what-changed     Show exactly what RuvNet Brain has put on this machine,
                               with the undo command for each piece
+  npx ruvnet-brain --whats-new        Show the curated v3 → v4 capabilities and honest limits
   npx ruvnet-brain --uninstall        Remove all of it (bundle, LaunchAgents, and our CLAUDE.md
                               block only — your own CLAUDE.md content is preserved and backed up)
   npx ruvnet-brain --enable-spend-guard   Install the hourly runaway-agent spend alarm (alert-only)
@@ -3692,7 +3951,17 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
 
 // ── main ─────────────────────────────────────────────────────────────────────────────────────────
 (async () => {
-  if (IMPORT_ONLY) return; // imported for its exports (tests) — never run the installer as a side effect
+  // Importing an executable module for its exported policy helpers must never install software.
+  // The old contract required every caller to remember RUVNET_BRAIN_IMPORT_ONLY=1; one missed flag
+  // in a unit test ran a real install against the maintainer's HOME. Direct argv identity is the
+  // authority boundary. The old IMPORT_ONLY flag may still be present in a long-lived test worker;
+  // it must never suppress a genuinely direct CLI execution.
+  const canonical = (value) => {
+    try { return fs.realpathSync(value); } catch { return path.resolve(value); }
+  };
+  const invokedDirectly = Boolean(process.argv[1])
+    && canonical(process.argv[1]) === canonical(fileURLToPath(import.meta.url));
+  if (!invokedDirectly) return;
   if (FLAG_HELP) return showHelp();
   // `process.exitCode`, not `return` — doctor()'s verdict is the whole point of running it in a
   // script. A bare `return await doctor()` discarded the number, which is how "! Needs attention"
@@ -3711,6 +3980,7 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   if (FLAG_DISABLE_SPEND_GUARD) { disableSpendGuard(); return; }
   if (FLAG_UNINSTALL) { uninstallAll(); return; }
   if (FLAG_WHAT_CHANGED) { printBanner('what RuvNet Brain put on this machine'); printFootprint(); return; }
+  if (FLAG_WHATS_NEW) { showWhatsNew(); return; }
 
   printBanner('installer');
   console.log(c.dim("I'll set up the brain for Claude Code and Codex, explaining each step as I go.\n"));
@@ -3856,6 +4126,15 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   }
 
   installReader(cacheDir);
+  try {
+    const consoleEntry = installConsoleRuntime(cacheDir);
+    ok(`Brain Console installed at ${consoleEntry}`);
+  } catch (error) {
+    die(
+      `the Brain Console runtime could not be installed (${error.message})`,
+      `The knowledge base is present, but /rvbc would be broken. Re-run the installer from a complete package.`,
+    );
+  }
   const plugin = wirePlugin();
   // Codex hosts got nothing before this (issue #42): shipped, never registered. Non-fatal like every
   // other wiring step — a second host we cannot reach must never break the one we can.