ruvnet-brain 3.9.134-dev → 4.0.2

package/bin/install.mjs

@@ -84,6 +84,7 @@ const FLAG_DEMO = argv.includes('--demo'); // guided, real (non-fabricated) walk
 const FLAG_FEEDBACK = argv.includes('--feedback'); // prefill a GitHub Discussion (version + health, nothing private) and open it
 // ── freshness flags — invoke/schedule the SELF-UPDATER the bundle already ships (kb/forge-update.mjs) ──
 const FLAG_UPDATE = argv.includes('--update'); // one-shot: pull the latest Release bundle into the installed brain now
+const FLAG_HOST_SYNC_ONLY = argv.includes('--host-sync-only'); // internal: repair host shells even when KB updater is absent
 const FLAG_AUTO = argv.includes('--auto'); // with --update: also enroll in Evergreen auto-update, so it's never run by hand again
 const FLAG_ENABLE_NIGHTLY = argv.includes('--enable-nightly'); // schedule that update nightly (macOS LaunchAgent)
 const FLAG_DISABLE_NIGHTLY = argv.includes('--disable-nightly'); // remove the nightly schedule
@@ -94,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
@@ -597,6 +599,50 @@ 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 installConsoleRuntime(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 });
+  }
+
+  if (fs.existsSync(runtime)) fs.renameSync(runtime, prior);
+  try {
+    fs.renameSync(staged, runtime);
+    fs.rmSync(prior, { recursive: true, force: true });
+  } catch (error) {
+    if (fs.existsSync(prior) && !fs.existsSync(runtime)) fs.renameSync(prior, runtime);
+    fs.rmSync(staged, { recursive: true, force: true });
+    throw error;
+  }
+  return path.join(runtime, 'scripts', 'onboarding-console.mjs');
+}
+
 // ── 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
@@ -620,7 +666,40 @@ function pluginCommandsDir() {
 }
 
 // ── step: wire the Claude Code plugin ────────────────────────────────────────────────────────────
