monomind 1.10.21 → 1.10.23

package/.claude/commands/monomind/understand.md

@@ -126,14 +126,18 @@ node "$SCRIPT" \
 
 The script will:
 1. Read all file nodes from the monograph DB
-2. For each file, call the Anthropic API (via `ANTHROPIC_API_KEY`) to get summaries, tags, and complexity
-3. Detect architectural layers (LLM-based if API key available, heuristic fallback otherwise)
-4. Write enrichment data back to `monograph.db` (community_id + properties JSON)
-5. Emit a `graph.json` to `$DIR/.understand/knowledge-graph.json`
-
-If `ANTHROPIC_API_KEY` is not set, the script automatically falls back to `--no-llm` mode — heuristic layer detection from file paths, no per-file summaries. Tell the user this happened.
-
-Wait for the script to complete before proceeding.
+2. Pick the best available LLM path automatically (no env vars to set):
+   - `claude -p` CLI passthrough — reuses the active Claude Code authentication
+   - direct Anthropic API — if `ANTHROPIC_API_KEY` happens to be set (faster for bulk runs)
+   - heuristic-only fallback — if neither is reachable
+3. For each file, generate summaries, tags, and complexity
+4. Detect architectural layers
+5. Write enrichment data back to `monograph.db` (community_id + properties JSON)
+6. Emit a `graph.json` to `$DIR/.understand/knowledge-graph.json`
+
+Wait for the script to complete before proceeding. Do NOT pre-check or advise about
+`ANTHROPIC_API_KEY` — the script picks its path silently and prints the chosen mode
+on stdout. Report only what the script actually reports.
 
 ---
 
@@ -173,17 +177,19 @@ Then tell the user:
 > Open the Monomind control panel and click **Monograph → GRAPH** to see multi-color layers.
 > Each color represents an architectural layer (API, Service, Data, UI, etc.).
 >
-> To re-run with full LLM analysis: `/monomind:understand --full`
-> To only refresh layer detection: `/monomind:understand --layers-only`
-> To run without API calls: `/monomind:understand --no-llm`
-> To re-analyze only changed files: `/monomind:understand --incremental`
-> To generate an onboarding guide: `/monomind:understand --onboard`
+> Common follow-ups:
+> - `/monomind:understand --full` — full re-analysis from scratch
+> - `/monomind:understand --layers-only` — refresh only layer detection
+> - `/monomind:understand --incremental` — re-analyze only changed files
+> - `/monomind:understand --onboard` — generate an onboarding guide
 
 ---
 
 ## Error Handling
 
-- If `ANTHROPIC_API_KEY` is not set, automatically use heuristic mode — report this clearly but do NOT stop.
+- The script auto-selects an LLM path (`claude -p` CLI → API key → heuristic). Do not
+  prompt the user to set `ANTHROPIC_API_KEY`. Monomind is designed to run inside an
+  authenticated Claude Code session — the CLI passthrough is the default path.
 - If the script exits non-zero, show stderr and suggest `npm install -g monomind@latest`.
 - If monograph.db has no file nodes, tell the user to run `npx monomind monograph build` first.
 - All errors are non-fatal to the main session — report and return cleanly.

package/.claude/helpers/hook-handler.cjs

@@ -1470,6 +1470,60 @@ const handlers = {
         console.log('[OK] Session restored: session-' + Date.now());
       }
     } catch (e) { console.log('[WARN] Session restore failed: ' + e.message); }
