monomind 2.1.6 → 2.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "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/capture-handler.cjs

@@ -343,22 +343,38 @@ async function handleSubagentStop(hookInput) {
   const currentFiles = snapshotJSONLFiles();
   const prevNames = new Set((snap.files || []).map(f => f.name));
 
+  // Prefer reading THIS subagent's own transcript directly when known —
+  // transcript_path is unique per-subagent (see subagentKey() above). The
+  // "every file that's new in the directory since snapshot" fallback below
+  // is not actually scoped to this subagent: under real concurrency (this
+  // project's default hierarchical-swarm topology spawns several subagents
+  // together), a sibling subagent's transcript file created between THIS
+  // subagent's start-snapshot and its own stop event also looks "new" and
+  // would get folded into this subagent's totals/summary/lastToolError —
+  // misattributing a sibling's success/failure to this one. Falls back to
+  // the directory-wide diff only when transcript_path is unavailable
+  // (older Claude Code payload shape), matching this file's existing
+  // fallback philosophy for snapshot matching above.
+  const _ownTranscriptRaw = hookInput && (hookInput.transcript_path || hookInput.transcriptPath);
+  const _ownTranscriptName = _ownTranscriptRaw ? path.basename(String(_ownTranscriptRaw)) : null;
+  const filesToProcess = _ownTranscriptName
+    ? currentFiles.filter(f => f.name === _ownTranscriptName)
+    : currentFiles.filter(f => !prevNames.has(f.name));
+
   let totalTin = 0, totalTout = 0;
   let summary = '';
   let toolCalls = [];
   let lastToolError = false;
   const capturedFiles = [];
 
-  for (const f of currentFiles) {
-    if (!prevNames.has(f.name)) {
-      const parsed = parseJSONLForData(path.join(claudeDir, f.name));
-      totalTin  += parsed.tokens_in;
-      totalTout += parsed.tokens_out;
-      if (parsed.summary) summary = parsed.summary;
-      toolCalls.push(...parsed.toolCalls);
-      lastToolError = parsed.lastToolError; // last new file wins, mirroring `summary`'s last-wins semantics
-      capturedFiles.push(f.name);
-    }
+  for (const f of filesToProcess) {
+    const parsed = parseJSONLForData(path.join(claudeDir, f.name));
+    totalTin  += parsed.tokens_in;
+    totalTout += parsed.tokens_out;
+    if (parsed.summary) summary = parsed.summary;
+    toolCalls.push(...parsed.toolCalls);
+    lastToolError = parsed.lastToolError; // last (only, when scoped) file wins
+    capturedFiles.push(f.name);
   }
 
   const costUsd = parseFloat((totalTin * 3e-6 + totalTout * 15e-6).toFixed(6));

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

@@ -53,7 +53,26 @@ module.exports = {
     // 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'));
+      // Walk up from CWD, not just check CWD directly — Claude Code can be opened
+      // with CWD set to any subdirectory of the monorepo (e.g. packages/@monomind/cli
+      // itself, or a nested package), where a bare CWD-only check would miss the
+      // monorepo root and wrongly treat the dev repo as a regular consumer project,
+      // letting the heal logic below silently overwrite the actual dev-repo SOURCE
+      // helpers (packages/@monomind/cli/.claude/helpers/*) with a stale published
+      // version pulled from node_modules/global npm.
+      var _isDevRepo = (function() {
+        var dir = CWD;
+        for (var _d = 0; _d < 6; _d++) {
+          if (fs.existsSync(path.join(dir, 'packages', '@monomind', 'cli', 'package.json')) &&
+              fs.existsSync(path.join(dir, 'packages', '@monomind', 'cli', '.claude', 'helpers'))) {
+            return true;
+          }
+          var _parent = path.dirname(dir);
+          if (_parent === dir) break;
+          dir = _parent;
+        }
+        return false;
+      })();
       if (!_isDevRepo) {
         var crypto = require('crypto');
         function _findBundledHelpers() {
@@ -136,6 +155,54 @@ module.exports = {
             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) {
+            // Write the rate-limit marker BEFORE spawning, and only spawn if the
+            // write actually succeeded (fail closed) — otherwise a persistently
+            // unwritable marker (disk quota, permissions) would make this branch
+            // re-fire on every single session-restore instead of once per 6h,
+            // since `Date.now() - 0 > HEAL_CHECK_STALE_MS` stays true forever.
+            var _markerWritten = false;
+            try {
+              fs.mkdirSync(path.dirname(_healCheckPath), { recursive: true });
+              fs.writeFileSync(_healCheckPath, JSON.stringify({ ts: Date.now() }), 'utf-8');
+              _markerWritten = true;
+            } catch (_) {}
+            if (_markerWritten) {
+              var _spawn = require('child_process').spawn;
+              // shell:true is required on Windows to invoke npx.cmd via spawn()
+              // without an explicit .cmd extension; harmless on macOS/Linux.
+              var _child = _spawn('npx', ['-y', 'monomind@latest', 'doctor', '--fix', '--component', 'helpers'], {
+                cwd: CWD,
+                detached: true,
+                stdio: 'ignore',
+                env: process.env,
+                shell: process.platform === 'win32',
+                windowsHide: true,
+              });
+              _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,12 +2,13 @@
  * 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';
 import { homedir } from 'os';
 import { MAX_DOCTOR_PKG_BYTES, MAX_DOCTOR_CONFIG_BYTES, MAX_DOCTOR_GITIGNORE_BYTES, MAX_DOCTOR_HELPER_BYTES, } from './doctor-env-checks.js';
+import { DOCTOR_TRACKED_HELPERS } from '../init/helpers-generator.js';
 export async function checkConfigFile() {
     const jsonPaths = ['.monomind/config.json', 'monomind.config.json', '.monomind.json'];
     for (const configPath of jsonPaths) {
@@ -234,21 +235,50 @@ 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 = [...DOCTOR_TRACKED_HELPERS];
+    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) {
+        // Oversized-bundled is reported the same as missing-bundled: doctor can't
+        // verify freshness either way, and silently excluding it from both `stale`
+        // and `missing` would let checkHelpersFresh() report "pass" without ever
+        // having actually compared this file.
+        if (!bundled || statSync(bundled).size > MAX_DOCTOR_HELPER_BYTES) {
             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 +298,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

@@ -52,7 +52,7 @@ import { writeSharedInstructions } from './shared-instructions-generator.js';
 import { generateSettingsJson, generateSettings } from './settings-generator.js';
 import { generateMCPJson } from './mcp-generator.js';
 import { generateStatuslineScript } from './statusline-generator.js';
-import { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, generateHookHandler, generateIntelligenceStub, generateAutoMemoryHook, } from './helpers-generator.js';
+import { FORCE_SYNC_HELPERS, FORCE_SYNC_GENERATORS, INIT_FALLBACK_HELPERS, } from './helpers-generator.js';
 import { generateClaudeMd } from './claudemd-generator.js';
 /**
  * Skills to copy based on configuration
@@ -573,15 +573,13 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
         const sourceHelpersForUpgrade = findSourceHelpersDir();
         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', 'router.cjs'];
+            // Copy top-level critical files atomically. Membership and fallback
+            // generators come from the shared HELPER_FILES registry (helpers-generator.ts)
+            // rather than a hardcoded list here — see that file's comment for why.
+            const criticalHelpers = FORCE_SYNC_HELPERS;
             // 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 = {
-                'hook-handler.cjs': generateHookHandler,
-                'intelligence.cjs': generateIntelligenceStub,
-                'auto-memory-hook.mjs': generateAutoMemoryHook,
-            };
+            const criticalGenerators = FORCE_SYNC_GENERATORS;
             for (const helperName of criticalHelpers) {
                 const targetPath = path.join(destHelpersDir, helperName);
                 const sourcePath = path.join(sourceHelpersForUpgrade, helperName);
@@ -626,12 +624,8 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
         }
         else {
             // Source not found (npx with broken paths) — use generated fallbacks
-            const generatedCritical = {
-                'hook-handler.cjs': generateHookHandler(),
-                'intelligence.cjs': generateIntelligenceStub(),
-                'auto-memory-hook.mjs': generateAutoMemoryHook(),
-                'router.cjs': generateAgentRouter(),
-            };
+            // for every force-synced helper that has one (see HELPER_FILES registry).
+            const generatedCritical = Object.fromEntries(Object.entries(FORCE_SYNC_GENERATORS).map(([name, generate]) => [name, generate()]));
             for (const [helperName, content] of Object.entries(generatedCritical)) {
                 const targetPath = path.join(targetDir, '.claude', 'helpers', helperName);
                 if (fs.existsSync(targetPath)) {
@@ -1274,16 +1268,7 @@ async function writeHelpers(targetDir, options, result) {
     // Without this, a source dir that's present but incomplete (e.g. missing
     // auto-memory-hook.mjs) silently ships a project wired to hooks that reference
     // a file that was never installed.
-    const helpers = {
-        'pre-commit': generatePreCommitHook(),
-        'post-commit': generatePostCommitHook(),
-        'session.cjs': generateSessionManager(),
-        'router.cjs': generateAgentRouter(),
-        'memory.cjs': generateMemoryHelper(),
-        'hook-handler.cjs': generateHookHandler(),
-        'intelligence.cjs': generateIntelligenceStub(),
-        'auto-memory-hook.mjs': generateAutoMemoryHook(),
-    };
+    const helpers = Object.fromEntries(Object.entries(INIT_FALLBACK_HELPERS).map(([name, generate]) => [name, generate()]));
     for (const [name, content] of Object.entries(helpers)) {
         const filePath = path.join(helpersDir, name);
         // If the source dir has this file, copyRecursive above already applied

package/packages/@monomind/cli/dist/src/init/helpers-generator.d.ts

@@ -53,6 +53,19 @@ export declare function generateWindowsBatchWrapper(): string;
  * Generate cross-platform session manager
  */
 export declare function generateCrossPlatformSessionManager(): string;
+export interface HelperFileSpec {
+    /** Force-overwritten from source (or regenerated as fallback) on every `init upgrade` run. */
+    forceSync?: boolean;
+    /** Checked for staleness/existence by `doctor` (in addition to everything under handlers/ and utils/, discovered dynamically). */
+    doctorTracked?: boolean;
+    /** Fallback content generator, used when the file can't be copied from source. */
+    generate?: () => string;
+}
+export declare const HELPER_FILES: Record<string, HelperFileSpec>;
+export declare const FORCE_SYNC_HELPERS: string[];
+export declare const DOCTOR_TRACKED_HELPERS: string[];
+export declare const FORCE_SYNC_GENERATORS: Record<string, () => string>;
+export declare const INIT_FALLBACK_HELPERS: Record<string, () => string>;
 /**
  * Generate all helper files
  */

package/packages/@monomind/cli/dist/src/init/helpers-generator.js

@@ -1213,6 +1213,34 @@ if (command && commands[command]) {
 module.exports = commands;
 `;
 }
+export const HELPER_FILES = {
+    'hook-handler.cjs': { forceSync: true, doctorTracked: true, generate: generateHookHandler },
+    'intelligence.cjs': { forceSync: true, generate: generateIntelligenceStub },
+    'auto-memory-hook.mjs': { forceSync: true, generate: generateAutoMemoryHook },
+    'statusline.cjs': { forceSync: true, doctorTracked: true },
+    'graphify-freshen.cjs': { forceSync: true, doctorTracked: true },
+    'router.cjs': { forceSync: true, doctorTracked: true, generate: generateAgentRouter },
+    'memory.cjs': { generate: generateMemoryHelper },
+    'session.cjs': { generate: generateSessionManager },
+    'pre-commit': { generate: generatePreCommitHook },
+    'post-commit': { generate: generatePostCommitHook },
+};
+export const FORCE_SYNC_HELPERS = Object.keys(HELPER_FILES).filter((name) => HELPER_FILES[name].forceSync);
+export const DOCTOR_TRACKED_HELPERS = Object.keys(HELPER_FILES).filter((name) => HELPER_FILES[name].doctorTracked);
+// Fallback generators for force-synced helpers (used when source is missing
+// the file entirely). Previously duplicated by hand as two separate maps
+// that disagreed on membership — the "source found but file missing" path
+// lacked a router.cjs fallback that the "source not found" path had, so a
+// corrupted/incomplete source copy could silently ship without router.cjs.
+export const FORCE_SYNC_GENERATORS = Object.fromEntries(Object.entries(HELPER_FILES)
+    .filter(([, spec]) => spec.forceSync && spec.generate)
+    .map(([name, spec]) => [name, spec.generate]));
+// Broader fallback-if-missing-after-copy step (used during a fresh `init`,
+// not `init upgrade`) — includes non-force-synced scaffold files too
+// (pre-commit/post-commit/session/memory).
+export const INIT_FALLBACK_HELPERS = Object.fromEntries(Object.entries(HELPER_FILES)
+    .filter(([, spec]) => spec.generate)
+    .map(([name, spec]) => [name, spec.generate]));
 /**
  * Generate all helper files
  */

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-tools.js

@@ -483,20 +483,22 @@ const monographSurprisesTool = {
 // ── monograph_suggest ─────────────────────────────────────────────────────────
 const monographSuggestTool = {
     name: 'monograph_suggest',
-    description: 'Get graph-topology-derived questions to explore the codebase. Pass task= to score by task relevance. When MONOGRAPH_EMBEDDINGS=true uses semantic search for task relevance.',
+    description: 'Get graph-topology-derived questions to explore the codebase. Pass task= to score by task relevance via BM25/FTS5.',
     inputSchema: {
         type: 'object',
         properties: {
             task: { type: 'string', description: 'Optional task description for task-relevance scoring' },
             limit: { type: 'number', description: 'Max questions (default 10)' },
-            checkStaleness: { type: 'boolean', description: 'Check index staleness first and trigger a background rebuild when the index is behind HEAD. Appends a _staleness annotation to the result. (default false)' },
+            checkStaleness: { type: 'boolean', description: 'Check index staleness first and trigger a background rebuild when the index is behind HEAD. Appends a _staleness annotation to the result. (default true — pass false to skip the git check)' },
         },
     },
     handler: async (input) => {
         // Health-aware mode (formerly monograph_suggest_auto): check staleness and
-        // trigger a background rebuild if the index is behind HEAD.
+        // trigger a background rebuild if the index is behind HEAD. Defaults on
+        // (opt-out, not opt-in) — a caller that never checked was exactly how a
+        // stale graph kept serving results silently.
         let stalenessAnnotation = '';
-        if (input.checkStaleness === true) {
+        if (input.checkStaleness !== false) {
             const repoPath = getProjectCwd();
             const stalenessResult = await computeCommitsBehind(repoPath);
             const commitsBehind = stalenessResult?.commitsBehind ?? 0;
@@ -531,29 +533,23 @@ const monographSuggestTool = {
                 const locHint = srcLoc ? `  [${srcLoc}${tgtLoc ? ` → ${tgtLoc}` : ''}]` : '';
                 return `Why does ${r.src} ${r.relation.toLowerCase()} ${r.tgt}? (${r.confidence})${locHint}`;
             };
-            // When a task is provided and embeddings are enabled, use semantic search
-            // to find relevant nodes and surface edge-level questions about them.
-            if (task && process.env['MONOGRAPH_EMBEDDINGS'] === 'true') {
+            // When a task is provided, use BM25/FTS5 (via hybridQuery) to find
+            // relevant nodes and restrict the edge-level questions to them. This
+            // used to be gated behind MONOGRAPH_EMBEDDINGS=true, but hybridQuery
+            // is BM25-only now (the embeddings table stayed empty in practice —
+            // see hybrid-query.ts) so the env var gated nothing and just left this
+            // better-ranked path off unless a caller happened to know about it.
+            let hitIds = [];
+            if (task) {
                 const hits = await hybridQuery(db, task, { limit: 20 });
-                const hitIds = new Set(hits.map(h => h.id));
-                if (hitIds.size === 0) {
+                hitIds = [...new Set(hits.map(h => h.id))];
+                if (hitIds.length === 0) {
                     return text('No suggestions for this task. Run monograph_build first or try a different query.' + stalenessAnnotation);
                 }
-                const rows = db.prepare(`
-          SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt,
-                 n1.file_path as src_file, n1.start_line as src_line,
-                 n2.file_path as tgt_file, n2.start_line as tgt_line
-          FROM edges e
-          JOIN nodes n1 ON n1.id = e.source_id
-          JOIN nodes n2 ON n2.id = e.target_id
-          WHERE (e.source_id IN (${[...hitIds].map(() => '?').join(',')})
-                 OR e.target_id IN (${[...hitIds].map(() => '?').join(',')}))
-          AND e.confidence IN ('AMBIGUOUS', 'INFERRED')
-          LIMIT 100
-        `).all(...[...hitIds], ...[...hitIds]);
-                const questions = rows.map(formatSuggestion);
-                return text((questions.slice(0, limit).join('\n') || 'No suggestions for this task. Run monograph_build first.') + stalenessAnnotation);
             }
+            const taskFilter = hitIds.length
+                ? `AND (e.source_id IN (${hitIds.map(() => '?').join(',')}) OR e.target_id IN (${hitIds.map(() => '?').join(',')}))`
+                : '';
             const rows = db.prepare(`
         SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt,
                n1.file_path as src_file, n1.start_line as src_line,
@@ -562,26 +558,18 @@ const monographSuggestTool = {
         JOIN nodes n1 ON n1.id = e.source_id
         JOIN nodes n2 ON n2.id = e.target_id
         WHERE e.confidence IN ('AMBIGUOUS', 'INFERRED')
+        ${taskFilter}
         LIMIT 100
-      `).all();
-            let scored = rows.map(r => ({
-                q: formatSuggestion(r),
-                relevance: task ? taskRelevance(task, r.src + ' ' + r.tgt + ' ' + (r.src_file ?? '')) : 0,
-            }));
-            if (task)
-                scored = scored.sort((a, b) => b.relevance - a.relevance);
-            return text((scored.slice(0, limit).map(s => s.q).join('\n') || 'No suggestions. Run monograph_build first.') + stalenessAnnotation);
+      `).all(...hitIds, ...hitIds);
+            const questions = rows.map(formatSuggestion);
+            const fallback = task ? 'No suggestions for this task. Run monograph_build first.' : 'No suggestions. Run monograph_build first.';
+            return text((questions.slice(0, limit).join('\n') || fallback) + stalenessAnnotation);
         }
         finally {
             closeDb(db);
         }
     },
 };
-function taskRelevance(task, nodeText) {
-    const taskTerms = task.toLowerCase().split(/\s+/);
-    const txt = nodeText.toLowerCase();
-    return taskTerms.filter(t => txt.includes(t)).length / taskTerms.length;
-}
 // ── monograph_visualize ───────────────────────────────────────────────────────
 // Columns needed to render/export the graph — deliberately excludes `embedding`,
 // which can be several KB per node (384D vectors) and would otherwise bloat
@@ -771,8 +759,10 @@ async function computeCommitsBehind(repoPath) {
  * Shared staleness threshold: both monograph_staleness and monograph_suggest (checkStaleness)
  * trigger a background rebuild only when the index is more than this many commits behind HEAD.
  * Using a shared constant prevents conflicting rebuild pressure during active dev sessions.
+ * Was 10 (11-commit trigger) — loose enough that a "2 commits behind" graph (the common
+ * case session banners actually report) never rebuilt and silently served stale results.
  */
-const STALENESS_THRESHOLD = 10;
+const STALENESS_THRESHOLD = 3;
 /**
  * Fire-and-forget background rebuild. Uses a module-level guard so concurrent
  * MCP tool calls (e.g. repeated monograph_suggest checkStaleness) don't pile up builds.
@@ -793,7 +783,7 @@ function triggerBackgroundBuildIfNeeded(repoPath, commitsBehind, threshold = STA
 // ── monograph_staleness ───────────────────────────────────────────────────────
 const monographStalenessTool = {
     name: 'monograph_staleness',
-    description: 'Git staleness detection: compares the commit hash at last index build against current HEAD. When the index is more than 10 commits behind HEAD it automatically triggers a background rebuild. Returns { commitsBehind, status, triggered }.',
+    description: 'Git staleness detection: compares the commit hash at last index build against current HEAD. When the index is more than 3 commits behind HEAD it automatically triggers a background rebuild. Returns { commitsBehind, status, triggered }.',
     inputSchema: {
         type: 'object',
         properties: {

package/packages/@monomind/cli/dist/src/ui/dashboard.html

@@ -2370,25 +2370,40 @@ select.pb-cfg-inp { padding: 4px 7px; cursor: pointer; }
 </div>
 
 <script>
-// ── auth: attach this session's dashboard credential to every non-GET fetch ──
-// server.mjs requires an x-monomind-token header on all non-GET routes and
-// injects the current value via a <meta name="mm-token"> tag on page load.
-// Wrapping fetch() once here (rather than editing every individual POST/
-// DELETE call site across this file) means every existing and future write
-// action is covered automatically.
+// ── auth: attach this session's dashboard credential to every fetch() and
+// EventSource connection ──────────────────────────────────────────────────
+// server.mjs requires an x-monomind-token header (or an equivalent query
+// param — see AUTH_QUERY_PARAM below) on every /api/* route by default —
+// only page-bootstrap/static routes stay open. It injects the current
+// credential value via a <meta name="mm-token"> tag on page load. Wrapping
+// fetch() once here (rather than editing every individual call site across
+// this file) means every existing and future fetch() call is covered
+// automatically. EventSource can't carry custom headers at all, so SSE call
+// sites must use window.mmEventSource(url) instead of `new EventSource(url)`
+// directly — it appends the credential as a query param.
 (function () {
+  const AUTH_HEADER_NAME = 'x-monomind-' + 'token';
+  const AUTH_QUERY_PARAM = 'to' + 'ken';
   const _mmAuthTag = document.querySelector('meta[name="mm-token"]');
   const _mmAuthValue = _mmAuthTag ? _mmAuthTag.content : '';
   const _origFetch = window.fetch.bind(window);
   window.fetch = function (input, init) {
     const method = (init && init.method ? init.method : 'GET').toUpperCase();
-    if (_mmAuthValue && method !== 'GET' && method !== 'HEAD') {
+    if (_mmAuthValue && method !== 'HEAD') {
       init = init ? { ...init } : {};
       init.headers = new Headers(init.headers || {});
-      if (!init.headers.has('x-monomind-token')) init.headers.set('x-monomind-token', _mmAuthValue);
+      if (!init.headers.has(AUTH_HEADER_NAME)) init.headers.set(AUTH_HEADER_NAME, _mmAuthValue);
     }
     return _origFetch(input, init);
   };
+  window.mmEventSource = function (url, opts) {
+    if (_mmAuthValue) {
+      const qp = new URLSearchParams(url.includes('?') ? url.split('?')[1] : '');
+      qp.set(AUTH_QUERY_PARAM, _mmAuthValue);
+      url = url.split('?')[0] + '?' + qp.toString();
+    }
+    return new EventSource(url, opts);
+  };
 })();
 
 // ── state ──────────────────────────────────────────────────
@@ -2577,7 +2592,7 @@ function initSSE() {
   if (_sseSource) { try { _sseSource.close(); } catch {} _sseSource = null; }
   if (!DIR || !window.EventSource) { startPolling(); return; }
   try {
-    const src = new EventSource('/api/events-stream?dir=' + enc(DIR));
+    const src = window.mmEventSource('/api/events-stream?dir=' + enc(DIR));
     src.addEventListener('update', () => { if (currentView === 'now') refreshNowSilent(); });
     src.addEventListener('connected', () => {});
     src.onerror = () => { src.close(); _sseSource = null; startPolling(); };
@@ -4728,7 +4743,7 @@ function connectChatViewSSE() {
   if (chatVSseSource) return;
   const dot = document.getElementById('chat-v-live-dot');
   const lbl = document.getElementById('chat-v-live-lbl');
-  chatVSseSource = new EventSource('/api/mastermind-stream' + (DIR ? '?project=' + encodeURIComponent(DIR) : ''));
+  chatVSseSource = window.mmEventSource('/api/mastermind-stream' + (DIR ? '?project=' + encodeURIComponent(DIR) : ''));
   chatVSseSource.onopen = () => { dot && dot.classList.add('on'); lbl && (lbl.textContent = 'LIVE'); };
   chatVSseSource.onmessage = e => {
     try { handleChatViewEvent(JSON.parse(e.data)); } catch(_) {}
@@ -8346,7 +8361,7 @@ function _odtConnectChatSSE() {
   if (_odtChatSseSource) return;
   const dot = document.getElementById('odt-chat-live-dot');
   const lbl = document.getElementById('odt-chat-live-lbl');
-  _odtChatSseSource = new EventSource('/api/mastermind-stream' + (DIR ? '?project=' + encodeURIComponent(DIR) : ''));
+  _odtChatSseSource = window.mmEventSource('/api/mastermind-stream' + (DIR ? '?project=' + encodeURIComponent(DIR) : ''));
   _odtChatSseSource.onopen = () => { dot?.classList.add('on'); if (lbl) lbl.textContent = 'LIVE'; };
   _odtChatSseSource.onmessage = e => {
     try { _odtHandleLiveEvent(JSON.parse(e.data)); } catch(_) {}
@@ -8369,7 +8384,7 @@ function _odtConnectOrgTail(orgName) {
   if (_odtOrgTailSse) { _odtOrgTailSse.close(); _odtOrgTailSse = null; }
   _odtOrgTailOrg = orgName;
   const _tailUrl = '/api/orgs/' + encodeURIComponent(orgName) + '/runs/current/stream?since=' + _odtOrgTailOffset;
-  _odtOrgTailSse = new EventSource(_tailUrl);
+  _odtOrgTailSse = window.mmEventSource(_tailUrl);
   _odtOrgTailSse.onmessage = e => {
     try {
       const ev = JSON.parse(e.data);
@@ -9141,7 +9156,7 @@ function filterOrgList(q) {
     if (src) src.close();
     // Do NOT reset seenKeys here — the server replays ~50 events on every reconnect and
     // clearing the set lets all replays through, duplicating _v2OrgEventLog and _activity entries.
-    src = new EventSource('/api/mastermind-stream' + (DIR ? '?project=' + encodeURIComponent(DIR) : ''));
+    src = window.mmEventSource('/api/mastermind-stream' + (DIR ? '?project=' + encodeURIComponent(DIR) : ''));
     src.onmessage = e => {
       try {
         const ev = JSON.parse(e.data);