ruvnet-brain 4.0.2 → 4.0.5

package/plugin/mcp/server.mjs

@@ -41,14 +41,15 @@ const CHILD_MCP = process.env.RUVNET_BRAIN_CHILD_MCP || path.join(KB, 'forge-mcp
 const ACTIVE = path.join(BRAIN_HOME, 'active.json');
 const LEASES = path.join(BRAIN_HOME, 'leases');
 const LEASE = path.join(LEASES, `mcp-${process.pid}.json`);
+const READINESS = path.join(BRAIN_HOME, 'mcp-readiness.json');
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_INFO = { name: 'ruvnet-brain', version: '2.0.0' };
-// Local frozen tool declarations. search_ruvnet is only a fallback: a live child's declaration wins
-// so its description can refresh. The two managed-CLI schemas are owned by this protocol shell.
+// Stable declarations belong to this protocol shell. Capability discovery must never wait for a
+// model or vector store; the first operation that needs the worker joins its readiness promise.
 const SEARCH_TOOL = {
   name: 'search_ruvnet',
-  description: 'Source-grounded knowledge base for the RuvNet ecosystem. (Brain bundle not installed on this machine — calls will return install guidance.)',
+  description: 'Source-grounded knowledge base for the RuvNet ecosystem. The first call may wait while the local search worker becomes ready.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -60,22 +61,45 @@ const SEARCH_TOOL = {
 };
 const FALLBACK_TOOLS = [SEARCH_TOOL, ...MANAGED_CLI_TOOLS];
 
-function withLocalTools(tools) {
-  const merged = new Map();
-  for (const tool of Array.isArray(tools) ? tools : []) {
-    if (tool?.name) merged.set(tool.name, tool);
-  }
-  for (const tool of FALLBACK_TOOLS) {
-    if (!merged.has(tool.name)) merged.set(tool.name, tool);
-  }
-  return [...merged.values()];
-}
-
 const out = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
 const clientOk = (id, result) => out({ jsonrpc: '2.0', id, result });
 const clientErr = (id, code, message) => out({ jsonrpc: '2.0', id, error: { code, message } });
 const readJSON = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
 
+function writeReadiness(value) {
+  try {
+    fs.mkdirSync(BRAIN_HOME, { recursive: true });
+    const tmp = `${READINESS}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify({ ...value, pid: process.pid, at: new Date().toISOString() })}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, READINESS);
+  } catch (error) {
+    console.error(`[ruvnet-brain] could not persist MCP readiness: ${error.message}`);
+  }
+}
+
+function recordStartupFailure({ phase, startedAt, generation, error }) {
+  const now = Date.now();
+  const fields = {
+    state: 'degraded', phase, generation, elapsedMs: now - startedAt,
+    retryable: true, retryState: 'next-search-retries',
+    error: String(error?.message || error || 'unknown startup failure').slice(0, 500),
+  };
+  writeReadiness(fields);
+  const healthPath = path.join(BRAIN_HOME, 'health.json');
+  try {
+    fs.mkdirSync(BRAIN_HOME, { recursive: true });
+    const tmp = `${healthPath}.${process.pid}.${now}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify({
+      status: 'down', source: 'mcp-parent-startup', phase,
+      error: fields.error, elapsedMs: fields.elapsedMs, generation,
+      retryState: fields.retryState, ts: new Date(now).toISOString(),
+    })}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, healthPath);
+  } catch (writeError) {
+    console.error(`[ruvnet-brain] could not persist startup health: ${writeError.message}`);
+  }
+}
+
 function currentGeneration() {
   const a = readJSON(ACTIVE);
   let brainMtime = 0;
@@ -124,6 +148,7 @@ function killChild(reason) {
   clearChildIdleTimer();
   if (!child) return childRetirement;
   const c = child; child = null;
+  c.intentionalStop = true;
   for (const [, p] of c.pending) p.reject(new Error(`brain worker ${reason}`));
   c.pending.clear();
   childRetirement = new Promise((resolve) => {
@@ -157,10 +182,12 @@ async function ensureChild() {
 
   if (!childStartup) {
     childStartup = (async () => {
+      const startedAt = Date.now();
+      let phase = 'initialize';
       const env = { ...process.env, KB_DIR: KB };
       if (!env.KB_MODEL_CACHE) env.KB_MODEL_CACHE = path.join(BRAIN_HOME, 'models');
       const proc = spawn(process.execPath, [CHILD_MCP], { stdio: ['pipe', 'pipe', 'inherit'], env });
-      const c = { proc, generation: currentGeneration(), nextId: 1, pending: new Map() };
+      const c = { proc, generation: currentGeneration(), nextId: 1, pending: new Map(), intentionalStop: false };
       const rl = readline.createInterface({ input: proc.stdout });
       rl.on('line', (line) => {
         let msg; try { msg = JSON.parse(line); } catch { return; }
@@ -171,6 +198,13 @@ async function ensureChild() {
         if (child === c) child = null;
         for (const [, p] of c.pending) p.reject(new Error('brain worker exited'));
         c.pending.clear();
+        if (!c.intentionalStop) {
+          writeReadiness({
+            state: 'degraded', phase: 'worker-exit', generation: c.generation,
+            elapsedMs: Date.now() - startedAt, retryable: true,
+            retryState: 'next-search-retries', error: 'brain worker exited unexpectedly',
+          });
+        }
       });
       proc.on('error', () => { if (child === c) child = null; });
       child = c;
@@ -180,8 +214,9 @@ async function ensureChild() {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
           clientInfo: { name: 'ruvnet-brain-shell', version: SERVER_INFO.version },
-        }, CHILD_INIT_TIMEOUT_MS);
-        const warmed = await childRequest(c, 'brain/warmup', {}, CHILD_INIT_TIMEOUT_MS);
+        }, CHILD_INIT_TIMEOUT_MS, { reportTimeout: false });
+        phase = 'warmup';
+        const warmed = await childRequest(c, 'brain/warmup', {}, CHILD_INIT_TIMEOUT_MS, { reportTimeout: false });
         // Rolling-upgrade compatibility: 4.0.1 workers predate the private warmup extension. The
         // stable shell is installed before the 700MB KB swap completes, so rejecting -32601 here
         // makes every query fail during the exact in-place upgrade window the shell exists to hide.
@@ -194,8 +229,14 @@ async function ensureChild() {
         }
       } catch (e) {
         await killChild('failed initialize');
+        recordStartupFailure({ phase, startedAt, generation: c.generation, error: e });
         throw new Error(`brain worker failed to initialize: ${e.message}`);
       }
+      writeReadiness({
+        state: 'ready', phase, generation: c.generation,
+        workerPid: c.proc.pid, elapsedMs: Date.now() - startedAt,
+        retryable: false, retryState: 'none',
+      });
       armChildIdleTimer(c);
       return c;
     })();
@@ -236,13 +277,13 @@ async function onChildTimeout(method, timeoutMs) {
 // Steady-state latency remains a separate release gate; this budget prevents a permanent cold loop.
 const CALL_TIMEOUT_MS = Number(process.env.RUVNET_BRAIN_CALL_TIMEOUT_MS) || 240_000;
 
-function childRequest(c, method, params, timeoutMs = CALL_TIMEOUT_MS) {
+function childRequest(c, method, params, timeoutMs = CALL_TIMEOUT_MS, { reportTimeout = true } = {}) {
   return new Promise((resolve, reject) => {
     const id = c.nextId++;
     const timer = setTimeout(() => {
       c.pending.delete(id);
       reject(new Error(`brain worker timeout on ${method}`));
-      void onChildTimeout(method, timeoutMs); // after the reject — the caller must not wait on the alarm
+      if (reportTimeout) void onChildTimeout(method, timeoutMs); // caller never waits on the alarm
     }, timeoutMs);
     c.pending.set(id, { resolve: (m) => { clearTimeout(timer); resolve(m); }, reject: (e) => { clearTimeout(timer); reject(e); } });
     try { c.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); }
@@ -266,19 +307,6 @@ async function handleClient(msg) {
     case 'ping':
       return clientOk(id, {});
     case 'tools/list': {
-      try {
-        const c = await ensureChild();
-        if (c) {
-          try {
-            const r = await childRequest(c, 'tools/list', {}, 15_000);
-            if (r.result?.tools?.length) {
-              armChildIdleTimer(c);
-              return clientOk(id, { ...r.result, tools: withLocalTools(r.result.tools) });
-            }
-          }
-          catch { /* fall through to the static declaration */ }
-        }
-      } catch { /* fall through to the static declaration during a transient startup outage */ }
       return clientOk(id, { tools: FALLBACK_TOOLS });
     }
     case 'tools/call': {
@@ -321,4 +349,13 @@ clientRl.on('line', (line) => {
   let msg; try { msg = JSON.parse(line); } catch { return; } // malformed line: ignore, never crash
   handleClient(msg).catch((e) => { if (msg.id !== undefined && msg.id !== null) clientErr(msg.id, -32603, e.message); });
 });
-clientRl.on('close', () => { killChild('client disconnected'); process.exit(0); });
+let shuttingDown = false;
+async function shutdown(reason) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  await killChild(reason);
+  process.exit(0);
+}
+clientRl.on('close', () => { void shutdown('client disconnected'); });
+process.once('SIGTERM', () => { void shutdown('parent received SIGTERM'); });
+process.once('SIGINT', () => { void shutdown('parent received SIGINT'); });

package/plugin/scripts/hook-shim.mjs

@@ -82,16 +82,16 @@ catch (e) { BRAIN_OFF = !(e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')); }
 //               ONE resolved answer instead of racing the filesystem again mid-run.
 const TABLE = {
   'session-start':    { file: 'session-start-core.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'partial' },
-  'ground-ruvnet':    { file: 'ground-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
+  'ground-ruvnet':    { file: 'ground-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence', stdinBytes: 32768 },
   'hijack-ruvnet':    { file: 'hijack-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
-  'route-dispatch':   { file: 'route-dispatch.sh',   interpreter: 'bash', mode: 'blocking', offBehavior: 'run' },
-  'ground-before-write': { file: 'ground-before-write.sh', interpreter: 'bash', mode: 'blocking', offBehavior: 'run' },
+  'route-dispatch':   { file: 'route-dispatch.sh',   interpreter: 'bash', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
+  'ground-before-write': { file: 'ground-before-write.sh', interpreter: 'bash', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
   'grounding-stamp': { file: 'grounding-stamp.sh', interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'verify-interface': { file: 'verify-interface.sh', interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
-  'design-wall':      { file: 'design-wall.sh',      interpreter: 'bash', mode: 'blocking', offBehavior: 'run' },
+  'design-wall':      { file: 'design-wall.sh',      interpreter: 'bash', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
   // The consent guard (ADR-054 §3): it protects the OFF state itself, so it is the one hook that
   // matters MORE while the brain is off. 'run', permanently.
-  'protect-state':    { file: 'protect-brain-state.sh', interpreter: 'bash', mode: 'blocking', offBehavior: 'run' },
+  'protect-state':    { file: 'protect-brain-state.sh', interpreter: 'bash', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
   'learn-capture':    { file: 'learn-capture.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'learn-flush':      { file: 'learn-flush.mjs',     interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   'md-stamp':         { file: 'md-stamp.mjs',        interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
@@ -112,7 +112,7 @@ const TABLE = {
   // exit code, and an opted-in lesson BLOCK must propagate as exit 2 (an advisory delivery is exit 0
   // and passes straight through; a spawn error is exit 1, which CC treats as a non-blocking notice).
   // The CC event name is forwarded to the runtime as an extra argv (see runHook's arg plumbing).
-  'unprompted-speech': { file: 'unprompted-runtime.mjs', interpreter: 'node', mode: 'blocking', channel: 'unprompted', offBehavior: 'silence' },
+  'unprompted-speech': { file: 'unprompted-runtime.mjs', interpreter: 'node', mode: 'blocking', channel: 'unprompted', offBehavior: 'silence', stdinBytes: 65536 },
   // THE LIFECYCLE PLANE (ADR-055 §2, build item 1). Stop was the ONE registered hook that bypassed
   // this table entirely — hooks.json pointed straight at continuation-gate.mjs, so it had no mode,
   // no offBehavior, and no spine resolution, contradicting this file's own `_note` and leaving
@@ -156,7 +156,7 @@ if (BRAIN_OFF && entry.offBehavior === 'silence') process.exit(0);
 // already running, and skip the interpreter entirely only when BOTH prompt intent and project
 // state prove that no advisory can fire. The regex deliberately over-approximates the shell gates:
 // false positives take the established body; false negatives would be a product defect.
-let groundInput = null;
+let hookInput = null;
 const GROUND_RELEVANT = /ruvnet|ruflo|ruvector|\brvf\b|agentdb|agenticow|rulake|ruview|rupixel|ruv-fann|agentic-flow|synthlang|dspy|qudag|safla|metaharness|cve-bench|sparc|swarm|claude-flow|pinecone|pgvector|chroma|weaviate|faiss|milvus|qdrant|hnswlib|annoy|vector|langchain|llama|autogen|crew-ai|semantic-kernel|embedding|retrieval|prompt compression|token cost|post-quantum|quantum-resistant|\badr\b|decision|architect|design|plan|spec|refactor|migrat|implement|build|write|add|change|fix|update|deploy|create|enhance|set up|setup|wire|integrate|test|coverage|audit|review|benchmark|lint|scan|debug|optimi|app|feature|service|system|backend|frontend|\bapi\b|module|pipeline|infra|database|schema|workflow|roadmap|milestone|autonomous|unattended|do not stop|keep working|keep going|soak run|harness|quality|readiness|evolve|self-improv|hardening|cheaper|cheap|lower cost|compute arbitrage|cascade|scorecard|score .*repo/i;
 
 function projectCanSpeakWithoutPrompt() {
@@ -173,7 +173,7 @@ function projectCanSpeakWithoutPrompt() {
   return false;
 }
 
-function readGroundInput() {
+function readHookInput(limit) {
   return new Promise((resolve) => {
     const chunks = [];
     let bytes = 0;
@@ -194,8 +194,8 @@ function readGroundInput() {
       idle.unref?.();
     };
     process.stdin.on('data', (chunk) => {
-      if (bytes < 32768) {
-        const kept = chunk.subarray(0, 32768 - bytes);
+      if (bytes < limit) {
+        const kept = chunk.subarray(0, limit - bytes);
         chunks.push(kept);
         bytes += kept.length;
       }
@@ -254,8 +254,8 @@ function runHook(file) {
   const env = (BRAIN_OFF && entry.offBehavior === 'partial')
     ? { ...process.env, RUVNET_BRAIN_OFF: '1' }
     : process.env;
-  const io = hookId === 'ground-ruvnet' && groundInput !== null
-    ? { stdio: ['pipe', 'inherit', 'inherit'], input: groundInput }
+  const io = hookInput !== null
+    ? { stdio: ['pipe', 'inherit', 'inherit'], input: hookInput }
     : { stdio: 'inherit' };
   const r = spawnSync(cmd, [file, ...extraArgs], { ...io, env });
   if (r.error) {
@@ -287,17 +287,22 @@ function dispatchHook() {
   return runHook(fallbackFile);
 }
 
-if (hookId === 'ground-ruvnet') {
-  readGroundInput().then((input) => {
-    groundInput = input;
-    let text = input.toString('utf8');
-    try {
-      const parsed = JSON.parse(text);
-      text = parsed?.prompt ?? parsed?.user_prompt ?? parsed?.input ?? text;
-    } catch { /* raw/malformed input is classified as-is */ }
-    if (!GROUND_RELEVANT.test(String(text)) && !projectCanSpeakWithoutPrompt()) process.exit(0);
+if (entry.stdinBytes) {
+  readHookInput(entry.stdinBytes).then((input) => {
+    hookInput = input;
+    if (hookId === 'ground-ruvnet') {
+      let text = input.toString('utf8');
+      try {
+        const parsed = JSON.parse(text);
+        text = parsed?.prompt ?? parsed?.user_prompt ?? parsed?.input ?? text;
+      } catch { /* raw/malformed input is classified as-is */ }
+      if (!GROUND_RELEVANT.test(String(text)) && !projectCanSpeakWithoutPrompt()) process.exit(0);
+    }
     process.exit(dispatchHook());
-  }).catch(() => process.exit(dispatchHook()));
+  }).catch(() => {
+    hookInput = Buffer.alloc(0);
+    process.exit(dispatchHook());
+  });
 } else {
   process.exit(dispatchHook());
 }

package/plugin/scripts/lesson-command-scope.mjs

@@ -0,0 +1,133 @@
+// lesson-command-scope.mjs — pure advisory scope classification for lesson-gate.
+//
+// This is deliberately an allowlist of outside-repository mutations. Unknown commands stay quiet:
+// over-firing an advisory trains users and agents to ignore it. Segments are classified only from
+// executable position, so quoted examples and grep/echo text cannot manufacture a trigger.
+import fs from 'node:fs';
+import path from 'node:path';
+
+function repositoryRoot(start = process.cwd()) {
+  let dir = start;
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+
+function splitTopLevelSegments(command) {
+  const segments = [];
+  let current = '';
+  let quote = null;
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i];
+    if (quote) {
+      current += char;
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if ((char === '&' && command[i + 1] === '&') || (char === '|' && command[i + 1] === '|')) {
+      segments.push(current);
+      current = '';
+      i++;
+      continue;
+    }
+    if (char === ';' || char === '&' || char === '|' || char === '\n') {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) segments.push(current);
+  return segments.map((segment) => segment.trim()).filter(Boolean);
+}
+
+function tokenize(segment) {
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  for (const char of segment) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) tokens.push(current);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+const SYSTEM_PATH_PREFIXES = ['/etc', '/usr', '/bin', '/sbin', '/System', '/Library', '/private', '/var', '/opt'];
+const INSTALL_VERBS = new Set(['install', 'i', 'add', 'uninstall', 'remove', 'rm', 'un']);
+const GLOBAL_FLAGS = new Set(['-g', '--global']);
+const SECURITY_MUTATING = new Set([
+  'create-keychain', 'delete-keychain', 'set-keychain-password', 'set-keychain-settings',
+  'unlock-keychain', 'lock-keychain', 'import', 'add-generic-password', 'add-internet-password',
+  'delete-generic-password', 'delete-internet-password', 'default-keychain',
+]);
+const BREW_MUTATING = new Set(['install', 'uninstall', 'remove', 'rm', 'upgrade', 'reinstall', 'tap', 'untap', 'link', 'unlink', 'pin', 'unpin', 'services']);
+const PKG_MUTATING = new Set(['install', 'remove', 'purge', 'upgrade']);
+const FS_MUTATING_VERBS = new Set(['rm', 'mv', 'cp', 'ln', 'shred', 'truncate', 'unlink']);
+
+function curlMutates(tokens) {
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    if ((token === '-X' || token === '--request') && ['POST', 'PUT', 'PATCH', 'DELETE'].includes((tokens[i + 1] || '').toUpperCase())) return true;
+    if (/^--request=/.test(token) && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(token.split('=')[1].toUpperCase())) return true;
+    if (token === '-d' || token === '--data' || /^--data(-raw|-binary|-urlencode)?$/.test(token) || token === '--upload-file' || token === '-T') return true;
+  }
+  return false;
+}
+
+function classifySegment(segment, repoRoot) {
+  let tokens = tokenize(segment);
+  while (tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0])) tokens = tokens.slice(1);
+  if (!tokens.length) return false;
+  const lead = tokens[0];
+  const outsideRepo = (token) => token && !token.startsWith('-') && (
+    token.startsWith('~') || (token.startsWith('/') && token !== repoRoot && !token.startsWith(repoRoot + path.sep))
+  );
+  const systemPath = (token) => token && !token.startsWith('-')
+    && SYSTEM_PATH_PREFIXES.some((prefix) => token === prefix || token.startsWith(prefix + '/'));
+  if (lead === 'sudo') return true;
+  switch (lead) {
+    case 'launchctl': return true;
+    case 'security': return SECURITY_MUTATING.has(tokens[1]);
+    case 'defaults': return tokens[1] === 'write' || tokens[1] === 'delete';
+    case 'npm': case 'pnpm': case 'yarn': return INSTALL_VERBS.has(tokens[1]) && tokens.some((token) => GLOBAL_FLAGS.has(token));
+    case 'pip': case 'pip3': case 'pipx': return tokens[1] === 'install' || tokens[1] === 'uninstall';
+    case 'brew': return BREW_MUTATING.has(tokens[1]);
+    case 'gem': return tokens[1] === 'install' || tokens[1] === 'uninstall';
+    case 'apt': case 'apt-get': case 'yum': case 'dnf': case 'pacman': case 'port': return PKG_MUTATING.has(tokens[1]);
+    case 'git': return tokens[1] === 'push';
+    case 'curl': return curlMutates(tokens);
+    case 'wget': return tokens.some((token) => token.startsWith('--post-data') || token.startsWith('--post-file'));
+    case 'chmod': case 'chown': case 'chgrp': return tokens.slice(1).some(systemPath);
+    case 'dd': case 'mkfs': case 'diskutil': return true;
+    case 'crontab': return tokens[1] === '-e' || tokens[1] === '-r';
+    default: return FS_MUTATING_VERBS.has(lead) && tokens.slice(1).some(outsideRepo);
+  }
+}
+
+export function looksLikeOutsideRepoMutation(command, repoRoot = repositoryRoot()) {
+  if (!command || typeof command !== 'string') return false;
+  return splitTopLevelSegments(command).some((segment) => classifySegment(segment, repoRoot));
+}