monomind 2.0.3 → 2.1.3

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

@@ -11,6 +11,22 @@ import { dirname } from 'path';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const MAX_EXEC_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
+/**
+ * Probe whether an optionalDependency actually resolved in this install
+ * (npm silently skips optionalDependencies it can't satisfy — see
+ * docs/AUDIT-BACKLOG.md P1-1/P1-23). Used to caveat generated docs instead
+ * of presenting these features as unconditionally working.
+ */
+function _isOptionalPackageResolvable(pkg) {
+    try {
+        const req = createRequire(import.meta.url);
+        req.resolve(pkg);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Atomic write helper — writes to a sibling .tmp file then renames into place.
  * SIGINT or crash during a partial write would otherwise corrupt user-critical
@@ -559,6 +575,13 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
             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'];
+            // 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,
+            };
             for (const helperName of criticalHelpers) {
                 const targetPath = path.join(destHelpersDir, helperName);
                 const sourcePath = path.join(sourceHelpersForUpgrade, helperName);
@@ -578,6 +601,17 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                     catch { }
                     fs.renameSync(tmp, targetPath);
                 }
+                else if (!fs.existsSync(targetPath) && criticalGenerators[helperName]) {
+                    const content = criticalGenerators[helperName]();
+                    const tmp = `${targetPath}.${process.pid}.tmp`;
+                    fs.writeFileSync(tmp, content, 'utf-8');
+                    try {
+                        fs.chmodSync(tmp, 0o755);
+                    }
+                    catch { }
+                    fs.renameSync(tmp, targetPath);
+                    result.created.push(`.claude/helpers/${helperName}`);
+                }
             }
             // Always recursively sync subdirectories (utils/, handlers/) — required by hook-handler.cjs.
             // Uses recursive copy so any future nested subdirs are also covered.
@@ -1180,13 +1214,15 @@ function findSourceHelpersDir(sourceBaseDir) {
         possiblePaths.push(helpersPath);
         currentDir = parentDir;
     }