+
+    // Stale helper detection — compare local helper hashes against the
+    // bundled (npm-installed) monomind copy and warn if they drift. This
+    // is what alerts the user that 'monomind init upgrade' would pick up
+    // new features (graph fallback routing, telemetry counters, etc).
+    try {
+      var crypto = require('crypto');
+      // Walk up from this file to find the monomind package root (looks for
+      // package.json with name === 'monomind' or '@monomind/cli').
+      function _findBundledHelpers() {
+        var helperPaths = [
+          path.join(__dirname),
+          path.join(CWD, 'node_modules', 'monomind', '.claude', 'helpers'),
+          path.join(CWD, 'node_modules', '@monoes', 'monomindcli', '.claude', 'helpers'),
+        ];
+        try {
+          var globalRoot = require('child_process')
+            .execSync('npm root -g 2>/dev/null', { encoding: 'utf-8', timeout: 2000 })
+            .trim();
+          if (globalRoot) {
+            helperPaths.push(path.join(globalRoot, 'monomind', '.claude', 'helpers'));
+            helperPaths.push(path.join(globalRoot, '@monoes', 'monomindcli', '.claude', 'helpers'));
+          }
+        } catch (_) {}
+        for (var i = 0; i < helperPaths.length; i++) {
+          if (fs.existsSync(path.join(helperPaths[i], 'hook-handler.cjs')) &&
+              helperPaths[i] !== path.join(CWD, '.claude', 'helpers')) {
+            return helperPaths[i];
+          }
+        }
+        return null;
+      }
+
+      var bundledDir = _findBundledHelpers();
+      if (bundledDir) {
+        var helpersToCheck = ['hook-handler.cjs', 'statusline.cjs'];
+        var stale = [];
+        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 (_) {}
+        }
+        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.');
+        }
+      }
+    } catch (e) { /* non-fatal */ }
     // Initialize intelligence (with timeout — #1530)
     // Respects monomind.neural.enabled kill switch from settings.json
     var neuralEnabled = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "1.10.21",
+  "version": "1.10.23",
   "description": "Monomind - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

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

@@ -411,6 +411,86 @@ async function checkMonograph() {
     }
 }
 // Check agentic-flow v1 integration (filesystem-based to avoid slow WASM/DB init)
