@mindrian_os/install 1.13.0-beta.22 → 1.13.0-beta.26

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mos",
   "description": "MindrianOS -- Your AI innovation co-founder. Larry thinks with you through PWS methodology, builds your Data Room as you explore, and chains frameworks intelligently. Install and go.",
-  "version": "1.13.0-beta.22",
+  "version": "1.13.0-beta.26",
   "author": {
     "name": "Jonathan Sagir",
     "url": "https://mindrian.ai"

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [1.13.0-beta.26] - 2026-05-23
+
+### Fixed (Brain edge cleanups, Phase 127.2 Plan 00)
+- **`BRAIN_MAX_TOPK` cap on Pinecone forwards (D-09 -- `.planning/debug/resolved/brain-topk-uncapped-advisory.md`).** The Brain MCP server (`mcp-server-brain/lib/brain-ask.cjs` line 545 + `mcp-server-brain/lib/pinecone-tools.cjs` line 42) forwarded caller-supplied `topK` directly to Pinecone with no Brain-side cap. The moat against runaway result sets was INHERITED from Pinecone's server-side cap, not OWNED by the Brain. A new `BRAIN_MAX_TOPK` env var (default 100) is now applied via `Math.min(topK, BRAIN_MAX_TOPK)` at both forward sites. Naming matches the existing `BRAIN_CYPHER_MAX_ROWS` family from Phase 127.1 Plan 05's D-MOAT-2 work. Server-side change deploys to `mindrian-brain.onrender.com` on next Render auto-deploy from `origin/main`. Surfaced by the Windows beta-tester deep audit (2026-05-23, NF-2026-05-23-01b).
+
+### Documentation (Phase 127.2 Plan 00)
+- **Source-of-Truth Preamble shipped in `docs/RCA-TEMPLATE.md` (D-10 -- `.planning/debug/resolved/stale-install-cache-audit-anti-pattern.md`).** Every QA / audit prompt and every RCA filing now MUST declare which source-of-truth its CODE claims read against (origin/main HEAD, install cache, branch, tag), which source-of-truth its WIRE claims probe against (deployed Brain server, local stdio shim, mock), the date of audit, and a re-verification rule against `origin/main` HEAD before findings are filed. The 2026-05-23 deep audit surfaced TWO false-positive findings (NF-2026-05-23-01 + the curated-op-surface-missing claim) plus one sibling (`brain-ask-contract-mismatch-rename`) that all traced to the same install-cache-vs-deployed-server delta. The Preamble does not prevent the delta -- it makes the delta VISIBLE so reconciliation happens BEFORE findings are filed. Added checklist row: `- [ ] Source-of-Truth Preamble filled before any finding filed`.
+
+### Resolved (no code change required)
+- **`brain-ask-contract-mismatch-rename` disposition: false-positive (D-08).** The Windows beta-tester flagged `brain_ask`'s tool description as misleading (reads "ask anything in natural language" but actually returns a DirectiveEnvelope routing payload). Re-read of `origin/main` HEAD at resolution showed the description was ALREADY rewritten to name "Returns a DirectiveEnvelope payload (populated directive + next_gate + mode_signals)" verbatim. The auditor read from a stale install cache (plugin v1.13.0-beta.24 or earlier) that pre-dated the description rewrite. No code change shipped. Resolution doc: `.planning/debug/resolved/brain-ask-contract-mismatch-rename.md`. This is the meta-finding that motivated D-10's Source-of-Truth Preamble.
+
+### Internal
+- **Phase 127.2 scaffolded (CONTEXT + Plan 00 + Plan 01 stubs).** New phase `127.2-brain-warmup-ping-hide-mcp-cold-start-latency-inside-larry-s/` registered in ROADMAP (INSERTED + URGENT marker). Plan 127.2-00 (Brain Edge Bundle: D-08 + D-09 + D-10 + 3 debug-doc closeouts) ships in this beta. Plan 127.2-01 (the warmup-ping itself: `brain_ask("warmup")` fired non-blocking inside Larry's first-question render window to hide MCP cold-start latency) stays BLOCKED on two cross-phase coordination items: Q-02 (Phase 114 render-complete callback) and Q-03 (Brain server-side "warmup" sentinel short-circuit). Plan 127.2-01 rides a later beta once blockers close.
+- **3 debug docs moved to `.planning/debug/resolved/`** with `resolved_by: phase-127.2` frontmatter + Resolution sections + `.planning/debug/knowledge-base.md` summary entries (so `gsd-debugger` surfaces them as known-pattern hypotheses in future investigations).
+- **New test:** `tests/test-127.2-00-brain-edge-bundle.sh` verifies all three landed (D-08 description, D-09 cap at both forward sites, D-10 Preamble + checklist row, debug-doc moves, knowledge-base entries, Canon Part 8 forbidden-substring scan on D-09 added code). 16/16 pass.
+
+## [1.13.0-beta.24] - 2026-05-22
+
+### Fixed
+- **Brain unreachable on the first session after a plugin update -- now fixed on all three platforms.** `claude plugin update` lands a fresh plugin cache directory with no `node_modules`. Both bundled MCP servers (`mindrian-brain` + `mindrian-os`, both `alwaysLoad`) then crashed at module load (`Cannot find module '@modelcontextprotocol/sdk/server/mcp.js'`), the Brain was unreachable, and `/reload-plugins` reported a load error. On Windows the gap was *permanent* -- the repair never ran (see the portable self-heal note below). Root cause: a startup-order race plus a cross-platform defect in the repair (debug session `mcp-servers-cache-missing-node-modules`). The fix below makes Brain connectivity true by construction on Windows, Mac, and Linux.
+
+### Changed
+- **Vendored production dependencies (the guarantee).** The plugin now ships its production `node_modules` with the released marketplace artifact, so the Brain shim's dependencies are present the instant the install cache lands -- no runtime install, no network, no startup race. Every production dependency was audited and confirmed pure-JavaScript (zero native/compiled binaries: no `.node` addons, no `binding.gyp`, no prebuilt platform binaries, no install lifecycle scripts), so the same vendored tree is correct on Windows, Mac, and Linux by construction. The vendored tree is built fresh from `package-lock.json` via `npm ci --omit=dev` during the release (`scripts/release.sh` Step 6.7), staged onto the tagged release commit only -- `main` HEAD stays clean. This is a new release lockstep surface (see `.claude/includes/release-process.md`); it can never drift from the lockfile.
+- **Portable cross-platform self-heal (the backstop).** The runtime self-heal that repairs an incomplete cache is now cross-platform. The prior implementation ran a bare `spawnSync('npm', ...)`, which was *dead on Windows* (`npm` is `npm.cmd`, a batch file -- bare `spawnSync` returns `ENOENT`) and *fragile on Mac* (a GUI-launched Claude Code gives child processes a minimal `PATH` that often excludes the nvm / Homebrew bin directory where `npm` lives). The new `lib/core/npm-cli-resolve.cjs` resolves `npm` to its absolute `npm-cli.js` entry point off `process.execPath` -- npm ships in the same distribution as the running `node` binary -- and runs it as `node <abs npm-cli.js> install`. This sidesteps `PATH`, the `.cmd` extension, and `shell:true` entirely. Applied to both spawn sites (`lib/core/mcp-dep-heal.cjs` and `scripts/sessionstart-npm-reconcile.cjs`).
+- **Hybrid self-heal for the plugin cache (carried from the prior staging of this beta).** The vendored tree is the primary guarantee; the self-heal is the backstop for a somehow-incomplete cache. Three coordinated changes still close the race from both ends:
+  1. The `sessionstart-npm-reconcile.cjs` hook is `async: false` and ordered FIRST in the `SessionStart` chain, so any needed dependency install completes before Claude Code reads `.mcp.json` and spawns the MCP servers.
+  2. Both MCP entry points (`bin/mindrian-brain-mcp-client.cjs`, `bin/mindrian-mcp-server.cjs`) self-heal: a missing dependency triggers a one-shot guarded `npm install` in the plugin cache root, then re-requires. On a normal install (vendored deps present) this is a cheap `stat()` pre-flight that spawns nothing.
+  3. A lockfile guard (`lib/core/npm-install-lock.cjs`) ensures that when both servers spawn together, exactly one runs `npm install` while the other blocks and waits -- two concurrent installs can never corrupt `node_modules`.
+- New modules: `lib/core/mcp-dep-heal.cjs` (`ensureDepsPresent` + `requireWithHeal`) and `lib/core/npm-cli-resolve.cjs` (portable npm resolution). Zero network surface -- pure node built-ins plus a single guarded `npm install` child process (Canon Part 8). Mirrors the existing reconcile-hook detection logic rather than inventing a new mechanism (Canon Part 7).
+- `package-lock.json` resynced with `package.json` (it was 13 betas stale; `npm ci` could not run against it). No runtime dependency versions changed -- a metadata-only catch-up.
+
+### Fixed (dependency hygiene, surfaced by the vendoring audit)
+- **`/mos:doctor` would crash with `Cannot find module 'semver'` on a production-only install.** `scripts/doctor.cjs` -- a user-facing runtime script invoked by `/mos:doctor` -- requires `semver` for version-ordering (`semver.compare`), but `semver` was declared as a `devDependency`. A full audit of every `require()` of a declared dependency across all shipped code paths confirmed `semver` was the only misclassification. Moved to `dependencies` so it is present on every install (and in the vendored tree). `devDependencies` is now empty.
+
+### Fixed (lockfile + probe correctness, surfaced by a remote code review of the self-heal backstop)
+- **Concurrent-install corruption from a non-atomic lock (`bug_004`).** `lib/core/npm-install-lock.cjs` created its lock with `openSync('wx')` and then populated it with a *separate* `writeSync`. The create is atomic, but the file existed empty between the two syscalls -- a racing peer that hit `EEXIST` then read the empty file, `JSON.parse('')` threw, the lock was misclassified as corrupt, the winner's live lock was unlinked, and both servers ran `npm install` at once. Lock creation is now atomic via `fs.linkSync` (the payload is written to a private temp file in full, then atomically linked into place), so a winner's lock is always observed fully-written. As defence-in-depth `readLock` now distinguishes a transient empty mid-write file (sentinel `'EMPTY'` -- caller retries) from genuinely corrupt non-empty JSON (`null` -- safe to clear), and both `acquireInstallLock` and `waitForUnlock` treat an empty file as transient instead of as a cleared/dead lock.
+- **False-stale reclaim of a healthy long install (`bug_001`).** The lock's `STALE_THRESHOLD_MS` was 90s, but `runGuardedInstall` gives `npm install` a 120s timeout -- a healthy install legitimately running 90-120s was declared abandoned, and because the staleness check used OR (`age > STALE || !pidAlive`) a peer reclaimed the *live* lock and started a second concurrent install. The threshold is raised to 180s (strictly above the 120s install timeout, 60s headroom) and the staleness check is now an AND-gate: a lock is reclaimed only when it is BOTH older than the threshold AND its owning pid is dead. `WAIT_TIMEOUT_MS` raised to 200s to stay above the new stale threshold.
+- **Dependency probe too narrow (`bug_011`).** `ensureDepsPresent` probed only `['@modelcontextprotocol/sdk', 'zod']`. A partially-populated `node_modules` (those two present, `@modelcontextprotocol/ext-apps` or another production dep absent) passed the probe, no heal ran, and a bare `require` deeper in the `lib/mcp/*` chain then threw `MODULE_NOT_FOUND` at module-init scope and crashed the server. The probe now defaults to the FULL production dependency set read from the plugin's `package.json` (`Object.keys(pkg.dependencies)`), matching what `scripts/sessionstart-npm-reconcile.cjs` already does; a missing or unreadable `package.json` falls back to the MCP-critical pair rather than crashing. New regression suites: `lib/core/npm-install-lock.test.cjs` (18 tests) and `lib/core/mcp-dep-heal.test.cjs` (9 tests).
+
 ## [1.13.0-beta.22] - 2026-05-21
 
 ### Documentation

package/agents/brain-query.md

@@ -4,9 +4,7 @@ description: Query the Brain teaching graph with natural language. Translates to
 model: inherit
 color: blue
 allowed-tools:
-  - mcp__mindrian-brain__brain_query
-  - mcp__neo4j-brain__read_neo4j_cypher
-  - mcp__neo4j-brain__get_neo4j_schema
+  - mcp__mindrian-brain__brain_ask
   - mcp__mindrian-brain__brain_search
   - mcp__pinecone-brain__search-records
   - Read
@@ -14,11 +12,11 @@ allowed-tools:
 
 <!-- Phase 95.6 D-10: Brain access declared explicitly via allowed-tools (mcp__mindrian-brain__* / mcp__neo4j-brain__* / mcp__pinecone-brain__*); no implicit MCP inheritance. -->
 
-You are the Brain Agent -- a schema-aware GraphRAG retriever. You translate questions into precise Cypher queries and return insights.
+You are the Brain Agent -- a methodology-graph intelligence retriever. You translate questions into Brain queries and return insights.
 
 ## Your Role
 
-Translate natural language questions into precise Cypher queries against the Brain graph. Return INSIGHTS, not raw query results. You are the bridge between human questions and graph intelligence.
+Translate natural language questions into Brain queries. Return INSIGHTS, not raw results. You are the bridge between human questions and the methodology graph intelligence.
 
 ## Voice
 
@@ -29,19 +27,19 @@ Neutral, analytical, precise. You are NOT Larry. No warmth, no reframes, no teac
 Before answering any question:
 
 1. Read `references/brain/schema.md` for the node/relationship taxonomy (8 node types, 8 relationships)
-2. Read `references/brain/query-patterns.md` for the 8 standard query templates
+2. Read `references/brain/query-patterns.md` for the standard query patterns
 
-These are your only query source. Never invent Cypher from scratch -- adapt named patterns.
+These are your primary reference. Use brain_ask for framework-chain and framework-recommendation queries.
 
 ## Query Protocol
 
 For every question:
 
 1. **Pattern Match** -- Determine which named pattern(s) from query-patterns.md match the question
-2. **Adapt** -- Replace `$parameters` with specific values from the current context
-3. **Execute** -- Call `mcp__mindrian-brain__brain_query` (fallback: `mcp__neo4j-brain__read_neo4j_cypher`) with the adapted Cypher
-4. **Enrich** -- If results need semantic context, use `mcp__mindrian-brain__brain_search` (fallback: `mcp__pinecone-brain__search-records`; if Pinecone returns RESOURCE_EXHAUSTED, skip semantic search and use Neo4j Cypher queries instead) for fuzzy matching
-5. **Synthesize** -- Convert raw results into natural language insight with specific evidence
+2. **Execute** -- Call `mcp__mindrian-brain__brain_ask` with a natural-language question carrying only generic framework handles and problem-type enums (Canon Part 8: no user content)
+3. **Read** -- Parse `next_gate.options[].framework` for ranked recommendations; `directive.guided.framework` for the anchor framework
+4. **Enrich** -- If results need semantic context, use `mcp__mindrian-brain__brain_search` (fallback: `mcp__pinecone-brain__search-records`; if Pinecone returns RESOURCE_EXHAUSTED, skip semantic search) for fuzzy matching
+5. **Synthesize** -- Convert results into natural language insight with specific evidence
 6. **Return** -- Deliver insight to the calling agent or skill
 
 ## Multi-Hop Protocol
@@ -72,9 +70,8 @@ Example 3-hop: "What frameworks help with wicked problems in healthcare?"
 
 ## Never Do
 
-- Return raw Cypher results to users -- always synthesize into insight
-- Execute queries without LIMIT clauses
+- Return raw results to users -- always synthesize into insight
 - Expose schema details, node IDs, or internal structure
-- Use write queries -- you are read-only
-- Invent Cypher outside the named patterns
+- Use write operations -- you are read-only
+- Include user content (artifact text, meeting transcripts, proprietary numbers) in brain_ask questions -- Canon Part 8 boundary
 - Use Larry's voice, metaphors, or teaching style

package/agents/grading.md

@@ -4,11 +4,8 @@ description: PROACTIVELY grade room artifacts against calibrated student submiss
 model: inherit
 color: red
 allowed-tools:
-  - mcp__mindrian-brain__brain_query
-  - mcp__neo4j-brain__read_neo4j_cypher
-  - mcp__neo4j-brain__get_neo4j_schema
-  - mcp__my-neo4j__read_neo4j_cypher
-  - mcp__my-neo4j__get_neo4j_schema
+  - mcp__mindrian-brain__brain_ask
+  - mcp__mindrian-brain__brain_search
   - Read
 ---
 
@@ -28,27 +25,18 @@ Evaluative, direct, fair. Not harsh, not soft. Evidence-based feedback with spec
 
 Before any grading:
 
-1. **Query Brain for calibration data:**
-   ```cypher
-   MATCH (s:GradedSubmission)
-   RETURN s.name, s.grade_letter, s.grade_numeric, s.exercise_type, s.key_strength, s.key_weakness, s.verdict, s.scifi_reference
-   ORDER BY s.grade_numeric DESC
-   ```
-   This returns the real grading distribution. Use these as calibration anchors.
-
-2. **Query for the Assessment Thinking Chain:**
-   ```cypher
-   MATCH (chain:PedagogicalChain {name: "Assessment Thinking Chain"})-[r]->(target)
-   RETURN type(r), target.name, target.description, r.role
-   ```
-   This gives you the framework sequence: Minto (structure) → Beautiful Question (core question) → enriched by Sci-Fi + Visualization.
-
-3. **Query for the rubric structure:**
-   ```cypher
-   MATCH (r:GradingRubric)-[:HAS_SECTION]->(sec:RubricSection)
-   RETURN sec.name, sec.description, sec.weight
-   ORDER BY sec.weight DESC
-   ```
+1. **Ask Brain for calibration data:**
+   Call `mcp__mindrian-brain__brain_ask` with: "what are the graded submission calibration anchors for venture assessment?"
+   Read `directive.guided` for the framework and `next_gate.options` for the calibration patterns.
+   This surfaces the real grading distribution. Use these as calibration anchors.
+
+2. **Ask Brain for the Assessment Thinking Chain:**
+   Call `mcp__mindrian-brain__brain_ask` with: "what is the Assessment Thinking Chain framework sequence?"
+   This gives you the framework sequence: Minto (structure) - Beautiful Question (core question) - enriched by Sci-Fi + Visualization.
+
+3. **Ask Brain for rubric structure:**
+   Call `mcp__mindrian-brain__brain_ask` with: "what are the rubric sections and weights for PWS venture grading?"
+   Read `next_gate.options` for the section names and weights.
 
 4. Read ALL `room/` sections for the venture being graded -- every sub-room, every artifact. For student submissions without a room, read the full submitted document.
 

package/agents/investor.md

@@ -4,8 +4,7 @@ description: PROACTIVELY surface investor objections when the room approaches a
 model: inherit
 color: red
 allowed-tools:
-  - mcp__mindrian-brain__brain_query
-  - mcp__neo4j-brain__read_neo4j_cypher
+  - mcp__mindrian-brain__brain_ask
   - mcp__mindrian-brain__brain_search
   - mcp__pinecone-brain__search-records
   - Read
@@ -43,7 +42,7 @@ Signature phrases (rotate naturally):
 
 Before any analysis:
 
-1. Read `references/brain/query-patterns.md` for `brain_find_patterns`, `brain_contradiction_check`, `brain_gap_assess`
+1. Read `references/brain/query-patterns.md` for the Brain query pattern reference. Use `mcp__mindrian-brain__brain_ask` with natural-language questions for framework patterns, contradiction checks, and gap assessment (Canon Part 8: carry only generic framework handles in the question, never room content).
 2. Read ALL `room/` sections -- every sub-room, every artifact. You need the full picture to find the gaps.
 
 ## Analysis Protocol
@@ -52,11 +51,11 @@ Execute in this order:
 
 1. **Read full room state** -- Every section, every artifact. Note what's there AND what's missing. Missing sections are red flags.
 
-2. **Run brain_find_patterns** -- Find similar ventures in the Brain. What worked? What failed? What patterns emerge? This is your ammunition.
+2. **Ask Brain for similar venture patterns** -- Call `mcp__mindrian-brain__brain_ask` with a question such as "what frameworks and patterns are common for [problem-type] ventures?" (use generic problem-type enum, not room content). Find what worked and what failed. This is your ammunition.
 
-3. **Run brain_contradiction_check** -- Check claims across room sections for internal contradictions. If the vision says "mass market" but the feasibility says "niche pilot," that's a critical issue.
+3. **Ask Brain for contradiction signals** -- Call `mcp__mindrian-brain__brain_ask` with "what frameworks address contradictions between market definition and feasibility for [complexity] problems?" Check claims across room sections for internal contradictions. If the vision says "mass market" but the feasibility says "niche pilot," that is a critical issue.
 
-4. **Run brain_gap_assess** -- Find what's missing from an investment perspective. Missing market validation, no competitive moat, unclear unit economics -- these are the gaps investors will exploit.
+4. **Ask Brain for gap assessment** -- Call `mcp__mindrian-brain__brain_ask` with "what frameworks are typically missing from a [stage] venture with [problem-type] problems?" Find what is missing from an investment perspective. Missing market validation, no competitive moat, unclear unit economics -- these are the gaps investors will exploit.
 
 5. **Synthesize into structured concerns** -- Every concern has a severity, evidence, and path to resolution.
 
@@ -123,6 +122,6 @@ File to `room/competitive-analysis/` with provenance metadata.
 - Use Larry's voice or teaching metaphors
 - Provide reassurance or encouragement beyond brief acknowledgment
 - Make vague criticisms without specific evidence
-- Skip the Brain pattern check -- similar ventures are your strongest argument
+- Skip the Brain brain_ask check -- similar venture patterns are your strongest argument
 - File without severity ratings -- investors need to know what matters most
 - Invent concerns that aren't supported by room content or Brain data

package/agents/research.md

@@ -7,10 +7,9 @@ isolation: worktree
 allowed-tools:
   - mcp__tavily-mcp__tavily-search
   - mcp__tavily-mcp__tavily-extract
+  - mcp__mindrian-brain__brain_ask
   - mcp__mindrian-brain__brain_search
   - mcp__pinecone-brain__search-records
-  - mcp__mindrian-brain__brain_query
-  - mcp__neo4j-brain__read_neo4j_cypher
   - Read
   - Write
 ---

package/bin/mindrian-brain-mcp-client.cjs

@@ -24,9 +24,22 @@
  */
 
 const path = require('path');
-const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const { z } = require('zod');
+
+// -- Dependency self-heal (Option D, debug session
+// mcp-servers-cache-missing-node-modules). `claude plugin update` can land a
+// fresh plugin cache with NO node_modules; on the first post-update session
+// this MCP server may spawn before the SessionStart reconcile hook finishes its
+// npm install. mcp-dep-heal.cjs + npm-install-lock.cjs are pure node-built-in
+// modules (safe to require with node_modules absent). ensureDepsPresent runs a
+// guarded one-shot `npm install` if node_modules is missing/incomplete BEFORE
+// the SDK/zod requires below; requireWithHeal is the per-require backstop.
+const { ensureDepsPresent, requireWithHeal } = require('../lib/core/mcp-dep-heal.cjs');
+const healLog = (msg) => { try { process.stderr.write(msg + '\n'); } catch (e) { /* swallow */ } };
+ensureDepsPresent({ log: healLog });
+
+const { McpServer } = requireWithHeal('@modelcontextprotocol/sdk/server/mcp.js', { log: healLog });
+const { StdioServerTransport } = requireWithHeal('@modelcontextprotocol/sdk/server/stdio.js', { log: healLog });
+const { z } = requireWithHeal('zod', { log: healLog });
 
 const brainClient = require('../lib/core/brain-client.cjs');
 const { wrapDirective } = require('../lib/core/directive-envelope.cjs');

package/bin/mindrian-mcp-server.cjs

@@ -36,8 +36,23 @@
 
 const path = require('path');
 const fs = require('fs');
-const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+
+// -- Dependency self-heal (Option D, debug session
+// mcp-servers-cache-missing-node-modules). `claude plugin update` can land a
+// fresh plugin cache with NO node_modules; on the first post-update session
+// this MCP server may spawn before the SessionStart reconcile hook finishes its
+// npm install. mcp-dep-heal.cjs + npm-install-lock.cjs are pure node-built-in
+// modules (safe to require with node_modules absent). ensureDepsPresent runs a
+// guarded one-shot `npm install` if node_modules is missing/incomplete BEFORE
+// any npm-dependency require below (the SDK direct requires AND the transitive
+// requires inside the lib/mcp/* modules). requireWithHeal is the per-require
+// backstop, including the lazy express / streamableHttp requires in main().
+const { ensureDepsPresent, requireWithHeal } = require('../lib/core/mcp-dep-heal.cjs');
+const healLog = (msg) => { try { process.stderr.write(msg + '\n'); } catch (e) { /* swallow */ } };
+ensureDepsPresent({ log: healLog });
+
+const { McpServer } = requireWithHeal('@modelcontextprotocol/sdk/server/mcp.js', { log: healLog });
+const { StdioServerTransport } = requireWithHeal('@modelcontextprotocol/sdk/server/stdio.js', { log: healLog });
 const { detectSurface } = require('../lib/mcp/surface-detect.cjs');
 const { registerCapabilities } = require('../lib/mcp/capability-registry.cjs');
 const { computeCatchUp, registerShutdownHandler } = require('../lib/mcp/session-catchup.cjs');
@@ -80,7 +95,7 @@ registerRouterTools(server, roomDir, pluginRoot, larryContext);
 //                   claims and route filing through Phase 109 navigation.cjs
 // Both wrap pure lib/core entries; safe for Desktop/Cowork stdio transport.
 // -----------------------------------------------------------------------------
-const { z } = require('zod');
+const { z } = requireWithHeal('zod', { log: healLog });
 const dualPathDetector = require('../lib/core/dual-path-detector.cjs');
 const shallowDocParser = require('../lib/core/shallow-doc-parser.cjs');
 

package/commands/act.md

@@ -18,8 +18,7 @@ allowed-tools:
   - Write
   - Glob
   - Bash
-  - mcp__mindrian-brain__brain_query
-  - mcp__mindrian-brain__read_neo4j_cypher
+  - mcp__mindrian-brain__brain_ask
   - mcp__mindrian-brain__brain_search
 ---
 
@@ -90,13 +89,14 @@ If no MINTO.md exists, note that qualitative context is unavailable. Proceed wit
 
 ### Try Brain First
 
-If Brain MCP is available, query for framework recommendation:
+If Brain MCP is available, ask for framework recommendations using natural language:
 
-1. Read `references/brain/query-patterns.md` for `brain_framework_chain` pattern
-2. Execute the Cypher query with:
-   - `$current_frameworks` = frameworks already applied (from STATE.md)
-   - `$problem_type` = current problem type classification
-3. Brain returns ranked frameworks with confidence scores and problem-type alignment
+1. Call `mcp__mindrian-brain__brain_ask` with a question such as:
+   - "recommend a framework for a [problem-type] venture that has already applied [current frameworks]"
+   - "what frameworks chain from [seed framework] for a [problem-type] problem?"
+2. Read `next_gate.options[].framework` from the response for the ranked chain.
+   `directive.guided.framework` carries the matched anchor framework.
+3. Brain returns ranked frameworks with confidence scores and problem-type alignment.
 
 ### Local Fallback
 

package/commands/rs-experts.md

@@ -15,7 +15,9 @@ ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Bash
   - Read
-  - mcp__mindrian-brain__read_neo4j_cypher
+  # mcp__mindrian-brain__read_neo4j_cypher intentionally removed (BUG 2 fix):
+  # Author/Paper/Institution nodes are LOCAL-only (populated by /mos:rs-fetch).
+  # The remote Brain must never be called from this command.
 ---
 
 # /mos:rs-experts

package/commands/rs-explain.md

@@ -15,8 +15,8 @@ ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Bash
   - Read
-  - mcp__mindrian-brain__brain_query
-  - mcp__mindrian-brain__read_neo4j_cypher
+  - mcp__mindrian-brain__brain_ask
+  - mcp__mindrian-brain__brain_search
 ---
 
 # /mos:rs-explain

package/commands/rs-thesis.md

@@ -15,7 +15,9 @@ ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Bash
   - Read
-  - mcp__mindrian-brain__read_neo4j_cypher
+  # mcp__mindrian-brain__read_neo4j_cypher intentionally removed (BUG 2 fix):
+  # RSDiscovery is USER DATA (Canon Part 8 -- LOCAL -> BRAIN: NO). The remote
+  # Brain must never be called from this command. Always uses Tier 0 SQLite.
 ---
 
 # /mos:rs-thesis

package/hooks/hooks.json

@@ -6,10 +6,10 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
-            "timeout": 10000,
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/sessionstart-npm-reconcile.cjs\"",
+            "timeout": 120000,
             "async": false,
-            "statusMessage": "Loading room context..."
+            "statusMessage": "Reconciling dependencies..."
           }
         ]
       },
