ruvnet-brain 4.5.0 → 4.5.2

package/README.md

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

@@ -27,7 +27,7 @@ import { assessLifecycleEvidence, pruneLifecycleEvidence } from '../kb/lifecycle
 import { checkDiskSpace, recoverIncompleteStorageTransactions } from '../kb/update-storage-transaction.mjs';
 import { footprintRoots, inventoryFootprint, sweepFootprint } from '../plugin/scripts/brain-footprint.mjs';
 import { kbCopyProof } from '../plugin/scripts/kb-copy-proof.mjs';
-import { isVolumeMetadata } from '../plugin/scripts/footprint-io.mjs';
+import { assessMoveLeftovers, isVolumeMetadata } from '../plugin/scripts/footprint-io.mjs';
 import { confirm, doctorVerdict, formatBytes, formatConfirmation, signatureEvidenceFromReceipts, signatureRecordValid, writeSignatureRecord } from '../plugin/scripts/brain-confirmation.mjs';
 import {
   requiredEmbedderModels,
@@ -3890,6 +3890,20 @@ function refuseUnmountedBrain() {
   die(roots.location.message, 'Nothing was installed, updated or removed.');
 }
 
+// An interrupted --move-brain left the ONLY Brain at <home>.old-<pid> while the home path is missing or was
+// recreated without a Brain by a hook (4.5.2): an install or update there would build a second, public-only
+// Brain beside it. Refuse with the restore command instead. Names only: no tree walk.
+function refuseOverSetAsideBrain() {
+  let lo = null;
+  try { const roots = footprintRoots(); lo = assessMoveLeftovers({ brainHome: roots.location?.path || roots.brainHome, location: roots.location }).find((l) => l.onlyCopy); }
+  catch { return false; }
+  if (!lo) return false;
+  warn(`the Brain is not at its path, but an interrupted move left the ONLY copy at ${lo.path} — restore it, do NOT reinstall:  ${lo.fix}`);
+  info(`then check:  ${c.bold('npx ruvnet-brain --doctor')}`);
+  process.exitCode = 1;
+  return true;
+}
+
 async function runUpdate() {
   printBanner('update');
   refuseUnmountedBrain();
@@ -4473,7 +4487,9 @@ async function printConfirmation({ footprint = null, json = false, print = true
   const now = footprintNow();
   // Read-only: the inventory only — no copy is proven (no GB-sized hashing) and nothing is written (re-review S4).
   const fp = footprint || inventoryFootprint({ now, evidence: footprintEvidence() });
-  const result = confirm({ footprint: fp, npmLatest: await npmLatestVersion(), installedVersion: PACKAGE_VERSION, now });
+  // The doctor also checks the directory's bytes against the release projection (bounded: ~0.3 s on 1.4 GB).
+  const result = confirm({ footprint: fp, npmLatest: await npmLatestVersion(), installedVersion: PACKAGE_VERSION, now,
+    coverageIntegrity: FLAG_DOCTOR ? (dir) => validateCoverageDirectory(dir) : null });
   if (!print) return result;
   if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   else console.log(`\n${formatConfirmation(result, { color: c })}`);
@@ -6061,7 +6077,7 @@ the installer reports that boot-level declarations changed.
   }
   if (FLAG_DEMO) return runDemo();
   if (FLAG_FEEDBACK) return runFeedback();
-  if (FLAG_UPDATE) return runUpdate();
+  if (FLAG_UPDATE) return refuseOverSetAsideBrain() || runUpdate();
   if (FLAG_ENABLE_NIGHTLY) return enableNightly();
   if (FLAG_DISABLE_NIGHTLY) return disableNightly();
   // Standalone, like the nightly pair above. Without these, the flags existed only as a way to
@@ -6074,6 +6090,7 @@ the installer reports that boot-level declarations changed.
   if (FLAG_WHAT_CHANGED) { printBanner('what RuvNet Brain put on this machine'); printFootprint(); return; }
   if (FLAG_WHATS_NEW) { showWhatsNew(); return; }
 
+  if (refuseOverSetAsideBrain()) return;
   printBanner('installer');
   console.log(c.dim("I'll set up the brain for Claude Code and Codex, explaining each step as I go.\n"));
 

package/kb/forge-update.mjs

@@ -1627,7 +1627,7 @@ async function main() {
         currencyVerdict: verdict.verdict, currencyReason: verdict.reason, candidateKind: candidateIdentity.kind,
         storeCount: targets.length })
       : writeCheckOutcome({ currencyVerdict: verdict.verdict, currencyReason: verdict.reason,
-        candidateKind: candidateIdentity.kind, storeCount: targets.length });
+        candidateKind: candidateIdentity.kind, candidateTag: candidateIdentity.tag, storeCount: targets.length });
     if (refusedOutcome?.terminalVerdict === 'recovery-required') die(refusedOutcome.reason);
     process.exit(0);
   }
@@ -1649,7 +1649,7 @@ async function main() {
 
   if (!APPLY) {
     writeCheckOutcome({ currencyVerdict: verdict.verdict, currencyReason: verdict.reason,
-      candidateKind: candidateIdentity.kind, storeCount: targets.length });
+      candidateKind: candidateIdentity.kind, candidateTag: candidateIdentity.tag, storeCount: targets.length });
     // 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); }

package/package.json

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

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

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/mcp/server.mjs

