ruvnet-brain 4.3.40 → 4.4.0

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.0 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.4.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)
 
 **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,8 @@ 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 { runHostCli, waitForHostCli } from '../scripts/host-cli.mjs';
 import {
   writeInstalledRuntimeIdentity, recordCorpusTransportIdentity, isCorpusReleaseTag, rejectedReleasePath,
 } from '../kb/corpus-release-identity.mjs';
@@ -228,6 +231,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 +1281,33 @@ 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 };
+}
+
 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 +1425,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 +1444,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']);
 
@@ -1856,13 +1877,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 };
@@ -2754,7 +2778,9 @@ async function doctor() {
   let hostConvergence = { healthy: true, state: 'not-recorded' };
   if (fs.existsSync(convergencePath)) {
     try {
-      hostConvergence = classifyHostConvergence(JSON.parse(fs.readFileSync(convergencePath, 'utf8')));
+      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}`);
       else {
         warn(`host convergence incomplete: ${hostConvergence.state}`);
@@ -3274,6 +3300,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 +3408,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],
@@ -3455,12 +3494,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 +3507,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({
@@ -3508,7 +3571,9 @@ export function classifyHostConvergence(receipt, expectedVersion = PACKAGE_VERSI
   }
   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` };
   }
   return { healthy: true, state: 'channels-converged' };
 }