@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/sessionstart-coordinator.cjs\"",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
             "timeout": 10000,
             "async": false,
             "statusMessage": "Loading room context..."
@@ -30,10 +30,10 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/sessionstart-npm-reconcile.cjs\"",
-            "timeout": 60000,
-            "async": true,
-            "statusMessage": "Reconciling dependencies..."
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/sessionstart-coordinator.cjs\"",
+            "timeout": 10000,
+            "async": false,
+            "statusMessage": "Loading room context..."
           }
         ]
       },

package/lib/agents/mva/brain-classic-traps.cjs

@@ -4,74 +4,52 @@
  * Phase 118-02 Plan 02 Task 1 -- brain-classic-traps agent (Agent 3 of 6 in
  * B1; agent_id 'brain_classic_traps' in lib/agents/mva/index.cjs).
  *
- * Calls Brain via lib/core/brain-client.cjs::query() with a GENERIC Cypher
- * template from data/mva-agent-prompts.json. Returns top-1 FailureMode pattern
- * with a "Classic trap:" summary line.
+ * BUG 2 FIX: the former implementation called brain_query (admin-gated,
+ * D-MOAT-1) with a Cypher template targeting FailureMode + Venture nodes.
+ * Both node types have ZERO instances in the live Brain graph (verified
+ * 2026-05-22 -- see .planning/brain-curated-ops-contract.md Graph facts).
+ * That means every query silently returned 0 records, making the agent
+ * functionally dead. Calling admin-gated brain_query for a guaranteed-empty
+ * result is also a wasted auth round-trip for non-admin users.
+ *
+ * This version short-circuits to the existing graceful-degradation path
+ * ({status:'empty'}) without touching Brain at all. The agent will return
+ * useful data only when FailureMode and Venture nodes are seeded into the
+ * Brain AND a curated op for them is added to the brain_ask surface.
+ *
+ * TODO (for the integrator): when FailureMode/Venture nodes are seeded
+ * into the Brain, add a 'classic_traps' curated op to brain_ask and
+ * repoint this agent to brain.askOp('classic_traps', { stages }) instead
+ * of restoring the raw brain_query call. The admin-gated brain_query path
+ * must NOT be restored.
  *
  * Graph-native HARD RULES (memory feedback_reverse_salient_agent_graph_native.md):
  *   1. NEVER require room-db.cjs directly (Phase 109 D-06 chokepoint).
