ruvnet-brain 4.0.1 → 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) => {
@@ -147,16 +172,22 @@ function killChild(reason) {
 async function ensureChild() {
   const gen = currentGeneration();
   if (child && child.generation !== gen && pendingCount === 0) await killChild('superseded by a newer generation');
+  // A concurrent initialize/tools-list/tools-call must join the same readiness promise. Returning
+  // `child` while its private initialize or model warmup is still running advertises a half-ready
+  // worker and charges cold-start to the first user call.
+  if (childStartup) return childStartup;
   if (child) return child;
   await childRetirement;
   if (!fs.existsSync(CHILD_MCP)) return null;
 
   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; }
@@ -167,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;
@@ -176,11 +214,29 @@ async function ensureChild() {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
           clientInfo: { name: 'ruvnet-brain-shell', version: SERVER_INFO.version },
-        }, 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.
+        // An older initialized worker is usable (its first query may be cold); any other warmup
+        // failure still fails closed.
+        const warmupUnsupported = warmed.error?.code === -32601
+          || /method not found/i.test(String(warmed.error?.message || ''));
+        if (!warmupUnsupported && (warmed.error || warmed.result?.ready !== true)) {
+          throw new Error(warmed.error?.message || 'brain worker did not confirm warm readiness');
+        }
       } 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;
     })();
