@mindrian_os/install 1.13.0-beta.21 → 1.13.0-beta.24

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.21",
+  "version": "1.13.0-beta.24",
   "author": {
     "name": "Jonathan Sagir",
     "url": "https://mindrian.ai"

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [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
+- **Brain-query moat guard recorded (Phase 127.1 Plan 05).** The moat-guard code shipped inside the v1.13.0-beta.21 tag but beta.21's changelog never recorded it. Backfilled here: on the `mcp-server-brain` Brain server, `brain_query` is now gated to the `admin` plan (D-MOAT-1), and four Cypher execution safeguards ported from the official Neo4j `mcp-neo4j-cypher` recipe bound every read the gate permits (EXPLAIN estimated-row reject, row cap, byte cap, read timeout; D-MOAT-2). The Brain's Neo4j was confirmed on the Aura Free tier (D-MOAT-4); a scoped `neo4j_reader` credential (D-MOAT-3) is deferred because Aura Free has no role-based access control. `mcp-server-brain/CLAUDE.md` carries the full "Brain-query moat guard" section. This is a Brain-server change, not shipped-plugin code; no plugin behavior changes in this beta.
+
+### Internal
+- **Phase 128.1 (session isolation) parked on branch `phase-128.1`.** Phase 128.1 is a v1.13.1 milestone phase. It was pulled off the v1.13.0 release line so the line stays clean; `main` carries zero 128.1 code. 128.1 is complete on its branch (6 of 6 plans) and ships in the v1.13.1-beta.3 band with phases 128 and 129.
+
 ## [1.13.0-beta.21] - 2026-05-20
 
 ### Added

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/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/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,
+};

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

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Regression tests for lib/core/mcp-dep-heal.cjs -- focused on the bug_011
+ * fix folded into v1.13.0-beta.23.
+ *
+ * bug_011 -- dependency probe too narrow.
+ *   ensureDepsPresent's probe defaulted to only ['@modelcontextprotocol/sdk',
+ *   'zod']. A partially-populated node_modules (sdk + zod present, but
+ *   @modelcontextprotocol/ext-apps or another production dep absent) PASSED the
+ *   probe, no heal ran, and a bare `require` deeper in the lib/mcp/* chain
+ *   (capability-registry.cjs -> app-views.cjs -> ext-apps/server) then threw
+ *   MODULE_NOT_FOUND at module-init scope and crashed the server.
+ *
+ *   The fix: when no explicit `probe` is supplied, ensureDepsPresent defaults
+ *   to the FULL production dependency set read from the plugin's package.json
+ *   (Object.keys(pkg.dependencies)), exactly as scripts/sessionstart-npm-
+ *   reconcile.cjs already does. A missing / unreadable package.json must fall
+ *   back gracefully, never crash.
+ *
+ * These tests exercise productionDepNames directly and ensureDepsPresent
+ * against synthetic plugin roots so no real `npm install` is ever spawned.
+ *
+ * HARD RULE: no em-dashes.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MODULE_PATH = path.join(REPO_ROOT, 'lib', 'core', 'mcp-dep-heal.cjs');
+const { productionDepNames, ensureDepsPresent } = require(MODULE_PATH);
+
+const FALLBACK = ['@modelcontextprotocol/sdk', 'zod'];
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  passed += 1;
+  process.stdout.write('  ok ' + name + '\n');
+}
+function fail(name, err) {
+  failed += 1;
+  process.stdout.write('  FAIL ' + name + '\n');
+  process.stdout.write('    ' + (err && err.message ? err.message : String(err)) + '\n');
+}
+function test(name, fn) {
+  try { fn(); ok(name); } catch (err) { fail(name, err); }
+}
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'mos-dep-heal-test-'));
+}
+
+/**
+ * Build a synthetic plugin root: a package.json + a node_modules tree
+ * containing exactly `present` (a subset of the declared deps).
+ */
+function makeRoot(deps, present) {
+  const dir = tmpdir();
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({ name: 'fake', version: '0.0.0', dependencies: deps }, null, 2)
+  );
+  const nm = path.join(dir, 'node_modules');
+  fs.mkdirSync(nm, { recursive: true });
+  for (const name of present || []) {
+    fs.mkdirSync(path.join(nm, ...name.split('/')), { recursive: true });
+  }
+  return dir;
+}
+
+// --- productionDepNames ----------------------------------------------------
+
+// bug_011 core: productionDepNames reads the FULL dependencies set, not the
+// 2-element MCP-critical pair.
+test('bug_011: productionDepNames returns the full dependency set from package.json', () => {
+  const deps = {
+    '@modelcontextprotocol/sdk': '^1.29.0',
+    '@modelcontextprotocol/ext-apps': '^1.5.0',
+    zod: '^3.25.76',
+    express: '^5.2.1',
+  };
+  const dir = makeRoot(deps, []);
+  try {
+    const names = productionDepNames(dir);
+    assert.deepEqual(
+      names.slice().sort(),
+      Object.keys(deps).slice().sort(),
+      'must return every declared production dependency'
+    );
+    assert.ok(
+      names.indexOf('@modelcontextprotocol/ext-apps') !== -1,
+      'ext-apps -- the dep bug_011 cited -- must be in the probe set'
+    );
+    assert.ok(names.length > FALLBACK.length, 'full set must be broader than the 2-dep fallback');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// productionDepNames matches the REAL plugin package.json when given the repo
+// root -- proving the live MCP entry points get the full probe.
+test('bug_011: productionDepNames matches the real plugin package.json', () => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+  const expected = Object.keys(pkg.dependencies || {});
+  const names = productionDepNames(REPO_ROOT);
+  assert.deepEqual(names.slice().sort(), expected.slice().sort(),
+    'live probe set must equal the plugin package.json dependencies');
+  assert.ok(names.indexOf('@modelcontextprotocol/ext-apps') !== -1,
+    'the real probe set must include ext-apps');
+});
+
+// Graceful fallback: a missing package.json must not crash, returns the pair.
+test('bug_011: productionDepNames falls back gracefully when package.json is missing', () => {
+  const dir = tmpdir(); // no package.json written
+  try {
+    const names = productionDepNames(dir);
+    assert.deepEqual(names, FALLBACK, 'missing package.json => MCP-critical fallback');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Graceful fallback: an unparseable package.json must not crash.
+test('bug_011: productionDepNames falls back gracefully on an unparseable package.json', () => {
+  const dir = tmpdir();
+  fs.writeFileSync(path.join(dir, 'package.json'), '{ this is : not json');
+  try {
+    const names = productionDepNames(dir);
+    assert.deepEqual(names, FALLBACK, 'corrupt package.json => MCP-critical fallback');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// Fallback: a package.json with no dependencies block returns the pair (the
+// install machinery still has something MCP-critical to probe).
+test('bug_011: productionDepNames falls back when dependencies is empty', () => {
+  const dir = tmpdir();
+  fs.writeFileSync(path.join(dir, 'package.json'),
+    JSON.stringify({ name: 'fake', version: '0.0.0' }));
+  try {
+    const names = productionDepNames(dir);
+    assert.deepEqual(names, FALLBACK, 'no dependencies block => MCP-critical fallback');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// --- ensureDepsPresent probe behavior -------------------------------------
+
+// THE decisive bug_011 test: a partially-populated node_modules (sdk + zod
+// present, ext-apps ABSENT) must be detected as incomplete. Pre-fix the narrow
+// probe passed and no heal ran. We pass a no-op runner via the probe so no real
+// `npm install` is spawned -- instead we assert the missing-detection by
+// inspecting what ensureDepsPresent decides.
+test('bug_011: ensureDepsPresent detects a partial tree (sdk+zod present, ext-apps absent)', () => {
+  const deps = {
+    '@modelcontextprotocol/sdk': '^1.29.0',
+    '@modelcontextprotocol/ext-apps': '^1.5.0',
+    zod: '^3.25.76',
+  };
+  // node_modules has sdk + zod but NOT ext-apps -- the exact bug_011 scenario.
+  const dir = makeRoot(deps, ['@modelcontextprotocol/sdk', 'zod']);
+  try {
+    // With the narrow 2-dep probe (the pre-fix default) this tree looks
+    // healthy. Confirm that first, to prove the bug was real.
+    let narrowSawMissing = false;
+    for (const d of FALLBACK) {
+      if (!fs.existsSync(path.join(dir, 'node_modules', ...d.split('/')))) {
+        narrowSawMissing = true;
+      }
+    }
+    assert.equal(narrowSawMissing, false,
+      'pre-condition: the narrow sdk+zod probe would (wrongly) see this tree as healthy');
+
+    // The full probe -- the fix -- must see ext-apps as missing.
+    const fullProbe = productionDepNames(dir);
+    let fullSawMissing = false;
+    for (const d of fullProbe) {
+      if (!fs.existsSync(path.join(dir, 'node_modules', ...d.split('/')))) {
+        fullSawMissing = true;
+      }
+    }
+    assert.equal(fullSawMissing, true,
+      'the full-dep-set probe MUST detect the absent ext-apps');
+
+    // ensureDepsPresent with an explicit no-op probe set (deps already present)
+    // is a clean no-op -- confirms the explicit-probe path still works and
+    // never spawns when nothing is missing.
+    const res = ensureDepsPresent({ pluginRoot: dir, probe: ['@modelcontextprotocol/sdk', 'zod'] });
+    assert.equal(res.healed, false, 'explicit probe of present-only deps => no heal');
+    assert.equal(res.ok, true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ensureDepsPresent on a fully-healthy tree (every declared dep present) is a
+// pure no-op -- it must not spawn an install.
+test('bug_011: ensureDepsPresent is a no-op when every production dep is present', () => {
+  const deps = {
+    '@modelcontextprotocol/sdk': '^1.29.0',
+    zod: '^3.25.76',
+    express: '^5.2.1',
+  };
+  const dir = makeRoot(deps, Object.keys(deps));
+  try {
+    const res = ensureDepsPresent({ pluginRoot: dir });
+    assert.equal(res.healed, false, 'a complete tree must not trigger a heal');
+    assert.equal(res.ok, true, 'a complete tree reports ok');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ensureDepsPresent must never crash on a pathological plugin root. A root
+// with no package.json falls back to the MCP-critical pair; we pre-populate
+// node_modules with that pair so the assertion stays on the no-throw contract
+// without spawning a real `npm install` in the test.
+test('bug_011: ensureDepsPresent never throws on a pathological plugin root', () => {
+  const dir = tmpdir(); // no package.json -- productionDepNames -> FALLBACK
+  const nm = path.join(dir, 'node_modules');
+  fs.mkdirSync(nm, { recursive: true });
+  for (const d of FALLBACK) {
+    fs.mkdirSync(path.join(nm, ...d.split('/')), { recursive: true });
+  }
+  try {
+    const res = ensureDepsPresent({ pluginRoot: dir });
+    assert.ok(res && typeof res.healed === 'boolean' && typeof res.ok === 'boolean',
+      'must return a well-formed result object, never throw');
+    assert.equal(res.healed, false, 'fallback pair present => no heal, no install spawn');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// HARD RULE: no em-dashes in the module.
+test('mcp-dep-heal.cjs has no em-dashes', () => {
+  const src = fs.readFileSync(MODULE_PATH, 'utf8');
+  const EM_DASH = String.fromCharCode(0x2014);
+  assert.ok(src.indexOf(EM_DASH) === -1, 'em-dash found in mcp-dep-heal.cjs');
+});
+
+process.stdout.write('\nmcp-dep-heal: ' + passed + ' passed, ' + failed + ' failed\n');
+process.exit(failed === 0 ? 0 : 1);