ruvnet-brain 4.3.40 → 4.4.1

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.40 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.40-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.4.1 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.4.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)
 
 **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.**
 
@@ -562,7 +562,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** — 199 public stores · 161,365 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 199 public stores · 161,371 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), 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

@@ -21,9 +21,10 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import readline from 'node:readline';
 import crypto from 'node:crypto';
 import { applyBrainProfile, readBrainProfile } from '../kb/brain-profile.mjs';
-import { acquireRefreshLock, finishRefreshReceipt, openRefreshReceipt, recordRefreshAdvisory,
+import { acquireRefreshLock, finishRefreshReceipt, openRefreshReceipt, physicalPath, recordRefreshAdvisory,
   recordRefreshPhase, settleRefreshRun, UPDATE_REFRESH_PHASES } from '../kb/refresh-run.mjs';
 import { pruneLifecycleEvidence } from '../kb/lifecycle-evidence-retention.mjs';
+import { recoverIncompleteStorageTransactions } from '../kb/update-storage-transaction.mjs';
 import {
   requiredEmbedderModels,
   missingEmbedderModels,
@@ -70,6 +71,10 @@ 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';
+import { readConsoleReceipts, replaceStaleConsoles } from '../scripts/console-instances.mjs';
+import { cleanLegacyRufloDebris } from '../plugin/scripts/project-progression-store.mjs';
+import { resolveProjectStore } from '../plugin/scripts/project-store-resolver.mjs';
+import { runHostCli, waitForHostCli } from '../scripts/host-cli.mjs';
 import {
   writeInstalledRuntimeIdentity, recordCorpusTransportIdentity, isCorpusReleaseTag, rejectedReleasePath,
 } from '../kb/corpus-release-identity.mjs';
@@ -228,6 +233,13 @@ function tryRun(cmd, args, opts = {}) {
   const r = spawnSync(cmd, args, { stdio: 'inherit', shell: IS_WIN, ...opts });
   return !r.error && r.status === 0;
 }
+// The claude/codex CLIs update themselves and can be absent for seconds (scripts/host-cli.mjs):
+// retried with a bounded backoff, then ONE clear line instead of raw shell errors.
+function tryHostCli(cmd, args, opts = {}) {
+  const r = runHostCli(cmd, args, opts);
+  if (r.missingBinary) warn(r.message);
+  return !r.missingBinary && !r.error && r.status === 0;
+}
 
 // ── download with redirect-following + progress ──────────────────────────────────────────────────
 function download(url, dest, redirects = 0) {
@@ -1271,24 +1283,57 @@ export function installConsoleRuntime(cacheDir, sourceRoot = REPO_ROOT) {
   }
 }
 
+// Receipts of Consoles that died (pid gone, port silent) are pruned, not counted: the owner's Mac
+// reported pending-console-restart forever from two receipts left on 2026-09-16/17
+// (scripts/console-instances.mjs).
+/**
+ * --doctor's view of a recorded convergence receipt. Its Console state is a snapshot from the last sync;
+ * a recorded pending-console-restart is re-read against the LIVE receipts, so a Console that has since
+ * exited (or a receipt it left when it died) stops failing --doctor. Returns a new object.
+ */
+export function withLiveConsoleState(recorded, { receiptDir, alive, probe } = {}) {
+  if (recorded?.consoleRuntime?.state !== 'pending-console-restart' || !recorded.consoleRuntime.sourceSha256) return recorded;
+  const { replacementFailures, ...kept } = recorded.consoleRuntime;
+  const live = { ...kept, ...consoleRestartState(recorded.consoleRuntime, { receiptDir, alive, probe }) };
+  if (live.state !== 'ready' && replacementFailures) live.replacementFailures = replacementFailures;
+  return { ...recorded, consoleRuntime: live };
+}
+
+/**
+ * 4.3.40's ruflo leftovers inside this project's `.swarm` (cleanLegacyRufloDebris). --update removes
+ * them; --doctor only reports (dryRun). Either way a REFUSED artifact (unexpected contents, a symlink) is
+ * printed, never dropped silently. Not a project (or no .swarm): nothing to say.
+ */
+export function reportLegacyRufloDebris({ projectDir = process.cwd(), dryRun = false } = {}) {
+  let storeDir;
+  try { storeDir = path.dirname(resolveProjectStore({ projectDir }).canonicalAgentDbPath); } catch { return null; }
+  if (!fs.existsSync(storeDir)) return null;
+  const result = cleanLegacyRufloDebris(storeDir, { dryRun });
+  for (const entry of result.removed) {
+    // Dry run applies the same checks (allowlist, mirror proof, in-use window); only the final
+    // unchanged-since-proof comparison can still keep it at --update time.
+    if (dryRun) info(`legacy ruflo debris from 4.3.40 in ${entry}: passes every check; --update removes it unless it is written to before then`);
+    else ok(`removed legacy ruflo debris from 4.3.40: ${entry}`);
+  }
+  for (const { path: entry, reason, kept } of result.refused) {
+    // A KEPT nested AgentDB holds rows (or may still be written): never suggest deleting it by hand.
+    if (kept) warn(`left 4.3.40's nested ruflo store in place — ${entry}: ${reason}. It is checked again on every update.`);
+    else warn(`left legacy ruflo debris in place — ${entry}: ${reason}. Inspect it; remove it yourself if it is ruflo's.`);
+  }
+  return result;
+}
+
 export function consoleRestartState(identity, {
   receiptDir = path.join(process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'), 'console-instances'),
+  alive, probe,
 } = {}) {
-  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;
+  const { live, pruned } = readConsoleReceipts(receiptDir, { ...(alive ? { alive } : {}), ...(probe ? { probe } : {}) });
+  const staleInstances = live.filter(({ receipt }) => receipt.sourceSha256 !== identity.sourceSha256).length;
   return {
     state: staleInstances > 0 ? 'pending-console-restart' : 'ready',
-    instanceReceipts: receipts.length,
+    instanceReceipts: live.length,
     staleInstances,
+    ...(pruned.length ? { prunedDeadReceipts: pruned.length } : {}),
   };
 }
 
@@ -1406,7 +1451,9 @@ function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false
   const manualMarketplace = `claude plugin marketplace add ${marketplaceSource}`;
   const manualInstall = 'claude plugin install ruvnet-brain@ruvnet-brain --scope user';
 
-  if (!have('claude')) {
+  const claudeCli = waitForHostCli('claude');
+  if (!claudeCli.present) {
+    if (claudeCli.message) warn(claudeCli.message);
     warn(`I couldn't run the \`claude\` command from this shell.`);
     info(`That's normal if you use Claude Code as the ${c.bold('VS Code extension')} or ${c.bold('desktop app')} — the`);
     info(`command just isn't on your terminal's PATH. ${c.green('The brain itself is fully downloaded.')}`);
@@ -1423,15 +1470,15 @@ function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false
     ? 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]);
+    ? tryHostCli('claude', ['plugin', 'marketplace', 'update', 'ruvnet-brain'])
+    : tryHostCli('claude', ['plugin', 'marketplace', 'add', marketplaceSource]);
   // 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', before.installed
+  tryHostCli('claude', before.installed
     ? ['plugin', 'update', 'ruvnet-brain@ruvnet-brain', '--scope', 'user']
     : ['plugin', 'install', 'ruvnet-brain@ruvnet-brain', '--scope', 'user']);
 
@@ -1442,17 +1489,22 @@ 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}`);
-    if (shellBoundary.restartRequired) {
-      warn(`boot-level plugin declarations changed; restart Claude Code once to load them (${shellBoundary.paths.join(', ') || shellBoundary.reason}).`);
+    if (shellBoundary.restartRequired && shellBoundary.known) {
+      info(`  boot-level plugin declarations changed (${shellBoundary.paths.join(', ')}): new Claude Code sessions load them; already-open windows keep the old hook definitions until they are reopened.`);
+    } else if (shellBoundary.restartRequired) {
+      warn(`could not verify the plugin's boot-level declarations (${shellBoundary.reason}); restart Claude Code once to be sure they are loaded.`);
     } 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')}`);
+    info(`  commands available${shellBoundary.restartRequired ? ' in new sessions' : ' 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 } : {}),
+      // 'open-sessions': the new declarations are installed and PROVEN changed — only sessions already
+      // open booted the old ones. 'unproven': the boot surface could not be compared at all.
+      ...(shellBoundary.restartRequired ? { sessionSafety: 'restart-required', sessionSafetyReason: shellBoundary.reason,
+        restartScope: shellBoundary.known ? 'open-sessions' : 'unproven' } : {}),
     };
   }
 
@@ -1856,13 +1908,16 @@ function runCodexJson(args, {
   codexHome = codexHomeDir(),
   cwd = process.cwd(),
 } = {}) {
-  const r = spawnSync(codexBin, args, {
+  const r = runHostCli(codexBin, args, {
+    stdio: 'pipe',
+    shell: false,
     cwd,
     env: { ...process.env, CODEX_HOME: codexHome },
     encoding: 'utf8',
     timeout: 30_000,
     maxBuffer: 20 * 1024 * 1024,
   });
+  if (r.missingBinary) return { ok: false, error: r.message };
   if (r.error || r.status !== 0) {
     const detail = String(r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim();
     return { ok: false, error: detail };
@@ -1978,7 +2033,7 @@ export function wireCodexPlugin({
   if (announce) {
     ok(`Codex Brain plugin installed and enabled (${after.version || 'version unknown'}).`);
     if (shellBoundary.restartRequired) {
-      warn(`boot-level plugin declarations changed; restart Codex once to load them (${shellBoundary.paths.join(', ') || shellBoundary.reason}).`);
+      warn(`boot-level plugin declarations changed; restart Codex, then review them in /hooks (${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.');
     }
@@ -1993,6 +2048,10 @@ export function wireCodexPlugin({
     ...(shellBoundary.restartRequired ? {
       sessionSafety: 'restart-required',
       sessionSafetyReason: shellBoundary.reason,
+      // Never 'open-sessions' for Codex: changed hook definitions show as PENDING until reviewed in
+      // /hooks (doctor fails closed on pending trust; the SessionStart notice says to trust them), and no
+      // measurement shows a fresh Codex session running them without that step. Unproven = restart.
+      restartScope: 'unproven',
     } : {}),
   };
 }
@@ -2754,8 +2813,13 @@ async function doctor() {
   let hostConvergence = { healthy: true, state: 'not-recorded' };
   if (fs.existsSync(convergencePath)) {
     try {
-      hostConvergence = classifyHostConvergence(JSON.parse(fs.readFileSync(convergencePath, 'utf8')));
-      if (hostConvergence.healthy) ok(`host convergence receipt: ${hostConvergence.state}`);
+      const recorded = withLiveConsoleState(JSON.parse(fs.readFileSync(convergencePath, 'utf8')),
+        { receiptDir: path.join(path.dirname(convergencePath), 'console-instances') });
+      hostConvergence = classifyHostConvergence(recorded);
+      if (hostConvergence.healthy) {
+        ok(`host convergence receipt: ${hostConvergence.state}`);
+        if (hostConvergence.notice) info(hostConvergence.notice);
+      }
       else {
         warn(`host convergence incomplete: ${hostConvergence.state}`);
         info(`Retry the same generation: ${c.bold('npx ruvnet-brain --update')}${hostConvergence.action ? `; ${hostConvergence.action}` : ''}`);
@@ -2765,6 +2829,7 @@ async function doctor() {
       warn(`host convergence receipt is invalid: ${error.message}`);
     }
   }
+  try { reportLegacyRufloDebris({ dryRun: true }); } catch (error) { warn(`legacy ruflo debris check failed: ${error.message}`); }
   const brainHome = process.env.RUVNET_BRAIN_HOME || path.dirname(cacheDir);
   const nightlyHealth = schedulerStatus({ platform: process.platform, env: process.env,
     brainHome, kbDir: cacheDir });
@@ -3274,6 +3339,18 @@ export function classifyUpdaterExit(status, { fallbackAllowed = true, result = n
     if (!requireResult) return { verdict: 'legacy-success', fallback: false, exitCode: 0 };
     return { verdict: 'invalid-result', fallback: false, exitCode: 1 };
   }
+  // The updater refused BECAUSE full-KB copies already sit beside the brain ("refusing to create another
+  // full-KB copy"). A fresh install is exactly another full copy (it preserves the prior generation), so
+  // the fallback would turn the refusal into +1 copy per run (measured: 2 -> 3, +1.3 GB). Report instead.
+  if (/^unresolved rollback state exists/.test(String(result?.reason || ''))) {
+    return { verdict: 'refused-retained-copies', fallback: false, exitCode: status || 1 };
+  }
+  // Exit 2 is "manifest unreachable, nothing touched". The fallback exists for a DEAD manifest URL (an old
+  // bundle polling a path that 404s); a rate limit, a 5xx or no network is transient, and a full fresh
+  // reinstall over it re-downloads the brain and preserves another full copy each time. Retry later instead.
+  if (status === 2 && /returned HTTP (?:403|408|429|5\d\d)\b|network failure/.test(String(result?.reason || ''))) {
+    return { verdict: 'transient-network', fallback: false, exitCode: 2 };
+  }
   return { verdict: 'failed', fallback: fallbackAllowed, exitCode: status || 1 };
 }
 
@@ -3370,6 +3447,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   wireCodexHost: detectCodexHost = wireCodexHost,
   wireCodexPlugin: installCodexPlugin = wireCodexPlugin,
   hostLockPath = path.join(brainHome, 'host-convergence.lock'),
+  replaceConsoles = null, // test seam; production runs replaceStaleConsoles
   runStableSpine = (apply) => spawnSync(
     process.execPath,
     [apply, '--auto', '--expected-version', PACKAGE_VERSION],
@@ -3425,6 +3503,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
     codexReceipt.restartRequired = true;
     codexReceipt.sessionSafety = results.codex.sessionSafety || null;
     codexReceipt.sessionSafetyReason = results.codex.sessionSafetyReason || null;
+    codexReceipt.restartScope = results.codex.restartScope || 'unproven';
   }
   const claudeReceipt = {
     state: results.claude.host ? 'ready' : 'absent',
@@ -3434,6 +3513,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
     claudeReceipt.restartRequired = true;
     claudeReceipt.sessionSafety = results.claude.sessionSafety || null;
     claudeReceipt.sessionSafetyReason = results.claude.sessionSafetyReason || null;
+    claudeReceipt.restartScope = results.claude.restartScope || 'unproven';
   }
   if (okApplied) {
     // ISSUE #153 — a running host may freeze an old plugin root. Reclaim only generations whose
@@ -3455,12 +3535,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
       warn(`stale plugin generations were not pruned (${e.message}); nothing was removed`);
     }
     const receiptPath = path.join(brainHome, 'host-convergence.json');
-    try {
-      runtimeTransaction.activate();
-      results.consoleRuntime = {
-        ...runtimeTransaction.identity,
-        ...consoleRestartState(runtimeTransaction.identity, { receiptDir: consoleReceiptDir }),
-      };
+    const writeConvergenceReceipt = () => {
       fs.mkdirSync(brainHome, { recursive: true });
       const tmp = `${receiptPath}.tmp-${process.pid}`;
       fs.writeFileSync(tmp, JSON.stringify({
@@ -3473,10 +3548,39 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
         consoleRuntime: results.consoleRuntime,
       }, null, 2));
       fs.renameSync(tmp, receiptPath);
+    };
+    try {
+      runtimeTransaction.activate();
+      results.consoleRuntime = {
+        ...runtimeTransaction.identity,
+        ...consoleRestartState(runtimeTransaction.identity, { receiptDir: consoleReceiptDir }),
+      };
+      writeConvergenceReceipt();
       runtimeTransaction.commit();
     } catch (error) {
       return fail({ applyStatus: applied.status, error: `Console runtime convergence failed: ${error.message}` });
     }
+    // A Console still serving the previous runtime is replaced here, by the activated runtime's own
+    // launcher (the 'stale-running' path of scripts/onboarding-console.mjs, without --open), so an
+    // update never ends with "restart Console". Anything it could not replace is recorded with why.
+    if (results.consoleRuntime.state === 'pending-console-restart') {
+      try {
+        const replaceArgs = { entry: runtimeTransaction.entry, identity: runtimeTransaction.identity, receiptDir: consoleReceiptDir };
+        results.consoleReplacement = replaceConsoles ? replaceConsoles(replaceArgs) : replaceStaleConsoles(replaceArgs);
+        const failures = results.consoleReplacement.filter((item) => !item.replaced);
+        for (const item of results.consoleReplacement) {
+          if (item.replaced) ok(`Console on port ${item.port} replaced with the current runtime (pid ${item.newPid})`);
+        }
+        results.consoleRuntime = {
+          ...runtimeTransaction.identity,
+          ...consoleRestartState(runtimeTransaction.identity, { receiptDir: consoleReceiptDir }),
+          ...(failures.length ? { replacementFailures: failures.map((item) => `port ${item.port ?? '?'}: ${item.reason}`) } : {}),
+        };
+        writeConvergenceReceipt();
+      } catch (error) {
+        warn(`could not replace the running Console automatically (${error.message})`);
+      }
+    }
   }
   if (!okApplied) return fail({ applyStatus: applied.status, error: applied.error?.message || 'Stable Spine activation failed' });
   const convergence = classifyHostConvergence({
@@ -3500,19 +3604,36 @@ export function classifyHostConvergence(receipt, expectedVersion = PACKAGE_VERSI
     return { healthy: false, state: 'version-mismatch', action: `required version ${expectedVersion}` };
   }
   const hostStates = Object.values(receipt.hosts || {});
-  const badHost = hostStates.find((host) => !['ready', 'disabled', 'absent'].includes(host?.state)
+  // A host that is ready at the expected version and whose ONLY gap is PROVEN changed boot-level
+  // declarations is converged: new sessions load the new hooks; only windows already open booted the
+  // old ones (owner's Mac, 4.3.40 -> 4.4.0: a fresh `claude -p` loaded 4.4.0 and ran its hooks). That is
+  // reported, not failed. An UNPROVEN boot surface (it could not be compared) still requires a restart.
+  const openSessionsOnly = (host) => host?.state === 'ready' && versionSatisfies(host.version, expectedVersion)
+    && host.restartRequired === true && host.restartScope === 'open-sessions';
+  const openSessions = Object.entries(receipt.hosts || {}).filter(([, host]) => openSessionsOnly(host)).map(([name]) => name);
+  const badHost = hostStates.find((host) => !openSessionsOnly(host) && (!['ready', 'disabled', 'absent'].includes(host?.state)
     || (host.state === 'ready' && !versionSatisfies(host.version, expectedVersion))
-    || (host.state === 'ready' && host.restartRequired === true));
+    || (host.state === 'ready' && host.restartRequired === true)));
   if (badHost?.restartRequired === true) {
     return { healthy: false, state: 'host-restart-required', action: badHost.sessionSafetyReason || 'restart the host, then re-run --doctor' };
   }
   if (badHost) return { healthy: false, state: 'host-pending', action: 're-run host synchronization' };
   if (receipt.consoleRuntime?.state !== 'ready') {
-    return { healthy: false, state: receipt.consoleRuntime?.state || 'console-unproven', action: 'restart Console, then re-run --doctor' };
+    const why = Array.isArray(receipt.consoleRuntime?.replacementFailures) && receipt.consoleRuntime.replacementFailures.length
+      ? `the installer could not replace the running Console (${receipt.consoleRuntime.replacementFailures.join('; ')}); ` : '';
+    return { healthy: false, state: receipt.consoleRuntime?.state || 'console-unproven', action: `${why}restart Console, then re-run --doctor` };
   }
+  if (openSessions.length) return { healthy: true, state: 'channels-converged', openSessions, notice: openSessionsNotice(openSessions, receipt.desiredVersion) };
   return { healthy: true, state: 'channels-converged' };
 }
 
+const HOST_LABELS = { claude: 'Claude Code', codex: 'Codex' };
+/** The one accurate line for converged hosts whose already-open windows booted the old declarations. */
+export function openSessionsNotice(hosts, version) {
+  const names = hosts.map((host) => HOST_LABELS[host] || host).join('/');
+  return `new ${names} sessions use ${version}; already-open windows keep the old hook definitions until they are reopened`;
+}
+
 async function runUpdate() {
   printBanner('update');
   const kbDir = resolvedKbDir();
@@ -3525,6 +3646,7 @@ async function runUpdate() {
       process.exitCode = 1;
       return;
     }
+    if (convergence.convergence?.notice) info(convergence.convergence.notice);
     try {
       const managed = applyManagedCatalogUpdate({
         routerDir: path.join(os.homedir(), '.claude', 'model-router'),
@@ -3587,6 +3709,21 @@ async function runUpdate() {
   };
   process.once('exit', exitGuard);
   info(`brain dir: ${c.bold(kbDir)}`);
+  // RECOVER AN INTERRUPTED UPDATE FIRST, before anything below writes into the brain. Two measured
+  // reasons: (1) a kill between the two directory renames leaves no usable kb/ — the brain sits in a
+  // receipted kb.rollback-<id>, and the recovery that renames it back lives inside the updater that is
+  // now missing; (2) the preflight below re-stamps RUNTIME-IDENTITY.json into kb/, after which recovery
+  // can never prove kb/ still equals the identity sealed at LOCKED, so any pre-activation kill wedged
+  // every later update at RECOVERY_REQUIRED. Same function the updater runs, under this refresh lock.
+  // Receipts hold the REAL paths the updater knew, so recovery is addressed by the physical path.
+  if (fs.existsSync(path.join(path.dirname(kbDir), `.${path.basename(kbDir)}.update-transactions`))) {
+    try {
+      const recovered = recoverIncompleteStorageTransactions(physicalPath(kbDir));
+      if (recovered.length) ok(`restored the brain from an interrupted update (${recovered.map((r) => `${r.transactionId}: ${r.from}`).join(', ')})`);
+    } catch (error) {
+      warn(`an interrupted update could not be recovered automatically: ${error.message}`);
+    }
+  }
   let updateStatus = 1;
   // NO updater at all = no brain installed here (or a pre-self-updater bundle). That is a USER
   // message, not a fallback trigger: fail LOUD with the re-run-installer help and exit — never
@@ -3645,6 +3782,10 @@ async function runUpdate() {
     result: updaterResult,
     requireResult: supportsResultReceipt,
   });
+  if (outcome.verdict === 'refused-retained-copies') {
+    warn('nothing was changed: full copies of earlier brain generations already sit beside this one (listed above).');
+    info('Check that you no longer need them, remove them, then re-run  npx ruvnet-brain --update');
+  }
   if (outcome.fallback && FLAG_HOST_SYNC_ONLY) {
     // Host synchronization has a narrower contract than a full update: it must converge the
     // executable plugin/spine to the published package even when an optional large KB asset is
@@ -3742,9 +3883,11 @@ async function runUpdate() {
     if (!convergence.ok) {
       warn(`host synchronization is incomplete — runtime stays on the prior verified generation${convergence.error ? ` (${convergence.error})` : ''}`);
       updateStatus = 1;
-    }
+    } else if (convergence.convergence?.notice) info(convergence.convergence.notice);
+    try { reportLegacyRufloDebris(); } catch (error) { warn(`legacy ruflo debris cleanup failed: ${error.message}`); }
     recordRefreshPhase(refreshReceipt, 'host-convergence', convergence.ok && convergence.convergence?.healthy === true ? 'PASS' : 'FAIL', {
       state: convergence.convergence?.state || null, error: convergence.error || null,
+      ...(convergence.convergence?.openSessions ? { openSessions: convergence.convergence.openSessions } : {}),
       execution: { kind: 'executed', runId: refreshReceipt.runId },
     });
   }
@@ -4951,7 +5094,7 @@ async function offerStack(env) {
   for (const m of missing) {
     if (m.shell) {
       info(`installing ${m.what} … ${c.dim(m.say)}`);
-      const ran = tryRun(m.shell[0], m.shell[1]);
+      const ran = ['claude', 'codex'].includes(m.shell[0]) ? tryHostCli(m.shell[0], m.shell[1]) : tryRun(m.shell[0], m.shell[1]);
       // Don't trust the exit code alone — e.g. `claude mcp add` exits non-zero on "already exists",
       // which is functionally success. Re-check the real state (m.verify) before warning.
       if (ran || (m.verify && m.verify())) ok(`${m.what} added`);

package/kb/brain-profile.mjs

@@ -61,16 +61,31 @@ function profileOwnership(dir) {
       ? Object.entries(source.stores) : null;
   if (!entries) throw new Error('invalid SOURCE ownership policy');
   const privateNames = new Set(fence.privateStores.map((s) => s.toLowerCase()));
+  // Published store names include dots (`dspy.ts`, `ruv.io`). A name may not start with a dot, hold `..`
+  // or a separator, or end in an artifact suffix (`x.big` would collide with store x's `x.big.rvf`).
+  const safeName = (name) => typeof name === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(name) && !name.includes('..')
+    && !/\.(?:big|rvf)$/i.test(name);
   const managed = new Set();
+  const optedOut = new Set();
   const seen = new Set();
   for (const [name, value] of entries) {
-    if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/i.test(name)
+    if (!safeName(name)
       || !value || typeof value !== 'object' || Array.isArray(value)
       || (value.kbName != null && value.kbName !== name)
       || (value.updateManaged != null && typeof value.updateManaged !== 'boolean')
       || seen.has(name.toLowerCase())) throw new Error('invalid SOURCE store ownership');
     seen.add(name.toLowerCase());
-    if (value.updateManaged !== false && !privateNames.has(name.toLowerCase())) managed.add(name);
+    if (value.updateManaged === false) optedOut.add(name.toLowerCase());
+    else if (!privateNames.has(name.toLowerCase())) managed.add(name);
+  }
+  // The release's PUBLIC ledger is the other ownership record: stores it publishes but SOURCE does not list
+  // (concepts, ruv-gists) are still release-owned, and forge-update's profiled check expects them gone.
+  const publicFile = path.join(dir, 'PUBLIC-RVF-GENERATIONS.json');
+  if (fs.existsSync(publicFile)) {
+    for (const name of Object.keys(read('PUBLIC-RVF-GENERATIONS.json').stores || {})) {
+      const key = String(name).toLowerCase();
+      if (safeName(name) && !privateNames.has(key) && !optedOut.has(key)) managed.add(name);
+    }
   }
   return { managed, read };
 }

package/kb/forge-update.mjs

@@ -650,7 +650,9 @@ export function restorePrivateOverlayState({ kbDir, overlay }) {
   const cardsFile = path.join(kbDir, 'capability-cards.md');
   const source = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));
   const generations = JSON.parse(fs.readFileSync(generationsFile, 'utf8'));
-  const aliases = JSON.parse(fs.readFileSync(aliasesFile, 'utf8'));
+  // A public bundle may ship no repo-aliases.json at all (build-bundle: "aliases will not resolve"); the
+  // private aliases then start from an empty map instead of failing the whole update on ENOENT.
+  const aliases = fs.existsSync(aliasesFile) ? JSON.parse(fs.readFileSync(aliasesFile, 'utf8')) : {};
   const mergedSource = mergePrivateEntries(source.stores, overlay.sourceStores, 'SOURCE.json');
   const mergedGenerations = mergePrivateEntries(generations.stores, overlay.generationStores, 'RVF-GENERATIONS.json');
   const mergedAliases = mergePrivateEntries(aliases, overlay.aliases, 'repo-aliases.json');
@@ -1640,7 +1642,9 @@ async function main() {
   if (!APPLY) {
     writeCheckOutcome({ currencyVerdict: verdict.verdict, currencyReason: verdict.reason,
       candidateKind: candidateIdentity.kind, storeCount: targets.length });
-    if (anyBehind) { console.log(`\nA newer build exists. Run:  node forge-update.mjs --apply`); process.exit(10); }
+    // The npx door upgrades this updater before applying; an old installed updater run directly can fail
+    // the guard on a newer bundle (customer-state-matrix D8, 2026-09-30).
+    if (anyBehind) { console.log(`\nA newer build exists. Run:  npx ruvnet-brain@latest --update`); process.exit(10); }
     console.log(`\nAll stores current. Nothing to do.`); process.exit(0);
   }
 

package/kb/lifecycle-evidence-retention.mjs

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { physicalPath } from './refresh-run.mjs';
 
 const TERMINAL_REFRESH = new Set(['SUCCEEDED', 'FAILED', 'ABANDONED']);
 const TERMINAL_TRANSACTION = new Set(['NOOP', 'COMMITTED', 'ROLLED_BACK']);
@@ -113,10 +114,11 @@ function newest(rows, predicate) {
 
 function trustedEvidenceRoot(root, unsafe) {
   try {
-    for (const entry of [path.dirname(root), root]) {
-      const stat = fs.lstatSync(entry);
-      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('evidence root is not a trusted directory (symbolic or special entry)');
-    }
+    // The PARENT is where the user put the brain (`~/.cache/ruvnet-brain` may be a link to another disk):
+    // it must be a directory once resolved. The evidence root itself must not be a link.
+    if (!fs.statSync(physicalPath(path.dirname(root))).isDirectory()) throw new Error('evidence root parent is not a directory');
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('evidence root is not a trusted directory (symbolic or special entry)');
     return true;
   } catch (error) {
     if (error.code !== 'ENOENT') unsafe.push({ path: root, reason: error.message });
@@ -130,7 +132,7 @@ function snapshot(options) {
   const refresh = trustedEvidenceRoot(roots.refresh, unsafe) ? scanRefresh(roots.refresh, unsafe) : [];
   const transactions = trustedEvidenceRoot(roots.transactions, unsafe) ? scanTransactions(roots.transactions, unsafe) : [];
   const preserveRefresh = new Set((options.preserveRefreshRunIds || []).map(String));
-  const preserveTransactions = new Set((options.preserveTransactionPaths || []).map((entry) => path.resolve(entry)));
+  const preserveTransactions = new Set((options.preserveTransactionPaths || []).map((entry) => physicalPath(entry)));
   const protectedRefresh = new Map();
   const protectRefresh = (row, reason) => { if (row) protectedRefresh.set(row.path, reason); };
   for (const row of refresh) {
@@ -147,17 +149,18 @@ function snapshot(options) {
     if (!protectedRefresh.has(row.path)) continue;
     for (const reference of transactionReferences(row.receipt)) {
       const resolved = path.resolve(String(reference || ''));
-      const relative = path.relative(roots.transactions, resolved);
+      // The updater records real paths; the caller may spell the brain through a link. Same space, both sides.
+      const relative = path.relative(physicalPath(roots.transactions), physicalPath(resolved));
       if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || relative.includes(path.sep)) {
         unsafe.push({ path: row.path, reason: `forged external transaction reference: ${String(reference)}` });
-      } else retainedTransactionPaths.add(resolved);
+      } else retainedTransactionPaths.add(physicalPath(resolved));
     }
   }
   const protectedTransactions = new Map();
   for (const row of transactions) {
     if (!TERMINAL_TRANSACTION.has(row.latest.state)) protectedTransactions.set(row.path, `nonterminal ${row.latest.state}`);
-    if (preserveTransactions.has(row.path)) protectedTransactions.set(row.path, 'explicitly preserved transaction');
-    if (retainedTransactionPaths.has(row.path)) protectedTransactions.set(row.path, 'referenced by retained refresh receipt');
+    if (preserveTransactions.has(physicalPath(row.path))) protectedTransactions.set(row.path, 'explicitly preserved transaction');
+    if (retainedTransactionPaths.has(physicalPath(row.path))) protectedTransactions.set(row.path, 'referenced by retained refresh receipt');
   }
   const bytes = [...refresh, ...transactions].reduce((sum, row) => sum + row.bytes, 0)
     + unsafe.filter(({ reason }) => /quarantine remains/.test(reason)).reduce((sum, { path: entry }) => {

package/kb/refresh-run.mjs

@@ -78,6 +78,19 @@ export function inspectRefreshOwner(owner, { hostname = os.hostname(), inspectPr
   return ownerState(owner, { hostname, inspectProcess, isAlive });
 }
 
+/**
+ * The ONE physical-path rule for brain directories. A user may reach the brain through a symlink
+ * (`~/.cache -> /Volumes/<disk>`) while the updater knows it by its real path (Node resolves
+ * import.meta.url), so identity checks compare this, never spellings. A directory that does not
+ * exist right now (kb/ mid-rename) resolves through its parent, so the answer does not flip.
+ */
+export function physicalPath(dir) {
+  const resolved = path.resolve(String(dir || ''));
+  try { return fs.realpathSync.native(resolved); } catch { /* absent: resolve through the parent */ }
+  try { return path.join(fs.realpathSync.native(path.dirname(resolved)), path.basename(resolved)); }
+  catch { return resolved; }
+}
+
 export const refreshLockPath = (kbDir) =>
   path.join(path.dirname(path.resolve(kbDir)), `.${path.basename(path.resolve(kbDir))}.refresh-run.lock`);
 
@@ -156,7 +169,10 @@ export function acquireRefreshLock({
   const inherited = String(env.RUVNET_REFRESH_RUN_TOKEN || '');
   if (inherited) {
     const owner = JSON.parse(fs.readFileSync(path.join(lockPath, 'owner.json'), 'utf8'));
-    if (owner.schemaVersion !== 3 || owner.token !== inherited || path.resolve(owner.kbDir) !== root
+    // Same DIRECTORY, not same spelling: the installer locks RUVNET_BRAIN_KB as given (possibly through
+    // a symlinked ~/.cache), the child updater knows its KB by import.meta.url, which Node resolves to
+    // the real path. Compare physical identity; a genuinely different directory still refuses.
+    if (owner.schemaVersion !== 3 || owner.token !== inherited || physicalPath(owner.kbDir) !== physicalPath(root)
       || path.resolve(owner.receiptPath || '') !== refreshReceiptPath(owner.brainHome, owner.runId)) {
       throw new Error(`refresh lock inheritance does not match ${lockPath}`);
     }