ruvnet-brain 3.9.134-dev → 4.0.1

package/plugin/hooks/hook-contracts.json

@@ -0,0 +1,77 @@
+{
+  "_note": "OUT-OF-SHIM HOOK CONTRACTS (ADR-055 §6). The per-hook contract — event, matcher, layer, codeRoot, mode, offBehavior, failureBehavior, timeout, budgets, state, dependencies, reachesStrangers, owner — is carried NATIVELY by plugin/scripts/hook-shim.mjs's dispatch table for every shim-routed registration. Everything registered outside that table has nowhere to carry it, which is how the whole non-plugin two thirds of this machine's mesh ended up with no declared answer to 'what happens when the brain is off' (ADR-055 F14). This file is the other half: a checked-in contract for every registration this REPO owns but does not route through the shim. scripts/hook-registry.mjs reads both, and tests/unit/hook-registry-lint.test.mjs fails any repo-owned registration absent from both — so a new one cannot be added silently. SCOPE, deliberately: this file declares only registrations THIS repo owns (plugin/hooks/hooks.json and this project's .claude/settings.json). It does NOT declare contracts for the machine owner's ~/.claude/settings.json or for third-party plugins — those are not ours to specify, and inventing an offBehavior for someone else's hook would be exactly the fiction the lint exists to prevent. They stay visible as documented machine-local findings in the lint's expected-red block.",
+  "_version": 1,
+  "contracts": [
+    {
+      "id": "project:version-bump-gate",
+      "layer": "project",
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "commandIncludes": "version-bump-gate.sh",
+      "mode": "blocking",
+      "offBehavior": "run",
+      "offReason": "ADR-054's discriminator, applied literally: this is an HONESTY wall, not a retrieval feature. It refuses a commit that changes behaviour without bumping the version — the signal every user's updater reads. Nothing about that becomes acceptable because the owner switched the retrieval brain off, and the gate reads git state only: no corpus, no network, no brain.",
+      "failureBehavior": "fail-open — a crash or unparseable payload permits the command and records degraded health; malfunction is never a decision (ADR-055 §1.2)",
+      "timeoutSeconds": 5,
+      "warmP95BudgetMs": 50,
+      "coldBudgetMs": 500,
+      "stdoutCapBytes": 4096,
+      "stateRead": ["git HEAD", "plugin/.claude-plugin/plugin.json"],
+      "stateWritten": [],
+      "dependencies": ["bash", "git"],
+      "reachesStrangers": false,
+      "owner": "ruvnet-brain (this repo only — ADR-053; it enforces a rule that is true here and nowhere else)",
+      "note": "Project-scoped on purpose: it lived in the GLOBAL settings until 2026-07-14, taxing every Bash call in 34+ projects with a rule true in one."
+    }
+  ],
+  "matcherAllowlist": [
+    {
+      "layer": "plugin",
+      "event": "PreToolUse",
+      "matcher": "Write|Edit|Bash",
+      "handler": "hijack-ruvnet.sh",
+      "reason": "UNANCHORED, known (ADR-055 F4). Claude Code SEARCHES the tool name, so this also selects MultiEdit, NotebookEdit, TodoWrite and BashOutput — an advisory hook firing on four tools nobody chose. Advisory, so the blast radius is wasted latency rather than a wrong refusal.",
+      "retiredBy": "ADR-055 build item 3 (four plane dispatchers) — registration changes are SHELL changes and item 2 (battery v2) must land first, so this is recorded, not fixed out of order."
+    },
+    {
+      "layer": "plugin",
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "handler": "verify-interface.sh",
+      "reason": "UNANCHORED, known (ADR-055 F4/F12): also selects BashOutput. One of three blocking walls on the same event that each re-parse the same payload — the parse-once execution-guard is the real fix, not six anchor characters.",
+      "retiredBy": "ADR-055 build item 3 (execution-guard.mjs — ONE registration, ONE parse)"
+    },
+    {
+      "layer": "plugin",
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "handler": "design-wall.sh",
+      "reason": "UNANCHORED, known (ADR-055 F4/F12) — same pair as verify-interface above, same fix.",
+      "retiredBy": "ADR-055 build item 3 (execution-guard.mjs)"
+    },
+    {
+      "layer": "plugin",
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit|Bash",
+      "handler": "learn-capture.sh",
+      "reason": "UNANCHORED, known (ADR-055 F4): NotebookEdit reaches the learning pipeline by substring accident, never by decision. Advisory.",
+      "retiredBy": "ADR-055 build item 3"
+    },
+    {
+      "layer": "plugin",
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit",
+      "handler": "md-stamp.mjs",
+      "reason": "UNANCHORED, known (ADR-055 F4): same NotebookEdit substring accident. Advisory.",
+      "retiredBy": "ADR-055 build item 3"
+    },
+    {
+      "layer": "project",
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "handler": "version-bump-gate.sh",
+      "reason": "UNANCHORED, known: also selects BashOutput, which carries no command to gate, so the gate reads an empty payload and permits. Wasted spawn, not a wrong refusal.",
+      "retiredBy": "ADR-055 build item 3, together with the plugin-layer Bash walls it sits beside"
+    }
+  ]
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,203 @@
+{
+  "_note": "STABLE SPINE (ADR-023): every hook routes through hook-shim.mjs, which resolves the ACTIVE generation from ~/.cache/ruvnet-brain/active.json per invocation. This file is boot-frozen, so matcher, command, and dispatch-mode changes require restart classification. Advisory hooks keep `|| true` and can never block a turn. FOUR blocking hooks remain unguarded because their exit codes are their contract: route-dispatch, design-wall, unprompted-speech, and protect-state. Issue #48 demoted verify-interface to advisory-only: raw shell reconstruction may suggest the structured ruvnet_cli_help/ruvnet_cli_run boundary but can never authorize or deny execution. protect-state remains a blocking offBehavior:'run' consent guard. continuation-gate remains advisory with offBehavior:'run'.",
+  "_platform": "posix",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" session-start || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" session-start || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" ground-ruvnet || true",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" unprompted-speech UserPromptSubmit",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" hijack-ruvnet || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Task|Agent)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" route-dispatch",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" ground-before-write || true",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" protect-state",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" verify-interface || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" design-wall",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Write|Edit|MultiEdit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" unprompted-speech PreToolUse-write",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" unprompted-speech PreToolUse-bash",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(Task|Agent)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" routing-outcome || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(?:.*__)?search_ruvnet$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" grounding-stamp || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-capture || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" md-stamp || true",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" signal-watch || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-flush || true",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" continuation-gate || true",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/mcp/server.mjs

@@ -37,7 +37,7 @@ import { callManagedCli, MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
 
 const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
 const KB = process.env.RUVNET_BRAIN_KB || path.join(BRAIN_HOME, 'kb');
-const CHILD_MCP = path.join(KB, 'forge-mcp-all.mjs');
+const CHILD_MCP = process.env.RUVNET_BRAIN_CHILD_MCP || path.join(KB, 'forge-mcp-all.mjs');
 const ACTIVE = path.join(BRAIN_HOME, 'active.json');
 const LEASES = path.join(BRAIN_HOME, 'leases');
 const LEASE = path.join(LEASES, `mcp-${process.pid}.json`);
@@ -95,10 +95,33 @@ let child = null;            // { proc, generation, nextId, pending: Map<childId
 let pendingCount = 0;        // client tools/call requests currently in flight (drain gate for swaps)
 let childRetirement = Promise.resolve();
 let childStartup = null;
+let childIdleTimer = null;
 const CHILD_TERM_GRACE_MS = 3_000;
 const CHILD_INIT_TIMEOUT_MS = Number(process.env.RUVNET_BRAIN_INIT_TIMEOUT_MS) || 60_000;
+const CHILD_IDLE_MS = Number(process.env.RUVNET_BRAIN_CHILD_IDLE_MS) || 30 * 60_000;
+
+function clearChildIdleTimer() {
+  if (childIdleTimer) clearTimeout(childIdleTimer);
+  childIdleTimer = null;
+}
+
+function armChildIdleTimer(c = child) {
+  clearChildIdleTimer();
+  if (!c || CHILD_IDLE_MS <= 0) return;
+  childIdleTimer = setTimeout(() => {
+    childIdleTimer = null;
+    if (child !== c) return;
+    if (pendingCount > 0 || c.pending.size > 0 || childStartup) {
+      armChildIdleTimer(c);
+      return;
+    }
+    void killChild(`idle for ${CHILD_IDLE_MS / 1000}s`);
+  }, CHILD_IDLE_MS);
+  childIdleTimer.unref?.();
+}
 
 function killChild(reason) {
+  clearChildIdleTimer();
   if (!child) return childRetirement;
   const c = child; child = null;
   for (const [, p] of c.pending) p.reject(new Error(`brain worker ${reason}`));
@@ -158,6 +181,7 @@ async function ensureChild() {
         await killChild('failed initialize');
         throw new Error(`brain worker failed to initialize: ${e.message}`);
       }
+      armChildIdleTimer(c);
       return c;
     })();
   }
@@ -191,10 +215,11 @@ async function onChildTimeout(method, timeoutMs) {
   }
 }
 