-function wirePlugin() {
+export function claudePluginStatus({ home = os.homedir() } = {}) {
+  const registry = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+  let sawUserRecord = false;
+  try {
+    const doc = JSON.parse(fs.readFileSync(registry, 'utf8'));
+    const rows = doc?.plugins?.['ruvnet-brain@ruvnet-brain'];
+    const row = Array.isArray(rows) ? rows.find((candidate) => candidate?.scope === 'user') : null;
+    if (!row?.installPath) return { managed: false, installed: false, version: null };
+    sawUserRecord = true;
+    const realHome = fs.realpathSync(home);
+    const cacheRoot = path.join(realHome, '.claude', 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain');
+    const realInstall = fs.realpathSync(row.installPath);
+    if (realInstall !== cacheRoot && !realInstall.startsWith(`${cacheRoot}${path.sep}`)) {
+      return { managed: true, installed: false, version: null, error: 'user plugin installPath escapes the managed cache' };
+    }
+    const manifestPath = path.join(realInstall, '.claude-plugin', 'plugin.json');
+    const commandPath = path.join(realInstall, 'commands', 'rvbc.md');
+    if (!fs.lstatSync(manifestPath).isFile() || fs.lstatSync(manifestPath).isSymbolicLink()
+      || !fs.lstatSync(commandPath).isFile() || fs.lstatSync(commandPath).isSymbolicLink()) {
+      return { managed: true, installed: false, version: null, error: 'managed payload files are not regular files' };
+    }
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    return {
+      managed: true,
+      installed: true,
+      version: manifest?.version || row.version || null,
+      installPath: realInstall,
+    };
+  } catch {
+    return { managed: sawUserRecord, installed: false, version: null };
+  }
+}
+
+function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false } = {}) {
   step(
     'Wiring the Claude Code plugin',
     'this registers search_ruvnet + the grounding hook so Claude uses the brain automatically',
@@ -636,37 +715,54 @@ function wirePlugin() {
     info(`  ${c.bold(manualMarketplace)}`);
     info(`  ${c.bold(manualInstall)}`);
     info(`Then reopen Claude Code once. ${c.dim('Or simply open Claude Code and ask: “finish setting up the RuvNet Brain.”')}`);
-    return { wired: false, manualMarketplace, manualInstall };
+    return { host: false, wired: false, manualMarketplace, manualInstall };
   }
 
-  const addedMarket = tryRun('claude', ['plugin', 'marketplace', 'add', 'stuinfla/ruvnet-brain']);
+  const before = claudePluginStatus();
+  if (requireManaged && !before.managed) return { host: false, wired: false, action: 'unmanaged' };
+  const addedMarket = before.managed
+    ? tryRun('claude', ['plugin', 'marketplace', 'update', 'ruvnet-brain'])
+    : tryRun('claude', ['plugin', 'marketplace', 'add', 'stuinfla/ruvnet-brain']);
   // Deliberately NOT reassuring here. This used to say "it may already be added — that's fine",
   // which is a GUESS about someone else's machine, and when it was wrong the user finished the
   // install with a working search_ruvnet, no slash commands, and a message telling them all was
   // well. The real state is checked below; nothing is declared fine until it has been looked at.
   if (!addedMarket) info(`marketplace add didn't report success — checking what actually landed…`);
 
-  tryRun('claude', ['plugin', 'install', 'ruvnet-brain@ruvnet-brain', '--scope', 'user']);
+  tryRun('claude', before.installed
+    ? ['plugin', 'update', 'ruvnet-brain@ruvnet-brain', '--scope', 'user']
+    : ['plugin', 'install', 'ruvnet-brain@ruvnet-brain', '--scope', 'user']);
 
   // NEVER take "installed" on faith — same discipline verifyInstall() applies to the KB. An exit
   // code says the command ran, not that the plugin is usable; the commands either exist on disk or
   // they do not. This is the difference between `/rvbc` working and "Unknown command: /rvbc".
-  const commandsDir = pluginCommandsDir();
-  if (commandsDir) {
-    ok('plugin installed at user scope (global, alongside Ruflo / RuVector)');
+  const installed = claudePluginStatus();
+  if (installed.installed && (!expectedVersion || installed.version === expectedVersion)) {
+    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 { wired: true, manualMarketplace, manualInstall };
+    return { host: true, wired: true, version: installed.version, manualMarketplace, manualInstall };
   }
 
   // The honest failure. The brain still WORKS — this is the difference between a broken install and
   // a partial one, and the user is told exactly which they have instead of being congratulated.
-  warn(`the plugin did NOT land — so slash commands like ${c.bold('/rvbc')} will not exist yet.`);
+  const mismatch = installed.installed && expectedVersion && installed.version !== expectedVersion;
+  warn(mismatch
+    ? `Claude installed ${installed.version || 'an unknown version'}, not required ${expectedVersion}; refusing to call this host converged.`
+    : `the plugin did NOT land — so slash commands like ${c.bold('/rvbc')} will not exist yet.`);
   info(`${c.green('Your brain still works')}: search_ruvnet is wired and Claude will ground answers with it.`);
   info(`Only the plugin extras (slash commands, the Console, the grounding hook) are missing.`);
   info(`Run these two yourself to finish:`);
   info(`  ${c.bold(manualMarketplace)}`);
   info(`  ${c.bold(manualInstall)}`);
-  return { wired: false, manualMarketplace, manualInstall };
+  return {
+    host: true,
+    wired: false,
+    action: mismatch ? 'verification-failed' : 'install-failed',
+    expectedVersion,
+    version: installed.version,
+    manualMarketplace,
+    manualInstall,
+  };
 }
 
 // ── step: wire the Codex host (issue #42, Henrik Pettersen) ──────────────────────────────────────
@@ -725,6 +821,37 @@ export function mergeCodexConfig(existing, serverPath) {
   return { text: `${text}${sep}${block}\n`, action: 'added' };
 }
 
+export function removeCodexManagedBlock(existing) {
+  const text = typeof existing === 'string' ? existing : '';
+  const start = text.indexOf(CODEX_BLOCK_START);
+  const end = text.indexOf(CODEX_BLOCK_END, start === -1 ? 0 : start);
+  if (start === -1 || end === -1 || end < start) return { text, action: 'absent' };
+  const blockEnd = end + CODEX_BLOCK_END.length;
+  let before = text.slice(0, start);
+  let after = text.slice(blockEnd);
+  // mergeCodexConfig inserts one separator newline before the block and the block carries one
+  // trailing newline. Remove exactly those two installer-owned seam bytes when present.
+  if (before.endsWith('\n\n')) before = before.slice(0, -1);
+  if (after.startsWith('\n')) after = after.slice(1);
+  return { text: `${before}${after}`, action: 'removed' };
+}
+
+function removeCodexWiring() {
+  const configPath = codexConfigPath();
+  let before = '';
+  try { before = fs.readFileSync(configPath, 'utf8'); } catch { return 'absent'; }
+  const result = removeCodexManagedBlock(before);
+  if (result.action !== 'removed') return result.action;
+  try {
+    const backup = `${configPath}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    fs.copyFileSync(configPath, backup);
+    atomicReplace(configPath, (tmp) => fs.writeFileSync(tmp, result.text));
+    return 'removed';
+  } catch {
+    return 'failed';
+  }
+}
+
 // 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.
@@ -774,6 +901,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,
 } = {}) {
@@ -794,14 +922,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)) {
@@ -817,7 +952,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 });
@@ -828,13 +963,39 @@ 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';
 const CODEX_MARKETPLACE = 'ruvnet-brain';
 const CODEX_MARKETPLACE_SOURCE = 'stuinfla/ruvnet-brain';
 
+function prepareCodexMarketplace() {
+  const target = path.join(
+    process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'),
+    'codex-marketplace',
+  );
+  const staged = `${target}.tmp-${process.pid}`;
+  fs.rmSync(staged, { recursive: true, force: true });
+  fs.mkdirSync(path.join(staged, '.claude-plugin'), { recursive: true });
+  fs.copyFileSync(
+    path.join(REPO_ROOT, '.claude-plugin', 'marketplace.json'),
+    path.join(staged, '.claude-plugin', 'marketplace.json'),
+  );
+  fs.cpSync(path.join(REPO_ROOT, 'plugin'), path.join(staged, 'plugin'), { recursive: true });
+  const prior = `${target}.prior-${process.pid}`;
+  fs.rmSync(prior, { recursive: true, force: true });
+  if (fs.existsSync(target)) fs.renameSync(target, prior);
+  try {
+    fs.renameSync(staged, target);
+    fs.rmSync(prior, { recursive: true, force: true });
+  } catch (error) {
+    if (fs.existsSync(prior) && !fs.existsSync(target)) fs.renameSync(prior, target);
+    throw error;
+  }
+  return target;
+}
+
 // Codex 0.145 returns `{ marketplaces: [...] }`; early preview builds returned the array itself.
 // Keep both shapes so an installer update never turns a harmless host-version difference into a
 // repeated "marketplace already exists" failure.
@@ -904,6 +1065,7 @@ export function wireCodexPlugin({
     return { host: true, action: 'unchanged', ...before };
   }
 
+  const localMarketplace = runJson === runCodexJson ? prepareCodexMarketplace() : null;
   const markets = runJson(['plugin', 'marketplace', 'list', '--json'], options);
   if (!markets.ok) {
     if (announce) warn(`Codex marketplace check failed — ${markets.error}`);
@@ -911,9 +1073,15 @@ export function wireCodexPlugin({
   }
   const marketRows = codexMarketplaceRows(markets.value);
   const known = marketRows.some((market) => market?.name === CODEX_MARKETPLACE);
-  const marketAction = known
-    ? runJson(['plugin', 'marketplace', 'upgrade', CODEX_MARKETPLACE, '--json'], options)
-    : runJson(['plugin', 'marketplace', 'add', marketplaceSource, '--json'], options);
+  let marketAction;
+  if (localMarketplace) {
+    if (known) runJson(['plugin', 'marketplace', 'remove', CODEX_MARKETPLACE, '--json'], options);
+    marketAction = runJson(['plugin', 'marketplace', 'add', localMarketplace, '--json'], options);
+  } else {
+    marketAction = known
+      ? runJson(['plugin', 'marketplace', 'upgrade', CODEX_MARKETPLACE, '--json'], options)
+      : runJson(['plugin', 'marketplace', 'add', marketplaceSource, '--json'], options);
+  }
   if (!marketAction.ok) {
     if (announce) warn(`Codex marketplace ${known ? 'upgrade' : 'add'} failed — ${marketAction.error}`);
     return { host: true, action: 'marketplace-failed', error: marketAction.error };
@@ -924,9 +1092,9 @@ export function wireCodexPlugin({
     return { host: true, action: 'plugin-failed', error: added.error };
   }
   const after = codexPluginStatus({ ...options, runJson });
-  if (!after.installed || !after.enabled) {
+  if (!after.installed || !after.enabled || (expectedVersion && after.version !== expectedVersion)) {
     if (announce) warn('Codex accepted the install command but the Brain plugin is not installed and enabled.');
-    return { host: true, action: 'verification-failed', ...after };
+    return { host: true, action: 'verification-failed', expectedVersion, ...after };
   }
   if (announce) {
     ok(`Codex Brain plugin installed and enabled (${after.version || 'version unknown'}).`);
@@ -1434,9 +1602,22 @@ async function doctor() {
     : info('git not found — that\'s fine, this installer never needs it');
   cleanupStrayRuvectorDb(); // issue #39: sweep a leftover empty scaffold from before this fix, if one's here
   const env = detectEnvironment();
-  env.ruflo
-    ? ok('Ruflo present — orchestration / swarms / SPARC available')
-    : warn('Ruflo not found — answers still work. To build: npm install -g claude-flow@alpha  (or /plugin add ruvnet/claude-flow)');
+  let rufloOperational = null;
+  if (env.ruflo) {
+    rufloOperational = probeRufloOperationalHealth();
+    if (rufloOperational.healthy) {
+      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');
+      if (rufloOperational.memoryContradiction) warn(`  status reports no memory while status memory reports ${rufloOperational.memoryEntries} entries`);
+      if (rufloOperational.zeroLearning) warn('  learning dashboard is all zero: patterns=0, routes=0, commands=0');
+    }
+  } else {
+    warn('Ruflo not found — answers still work. To build: npm install -g claude-flow@alpha  (or /plugin add ruvnet/claude-flow)');
+  }
   env.ruvector
     ? ok('RuVector present — vector CLI / MCP available')
     : warn(`RuVector not found — answers still work. To add: ${buildRuvectorMcpAddCommand(env).say}`);
@@ -1569,9 +1750,12 @@ async function doctor() {
     && !codexLifecycleGuidance(codexLifecycle).healthy
     && !codexLifecycleGuidance(codexLifecycle).intentional,
   );
+  const codexWiringFailed = Boolean(cx.host && !cx.wired);
   const failed = (hookResult ? hookResult.exitCode !== 0 : !allGreen)
     || groundingUnprovenPersisted
-    || codexLifecycleFailed;
+    || codexLifecycleFailed
+    || codexWiringFailed
+    || 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.`);
   }
@@ -1834,6 +2018,49 @@ function missingUpdaterHelp(kbDir) {
   console.error(`  — the current bundle ships forge-update.mjs; then this command will work.`);
 }
 
+function syncHostsAfterUpdate() {
+  const results = {};
+  results.claude = wirePlugin({ expectedVersion: PACKAGE_VERSION, requireManaged: true });
+  if (results.claude.host && !results.claude.wired) return { ok: false, results };
+  try {
+    results.codexHost = wireCodexHost();
+    if (results.codexHost.host) {
+      results.codex = wireCodexPlugin({ expectedVersion: PACKAGE_VERSION });
+      if (!['unchanged', 'installed', 'updated', 'disabled'].includes(results.codex.action)) {
+        return { ok: false, results };
+      }
+    }
+  } catch (error) {
+    results.codex = { action: 'failed', error: error?.message || String(error) };
+    return { ok: false, results };
+  }
+
+  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 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');
+    try {
+      fs.mkdirSync(home, { recursive: true });
+      const tmp = `${receiptPath}.tmp-${process.pid}`;
+      fs.writeFileSync(tmp, JSON.stringify({
+        desiredVersion: PACKAGE_VERSION,
+        verifiedAt: new Date().toISOString(),
+        hosts: {
+          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 },
+        },
+      }, null, 2));
+      fs.renameSync(tmp, receiptPath);
+    } catch (error) {
+      return { ok: false, results, applyStatus: applied.status, error: `host convergence receipt failed: ${error.message}` };
+    }
+  }
+  return { ok: okApplied, results, applyStatus: applied.status };
+}
+
 function runUpdate() {
   printBanner('update');
   const kbDir = resolvedKbDir();
@@ -1848,10 +2075,14 @@ function runUpdate() {
   // private KB stores a surprise fresh PUBLIC install is exactly the store-stripping hazard the
   // project docs warn about. The fallback's own comment scopes it to an updater that EXISTS but
   // is broken — this branch enforces that scope.)
-  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs')) && !FLAG_HOST_SYNC_ONLY) {
     missingUpdaterHelp(kbDir);
     process.exit(1);
   }
+  if (FLAG_HOST_SYNC_ONLY && !fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+    warn('KB updater is absent — continuing with host-shell repair only; the knowledge bundle remains unchanged.');
+    updateStatus = 0;
+  } else {
   info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
   // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
   // streams the updater's narration live and unedited.
@@ -1869,6 +2100,15 @@ function runUpdate() {
       env: { ...process.env, RUVNET_BRAIN_NO_UPDATE_FALLBACK: '1' } });
     updateStatus = fr.error ? 1 : (fr.status === null ? 1 : fr.status);
   }
