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

package/lib/brain/framework-chain-slice.cjs

@@ -1,33 +1,46 @@
 'use strict';
-// Phase 125-02 -- Brain Cypher slice query (parameterized 1-3 hop FEEDS_INTO; LIMIT 50).
-// CONTEXT.md Scope IN section B item 4 -- the LOCKED Cypher. Async wrapper over
-// brain-client.query that produces the framework_chain_hint shape Plan 03 stitches
-// into the packet's local_graph_summary.
+// Phase 125-02 -- Brain framework-chain slice (FEEDS_INTO 1-3 hops).
+// CONTEXT.md Scope IN section B item 4.
 //
-// Canon Part 8: only $active_frameworks (array of generic framework name strings,
-// each passed through sanitizeCypherInput) + $max_hops (1|2|3 int) cross the wire.
-// No user content. No artifact text. No room identifiers in the query.
+// Repointed (BUG 2 fix) from the admin-gated brain_query / raw-Cypher path
+// onto the curated brain.askOp('framework_chain_slice', { seeds, max_hops })
+// surface so any valid API key can call it.
 //
-// Graceful degradation: any failure path (Brain unreachable, query throws, invalid
-// max_hops, empty active_frameworks, all-rejected-by-sanitizer, non-array result)
-// returns a degraded result envelope rather than throwing. Tier 0 stays functional.
+// Contract (from .planning/brain-curated-ops-contract.md):
+//   brain.askOp('framework_chain_slice', { seeds: string[], max_hops?: 1|2|3 })
+//   -> { op, source, count, rows: Array<{from, to, hop_distance}>, degraded? }
+//
+// INTEGRATOR NOTE -- partial substitute:
+//   The old Cypher returned `confidence` and `transform_description` per edge.
+//   The curated op returns ONLY `from`, `to`, `hop_distance` (no confidence,
+//   no transform_description). Downstream consumers that used those fields will
+//   receive `null` after this change. Flag logged in fetchFrameworkChainSlice
+//   return envelope as `confidence_omitted: true` so callers can detect this.
+//   A future curated-op extension could re-expose the fields if needed.
+//
+// Canon Part 8: seeds are generic framework-name strings (allow-listed by
+// the server); max_hops is a clamped integer 1-3. No user content crosses the
+// wire. The curated op enforces this server-side; no caller Cypher ever.
+//
+// Graceful degradation: any failure path (Brain unreachable, askOp throws,
+// invalid max_hops, empty seeds, non-array result, degraded envelope) returns
+// a degraded result envelope rather than throwing. Tier 0 stays functional.
+//
+// BACKWARD-COMPAT SURFACE: the module still exports FRAMEWORK_CHAIN_SLICE_CYPHER
+// as an empty string so existing test-seam checks that assert on the exported
+// constant do not break (tests/brain-cypher-chain-slice.test.cjs Test 2 checks
+// that the CYPHER includes 'LIMIT 50' and 'FEEDS_INTO*1..$max_hops'; those
+// tests will need updating now that the Cypher is server-side). The constant is
+// deprecated; callers should NOT use it.
 
 const crypto = require('node:crypto');
 const defaultBrainClient = require('../core/brain-client.cjs');
 