-    // Strategy 4: Check cwd-relative paths (for local dev)
-    const cwdBased = [
-        path.join(process.cwd(), '.claude', 'helpers'),
-        path.join(process.cwd(), '..', '.claude', 'helpers'),
-        path.join(process.cwd(), '..', '..', '.claude', 'helpers'),
-    ];
-    possiblePaths.push(...cwdBased);
+    // NOTE: deliberately no cwd-ancestor-search fallback here (removed — see
+    // docs/AUDIT-BACKLOG.md P3-25). Searching process.cwd() and its parents for
+    // ".claude/helpers" could pick up an unrelated project's own helper scripts
+    // (stale, customized, or untrusted) when `monomind init` is run from a
+    // nested subdirectory of some other checkout. Helper source resolution is
+    // restricted to the package's own bundled location(s) above; if none of
+    // those are found, callers should treat it as a corrupt install rather than
+    // silently falling back to scanning ancestor directories for someone else's
+    // files.
     // Return first path that exists AND contains ALL sentinel files
     for (const p of possiblePaths) {
         if (fs.existsSync(p) && SENTINEL_FILES.every(f => fs.existsSync(path.join(p, f)))) {
@@ -1204,10 +1240,12 @@ async function writeHelpers(targetDir, options, result) {
     const sourceHelpersDir = findSourceHelpersDir(options.sourceBaseDir);
     // Try to copy existing helpers from source first (recursive — includes utils/ and handlers/)
     if (sourceHelpersDir && fs.existsSync(sourceHelpersDir)) {
-        let copiedCount = 0;
         const copyRecursive = (srcDir, destDir, relBase) => {
             fs.mkdirSync(destDir, { recursive: true });
             for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+                // Skip exFAT/macOS AppleDouble junk files (e.g. "._foo.cjs").
+                if (entry.name.startsWith('._'))
+                    continue;
                 const srcPath = path.join(srcDir, entry.name);
                 const destPath = path.join(destDir, entry.name);
                 const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
@@ -1221,7 +1259,6 @@ async function writeHelpers(targetDir, options, result) {
                             fs.chmodSync(destPath, '755');
                         }
                         result.created.files.push(`.claude/helpers/${relPath}`);
-                        copiedCount++;
                     }
                     else {
                         result.skipped.push(`.claude/helpers/${relPath}`);
@@ -1230,11 +1267,12 @@ async function writeHelpers(targetDir, options, result) {
             }
         };
         copyRecursive(sourceHelpersDir, helpersDir, '');
-        if (copiedCount > 0) {
-            return; // Skip generating if we copied from source
-        }
     }
-    // Fall back to generating helpers if source not available
+    // Always run the fallback generator too — it only fills in files still missing
+    // after the source copy above (it no-ops on anything the copy already wrote).
+    // 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(),
@@ -1247,6 +1285,13 @@ async function writeHelpers(targetDir, options, result) {
     };
     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
+        // the correct (force-aware) copy — never let this generated fallback
+        // clobber it with a bare-bones stub. Only step in when source truly
+        // doesn't have the file, regardless of `force`.
+        const inSource = !!(sourceHelpersDir && fs.existsSync(path.join(sourceHelpersDir, name)));
+        if (inSource)
+            continue;
         if (!fs.existsSync(filePath) || options.force) {
             atomicWriteFile(filePath, content);
             // Make shell scripts executable
@@ -1549,6 +1594,7 @@ async function writeCapabilitiesDoc(targetDir, options, result) {
         result.skipped.push('.monomind/CAPABILITIES.md');
         return;
     }
+    const hooksAvailable = _isOptionalPackageResolvable('@monomind/hooks');
     const capabilities = `# Monomind - Complete Capabilities Reference
 > Generated: ${new Date().toISOString()}
 > Full documentation: https://github.com/monoes/monomind
@@ -1558,8 +1604,8 @@ async function writeCapabilitiesDoc(targetDir, options, result) {
 1. [Overview](#overview)
 2. [Swarm Orchestration](#swarm-orchestration)
 3. [Available Agents (60+)](#available-agents)
-4. [CLI Commands (26 Commands, 140+ Subcommands)](#cli-commands)
-5. [Hooks System (27 Hooks + 12 Workers)](#hooks-system)
+4. [CLI Commands](#cli-commands)
+5. [Hooks System (29 Hook Subcommands + 15 Background Workers)](#hooks-system)
 6. [Memory & Intelligence](#memory--intelligence)
 7. [Hive-Mind Consensus](#hive-mind-consensus)
 8. [Performance Targets](#performance-targets)
@@ -1661,33 +1707,31 @@ npx monomind@latest swarm monitor
 
 ## CLI Commands
 
-### Core Commands (12)
+### Core Commands
 | Command | Subcommands | Description |
 |---------|-------------|-------------|
-| \`init\` | 4 | Project initialization |
-| \`agent\` | 8 | Agent lifecycle management |
+| \`init\` | 5 | Project initialization |
+| \`agent\` | 7 | Agent lifecycle management |
 | \`swarm\` | 6 | Multi-agent coordination |
-| \`memory\` | 11 | LanceDB with ANN vector search |
+| \`memory\` | 12 | LanceDB with ANN vector search |
 | \`mcp\` | 9 | MCP server management |
-| \`task\` | 6 | Task assignment |
-| \`session\` | 7 | Session persistence |
+| \`task\` | 5 | Task assignment |
+| \`session\` | 6 | Session persistence |
 | \`config\` | 7 | Configuration |
 | \`status\` | 3 | System monitoring |
-| \`workflow\` | 6 | Workflow templates |
-| \`hooks\` | 17 | Self-learning hooks |
-| \`hive-mind\` | 6 | Consensus coordination |
+| \`hooks\` | 29 | Self-learning hooks + 15 background workers${hooksAvailable ? '' : ' (background workers unavailable in this install)'} |
+
+> Note: there is no \`hive-mind\`, \`workflow\`, \`neural\`, \`embeddings\`, \`claims\`, \`migrate\`, or \`process\` CLI command.
+> Hive-Mind consensus (byzantine/raft/quorum) is available exclusively via MCP tools, not the CLI.
+> Neural pattern learning was merged into \`hooks intelligence\`.
 
-### Advanced Commands (14)
+### Advanced Commands
 | Command | Subcommands | Description |
 |---------|-------------|-------------|
-| \`neural\` | 5 | Pattern training |
 | \`security\` | 6 | Security scanning |
-| \`performance\` | 5 | Profiling & benchmarks |
-| \`providers\` | 5 | AI provider config |
-| \`embeddings\` | 4 | Vector embeddings |
-| \`claims\` | 4 | Authorization |
-| \`migrate\` | 5 | V2→V1 migration |
-| \`process\` | 4 | Process management |
+| \`performance\` | 4 | Profiling & benchmarks |
+| \`providers\` | 4 | AI provider config |
+| \`guidance\` | 1 | Governance gate setup |
 | \`doctor\` | 1 | Health diagnostics |
 | \`completions\` | 4 | Shell completions |
 
@@ -1711,7 +1755,7 @@ npx monomind@latest doctor --fix
 
 ## Hooks System
 
-### 27 Available Hooks
+### 29 Available Hook Subcommands${hooksAvailable ? '' : ' — background workers unavailable in this install (@monomind/hooks did not resolve)'}
 
 #### Core Hooks (6)
 | Hook | Description |
@@ -1818,6 +1862,11 @@ npx monomind@latest memory init --force
 
 ## Hive-Mind Consensus
 
+> **Experimental, MCP-only.** There is no \`hive-mind\` CLI command — this is
+> single-process vote counting exposed exclusively via MCP tools
+> (\`hive-mind-tools.ts\`), not distributed networking. Reach it through the
+> MCP server (\`npx monomind@latest mcp start\`) once connected to an MCP client.
+
 ### Queen Types
 | Type | Role |
 |------|------|
@@ -1829,28 +1878,13 @@ npx monomind@latest memory init --force
 \`researcher\`, \`coder\`, \`analyst\`, \`tester\`, \`architect\`, \`reviewer\`, \`optimizer\`, \`documenter\`
 
 ### Consensus Mechanisms
-| Mechanism | Fault Tolerance | Use Case |
-|-----------|-----------------|----------|
-| \`byzantine\` | f < n/3 faulty | Adversarial |
-| \`raft\` | f < n/2 failed | Leader-based |
-| \`gossip\` | Eventually consistent | Large scale |
-| \`crdt\` | Conflict-free | Distributed |
-| \`quorum\` | Configurable | Flexible |
-
-### Hive-Mind Commands
-\`\`\`bash
-# Initialize
-npx monomind@latest hive-mind init --queen-type strategic
-
-# Status
-npx monomind@latest hive-mind status
-
-# Spawn workers
-npx monomind@latest hive-mind spawn --count 5 --type worker
-
-# Consensus
-npx monomind@latest hive-mind consensus --propose "task"
-\`\`\`
+| Mechanism | Fault Tolerance | Status |
+|-----------|-----------------|--------|
+| \`byzantine\` / \`bft\` | f < n/3 faulty | Implemented (vote counting) |
+| \`raft\` | f < n/2 failed | Implemented (vote counting) |
+| \`quorum\` | Configurable | Implemented |
+| \`gossip\` | Eventually consistent | Planned — not implemented, rejected by \`hive_mind_init\` |
+| \`crdt\` | Conflict-free | Planned — not implemented, rejected by \`hive_mind_init\` |
 
 ---
 
@@ -2074,6 +2108,10 @@ function copyDirRecursive(src, dest) {
     fs.mkdirSync(dest, { recursive: true });
     const entries = fs.readdirSync(src, { withFileTypes: true });
     for (const entry of entries) {
+        // Skip exFAT/macOS AppleDouble junk files (e.g. "._foo.js") so they don't
+        // get perpetuated into every newly-initialized project.
+        if (entry.name.startsWith('._'))
+            continue;
         const srcPath = path.join(src, entry.name);
         const destPath = path.join(dest, entry.name);
         if (entry.isDirectory()) {

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

@@ -8,6 +8,7 @@
  * containing hardcoded business logic. All business logic lives in MCP tool handlers.
  */
 import type { MCPTool } from './mcp-tools/types.js';
+export declare function isToolDisabled(toolName: string, cwd?: string): boolean;
 /**
  * MCP Client Error
  */
@@ -54,10 +55,14 @@ export declare function getToolMetadata(toolName: string): Omit<MCPTool, 'handle
  * @param category - Optional category filter
  * @returns Array of tool metadata
  */
-export declare function listMCPTools(category?: string): Array<Omit<MCPTool, 'handler'>>;
+export declare function listMCPTools(category?: string): Array<Omit<MCPTool, 'handler'> & {
+    enabled: boolean;
+}>;
 /**
- * Return all registered tools including their handler functions.
- * Used by startHttpServer() to register tools with the HTTP/WS MCP server.
+ * Return all registered tools including their handler functions, excluding
+ * any disabled via `mcp toggle`. Used by startHttpServer() to register tools
+ * with the HTTP/WS MCP server, so a disabled tool is never exposed to
+ * external MCP clients after the next server start.
  */
 export declare function getAllMCPTools(): MCPTool[];
 /**

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

@@ -7,6 +7,8 @@
  * This provides a simple interface for CLI commands to call MCP tools without
  * containing hardcoded business logic. All business logic lives in MCP tool handlers.
  */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 // Import MCP tool handlers from local package
 import { agentTools } from './mcp-tools/agent-tools.js';
 import { swarmTools } from './mcp-tools/swarm-tools.js';
@@ -95,6 +97,30 @@ registerTools([
     // Second Brain knowledge tools
     ...knowledgeTools,
 ]);
+/**
+ * Disabled-tools registry (`mcp toggle`)
+ *
+ * Read fresh on every check (the file is tiny and toggles are infrequent) so a
+ * `mcp toggle` run in another process/session takes effect without restarting
+ * this one. Filters both direct invocation (callMCPTool) and MCP server
+ * registration (getAllMCPTools) so a disabled tool is actually excluded, not
+ * just cosmetically hidden.
+ */
+function loadDisabledTools(cwd = process.cwd()) {
+    const stateFile = join(cwd, '.monomind', 'mcp-disabled-tools.json');
+    if (!existsSync(stateFile))
+        return new Set();
+    try {
+        const parsed = JSON.parse(readFileSync(stateFile, 'utf8'));
+        return Array.isArray(parsed) ? new Set(parsed) : new Set();
+    }
+    catch {
+        return new Set();
+    }
+}
+export function isToolDisabled(toolName, cwd) {
+    return loadDisabledTools(cwd).has(toolName);
+}
 /**
  * MCP Client Error
  */
@@ -138,6 +164,9 @@ export async function callMCPTool(toolName, input = {}, context) {
     if (!tool) {
         throw new MCPClientError(`MCP tool not found: ${toolName}`, toolName);
     }
+    if (isToolDisabled(toolName)) {
+        throw new MCPClientError(`MCP tool '${toolName}' is disabled. Re-enable with: mcp toggle --enable ${toolName}`, toolName);
+    }
     try {
         // Call the tool handler
         const result = await tool.handler(input, context);
@@ -179,6 +208,7 @@ export function getToolMetadata(toolName) {
  */
 export function listMCPTools(category) {
     const tools = Array.from(TOOL_REGISTRY.values());
+    const disabled = loadDisabledTools();
     const filtered = category
         ? tools.filter(t => t.category === category)
         : tools;
@@ -191,14 +221,18 @@ export function listMCPTools(category) {
         version: tool.version,
         cacheable: tool.cacheable,
         cacheTTL: tool.cacheTTL,
+        enabled: !disabled.has(tool.name),
     }));
 }
 /**
- * Return all registered tools including their handler functions.
- * Used by startHttpServer() to register tools with the HTTP/WS MCP server.
+ * Return all registered tools including their handler functions, excluding
+ * any disabled via `mcp toggle`. Used by startHttpServer() to register tools
+ * with the HTTP/WS MCP server, so a disabled tool is never exposed to
+ * external MCP clients after the next server start.
  */
 export function getAllMCPTools() {
-    return Array.from(TOOL_REGISTRY.values());
+    const disabled = loadDisabledTools();
+    return Array.from(TOOL_REGISTRY.values()).filter(t => !disabled.has(t.name));
 }
 /**
  * Check if an MCP tool exists

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

@@ -190,9 +190,15 @@ export class MCPServerManager extends EventEmitter {
         if (!pid) {
             // No PID file found. Detect if we are running in stdio mode
             // (e.g., launched by Claude Code via `claude mcp add`).
-            const isStdio = !process.stdin.isTTY;
+            //
+            // SECURITY/CORRECTNESS: this must NOT fall back to a TTY heuristic
+            // (`!process.stdin.isTTY`) — that is true for ANY non-interactive
+            // invocation (piped, in CI, in a script), so it falsely reported
+            // "running" even when no server was actually started. Only trust
+            // real state: the explicit stdio-transport env var, or the
+            // `_stdioServerStarted` flag that tracks an actually-started server.
             const envTransport = process.env.MONOMIND_MCP_TRANSPORT;
-            if (isStdio || envTransport === 'stdio' || this._stdioServerStarted) {
+            if (envTransport === 'stdio' || this._stdioServerStarted) {
                 return {
                     running: true,
                     pid: process.pid,

package/packages/@monomind/cli/dist/src/mcp-tools/agent-tools.d.ts

@@ -5,5 +5,25 @@
  * Includes model routing integration for intelligent model selection.
  */
 import { type MCPTool } from './types.js';
+type ClaudeModel = 'haiku' | 'sonnet' | 'opus' | 'inherit';
+interface AgentRecord {
+    agentId: string;
+    agentType: string;
+    status: 'idle' | 'busy' | 'terminated';
+    health: number;
+    taskCount: number;
+    config: Record<string, unknown>;
+    createdAt: string;
+    domain?: string;
+    model?: ClaudeModel;
+    modelRoutedBy?: 'explicit' | 'router' | 'agent-booster' | 'default';
+    lastResult?: Record<string, unknown>;
+}
+interface AgentStore {
+    agents: Record<string, AgentRecord>;
+    version: string;
+}
+export declare function loadAgentStore(): AgentStore;
 export declare const agentTools: MCPTool[];
+export {};
 //# sourceMappingURL=agent-tools.d.ts.map

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

@@ -7,13 +7,14 @@
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { getProjectCwd } from './types.js';
-// Storage paths
-const STORAGE_DIR = '.monomind';
+import { getMonomindDataRoot, migrateLegacyStoreFile } from './types.js';
+// Storage paths — relative to the git-safe data root (see getMonomindDataRoot()).
+// Canonical location matches task-tools.ts/session-tools.ts/hive-mind-tools.ts/
+// swarm-tools.ts so the agent store is a single physical file across all tools.
 const AGENT_DIR = 'agents';
 const AGENT_FILE = 'store.json';
 function getAgentDir() {
-    return join(getProjectCwd(), STORAGE_DIR, AGENT_DIR);
+    return join(getMonomindDataRoot(), AGENT_DIR);
 }
 function getAgentPath() {
     return join(getAgentDir(), AGENT_FILE);
@@ -25,9 +26,13 @@ function ensureAgentDir() {
     }
 }
 const MAX_AGENT_STORE_BYTES = 50 * 1024 * 1024;
-function loadAgentStore() {
+// Exported so other tool modules reading the same physical store file
+// (e.g. hive-mind-tools.ts) can reuse this hardened loader instead of
+// maintaining their own weaker copy (missing the size cap / __proto__ guard).
+export function loadAgentStore() {
     try {
         const path = getAgentPath();
+        migrateLegacyStoreFile(path, join(AGENT_DIR, AGENT_FILE));
         if (existsSync(path)) {
             if (statSync(path).size > MAX_AGENT_STORE_BYTES)
                 return { agents: {}, version: '3.0.0' };

package/packages/@monomind/cli/dist/src/mcp-tools/auto-install.d.ts

@@ -47,12 +47,12 @@ export declare function resetInstallAttempts(): void;
  */
 export declare const OPTIONAL_PACKAGES: {
     readonly 'monofence-ai': {
-        readonly description: "AI manipulation defense (prompt injection, PII detection)";
-        readonly tools: readonly ["aidefence_scan", "aidefence_analyze", "aidefence_stats", "aidefence_learn"];
+        readonly description: 'AI manipulation defense (prompt injection, PII detection)';
+        readonly tools: readonly ['aidefence_scan', 'aidefence_analyze', 'aidefence_stats', 'aidefence_learn'];
     };
     readonly 'onnxruntime-node': {
-        readonly description: "ONNX runtime for neural network inference";
-        readonly tools: readonly ["neural_*"];
+        readonly description: 'ONNX runtime for neural network inference';
+        readonly tools: readonly ['neural_*'];
     };
 };
 declare const _default: {
@@ -62,12 +62,12 @@ declare const _default: {
     resetInstallAttempts: typeof resetInstallAttempts;
     OPTIONAL_PACKAGES: {
         readonly 'monofence-ai': {
-            readonly description: "AI manipulation defense (prompt injection, PII detection)";
-            readonly tools: readonly ["aidefence_scan", "aidefence_analyze", "aidefence_stats", "aidefence_learn"];
+            readonly description: 'AI manipulation defense (prompt injection, PII detection)';
+            readonly tools: readonly ['aidefence_scan', 'aidefence_analyze', 'aidefence_stats', 'aidefence_learn'];
         };
         readonly 'onnxruntime-node': {
-            readonly description: "ONNX runtime for neural network inference";
-            readonly tools: readonly ["neural_*"];
+            readonly description: 'ONNX runtime for neural network inference';
+            readonly tools: readonly ['neural_*'];
         };
     };
 };