+  }
+  if (updateStatus === 0) {
+    info(c.dim('\nsynchronizing every detected host to this exact published version…\n'));
+    const convergence = syncHostsAfterUpdate();
+    if (!convergence.ok) {
+      warn(`host synchronization is incomplete — runtime stays on the prior verified generation${convergence.error ? ` (${convergence.error})` : ''}`);
+      updateStatus = 1;
+    }
+  }
   // `--update --auto` = update now AND enroll in Evergreen, so this is the LAST time it's ever run by
   // hand. Only enroll if the update itself succeeded — never promise "you're set forever" on a failed
   // update. enableNightly() prints its own real verification (plist path + launchctl result).
@@ -2185,6 +2425,27 @@ export function machineFootprint() {
       items.push({ label: 'The search_ruvnet MCP server registration', path: claudeJson, undo: 'claude mcp remove ruvnet-brain --scope user' });
     }
   } catch { /* unreadable — do not claim it */ }
+  try {
+    const codex = codexStatus();
+    if (codex.host && codex.serverPath) {
+      items.push({
+        label: 'The Codex search_ruvnet MCP registration',
+        path: codexConfigPath(),
+        undo: 'npx ruvnet-brain --uninstall (removes only the managed block)',
+      });
+    }
+    add('Codex lifecycle hook wrapper', codexHookWrapperPath(),
+      'npx ruvnet-brain --uninstall');
+    add('Codex MCP server files', codexServerDir(), 'npx ruvnet-brain --uninstall');
+    const codexPlugin = codexPluginStatus();
+    if (codexPlugin.installed) {
+      items.push({
+        label: 'Codex plugin',
+        path: codexHomeDir(),
+        undo: 'codex plugin remove ruvnet-brain@ruvnet-brain && codex plugin marketplace remove ruvnet-brain',
+      });
+    }
+  } catch { /* Codex absent or unavailable — do not claim it */ }
   // GAP FIX: recordNotified() (scripts/upgrade-notice.mjs, invoked from main() and runDemo() below)
   // writes this file the first time a "what's new" notice is shown — a real disk artifact this
   // installer's own code path creates, that was never listed here and never removed on --uninstall.