-// Overridable so the outage path above can actually be TESTED — a 120s default is untestable, and
-// an untestable failure path is how this one went four days reporting "ok" while it was down. Also
-// genuinely useful in the field: a slow machine can raise it, and a CI runner can lower it.
-const CALL_TIMEOUT_MS = Number(process.env.RUVNET_BRAIN_CALL_TIMEOUT_MS) || 120_000;
+// Overridable so the outage path above can actually be TESTED. The default matches the installer's
+// real cold-start smoke budget: measured 153s after a cache repair on 2026-07-29. A 120s parent
+// deadline killed the model just before it became usable and forced every retry to start cold.
+// 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) {
   return new Promise((resolve, reject) => {
@@ -225,7 +250,10 @@ async function handleClient(msg) {
         if (c) {
           try {
             const r = await childRequest(c, 'tools/list', {}, 15_000);
-            if (r.result?.tools?.length) return clientOk(id, { ...r.result, tools: withLocalTools(r.result.tools) });
+            if (r.result?.tools?.length) {
+              armChildIdleTimer(c);
+              return clientOk(id, { ...r.result, tools: withLocalTools(r.result.tools) });
+            }
           }
           catch { /* fall through to the static declaration */ }
         }
@@ -259,6 +287,7 @@ async function handleClient(msg) {
         return clientOk(id, { content: [{ type: 'text', text: `search_ruvnet error: ${e.message}` }], isError: true });
       } finally {
         pendingCount--;
+        armChildIdleTimer(c);
       }
     }
     default: