ruvnet-brain 3.9.134-dev → 4.0.2

package/plugin/commands/rvbc.md

@@ -0,0 +1,79 @@
+---
+description: "RvBC — RuvNet Brain Console. Opens the live console page: your whole RuvNet stack on one page — what's installed, what your AI learned, one-click reversible fixes. Read-only until you click. (Also: /rvcb, /brain-console — all the same thing.)"
+updated: 2026-07-20
+---
+
+Launch the **RuvNet Brain Console** for the user. Same console as `/ruvnet-brain:configure`,
+`/rvcb`, and `/brain-console` — every spelling lands here, so never tell the user they typed it wrong.
+
+## The contract you are keeping
+
+The page **opens immediately and scans itself while they watch.** The server never blocks: a cold or
+new-project read is answered in milliseconds with "measuring…", the page keeps its skeletons and
+narrates the wait, and each card fills in as its own measurement lands. A chip in the header says how
+old the picture is and re-measures when clicked.
+
+So there is nothing to wait for and nothing to warn them about. **Your entire job is: say one
+sentence, start the server in the background, hand over the URL, and get out of the way.**
+
+## 1. SPEAK FIRST — one short sentence, before any tool call
+
+Your FIRST output — before any tool call, any file read, any search — is one warm line saying you are
+opening it now and it will scan itself live in their browser. Something in the spirit of:
+
+> "Opening your console now — it'll come up right away and scan your setup live while you watch."
+
+Say it like a person, not a status bar. **Do not** promise 20 seconds, a minute, or any duration: the
+page carries its own timing now, and a number invented here is a number the page will contradict.
+
+## 2. Find the installed runtime
+
+Use `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+A current-repository copy is allowed only in an explicit developer checkout. Never guess a
+`~/Code/ruvnet-brain` path: the installer persists this runtime for clean users.
+
+## 3. Start it in the BACKGROUND and open the browser
+
+```
+node <repo>/scripts/onboarding-console.mjs --serve --open
+```
+
+**`run_in_background: true`, ALWAYS — never in the foreground.** This is a server: it does not exit,
+so a foreground run hangs the tool call until the 120-second timeout and turns an instant page into
+two minutes of dead air. It binds `127.0.0.1` only and prints `http://127.0.0.1:7411/` within about a
+third of a second.
+
+**Then post the URL immediately.** Do not poll the log, do not wait for a scan, do not check whether
+the data has landed — the page reports its own progress and none of it is visible from here.
+
+**If it reports it is already running**, that is a success, not an error: open the URL yourself with
+`open "http://127.0.0.1:<port>/"`. One honest caveat, worth half a sentence if it comes up — a
+console that is already running is serving the project it was *launched* from, so if they want this
+project's view they can stop that one (`^C` in its terminal) and run this again.
+
+## 4. Hand it over and stop
+
+Give them the URL as a clickable line, and one warm sentence: the page is **read-only until you
+click**, every machine change is **explained first and reversible**, and Settings save at the user
+level only. Worth naming once: the brain's on/off switch is the first card on the page, and the
+header chip says how fresh the reading is and re-measures if they click it.
+
+## 5. If it errors
+
+Report it plainly — the real error, not a guess — and offer to fix it. Never leave them staring at
+a dead tab wondering whether it is still loading.
+
+---
+
+## Things NOT to do before the page is open
+
+Each of these has cost a real user real minutes of silence, and not one of them is needed to open a
+local web page:
+
+- **No knowledge search, no memory recall, no source grounding, no repo exploration.** A cold
+  embedding-model load alone is allowed up to 180 seconds.
+- **No model selection or routing work.**
+- **No reading this repo to "check" anything first.** Find the script, run it.
+
+Do **not** narrate the machine yourself afterwards; the page is the mirror. Your job is to open it,
+say one sentence, and get out of the way.

package/plugin/commands/rvcb.md

@@ -0,0 +1,16 @@
+---
+description: "RvCB — RuvNet Brain Console (same console as /rvbc, /brain-console, and /ruvnet-brain:configure — every spelling works). Opens the live console page: your whole RuvNet stack on one page. Read-only until you click."
+updated: 2026-07-20
+---
+
+`/rvbc`, `/rvcb`, `/brain-console`, and `/ruvnet-brain:configure` are equally valid names. Never
+correct the user's spelling.
+
+1. Say: "Opening it now; it scans live while you watch."
+2. Use `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository copy is allowed only for an explicit developer checkout.
+3. Run `node <resolved-script> --serve --open` in the background.
+4. Give the URL immediately. Never promise a duration; the page reports its own progress.
+
+An already-running server is success. It is read-only until the user clicks; changes must be
+explained and reversible. If the script or server is unavailable, report the exact failure.

package/plugin/commands/whats-new.md

@@ -0,0 +1,57 @@
+---
+description: "What's new in RuvNet Brain — the big things in the current MAJOR release (4.0), in plain English. Not the point-release churn — the headline changes since 3.x. Ends by offering to open the Console so you can see it live."
+updated: 2026-07-25
+---
+
+# RuvNet-Brain: what's new
+
+The user wants the headline story of the **major** release they're on — the 4.0-vs-3.0 kind of change,
+**not** the "3.9.x → 3.9.y" point-release churn. Deliver it warmly and honestly, then offer the Console.
+
+**First, ground — never recite this from memory (it drifts every release):**
+1. Read the running version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`. State it honestly.
+   **Do NOT claim "you're on 4.0"** unless the version literally starts with `4.` — per ADR-042 the
+   number stays `3.9.x-dev` until the 4.0 line is field-verified. The honest framing is: *"these are the
+   4.0-line enhancements, and you already have them — the version stamps to 4.0 once they're proven in
+   real use."*
+2. Read `docs/RELEASE-NOTES-4.0.md` (the curated highlights + its VERSION STATUS banner). Its content is
+   the source of truth for what follows — summarize it, don't invent beside it, and carry its honest
+   version framing.
+
+**Then tell them what the 4.0 line is — the honest headline (adapt to the notes file; do NOT overclaim):**
+
+The 4.0 line is where the brain got **honest, legible, fast, and self-measuring** — landing now in the
+3.9.x releases. The big things:
+
+- **The Console is the front door.** One live local page (type `/rvbc`) — your whole RuvNet stack on
+  one screen: what's installed, what the AI has actually learned from *your* projects (real memories +
+  distilled lessons, drill-down to the verbatim cards), which subscription pays for what, and one-click
+  **reversible** fixes for anything stale. New in 4.0: a plain-English explainer on every card, each
+  suggestion labelled with its blast radius (*just this project* vs *every project*), safe on/off
+  checkboxes that only appear where the undo is proven, and a terminal-first install.
+- **It will not lie about your machine.** Every number is measured live; "we couldn't check" never
+  renders as "off"; one project's state can never leak into another's view.
+- **Fast, and it tells you when it's ready.** The console and tips page paint in well under a second;
+  on a first scan it shows a countdown and then says *"it's live — take a look at your page,"* so you're
+  never staring at nothing.
+- **It measures itself now.** The brain records when it offered help and whether you acted on it, so it
+  can *prove* it's improving rather than assert it. **Be honest that this has only just started
+  collecting** — the proof accrues as you use it; it is not a claim of "proven better" yet.
+- **It learns across your projects.** A lesson proven in one project can be promoted to your global
+  brain and now survives an update (tested against the real updater, not argued).
+- **Runs on your account, cheapest capable model.** The QE suite and routing use your Claude account,
+  not an API key, at the least-powerful model that does the job.
+
+**Then offer the Console (the point of the whole thing):**
+
+End by offering to open it: *"Want me to open the Console so you can see all of this live? Just say the
+word — or type `/rvbc`."* If they say yes, follow `rvbc.md` in this same directory exactly (including the
+warm heads-up about the ~20s scan).
+
+**Honesty rules for this command (same as the product):**
+- If `docs/RELEASE-NOTES-4.0.md` is missing, say the notes aren't written yet and summarize from what
+  you can verify — never fabricate a highlight.
+- Never claim a metric ("40% better", "95/100") the release has not independently earned. The self-
+  measurement is new and still filling; say so plainly.
+- This is the MAJOR story only. If the user wants the point-release detail, point them at the repo's
+  release notes / `git log`.

package/plugin/hooks/codex-hooks.json

@@ -0,0 +1,160 @@
+{
+  "description": "RuvNet Brain lifecycle hooks for Codex. Every command enters through a generation-independent wrapper and adapts the shared Brain hook bodies to Codex contracts.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" session-start",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" ground-ruvnet",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" unprompted-speech UserPromptSubmit",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "^(Bash|Edit|Write|exec_command|functions\\.exec_command|functions__exec_command|apply_patch)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" hijack-ruvnet",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Agent|spawn_agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" route-dispatch",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Edit|Write|apply_patch)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" ground-before-write",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" protect-state",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" unprompted-speech PreToolUse-write",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Bash|exec_command|functions\\.exec_command|functions__exec_command)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" verify-interface",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" design-wall",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" unprompted-speech PreToolUse-bash",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(?:.*__)?search_ruvnet$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" grounding-stamp",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Bash|Edit|Write|exec_command|functions\\.exec_command|functions__exec_command|apply_patch)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" learn-capture",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Edit|Write|apply_patch)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" md-stamp",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "^(Bash|exec_command|functions\\.exec_command|functions__exec_command)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" signal-watch",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "other",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" learn-flush",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.cache/ruvnet-brain/codex-hook.mjs\" continuation-gate",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

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,202 @@
+{
+  "description": "POSIX Stable Spine (ADR-023): every hook routes through hook-shim.mjs, which resolves the active generation per invocation. Advisory hooks fail open; blocking hooks preserve their exit-code contract.",
+  "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/managed-cli-interface.mjs

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { loadRuntimePreferences, runtimeChildEnv } from '../scripts/runtime-preferences.mjs';
 
 export const MANAGED_EXECUTABLES = Object.freeze([
   'ruflo',
@@ -142,9 +143,21 @@ function writeStamps(executable, argv, env) {
   }
 }
 
+export function resolveManagedExecutable(executable, env = process.env) {
+  if (executable !== 'ruflo') return executable;
+  const home = env.HOME || os.homedir();
+  const canonical = path.join(home, '.npm-global', 'bin', 'ruflo');
+  try {
+    fs.accessSync(canonical, fs.constants.X_OK);
+    return canonical;
+  } catch {
+    return executable;
+  }
+}
+
 function execute(executable, argv, env) {
   return new Promise((resolve) => {
-    const child = spawn(executable, argv, {
+    const child = spawn(resolveManagedExecutable(executable, env), argv, {
       env,
       shell: false,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -186,8 +199,9 @@ function execute(executable, argv, env) {
 
 function resultOf(executable, argv, result) {
   const output = [result.stdout, result.stderr].filter(Boolean).join(result.stdout && result.stderr ? '\n' : '');
-  if (result.error || result.code !== 0) {
-    const reason = result.error || `exit ${result.code}`;
+  const contradictoryFailure = /(?:^|\n)\s*(?:❌|\[ERROR\])|invalid pragma command|key not found/i.test(output);
+  if (result.error || result.code !== 0 || contradictoryFailure) {
+    const reason = result.error || (contradictoryFailure ? 'fatal output despite exit 0' : `exit ${result.code}`);
     return {
       content: [{ type: 'text', text: output || `${executable} ${argv.join(' ')} failed: ${reason}` }],
       isError: true,
@@ -220,7 +234,36 @@ export async function callManagedCli(toolName, args, env = process.env) {
           isError: true,
         };
       }
-      return resultOf(executable, argv, await execute(executable, argv, env));
+      const policy = loadRuntimePreferences({ env, cwd: env.RUVNET_BRAIN_PROJECT_DIR || process.cwd() });
+      if (executable === 'agentic-flow' && policy.values.routing !== 'auto') {
+        return {
+          content: [{
+            type: 'text',
+            text: policy.values.routing === 'off'
+              ? 'Token-smart routing is off in RuvNet Brain Console; agentic-flow was not started.'
+              : 'Token-smart routing has not been enabled in RuvNet Brain Console; agentic-flow was not started.',
+          }],
+          isError: true,
+        };
+      }
+      const isFleetMutation = executable === 'agentic-qe'
+        && argv[0] === 'fleet'
+        && ['init', 'spawn', 'run'].includes(argv[1]);
+      if (isFleetMutation && policy.values.qeFleet !== true) {
+        return {
+          content: [{
+            type: 'text',
+            text: policy.values.qeFleet === false
+              ? 'The Agentic-QE fleet is off in RuvNet Brain Console; no QE agents were started.'
+              : 'The Agentic-QE fleet has not been enabled in RuvNet Brain Console; no QE agents were started.',
+          }],
+          isError: true,
+        };
+      }
+      const childEnv = (executable === 'agentic-flow' || executable === 'agentic-qe')
+        ? runtimeChildEnv({ env, cwd: env.RUVNET_BRAIN_PROJECT_DIR || process.cwd() })
+        : env;
+      return resultOf(executable, argv, await execute(executable, argv, childEnv));
     }
 
     return {