@@ -2215,6 +2476,18 @@ function printFootprint({ heading = 'What this put on your machine' } = {}) {
   return items;
 }
 
+function showWhatsNew() {
+  const notes = path.join(REPO_ROOT, 'docs', 'RELEASE-NOTES-4.0.md');
+  if (!fs.existsSync(notes)) {
+    console.error('RuvNet Brain release notes are missing from this artifact.');
+    process.exitCode = 1;
+    return;
+  }
+  const text = fs.readFileSync(notes, 'utf8');
+  process.stdout.write(text);
+  if (!text.endsWith('\n')) process.stdout.write('\n');
+}
+
 /**
  * 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
@@ -2276,7 +2549,9 @@ function uninstallAll() {
     'Model-router files', 'Status-bar version script', 'Status-bar preference', 'Usage-counts preference',
     // Two gaps closed here: the statusLine KEY is now removable in place (we know exactly what we
     // wrote — see removeSettingsStatusLine()), and the upgrade-notice tracker is a file we fully own.
-    'The statusLine entry in settings.json', 'Upgrade-notice state (release-notice tracking)']);
+    'The statusLine entry in settings.json', 'Upgrade-notice state (release-notice tracking)',
+    'The Codex search_ruvnet MCP registration', 'Codex lifecycle hook wrapper',
+    'Codex MCP server files']);
   const willRemove = before.filter((it) => AUTO.has(it.label));
   const manual = before.filter((it) => !AUTO.has(it.label));
 
@@ -2302,6 +2577,8 @@ function uninstallAll() {
   // customized — removeSettingsStatusLine() checks the live command before touching anything).
   const statusLine = removeSettingsStatusLine();
   if (statusLine === 'removed') ok('removed the statusLine entry from ~/.claude/settings.json (your other settings untouched, backup saved)');
+  const codexWiring = removeCodexWiring();
+  if (codexWiring === 'removed') ok('removed the managed RuvNet Brain block from Codex config (your other config untouched, backup saved)');
 
   // NEVER rm -rf A PATH WE HAVE NOT PROVEN IS OURS. resolvedKbDir() honours $RUVNET_BRAIN_KB, which
   // the docs encourage for custom install locations — so `RUVNET_BRAIN_KB=$HOME npx ruvnet-brain
@@ -2340,6 +2617,8 @@ function uninstallAll() {
     ['upgrade-notice state', upgradeNoticeStatePath()],
     // ADR-054 §5: a reinstall must never inherit an invisible OFF. See brainOffSentinelPath().
     ['brain on/off switch', brainOffSentinelPath()],
+    ['Codex lifecycle hook wrapper', codexHookWrapperPath()],
+    ['Codex MCP server files', codexServerDir()],
   ]) {
     if (!fs.existsSync(target)) continue;
     try { fs.rmSync(target, { recursive: true, force: true }); ok(`removed the ${label}`); }
@@ -2714,9 +2993,9 @@ async function printPlanAndConfirm() {
     { name: 'Download the knowledge base',
       cost: short(resolveCacheDir().cacheDir),
       what: 'Real rUv source, on your disk, so answers cite files instead of guessing.' },
-    { name: 'Register the Claude Code plugin + MCP server',
-      cost: `an entry in ${short(path.join(H, '.claude'))}`,
-      what: 'Gives Claude a search_ruvnet tool. Adds no hooks you have not agreed to.' },
+    { name: 'Register host plugins + MCP server',
+      cost: `managed entries in ${short(path.join(H, '.claude'))} and, when detected, ${short(path.join(H, '.codex'))}`,
+      what: 'Gives Claude Code and Codex the same search_ruvnet tool and native Brain workflows.' },
   ];
   // The OPTIONAL steps — each asked ONCE here, stored in PLAN_CHOICES, and consumed by its offer
   // later (no second prompt). `def` is the pre-check: nightly + spend are recommended (default yes),
@@ -2850,6 +3129,42 @@ function detectEnvironment() {
   return env;
 }
 
+export function classifyRufloOperationalHealth({ status = '', memory = '', metrics = '' } = {}) {
+  const stopped = /\b(?:RuFlo V3 \[STOPPED\]|Swarm not running|MCP Server\s*\\n.*Not running)/i.test(status);
+  const statusSaysNoMemory = /Backend\s*[|:]?\s*none|Entries\s*[|:]?\s*0\b/i.test(status);
+  const memoryEntries = Number((memory.match(/Total Entries\s*[|:]?\s*([\d,]+)/i)?.[1] || '0').replace(/,/g, ''));
+  const zeroLearning = /Total Patterns\s*[|:]?\s*0\b/i.test(metrics)
+    && /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: directMode || (!memoryContradiction && !zeroLearning),
+    directMode,
+    stopped,
+    zeroLearning,
+    memoryContradiction,
+    memoryEntries,
+  };
+}
+
+function probeRufloOperationalHealth() {
+  const run = (args) => {
+    const result = spawnSync('ruflo', args, { cwd: process.cwd(), encoding: 'utf8', timeout: 10_000 });
+    return `${result.stdout || ''}\n${result.stderr || ''}`;
+  };
+  return classifyRufloOperationalHealth({
+    status: run(['status']),
+    memory: run(['status', 'memory']),
+    metrics: run(['hooks', 'metrics', '--v3-dashboard']),
+  });
+}
+
 // ── issue #39: the ruvector MCP server's own native VectorDb defaults ITS storage to
 // "./ruvector.db" relative to whatever cwd it happens to be launched in — and Claude Code
 // always launches an MCP server with cwd = the current project, so every consumer project got
@@ -3295,7 +3610,7 @@ function installedRepoCount(cacheDir) {
   }
 }
 
-function success({ cacheDir, isCustom, plugin, env, nightly }) {
+function success({ cacheDir, isCustom, plugin, codexHost, codexPlugin, env, nightly }) {
   const line = '─'.repeat(64);
   console.log(`\n${c.green(line)}`);
   console.log(`${c.green(c.bold('  RuvNet Brain is installed.'))}`);
@@ -3306,6 +3621,13 @@ function success({ cacheDir, isCustom, plugin, env, nightly }) {
   console.log(
     `    • the Claude Code plugin ${plugin.wired ? c.green('wired at user scope') : c.yellow('(finish the 2 commands above)')} — search_ruvnet + grounding hook`,
   );
+  if (codexHost?.host) {
+    const hostReady = ['added', 'rewritten', 'user-owned'].includes(codexHost.action);
+    const pluginReady = Boolean(codexPlugin?.installed && codexPlugin?.enabled);
+    console.log(
+      `    • the Codex host ${hostReady && pluginReady ? c.green('wired at user scope') : c.yellow('needs attention')} — search_ruvnet + native Brain skills`,
+    );
+  }
   if (env) {
     const t = (okv) => (okv ? c.green('✓ present') : c.yellow('not added (optional)'));
     console.log(`    • rUv build toolkit — Ruflo: ${t(env.ruflo)} · RuVector: ${t(env.ruvector)}  ${c.dim('answers work without them')}`);
@@ -3316,7 +3638,8 @@ function success({ cacheDir, isCustom, plugin, env, nightly }) {
     console.log(`    ${c.bold(`export RUVNET_BRAIN_KB="${cacheDir}"`)}`);
   }
   // ── where + how it runs — the confidence answers, stated up front ──
-  console.log(`\n  ${c.bold('Where it runs:')} ${c.bold('everywhere you use Claude Code')} — CLI, VS Code, JetBrains, the desktop app.`);
+  const hostLabel = codexHost?.host ? 'Claude Code and Codex' : 'Claude Code';
+  console.log(`\n  ${c.bold('Where it runs:')} ${c.bold(`everywhere you use ${hostLabel}`)} — CLI and supported editor/desktop surfaces.`);
   console.log(`    It's ${c.bold('user-level (global)')}: open ANY repo or folder and it's already there. Nothing per project,`);
   console.log(`    nothing to copy in, nothing to git-ignore. ${c.dim('(Runs locally — it is not active in the claude.ai web app.)')}`);
   console.log(`\n  ${c.bold('How it runs:')} ${c.bold('automatically')} — you never call or configure anything. Ask normally; on rUv-stack work it`);
@@ -3325,12 +3648,12 @@ function success({ cacheDir, isCustom, plugin, env, nightly }) {
   console.log(`  Release regardless (that part isn't cached). For the bleeding-edge installer too, use ${c.bold('npx github:stuinfla/ruvnet-brain')}.`);
 
   // ── one important expectation: the hook activates on the NEXT session ──
-  console.log(`\n  ${c.yellow(c.bold('One thing to know:'))} the grounding hook turns on at your ${c.bold('next')} Claude Code session.`);
-  console.log(`  ${c.dim('If Claude Code is open right now, quit and reopen it — then the brain is live on every prompt.')}`);
+  console.log(`\n  ${c.yellow(c.bold('One thing to know:'))} lifecycle hooks turn on in your ${c.bold('next')} host session.`);
+  console.log(`  ${c.dim(`If ${hostLabel} is open right now, quit and reopen it so the new plugin snapshot loads.`)}`);
 
   // ── what to do now ──
   console.log(`\n  ${c.bold('What to do now:')}`);
-  console.log(`    ${c.cyan('1.')} Open Claude Code in ${c.bold('any')} project (your own, or a fresh repo — nothing to copy in).`);
+  console.log(`    ${c.cyan('1.')} Open ${hostLabel} in ${c.bold('any')} project (your own, or a fresh repo — nothing to copy in).`);
   console.log(`    ${c.cyan('2.')} Just ask, normally. Try:  ${c.bold('"Set up vector search here the way rUv would."')}`);
   console.log(`    ${c.cyan('3.')} Watch what changes (below).`);
 
@@ -3404,6 +3727,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)
@@ -3443,7 +3767,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"
@@ -3462,9 +3796,10 @@ 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 and the Claude Code plugin, explaining each step as I go.\n"));
+  console.log(c.dim("I'll set up the brain for Claude Code and Codex, explaining each step as I go.\n"));
 
   // ── environment guard: fail early and CLEARLY on unsupported Node, not cryptically mid-install ──
   // Node itself can't be silently auto-upgraded from inside a script it's currently running as —
@@ -3607,13 +3942,24 @@ 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.
+  let codexHost = { host: false, action: 'no-host' };
+  let codexPlugin = null;
   try {
-    const codexHost = wireCodexHost();
+    codexHost = wireCodexHost();
     if (codexHost.host) {
-      const codexPlugin = wireCodexPlugin();
+      codexPlugin = wireCodexPlugin();
       if (codexPlugin.available) printCodexLifecycle(await codexLifecycleStatus());
     }
   } catch (e) {
@@ -3657,7 +4003,7 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   // Same rule: an optional offer can never break a finished install.
   try { await offerStatusline(); } catch { /* non-fatal — a status-bar nicety must never break the install */ }
 
-  success({ cacheDir, isCustom, plugin, env, nightly });
+  success({ cacheDir, isCustom, plugin, codexHost, codexPlugin, env, nightly });
 
   // Close every install by stating, in one place, exactly what is now on their machine and how to
   // take each piece back off. Someone reading this should never have to file a bug report to find