-// LOCKED Cypher template per CONTEXT.md Scope IN section B item 4.
-// READ-ONLY (MATCH/RETURN/LIMIT only -- no MERGE/CREATE/DELETE). The two $-bound
-// params ($active_frameworks, $max_hops) are the ONLY values that cross the wire;
-// every framework name in $active_frameworks is sanitized via the brain-client
-// sanitizeCypherInput whitelist before binding (Canon Part 8 invariant).
-const FRAMEWORK_CHAIN_SLICE_CYPHER =
-  'MATCH (f:Framework)-[r:FEEDS_INTO*1..$max_hops]->(g:Framework) ' +
-  'WHERE f.name IN $active_frameworks ' +
-  'RETURN f.name AS from, g.name AS to, ' +
-  '       r.confidence AS confidence, ' +
-  '       r.transform_description AS transform_description, ' +
-  '       length(r) AS hop_distance ' +
-  'LIMIT 50';
+// DEPRECATED: the Cypher is now frozen server-side inside the curated op.
+// Retained as an empty string to avoid hard breaking any import that
+// destructures this export. Tests that assert on its content should be
+// updated to reflect the curated-op architecture.
+const FRAMEWORK_CHAIN_SLICE_CYPHER = '';
 
 function _nowIso() {
   return new Date().toISOString();
@@ -62,22 +75,29 @@ function _unwrapRows(result) {
 }
 
 /**
- * Fetch a parameterized 1-3 hop FEEDS_INTO slice from the live Brain.
+ * Fetch a 1-3 hop FEEDS_INTO slice from the live Brain via the curated
+ * askOp surface (D-MOAT-1-safe; no admin gate required).
  *
  * @param {object} opts
- * @param {string[]} opts.active_frameworks - Array of framework name strings.
- *   Empty array short-circuits to a degraded envelope.
+ * @param {string[]} opts.active_frameworks - Array of framework name strings
+ *   used as seeds. Empty array short-circuits to a degraded envelope.
  * @param {1|2|3} opts.max_hops - Hop depth (must be exactly 1, 2, or 3).
  *   Any other value short-circuits to a degraded envelope.
  * @param {object} [opts.brainClient] - Test seam; defaults to live brain-client.
  * @returns {Promise<{
- *   edges: Array<{from:string|null, to:string|null, confidence:number|null,
- *                 transform_description:string|null, hop_distance:number|null}>,
+ *   edges: Array<{from:string|null, to:string|null, confidence:null,
+ *                 transform_description:null, hop_distance:number|null}>,
  *   slice_scope: 1|2|3,
  *   slice_rationale: string,
  *   brain_snapshot_id: string|null,
- *   fetched_at: string
+ *   fetched_at: string,
+ *   confidence_omitted: true
  * }>}
+ *
+ * INTEGRATOR NOTE: confidence + transform_description are always null after
+ * this repoint. The curated op returns only { from, to, hop_distance }.
+ * `confidence_omitted: true` is set in every returned envelope so callers
+ * can detect the reduction and adapt accordingly.
  */
 async function fetchFrameworkChainSlice(opts) {
   const o = opts || {};
@@ -85,29 +105,31 @@ async function fetchFrameworkChainSlice(opts) {
   const max_hops = (o.max_hops === 1 || o.max_hops === 2 || o.max_hops === 3) ? o.max_hops : null;
   const brainClient = o.brainClient || defaultBrainClient;
 
-  // Gate 1: max_hops must be 1, 2, or 3. Anything else (0, 4, undefined,
-  // string, null) returns a degraded envelope with slice_scope defaulted to 3.
+  // Gate 1: max_hops must be 1, 2, or 3.
   if (max_hops === null) {
-    return _degraded({ max_hops: 3, rationale: 'invalid_max_hops; expected 1|2|3' });
+    return Object.assign(_degraded({ max_hops: 3, rationale: 'invalid_max_hops; expected 1|2|3' }), { confidence_omitted: true });
   }
 
   // Gate 2: empty active_frameworks short-circuits before any Brain contact.
-  // The Cypher would match nothing anyway; the degraded envelope is honest.
   if (active_frameworks.length === 0) {
-    return _degraded({ max_hops: max_hops, rationale: 'empty active_frameworks; no slice fetched' });
+    return Object.assign(_degraded({ max_hops: max_hops, rationale: 'empty active_frameworks; no slice fetched' }), { confidence_omitted: true });
   }
 
-  // Gate 3: Brain reachability check before issuing the Cypher query. The
-  // live brain-client.isAvailable() is sync + cheap (an API-key resolve).
+  // Gate 3: Brain reachability check.
   if (typeof brainClient.isAvailable === 'function' && !brainClient.isAvailable()) {
-    return _degraded({ max_hops: max_hops, rationale: 'brain_unreachable' });
+    return Object.assign(_degraded({ max_hops: max_hops, rationale: 'brain_unreachable' }), { confidence_omitted: true });
   }
 
-  // Canon Part 8 sanitization. brain-client._test.sanitizeCypherInput is the
-  // shipped whitelist (Phase 110-05 D-04 invariant). Each framework name is
-  // sanitized BEFORE binding; values that scrub down to empty are dropped.
-  // Fallback no-op only when the seam is genuinely absent (the live
-  // brain-client always exposes it; tests may stub a minimal client).
+  // Gate 4: askOp must be available on the client. The live brain-client
+  // gains askOp in the parallel BUG 2 build; tests may stub it. If the
+  // method is absent we fall back to the degraded path cleanly.
+  if (typeof brainClient.askOp !== 'function') {
+    return Object.assign(_degraded({ max_hops: max_hops, rationale: 'askOp_not_available_on_client' }), { confidence_omitted: true });
+  }
+
+  // Sanitize seed names before passing to askOp. The server also enforces
+  // the allow-list but we sanitize client-side as defence-in-depth.
+  // Canon Part 8 invariant preserved.
   const sanitizer = (brainClient._test && typeof brainClient._test.sanitizeCypherInput === 'function')
     ? brainClient._test.sanitizeCypherInput
     : function (s) { return s; };
@@ -117,66 +139,63 @@ async function fetchFrameworkChainSlice(opts) {
     .filter(function (n) { return typeof n === 'string' && n.length > 0; });
 
   if (sanitized.length === 0) {
-    return _degraded({
+    return Object.assign(_degraded({
       max_hops: max_hops,
       rationale: 'all_active_frameworks_rejected_by_sanitizer',
-    });
+    }), { confidence_omitted: true });
   }
 
-  // Issue the parameterized Cypher. The ONLY $-bound values are the sanitized
-  // framework name array + the max_hops integer. The Cypher string itself is
-  // a frozen constant -- no template interpolation, no string concatenation
-  // with caller-derived data (Canon Part 8 enforced by inspection).
-  let result;
+  // Issue the curated op. `seeds` is the param name per the contract;
+  // `max_hops` is passed through as-is (server clamps to [1,3]).
+  let opResult;
   try {
-    result = await brainClient.query(FRAMEWORK_CHAIN_SLICE_CYPHER, {
-      active_frameworks: sanitized,
+    opResult = await brainClient.askOp('framework_chain_slice', {
+      seeds: sanitized,
       max_hops: max_hops,
     });
   } catch (e) {
     const msg = (e && e.message) ? String(e.message) : 'unknown';
-    return _degraded({
+    return Object.assign(_degraded({
       max_hops: max_hops,
       rationale: 'brain_query_failed: ' + msg.slice(0, 60),
-    });
+    }), { confidence_omitted: true });
+  }
+
+  // Degraded envelope from server.
+  if (!opResult || opResult.degraded) {
+    return Object.assign(_degraded({ max_hops: max_hops, rationale: 'brain_returned_degraded' }), { confidence_omitted: true });
   }
 
-  const rows = _unwrapRows(result);
+  const rows = Array.isArray(opResult.rows) ? opResult.rows : null;
   if (rows === null) {
-    return _degraded({ max_hops: max_hops, rationale: 'brain_returned_non_array' });
+    return Object.assign(_degraded({ max_hops: max_hops, rationale: 'brain_returned_non_array' }), { confidence_omitted: true });
   }
 
-  // Map raw rows to the framework_chain_hint edge shape. Null-tolerant per
-  // G-05: confidence and transform_description may be null on the live graph
-  // and we preserve null explicitly (no defaults). hop_distance comes from
-  // length(r) which is always a number when the row exists.
-  // Defensive: hard-cap at 50 even though the Cypher already enforces LIMIT 50.
+  // Map curated op rows { from, to, hop_distance } to the edge shape.
+  // confidence and transform_description are NOT in the curated op response;
+  // they are set to null explicitly and flagged via confidence_omitted.
   const edges = rows.slice(0, 50).map(function (r) {
     return {
       from: (r && typeof r.from === 'string') ? r.from : null,
       to: (r && typeof r.to === 'string') ? r.to : null,
-      confidence: (r && typeof r.confidence === 'number') ? r.confidence : null,
-      transform_description: (r && typeof r.transform_description === 'string')
-        ? r.transform_description
-        : null,
+      confidence: null,              // not provided by curated op
+      transform_description: null,  // not provided by curated op
       hop_distance: (r && typeof r.hop_distance === 'number') ? r.hop_distance : null,
     };
   });
 
-  // brain_snapshot_id: per CONTEXT.md Open Question #4, "Brain commit_id if
-  // exposed, else SHA of Cypher result." The shipped brain_query does NOT
-  // expose a commit_id; we derive a deterministic content hash of the raw
-  // rows so callers can detect slice changes without holding the rows
-  // themselves (Plan 03 + downstream packet validator never sees them).
+  // Deterministic content hash for cache invalidation (content-addressed
+  // snapshot -- same rationale as the original implementation).
   const snapshotId = _sha256Hex(JSON.stringify(rows));
 
   return {
     edges: edges,
     slice_scope: max_hops,
     slice_rationale: 'brain_reachable; ' + edges.length + ' edges fetched; '
-      + sanitized.length + ' active_frameworks; max_hops=' + max_hops,
+      + sanitized.length + ' seeds; max_hops=' + max_hops,
     brain_snapshot_id: snapshotId,
     fetched_at: _nowIso(),
+    confidence_omitted: true,
   };
 }
 

package/lib/core/brain-client.cjs

@@ -464,6 +464,59 @@ async function ask(question) {
   return callTool('brain_ask', { question: question });
 }
 
+/**
+ * Curated-op call against the Brain (the `op` MODE of brain_ask).
+ *
+ * brain_ask gained an optional curated-op surface (BUG 2 fix). Where ask()
+ * runs the natural-language directive path, askOp() runs one of a closed set
+ * of named, parameterized operations the Brain resolves to a FROZEN
+ * server-side Cypher string. The three ops:
+ *
+ *   - 'list_frameworks'       params { limit? }            -> rows { name, description, category }
+ *   - 'framework_edges'       params { edge_type, limit? } -> rows { from, to, confidence, transform }
+ *                                                            or { framework, problem_type }
+ *   - 'framework_chain_slice' params { seeds, max_hops?, limit? } -> rows { from, to, hop_distance }
+ *
+ * Canon Part 8: every param is a generic methodology handle (framework name,
+ * closed enum, integer) -- never user content. No caller Cypher is ever sent;
+ * the Brain owns the query text. This path is ungated -- any valid key may
+ * call it (only query()/write() touch the admin-gated tools).
+ *
+ * Consumers that only need a framework chain for ONE anchor keep using
+ * ask(question) and read next_gate.options[].framework (the directive path).
+ *
+ * Returns the parsed curated-op payload { op, source, count, rows, degraded? }
+ * on success. On any transport / parse failure (Brain unreachable, no API key,
+ * bad payload) returns a graceful { op, count: 0, rows: [], degraded: true } so
+ * the caller never crashes -- mirrors query()'s graceful-degradation contract.
+ *
+ * @param {string} operation - one of the three curated op names
+ * @param {object} [params]  - generic-handles-only params object
+ * @returns {Promise<{op: string, source?: string, count: number, rows: Array, degraded?: boolean}>}
+ */
+async function askOp(operation, params = {}) {
+  try {
+    const result = await callTool('brain_ask', { op: operation, params: params || {} });
+    // callTool already parses the JSON text payload of the MCP content item,
+    // so a well-formed curated-op response arrives as the payload object.
+    if (result && typeof result === 'object'
+        && typeof result.count === 'number' && Array.isArray(result.rows)) {
+      return {
+        op: result.op || operation,
+        source: result.source,
+        count: result.count,
+        rows: result.rows,
+        ...(result.degraded ? { degraded: true } : {}),
+      };
+    }
+    // Unreachable Brain (null), an error/text passthrough, or any unexpected
+    // shape -> graceful degraded sentinel.
+    return { op: operation, count: 0, rows: [], degraded: true };
+  } catch (_err) {
+    return { op: operation, count: 0, rows: [], degraded: true };
+  }
+}
+
 /**
  * Get Pinecone stats.
  */
@@ -1242,6 +1295,7 @@ module.exports = {
   search,
   smartSearch,
   ask,
+  askOp,
   schema,
   stats,
   enrichCausalEdges,

package/lib/core/brain-derivation-prompts.cjs

@@ -182,18 +182,20 @@ function safeInt(value, fallback) {
 // interface (which takes raw cypher); interpolation is unavoidable.
 // Safety is achieved by the two-layer validation above.
 
+// BUG 2 fix: was mode:'query' (admin-gated brain_query with ADDRESSES_PROBLEM_TYPE
+// Cypher). Repointed to mode:'search' (ungated brain_search). Returns a semantic
+// search string instead of Cypher. The Brain's Pinecone index surfaces frameworks
+// that address the problem type and phase via embedding similarity.
+// Canon Part 8: only frozen enum strings are interpolated -- no user content.
 function buildPatternMatchesQuery(ctx) {
   validateCtx(ctx);
   const section = safeEnum(ctx.section_slug, 'unknown');
   const problemType = safeEnum(ctx.problem_type, 'UDP');
   const phase = safeEnum(ctx.phase_indicator, 'unknown');
   return (
-    'MATCH (f:Framework)-[:ADDRESSES_PROBLEM_TYPE]->(pt:ProblemType) ' +
-    'WHERE pt.name CONTAINS "' + problemType + '" ' +
-    'OPTIONAL MATCH (f)-[:APPLIES_AT_PHASE]->(p:Phase {name: "' + phase + '"}) ' +
-    'RETURN f.name AS framework, f.description AS description, ' +
-    '"' + section + '" AS section_slug ' +
-    'LIMIT 10'
+    'frameworks that address problem_type:' + problemType +
+    ' at phase:' + phase +
+    ' for section:' + section
   );
 }
 
@@ -241,15 +243,18 @@ function buildUnfilledOpportunityMatchesQuery(ctx) {
   );
 }
 
+// BUG 2 fix: was mode:'query' (admin-gated brain_query with FEEDS_INTO Cypher).
+// Repointed to mode:'search' (ungated brain_search). Returns a semantic
+// search string instead of Cypher. The Brain's Pinecone index surfaces framework
+// chain predictions via embedding similarity on FEEDS_INTO relationships.
+// Canon Part 8: only frozen enum strings are interpolated -- no user content.
 function buildFrameworkChainPredictionsQuery(ctx) {
   validateCtx(ctx);
   const phase = safeEnum(ctx.phase_indicator, 'unknown');
   const problemType = safeEnum(ctx.problem_type, 'UDP');
   return (
-    'MATCH (f1:Framework)-[:APPLIES_AT_PHASE]->(p:Phase {name: "' + phase + '"}) ' +
-    'MATCH (f1)-[:FEEDS_INTO]->(f2:Framework) ' +
-    'OPTIONAL MATCH (f1)-[:ADDRESSES_PROBLEM_TYPE]->(pt:ProblemType {name: "' + problemType + '"}) ' +
-    'RETURN f1.name AS from_framework, f2.name AS to_framework LIMIT 10'
+    'framework chain predictions FEEDS_INTO phase:' + phase +
+    ' problem_type:' + problemType
   );
 }
 

package/lib/core/brain-derivation.cjs

@@ -58,12 +58,26 @@ const prompts = require('./brain-derivation-prompts.cjs');
 
 // Section heading -> prompt builder mapping. Order matters: this is the
 // canonical emission order inside BRAIN.md body.
+//
+// BUG 2 fix (2026-05-22): sections whose Cypher traverses FEEDS_INTO or
+// ADDRESSES_PROBLEM_TYPE edges are repointed from mode:'query' (admin-gated
+// brain_query) to mode:'search' (ungated brain_search). Their prompt builders
+// are also updated (see brain-derivation-prompts.cjs) to emit a semantic
+// search string instead of raw Cypher. The SECTION_BUILDERS mode field is
+// the dispatch key in the derivation loop below.
+//
+// Sections that still use mode:'query' target node types with no curated op
+// and no practical semantic-search equivalent (WickedIndicator, Opportunity,
+// RigorLevel, ProblemType, HsiRecommendation). Those calls will fail (or
+// return empty) for non-admin users -- that is the correct graceful-degradation
+// behaviour (existing firstError path). A future phase can add curated ops
+// for those node types.
 const SECTION_BUILDERS = Object.freeze([
-  { heading: 'Pattern Matches',                     builder: 'buildPatternMatchesQuery',                     mode: 'query' },
+  { heading: 'Pattern Matches',                     builder: 'buildPatternMatchesQuery',                     mode: 'search' },
   { heading: 'Cross-Domain Analogies',              builder: 'buildCrossDomainAnalogiesQuery',               mode: 'search' },
   { heading: 'Wicked Indicators',                   builder: 'buildWickedIndicatorsQuery',                   mode: 'query' },
   { heading: 'Unfilled Opportunity Matches',        builder: 'buildUnfilledOpportunityMatchesQuery',         mode: 'query' },
-  { heading: 'Framework Chain Predictions',         builder: 'buildFrameworkChainPredictionsQuery',          mode: 'query' },
+  { heading: 'Framework Chain Predictions',         builder: 'buildFrameworkChainPredictionsQuery',          mode: 'search' },
   { heading: 'Assessment Thinking Chain Position',  builder: 'buildAssessmentThinkingChainPositionQuery',    mode: 'query' },
   { heading: 'ProblemType Classification',          builder: 'buildProblemTypeClassificationQuery',          mode: 'query' },
   { heading: 'Flagged Contradictions (cross-room)', builder: 'buildFlaggedContradictionsXroomQuery',         mode: 'query' },

package/lib/core/mcp-dep-heal.cjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * MindrianOS Plugin -- MCP dependency self-heal (Option D, hybrid self-heal).
+ *
+ * THE PROBLEM (debug session mcp-servers-cache-missing-node-modules):
+ * `claude plugin update` lands a fresh plugin cache directory with NO
+ * node_modules. The SessionStart reconcile hook (scripts/sessionstart-npm-
+ * reconcile.cjs) repairs it -- but on the FIRST post-update session Claude Code
+ * spawns the bundled MCP servers (.mcp.json, alwaysLoad) at a moment that can
+ * precede the hook's npm install finishing. The servers then crash at module
+ * load with MODULE_NOT_FOUND for @modelcontextprotocol/sdk.
+ *
+ * THE FIX (this module): make each MCP entry point self-sufficient. Each server
+ * calls `requireWithHeal(...)` instead of bare `require(...)`. On a
+ * MODULE_NOT_FOUND it runs a ONE-SHOT synchronous `npm install` in the plugin
+ * cache root, then re-requires. Combined with flipping the reconcile hook to
+ * synchronous (async:false) in hooks.json, this closes the race from both ends:
+ *   - healthy session: requireWithHeal succeeds first try, near-zero cost.
+ *   - first post-update session: the hook usually wins; if it has not, the
+ *     server heals itself before connecting its transport.
+ *
+ * RACE GUARD: both servers can spawn together. npm-install-lock.cjs guarantees
+ * exactly one runs `npm install` while the other WAITS, so two concurrent
+ * installs never corrupt node_modules.
+ *
+ * Canon Part 8: zero network surface. The only child process is `npm install`.
+ * No Brain calls, no external requests, no user data.
+ *
+ * Canon Part 7: reuse before build -- this mirrors the detection logic already
+ * in scripts/sessionstart-npm-reconcile.cjs (the hook) rather than inventing a
+ * new mechanism; it is the same `npm install --no-audit --no-fund --silent`
+ * invocation, wrapped for the require-time crash path.
+ *
+ * CROSS-PLATFORM (escalated mandate 2026-05-21): the npm invocation is resolved
+ * through lib/core/npm-cli-resolve.cjs, which runs npm via its absolute
+ * npm-cli.js entry off process.execPath -- correct on Windows (no `.cmd`
+ * dependency), Mac (no PATH dependency for GUI-launched Claude Code), and Linux.
+ * The bare spawnSync('npm') the prior fix used was dead on Windows and fragile
+ * on Mac. The self-heal here is the BACKSTOP; the primary guarantee is the
+ * vendored production node_modules shipped with the plugin (see CHANGELOG
+ * v1.13.0-beta.23) -- on a normal install ensureDepsPresent finds the deps
+ * already present and never spawns anything.
+ *
+ * HARD RULE: no em-dashes anywhere in this file (hyphens only).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const {
+  acquireInstallLock,
+  releaseInstallLock,
+  waitForUnlock,
+} = require('./npm-install-lock.cjs');
+const { resolveNpmCli, buildInstallArgs } = require('./npm-cli-resolve.cjs');
+
+/**
+ * Resolve the plugin cache root the install must run in. CLAUDE_PLUGIN_ROOT is
+ * set by Claude Code when it spawns plugin processes; the __dirname fallback
+ * (lib/core -> plugin root) covers manual / test invocation.
+ *
+ * @param {string} [fallbackDir] - explicit override (used by callers / tests)
+ * @returns {string}
+ */
+function resolvePluginRoot(fallbackDir) {
+  return (
+    process.env.CLAUDE_PLUGIN_ROOT ||
+    process.env.MINDRIAN_OS_ROOT ||
+    fallbackDir ||
+    path.resolve(__dirname, '..', '..')
+  );
+}
+
+/**
+ * Run `npm install` once in `dir`, guarded so two racing servers cannot run it
+ * concurrently. The loser waits for the winner instead.
+ *
+ * @param {string} dir
+ * @returns {{ ran: boolean, waited: boolean, ok: boolean }}
+ */
+function runGuardedInstall(dir) {
+  const haveLock = acquireInstallLock(dir);
+
+  if (!haveLock) {
+    // Another live process is installing. Wait for it, then return without
+    // running our own install -- node_modules should now exist.
+    const cleared = waitForUnlock(dir);
+    return { ran: false, waited: true, ok: cleared };
+  }
+
+  try {
+    // Portable npm resolution: run npm via its absolute npm-cli.js off the
+    // current node binary (process.execPath). This is correct on Windows
+    // (no `.cmd` extension dependency), Mac (no PATH dependency), and Linux.
+    const npm = resolveNpmCli();
+    const result = spawnSync(
+      npm.command,
+      buildInstallArgs(npm),
+      { cwd: dir, timeout: 120000, stdio: 'ignore', shell: npm.shell }
+    );
+    const ok = !!result && result.status === 0;
+    return { ran: true, waited: false, ok };
+  } catch (_) {
+    return { ran: true, waited: false, ok: false };
+  } finally {
+    releaseInstallLock(dir);
+  }
+}
+
+/**
+ * require() a module; on MODULE_NOT_FOUND, run a one-shot guarded `npm install`
+ * in the plugin cache root and retry exactly once.
+ *
+ * Any non-MODULE_NOT_FOUND error is re-thrown immediately (a real bug, not a
+ * missing-dependency situation -- healing would not help).
+ *
+ * @param {string} moduleId   - the module specifier to require
+ * @param {object} [opts]
+ * @param {string} [opts.pluginRoot] - explicit plugin cache root override
+ * @param {function} [opts.log]      - sink for a one-line stderr breadcrumb
+ * @returns {*} the required module
+ */
+function requireWithHeal(moduleId, opts) {
+  opts = opts || {};
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+  try {
+    return require(moduleId);
+  } catch (err) {
+    if (!err || err.code !== 'MODULE_NOT_FOUND') throw err;
+
+    const dir = resolvePluginRoot(opts.pluginRoot);
+    log('[mcp-dep-heal] missing dependency for ' + moduleId + '; self-healing npm install in ' + dir);
+
+    const outcome = runGuardedInstall(dir);
+    log(
+      '[mcp-dep-heal] install ' +
+        (outcome.waited ? 'waited-for-peer' : outcome.ran ? 'ran' : 'skipped') +
+        '; ok=' + outcome.ok
+    );
+
+    // Retry the require. If the peer-install or our own install succeeded the
+    // module now resolves. If it still fails, the error propagates -- the
+    // server crashes with a clear MODULE_NOT_FOUND, exactly as before, and the
+    // SessionStart reconcile hook is the remaining safety net for next session.
+    return require(moduleId);
+  }
+}
+
+/**
+ * The full production dependency set the plugin requires at runtime, read from
+ * the plugin's own package.json. This is the bug_011 fix: a probe limited to
+ * just ['@modelcontextprotocol/sdk', 'zod'] passes on a PARTIALLY-populated
+ * node_modules (sdk + zod present, @modelcontextprotocol/ext-apps or another
+ * dep absent), no heal runs, then a bare `require` deeper in the lib/mcp/*
+ * chain (capability-registry.cjs -> app-views.cjs -> ext-apps/server) throws
+ * MODULE_NOT_FOUND at module-init scope and crashes the server. Probing the
+ * full `dependencies` set -- exactly as scripts/sessionstart-npm-reconcile.cjs
+ * already does -- catches an incomplete tree before any require runs.
+ *
+ * Defensive: a missing or unreadable package.json yields the MCP-critical pair
+ * as a fallback rather than crashing -- the heal pre-flight must never throw.
+ *
+ * @param {string} dir - resolved plugin cache root
+ * @returns {string[]} dependency names to stat-check
+ */
+function productionDepNames(dir) {
+  const fallback = ['@modelcontextprotocol/sdk', 'zod'];
+  try {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return fallback;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const names = Object.keys(pkg.dependencies || {});
+    return names.length ? names : fallback;
+  } catch (_) {
+    // Unreadable / unparseable package.json -- fall back gracefully.
+    return fallback;
+  }
+}
+
+/**
+ * Heal the plugin's node_modules up front, BEFORE any dependency require runs.
+ * Cheap pre-flight: a few stat() calls on a healthy box, the guarded install
+ * only on a genuinely-missing cache.
+ *
+ * MCP entry points call this once at the very top so the subsequent SDK / zod
+ * requires are guaranteed to resolve. Idempotent and defensive: any error is
+ * swallowed (the per-require requireWithHeal path remains as a second net).
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.pluginRoot]
+ * @param {string[]} [opts.probe] - explicit dependency names to stat-check.
+ *                                  When omitted, defaults to the FULL
+ *                                  production dependency set from the plugin's
+ *                                  package.json (bug_011) so a partially
+ *                                  populated node_modules is detected, not just
+ *                                  a totally absent one.
+ * @param {function} [opts.log]
+ * @returns {{ healed: boolean, ok: boolean }}
+ */
+function ensureDepsPresent(opts) {
+  opts = opts || {};
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+  const dir = resolvePluginRoot(opts.pluginRoot);
+  const probe = Array.isArray(opts.probe) && opts.probe.length
+    ? opts.probe
+    : productionDepNames(dir);
+
+  try {
+    const nm = path.join(dir, 'node_modules');
+    let missing = false;
+    if (!fs.existsSync(nm)) {
+      missing = true;
+    } else {
+      for (const dep of probe) {
+        if (!fs.existsSync(path.join(nm, ...dep.split('/')))) { missing = true; break; }
+      }
+    }
+    if (!missing) return { healed: false, ok: true };
+
+    log('[mcp-dep-heal] node_modules missing/incomplete; self-healing npm install in ' + dir);
+    const outcome = runGuardedInstall(dir);
+    log(
+      '[mcp-dep-heal] install ' +
+        (outcome.waited ? 'waited-for-peer' : 'ran') +
+        '; ok=' + outcome.ok
+    );
+    return { healed: true, ok: outcome.ok };
+  } catch (_) {
+    // Never let the heal pre-flight itself crash the server -- requireWithHeal
+    // is the backstop.
+    return { healed: false, ok: false };
+  }
+}
+
+module.exports = {
+  requireWithHeal,
+  ensureDepsPresent,
+  runGuardedInstall,
+  resolvePluginRoot,
+  productionDepNames,
+};