ruvnet-brain 4.3.20 → 4.3.21

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.20 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.20-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.3.21 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.21-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.**
 

package/bin/install.mjs

@@ -67,6 +67,7 @@ const versionSatisfies = (installed, expected) => {
 import {
   CONSOLE_RUNTIME_SURFACE, CONSOLE_RUNTIME_IDENTITY_FILE, consoleRuntimeDigest,
 } from '../scripts/console-runtime-identity.mjs';
+import { shellDiff as pluginShellDiff } from '../plugin/scripts/host-shell-boundary.mjs';
 
 // SEC-0010 #6 — the Ed25519 PUBLIC key is EMBEDDED here (not a separate file) so the installer's
 // trust root travels with the installer code itself: an attacker who swaps the downloaded bundle
@@ -1182,6 +1183,55 @@ export function claudePluginStatus({ home = os.homedir() } = {}) {
   }
 }
 
+// A plugin version can change without changing anything a running host freezes at boot. Compare
+// the actual installed payload with this candidate before updating it so body-only releases do not
+// manufacture a restart requirement. Unknown paths fail closed: if we cannot prove the boundary,
+// the caller must retain the restart notice rather than silently promise hot loading.
+function inspectPluginShellBoundary(installedRoot, candidateRoot = path.join(REPO_ROOT, 'plugin')) {
+  if (!installedRoot || !candidateRoot) {
+    return { known: false, changed: true, paths: [], restartRequired: true, reason: 'plugin boot surface could not be located' };
+  }
+  try {
+    const paths = pluginShellDiff(installedRoot, candidateRoot);
+    return {
+      known: true,
+      changed: paths.length > 0,
+      paths,
+      restartRequired: paths.length > 0,
+      reason: paths.length ? `boot-level declarations changed: ${paths.join(', ')}` : 'body-only plugin update',
+    };
+  } catch (error) {
+    return { known: false, changed: true, paths: [], restartRequired: true,
+      reason: `plugin boot surface comparison failed: ${error.message}` };
+  }
+}
+
+function codexInstalledPluginRoot({ codexHome = codexHomeDir(), status } = {}) {
+  const row = status?.row || {};
+  for (const value of [status?.installPath, status?.path, row.installPath, row.path]) {
+    if (typeof value === 'string' && value) {
+      try {
+        const real = fs.realpathSync(value);
+        if (fs.statSync(real).isDirectory()) return real;
+      } catch { /* try the cache scan below */ }
+    }
+  }
+  const cacheRoot = path.join(codexHome, 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain');
+  let candidates = [];
+  try {
+    candidates = fs.readdirSync(cacheRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(cacheRoot, entry.name))
+      .filter((dir) => {
+        try {
+          const manifest = JSON.parse(fs.readFileSync(path.join(dir, '.codex-plugin', 'plugin.json'), 'utf8'));
+          return manifest?.name === 'ruvnet-brain' && (!status?.version || manifest.version === status.version);
+        } catch { return false; }
+      });
+  } catch { /* absent cache is handled as unknown below */ }
+  return candidates.sort().at(-1) || null;
+}
+
 function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false } = {}) {
   step(
     'Wiring the Claude Code plugin',
@@ -1204,6 +1254,9 @@ function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false
 
   const before = claudePluginStatus();
   if (requireManaged && !before.managed) return { host: false, wired: false, action: 'unmanaged' };
+  const shellBoundary = before.installed
+    ? inspectPluginShellBoundary(before.installPath)
+    : { known: true, changed: false, paths: [], restartRequired: false, reason: 'new host installation' };
   const addedMarket = before.managed
     ? tryRun('claude', ['plugin', 'marketplace', 'update', 'ruvnet-brain'])
     : tryRun('claude', ['plugin', 'marketplace', 'add', marketplaceSource]);
@@ -1224,8 +1277,18 @@ function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false
   const installedHookRetirement = claudeInstalledHookRetirementStatus({ plugin: installed });
   if (installed.installed && versionSatisfies(installed.version, expectedVersion) && installedHookRetirement.ok) {
     ok(`plugin installed at user scope (global, alongside Ruflo / RuVector) — exact version ${installed.version}`);
-    info(`  commands available after a restart: ${c.bold('/rvbc')}, ${c.bold('/ruvnet-brain:configure')}`);
-    return { host: true, wired: true, version: installed.version, manualMarketplace, manualInstall };
+    if (shellBoundary.restartRequired) {
+      warn(`boot-level plugin declarations changed; restart Claude Code once to load them (${shellBoundary.paths.join(', ') || shellBoundary.reason}).`);
+    } else if (before.installed && before.version !== installed.version) {
+      info('  body-only update: the Stable Spine is live on the next hook/MCP call; no restart is required.');
+    }
+    info(`  commands available${shellBoundary.restartRequired ? ' after a restart' : ' immediately'}: ${c.bold('/rvbc')}, ${c.bold('/ruvnet-brain:configure')}`);
+    return {
+      host: true, wired: true, version: installed.version, manualMarketplace, manualInstall,
+      shellChanged: shellBoundary.changed, shellChangedPaths: shellBoundary.paths,
+      restartRequired: shellBoundary.restartRequired,
+      ...(shellBoundary.restartRequired ? { sessionSafety: 'restart-required', sessionSafetyReason: shellBoundary.reason } : {}),
+    };
   }
 
   // The honest failure. The brain still WORKS — this is the difference between a broken install and
@@ -1654,6 +1717,7 @@ export function codexPluginStatus(options = {}) {
     installed: Boolean(row?.installed),
     enabled: Boolean(row?.enabled),
     version: row?.version || null,
+    installPath: row?.installPath || row?.path || null,
     row: row || null,
   };
 }
@@ -1691,9 +1755,22 @@ export function wireCodexPlugin({
     if (announce) warn(`Codex Brain plugin is installed but disabled by user or policy — left disabled (${CODEX_PLUGIN_ID}).`);
     return { host: true, action: 'disabled', ...before };
   }
+  // An existing Codex session can keep the plugin generation it loaded at boot. Compare the
+  // installed bytes with the source candidate before mutating the marketplace so body-only updates
+  // remain live while a changed/unknown boot surface gets one explicit restart request.
+  const shellBoundary = before.installed
+    ? inspectPluginShellBoundary(
+      codexInstalledPluginRoot({ codexHome, status: before }),
+      path.join(REPO_ROOT, 'plugin'),
+    )
+    : { known: true, changed: false, paths: [], restartRequired: false, reason: 'new host installation' };
   if (before.installed && before.enabled && versionSatisfies(before.version, expectedVersion)) {
     if (announce) ok(`Codex Brain plugin already installed and enabled (${before.version || 'version unknown'}) — no changes.`);
-    return { host: true, action: 'unchanged', ...before };
+    return {
+      host: true, action: 'unchanged', ...before,
+      shellChanged: shellBoundary.changed, shellChangedPaths: shellBoundary.paths,
+      restartRequired: false,
+    };
   }
 
   if (runJson === runCodexJson && !localMarketplace) {
@@ -1735,17 +1812,23 @@ export function wireCodexPlugin({
   }
   if (announce) {
     ok(`Codex Brain plugin installed and enabled (${after.version || 'version unknown'}).`);
-    warn('Existing Codex app-server sessions may retain the previous plugin path; restart Codex before using the updated plugin.');
+    if (shellBoundary.restartRequired) {
+      warn(`boot-level plugin declarations changed; restart Codex once to load them (${shellBoundary.paths.join(', ') || shellBoundary.reason}).`);
+    } else if (before.installed && before.version !== after.version) {
+      info('  body-only update: the Stable Spine is live on the next hook/MCP call; no restart is required.');
+    }
   }
   return {
     host: true,
     action: before.installed ? 'updated' : 'installed',
     ...after,
-    // Codex currently exposes no generation/session lease API. This explicit guard prevents the
-    // installer from implying that a native cache update is safe for an already-running session.
-    sessionSafety: 'restart-required',
-    restartRequired: true,
-    sessionSafetyReason: 'Codex host cache generations are owned by Codex and have no lease API',
+    shellChanged: shellBoundary.changed,
+    shellChangedPaths: shellBoundary.paths,
+    restartRequired: shellBoundary.restartRequired,
+    ...(shellBoundary.restartRequired ? {
+      sessionSafety: 'restart-required',
+      sessionSafetyReason: shellBoundary.reason,
+    } : {}),
   };
 }
 
@@ -2802,7 +2885,7 @@ function reportVersionDrift(cacheDir) {
   if (!state.drift) return state;
   warn(`the brain (${c.bold(state.kb)}) and the Claude Code plugin (${c.bold(state.wrapper)}) have drifted apart —`);
   info(`that's normal (they update on separate schedules) and neither one is broken. To bring the`);
-  info(`plugin up to date:  ${c.bold('claude plugin marketplace update ruvnet-brain')}  ${c.dim('(then restart Claude Code)')}`);
+  info(`plugin up to date:  ${c.bold('claude plugin marketplace update ruvnet-brain')}  ${c.dim('(body updates go live without a restart; boot-surface changes are called out)')}`);
   return state;
 }
 
@@ -3061,6 +3144,15 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
     codexReceipt.sessionSafety = results.codex.sessionSafety || null;
     codexReceipt.sessionSafetyReason = results.codex.sessionSafetyReason || null;
   }
+  const claudeReceipt = {
+    state: results.claude.host ? 'ready' : 'absent',
+    version: results.claude.version || null,
+  };
+  if (results.claude?.restartRequired === true) {
+    claudeReceipt.restartRequired = true;
+    claudeReceipt.sessionSafety = results.claude.sessionSafety || null;
+    claudeReceipt.sessionSafetyReason = results.claude.sessionSafetyReason || null;
+  }
   if (okApplied) {
     // ISSUE #153 — a running host may freeze an old plugin root. Reclaim only generations whose
     // modern leases prove no live consumer; legacy roots without that proof stay on disk.
@@ -3093,7 +3185,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
         desiredVersion: PACKAGE_VERSION,
         verifiedAt: new Date().toISOString(),
         hosts: {
-          claude: { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null },
+          claude: claudeReceipt,
           codex: codexReceipt,
         },
         consoleRuntime: results.consoleRuntime,
@@ -3108,7 +3200,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   const convergence = classifyHostConvergence({
     desiredVersion: PACKAGE_VERSION,
     hosts: {
-      claude: { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null },
+      claude: claudeReceipt,
       codex: codexReceipt,
     },
     consoleRuntime: results.consoleRuntime,
@@ -4871,10 +4963,8 @@ function success({ cacheDir, isCustom, plugin, codexHost, codexPlugin, env, nigh
   console.log(`\n  ${c.bold('Keep it fresh:')} re-run ${c.bold('npx ruvnet-brain')} any time — the brain itself always pulls the latest`);
   console.log(`  Release regardless (that part isn't cached). For the bleeding-edge installer too, use ${c.bold('npx github:stuinfla/ruvnet-brain')}.`);
 
-  // Hosts cache plugin registries for the lifetime of a session. A restart is therefore required to
-  // unload callbacks from an older hook-bearing generation even though this version registers none.
-  console.log(`\n  ${c.yellow(c.bold('One required cleanup step:'))} restart any ${hostLabel} window that was open before this update.`);
-  console.log(`  ${c.dim('That unloads the old in-memory hook registry; new sessions load the intentional empty registry.')}`);
+  console.log(`\n  ${c.bold('Updates take effect:')} body-only releases go live on the next hook/MCP call without a restart.`);
+  console.log(`  ${c.dim('If boot-level declarations change, the installer names the affected host and requests one restart.')}`);
 
   // ── what to do now ──
   console.log(`\n  ${c.bold('What to do now:')}`);
@@ -4982,8 +5072,8 @@ Env:
                         download or an air-gapped machine is not a broken install). Only ever set
                         this for a locked-down environment where you want to know immediately.
 
-It is safe to re-run at any time. After updating from a hook-bearing version, restart open hosts so
-their old in-memory hook registries unload.
+It is safe to re-run at any time. Body updates go live on the next hook/MCP call. Restart only when
+the installer reports that boot-level declarations changed.
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.20",
+  "version": "4.3.21",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {

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

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 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 an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.3.20",
+  "version": "4.3.21",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/scripts/host-shell-boundary.mjs

@@ -0,0 +1,43 @@
+// host-shell-boundary.mjs — one definition of the files a running host freezes at boot.
+//
+// Body files are reached through the Stable Spine and can change in place. These paths are the
+// host declarations or boot-loaded surfaces whose change must be reported honestly to a running
+// Claude/Codex session. Both the updater and the installer consume this one list so they cannot
+// disagree about whether a release needs a restart.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SHELL_PATHS = Object.freeze([
+  'hooks/hooks.json',
+  'scripts/hook-shim.mjs',
+  'scripts/hook-shim-bash.mjs',
+  'scripts/development-maintenance.mjs',
+  'mcp/server.mjs',
+  '.mcp.json',
+]);
+
+function treeDigest(root, relative) {
+  const target = path.join(root, relative);
+  let stat;
+  try { stat = fs.lstatSync(target); } catch { return '<missing>'; }
+  if (stat.isSymbolicLink()) return '<symlink>';
+  if (stat.isFile()) return `file:${crypto.createHash('sha256').update(fs.readFileSync(target)).digest('hex')}`;
+  if (!stat.isDirectory()) return `<special:${stat.mode}>`;
+  const entries = fs.readdirSync(target, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  return `dir:${entries.map((entry) => `${entry.name}:${treeDigest(target, entry.name)}`).join('|')}`;
+}
+/** Return the boot-loaded paths that differ between two plugin payload roots. */
+export function shellDiff(prevRootAbs, nextRootAbs) {
+  if (!prevRootAbs || !nextRootAbs) throw new Error('both plugin roots are required for shell comparison');
+  const changed = [];
+  for (const rel of SHELL_PATHS) {
+    if (treeDigest(prevRootAbs, rel) !== treeDigest(nextRootAbs, rel)) changed.push(rel);
+  }
+  // skills/ and commands/ are markdown surfaces loaded at host boot. Any file-set or content
+  // difference is a boot-surface change, even though they are not executable hook declarations.
+  for (const dir of ['skills', 'commands']) {
+    if (treeDigest(prevRootAbs, dir) !== treeDigest(nextRootAbs, dir)) changed.push(`${dir}/`);
+  }
+  return changed;
+}

package/plugin/scripts/update-apply.mjs

@@ -41,6 +41,8 @@ import { fileURLToPath } from 'node:url';
 // check on every .sh it was about to install — the platform most likely to receive a broken hook
 // was the one platform that never checked. Git-for-Windows bash can run `bash -n` perfectly well.
 import { resolveBash } from './hook-shim-bash.mjs';
+import { SHELL_PATHS, shellDiff } from './host-shell-boundary.mjs';
+export { SHELL_PATHS, shellDiff } from './host-shell-boundary.mjs';
 
 const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
 const ACTIVE = path.join(BRAIN_HOME, 'active.json');
@@ -212,38 +214,6 @@ function promote(staging, version) {
 // the update is fully live with no restart and session-start stays silent; if any did, the ONE
 // honest nag fires (the release classifier computes the same thing publish-side; this is the
 // client-side truth for locally-applied generations). Red-team finding 18's client half.
-export const SHELL_PATHS = [
-  'hooks/hooks.json',
-  'scripts/hook-shim.mjs',
-  'scripts/hook-shim-bash.mjs',
-  'scripts/development-maintenance.mjs',
-  'mcp/server.mjs',
-  '.mcp.json',
-];
-
-function treeDigest(root, relative) {
-  const target = path.join(root, relative);
-  let stat;
-  try { stat = fs.lstatSync(target); } catch { return '<missing>'; }
-  if (stat.isSymbolicLink()) return '<symlink>';
-  if (stat.isFile()) return `file:${crypto.createHash('sha256').update(fs.readFileSync(target)).digest('hex')}`;
-  if (!stat.isDirectory()) return `<special:${stat.mode}>`;
-  const entries = fs.readdirSync(target, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
-  return `dir:${entries.map((entry) => `${entry.name}:${treeDigest(target, entry.name)}`).join('|')}`;
-}
-
-export function shellDiff(prevRootAbs, nextRootAbs) {
-  const changed = [];
-  for (const rel of SHELL_PATHS) {
-    if (treeDigest(prevRootAbs, rel) !== treeDigest(nextRootAbs, rel)) changed.push(rel);
-  }
-  // skills/ and commands/ are boot-loaded markdown: any file-set or content difference counts.
-  for (const dir of ['skills', 'commands']) {
-    if (treeDigest(prevRootAbs, dir) !== treeDigest(nextRootAbs, dir)) changed.push(`${dir}/`);
-  }
-  return changed;
-}
-
 function flip(version, codeRootAbs, why) {
   const prev = readJSON(ACTIVE);
   const prevRootAbs = prev?.codeRoot ? (path.isAbsolute(prev.codeRoot) ? prev.codeRoot : path.join(BRAIN_HOME, prev.codeRoot)) : null;