@@ -3587,6 +3652,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 +3725,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
@@ -4951,7 +5035,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}`);
     }

package/kb/update-storage-transaction.mjs

@@ -258,7 +258,23 @@ export function recoverIncompleteStorageTransactions(liveDir, { removeTree = rem
     const phaseFiles = fs.readdirSync(receipts).filter((name) => /^\d{3}-[A-Z_]+\.json$/.test(name)).sort();
     if (!phaseFiles.length) throw new Error(`storage transaction receipt is empty: ${receipts}`);
     const latest = JSON.parse(fs.readFileSync(path.join(receipts, phaseFiles.at(-1)), 'utf8'));
-    if (['NOOP', 'COMMITTED', 'ROLLED_BACK'].includes(latest.state)) continue;
+    if (['NOOP', 'COMMITTED', 'ROLLED_BACK'].includes(latest.state)) {
+      // A quarantined unsealed candidate is kept for ONE full update cycle, then released on the next
+      // run — but only if its bytes are exactly what was sealed when it was quarantined.
+      const quarantine = latest.quarantinedUnsealedCandidate;
+      if (latest.state === 'ROLLED_BACK' && quarantine && latest.quarantineReclaimed !== true
+        && path.resolve(quarantine) === transactionPaths(live, transactionId).failed) {
+        const unchanged = !fs.existsSync(quarantine) || (() => {
+          try { requireDigest(quarantine, latest.quarantineIdentity, 'quarantined candidate'); return true; } catch { return false; }
+        })();
+        if (unchanged) {
+          removeIfPresent(quarantine);
+          appendRecoveryReceipt(receipts, 'ROLLED_BACK', { quarantineReclaimed: true,
+            reason: 'released the quarantined unsealed candidate one update cycle later (bytes unchanged)' });
+        }
+      }
+      continue;
+    }
     if (latest.state === 'RECOVERY_REQUIRED') throw new Error(`storage transaction requires manual recovery: ${transactionId}`);
     const paths = latest.paths;
     const expectedPaths = transactionPaths(live, transactionId);
@@ -273,12 +289,22 @@ export function recoverIncompleteStorageTransactions(liveDir, { removeTree = rem
     try {
       // Validate every retained tree before any rename or deletion. A receipt owns
       // paths, but cannot authorize discarding bytes added after the process died.
-      if (fs.existsSync(paths.candidate)) requireDigest(paths.candidate, latest.candidate, 'interrupted candidate');
+      // A kill DURING candidate building (the long phase: copy, private restore, guard) leaves a candidate
+      // that was never sealed, so no receipt can vouch for its bytes. Refusing made every later update
+      // fail forever; deleting would discard bytes nothing proved disposable. It is QUARANTINED instead:
+      // renamed intact to this transaction's `failed` path, named in the receipt, and live (proved equal
+      // to the prior identity) stays in service.
+      const unsealedCandidate = fs.existsSync(paths.candidate) && !latest.candidate?.sha256
+        && ['LOCKED', 'CANDIDATE_BUILDING'].includes(latest.state);
+      if (fs.existsSync(paths.candidate) && !unsealedCandidate) requireDigest(paths.candidate, latest.candidate, 'interrupted candidate');
       if (fs.existsSync(paths.rollback)) requireDigest(paths.rollback, prior, 'interrupted rollback');
       if (fs.existsSync(paths.failed)) throw new Error('interrupted failed tree has no safe recovery disposition');
       if (['LOCKED', 'CANDIDATE_BUILDING', 'CANDIDATE_VERIFIED'].includes(latest.state)) {
         requireDigest(live, prior, 'interrupted live');
-        removeIfPresent(paths.candidate);
+        if (unsealedCandidate) {
+          assertDirectory(paths.candidate, 'unsealed candidate');
+          fs.renameSync(paths.candidate, paths.failed);
+        } else removeIfPresent(paths.candidate);
       } else if (latest.state === 'OLD_RENAME_STARTED') {
         const hasLive = fs.existsSync(live);
         const hasRollback = fs.existsSync(paths.rollback);
@@ -324,10 +350,12 @@ export function recoverIncompleteStorageTransactions(liveDir, { removeTree = rem
         continue;
       } else throw new Error(`unsupported interrupted state ${latest.state}`);
       const delta = storageDelta(paths, { prior, candidate: latest.candidate || null });
+      const quarantined = unsealedCandidate
+        ? { quarantinedUnsealedCandidate: paths.failed, quarantineIdentity: identitySummary(treeIdentity(paths.failed)) } : {};
       appendRecoveryReceipt(receipts, 'ROLLED_BACK', { terminalVerdict: 'interrupted-run-restored', prior,
-        storageDelta: delta, reason: `recovered interrupted ${latest.state} transaction before new work` });
+        storageDelta: delta, reason: `recovered interrupted ${latest.state} transaction before new work`, ...quarantined });
       recovered.push({ transactionId, from: latest.state, terminalVerdict: 'interrupted-run-restored',
-        storageDelta: delta });
+        storageDelta: delta, ...quarantined });
     } catch (error) {
       appendRecoveryReceipt(receipts, 'RECOVERY_REQUIRED', { terminalVerdict: 'recovery-required', prior,
         reason: error.message });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.40",
+  "version": "4.4.0",
   "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.3.40",
+  "version": "4.4.0",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/hooks/codex-hooks.json

@@ -92,8 +92,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 session-snapshot SessionEnd",
-            "timeout": 10
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 2500 session-snapshot SessionEnd",
+            "timeout": 3
           }
         ]
       }

package/plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint, ground-ruvnet grounding injection, and a capacity-aware context hint for clearly large independent work. The capacity hook uses bounded CPU/memory-pressure evidence, never starts agents, and tells the coordinator to check live tools and clamp to the runtime cap; it is not user-facing speech. ground-ruvnet remains a directive to the model, not speech — ADR-040 §Amendment 2026-09-11. PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate. grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if no search_ruvnet call was recorded since. Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors — the Stop stdout envelopes are advisory at the shim boundary but keep the agent working.",
+  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint, ground-ruvnet grounding injection, and a capacity-aware context hint for clearly large independent work. The capacity hook uses bounded CPU/memory-pressure evidence, never starts agents, and tells the coordinator to check live tools and clamp to the runtime cap; it is not user-facing speech. ground-ruvnet remains a directive to the model, not speech — ADR-040 §Amendment 2026-09-11. PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate. grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if the final answer asserts a rUv capability and no search_ruvnet call was recorded since. Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors — the Stop stdout envelopes are advisory at the shim boundary but keep the agent working.",
   "hooks": {
     "SessionStart": [
       {

package/plugin/scripts/capability-registry.mjs

@@ -451,11 +451,11 @@ export const CAPABILITIES = [
       if (d.unreadable) {
         const locked = /lock|busy|writer/i.test(String(d.unreadable));
         return row(STATE.UNKNOWN, locked
-          ? `the memory store is currently held by another process (${d.unreadable}) — that is a passing lock, not a fault; re-checking in a moment should clear it`
+          ? `could not read the memory store: another process is holding it (${d.unreadable}) — that is a passing lock, not a fault; re-checking in a moment should clear it`
           : `the memory store could not be read (${d.unreadable}) — this is not a transient lock, so re-checking will not clear it; the store or its journal files need attention before distillation state can be established`);
       }
-      if (d.schemaless) return row(STATE.UNKNOWN, 'the store exists but has no memory_entries table (pre-AgentDB schema, never initialised) — nothing to distill yet, and nothing is broken');
-      if (typeof d.total !== 'number') return row(STATE.UNKNOWN, 'the store opened but returned no countable rows — distillation state not established');
+      if (d.schemaless) return row(STATE.UNKNOWN, 'cannot measure distillation: the store exists but has no memory_entries table (pre-AgentDB schema, never initialised) — nothing to distill yet, and nothing is broken');
+      if (typeof d.total !== 'number') return row(STATE.UNKNOWN, 'the store opened but returned no countable rows — distillation state could not be established');
 
       if (d.total === 0) return row(STATE.ABSENT, 'the memory store is empty, so there is nothing to distill yet');
       if (d.learns) return row(STATE.ON, `${d.patterns} reusable patterns distilled from ${d.real} memories (${(d.cover * 100).toFixed(1)}% embedded)`);

package/plugin/scripts/codex-hook-wrapper.mjs

@@ -60,7 +60,7 @@ const blockingHooks = new Set([
 const DETACHED_HOOKS = new Set(['learn-flush']);
 
 /** THE BUDGET IS DERIVED FROM WHAT THE HOOK MEASURABLY COSTS, never from what looks tidy. */
-function timeoutFor(hookId) {
+function timeoutFor(hookId, event = '') {
   const override = Number(process.env.RUVNET_CODEX_HOOK_TIMEOUT_MS);
   if (Number.isFinite(override) && override > 0) return override;
   // decision-gate's own internal budget is 4000ms (RUVNET_DECISION_BUDGET_MS) and it is allowed to
@@ -75,6 +75,11 @@ function timeoutFor(hookId) {
   if (hookId === 'ground-ruvnet' || hookId === 'unprompted-speech' || hookId === 'continuation-gate') {
     return 8_500;
   }
+  // SessionEnd is hard-capped at 3s by the host (see DETACHED_HOOKS above) and the codex-hooks.json
+  // launcher kills this wrapper at 2500ms. A 4000ms budget here was a number nobody would ever reach:
+  // the body planned for 8s and was SIGKILLed mid-write. 2200ms leaves the launcher its margin, and the
+  // body receives it as RUVNET_CODEX_BUDGET_MS (below) so it can save the new snapshot first.
+  if (event === 'SessionEnd') return 2_200;
   return 4_000;
 }
 
@@ -193,7 +198,7 @@ if (DETACHED_HOOKS.has(hookId)) {
   process.exit(0);
 }
 
-const budgetMs = timeoutFor(hookId);
+const budgetMs = timeoutFor(hookId, process.argv[3] || '');
 const result = spawnSync(process.execPath, [adapter, ...process.argv.slice(2)], {
   input,
   encoding: 'utf8',

package/plugin/scripts/design-wall.sh

@@ -29,6 +29,7 @@ INPUT=""
 # exactly why a hook that CAN hang forever survives unnoticed. -t bounds the wait, and the string
 # is truncated AFTER the loop because a hook payload is one line with no newline, so `read` hands
 # the whole thing back at once and a per-iteration cap never fires.
+_l=""   # set -u: a read that times out before any byte leaves _l unset ("unbound variable" on stderr)
 while IFS= read -r -t 2 _l; do
   INPUT+="$_l"
   [ ${#INPUT} -ge 65536 ] && break

package/plugin/scripts/ground-before-write.sh

@@ -43,6 +43,7 @@ INPUT=""
 # exactly why a hook that CAN hang forever survives unnoticed. -t bounds the wait, and the string
 # is truncated AFTER the loop because a hook payload is one line with no newline, so `read` hands
 # the whole thing back at once and a per-iteration cap never fires.
+_l=""   # set -u: a read that times out before any byte leaves _l unset ("unbound variable" on stderr)
 while IFS= read -r -t 2 _l; do
   INPUT+="$_l"
   [ ${#INPUT} -ge 65536 ] && break