@@ -33,6 +33,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
 import { writeOwn as writeOwnReadiness } from '../scripts/mcp-readiness.mjs';
 import { callManagedCli, MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
 import { unmountedNotice } from '../scripts/brain-location.mjs';
@@ -133,7 +134,11 @@ function currentGeneration() {
   const a = readJSON(ACTIVE);
   let brainMtime = 0;
   try { brainMtime = fs.statSync(CHILD_MCP).mtimeMs; } catch { /* brain absent */ }
-  return `${a?.generation ?? 0}:${brainMtime}`;
+  // The KB's own identity record: every knowledge update (corpus-only included) rewrites SOURCE.json, so a
+  // swapped knowledge base respawns the worker even when its code file is byte- and mtime-identical.
+  let knowledgeMtime = 0;
+  try { knowledgeMtime = fs.statSync(path.join(KB, 'SOURCE.json')).mtimeMs; } catch { /* brain absent */ }
+  return `${a?.generation ?? 0}:${brainMtime}:${knowledgeMtime}`;
 }
 function refreshLease() {
   try {
@@ -393,6 +398,27 @@ async function handleClient(msg) {
   }
 }
 
+// KNOWLEDGE CURRENCY TIMER (2026-10-02). A session can stay open for days and SessionStart never fires
+// again, so this process — alive for the whole session on Claude Code and Codex alike — runs the SAME
+// throttled newer-published check SessionStart runs (session-start-update-plane.mjs knowledgeAutoUpdate:
+// per-machine throttle, shared O_EXCL lock, one detached updater). Unref'd (never keeps this process
+// alive), skipped while a query is in flight or the worker is starting, skipped when the brain is off.
+// The new knowledge reaches the worker through currentGeneration() above: the next call after the swap
+// respawns it between requests. announce:false — the once-per-session UPDATED line is SessionStart's.
+const CORPUS_CHECK_INTERVAL_MS = Number(process.env.RUVNET_CORPUS_CHECK_INTERVAL_MS) || 15 * 60_000;
+const SCRIPTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'scripts');
+const corpusTimer = setInterval(() => {
+  if (pendingCount > 0 || childStartup) return;
+  Promise.all([import('../scripts/session-start-update-plane.mjs'), import('../scripts/session-start-health.mjs')])
+    .then(([plane, health]) => {
+      const home = os.homedir();
+      if (health.brainState(process.env, home).off) return;
+      plane.knowledgeAutoUpdate({ env: process.env, home, now: Date.now(), hookDir: SCRIPTS_DIR, announce: false });
+    })
+    .catch((e) => console.error(`[ruvnet-brain] knowledge currency check skipped: ${e.message}`));
+}, CORPUS_CHECK_INTERVAL_MS);
+corpusTimer.unref();
+
 const clientRl = readline.createInterface({ input: process.stdin });
 clientRl.on('line', (line) => {
   let msg; try { msg = JSON.parse(line); } catch { return; } // malformed line: ignore, never crash

package/plugin/scripts/brain-confirmation.mjs

@@ -15,6 +15,7 @@ import crypto from 'node:crypto';
 import { cmpVersion, footprintRoots, physical } from './brain-footprint.mjs';
 import { readAll as readReadiness } from './mcp-readiness.mjs';
 import { volumeOf } from './brain-location.mjs';
+import { AUTO_UPDATE_LOCK_STALE_MS, autoUpdatePaths, newerCorpusPending } from './session-start-health.mjs';
 
 export const KNOWLEDGE_MAX_AGE_HOURS = 48;
 export const SIGNATURE_RECORD = 'knowledge-signature.json';
@@ -84,7 +85,7 @@ const line = (id, label, state, detail, fix = null) => ({ id, label, state, deta
  * @param installedVersion the package version the caller runs, used when no spine is active
  */
 export function confirm({ footprint, env = process.env, home = os.homedir(), now = Date.now(), npmLatest = null,
-  installedVersion = null, readiness = null } = {}) {
+  installedVersion = null, readiness = null, coverageIntegrity = null } = {}) {
   const roots = footprint?.roots || footprintRoots({ env, home });
   const lines = [];
   const active = readJson(path.join(roots.brainHome, 'active.json'));
@@ -121,21 +122,41 @@ export function confirm({ footprint, env = process.env, home = os.homedir(), now
   }
   const source = readJson(path.join(roots.kbDir, 'SOURCE.json'));
   const builtMs = Date.parse(source?.builtUtc || '');
-  const signature = readJson(path.join(roots.brainHome, SIGNATURE_RECORD));
+  const signatureFile = path.join(roots.brainHome, SIGNATURE_RECORD);
+  const recorded = fs.existsSync(signatureFile);
+  const signature = recorded ? readJson(signatureFile) : null;
   const coverage = sha256File(path.join(roots.kbDir, 'COVERAGE.json'));
   const signed = Boolean(signature?.coverageSha256 && coverage && signature.coverageSha256 === coverage);
   const tag = source?.corpusReleaseTag || source?.releaseTag || null;
-  // Structural problems (a second copy, unverified bytes) gate; age is currency and only advises.
+  // Structural problems (a second copy, a record the live bytes contradict) gate; age is currency and only advises.
+  // NO record is provenance unknown, not provably broken (an install from a local sealed artifact and the automatic
+  // updater never write one): it advises. A record that is present but unreadable or does not match gates.
   const knowledgeProblems = [];
   const knowledgeAdvice = [];
   if (footprint.kbCopies !== 1) knowledgeProblems.push([`${footprint.kbCopies} copies on disk (must be exactly 1)`, footprint.kbCopyFix || (footprint.kbCopies ? CLEAN : 'npx ruvnet-brain@latest')]);
-  if (!signed) knowledgeProblems.push([signature ? 'signature record does not match the live COVERAGE.json' : 'no signature verification recorded for these bytes', UPDATE]);
+  if (!recorded) knowledgeAdvice.push([`installed or updated without a recorded signature verification — run ${UPDATE} to verify`, UPDATE]);
+  else if (!signed) knowledgeProblems.push([signature ? 'signature record does not match the live COVERAGE.json' : 'signature record is unreadable', UPDATE]);
+  // The record binds COVERAGE.json's bytes only. The doctor passes the release-coverage check (every store's bytes
+  // against the release projection, ~0.3 s on a 1.4 GB KB): a projection that fails it is ✗; a directory without one
+  // (an older corpus) cannot be checked, and the line then claims only what the record proves (4.5.2).
+  const integrity = signed && coverageIntegrity ? coverageIntegrity(roots.kbDir) : null;
+  const checkable = Boolean(integrity) && fs.existsSync(path.join(roots.kbDir, 'CORPUS-COVERAGE.json'));
+  if (checkable && !integrity.valid) knowledgeProblems.push([`the bytes on disk fail the release-coverage check (${integrity.failures?.[0] || 'unknown'})`, UPDATE]);
+  // A newer corpus is published and not yet installed (identity, not age): advisory, never a gate.
+  const pending = newerCorpusPending({ source, corpusCheck: readJson(autoUpdatePaths(roots.brainHome).checkFile) });
+  if (pending) {
+    const lockAt = readJson(autoUpdatePaths(roots.brainHome).lockFile)?.at;
+    const running = Number.isFinite(Date.parse(lockAt || '')) && now - Date.parse(lockAt) < AUTO_UPDATE_LOCK_STALE_MS;
+    const short = pending.tag.length > 28 ? `${pending.tag.slice(0, 26)}…` : pending.tag;
+    knowledgeAdvice.push([`newer corpus ${short} published (checked ${iso(Date.parse(pending.checkedAt || ''))}); automatic update ${running ? 'running now' : 'pending'}`, UPDATE]);
+  }
   if (!Number.isFinite(builtMs) || (now - builtMs) / 3_600_000 >= KNOWLEDGE_MAX_AGE_HOURS) knowledgeAdvice.push([`built ${Number.isFinite(builtMs) ? ago(builtMs, now) : 'at an unknown time'} (limit ${KNOWLEDGE_MAX_AGE_HOURS}h)`, UPDATE]);
   const where = roots.location?.state === 'linked'
     ? `at ${roots.kbDir} (moved to ${volumeOf(roots.location.real)}, mounted)` : `at ${roots.kbDir}`;
   const moved = footprint.moveLeftovers || { copies: 0, bytes: 0 };
   const knowledgeDetail = [`${footprint.kbCopies} copy ${where}${moved.copies ? ` (not counted: ${moved.copies} interrupted-move cop${moved.copies === 1 ? 'y' : 'ies'} (${formatBytes(moved.bytes)}) — see the Move lines)` : ''}`, `built ${iso(builtMs)}${Number.isFinite(builtMs) ? ` (${ago(builtMs, now)})` : ''}`,
-    signed ? `signature verified ${iso(Date.parse(signature.verifiedAt))}` : 'signature NOT verified', `corpus ${tag ? (tag.length > 28 ? `${tag.slice(0, 26)}…` : tag) : 'unknown'}`].join(' · ');
+    !signed ? 'signature NOT verified' : integrity && !checkable ? `install record matches COVERAGE.json ${iso(Date.parse(signature.verifiedAt))}`
+      : `signature verified ${iso(Date.parse(signature.verifiedAt))}`, `corpus ${tag ? (tag.length > 28 ? `${tag.slice(0, 26)}…` : tag) : 'unknown'}`].join(' · ');
   const knowledgeIssues = [...knowledgeProblems, ...knowledgeAdvice];
   lines.push(line('knowledge', 'Knowledge', knowledgeProblems.length ? 'fail' : knowledgeAdvice.length ? 'warn' : 'ok',
     knowledgeIssues.length ? `${knowledgeDetail} — ${knowledgeIssues.map(([p]) => p).join('; ')}` : knowledgeDetail, knowledgeIssues[0]?.[1]));

package/plugin/scripts/brain-footprint.mjs

@@ -52,7 +52,8 @@ export const kbCopyPrefixes = (base) => [
   `${base}-pre-gap-rebuild-backup-`, `${base}.install-preserved-`, `${base}.install-prior-`,
   `${base}.pre-update-`, `${base}.next-`, `${base}.rollback-`, `${base}.failed-`,
 ];
-const TRANSACTION_KINDS = { next: 'candidate', rollback: 'rollback', failed: 'failed' };
+const BRAIN_BACKUP_STAMP = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:-\d{3})?Z$/; // the updater's stamp(); other kb.bak-* are the customer's
+const TRANSACTION_KINDS ={ next: 'candidate', rollback: 'rollback', failed: 'failed' };
 export const LOG_FILES = Object.freeze(['evidence.jsonl', 'token-ledger.jsonl', 'detached-jobs.jsonl',
   'update-receipts.jsonl', 'gate-blocks.jsonl', 'distill-receipts.jsonl', 'assertion-gate-shadow.jsonl',
   'capability-live-evidence.jsonl', 'design-grades.jsonl', 'grounding-overrides.jsonl']);
@@ -184,6 +185,10 @@ export function inventoryFootprint({ env = process.env, home = os.homedir(), now
   const classifySibling = (name, full, st) => {
     {
       const prefix = kbCopyPrefixes(base).find((p) => name.startsWith(p));
+      if (prefix === `${base}.bak-` && !BRAIN_BACKUP_STAMP.test(name.slice(prefix.length))) {
+        return void add({ id: 'foreign', path: full, class: 'unowned', kind: 'hand-made-backup', action: 'report', bytes: bytes(full),
+          reason: 'a hand-made KB backup (not the Brain\'s own kb.bak-<stamp> name): reported, never deleted' });
+      }
       if (prefix) {
         if (st.isSymbolicLink() || !st.isDirectory()) { add({ id: 'kb-copy', path: full, class: 'unowned', kind: 'kb-copy-link', action: 'report', reason: 'a link or file under a KB-copy name; never followed or removed' }); return; }
         const kind = Object.entries(TRANSACTION_KINDS).find(([k]) => prefix === `${base}.${k}-`)?.[1] || null;
@@ -392,10 +397,10 @@ function summarize({ roots, items, policy, kbCopyDirs, lockHeld }) {
     breakdown[group] = (breakdown[group] || 0) + (i.bytes || 0);
   }
   const cruft = items.filter((i) => i.class === 'must-not-exist');
-  // When every extra KB copy is one no command can remove, the copy-count fix is the honest remedy, not --clean.
-  const extra = items.filter((i) => i.kind === 'kb-copy' || i.kind === 'quarantine');
-  const onlyCopy = items.find((i) => i.kind === 'move-leftover' && i.onlyCopy);
-  const kbCopyFix = onlyCopy ? onlyCopy.fix : extra.length && extra.every((i) => i.keptUnique) ? extra[0].fix : null;
+  // Every extra copy unremovable → its own fix, not --clean; all owned by an update transaction → --update (4.5.2).
+  const extra = items.filter((i) => i.kind === 'kb-copy' || i.kind === 'quarantine'), onlyCopy = items.find((i) => i.kind === 'move-leftover' && i.onlyCopy);
+  const inTransaction = items.some((i) => /^transaction-/.test(i.kind)), kbCopyFix = onlyCopy ? onlyCopy.fix : extra.length && extra.every((i) => i.keptUnique) ? extra[0].fix
+    : !extra.length && inTransaction ? 'npx ruvnet-brain@latest --update' : null;
   const moved = items.filter((i) => i.kind === 'move-leftover');
   return { schemaVersion: 1, kind: 'ruvnet-brain-footprint', roots, items, policy, lockHeld, kbCopyFix,
     liveKb: items.find((i) => i.kind === 'live-kb'),

package/plugin/scripts/footprint-io.mjs

@@ -77,8 +77,8 @@ export function findMoveLeftovers({ brainHome, location = null, isAlive = pidAli
 // has no control character (or, on Windows, no double quote); otherwise the advice is to inspect it by hand.
 const shQuote = (p) => `'${String(p).replace(/'/g, `'\\''`)}'`;
 const COMMANDS = {
-  posix: { rmTree: (p) => `rm -rf -- ${shQuote(p)}`, rmLink: (p) => `rm -- ${shQuote(p)}`, mv: (a, b) => `mv -- ${shQuote(a)} ${shQuote(b)}` },
-  win32: { rmTree: (p) => `rmdir /s /q "${p}"`, rmLink: (p) => `rmdir "${p}"`, mv: (a, b) => `move "${a}" "${b}"` },
+  posix: { rmTree: (p) => `rm -rf -- ${shQuote(p)}`, rmLink: (p) => `rm -- ${shQuote(p)}`, mv: (a, b) => `mv -- ${shQuote(a)} ${shQuote(b)}`, rmdir: (p) => `rmdir -- ${shQuote(p)}` },
+  win32: { rmTree: (p) => `rmdir /s /q "${p}"`, rmLink: (p) => `rmdir "${p}"`, mv: (a, b) => `move "${a}" "${b}"`, rmdir: (p) => `rmdir "${p}"` },
 };
 const holdsBrain = (dir) => ['SOURCE.json', path.join('kb', 'SOURCE.json')].some((f) => Boolean(lstat(path.join(dir, f))));
 
@@ -93,7 +93,11 @@ export function assessMoveLeftovers({ brainHome, location = null, isAlive = pidA
   const safe = (p, dir) => physical(path.dirname(p)) === physical(dir) && !/[\u0000-\u001f\u007f]/.test(p)
     && !(platform === 'win32' && p.includes('"')) && !/[\u0000-\u001f\u007f]/.test(brainHome);
   const inspect = (p) => `inspect it by hand: ${JSON.stringify(p)} (no command is suggested for this path)`;
-  const homeMissing = !lstat(brainHome);
+  // A real directory with no Brain in it counts as missing: a hook or the search server recreates the home on a
+  // failure path (health.json, a notice file) after an interrupted move (4.5.2). A link is judged by `location`.
+  const homeSt = lstat(brainHome);
+  const homeMissing = !homeSt || (!homeSt.isSymbolicLink() && !holdsBrain(brainHome));
+  const homeEmpty = Boolean(homeSt) && homeMissing && !names(brainHome).length;
   const found = findMoveLeftovers({ brainHome, location, isAlive }).map((lo) => {
     const link = Boolean(lstat(lo.path)?.isSymbolicLink());
     let target = null;
@@ -104,7 +108,10 @@ export function assessMoveLeftovers({ brainHome, location = null, isAlive = pidA
   const restore = homeMissing ? found.filter((f) => f.brain).sort((a, b) => order.indexOf(a.what) - order.indexOf(b.what))[0] : null;
   return found.map((f) => {
     const ok = safe(f.path, f.dir);
-    if (f === restore) return { ...f, onlyCopy: true, fix: ok ? cmd.mv(f.path, brainHome) : inspect(f.path) };
+    // The recreated home is cleared out of the way first: removed if empty (rmdir refuses anything else), set aside
+    // under a name of its own otherwise — never deleted with its contents, and the leftover is never deleted.
+    const clear = !homeSt ? null : homeEmpty ? cmd.rmdir(brainHome) : cmd.mv(brainHome, `${brainHome}.recreated-${f.pid}`);
+    if (f === restore) return { ...f, onlyCopy: true, fix: ok ? [clear, cmd.mv(f.path, brainHome)].filter(Boolean).join(' && ') : inspect(f.path) };
     if (restore) return { ...f, onlyCopy: false, fix: `keep it until the Brain is restored at ${JSON.stringify(brainHome)} and --doctor is green` };
     return { ...f, onlyCopy: false, fix: ok ? (f.link ? cmd.rmLink(f.path) : cmd.rmTree(f.path)) : inspect(f.path) };
   });

package/plugin/scripts/host-update.mjs

@@ -37,7 +37,8 @@ if (process.argv.includes('--check')) {
 
 const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
 
-// --knowledge <attemptFile> <lockFile>: the SessionStart knowledge self-heal worker (launched by
+// --knowledge <attemptFile> <lockFile> [--if-newer <kbDir> <checkFile> <resultFile>]: the SessionStart
+// (and MCP server timer) knowledge self-heal worker (launched by
 // session-start-update-plane.mjs under detach.mjs's TTL). Unlike the default mode below it DOES
 // update knowledge: the same argv bin/nightly-refresh.mjs runs, through the same env boundary.
 // Offline (registry unreachable) is recorded as 'offline' so the next session retries in 30 min
@@ -56,6 +57,61 @@ if (knowledgeAt >= 0) {
     } catch { /* the next session reports a launch with no outcome as a failure */ }
   };
   try {
+    // --if-newer <kbDir> <checkFile> <resultFile>: the newer-published identity check (2026-10-02). Run the
+    // INSTALLED updater's --check (one GET of the canonical releases/latest pointer, no download) and only a
+    // newer identity proceeds to the update below. Exit codes are forge-update.mjs's own: 0 current (or
+    // REFUSED: the published corpus is older — never downgrade), 10 newer, 2 network, 5 incompatible.
+    const ifNewerAt = process.argv.indexOf('--if-newer');
+    if (ifNewerAt >= 0) {
+      const path = await import('node:path');
+      const [kbDir, checkFile, resultFile] = process.argv.slice(ifNewerAt + 1);
+      const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+      const note = (fields) => {
+        try {
+          const tmp = `${checkFile}.tmp-${process.pid}`;
+          fs.writeFileSync(tmp, `${JSON.stringify({ ...(readJson(checkFile) || {}), schemaVersion: 1, ...fields, checkedAt: new Date().toISOString() })}\n`);
+          fs.renameSync(tmp, checkFile);
+        } catch { /* the next tick re-checks */ }
+      };
+      // process.exit() skips finally{}, so every early stop releases the shared lock itself.
+      const stop = () => { try { fs.rmSync(lockFile, { force: true }); } catch { /* stale-lock rule reclaims it */ } process.exit(0); };
+      const started = Date.now();
+      const check = spawnSync(process.execPath, [path.join(kbDir, 'forge-update.mjs'), '--check', '--result-file', resultFile], {
+        env: childEnvironment(), encoding: 'utf8', timeout: Number(process.env.RUVNET_CORPUS_CHECK_TIMEOUT_MS || 90_000),
+      });
+      const out = `${check.stdout || ''}\n${check.stderr || ''}`;
+      const result = readJson(resultFile);
+      const fresh = result && Date.parse(result.recordedAt || '') >= started - 1000 ? result : null;
+      const candidateTag = fresh?.candidateTag || /canonical built:\s+(\S+)/.exec(out)?.[1] || null;
+      const verdict = fresh?.currencyVerdict || /currency verdict:\s+([A-Z_]+)/.exec(out)?.[1] || null;
+      const reason = (out.split('\n').map((l) => l.trim()).filter(Boolean).find((l) => /error|refus|incompatible|fail/i.test(l)) || '').slice(0, 200);
+      // Decide by the recorded IDENTITY verdict whenever this run wrote one; the exit code only when it did
+      // not (a network failure or an incompatible release dies before recording). Measured against the real
+      // API: an install whose profile selects no stores exits 0 on UPDATE_AVAILABLE ("All stores current").
+      const newer = verdict ? ['UPDATE_AVAILABLE', 'UNKNOWN'].includes(verdict) : check.status === 10;
+      if (!newer && (verdict || check.status === 0)) {
+        note({ outcome: verdict === 'REFUSED' ? 'refused' : 'current', verdict: verdict || 'CURRENT', candidateTag, reason: '' });
+        stop();
+      }
+      if (!newer) {
+        note({ outcome: check.status === 2 ? 'offline' : check.status === 5 ? 'incompatible' : 'failed',
+          verdict: null, candidateTag, reason: reason || `check exited ${check.error ? check.error.message : check.status}` });
+        stop();
+      }
+      // Newer. Loop guard: the same target already "succeeded" within 6h yet is still not installed — do
+      // not download it again every hour; a DIFFERENT newer corpus proceeds at once.
+      const prior = readJson(attemptFile);
+      if (prior?.outcome === 'succeeded' && candidateTag && prior.targetTag === candidateTag
+        && Date.now() - Date.parse(prior.launchedAt || '') < 6 * 3_600_000) {
+        note({ outcome: 'not-converged', verdict, candidateTag, reason: 'the last automatic update to this corpus finished without installing it' });
+        stop();
+      }
+      note({ outcome: 'updating', verdict, candidateTag, reason: '' });
+      const tmp = `${attemptFile}.tmp-${process.pid}`;
+      fs.writeFileSync(tmp, `${JSON.stringify({ schemaVersion: 1, launchedAt: new Date().toISOString(), outcome: 'launched',
+        trigger: 'newer-corpus-published', targetTag: candidateTag })}\n`);
+      fs.renameSync(tmp, attemptFile);
+    }
     const probe = process.env.RUVNET_AUTO_UPDATE_PROBE_URL || 'https://registry.npmjs.org/ruvnet-brain/latest';
     let online = false;
     try { online = (await fetch(probe, { signal: AbortSignal.timeout(5_000) })).ok; } catch { /* offline */ }

package/plugin/scripts/session-start-health.mjs

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { json, exists, mtimeMs, read } from './session-start-fsutil.mjs';
 import { unmountedNotice } from './brain-location.mjs';
+import { assessMoveLeftovers } from './footprint-io.mjs';
 import {
   describeFailedRefreshRun, readNightlyRegistration, refreshHistory, updateOwnedByAgenticKit,
 } from './nightly-scheduler.mjs';
@@ -33,6 +34,15 @@ export const brainState = (env, home) => {
   return { off, since, stateDir, file };
 };
 
+// An interrupted --move-brain may hold the ONLY Brain at <home>.old-<pid>: "reinstall" there would build a
+// second, public-only Brain beside it (4.5.2). Names only; consulted only when the KB is missing or empty.
+const restoreNotice = (home) => {
+  try {
+    const lo = assessMoveLeftovers({ brainHome: path.join(home, '.cache', 'ruvnet-brain') }).find((l) => l.onlyCopy);
+    return lo ? `the Brain is not at its path — an interrupted move left the ONLY copy at ${lo.path}; restore it, do NOT reinstall: ${lo.fix}` : '';
+  } catch { return ''; }
+};
+
 export const health = (home, off) => {
   // Moved to another disk that is not plugged in: say exactly that — not "MISSING, reinstall", which
   // would re-create a fresh brain in ~/.cache over the link. A problem also stands the self-heal down.
@@ -45,8 +55,8 @@ export const health = (home, off) => {
   catch { /* absent */ }
   const absentByChoice = off && (!exists(kb) || !rvf);
   if (absentByChoice) return { problem: '', absentByChoice };
-  if (!exists(kb)) return { problem: `the brain cache directory is MISSING (${kb}) — reinstall: npx github:stuinfla/ruvnet-brain`, absentByChoice };
-  if (!rvf) return { problem: `NO vector stores (.rvf) found in ${kb} — the brain is empty; reinstall: npx github:stuinfla/ruvnet-brain --force`, absentByChoice };
+  if (!exists(kb)) return { problem: restoreNotice(home) || `the brain cache directory is MISSING (${kb}) — reinstall: npx github:stuinfla/ruvnet-brain`, absentByChoice };
+  if (!rvf) return { problem: restoreNotice(home) || `NO vector stores (.rvf) found in ${kb} — the brain is empty; reinstall: npx github:stuinfla/ruvnet-brain --force`, absentByChoice };
   if (!exists(path.join(kb, 'node_modules', '@xenova', 'transformers', 'package.json'))) {
     return { problem: `reader dependencies are MISSING (node_modules gone) — every search WILL fail. Fix: cd ${kb} && npm i`, absentByChoice };
   }
@@ -78,6 +88,10 @@ export const autoUpdatePaths = (brainHome) => ({
   attemptFile: path.join(brainHome, 'auto-update.json'),
   lockFile: path.join(brainHome, 'auto-update.lock'),
   logFile: path.join(brainHome, '.last-auto-update-knowledge.log'),
+  // The newer-published identity check (2026-10-02): its own throttle + outcome record, never the update
+  // attempt file (a check is not an update; it must not reset the 6h retry or read as an abandoned launch).
+  checkFile: path.join(brainHome, 'corpus-check.json'),
+  checkResultFile: path.join(brainHome, '.last-kb-check-result.json'),
 });
 export const AUTO_UPDATE_LOCK_STALE_MS = 35 * 60_000; // detach TTL (30 min) + slack
 
@@ -95,7 +109,7 @@ export const knowledgeFacts = ({ env = process.env, home, now = Date.now() } = {
   const provenWithin = (h) => Boolean((history.lastSuccess && hours(history.lastSuccess.at) <= h)
     || (check?.currencyVerdict === 'CURRENT' && Number.isFinite(checkMs) && hours(checkMs) <= h));
   return { brainHome, kbDir, source, builtMs, history, hours, provenWithin, auto,
-    attempt: json(auto.attemptFile),
+    attempt: json(auto.attemptFile), corpusCheck: json(auto.checkFile),
     lockMs: Date.parse(json(auto.lockFile)?.at || '') || mtimeMs(auto.lockFile) };
 };
 
@@ -126,6 +140,21 @@ export const autoUpdateOptOut = ({ env = process.env, home, facts }) => {
   return '';
 };
 
+/**
+ * A newer corpus is PUBLISHED and not yet installed — decided by identity, never by age: the last
+ * recorded --if-newer check found a release whose tag is newer (UPDATE_AVAILABLE, or UNKNOWN when the
+ * installed tree carries no generation stamp) and that tag is not what SOURCE.json now names. A check
+ * recorded before the update landed therefore stops reading as pending the moment B is installed.
+ */
+export const newerCorpusPending = (facts) => {
+  const c = facts.corpusCheck;
+  if (!c?.candidateTag || !['UPDATE_AVAILABLE', 'UNKNOWN'].includes(c.verdict)) return null;
+  const installed = [facts.source?.corpusReleaseTag, facts.source?.releaseTag].filter(Boolean);
+  if (installed.includes(c.candidateTag)) return null;
+  return { tag: c.candidateTag, installed: installed[0] || null, checkedAt: c.checkedAt || c.launchedAt || null, outcome: c.outcome };
+};
+const shortTag = (tag) => (tag && tag.length > 28 ? `${tag.slice(0, 26)}…` : tag || 'unknown');
+
 export const knowledgeCurrency = ({ env = process.env, home, now = Date.now(), windowHours = 48 } = {}) => {
   const facts = knowledgeFacts({ env, home, now });
   const { brainHome, builtMs, history, hours, attempt } = facts;
@@ -142,6 +171,16 @@ export const knowledgeCurrency = ({ env = process.env, home, now = Date.now(), w
     && !(history.latest && history.latest.at >= launchedMs);
   const failing = latest?.status === 'FAILED' || autoFailed;
   const ageKnown = Number.isFinite(builtMs);
+  const pending = newerCorpusPending(facts);
+  if (!failing && pending && (proven || (ageKnown && hours(builtMs) <= windowHours))) {
+    const optOut = autoUpdateOptOut({ env, home, facts });
+    const what = autoRunning ? 'the automatic update is installing it now'
+      : optOut ? `automatic update is off (${optOut}). Fix: npx ruvnet-brain@latest --update`
+        : pending.outcome === 'not-converged' ? 'an automatic update to it finished without installing it; it retries within 6h'
+          : 'the automatic update installs it in the background';
+    return `${KNOWLEDGE_LINE_PREFIX}UPDATE PENDING] a newer corpus ${shortTag(pending.tag)} is published `
+      + `(this machine has ${shortTag(pending.installed)}, built ${ageKnown ? age(builtMs) : 'at an UNKNOWN time'}); ${what}.`;
+  }
   if (!failing && proven) return '';
   if (!failing && ageKnown && hours(builtMs) <= windowHours) return '';
   const kit = agenticKitUpdates({ home, facts });

package/plugin/scripts/session-start-update-plane.mjs

@@ -13,16 +13,30 @@ import { inventoryFootprint } from './brain-footprint.mjs';
 import { confirm, footprintAlarm } from './brain-confirmation.mjs';
 
 /**
- * KNOWLEDGE SELF-HEAL (owner invariant 2026-09-30: no brain may ever be more than 48h old). The
- * nightly scheduler is opt-in and can silently never register, so this does not depend on it: when
- * a session starts and nothing proves the knowledge current inside 24h, launch ONE detached, bounded
- * `npx ruvnet-brain@latest --update --no-nightly-prompt` (the exact argv bin/nightly-refresh.mjs
- * runs) through the existing host-update.mjs credential boundary and detach.mjs TTL supervisor.
- * Per machine (all state under brainHome), at most one launch per 6h (30 min after an offline
- * probe), never while a refresh lock or another launch is live, never blocks (spawn + unref, no
- * wait). The outcome is recorded by the worker and spoken by the NEXT session's knowledge line.
+ * KNOWLEDGE SELF-HEAL (owner invariant 2026-09-30: no brain may ever be more than 48h old) AND
+ * NEWER-PUBLISHED CHECK (owner requirement 2026-10-02: "all accounts auto update anytime a new corpus of
+ * knowledge happens"). Two triggers, ONE updater:
+ *   • 'update' — nothing proves the knowledge current inside 24h: launch the detached, bounded
+ *     `npx ruvnet-brain@latest --update --no-nightly-prompt` (the exact argv bin/nightly-refresh.mjs runs)
+ *     through host-update.mjs's credential boundary and detach.mjs's TTL supervisor. At most one launch
+ *     per 6h (30 min after an offline probe).
+ *   • 'check' — the knowledge is fresh BY AGE, but age never says whether something newer was published
+ *     (measured: v4.4.1 stayed live ~13h after v4.5.0 shipped). At most once per checkMinutes per machine,
+ *     the same detached worker first runs the installed `kb/forge-update.mjs --check` (one GET of the
+ *     canonical releases/latest pointer, no download) and proceeds to the SAME update only on a newer
+ *     identity — forge-update's currencyVerdict(): UPDATE_AVAILABLE/UNKNOWN; CURRENT and REFUSED (the
+ *     published corpus is older: never downgrade) stop there.
+ * Per machine (all state under brainHome), never while a refresh lock or another launch is live, never
+ * blocks (spawn + unref, no wait). SessionStart calls this; so does the long-lived MCP server on a timer
+ * (plugin/mcp/server.mjs, announce:false so it never consumes the once-per-session line). The outcome is
+ * recorded by the worker and spoken by the NEXT session's knowledge line.
  */
-export const AUTO_UPDATE_POLICY = Object.freeze({ staleHours: 24, retryHours: 6, offlineRetryMinutes: 30, ttlSec: 1800 });
+export const AUTO_UPDATE_POLICY = Object.freeze({ staleHours: 24, retryHours: 6, offlineRetryMinutes: 30, ttlSec: 1800, checkMinutes: 60 });
+export const corpusCheckMinutes = (env = {}) => {
+  const raw = env.RUVNET_CORPUS_CHECK_MINUTES;
+  const n = Number(raw);
+  return raw !== undefined && raw !== '' && Number.isFinite(n) && n >= 0 ? n : AUTO_UPDATE_POLICY.checkMinutes;
+};
 
 const writeJsonAtomic = (file, value) => {
   const tmp = `${file}.tmp-${process.pid}`;
@@ -30,14 +44,17 @@ const writeJsonAtomic = (file, value) => {
   catch { try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ } return false; }
 };
 
-export const knowledgeAutoUpdate = ({ env, home, now, hookDir, emit = () => {}, spawnFn = spawn }) => {
+export const knowledgeAutoUpdate = ({ env, home, now, hookDir, emit = () => {}, spawnFn = spawn, announce = true }) => {
   const facts = knowledgeFacts({ env, home, now });
-  const { attemptFile, lockFile, logFile } = facts.auto;
+  const { attemptFile, lockFile, logFile, checkFile, checkResultFile } = facts.auto;
   const attempt = facts.attempt;
   const hoursAgo = (iso) => (now - Date.parse(iso || '')) / 3_600_000;
-  if (attempt?.outcome === 'succeeded' && !attempt.reported) {
+  if (announce && attempt?.outcome === 'succeeded' && !attempt.reported) {
     const built = facts.builtMs;
-    const tag = facts.source?.releaseTag ? `corpus ${facts.source.releaseTag}` : 'the latest corpus';
+    // A corpus-only release carries its identity in corpusReleaseTag; releaseTag is the code release beside it.
+    const id = facts.source?.corpusReleaseTag || facts.source?.releaseTag;
+    const short = id && id.length > 28 ? `${id.slice(0, 26)}…` : id;
+    const tag = !id ? 'the latest corpus' : id.startsWith('corpus-') ? short : `corpus ${short}`;
     emit(`${KNOWLEDGE_LINE_PREFIX}UPDATED] automatic update finished ${Math.round(hoursAgo(attempt.finishedAt))}h ago: ${tag}, `
       + `knowledge base built ${Number.isFinite(built) ? `${Math.round(facts.hours(built))}h ago` : 'at an UNKNOWN time'}.`);
     writeJsonAtomic(attemptFile, { ...attempt, reported: true });
@@ -46,7 +63,14 @@ export const knowledgeAutoUpdate = ({ env, home, now, hookDir, emit = () => {},
   if (optOut) return { launched: false, why: optOut };
   const fresh = facts.provenWithin(AUTO_UPDATE_POLICY.staleHours)
     || (Number.isFinite(facts.builtMs) && facts.hours(facts.builtMs) <= AUTO_UPDATE_POLICY.staleHours);
-  if (fresh) return { launched: false, why: 'fresh' };
+  const mode = fresh ? 'check' : 'update';
+  if (mode === 'check') {
+    const lastCheck = Date.parse(facts.corpusCheck?.launchedAt || '');
+    const sinceCheck = now - lastCheck;
+    if (Number.isFinite(lastCheck) && sinceCheck >= 0 && sinceCheck < corpusCheckMinutes(env) * 60_000) {
+      return { launched: false, why: 'fresh' };
+    }
+  }
   // A nightly or manual --update holds this lock (kb/refresh-run.mjs refreshLockPath, duplicated here
   // because the plugin payload cannot import kb/); --update would refuse anyway, this saves the launch.
   if (exists(path.join(path.dirname(facts.kbDir), `.${path.basename(facts.kbDir)}.refresh-run.lock`))) {
@@ -54,8 +78,11 @@ export const knowledgeAutoUpdate = ({ env, home, now, hookDir, emit = () => {},
   }
   const since = hoursAgo(attempt?.launchedAt);
   const retryHours = attempt?.outcome === 'offline' ? AUTO_UPDATE_POLICY.offlineRetryMinutes / 60 : AUTO_UPDATE_POLICY.retryHours;
-  if (since >= 0 && since < retryHours) return { launched: false, why: 'throttled' };
-  // Cross-process: exactly one session wins the O_EXCL create; a lock older than the TTL is stale.
+  // A SUCCEEDED update never delays the next newer-published check: a different, newer corpus may proceed
+  // at once. The same target is not re-run within 6h (host-update.mjs --if-newer's 'not-converged' guard).
+  const retryBlocks = !(mode === 'check' && attempt?.outcome === 'succeeded');
+  if (retryBlocks && since >= 0 && since < retryHours) return { launched: false, why: 'throttled' };
+  // Cross-process: exactly one session (or MCP server timer) wins the O_EXCL create; a stale lock is reclaimed.
   const claim = () => { try { fs.writeFileSync(lockFile, `${JSON.stringify({ pid: process.pid, at: new Date(now).toISOString() })}\n`, { flag: 'wx' }); return true; } catch { return false; } };
   if (!claim()) {
     const lockMs = Date.parse(json(lockFile)?.at || '') || mtimeMs(lockFile);
@@ -63,20 +90,26 @@ export const knowledgeAutoUpdate = ({ env, home, now, hookDir, emit = () => {},
     try { fs.rmSync(lockFile, { force: true }); } catch { /* raced */ }
     if (!claim()) return { launched: false, why: 'locked' };
   }
-  writeJsonAtomic(attemptFile, { schemaVersion: 1, launchedAt: new Date(now).toISOString(), outcome: 'launched' });
+  const at = new Date(now).toISOString();
+  // A check is not an update attempt: it must not reset the 6h retry or read as an abandoned launch.
+  if (mode === 'update') writeJsonAtomic(attemptFile, { schemaVersion: 1, launchedAt: at, outcome: 'launched' });
+  else writeJsonAtomic(checkFile, { ...(facts.corpusCheck || {}), schemaVersion: 1, launchedAt: at, outcome: 'checking' });
   try {
     const child = spawnFn(process.execPath, [path.join(hookDir, 'detach.mjs'), String(AUTO_UPDATE_POLICY.ttlSec), logFile,
-      process.execPath, path.join(hookDir, 'host-update.mjs'), '--knowledge', attemptFile, lockFile],
+      process.execPath, path.join(hookDir, 'host-update.mjs'), '--knowledge', attemptFile, lockFile,
+      ...(mode === 'check' ? ['--if-newer', facts.kbDir, checkFile, checkResultFile] : [])],
     { detached: true, stdio: 'ignore', env, windowsHide: true });
     child.on?.('error', () => {});
     child.unref?.();
   } catch (error) {
-    writeJsonAtomic(attemptFile, { schemaVersion: 1, launchedAt: new Date(now).toISOString(), outcome: 'failed',
-      code: null, reason: `could not launch: ${error.message}`, finishedAt: new Date(now).toISOString() });
+    const reason = `could not launch: ${error.message}`;
+    if (mode === 'update') {
+      writeJsonAtomic(attemptFile, { schemaVersion: 1, launchedAt: at, outcome: 'failed', code: null, reason, finishedAt: at });
+    } else writeJsonAtomic(checkFile, { schemaVersion: 1, launchedAt: at, outcome: 'failed', reason, checkedAt: at });
     try { fs.rmSync(lockFile, { force: true }); } catch { /* ignore */ }
-    return { launched: false, why: 'launch failed' };
+    return { launched: false, why: 'launch failed', mode };
   }
-  return { launched: true, why: 'stale' };
+  return { launched: true, why: mode === 'check' ? 'checking for a newer published corpus' : 'stale', mode };
 };
 
 /**
@@ -179,7 +212,9 @@ export const heartbeat = ({ env, hookDir, stateDir, home, running, seedDispatche
   const kbDir = path.join(home, '.cache', 'ruvnet-brain', 'kb');
   if (pref === 'yes' && exists(path.join(kbDir, 'forge-update.mjs'))) {
     const kbLog = path.join(stateDir, '.last-kb-check.log');
-    if (/\bBEHIND\b/.test(read(kbLog))) {
+    // Only when the automatic knowledge update is OFF on this machine: otherwise it IS applied (signature
+    // verified first) and the knowledge line says so — this notice would be a false statement.
+    if (/\bBEHIND\b/.test(read(kbLog)) && autoUpdateOptOut({ env, home, facts: knowledgeFacts({ env, home, now }) })) {
       emit('[RuvNet Brain — a newer knowledge bundle is available. It is signed (Ed25519) and the updater verifies that signature before extracting anything. We do NOT auto-apply it: applying replaces executable tool files, which is your call. To update: npx ruvnet-brain@latest --update]');
     }
     // S2 (ONE CURRENCY VERDICT): --result-file records the SAME structured verdict --check/--apply