ruvnet-brain 4.3.19 → 4.3.20

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.19 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.19-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.20 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.20-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **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

@@ -673,8 +673,8 @@ export async function unzipInto(zipPath, cacheDir, sourceDir = null) {
  * Registry reachability identifies candidates; it is not deletion proof. Claude freezes
  * CLAUDE_PLUGIN_ROOT at session start, so an unregistered generation can remain live until that
  * session exits. Modern roots expose `.in_use` PID-incarnation leases. Live or ambiguous leases
- * retain the complete root; dead leases are collected. Legacy roots without the protocol receive
- * a 14-day compatibility grace.
+ * retain the complete root; dead leases are collected. Legacy roots without the protocol are
+ * retained indefinitely because a frozen host session is not observable without a lease.
  *
  * WHAT MAKES DELETION SAFE HERE, since this removes directories from someone's machine:
  *   • The registry is the ONLY authority. Unreadable, missing, or naming no ruvnet-brain install →
@@ -786,7 +786,11 @@ export function prunePluginGenerations({
       continue;
     }
 
-    if (!leaseCapable && now() - orphanedAt < graceMs) continue;
+    if (!leaseCapable) {
+      if (now() - orphanedAt < graceMs) continue;
+      cleanupBlocked.push({ version: candidate.version, reason: 'legacy generation has no liveness lease; refusing destructive cleanup' });
+      continue;
+    }
     let safeToReap = true;
     for (const leaseName of leaseNames) {
       const leasePath = path.join(leaseDir, leaseName);
@@ -2915,29 +2919,82 @@ function missingUpdaterHelp(kbDir) {
   console.error(`  — the current bundle ships forge-update.mjs; then this command will work.`);
 }
 
-function acquireHostConvergenceLock(lockPath) {
-  try {
-    fs.mkdirSync(lockPath);
-    fs.writeFileSync(path.join(lockPath, 'owner.json'), JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
-    return { acquired: true, release: () => fs.rmSync(lockPath, { recursive: true, force: true }) };
-  } catch (error) {
-    if (error?.code !== 'EEXIST') return { acquired: false, error: error.message };
+export function acquireHostConvergenceLock(lockPath, {
+  staleMs = 5 * 60 * 1000,
+  now = () => Date.now(),
+  processAlive = (pid, owner) => {
+    if (owner?.host && owner.host !== os.hostname()) return true;
+    try { process.kill(pid, 0); return true; }
+    catch (error) { return error?.code !== 'ESRCH'; }
+  },
+} = {}) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  const token = crypto.randomBytes(16).toString('hex');
+  const owner = {
+    pid: process.pid,
+    host: os.hostname(),
+    token,
+    startedAt: new Date(now()).toISOString(),
+  };
+  const publish = () => {
+    try {
+      // mkdir is the exclusive operation. The owner write follows it, but an incomplete
+      // directory is treated as busy until the stale threshold; no contender may reclaim it in
+      // that publication window. This avoids rename-over-empty-directory replacement on macOS.
+      fs.mkdirSync(lockPath, { recursive: false });
+      fs.writeFileSync(path.join(lockPath, 'owner.json'), JSON.stringify(owner), { flag: 'wx', mode: 0o600 });
+      return true;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      return false;
+    }
+  };
+  const release = () => {
+    const quarantine = `${lockPath}.release-${process.pid}-${token}`;
     try {
-      const owner = JSON.parse(fs.readFileSync(path.join(lockPath, 'owner.json'), 'utf8'));
-      if (Number.isInteger(owner.pid) && owner.pid !== process.pid) {
-        try { process.kill(owner.pid, 0); return { acquired: false, error: `another host synchronization is running (pid ${owner.pid})` }; }
-        catch (probeError) { if (probeError?.code !== 'ESRCH') return { acquired: false, error: 'another host synchronization owns the lock' }; }
+      const current = JSON.parse(fs.readFileSync(path.join(lockPath, 'owner.json'), 'utf8'));
+      if (current?.token !== token) return false;
+      fs.renameSync(lockPath, quarantine);
+      const moved = JSON.parse(fs.readFileSync(path.join(quarantine, 'owner.json'), 'utf8'));
+      if (moved?.token !== token) {
+        try { fs.renameSync(quarantine, lockPath); } catch { /* preserve evidence if another writer won */ }
+        return false;
       }
-    } catch { /* an incomplete lock is safe to reclaim */ }
-    fs.rmSync(lockPath, { recursive: true, force: true });
+      fs.rmSync(quarantine, { recursive: true, force: true });
+      return true;
+    } catch { return false; }
+  };
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      if (publish()) return { acquired: true, release };
+    } catch (error) {
+      return { acquired: false, error: error.message };
+    }
+
+    let existing;
+    let lockAge = 0;
+    try {
+      const stat = fs.statSync(lockPath);
+      lockAge = Math.max(0, now() - stat.mtimeMs);
+      existing = JSON.parse(fs.readFileSync(path.join(lockPath, 'owner.json'), 'utf8'));
+    } catch { /* an incomplete lock is handled below, with a grace period */ }
+    if (existing && Number.isInteger(existing.pid) && processAlive(existing.pid, existing)) {
+      return { acquired: false, error: `another host synchronization is running (pid ${existing.pid})` };
+    }
+    if (!existing && lockAge < staleMs) {
+      return { acquired: false, error: 'another host synchronization is publishing its lock' };
+    }
+    const quarantine = `${lockPath}.reclaim-${process.pid}-${token}-${attempt}`;
     try {
-      fs.mkdirSync(lockPath);
-      fs.writeFileSync(path.join(lockPath, 'owner.json'), JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
-      return { acquired: true, release: () => fs.rmSync(lockPath, { recursive: true, force: true }) };
-    } catch (retryError) {
-      return { acquired: false, error: retryError.message };
+      fs.renameSync(lockPath, quarantine);
+      fs.rmSync(quarantine, { recursive: true, force: true });
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+      return { acquired: false, error: `host synchronization lock changed concurrently: ${error.message}` };
     }
   }
+  return { acquired: false, error: 'host synchronization lock changed concurrently' };
 }
 
 export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
@@ -2995,9 +3052,18 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   if (!fs.existsSync(apply)) return fail({ error: 'Stable Spine updater missing from package' });
   const applied = runStableSpine(apply);
   const okApplied = !applied.error && applied.status === 0;
+  const codexReceipt = {
+    state: results.codex?.action === 'disabled' ? 'disabled' : (results.codexHost?.host ? 'ready' : 'absent'),
+    version: results.codex?.version || null,
+  };
+  if (results.codex?.restartRequired === true) {
+    codexReceipt.restartRequired = true;
+    codexReceipt.sessionSafety = results.codex.sessionSafety || null;
+    codexReceipt.sessionSafetyReason = results.codex.sessionSafetyReason || null;
+  }
   if (okApplied) {
     // ISSUE #153 — a running host may freeze an old plugin root. Reclaim only generations whose
-    // modern leases prove no live consumer, or legacy generations past the compatibility grace.
+    // modern leases prove no live consumer; legacy roots without that proof stay on disk.
     try {
       const gens = prunePluginGenerations({ apply: true });
       if (gens.retired?.length) {
@@ -3028,7 +3094,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
         verifiedAt: new Date().toISOString(),
         hosts: {
           claude: { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null },
-          codex: { state: results.codex?.action === 'disabled' ? 'disabled' : (results.codexHost?.host ? 'ready' : 'absent'), version: results.codex?.version || null },
+          codex: codexReceipt,
         },
         consoleRuntime: results.consoleRuntime,
       }, null, 2));
@@ -3043,7 +3109,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
     desiredVersion: PACKAGE_VERSION,
     hosts: {
       claude: { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null },
-      codex: { state: results.codex?.action === 'disabled' ? 'disabled' : (results.codexHost?.host ? 'ready' : 'absent'), version: results.codex?.version || null },
+      codex: codexReceipt,
     },
     consoleRuntime: results.consoleRuntime,
   });
@@ -3061,7 +3127,11 @@ export function classifyHostConvergence(receipt, expectedVersion = PACKAGE_VERSI
   }
   const hostStates = Object.values(receipt.hosts || {});
   const badHost = hostStates.find((host) => !['ready', 'disabled', 'absent'].includes(host?.state)
-    || (host.state === 'ready' && !versionSatisfies(host.version, expectedVersion)));
+    || (host.state === 'ready' && !versionSatisfies(host.version, expectedVersion))
+    || (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' };

package/package.json

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

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

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.3.19",
+  "version": "4.3.20",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

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

@@ -248,6 +248,19 @@ const announceVersion = ({ running, off, stateDir, consoleInvoke, emit }) => {
   write(announced, `${running}\n`);
 };
 
+const compareVersions = (a, b) => {
+  const left = String(a).split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+  const right = String(b).split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const x = left[i] ?? 0;
+    const y = right[i] ?? 0;
+    if (x === y) continue;
+    if (typeof x === 'number' && typeof y === 'number') return x - y;
+    return String(x) < String(y) ? -1 : 1;
+  }
+  return 0;
+};
+
 const stableSpine = ({ env, hookDir, stateDir, home, pluginVersion, emit, now }) => {
   const activeFile = path.join(stateDir, 'active.json');
   const stamp = path.join(stateDir, '.last-update-check');
@@ -270,7 +283,11 @@ const stableSpine = ({ env, hookDir, stateDir, home, pluginVersion, emit, now })
     }
   } else {
     const active = json(activeFile);
-    if (active?.shellChanged && pluginVersion && active.version && active.version !== pluginVersion) {
+    const shellBoundary = active?.shellChangedAtVersion;
+    const shellChangedBeforeHost = shellBoundary && pluginVersion
+      ? compareVersions(pluginVersion, shellBoundary) < 0
+      : false;
+    if ((active?.shellChanged || shellChangedBeforeHost) && pluginVersion && active.version && active.version !== pluginVersion) {
       emit(`[RuvNet Brain — v${active.version} changed boot-level declarations (the rare case); this session booted v${pluginVersion}'s]`);
       const host = env.RUVNET_HOOK_HOST || 'claude';
       const convergence = json(path.join(stateDir, 'host-convergence.json'));
@@ -371,6 +388,8 @@ export async function runSessionStart({
       || s.startsWith('[RuvNet Brain — grounding not yet PROVEN')
       || s.startsWith('The last check (')
       || s.startsWith('[RuvNet Brain — update available')
+      || s.startsWith('[RuvNet Brain — v')
+      || s.startsWith('Tell the user ONE line: "🧠 RuvNet Brain v')
       || s.startsWith('[RuvNet Brain — brain OFF by your setting')
       || s.startsWith('[RuvNet Brain — new in v')
       || s.startsWith('[RuvNet Brain — first session initialized]')

package/plugin/scripts/update-apply.mjs

@@ -212,18 +212,34 @@ function promote(staging, version) {
 // the update is fully live with no restart and session-start stays silent; if any did, the ONE
 // honest nag fires (the release classifier computes the same thing publish-side; this is the
 // client-side truth for locally-applied generations). Red-team finding 18's client half.
-const SHELL_PATHS = ['hooks/hooks.json', 'scripts/hook-shim.mjs', 'mcp/server.mjs', '.mcp.json'];
-function shellDiff(prevRootAbs, nextRootAbs) {
+export const SHELL_PATHS = [
+  'hooks/hooks.json',
+  'scripts/hook-shim.mjs',
+  'scripts/hook-shim-bash.mjs',
+  'scripts/development-maintenance.mjs',
+  'mcp/server.mjs',
+  '.mcp.json',
+];
+
+function treeDigest(root, relative) {
+  const target = path.join(root, relative);
+  let stat;
+  try { stat = fs.lstatSync(target); } catch { return '<missing>'; }
+  if (stat.isSymbolicLink()) return '<symlink>';
+  if (stat.isFile()) return `file:${crypto.createHash('sha256').update(fs.readFileSync(target)).digest('hex')}`;
+  if (!stat.isDirectory()) return `<special:${stat.mode}>`;
+  const entries = fs.readdirSync(target, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  return `dir:${entries.map((entry) => `${entry.name}:${treeDigest(target, entry.name)}`).join('|')}`;
+}
+
+export function shellDiff(prevRootAbs, nextRootAbs) {
   const changed = [];
   for (const rel of SHELL_PATHS) {
-    const a = (() => { try { return fs.readFileSync(path.join(prevRootAbs, rel), 'utf8'); } catch { return null; } })();
-    const b = (() => { try { return fs.readFileSync(path.join(nextRootAbs, rel), 'utf8'); } catch { return null; } })();
-    if (a !== b) changed.push(rel);
+    if (treeDigest(prevRootAbs, rel) !== treeDigest(nextRootAbs, rel)) changed.push(rel);
   }
   // skills/ and commands/ are boot-loaded markdown: any file-set or content difference counts.
   for (const dir of ['skills', 'commands']) {
-    const list = (root) => { try { return fs.readdirSync(path.join(root, dir), { recursive: true }).sort().join('|'); } catch { return ''; } };
-    if (list(prevRootAbs) !== list(nextRootAbs)) changed.push(`${dir}/`);
+    if (treeDigest(prevRootAbs, dir) !== treeDigest(nextRootAbs, dir)) changed.push(`${dir}/`);
   }
   return changed;
 }
@@ -239,6 +255,15 @@ function flip(version, codeRootAbs, why) {
     previous: prev ? { generation: prev.generation, version: prev.version, codeRoot: prev.codeRoot } : null,
     shellChanged: shellChanged.length > 0,
     shellChangedPaths: shellChanged,
+    // Keep the first boot-level change attached to subsequent body-only generations. A host that
+    // still booted the pre-change generation must not lose the restart signal merely because a
+    // later update changed only implementation code.
+    shellChangedSinceVersion: shellChanged.length > 0
+      ? (prev?.version || version)
+      : (prev?.shellChangedSinceVersion || null),
+    shellChangedAtVersion: shellChanged.length > 0
+      ? version
+      : (prev?.shellChangedAtVersion || null),
     flippedAt: new Date().toISOString(),
   };
   writeAtomic(TXN, JSON.stringify({ state: 'flipping', from: prev?.version ?? null, to: version }));
@@ -446,4 +471,4 @@ function main() {
   }
 }
 
-process.exit(main());
+if (process.env.RUVNET_BRAIN_IMPORT_ONLY !== 'update-shell-test') process.exit(main());

package/scripts/wired-check.mjs

@@ -70,7 +70,7 @@ const argv = process.argv.slice(2);
  * every entry on every run, below, so they cannot rot unseen.
  */
 const STANDALONE = [
-  ['gate', 'retired automatic-hook helper retained for explicit use and tests'],
+  ['gate', 'retired automatic-hook helper and manual benchmark retained for explicit human use; no workflow or scheduler invokes this expensive command'],
   ['dream-issue-gate', 'pure Dream Cycle disposition policy; invoked by the external issue adapter, never a GitHub writer'],
   ['sync-census', 'explicit maintainer census writer; a destructive source-to-surface refresh is never scheduled'],
   ['sync-commands', 'explicit maintainer alias synchronizer; run deliberately before release, never from a lifecycle hook'],
@@ -105,8 +105,6 @@ const STANDALONE = [
     + 'stops at sealed preparation with contents:read. This entry validates receipt/archive inputs '
     + 'and delegates mutation to release.mjs protected authority. No operational caller is registered; '
     + 'classification does not claim publication works or has occurred'],
-  ['gate', 'manual benchmark harness: rebuilds concepts and runs three routing proof batteries; '
-    + 'no workflow or scheduler invokes this expensive command'],
   ['execution-preflight', 'external orchestration boundary — invoked by the host before consequential Ruflo/Codex execution; no in-repo caller exists because the host supplies the live Brain and AgentDB receipts'],
   ['fix-workstream', 'session-supervised coordination CLI run explicitly by the integration owner or an '
     + 'isolated writing agent to start and hand off a fix lane. Scheduling it would violate its safety '