ruvnet-brain 4.0.2 → 4.0.4

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/session-start-core.mjs

@@ -172,6 +172,20 @@ const health = (home, off) => {
   return { problem: '', absentByChoice };
 };
 
+const mcpReadiness = (env, home) => {
+  const brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
+  const receipt = json(path.join(brainHome, 'mcp-readiness.json'));
+  if (receipt?.state === 'ready' && Number.isInteger(receipt.pid) && Number.isInteger(receipt.workerPid)) {
+    try {
+      process.kill(receipt.pid, 0);
+      process.kill(receipt.workerPid, 0);
+      return { state: 'ready', receipt };
+    } catch { /* a stale receipt is registration evidence, not live evidence */ }
+  }
+  if (receipt?.state === 'degraded') return { state: 'degraded', receipt };
+  return { state: 'registered', receipt };
+};
+
 const announceVersion = ({ running, off, stateDir, consoleInvoke, emit }) => {
   if (off || !running) return;
   const announced = path.join(stateDir, '.last-announced-version');
@@ -412,6 +426,7 @@ export async function runSessionStart({
     }
     const source = json(path.join(home, '.cache', 'ruvnet-brain', 'kb', 'SOURCE.json'), {});
     const kbVersion = typeof source?.releaseTag === 'string' ? source.releaseTag : '';
+    const readiness = mcpReadiness(env, home);
 
     const grounding = json(path.join(stateDir, 'install-state.json'));
     const asciiDrift = path.join(env.CLAUDE_PROJECT_DIR || cwd, 'scripts', 'ascii-drift.mjs');
@@ -437,8 +452,19 @@ export async function runSessionStart({
         emit(`The plugin and its hooks are running, but the brain itself is broken (see the alarm above). Do not claim grounding works. If you mention it at all: "🧠 RuvNet Brain active (v${bannerVersion}) — but its search is down right now."`);
       } else {
         emit(`[RuvNet Brain v${bannerVersion} — active this session${updated ? ` · updated ${updated}` : ''}${kbVersion ? ` · knowledge bundle ${kbVersion}` : ''}]`);
-        emit('USER-LEVEL: one brain (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project. search_ruvnet and the grounding hooks are live now.');
-        emit(`Open your FIRST response with ONE short, warm confirmation in your own words (2-3 lines, then move on; never repeat it this session). It must say "🧠 RuvNet Brain active (v${bannerVersion}${kbVersion ? `, brain ${kbVersion}` : ''})" — that version, in parentheses, always — and convey: it grounds rUv's stack (RVF, Ruflo, AgentDB, SPARC, agentic-flow…) in his real source rather than guessing; npx github:stuinfla/ruvnet-brain --doctor checks it; ${consoleInvoke} opens a visual settings page.`);
+        let confidenceInstruction;
+        if (readiness.state === 'ready') {
+          emit('USER-LEVEL: one brain (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project. search_ruvnet is ready and live; the grounding hooks are active.');
+          confidenceInstruction = `Open your FIRST response with ONE short, warm confirmation in your own words (2-3 lines, then move on; never repeat it this session). It must say "🧠 RuvNet Brain active (v${bannerVersion}${kbVersion ? `, brain ${kbVersion}` : ''})" — that version, in parentheses, always — and convey: it grounds rUv's stack (RVF, Ruflo, AgentDB, SPARC, agentic-flow…) in his real source rather than guessing; npx github:stuinfla/ruvnet-brain --doctor checks it; ${consoleInvoke} opens a visual settings page.`;
+        } else if (readiness.state === 'degraded') {
+          const receipt = readiness.receipt || {};
+          emit(`USER-LEVEL: one brain (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project. search_ruvnet is registered but degraded (${receipt.phase || 'startup'}: ${receipt.error || 'readiness failed'}); the grounding hooks remain active.`);
+          confidenceInstruction = `Open your FIRST response with ONE short line: "🧠 RuvNet Brain active (v${bannerVersion}) — search is degraded right now." Do not claim source grounding until a real search succeeds. npx github:stuinfla/ruvnet-brain --doctor shows the current verdict; ${consoleInvoke} opens the Console.`;
+        } else {
+          emit('USER-LEVEL: one brain (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project. search_ruvnet is registered; live readiness is not yet proven. The grounding hooks are active.');
+          confidenceInstruction = `Open your FIRST response with ONE short line: "🧠 RuvNet Brain active (v${bannerVersion}) — search is registered and will prove readiness on first use." Do not claim source grounding until a real search returns a citation. npx github:stuinfla/ruvnet-brain --doctor shows the current verdict; ${consoleInvoke} opens the Console.`;
+        }
+        emit(confidenceInstruction);
       }
 
       const claudeJson = read(path.join(home, '.claude.json'));

package/plugin/scripts/whats-new.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Installed What's New boundary. The executable, manifest and curated notes live in the same
+// immutable plugin payload, so a Stable Spine generation can never report another version's notes.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const notesPath = path.join(pluginRoot, 'docs', 'RELEASE-NOTES-4.0.md');
+const manifestCandidates = [
+  path.join(pluginRoot, '.codex-plugin', 'plugin.json'),
+  path.join(pluginRoot, '.claude-plugin', 'plugin.json'),
+];
+
+function fail(message) {
+  process.stderr.write(`RuvNet Brain What's New failed: ${message}\n`);
+  process.exitCode = 1;
+}
+
+let manifest = null;
+for (const candidate of manifestCandidates) {
+  try {
+    manifest = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+    if (manifest?.version) break;
+  } catch { /* try the other installed host manifest */ }
+}
+
+if (!manifest?.version) {
+  fail(`installed version metadata is missing from ${pluginRoot}`);
+} else if (!fs.existsSync(notesPath)) {
+  fail(`installed release notes are missing at ${notesPath}`);
+} else {
+  let notes = '';
+  try { notes = fs.readFileSync(notesPath, 'utf8'); }
+  catch (error) { fail(`installed release notes could not be read at ${notesPath}: ${error.message}`); }
+  if (notes) {
+    process.stdout.write(`RuvNet Brain ${manifest.version}\n\n`);
+    process.stdout.write(notes);
+    if (!notes.endsWith('\n')) process.stdout.write('\n');
+  }
+}

package/plugin/skills/release-proof/SKILL.md

@@ -17,17 +17,24 @@ green.
 4. Reject any test/QE result with zero tests, skips, todos, unknowns, pending jobs, or failures.
 5. Require two distinct independent graders scoring at least 95, each bound to the SHA and digest.
 6. Install the sealed artifact into virgin Claude Code and Codex homes; test their real entrypoints.
-7. Require the active Brain registry to contain the `ruvnet-brain` RVF store and require narrow,
+7. Require the source package, Claude manifest, Codex manifest, packed npm version, bundle
+   `brainVersion`/`releaseTag`, and both installed host versions to identify one exact generation.
+8. Require the active Brain registry to contain the `ruvnet-brain` RVF store and require narrow,
    broad, and concurrent cited searches to complete within 80% of their deadline.
-8. Publish only through the protected release workflow. Never run `npm publish` or `gh release
+9. Publish only through the protected release workflow. Never run `npm publish` or `gh release
    create` locally.
-9. After publication, download npm and GitHub artifacts, compare their bytes with the seal, install
+10. After publication, download npm and GitHub artifacts, compare their bytes with the seal, install
    both hosts again, query the active MCP again, and require `published-surface-probe` green.
-10. Close an issue only after posting its acceptance evidence. Never close from source inspection.
+11. Close an issue only after posting its acceptance evidence. Never close from source inspection.
 
 ## Candidate seal
 
 Generate the receipt from commands in the protected candidate workflow. Do not hand-author it.
+For generation 4.0.4, dispatch `.github/workflows/protected-release.yml` only with the full candidate
+SHA, sealed artifact SHA-256, exact version `4.0.4`, and the successful exact-SHA CI run ID whose
+named `release-qe` job produced `release-evidence-<sha>`. The workflow checks every binding before
+creating its sealed handoff and again after the production reviewer approves. Missing artifacts,
+pending/red jobs, malformed inputs, version splits, and byte mismatches stop before the publisher.
 Validate it from the repository with:
 
 ```bash
@@ -58,6 +65,16 @@ Only exit 0 permits “shipped,” “deployed,” “green,” or “ready.”
 seal fails, say `PUBLICATION DEGRADED`, preserve the previous known-good release, and repair or
 roll back through the release workflow.
 
+`scripts/release.mjs --publish` is intentionally unusable from a local shell or another workflow.
+Its invocation guard requires GitHub Actions workflow `protected-release`, the candidate receipt,
+and matching SHA/digest/version bindings before any push, tag, release, or npm action. The workflow
+then runs `scripts/publication-receipt.mjs` after channel verification. That producer independently
+downloads the sealed package from npm and the GitHub Release, requires both copies to match the
+candidate bytes and identity, installs the npm copy into virgin Claude and Codex homes, proves the
+installed self-RVF/readiness/search deadline, and runs `published-surface-probe` on the candidate
+SHA. It refuses to overwrite an existing receipt. The workflow uploads both append-only receipts
+only after the two-receipt validator exits 0; missing evidence is red, never inferred.
+
 ## Evidence and issue handling
 
 For each issue:

package/plugin/skills/release-proof/references/receipt-contract.md

@@ -8,13 +8,17 @@ by protected workflows, never editable status documents.
 Required bindings:
 
 - `sha`, `tree`, `dirty:false`
+- `version`, `tag`, and exact-equal `sourceVersions.package`, `sourceVersions.claudePlugin`, and
+  `sourceVersions.codexPlugin`
 - `artifact.path`, `artifact.sha256`, `artifact.sourceSha`
+- exact-equal `artifact.version`, `artifact.bundle.brainVersion`, and
+  `artifact.bundle.releaseTag`
 - exact-SHA release-vector verdict with zero unknown/skipped
 - aggregate tests with nonzero total, all passed, zero failed/skipped/todo
 - fresh coverage floor and zero critical/high security findings
 - zero open GitHub issues
 - required GitHub workflow results on the same SHA
-- virgin-home Claude and Codex results on the same artifact digest
+- virgin-home Claude and Codex results on the same artifact digest and exact candidate version
 - installed Brain self-RVF plus narrow, broad, and concurrent cited search timings
 - nonzero Agentic QE totals with zero failed/skipped
 - two distinct independent grader receipts at 95 or higher, bound to SHA and digest
@@ -24,6 +28,8 @@ Required bindings:
 Required bindings:
 
 - candidate SHA and artifact digest
+- candidate `version` plus exact-equal npm version, GitHub tag, bundle `brainVersion`/`releaseTag`,
+  and installed Claude/Codex versions
 - npm and GitHub release bytes matching the candidate digest
 - clean installed Claude and Codex results from the public package
 - installed Brain self-RVF and broad search within 80 percent of deadline
@@ -31,7 +37,7 @@ Required bindings:
 
 ## Failure semantics
 
-Any missing field, malformed digest, mismatched SHA, dirty tree, open issue, absent/pending/red
+Any missing field, split version identity, malformed digest, mismatched SHA, dirty tree, open issue, absent/pending/red
 workflow, skipped/todo/zero-test result, missing RVF store, uncited search, deadline-margin breach,
 low/missing grader, or public byte mismatch is `FAIL`. There is no warning state and no score
 average. The authority never publishes; publication belongs to the protected workflow after the

package/plugin/skills/release-proof/scripts/release-proof.mjs

@@ -6,13 +6,59 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
-export const REQUIRED_CHECKS = ['ci', 'integration-linux', 'stranger-matrix', 'ux-qe'];
+export const REQUIRED_CHECKS = ['ci', 'integration-linux', 'stranger-matrix', 'ux-qe', 'release-qe'];
 
 const fail = (code, detail) => ({ code, detail });
 const cleanHex = (value, length) => new RegExp(`^[a-f0-9]{${length}}$`, 'i').test(String(value || ''));
 const digestOf = (receipt) => String(receipt?.artifact?.sha256 || '').replace(/^sha256:/, '');
+const versionField = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+
+function versionIdentityFailures(expectedVersion, expectedTag, fields) {
+  const mismatches = [];
+  if (!versionField(expectedVersion)) mismatches.push('version is missing');
+  if (expectedTag !== `v${expectedVersion}`) mismatches.push(`tag=${expectedTag ?? 'missing'}`);
+  for (const [name, value, expected = expectedVersion] of fields) {
+    if (value !== expected) mismatches.push(`${name}=${value ?? 'missing'}`);
+  }
+  return mismatches;
+}
+
+export function evaluateStabilizationCandidateReceipt(receipt) {
+  const failures = [];
+  const sha = String(receipt?.sha || '');
+  const digest = digestOf(receipt);
+  if (receipt?.schemaVersion !== 1 || receipt?.phase !== 'stabilization-candidate' || receipt?.mode !== 'stabilization') {
+    failures.push(fail('INVALID_STABILIZATION_RECEIPT', 'schemaVersion=1, phase=stabilization-candidate, and mode=stabilization are required'));
+  }
+  if (receipt?.targetScore !== 95 || receipt?.scoreClaimed !== false) {
+    failures.push(fail('STABILIZATION_SCORE_MISREPRESENTED', 'stabilization must preserve the 95 target and explicitly make no 95 claim'));
+  }
+  if (!cleanHex(sha, 40) || !cleanHex(receipt?.tree, 40) || receipt?.dirty !== false) {
+    failures.push(fail('INVALID_LINEAGE', 'clean candidate SHA and tree are required'));
+  }
+  if (!cleanHex(digest, 64) || receipt?.artifact?.sourceSha !== sha) {
+    failures.push(fail('INVALID_ARTIFACT_DIGEST', 'sealed package digest must be bound to the candidate SHA'));
+  }
+  const version = versionField(receipt?.version);
+  const identityMismatches = versionIdentityFailures(version, receipt?.tag, [
+    ['source package', receipt?.sourceVersions?.package],
+    ['source Claude plugin', receipt?.sourceVersions?.claudePlugin],
+    ['source Codex plugin', receipt?.sourceVersions?.codexPlugin],
+    ['packed npm artifact', receipt?.artifact?.version],
+  ]);
+  if (identityMismatches.length) failures.push(fail('VERSION_IDENTITY_MISMATCH', identityMismatches.join(', ')));
+  if (receipt?.security?.status !== 'PASS' || receipt?.security?.critical !== 0 || receipt?.security?.high !== 0) {
+    failures.push(fail('SECURITY_NOT_PASS', 'stabilization requires zero critical/high dependency findings'));
+  }
+  if (!(receipt?.qe?.total > 0) || receipt?.qe?.status !== 'PASS' || receipt?.qe?.failed !== 0
+    || receipt?.qe?.skipped !== 0 || receipt?.qe?.passed !== receipt?.qe?.total) {
+    failures.push(fail('QE_NOT_PASS', 'release QE must execute nonzero work with zero failed/skipped tests'));
+  }
+  return { verdict: failures.length === 0 ? 'PASS' : 'FAIL', sha, artifactSha256: digest, failures };
+}
 
 export function evaluateCandidateReceipt(receipt) {
+  if (receipt?.phase === 'stabilization-candidate') return evaluateStabilizationCandidateReceipt(receipt);
   const failures = [];
   const sha = String(receipt?.sha || '');
   const digest = digestOf(receipt);
@@ -23,6 +69,22 @@ export function evaluateCandidateReceipt(receipt) {
   if (!cleanHex(digest, 64)) failures.push(fail('INVALID_ARTIFACT_DIGEST', 'artifact SHA-256 is missing or malformed'));
   if (receipt?.artifact?.sourceSha !== sha) failures.push(fail('ARTIFACT_SOURCE_MISMATCH', 'packed artifact is not bound to the candidate SHA'));
 
+  const version = versionField(receipt?.version);
+  const tag = version ? `v${version}` : null;
+  const identityMismatches = versionIdentityFailures(version, receipt?.tag, [
+    ['source package', receipt?.sourceVersions?.package],
+    ['source Claude plugin', receipt?.sourceVersions?.claudePlugin],
+    ['source Codex plugin', receipt?.sourceVersions?.codexPlugin],
+    ['packed npm artifact', receipt?.artifact?.version],
+    ['bundle brainVersion', receipt?.artifact?.bundle?.brainVersion],
+    ['bundle releaseTag', receipt?.artifact?.bundle?.releaseTag, tag],
+    ['installed Claude host', receipt?.hosts?.claude?.version],
+    ['installed Codex host', receipt?.hosts?.codex?.version],
+  ]);
+  if (identityMismatches.length > 0) {
+    failures.push(fail('VERSION_IDENTITY_MISMATCH', `candidate surfaces must identify one generation: ${identityMismatches.join(', ')}`));
+  }
+
   const vector = receipt?.releaseVector || {};
   if (vector.verdict !== 'PASS' || vector.sha !== sha || vector.unknown !== 0 || vector.skipped !== 0) {
     failures.push(fail('RELEASE_VECTOR_NOT_PASS', 'release vector must PASS on the exact SHA with zero UNKNOWN/SKIP'));
@@ -85,6 +147,20 @@ export function evaluatePublicationReceipt(candidate, publication) {
   const digest = candidateResult.artifactSha256;
   if (publication?.schemaVersion !== 1 || publication?.phase !== 'publication') failures.push(fail('INVALID_PUBLICATION_RECEIPT', 'schemaVersion=1 and phase=publication are required'));
   if (publication?.sha !== sha || publication?.artifactSha256 !== digest) failures.push(fail('PUBLICATION_SEAL_MISMATCH', 'publication does not reference candidate seal'));
+  const version = versionField(candidate?.version);
+  const tag = version ? `v${version}` : null;
+  const identityMismatches = versionIdentityFailures(version, candidate?.tag, [
+    ['publication version', publication?.version],
+    ['npm version', publication?.npm?.version],
+    ['GitHub release tag', publication?.githubRelease?.tag, tag],
+    ['bundle brainVersion', publication?.bundle?.brainVersion],
+    ['bundle releaseTag', publication?.bundle?.releaseTag, tag],
+    ['installed Claude host', publication?.installed?.claude?.version],
+    ['installed Codex host', publication?.installed?.codex?.version],
+  ]);
+  if (identityMismatches.length > 0) {
+    failures.push(fail('PUBLIC_VERSION_IDENTITY_MISMATCH', `public surfaces must identify candidate ${version ?? 'UNKNOWN'}: ${identityMismatches.join(', ')}`));
+  }
   for (const surface of ['npm', 'githubRelease']) {
     const item = publication?.[surface];
     if (item?.sha !== sha || item?.artifactSha256 !== digest) failures.push(fail('PUBLIC_ARTIFACT_MISMATCH', `${surface} differs from candidate seal`));