+// Resolve the path to the bundled (npm-installed) copy of a helper file.
+// Walks up from this module's location to find the package root, then joins
+// the relative path. Returns null if not found.
+function _resolveBundledHelper(relativePath) {
+    try {
+        const thisFile = fileURLToPath(import.meta.url);
+        let dir = dirname(thisFile);
+        for (;;) {
+            const candidate = join(dir, 'package.json');
+            if (existsSync(candidate)) {
+                try {
+                    const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+                    if (pkg.name === '@monomind/cli' || pkg.name === 'monomind') {
+                        const helperPath = join(dir, relativePath);
+                        return existsSync(helperPath) ? helperPath : null;
+                    }
+                }
+                catch { /* keep walking */ }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+// Compare per-project helper file content vs the bundled (npm) version.
+// Returns the list of files that drifted.
+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))
+            continue;
+        const bundled = _resolveBundledHelper(join('.claude', 'helpers', name));
+        if (!bundled) {
+            missing.push(name);
+            continue;
+        }
+        try {
+            const hashLocal = crypto.createHash('sha256').update(readFileSync(local)).digest('hex');
+            const hashBundled = crypto.createHash('sha256').update(readFileSync(bundled)).digest('hex');
+            if (hashLocal !== hashBundled)
+                stale.push(name);
+        }
+        catch { /* skip */ }
+    }
+    return { stale, missing };
+}
+async function checkHelpersFresh() {
+    try {
+        const { stale, missing } = await _detectStaleHelpers();
+        if (stale.length === 0 && missing.length === 0) {
+            return { name: 'Helper Files', status: 'pass', message: 'Project helpers match bundled version' };
+        }
+        if (stale.length > 0) {
+            return {
+                name: 'Helper Files',
+                status: 'warn',
+                message: `${stale.length} stale helper(s) in .claude/helpers/: ${stale.join(', ')}`,
+                fix: 'monomind init upgrade',
+            };
+        }
+        return {
+            name: 'Helper Files',
+            status: 'warn',
+            message: `Could not locate bundled copies of: ${missing.join(', ')}`,
+            fix: 'Reinstall monomind or run `monomind init upgrade`',
+        };
+    }
+    catch (e) {
+        return { name: 'Helper Files', status: 'warn', message: `check failed: ${e instanceof Error ? e.message : 'unknown'}` };
+    }
+}
 async function checkAgenticFlow() {
     try {
         // Walk common node_modules paths to find agentic-flow/package.json
@@ -523,6 +603,7 @@ export const doctorCommand = {
             checkDiskSpace,
             checkBuildTools,
             checkMonograph,
+            checkHelpersFresh,
             checkAgenticFlow
         ];
         const componentMap = {
@@ -540,6 +621,7 @@ export const doctorCommand = {
             'disk': checkDiskSpace,
             'typescript': checkBuildTools,
             'monograph': checkMonograph,
+            'helpers': checkHelpersFresh,
             'agentic-flow': checkAgenticFlow
         };
         let checksToRun = allChecks;

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

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "1.10.21",
+  "version": "1.10.23",
   "type": "module",
   "description": "Monomind CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",

package/packages/@monomind/cli/scripts/understand-analyze.mjs

@@ -153,12 +153,14 @@ const USE_CLAUDE_CLI = !ANTHROPIC_API_KEY && !!_detectClaudeCli();
 
 async function callClaudeViaCli(systemPrompt, userPrompt, maxTokens = 1024) {
   return new Promise((resolveP, reject) => {
+    // NOTE: do NOT pass --bare here. --bare disables OAuth/keychain reads
+    // and forces ANTHROPIC_API_KEY — which is exactly what we're avoiding.
+    // We want the CLI to use the user's logged-in Claude Code session.
     const args = [
       '-p',
       '--model', 'haiku',
       '--output-format', 'text',
-      '--bare', // skip hooks/skills/auto-memory — we want a fast, clean call
-      // Combine system + user into a single prompt argument
+      '--disable-slash-commands', // skip skill auto-resolution overhead
       `${systemPrompt}\n\n---\n\n${userPrompt}`,
     ];
     const child = spawn(_claudeCliPath, args, {
@@ -170,8 +172,8 @@ async function callClaudeViaCli(systemPrompt, userPrompt, maxTokens = 1024) {
     child.stderr.on('data', d => err += d.toString());
     const timeout = setTimeout(() => {
       child.kill('SIGKILL');
-      reject(new Error('claude -p timed out after 60s'));
-    }, 60000);
+      reject(new Error('claude -p timed out after 120s'));
+    }, 120000);
     child.on('close', code => {
       clearTimeout(timeout);
       if (code !== 0) return reject(new Error(`claude -p exited ${code}: ${err.slice(0, 200)}`));
@@ -697,11 +699,22 @@ async function main() {
   const batch = toAnalyze.slice(0, limit);
   console.log(`[understand] Analyzing ${batch.length} files (${toAnalyze.length - batch.length} skipped/already enriched)`);
 
-  const llmPath = ANTHROPIC_API_KEY ? 'api' : (USE_CLAUDE_CLI ? 'claude-cli' : 'none');
+  // Prefer the CLI passthrough when available — monomind is designed to run
+  // inside an authenticated Claude Code session and the CLI reuses that auth
+  // without prompting for an API key. Direct API only takes precedence when
+  // explicitly opted into (MONOMIND_PREFER_API=1).
+  const preferApi = process.env.MONOMIND_PREFER_API === '1';
+  const llmPath = (preferApi && ANTHROPIC_API_KEY) ? 'api'
+                : USE_CLAUDE_CLI ? 'claude-cli'
+                : ANTHROPIC_API_KEY ? 'api'
+                : 'none';
   if (llmPath === 'none' && !noLlm) {
-    console.warn('[understand] No LLM path available (no ANTHROPIC_API_KEY and no `claude` CLI) — falling back to --no-llm heuristic mode');
+    console.warn('[understand] No LLM path available — `claude` CLI not found on PATH and ANTHROPIC_API_KEY not set. Running in heuristic mode.');
+    console.warn('[understand] Tip: install Claude Code or set ANTHROPIC_API_KEY to enable per-file summaries.');
   } else if (llmPath === 'claude-cli' && !noLlm) {
-    console.log('[understand] Using `claude -p` CLI passthrough (no API key needed; reusing Claude Code auth)');
+    console.log('[understand] LLM path: `claude -p` CLI passthrough (reusing Claude Code session, no key needed)');
+  } else if (llmPath === 'api' && !noLlm) {
+    console.log('[understand] LLM path: direct Anthropic API (ANTHROPIC_API_KEY set)');
   }
   const useLlm = !noLlm && llmPath !== 'none';