monomind 2.7.6 → 2.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.7.6",
+  "version": "2.7.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",
@@ -63,7 +63,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",
     "@monoes/monobrowse": "^1.0.6",
-    "@monoes/monodesign": "^1.2.0",
+    "@monoes/monodesign": "^1.2.1",
     "@monoes/monograph": "^1.5.4",
     "@noble/ed25519": "^2.1.0",
     "mammoth": "^1.12.0",
@@ -76,9 +76,9 @@
   "optionalDependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@monoes/hooks": "^1.0.0",
-    "@monoes/mcp": "^1.0.0",
+    "@monoes/mcp": "^1.0.1",
     "@monoes/memory": "^1.0.10",
-    "@monoes/routing": "^1.0.0",
+    "@monoes/routing": "^1.0.1",
     "monofence-ai": "*",
     "sql.js": "^1.14.1"
   },

package/packages/@monomind/cli/.claude/skills/monodesign/scripts/live-server.mjs

@@ -1112,7 +1112,8 @@ applyLegacyDeferredAcceptsOnStartup();
 restorePendingEventsFromStore();
 manualApply.pruneStaleEvidence();
 const portArg = args.find(a => a.startsWith('--port='));
-state.port = portArg ? parseInt(portArg.split('=')[1], 10) : await findOpenPort();
+const explicitPort = portArg ? parseInt(portArg.split('=')[1], 10) : null;
+state.port = explicitPort ?? await findOpenPort();
 // Annotation screenshots live in the project root so the agent's Read tool
 // doesn't trip a per-file permission prompt. Sessioned by token so concurrent
 // projects (or quick restarts) don't collide.
@@ -1123,7 +1124,43 @@ state.sessionDir = fs.mkdtempSync(path.join(annotRoot, 'session-'));
 const { detectScript, liveScriptParts } = loadBrowserScripts();
 httpServer = http.createServer(createRequestHandler({ detectScript, liveScriptParts }));
 
+// findOpenPort() probes a port, closes the probe socket, and only then does the
+// real server bind it. Another process scanning the same range can take the
+// port inside that gap, which surfaced as an intermittent
+// "EADDRINUSE 127.0.0.1:8405" — about one run in five of the test suite, where
+// several server-starting test files run in parallel.
+//
+// Retry on the next port when we picked it ourselves. An explicit --port is
+// never silently moved: the caller asked for that port, so a conflict there
+// must be an error they can see.
+const MAX_PORT_RETRIES = 25;
+let portRetries = 0;
+
+httpServer.on('error', (err) => {
+  if (err?.code !== 'EADDRINUSE') throw err;
+
+  if (explicitPort !== null) {
+    console.error(`\nPort ${state.port} is already in use.`);
+    console.error('Another live server may be running — stop it, or pass a different --port.');
+    process.exit(1);
+  }
+
+  if (portRetries >= MAX_PORT_RETRIES) {
+    console.error(`\nCould not find a free port after ${MAX_PORT_RETRIES} attempts (last tried ${state.port}).`);
+    process.exit(1);
+  }
+
+  portRetries++;
+  state.port++;
+  httpServer.listen(state.port, '127.0.0.1');
+});
+
 httpServer.listen(state.port, '127.0.0.1', () => {
+  // Trust the address the OS actually bound over the one we asked for — after
+  // a retry above, state.port and the bound port must not drift apart.
+  const boundAddr = httpServer.address();
+  if (boundAddr && typeof boundAddr === 'object') state.port = boundAddr.port;
+
   writeLiveServerInfo(process.cwd(), { pid: process.pid, port: state.port, token: state.token });
   const url = `http://localhost:${state.port}`;
   console.log(`\nMonodesign live server running on ${url}`);

package/packages/@monomind/cli/dist/src/commands/agent-ops.js

@@ -180,6 +180,36 @@ export const healthCommand = {
         { command: 'monomind agent health -i agent-001 -d', description: 'Detailed health for specific agent' },
     ],
     action: async (ctx) => {
+        // --watch was declared (and documented as "refresh every 5s") but never
+        // read, so the command rendered once and exited. Mirrors the watch loop in
+        // commands/status.ts.
+        if (ctx.flags.watch) {
+            return watchAgentHealth(ctx);
+        }
+        return renderAgentHealth(ctx);
+    },
+};
+const WATCH_INTERVAL_MS = 5000;
+async function watchAgentHealth(ctx) {
+    const refresh = async () => {
+        process.stdout.write('\x1b[2J\x1b[H');
+        output.writeln(output.dim(`Last updated: ${new Date().toLocaleTimeString()} — refreshing every 5s. Press Ctrl+C to exit.`));
+        await renderAgentHealth(ctx);
+    };
+    await refresh();
+    const intervalId = setInterval(() => { void refresh(); }, WATCH_INTERVAL_MS);
+    // `once` so repeated invocations don't accumulate SIGINT handlers.
+    return new Promise((resolve) => {
+        process.once('SIGINT', () => {
+            clearInterval(intervalId);
+            output.writeln();
+            output.printInfo('Watch mode stopped');
+            resolve({ success: true });
+        });
+    });
+}
+async function renderAgentHealth(ctx) {
+    {
         const agentId = ctx.args[0] || ctx.flags.id;
         const detailed = ctx.flags.detailed;
         try {
@@ -242,6 +272,6 @@ export const healthCommand = {
             output.printError(error instanceof MCPClientError ? `Health check error: ${error.message}` : `Unexpected error: ${String(error)}`);
             return { success: false, exitCode: 1 };
         }
-    },
-};
+    }
+}
 //# sourceMappingURL=agent-ops.js.map