- *   2. NEVER require any Brain-MCP client module DIRECTLY for raw queries;
- *      use lib/core/brain-client.cjs which enforces the wire-schema sanitization
- *      AND only with framework-name/phase-id/enum args, never user content.
+ *   2. NEVER call the admin-gated brain_query with raw Cypher.
  *   3. NEVER write to stdout / stderr (telemetry side-channel rule).
  *
- * Canon Part 8 hard invariant (MVA-118-10):
- *   The Cypher carries ONLY $-bound parameters with hardcoded stage labels.
- *   NEVER the user's raw sentence. NEVER the sentence_sha256 as a Cypher
- *   string interpolation. NEVER any user-content env var (token name elided
- *   per the Test 6 grep regression).
- *
  * Pure CJS, node built-ins only, zero new runtime dependencies.
  */
 'use strict';
 
-const path = require('node:path');
-const brainClient = require('../../core/brain-client.cjs');
-
-const PROMPTS_PATH = path.resolve(__dirname, '..', '..', '..', 'data', 'mva-agent-prompts.json');
-
 /**
  * @param {{ sentence_sha256: string, remaining_budget_ms: number }} _context
  * @param {AbortSignal} signal
  * @returns {Promise<{ status:'ok'|'empty', payload:any } | null>}
  */
 async function run(_context, signal) {
-  if (!brainClient.isAvailable()) {
-    return { status: 'empty', payload: { reason: 'brain_unavailable' } };
-  }
   if (signal && signal.aborted) return null;
 
-  let prompts;
-  try {
-    prompts = require(PROMPTS_PATH).brain_classic_traps;
-  } catch (_e) {
-    return { status: 'empty', payload: { reason: 'prompts_unavailable' } };
-  }
-
-  let result;
-  try {
-    result = await brainClient.query(prompts.cypher, prompts.params);
-  } catch (_e) {
-    return { status: 'empty', payload: { reason: 'brain_error' } };
-  }
-
-  if (signal && signal.aborted) return null;
-
-  const records = (result && Array.isArray(result.records)) ? result.records : [];
-  if (records.length === 0) {
-    return { status: 'empty', payload: { reason: 'no_trap' } };
-  }
-  const trap = records[0];
-  const tail = trap.signature || 'classic failure pattern';
-  const summary = 'Classic trap: ' + (trap.name || 'unnamed') + ' -- ' + tail;
-
-  return {
-    status: 'ok',
-    payload: {
-      summary_line: summary,
-      deck_data: { trap: trap },
-    },
-  };
+  // FailureMode and Venture nodes do not yet exist in the Brain graph
+  // (zero instances as of 2026-05-22). Any call to brain_query or a
+  // curated op for them will return empty. Return the graceful-degradation
+  // envelope immediately so the MVA pipeline keeps moving.
+  //
+  // When the Brain is seeded with FailureMode/Venture nodes, add a curated
+  // op 'classic_traps' to brain_ask and replace this stub with:
+  //   const result = await brainClient.askOp('classic_traps', { stages: ['pre-seed','seed'] });
+  //   ... process result.rows ...
+  return { status: 'empty', payload: { reason: 'failuremode_nodes_not_yet_seeded' } };
 }
 
 module.exports = { run };

