monomind 2.1.5 → 2.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "Open-source CLI extension for Claude Code. Adds an MCP server with a codebase knowledge graph, persistent memory, multi-agent coordination, and reusable slash commands. MIT licensed, runs locally, no data leaves your machine.",
   "main": "dist/index.js",
   "type": "module",

package/packages/@monomind/cli/.claude/helpers/handlers/session-restore-handler.cjs

@@ -45,9 +45,13 @@ module.exports = {
       }
     } catch (e) { /* @monomind/hooks not available or not built — skip */ }
 
-    // Stale helper detection — warn when project helpers drift from the bundled npm copy.
-    // Skip when running inside the monomind dev repo itself: local helpers ARE the
-    // source of truth there, so any diff vs. the npm global install is expected.
+    // Stale helper self-heal — silently refresh project helpers that drift from
+    // the bundled npm copy, so a `npm i -g monomind@latest` (or npx picking up a
+    // new version) takes effect on the very next session instead of requiring a
+    // manual `doctor --fix` / `init upgrade`. Skip when running inside the
+    // monomind dev repo itself: local helpers ARE the source of truth there, so
+    // any diff vs. the npm global install is expected (and would self-clobber
+    // in-progress edits).
     try {
       var _isDevRepo = fs.existsSync(path.join(CWD, 'packages', '@monomind', 'cli', 'package.json'));
       if (!_isDevRepo) {
@@ -76,26 +80,95 @@ module.exports = {
           return null;
         }
 
+        function _hashFile(p) {
+          try { return crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex'); }
+          catch (_) { return null; }
+        }
+
+        // Copy `bundledF` -> `localF` iff their contents differ (or local is missing).
+        // Atomic copy-via-rename so a partial write can never leave a broken hook.
+        function _healIfStale(localF, bundledF) {
+          if (!fs.existsSync(bundledF)) return null;
+          var hashB = _hashFile(bundledF);
+          var hashL = fs.existsSync(localF) ? _hashFile(localF) : null;
+          if (hashL === hashB) return null;
+          try {
+            var tmp = localF + '.' + process.pid + '.tmp';
+            fs.mkdirSync(path.dirname(localF), { recursive: true });
+            fs.copyFileSync(bundledF, tmp);
+            try { fs.chmodSync(tmp, 0o755); } catch (_) {}
+            fs.renameSync(tmp, localF);
+            return path.relative(path.join(CWD, '.claude', 'helpers'), localF);
+          } catch (_) { return null; }
+        }
+
         var bundledDir = _findBundledHelpers();
         if (bundledDir) {
-          var helpersToCheck = ['hook-handler.cjs', 'statusline.cjs'];
-          var stale = [];
+          var healed = [];
+          // Top-level critical files — mirrors executor.ts's `criticalHelpers` list.
+          var helpersToCheck = ['hook-handler.cjs', 'statusline.cjs', 'router.cjs', 'graphify-freshen.cjs', 'intelligence.cjs', 'auto-memory-hook.mjs'];
           for (var hi = 0; hi < helpersToCheck.length; hi++) {
             var hName = helpersToCheck[hi];
-            var localF   = path.join(CWD, '.claude', 'helpers', hName);
-            var bundledF = path.join(bundledDir, hName);
-            if (!fs.existsSync(localF) || !fs.existsSync(bundledF)) continue;
-            try {
-              var hashL = crypto.createHash('sha256').update(fs.readFileSync(localF)).digest('hex');
-              var hashB = crypto.createHash('sha256').update(fs.readFileSync(bundledF)).digest('hex');
-              if (hashL !== hashB) stale.push(hName);
-            } catch (_) {}
+            var healedName = _healIfStale(
+              path.join(CWD, '.claude', 'helpers', hName),
+              path.join(bundledDir, hName)
+            );
+            if (healedName) healed.push(healedName);
           }
-          if (stale.length > 0) {
-            console.log('[STALE_HELPERS] Project helpers differ from bundled version: ' + stale.join(', '));
-            console.log('  Run `npx monomind@latest init upgrade` to refresh and pick up the latest features.');
+          // handlers/ and utils/ subdirectories — where most real hook-behavior
+          // fixes actually live (capture-handler.cjs, gates-handler.cjs, etc.).
+          var subdirs = ['handlers', 'utils'];
+          for (var si = 0; si < subdirs.length; si++) {
+            var bundledSub = path.join(bundledDir, subdirs[si]);
+            if (!fs.existsSync(bundledSub)) continue;
+            var files;
+            try { files = fs.readdirSync(bundledSub).filter(function(f) { return !f.startsWith('._') && !fs.statSync(path.join(bundledSub, f)).isDirectory(); }); }
+            catch (_) { files = []; }
+            for (var fi = 0; fi < files.length; fi++) {
+              var healedName2 = _healIfStale(
+                path.join(CWD, '.claude', 'helpers', subdirs[si], files[fi]),
+                path.join(bundledSub, files[fi])
+              );
+              if (healedName2) healed.push(healedName2);
+            }
+          }
+          if (healed.length > 0) {
+            console.log('[STALE_HELPERS] Refreshed ' + healed.length + ' helper(s) from bundled version: ' + healed.join(', '));
           }
         }
+
+        // Fallback for pure `npx monomind@latest ...` usage — the local scan above
+        // only finds a bundled copy via node_modules or a global npm install, but a
+        // per-invocation `npx` run leaves no reliably-discoverable copy there (each
+        // invocation caches under a hashed, non-predictable ~/.npm/_npx/<hash>/ dir
+        // that this process has no correct way to pick the newest of without risking
+        // healing "backward" to some older cached version). `npx monomind@latest`
+        // itself already resolves this correctly (it always fetches/uses latest),
+        // and `doctor --fix` reuses the exact same bundled-package resolution that
+        // `init upgrade` uses — so shell out to it instead of re-solving the same
+        // problem here. Rate-limited to once per 6h (mirrors the metrics-worker
+        // staleness gate below) and fully non-blocking: spawned detached+unref with
+        // stdio ignored, session start never waits on it, and a fresh session or
+        // hook a few seconds later just picks up whatever it left behind.
+        try {
+          var _healCheckPath = path.join(CWD, '.monomind', 'helpers-heal-check.json');
+          var _lastHealCheck = 0;
+          try { _lastHealCheck = JSON.parse(fs.readFileSync(_healCheckPath, 'utf-8')).ts || 0; } catch (_) {}
+          var HEAL_CHECK_STALE_MS = 6 * 60 * 60 * 1000; // 6 hours
+          if (Date.now() - _lastHealCheck > HEAL_CHECK_STALE_MS) {
+            fs.mkdirSync(path.dirname(_healCheckPath), { recursive: true });
+            try { fs.writeFileSync(_healCheckPath, JSON.stringify({ ts: Date.now() }), 'utf-8'); } catch (_) {}
+            var _spawn = require('child_process').spawn;
+            var _child = _spawn('npx', ['-y', 'monomind@latest', 'doctor', '--fix', '--component', 'helpers'], {
+              cwd: CWD,
+              detached: true,
+              stdio: 'ignore',
+              env: process.env,
+            });
+            _child.on('error', function() {}); // offline / npx unavailable — silently skip
+            _child.unref();
+          }
+        } catch (e) { /* non-fatal — background self-heal is best-effort */ }
       }
     } catch (e) { /* non-fatal */ }
 

package/packages/@monomind/cli/dist/src/commands/doctor-project-checks.js

@@ -2,7 +2,7 @@
  * Doctor — project/monomind health checks
  * Config, memory, API keys, MCP, monograph, helpers, routing, gates, gitignore, worker metrics
  */
-import { existsSync, readFileSync, statSync, mkdirSync, copyFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, copyFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -234,21 +234,47 @@ function _resolveBundledHelper(relativePath) {
         return null;
     }
 }
+// Top-level critical helpers, plus every file bundled under handlers/ and utils/
+// (capture-handler.cjs, gates-handler.cjs, route-handler.cjs, session-handler.cjs,
+// etc. — where most actual hook-behavior fixes live). Subdir membership is
+// discovered from the bundled package itself, not hardcoded, so a helper added
+// upstream is picked up automatically instead of silently never syncing.
+function _allTrackedHelperNames() {
+    const names = ['hook-handler.cjs', 'statusline.cjs', 'router.cjs', 'graphify-freshen.cjs'];
+    for (const sub of ['handlers', 'utils']) {
+        const bundledSubDir = _resolveBundledHelper(join('.claude', 'helpers', sub));
+        if (!bundledSubDir)
+            continue;
+        try {
+            for (const f of readdirSync(bundledSubDir)) {
+                if (f.startsWith('._'))
+                    continue;
+                if (statSync(join(bundledSubDir, f)).isDirectory())
+                    continue;
+                names.push(join(sub, f));
+            }
+        }
+        catch { /* skip */ }
+    }
+    return names;
+}
 async function _detectStaleHelpers() {
     const stale = [];
     const missing = [];
-    const helpers = ['hook-handler.cjs', 'statusline.cjs', 'router.cjs', 'graphify-freshen.cjs'];
     const crypto = await import('node:crypto');
-    for (const name of helpers) {
-        const local = join(process.cwd(), '.claude', 'helpers', name);
-        if (!existsSync(local) || statSync(local).size > MAX_DOCTOR_HELPER_BYTES)
-            continue;
+    for (const name of _allTrackedHelperNames()) {
         const bundled = _resolveBundledHelper(join('.claude', 'helpers', name));
-        if (!bundled) {
-            missing.push(name);
+        if (!bundled || statSync(bundled).size > MAX_DOCTOR_HELPER_BYTES) {
+            if (!bundled)
+                missing.push(name);
             continue;
         }
-        if (statSync(bundled).size > MAX_DOCTOR_HELPER_BYTES)
+        const local = join(process.cwd(), '.claude', 'helpers', name);
+        if (!existsSync(local)) {
+            stale.push(name);
+            continue;
+        } // bundled has it, project doesn't — needs creating
+        if (statSync(local).size > MAX_DOCTOR_HELPER_BYTES)
             continue;
         try {
             const hashLocal = crypto.createHash('sha256').update(readFileSync(local)).digest('hex');
@@ -268,6 +294,7 @@ export async function fixStaleHelpers() {
         const bundled = _resolveBundledHelper(join('.claude', 'helpers', name));
         if (bundled) {
             try {
+                mkdirSync(dirname(local), { recursive: true });
                 copyFileSync(bundled, local);
                 fixed++;
             }

package/packages/@monomind/cli/dist/src/commands/doctor.js

@@ -19,7 +19,7 @@ export const doctorCommand = {
     name: 'doctor',
     description: 'System diagnostics and health checks',
     options: [
-        { name: 'fix', short: 'f', description: 'Show fix commands for issues', type: 'boolean', default: false },
+        { name: 'fix', short: 'f', description: 'Apply local fixes (helper files, monoes tool shims) and show fix commands for the rest', type: 'boolean', default: false },
         { name: 'install', short: 'i', description: 'Auto-install missing dependencies (Claude Code CLI)', type: 'boolean', default: false },
         {
             name: 'component', short: 'c',
@@ -122,9 +122,16 @@ export const doctorCommand = {
             spinner.stop();
             output.writeln(output.error('Failed to run health checks'));
         }
-        if (autoInstall) {
+        // `--fix` applies the lightweight, local, no-network fixes (helper files,
+        // monoes CLI tool shims) — its description says "show fix commands" but
+        // silently doing nothing for these two beyond printing a hint is a worse
+        // outcome than just fixing them, and copying a bundled file locally is
+        // nothing like installing a package. `--install` additionally covers the
+        // Claude Code CLI, which is a real install (network fetch + binary setup)
+        // — kept opt-in separately so `--fix` alone never triggers that.
+        if (autoInstall || showFix) {
             const claudeResult = results.find(r => r.name === 'Claude Code CLI');
-            if (claudeResult && claudeResult.status !== 'pass') {
+            if (autoInstall && claudeResult && claudeResult.status !== 'pass') {
                 if (await installClaudeCode()) {
                     const newCheck = await checkClaudeCode();
                     const idx = results.findIndex(r => r.name === 'Claude Code CLI');

package/packages/@monomind/cli/dist/src/init/executor.js

@@ -574,7 +574,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
         if (sourceHelpersForUpgrade) {
             const destHelpersDir = path.join(targetDir, '.claude', 'helpers');
             // Copy top-level critical files atomically
-            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs', 'graphify-freshen.cjs'];
+            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs', 'graphify-freshen.cjs', 'router.cjs'];
             // Generated fallback for any critical helper missing from the source dir itself
             // (e.g. the published npm template lacking auto-memory-hook.mjs).
             const criticalGenerators = {
@@ -630,6 +630,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 'hook-handler.cjs': generateHookHandler(),
                 'intelligence.cjs': generateIntelligenceStub(),
                 'auto-memory-hook.mjs': generateAutoMemoryHook(),
+                'router.cjs': generateAgentRouter(),
             };
             for (const [helperName, content] of Object.entries(generatedCritical)) {
                 const targetPath = path.join(targetDir, '.claude', 'helpers', helperName);

package/packages/@monomind/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "type": "module",
   "description": "CLI engine for Monomind — an open-source MCP server that extends Claude Code with a codebase knowledge graph (tree-sitter + SQLite), persistent memory, multi-agent task coordination, and session hooks. MIT licensed, fully local.",
   "main": "dist/src/index.js",