@@ -221,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'); }
@@ -241,23 +297,16 @@ async function handleClient(msg) {
   if (id === undefined || id === null) return; // notifications need no answer
   switch (method) {
     case 'initialize':
+      // MCP initialize itself stays protocol-fast; normal clients request tools/list immediately
+      // afterwards, which joins this readiness promise and does not receive the tool declaration
+      // until the worker's query embedder and cross-encoder are warm.
+      void ensureChild().catch((e) => {
+        console.error(`[ruvnet-brain] worker warmup failed during initialize: ${e.message}`);
+      });
       return clientOk(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });
     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': {
@@ -300,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/detach.mjs

@@ -107,11 +107,25 @@ if (!SUPERVISOR) {
         ? path.join(process.env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
         : 'powershell.exe';
       const quotePs = (value) => `'${String(value).replaceAll("'", "''")}'`;
+      // Start-Process has its own standard-stream boundary. On GitHub's packed PowerShell install
+      // path the SessionStart body finished but the external checker never received `close` before
+      // its 5s watchdog — consistent with a descendant retaining a capture handle, though that job
+      // did not instrument exact handle ownership. Redirect both streams to distinct files at the
+      // native boundary so the supervisor cannot inherit the hook's capture streams; redirecting
+      // only this short Node wrapper's stdio does not establish that contract for its grandchild.
+      const supervisorOut = logPath && logPath !== '-'
+        ? `${logPath}.supervisor.stdout`
+        : path.join(os.tmpdir(), `ruvnet-brain-detach-supervisor-${process.pid}.stdout`);
+      const supervisorErr = logPath && logPath !== '-'
+        ? `${logPath}.supervisor.stderr`
+        : path.join(os.tmpdir(), `ruvnet-brain-detach-supervisor-${process.pid}.stderr`);
       const launch = [
         'Start-Process',
         '-FilePath', quotePs(process.execPath),
         '-ArgumentList', `@(${quotePs(SELF)},${quotePs('--payload-env')})`,
         '-WindowStyle', 'Hidden',
+        '-RedirectStandardOutput', quotePs(supervisorOut),
+        '-RedirectStandardError', quotePs(supervisorErr),
       ].join(' ');
       child = spawn(powershell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', launch], {
         detached: true,

package/plugin/scripts/first-session-worker.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// One detached first-session lifecycle worker: seed the Stable Spine, then perform the update
+// heartbeat the seed used to race. Keeping both operations in one worker preserves ADR-054's
+// "Brain OFF still receives fixes" contract without making SessionStart launch two detachers.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const [updateApply, hostUpdate, versionLog] = process.argv.slice(2);
+if (![updateApply, hostUpdate, versionLog].every((value) => typeof value === 'string' && value)) {
+  process.stderr.write('usage: first-session-worker.mjs <update-apply.mjs> <host-update.mjs> <version-log>\n');
+  process.exit(2);
+}
+
+const seed = spawnSync(process.execPath, [updateApply, '--seed'], {
+  env: process.env,
+  stdio: 'inherit',
+});
+if (seed.error || seed.status !== 0) {
+  process.stderr.write(`[ruvnet-brain] first-session seed failed: ${seed.error?.message || `exit ${seed.status}`}\n`);
+  process.exit(1);
+}
+
+const check = spawnSync(process.execPath, [hostUpdate, '--check'], {
+  env: process.env,
+  encoding: 'utf8',
+});
+const version = String(check.stdout || '').trim();
+if (!check.error && check.status === 0 && /^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/.test(version)) {
+  fs.mkdirSync(path.dirname(versionLog), { recursive: true });
+  const temporary = `${versionLog}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, `${version}\n`);
+  fs.renameSync(temporary, versionLog);
+}
+
+// Network failure must not undo a successful seed. The 15-minute heartbeat stamp lets the normal
+// SessionStart path retry later, while the current runtime remains valid and usable.
+process.exit(0);

package/plugin/scripts/ground-ruvnet.sh

@@ -121,7 +121,7 @@ check_memory_db() {
 for _db in .swarm/agentdb-memory.db .swarm/memory.db .claude/memory.db; do
   check_memory_db "$_db" && break
 done
-if [ "$MEM_STATE" = "off" ]; then
+if [ "$MEM_STATE" != "on" ]; then
   _common_git=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
   case "$_common_git" in
     */.git)
@@ -136,6 +136,15 @@ if [ "$MEM_STATE" = "off" ]; then
       ;;
   esac
 fi
+if [ "$MEM_STATE" != "on" ] && [ -n "${HOME:-}" ] && [ "$PWD" != "$HOME" ]; then
+  for _db in \
+    "$HOME/.swarm/agentdb-memory.db" \
+    "$HOME/.swarm/memory.db" \
+    "$HOME/.claude/memory.db"
+  do
+    check_memory_db "$_db" && break
+  done
+fi
 unset _db
 unset _common_git _primary_root
 # RUNNING version (this session's loaded plugin) vs STAGED version (marketplace copy on disk).
@@ -162,11 +171,10 @@ if [ "$RUFLO_STATE" = "yes" ] && [ "$MEM_STATE" = "off" ]; then
 This project runs the Ruflo stack but AgentDB persistent project memory is NOT set up (.swarm/memory.db does not exist) — decisions made here are being lost between sessions. rUv's default is memory ON. If you have not already offered this session, offer ONCE, plainly and warmly: "One thing I noticed: this project doesn't have persistent memory turned on — AgentDB would let me carry decisions and context across sessions instead of starting cold each time. Want me to turn it on and wire it up?" On a yes, set it up with the ruflo tools you have (a first memory_store write creates the store) and confirm with the real file path. If they decline, respect it for the rest of the session — the status line keeps them informed without nagging.
 EOF
 fi
-if [ "$RUFLO_STATE" = "yes" ] && [ "$MEM_IDLE" = "1" ]; then
-  cat <<'EOF'
-AgentDB memory exists here but has NOT been written in over 90 minutes. If meaningful decisions HAVE happened this session, the memory hooks may be miswired — do what Ruv would: probe it. Quietly store a session checkpoint via the ruflo memory tools, then verify .swarm/memory.db's mtime actually changed. If the write fails or the file doesn't move, tell the user plainly: "your project memory isn't capturing this session — the hooks look miswired; want me to fix them?" If this session genuinely hasn't produced decisions yet, stay silent — idle is normal at a session's start.
-EOF
-fi
+# A stale mtime is not a user-facing event. SessionEnd/PreCompact own capture;
+# their persistence receipt must fail closed at the write boundary. Emitting a
+# UserPromptSubmit instruction here interrupted unrelated work and still could
+# not prove that the store command wrote the canonical database.
 
 # ── Self-learning flywheel (ruflo ≥3.24, ADR-176) — OFFER it, never switch it on for them ────────
 # Opt-in is a single env var; `harnessLoopOptedIn()` in @claude-flow/cli reads process.env directly,
@@ -375,6 +383,7 @@ This task touches the RuvNet / rUv stack. Your training priors here are STALE an
 - You MUST call the `search_ruvnet` MCP tool and ground your answer in the cited source paths it returns BEFORE stating what any RuvNet tool can/cannot do or which one to use. Asserting a RuvNet capability from memory, without a cited source path, is an error — do not do it.
 - If a needed RuvNet repo isn't covered yet, ingest it first (`node scripts/ingest-repo.mjs --name <repo>`) rather than guessing.
 - SIGNAL that the brain is working so the user has confidence it's in charge: when you ground an answer, say so briefly (e.g. "Grounding in rUv's source…" → cite the path). Silent grounding leaves the user unsure it's even on.
+- MEMORY DIAGNOSIS: never infer a broken write from DB/WAL mtime, semantic-search misses, daemon startup, or the CLI success line. Prove it against ONE canonical absolute path: unique-key `ruflo memory store --path <project>/.swarm/memory.db` → exact-key `ruflo memory retrieve --path ...` → exact SQL row. Only then call it miswired.
 EOF
 fi
 
@@ -398,6 +407,7 @@ This is a build / change request — run THE PLAYBOOK (the standing build playbo
 - Read the actual files in THEIR repo this touches — what pattern do they already use? what would duplicate?
 - Call `search_ruvnet` for what the feature technically DOES — never trust memory about what the corpus has.
 - Check project memory (ruflo memory search / AgentDB) for prior decisions on this area.
+- If memory looks broken, use the exact-path store → exact-key retrieve → exact SQL proof; never diagnose from semantic search, mtime, daemon startup, or a success message.
 ⛔ NO SILENT SUBSTITUTION: use the real RuvNet tool, or say out loud that you're hand-rolling and why.
 Senior partner: one plan, momentum, end with real work.
 EOF

package/plugin/scripts/hook-shim.mjs

@@ -75,23 +75,23 @@ catch (e) { BRAIN_OFF = !(e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')); }
 //               stops a subagent fan-out inheriting an expensive model; design-wall stops an
 //               ungraded surface shipping; protect-state guards the user's own consent record.
 //               None becomes acceptable because retrieval is off.
-//   'partial' — the hook splits INTERNALLY. session-start still runs the auto-updater heartbeat, the
+//   'partial' — the hook splits INTERNALLY. session-start-core still runs the auto-updater heartbeat, the
 //               GONG health alarm and the SLA banner (an off machine must still receive fixes,
 //               otherwise the fix for an off-state bug can never arrive) while suppressing every
 //               advertising byte. The snapshot is forwarded as RUVNET_BRAIN_OFF so the body reads
 //               ONE resolved answer instead of racing the filesystem again mid-run.
 const TABLE = {
-  'session-start':    { file: 'session-start.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'partial' },
-  'ground-ruvnet':    { file: 'ground-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
+  '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', 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' },
@@ -102,7 +102,7 @@ const TABLE = {
   // SEPARATE process, SEPARATE cadence) resolves later via `gh run list`. offBehavior 'silence' per
   // the ADR's explicit instruction: this plane observes and advises, it never guards money or
   // honesty on its own — the git-push debt it opens is only ever SURFACED (never gated) by
-  // session-start.sh, and that surfacing already lives under session-start's own 'partial' contract.
+  // session-start-core.mjs, and that surfacing already lives under SessionStart's 'partial' contract.
   'signal-watch':     { file: 'signal-watch.mjs',    interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   'routing-outcome':  { file: 'routing-outcome-capture.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run' },
   // The unprompted-speech chokepoint (ADR-040 / DDD-0004). ONE runtime is the sole writer of
@@ -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;
       }
@@ -247,15 +247,15 @@ function runHook(file) {
   // The unprompted-speech chokepoint uses this to receive the CC event name:
   // `hook-shim.mjs unprompted-speech UserPromptSubmit` → `unprompted-runtime.mjs UserPromptSubmit`.
   const extraArgs = process.argv.slice(3);
-  // Forward the ONE resolved OFF snapshot to a 'partial' body (ADR-054 §4). The body could stat the
-  // sentinel itself — and session-start.sh still does, because it is also invoked directly, outside
-  // this shim, by tests and by a bare install. Passing it means the two readings cannot disagree
-  // within a single invocation if the user flips the switch while the hook is mid-run.
+  // Forward the ONE resolved OFF snapshot to a 'partial' body (ADR-054 §4). The native SessionStart
+  // core also reads the sentinel because the POSIX compatibility launcher and bare installs invoke
+  // it outside this shim. Passing the snapshot means the two readings cannot disagree within one
+  // invocation if the user flips the switch while the hook is mid-run.
   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/learn-capture.sh

@@ -9,6 +9,21 @@
 
 set -uo pipefail
 
+# One policy source for both capture and flush. `off` means zero bytes written. `project` keeps the
+# trajectory queue under this project's .swarm directory; `user` preserves the cross-project learner
+# introduced by ADR-0017. Tests and managed hosts may pass an already-resolved snapshot in
+# RUVNET_LEARNING_SCOPE so the two halves cannot disagree during one hook invocation.
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+SCOPE="${RUVNET_LEARNING_SCOPE:-}"
+if [ -z "$SCOPE" ] && [ -f "$HERE/runtime-preferences.mjs" ] && command -v node >/dev/null 2>&1; then
+  SCOPE=$(node "$HERE/runtime-preferences.mjs" --learning-scope 2>/dev/null) || SCOPE=""
+fi
+case "$SCOPE" in
+  off) exit 0 ;;
+  user|project) ;;
+  *) SCOPE="project" ;;
+esac
+
 # BOUNDED READ. An unqualified `read` waits forever on a stdin that is opened and never closed, and
 # an unbounded accumulator turns a large payload into an unbounded regex scan. Claude Code always
 # writes the payload and closes, so neither costs a normal turn — which is exactly why a hook that
@@ -104,7 +119,11 @@ re_s='"session_id"[[:space:]]*:[[:space:]]*"([^"\]*)"'
 # keeping `.` would let a crafted id survive as `..`-shaped debris in a filename for no benefit.
 SID="${SID//[^A-Za-z0-9_-]/}"           # a filename COMPONENT, never a path
 [ -n "$SID" ] || SID="default"
-DIR="$HOME/.cache/ruvnet-brain/learn"
+if [ "$SCOPE" = "user" ]; then
+  DIR="$HOME/.cache/ruvnet-brain/learn"
+else
+  DIR="$PWD/.swarm/ruvnet-brain-learn"
+fi
 # Owner-only (0700 dir / 0600 file). This queue was 0644 inside a 0755 dir: on macOS every local
 # account is normally in `staff`, so any other user on a shared or corporate machine could read it.
 ( umask 077 && mkdir -p "$DIR" ) 2>/dev/null || exit 0
@@ -147,8 +166,8 @@ if [ "$LINES" -ge "$HEARTBEAT_EVERY" ]; then
   LAST=$(cat "$STAMP" 2>/dev/null || echo 0)
   if [ $((NOW - LAST)) -ge 60 ]; then
     echo "$NOW" > "$STAMP" 2>/dev/null || true
-    FLUSH="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/ruvnet-brain/plugin}/scripts/learn-flush.mjs"
-    [ -f "$FLUSH" ] && (nohup node "$FLUSH" >/dev/null 2>&1 &) || true
+    FLUSH="$HERE/learn-flush.mjs"
+    [ -f "$FLUSH" ] && (RUVNET_LEARNING_SCOPE="$SCOPE" nohup node "$FLUSH" >/dev/null 2>&1 &) || true
   fi
 fi
 exit 0

package/plugin/scripts/learn-flush.mjs

@@ -13,8 +13,15 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { readStdinBounded } from './hook-input.mjs';
+import { loadRuntimePreferences } from './runtime-preferences.mjs';
 
 const HOME = os.homedir();
+const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || process.cwd();
+const configuredScope = process.env.RUVNET_LEARNING_SCOPE
+  || loadRuntimePreferences({ cwd: PROJECT }).values.learningScope;
+const LEARNING_SCOPE = ['off', 'project', 'user'].includes(configuredScope)
+  ? configuredScope : 'project';
+if (LEARNING_SCOPE === 'off') process.exit(0);
 
 // THE SESSION ID COMES OFF THE PAYLOAD, exactly as it does in learn-capture.sh (fixed 2026-07-27).
 //
@@ -37,8 +44,12 @@ async function payloadSessionId() {
 }
 // A filename COMPONENT, never a path — the payload is untrusted input.
 const SID = ((await payloadSessionId()) || process.env.CLAUDE_SESSION_ID || '').replace(/[^A-Za-z0-9_-]/g, '') || 'default';
-const QUEUE = process.env.LEARN_QUEUE || path.join(HOME, '.cache/ruvnet-brain/learn', `session-${SID}.jsonl`);
+const QUEUE_ROOT = LEARNING_SCOPE === 'user'
+  ? path.join(HOME, '.cache', 'ruvnet-brain', 'learn')
+  : path.join(PROJECT, '.swarm', 'ruvnet-brain-learn');
+const QUEUE = process.env.LEARN_QUEUE || path.join(QUEUE_ROOT, `session-${SID}.jsonl`);
 const RUFLO = path.join(HOME, '.npm-global/bin/ruflo');
+const RUFLO_ENV = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
 const MAX_ACTIONS = 8; // bound the work so SessionEnd stays fast
 
 // THE DEADLINE. SessionEnd's registered timeout is 30s (plugin/hooks/hooks.json) and this hook fires
@@ -100,8 +111,14 @@ for (let i = 0; i < actions.length; i++) {
     ? ['hooks', 'post-command', '-c', s.action, '-s', 'true']
     : ['hooks', 'post-edit', '-f', s.action, '-s', 'true', '-o', 'session edit'];
   try {
-    // cwd: HOME → writes the GLOBAL per-user learner (cross-project), not a project-local one.
-    execFileSync(RUFLO, args, { cwd: HOME, stdio: 'ignore', timeout: Math.min(6000, remaining) });
+    // One command, two real Ruflo scopes: project cwd keeps patterns local; HOME retains the
+    // cross-project SONA learner for users who explicitly chose `user`.
+    execFileSync(RUFLO, args, {
+      cwd: LEARNING_SCOPE === 'user' ? HOME : PROJECT,
+      env: RUFLO_ENV,
+      stdio: 'ignore',
+      timeout: Math.min(6000, remaining),
+    });
     fed++;
   } catch { /* best-effort — one slow/failed record must not stall session end */ }
 }
@@ -129,7 +146,7 @@ if (fed > 0 || allDistinct.length === 0) {
   console.log(`learn-flush: 0/${actions.length} fed (ruflo hooks failing?) — queue KEPT for retry next session-end`);
 }
 if (process.argv.includes('--sync')) {
-  console.log(`learn-flush: fed ${fed}/${actions.length} distinct actions to the global learner`
+  console.log(`learn-flush: fed ${fed}/${actions.length} distinct actions to the ${LEARNING_SCOPE} learner`
     // Say the deadline out loud when it fires. A budget that silently truncates reads as "that was
     // all there was", which is the same lie as the count cap that preceded it.
     + (stoppedAt < actions.length ? `; STOPPED at ${stoppedAt}/${actions.length} on the ${DEADLINE_MS}ms deadline` : '')