package/packages/@monomind/cli/dist/src/commands/browse-workflow.js

@@ -53,6 +53,35 @@ const runSubcommand = {
         const wf = await readWorkflow(filePath).catch(e => { output.printError(e.message); return null; });
         if (!wf)
             return { success: false, exitCode: 1 };
+        // --items feeds the run's input set. Previously the flag was parsed and
+        // then dropped, so every run silently used the single empty default item.
+        let items;
+        const itemsFlag = ctx.flags.items;
+        if (itemsFlag) {
+            const itemsPath = isAbsolute(itemsFlag) ? itemsFlag : resolve(ctx.cwd, itemsFlag);
+            let parsed;
+            try {
+                const { readFile } = await import('fs/promises');
+                parsed = JSON.parse(await readFile(itemsPath, 'utf8'));
+            }
+            catch (e) {
+                output.printError(`Cannot read items file ${itemsPath}: ${e.message}`);
+                return { success: false, exitCode: 1 };
+            }
+            if (!Array.isArray(parsed)) {
+                output.printError(`Items file ${itemsPath} must contain a JSON array`);
+                return { success: false, exitCode: 1 };
+            }
+            // Accept both the engine's `{ data: {...} }` envelope and a bare array
+            // of objects, which is the shape people naturally write by hand.
+            items = parsed.map((entry) => {
+                const rec = entry;
+                return rec && typeof rec === 'object' && 'data' in rec && typeof rec.data === 'object' && rec.data !== null
+                    ? { data: rec.data }
+                    : { data: (rec ?? {}) };
+            });
+            output.printInfo(`Loaded ${items.length} input item(s) from ${itemsFlag}`);
+        }
         const port = ctx.flags.port ?? 4243;
         const dashboard = getDashboardServer(port);
         if (!ctx.flags['no-dashboard']) {
@@ -65,6 +94,7 @@ const runSubcommand = {
         spinner.start();
         const record = await runWorkflow(wf, {
             onEvent: (ev) => dashboard.broadcast(ev),
+            ...(items ? { items } : {}),
         });
         if (record.status === 'completed') {
             spinner.succeed(`Done — ${record.itemsProcessed} items in ${((record.completedAt - record.startedAt) / 1000).toFixed(1)}s`);

package/packages/@monomind/cli/dist/src/commands/hooks-extended-commands.js

@@ -200,7 +200,7 @@ export const notifyCommand = {
     options: [
         { name: 'message', short: 'm', type: 'string', description: 'Notification message', required: true },
         { name: 'level', short: 'l', type: 'string', description: 'Level: info, warn, error', default: 'info' },
-        { name: 'channel', short: 'c', type: 'string', description: 'Notification channel', default: 'console' },
+        { name: 'channel', short: 'c', type: 'string', description: 'Notification channel (only "console" is implemented)', default: 'console' },
     ],
     examples: [
         { command: 'monomind hooks notify -m "Build complete"', description: 'Send info notification' },
@@ -213,6 +213,14 @@ export const notifyCommand = {
             output.printError('Message is required: --message "your message"');
             return { success: false, exitCode: 1 };
         }
+        // Console is the only delivery mechanism that exists. Accepting
+        // `--channel slack` and then printing to the console anyway would tell the
+        // user their message went somewhere it did not.
+        const channel = ctx.flags.channel || 'console';
+        if (channel !== 'console') {
+            output.writeln(output.warning(`Channel "${channel}" is not implemented — delivering to console. ` +
+                `Only "console" is supported today.`));
+        }
         const timestamp = new Date().toISOString();
         if (level === 'error') {
             output.printError(`[${timestamp}] ${message}`);
@@ -229,7 +237,7 @@ export const notifyCommand = {
             await storeEntry({ key: `notify-${Date.now()}`, value: `[${level}] ${message}`, namespace: 'notifications' });
         }
         catch { /* memory not available */ }
-        return { success: true, data: { timestamp, level, message } };
+        return { success: true, data: { timestamp, level, message, channel: 'console' } };
     }
 };
 //# sourceMappingURL=hooks-extended-commands.js.map

package/packages/@monomind/cli/dist/src/commands/memory-crud.js

@@ -297,7 +297,10 @@ export const searchCommand = {
                 output.writeln();
             }
         }
-        output.printInfo(`Searching: "${query}" (${searchType})`);
+        // Requested type only — the method that ACTUALLY ran is printed after the
+        // search, from searchResult.searchMethod. Labelling this line "(semantic)"
+        // used to claim a vector search that may never have happened.
+        output.printInfo(`Searching: "${query}" (requested: ${searchType})`);
         output.writeln();
         // Use direct sql.js search with vector similarity
         try {
@@ -318,11 +321,39 @@ export const searchCommand = {
                 namespace: r.namespace,
                 preview: r.content
             }));
+            const actualMethod = searchResult.searchMethod ?? 'unknown';
+            const fallbackReason = searchResult.fallbackReason;
             if (ctx.flags.format === 'json') {
-                output.printJson({ query, searchType, results, searchTime: `${searchResult.searchTime}ms` });
+                output.printJson({
+                    query,
+                    searchType,
+                    searchMethod: actualMethod,
+                    ...(fallbackReason ? { fallbackReason } : {}),
+                    results,
+                    searchTime: `${searchResult.searchTime}ms`,
+                });
                 return { success: true, data: results };
             }
-            // Performance stats
+            // Performance stats — method first, so a keyword fallback is never hidden
+            // behind a "(semantic)" header.
+            const REASON_TEXT = {
+                'no-embedding-model': 'embedding model unavailable',
+                'embedding-failed': 'embedding generation failed',
+                'no-semantic-matches': 'vector search returned no matches',
+            };
+            if (actualMethod === 'semantic') {
+                output.writeln(output.dim('  Method: semantic (vector similarity)'));
+            }
+            else if (actualMethod === 'hybrid') {
+                output.writeln(output.dim('  Method: hybrid (per-entry cosine, keyword overlap where no vector exists)'));
+            }
+            else if (actualMethod === 'unknown') {
+                output.writeln(output.dim('  Method: unknown'));
+            }
+            else {
+                const why = fallbackReason ? REASON_TEXT[fallbackReason] ?? fallbackReason : undefined;
+                output.printWarning(`Method: ${actualMethod}${why ? ` — ${why}` : ''}. Scores are token-overlap fractions, not vector similarity.`);
+            }
             output.writeln(output.dim(`  Search time: ${searchResult.searchTime}ms`));
             output.writeln();
             if (results.length === 0) {

package/packages/@monomind/cli/dist/src/commands/org-observe.js

@@ -178,17 +178,44 @@ export const reportAction = async (ctx, name) => {
     }
     return { success: true };
 };
+/** Read questions.json. A MISSING file legitimately means "no questions" → [].
+ *  Any other failure (unreadable, malformed — e.g. a partial daemon write) THROWS:
+ *  answerAction rewrites this file from what this returns, so silently coercing a
+ *  failed read to [] would atomically replace every recorded question with one. */
 const readQuestions = (cwd, name) => {
+    const path = join(cwd, ORG_DIR, name, 'questions.json');
+    let raw;
     try {
-        return JSON.parse(readFileSync(join(cwd, ORG_DIR, name, 'questions.json'), 'utf8')).questions ?? [];
+        raw = readFileSync(path, 'utf8');
     }
-    catch {
-        return [];
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw new Error(`cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
     }
+    if (parsed?.questions === undefined || parsed.questions === null)
+        return [];
+    if (!Array.isArray(parsed.questions))
+        throw new Error(`${path}: "questions" is not an array`);
+    return parsed.questions;
 };
 /** `org questions <name> [--all]` — list pending (or all) ask_human questions. */
 export const questionsAction = async (ctx, name) => {
-    const all = readQuestions(ctx.cwd, name);
+    let all;
+    try {
+        all = readQuestions(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Cannot read questions for org ${name}: ${err instanceof Error ? err.message : String(err)}`));
+        return { success: false, message: 'questions.json unreadable' };
+    }
     const shown = ctx.flags['all'] === true ? all : all.filter(q => q.answer === null);
     if (!shown.length) {
         log(output.info(all.length ? `No pending questions for org ${name} (${all.length} answered — use --all).` : `No questions recorded for org ${name}.`));
@@ -212,7 +239,14 @@ export const answerAction = async (ctx, name) => {
     const answer = ctx.args.slice(2).join(' ').trim();
     if (!questionId || !answer)
         return { success: false, message: `usage: monomind org answer ${name} <question-id> "answer text"` };
-    const questions = readQuestions(ctx.cwd, name);
+    let questions;
+    try {
+        questions = readQuestions(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Cannot read questions for org ${name}: ${err instanceof Error ? err.message : String(err)}`));
+        return { success: false, message: 'questions.json unreadable — answer not recorded' };
+    }
     const q = questions.find(x => x.questionId === questionId);
     if (!q) {
         log(output.error(`Question "${questionId}" not found for org ${name} — list with: monomind org questions ${name}`));
@@ -246,7 +280,17 @@ export const answerAction = async (ctx, name) => {
     // snapshot can be up to 10s stale (live-delivery timeout), and rewriting
     // from it would delete questions the daemon appended meanwhile and revert
     // answers it recorded (atomic rename prevents torn writes, not lost updates).
-    const fresh = readQuestions(ctx.cwd, name);
+    // A FAILED re-read must abort the write: rewriting from [] would atomically
+    // rename a single-question file over every other recorded question.
+    let fresh;
+    try {
+        fresh = readQuestions(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Refusing to rewrite questions.json — ${err instanceof Error ? err.message : String(err)}`));
+        log(output.warning(`The answer was NOT recorded. Fix or restore ${join(ctx.cwd, ORG_DIR, name, 'questions.json')}, then retry.`));
+        return { success: false, message: 'questions.json unreadable — answer not recorded' };
+    }
     const freshQ = fresh.find(x => x.questionId === questionId);
     if (freshQ && freshQ.answer !== null) {
         return { success: false, message: `question "${questionId}" was answered while this command was running` };

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

@@ -521,12 +521,24 @@ const bottleneckCommand = {
     ],
     examples: [
         { command: 'monomind performance bottleneck', description: 'Find bottlenecks' },
-        { command: 'monomind performance bottleneck -d full', description: 'Full analysis' },
+        { command: 'monomind performance bottleneck -c network', description: 'Only the Network component' },
     ],
     action: async (ctx) => {
         output.writeln();
         output.writeln(output.bold('Bottleneck Analysis'));
         output.writeln(output.dim('─'.repeat(50)));
+        // Components this command actually knows how to inspect. Used both to
+        // validate --component and to tell the user what they could have asked for.
+        const ANALYZED_COMPONENTS = ['Runtime', 'Vector Search', 'Traces', 'Memory DB', 'Network'];
+        // Only a single depth of analysis is implemented. Accepting `--depth full`
+        // and quietly running the quick analysis discards the user's request with
+        // no indication it was ignored, so say so instead.
+        const depthRaw = ctx.flags.depth || 'quick';
+        if (depthRaw !== 'quick') {
+            output.writeln(output.warning(`--depth ${depthRaw} is not implemented — running the "quick" analysis. ` +
+                `Only "quick" is supported today.`));
+        }
+        const componentFilter = ctx.flags.component?.trim();
         const spinner = output.createSpinner({ text: 'Analyzing system...', spinner: 'dots' });
         spinner.start();
         const fs = await import('node:fs');
@@ -575,10 +587,24 @@ const bottleneckCommand = {
         if (!network.batching) {
             findings.push({ component: 'Network', bottleneck: 'No request batching', severity: output.info('Low'), solution: 'Run: monomind performance optimize --apply -t latency' });
         }
-        if (findings.length === 0) {
-            findings.push({ component: 'System', bottleneck: 'No bottlenecks detected', severity: output.success('None'), solution: 'System is performing well' });
+        let results = findings;
+        if (componentFilter) {
+            const known = ANALYZED_COMPONENTS.find(c => c.toLowerCase() === componentFilter.toLowerCase())
+                ?? ANALYZED_COMPONENTS.find(c => c.toLowerCase().includes(componentFilter.toLowerCase()));
+            if (!known) {
+                spinner.fail(`Unknown component "${componentFilter}"`);
+                output.writeln(output.warning(`Analyzed components: ${ANALYZED_COMPONENTS.join(', ')}.`));
+                return { success: false, message: `Unknown component: ${componentFilter}`, exitCode: 1 };
+            }
+            results = findings.filter(f => f.component === known);
+            if (results.length === 0) {
+                results = [{ component: known, bottleneck: 'No bottlenecks detected', severity: output.success('None'), solution: `${known} is performing well` }];
+            }
+        }
+        else if (results.length === 0) {
+            results = [{ component: 'System', bottleneck: 'No bottlenecks detected', severity: output.success('None'), solution: 'System is performing well' }];
         }
-        spinner.succeed(`Analysis complete — ${findings.length} finding(s)`);
+        spinner.succeed(`Analysis complete — ${results.length} finding(s)`);
         output.writeln();
         output.printTable({
             columns: [
@@ -587,7 +613,7 @@ const bottleneckCommand = {
                 { key: 'severity', header: 'Severity', width: 12 },
                 { key: 'solution', header: 'Solution', width: 50 },
             ],
-            data: findings,
+            data: results,
         });
         return { success: true };
     },

package/packages/@monomind/cli/dist/src/commands/security-misc.js

@@ -11,10 +11,11 @@ export const auditCommand = {
     options: [
         { name: 'action', short: 'a', type: 'string', description: 'Action: list (only supported value — log/export/clear are not implemented)', default: 'list' },
         { name: 'limit', short: 'l', type: 'number', description: 'Number of entries to show', default: '20' },
-        { name: 'filter', short: 'f', type: 'string', description: 'Filter by event type' },
+        { name: 'filter', short: 'f', type: 'string', description: 'Filter by event type (substring, case-insensitive)' },
     ],
     examples: [
         { command: 'monomind security audit --action list', description: 'List audit logs' },
+        { command: 'monomind security audit --filter SWARM', description: 'Only swarm activity events' },
     ],
     action: async (ctx) => {
         const requestedAction = ctx.flags.action || 'list';
@@ -54,7 +55,21 @@ export const auditCommand = {
         const now = new Date().toISOString().replace('T', ' ').substring(0, 19);
         auditEntries.push({ timestamp: now, event: 'AUDIT_RUN', user: 'cli', status: output.success('Success') });
         auditEntries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
-        if (auditEntries.length === 0) {
+        // --filter was previously parsed and discarded, so every invocation
+        // returned the full log regardless of what the user asked for.
+        const eventFilter = ctx.flags.filter?.trim();
+        let visibleEntries = auditEntries;
+        if (eventFilter) {
+            const needle = eventFilter.toLowerCase();
+            visibleEntries = auditEntries.filter(e => e.event.toLowerCase().includes(needle));
+            if (visibleEntries.length === 0) {
+                const seen = [...new Set(auditEntries.map(e => e.event))].sort();
+                output.writeln(output.warning(`No audit events match "${eventFilter}".`));
+                output.writeln(output.dim(`Event types present: ${seen.join(', ') || 'none'}`));
+                return { success: true, data: { entries: [], filter: eventFilter } };
+            }
+        }
+        if (visibleEntries.length === 0) {
             output.writeln(output.dim('No audit events found. Initialize a project first: monomind init'));
         }
         else {
@@ -65,7 +80,7 @@ export const auditCommand = {
                     { key: 'user', header: 'User', width: 15 },
                     { key: 'status', header: 'Status', width: 12 },
                 ],
-                data: auditEntries.slice(0, parseInt(ctx.flags.limit || '20', 10)),
+                data: visibleEntries.slice(0, parseInt(ctx.flags.limit || '20', 10)),
             });
         }
         return { success: true };

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

@@ -110,6 +110,83 @@ export class MCPClientError extends Error {
         this.name = 'MCPClientError';
     }
 }
+/**
+ * Runtime JSON-Schema type name for a JS value, or undefined for values we do
+ * not model (functions, symbols, bigint). `null` is reported as 'null' so a
+ * declared `type: 'object'` does not silently accept it.
+ *
+ * Note the two JS/JSON mismatches this has to paper over: arrays are objects
+ * in JS but a distinct type in JSON Schema, and JSON has no integer type —
+ * `integer` is a *number* with a constraint, so `3` satisfies both `number`
+ * and `integer` while `3.5` satisfies only `number`.
+ */
+function jsonTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    switch (typeof value) {
+        case 'string': return 'string';
+        case 'boolean': return 'boolean';
+        case 'number': return Number.isInteger(value) ? 'integer' : 'number';
+        case 'object': return 'object';
+        default: return undefined;
+    }
+}
+function matchesDeclaredType(declared, actual) {
+    if (declared === actual)
+        return true;
+    // Every integer is a valid number; the reverse is not true.
+    if (declared === 'number' && actual === 'integer')
+        return true;
+    return false;
+}
+/**
+ * Check present arguments against the `type` each property declares in the
+ * tool's inputSchema and WARN on a mismatch — deliberately non-fatal for now.
+ *
+ * `required` is already hard-enforced above; `type` is not, because nothing
+ * ever checked it, so a tool declaring `{type: 'string'}` has always been free
+ * to receive a number and reach its handler. Turning that into a throw without
+ * knowing how many real callers violate their own schemas would break working
+ * code, so this logs first: run the suite, count the warnings, then decide.
+ *
+ * Absent properties are ignored — that is `required`'s job, not this one's.
+ * Explicit null is also ignored here for the same reason (the required check
+ * already rejects it for required params, and an optional param set to null is
+ * an "unset" idiom, not a type error).
+ */
+function warnOnTypeMismatch(toolName, schema, input) {
+    const properties = schema?.properties;
+    if (!properties || typeof properties !== 'object')
+        return;
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined || value === null)
+            continue;
+        const prop = properties[key];
+        if (!prop || typeof prop !== 'object')
+            continue;
+        const declared = prop.type;
+        // Union types (`type: ['string','number']`) pass if any branch matches.
+        const declaredList = typeof declared === 'string'
+            ? [declared]
+            : Array.isArray(declared) && declared.every(t => typeof t === 'string')
+                ? declared
+                : undefined;
+        if (!declaredList || declaredList.length === 0)
+            continue;
+        const actual = jsonTypeOf(value);
+        if (!actual)
+            continue;
+        if (declaredList.some(d => matchesDeclaredType(d, actual)))
+            continue;
+        // Report `integer` as `number` — the distinction is an artefact of how we
+        // classify JS numbers, not something the caller passed.
+        const reported = actual === 'integer' ? 'number' : actual;
+        console.error(`[mcp] tool '${toolName}' param '${key}': schema declares ` +
+            `${declaredList.join('|')}, got ${reported}`);
+    }
+}
 /**
  * Call an MCP tool by name with input parameters
  */
@@ -142,6 +219,7 @@ export async function callMCPTool(toolName, input = {}, context) {
             throw new MCPClientError(`MCP tool '${toolName}' missing required parameter${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`, toolName);
         }
     }
+    warnOnTypeMismatch(toolName, tool.inputSchema, input);
     try {
         const result = await tool.handler(input, context);
         return result;

package/packages/@monomind/cli/dist/src/memory/memory-bridge.d.ts

@@ -63,7 +63,11 @@ export declare function bridgeSearchEntries(options: {
         tags?: string[];
     }[];
     searchTime: number;
-    searchMethod?: string;
+    /** What actually ran, never what was requested. 'keyword-fallback' means the
+     *  vector path was attempted and did not produce the results. */
+    searchMethod?: 'semantic' | 'keyword' | 'keyword-fallback';
+    /** Why the vector path did not serve these results (absent when it did). */
+    fallbackReason?: 'no-embedding-model' | 'embedding-failed' | 'no-semantic-matches';
     error?: string;
 } | null>;
 export declare function bridgeListEntries(options: {

package/packages/@monomind/cli/dist/src/memory/memory-bridge.js

@@ -406,7 +406,11 @@ export async function bridgeSearchEntries(options) {
         const startTime = Date.now();
         let results = [];
         let searchMethod = 'keyword';
+        // Reported to callers so "(semantic)" can never be printed over keyword hits.
+        let fallbackReason = _embedder && queryStr.length > 0 ? undefined : 'no-embedding-model';
+        let semanticAttempted = false;
         if (_embedder && queryStr.length > 0) {
+            semanticAttempted = true;
             try {
                 const queryEmbedding = await _embedder(queryStr);
                 const searchResults = await backend.search(queryEmbedding, {
@@ -431,8 +435,14 @@ export async function bridgeSearchEntries(options) {
                     };
                 }).sort((a, b) => b.score - a.score);
                 searchMethod = 'semantic';
+                fallbackReason = undefined;
+            }
+            catch (e) {
+                // fall through to keyword search — but never claim this was semantic
+                fallbackReason = 'embedding-failed';
+                if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
+                    console.error('[memory-bridge] semantic search failed — falling back to keyword matching:', e);
             }
-            catch { /* fall through to keyword search */ }
         }
         // Keyword fallback — scan all entries in namespace (not just first 100)
         // to avoid missing documents that were ingested later in the batch.
@@ -463,14 +473,22 @@ export async function bridgeSearchEntries(options) {
                     id: e.id,
                     key: e.key,
                     content: e.content || '',
-                    score: Math.min(0.9, 0.3 + score * 0.6),
+                    // Raw token-overlap fraction, NOT rescaled to look like a cosine.
+                    // The old `min(0.9, 0.3 + score*0.6)` floor/ceiling made a weak
+                    // keyword hit outrank a genuine cosine match (0.90 vs 0.63 for the
+                    // same entry) and fed cosine-calibrated gates (memory-kg dedup)
+                    // scores that never came from a vector.
+                    score,
                     namespace: e.namespace,
                     provenance: `keyword:${score.toFixed(2)}`,
                     tags: e.tags ?? [],
                     _createdAt: e.createdAt || 0,
                 }));
             }
-            searchMethod = 'keyword';
+            // The vector path ran and simply matched nothing — still not semantic.
+            searchMethod = semanticAttempted ? 'keyword-fallback' : 'keyword';
+            if (semanticAttempted && !fallbackReason)
+                fallbackReason = 'no-semantic-matches';
         }
         // Filter stale entries based on automem config — skip for knowledge
         // namespaces (documents should remain searchable indefinitely)
@@ -494,6 +512,7 @@ export async function bridgeSearchEntries(options) {
             results,
             searchTime: Date.now() - startTime,
             searchMethod,
+            ...(searchMethod === 'semantic' ? {} : { fallbackReason }),
         };
     }
     catch {

package/packages/@monomind/cli/dist/src/memory/memory-read.d.ts

@@ -25,6 +25,10 @@ export declare function searchEntries(options: {
         namespace: string;
     }[];
     searchTime: number;
+    /** What actually ran — propagated from the bridge so callers can report the
+     *  real method instead of echoing the requested one. */
+    searchMethod?: 'semantic' | 'keyword' | 'keyword-fallback' | 'hybrid';
+    fallbackReason?: string;
     error?: string;
 }>;
 /**

package/packages/@monomind/cli/dist/src/memory/memory-read.js

@@ -66,7 +66,8 @@ export async function searchEntries(options) {
             return {
                 success: true,
                 results: filtered,
-                searchTime: Date.now() - startTime
+                searchTime: Date.now() - startTime,
+                searchMethod: 'semantic'
             };
         }
         // Fall back to brute-force SQLite search
@@ -127,7 +128,9 @@ export async function searchEntries(options) {
         return {
             success: true,
             results: results.slice(0, limit),
-            searchTime: Date.now() - startTime
+            searchTime: Date.now() - startTime,
+            // Per-row: cosine when the entry had a vector, keyword overlap otherwise.
+            searchMethod: 'hybrid'
         };
     }
     catch (error) {

package/packages/@monomind/cli/dist/src/routing/route-layer-factory.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Pick the argv prefix used to spawn the embedding worker.
+ *
+ * dist/: `embed-worker.js` exists → `node embed-worker.js <task>`, byte-identical
+ * to the original behaviour, no extra flags, no extra resolution.
+ *
+ * src/ (tsx / vitest): only `embed-worker.ts` exists. Node's
+ * `--experimental-strip-types` cannot run it — the worker imports
+ * `./embedder.js`, and type-stripping does no `.js`→`.ts` extension rewriting,
+ * so it dies with ERR_MODULE_NOT_FOUND. tsx does rewrite, so the source path
+ * runs through tsx's CLI (a devDependency, never needed by dist/).
+ *
+ * Exported for tests.
+ */
+export declare function resolveWorkerArgv(): string[];
 type RouteResult = any;
 export interface ConfiguredRouteLayer {
     route: (taskDescription: string) => Promise<RouteResult>;

package/packages/@monomind/cli/dist/src/routing/route-layer-factory.js

@@ -18,9 +18,44 @@
 // loading onnxruntime in-process deterministically SIGSEGVs. The model lives
 // ONLY in embed-worker.ts, reached via the spawn below.
 import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'embed-worker.js');
+const WORKER_DIR = dirname(fileURLToPath(import.meta.url));
+/** Compiled worker — the only path production (dist/) ever takes. */
+const COMPILED_WORKER_PATH = join(WORKER_DIR, 'embed-worker.js');
+/** TypeScript sibling — only present when running from src/ (tsx, vitest). */
+const SOURCE_WORKER_PATH = join(WORKER_DIR, 'embed-worker.ts');
+/**
+ * Pick the argv prefix used to spawn the embedding worker.
+ *
+ * dist/: `embed-worker.js` exists → `node embed-worker.js <task>`, byte-identical
+ * to the original behaviour, no extra flags, no extra resolution.
+ *
+ * src/ (tsx / vitest): only `embed-worker.ts` exists. Node's
+ * `--experimental-strip-types` cannot run it — the worker imports
+ * `./embedder.js`, and type-stripping does no `.js`→`.ts` extension rewriting,
+ * so it dies with ERR_MODULE_NOT_FOUND. tsx does rewrite, so the source path
+ * runs through tsx's CLI (a devDependency, never needed by dist/).
+ *
+ * Exported for tests.
+ */
+export function resolveWorkerArgv() {
+    if (existsSync(COMPILED_WORKER_PATH))
+        return [COMPILED_WORKER_PATH];
+    if (existsSync(SOURCE_WORKER_PATH)) {
+        let tsxCli;
+        try {
+            tsxCli = createRequire(import.meta.url).resolve('tsx/cli');
+        }
+        catch {
+            throw new Error('embed worker: running from source but tsx is not installed (cannot execute embed-worker.ts)');
+        }
+        return [tsxCli, SOURCE_WORKER_PATH];
+    }
+    throw new Error(`embed worker not found at ${COMPILED_WORKER_PATH}`);
+}
 /** Generous: the first-ever run computes + caches ~500 utterance embeddings. */
 const WORKER_TIMEOUT_MS = 90_000;
 /** Cap worker stdout so a runaway child can't grow parent memory unbounded. */
@@ -37,8 +72,15 @@ const RESULT_MARKER = '__ROUTE_RESULT__';
 function runWorker(task) {
     // Cap task length before passing as argv to prevent OOM/DoS via oversized args.
     const safeTask = task.length > MAX_TASK_LENGTH ? task.slice(0, MAX_TASK_LENGTH) : task;
+    let workerArgv;
+    try {
+        workerArgv = resolveWorkerArgv();
+    }
+    catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+    }
     return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, [WORKER_PATH, safeTask], {
+        const child = spawn(process.execPath, [...workerArgv, safeTask], {
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
         });

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

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "2.7.6",
+  "version": "2.7.7",
   "type": "module",
   "description": "CLI engine for Monomind \u2014 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",
@@ -92,13 +92,14 @@
     "publish:all": "./scripts/publish.sh"
   },
   "devDependencies": {
+    "tsx": "^4.21.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.4"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",
     "@monoes/monobrowse": "^1.0.6",
-    "@monoes/monodesign": "^1.2.0",
+    "@monoes/monodesign": "^1.2.1",
     "@monoes/monograph": "^1.5.4",
     "@noble/ed25519": "^2.1.0",
     "mammoth": "^1.12.0",
@@ -110,9 +111,9 @@
   "optionalDependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@monoes/hooks": "^1.0.0",
-    "@monoes/mcp": "^1.0.0",
+    "@monoes/mcp": "^1.0.1",
     "@monoes/memory": "^1.0.10",
-    "@monoes/routing": "^1.0.0",
+    "@monoes/routing": "^1.0.1",
     "monofence-ai": "*",
     "sql.js": "^1.14.1"
   },