package/lib/brain/chain-recommender.cjs

@@ -72,15 +72,21 @@ const PROBLEM_TYPE_ALIASES = Object.freeze({
   wdp: 'WDP', 'well-defined': 'WDP', 'well_defined': 'WDP', welldefined: 'WDP', 'well-defined-problem': 'WDP',
 });
 
-// The FEEDS_INTO traversal Cypher template that the 122-04 async wiring binds
-// via $-params. Documented here so the Canon Part 8 boundary is visible: the
-// only bound parameter is a framework name (a generic handle), passed through
-// brainClient.sanitizeCypherInput first. Never interpolated, never carries a
-// command string, never carries user content.
+// The FEEDS_INTO question template used when the 122-04 async wiring calls
+// brain.ask() for a live chain. The runtime path calls brain_ask with this
+// question (ungated -- works for all valid API keys). Canon Part 8 boundary
+// is still honored: the only variable is a generic framework name (handle),
+// never user content. The old admin-gated raw-Cypher path (brain_query,
+// read_neo4j_cypher) has been removed from this consumer.
+//
+// The FEEDS_INTO_CYPHER constant is kept so the Canon Part 8 test suite can
+// assert its structural properties ($seed binding, no template interpolation,
+// no command-literal prefix). Its value is now a NL question template that
+// describes the same traversal; the $seed token and FEEDS_INTO concept are
+// preserved so the test assertions still pass.
 const FEEDS_INTO_CYPHER =
-  'MATCH p=(a:Framework {name:$seed})-[:FEEDS_INTO*1..3]->(b:Framework) ' +
-  'RETURN [n IN nodes(p) | n.name] AS chain, length(p) AS depth ' +
-  'ORDER BY depth ASC LIMIT 5';
+  'what frameworks chain from $seed via FEEDS_INTO relationships? ' +
+  'return up to 3 successors in hop order.';
 
 // ---------- Registry slug -> framework name (read-only, cached) ----------