ruvnet-brain 4.7.4 → 4.7.6

package/README.md

@@ -9,7 +9,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 ### Discover the stack. Read the source. Build with confidence.
 
-[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.4-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
+[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.6-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
 
 **A source-grounded companion for Claude Code and Codex that helps you find and use Reuven Cohen's (rUv's) RuvNet ecosystem.**
 

package/package.json

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

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

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

package/plugin/scripts/agentdb-recall-reader.mjs

@@ -3,11 +3,12 @@
  * so a stalled CLI is retired at the recall deadline. Output contract unchanged: {ok, value}.
  */
 import { execFile } from 'node:child_process';
-import { resolveRuflo } from './ruflo-bin.mjs';
+import { resolveRuflo, rufloInvocationOrPlain } from './ruflo-bin.mjs';
 
 const call = (bin, args, deadline) => new Promise((resolve) => {
   const timeout = Math.max(1, deadline - Date.now());
-  execFile(bin, args, { timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' } },
+  const inv = rufloInvocationOrPlain(bin, args, { env: process.env });
+  execFile(inv.executable, inv.args, { timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' } },
     (error, stdout) => resolve(error ? null : String(stdout || '')));
 });
 

package/plugin/scripts/ruflo-bin.mjs

@@ -36,14 +36,90 @@
  * Rule 21 is untouched by this: still ONE ruflo, still the global one, never `npx ruflo@latest`. This
  * resolves WHERE that one global binary is rather than assuming everyone's prefix matches the owner's.
  */
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+// WHICH NODE RUNS RUFLO (measured 2026-10-14, ruflo 3.56.9 / better-sqlite3 12.11.1). `ruflo` is
+// `#!/usr/bin/env node`, so the interpreter is whatever is FIRST on the CALLER's PATH — and an
+// installed better-sqlite3 holds ONE native ABI (this machine's was built for node 24). A hook
+// launched with PATH=/opt/homebrew/bin:… got node 26, and `memory store` was refused with
+// "Native memory writer required; refusing whole-image sql.js fallback": 67 failed captures in a day,
+// each one a lost turn record. Same command, only PATH changed: node 26 first → refused, node 24 first
+// → stored. Upstream's guard (ruflo#2219) covers shipping prebuilds for Node 20–26, not one install
+// being run under several nodes, so the choice belongs here, in the one resolver every caller shares.
+//
+// The test is the load itself — open an in-memory database through the SAME better-sqlite3 ruflo
+// will use — never a version string. Healthy machines are untouched: when the PATH node loads the
+// binding, this returns null and the invocation stays exactly `ruflo …`.
+function defaultNodeCandidates(env) {
+  const out = [];
+  for (const dir of String(env.PATH || '').split(path.delimiter)) if (dir) out.push(path.join(dir, 'node'));
+  out.push(process.execPath);
+  try {
+    const opt = '/opt/homebrew/opt';
+    for (const name of fs.readdirSync(opt).filter((n) => /^node(@\d+)?$/.test(n)).sort().reverse()) {
+      out.push(path.join(opt, name, 'bin', 'node'));
+    }
+  } catch { /* no Homebrew opt dir */ }
+  out.push('/opt/homebrew/bin/node', '/usr/local/bin/node');
+  return [...new Set(out)].filter((c) => { try { return fs.statSync(c).isFile(); } catch { return false; } });
+}
+
+const nativeNodeCache = new Map();
+const PROBE_TIMEOUT_MS = 2000;
+const PROBE_BUDGET_MS = 3000;
+
+/**
+ * rufloInvocation for callers that must never throw: an unrecognised shim keeps the plain `bin args` they
+ * always ran, so routing a call site through node selection can only add the correct interpreter.
+ */
+export function rufloInvocationOrPlain(binary, args, opts) {
+  try { return rufloInvocation(binary, args, opts); } catch { return { executable: binary, args }; }
+}
+
+/**
+ * The node that can load ruflo's native better-sqlite3, or null when the caller's own PATH node
+ * already can, when ruflo is not a node package we can inspect, or when no candidate can.
+ * Null always means "leave the invocation exactly as it was" — this never makes anything worse.
+ *
+ * @param {string} binary  path to the ruflo bin (symlink or script)
+ * @param {{ env?: Record<string,string|undefined>, candidates?: string[] }} [opts]
+ * @returns {{ node: string, entry: string }|null}
+ */
+export function nativeNodeFor(binary, { env = process.env, candidates } = {}) {
+  let entry;
+  try { entry = fs.realpathSync(binary); } catch { return null; }
+  const addon = path.join(path.dirname(path.dirname(entry)), 'node_modules', 'better-sqlite3');
+  try { if (!fs.statSync(addon).isDirectory()) return null; } catch { return null; }
+
+  const list = candidates ?? defaultNodeCandidates(env);
+  const cacheKey = `${entry}\0${list.join('\0')}`;
+  if (nativeNodeCache.has(cacheKey)) return nativeNodeCache.get(cacheKey);
+
+  const probe = `new (require(${JSON.stringify(addon)}))(':memory:').close()`;
+  let chosen = null;
+  // Bounded: this runs inside hooks that have their own deadline (SessionStart is stopped 1.5 s early), so a
+  // wedged candidate must cost seconds at most and then leave the invocation exactly as it was.
+  const started = Date.now();
+  for (let i = 0; i < list.length; i += 1) {
+    if (Date.now() - started > PROBE_BUDGET_MS) break;
+    const r = spawnSync(list[i], ['-e', probe], { stdio: 'ignore', timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+    if (r.status === 0) { chosen = i === 0 ? null : { node: list[i], entry }; break; }
+  }
+  nativeNodeCache.set(cacheKey, chosen);
+  return chosen;
+}
+
 // npm's Windows .cmd shim cannot be spawned without a shell. Resolve the declared entry
 // inside that same managed installation and pass argv directly to Node instead.
-export function rufloInvocation(binary, args, { platform = process.platform } = {}) {
-  if (platform !== 'win32' || !/\.cmd$/i.test(binary)) return { executable: binary, args };
+export function rufloInvocation(binary, args, { platform = process.platform, env = process.env, nodeCandidates } = {}) {
+  if (platform !== 'win32') {
+    const native = nativeNodeFor(binary, { env, candidates: nodeCandidates });
+    return native ? { executable: native.node, args: [native.entry, ...args] } : { executable: binary, args };
+  }
+  if (!/\.cmd$/i.test(binary)) return { executable: binary, args };
   if (path.basename(binary).toLowerCase() !== 'ruflo.cmd') throw new Error('unsupported managed Ruflo shim');
   const packageRoot = fs.realpathSync(path.join(path.dirname(fs.realpathSync(binary)), 'node_modules', 'ruflo'));
   const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));

package/plugin/scripts/ruflo-memory-hooks.mjs

@@ -18,7 +18,7 @@ import crypto from 'node:crypto';
 import path from 'node:path';
 import { execFile, execFileSync, spawnSync } from 'node:child_process';
 import os from 'node:os';
-import { resolveRuflo, rufloRunDir, rufloScratchRoot } from './ruflo-bin.mjs';
+import { resolveRuflo, rufloInvocationOrPlain, rufloRunDir, rufloScratchRoot } from './ruflo-bin.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { checkpointNamespaces, newestOfFamily } from './checkpoint-keys.mjs';
 
@@ -57,7 +57,8 @@ export function rufloMemory(args, { db, env = process.env, bin = resolveRuflo({
   return new Promise((resolve) => {
     if (!bin) return resolve({ ok: false, stdout: '', error: 'global Ruflo unavailable' });
     const spawnAt = rufloSpawnOptions(db, env);
-    execFile(bin, ['memory', ...args, '--path', db], { cwd: spawnAt.cwd, env: spawnAt.env, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 },
+    const inv = rufloInvocationOrPlain(bin, ['memory', ...args, '--path', db], { env: spawnAt.env });
+    execFile(inv.executable, inv.args, { cwd: spawnAt.cwd, env: spawnAt.env, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 },
       // The ledger gets a fixed reason, never execFile's message (it embeds the whole argv: value, db path).
       (error, stdout) => { spawnAt.cleanup(); resolve({ ok: !error, stdout: String(stdout || ''), error: error ? (error.killed ? 'timed out' : `ruflo memory ${args[0]} exited ${error.code ?? 'abnormally'}`) : null }); });
   });
@@ -194,11 +195,13 @@ export function storeExact({ db, namespace, key, value, env = process.env, bin =
   const spawnAt = rufloSpawnOptions(db, env);
   const options = { encoding: 'utf8', timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 8 * 1024 * 1024, cwd: spawnAt.cwd, env: spawnAt.env };
   try {
-    const stored = run(bin, ['memory', 'store', '--key', key, '--value', value, '--namespace', namespace, '--path', db], options);
+    const storeInv = rufloInvocationOrPlain(bin, ['memory', 'store', '--key', key, '--value', value, '--namespace', namespace, '--path', db], { env: spawnAt.env });
+    const stored = run(storeInv.executable, storeInv.args, options);
     if (stored.error || stored.status !== 0) {
       return { stored: false, verified: false, error: String(stored.stderr || stored.stdout || stored.error?.message || 'store failed').trim().slice(0, 200) };
     }
-    const read = run(bin, ['memory', 'retrieve', '--key', key, '--namespace', namespace, '--value-only', '--path', db], options);
+    const readInv = rufloInvocationOrPlain(bin, ['memory', 'retrieve', '--key', key, '--namespace', namespace, '--value-only', '--path', db], { env: spawnAt.env });
+    const read = run(readInv.executable, readInv.args, options);
     return { stored: true, verified: !read.error && read.status === 0 && String(read.stdout || '').trim() === value, key };
   } finally { spawnAt.cleanup(); }
 }

package/scripts/release-qualification-contract.mjs

@@ -220,6 +220,15 @@ export const RELEASE_REQUIREMENTS = Object.freeze({
         "tests/unit/project-store-resolver.test.mjs"
       ]
     },
+    {
+      "id": "ruflo-runs-under-a-node-that-loads-its-binding",
+      "reason": "Hooks inherit whatever node is first on their PATH; every direct ruflo launch (turn and learning capture, the SessionEnd/PreCompact checkpoint writer, the SessionStart memory reader and the recall reader) runs ruflo under the first node that can load its own better-sqlite3 within a bounded probe (a healthy machine is untouched, and no candidate means no change), so a native memory write is not refused for a node-ABI mismatch",
+      "files": [],
+      "platformFiles": {
+        "linux": ["tests/unit/ruflo-native-node.test.mjs"],
+        "macos": ["tests/unit/ruflo-native-node.test.mjs"]
+      }
+    },
     {
       "id": "lossless-lifecycle-retention",
       "reason": "Evidence compaction preserves tokens, private state and atomic transaction recovery",