monomind 2.0.2 → 2.1.0

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
@@ -1180,13 +1196,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)))) {
@@ -1208,6 +1226,9 @@ async function writeHelpers(targetDir, options, result) {
         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;
@@ -1549,6 +1570,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 +1580,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 +1683,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 +1731,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 +1838,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 +1854,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 +2084,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/github-tools.js

@@ -60,6 +60,18 @@ function runSafe(cmd, args, cwd) {
         return null;
     }
 }
+/** Run a `gh` command and preserve the real failure reason instead of collapsing to null. */
+function runSafeResult(cmd, args, cwd) {
+    try {
+        const stdout = execFileSync(cmd, args, { encoding: 'utf-8', timeout: 15000, cwd: cwd || getProjectCwd(), stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        return { ok: true, stdout };
+    }
+    catch (err) {
+        const e = err;
+        const stderr = e.stderr ? String(e.stderr).trim() : '';
+        return { ok: false, error: stderr || e.message || 'gh command failed' };
+    }
+}
 /** Check if gh CLI is available */
 function hasGhCli() {
     return run('gh --version') !== null;
@@ -216,7 +228,11 @@ export const githubTools = [
                 }
                 // Fallback: local store
                 const prId = `pr-${Date.now()}`;
-                const pr = { id: prId, title, status: 'open', branch: headBranch, baseBranch, createdAt: new Date().toISOString() };
+                // Locally-assigned PR number, independent of the timestamp-based key —
+                // monotonic within this store so lookups by number are unambiguous.
+                const existingNumbers = Object.values(store.prs).map(p => p.number || 0);
+                const nextNumber = existingNumbers.length > 0 ? Math.max(...existingNumbers) + 1 : 1;
+                const pr = { id: prId, number: nextNumber, title, status: 'open', branch: headBranch, baseBranch, createdAt: new Date().toISOString() };
                 store.prs[prId] = pr;
                 saveGitHubStore(store);
                 return { success: true, source: 'local-store', action: 'created', pullRequest: pr };
@@ -241,13 +257,17 @@ export const githubTools = [
                 if (!prNumber)
                     return { success: false, error: 'prNumber is required and must be a positive integer for merge.' };
                 if (gh) {
-                    const result = runSafe('gh', ['pr', 'merge', String(prNumber), '--merge']);
-                    if (result !== null) {
+                    // gh CLI is actually installed — trust its real exit status. A genuine
+                    // failure (branch protection, conflicts, auth) must be reported as a
+                    // failure, not silently swallowed into the local-store simulation.
+                    const result = runSafeResult('gh', ['pr', 'merge', String(prNumber), '--merge']);
+                    if (result.ok) {
                         return { success: true, _real: true, action: 'merged', prNumber, mergedAt: new Date().toISOString() };
                     }
+                    return { success: false, error: result.error };
                 }
-                // Fallback: local store
-                const prKey = Object.keys(store.prs).find(k => k.includes(String(prNumber)));
+                // Fallback: local store (only reached when gh CLI is not installed at all)
+                const prKey = Object.keys(store.prs).find(k => store.prs[k].number === prNumber);
                 if (prKey && store.prs[prKey]) {
                     store.prs[prKey].status = 'merged';
                     saveGitHubStore(store);
@@ -259,12 +279,14 @@ export const githubTools = [
                 if (!prNumber)
                     return { success: false, error: 'prNumber is required and must be a positive integer for close.' };
                 if (gh) {
-                    const result = runSafe('gh', ['pr', 'close', String(prNumber)]);
-                    if (result !== null) {
+                    const result = runSafeResult('gh', ['pr', 'close', String(prNumber)]);
+                    if (result.ok) {
                         return { success: true, _real: true, action: 'closed', prNumber, closedAt: new Date().toISOString() };
                     }
+                    return { success: false, error: result.error };
                 }
-                const prKey = Object.keys(store.prs).find(k => k.includes(String(prNumber)));
+                // Fallback: local store (only reached when gh CLI is not installed at all)
+                const prKey = Object.keys(store.prs).find(k => store.prs[k].number === prNumber);
                 if (prKey && store.prs[prKey]) {
                     store.prs[prKey].status = 'closed';
                     saveGitHubStore(store);

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

@@ -4,7 +4,14 @@
  * All graphify_* tools are deprecated. They proxy to monograph_* tools.
  * Will be removed in next major release.
  */
-import { allMonographTools } from './monograph-tools.js';
+import { allMonographTools, monographTools } from './monograph-tools.js';
+// Advanced monograph tools are gated behind MONOGRAPH_MCP_ADVANCED=1 (see
+// monograph-tools.ts). Shims that target an advanced-tier tool must be gated
+// the same way, otherwise they re-expose advanced tools under a different
+// name regardless of the flag. `monographTools` is the already-gated export
+// (core-only unless MONOGRAPH_MCP_ADVANCED=1); a target is "advanced" if it's
+// present in allMonographTools but absent from monographTools.
+const exposedMonographNames = new Set(monographTools.map(t => t.name));
 function findMonographTool(name) {
     const tool = allMonographTools.find(t => t.name === name);
     if (!tool)
@@ -12,6 +19,8 @@ function findMonographTool(name) {
     return tool;
 }
 function shimTool(graphifyName, monographName, paramMap) {
+    if (!exposedMonographNames.has(monographName))
+        return null;
     const target = findMonographTool(monographName);
     return {
         name: graphifyName,
@@ -44,6 +53,6 @@ export const graphifyTools = [
     shimTool('graphify_report', 'monograph_report'),
     // Bug fix: graphify_health previously referenced `files.length` (ReferenceError) — now delegates cleanly
     shimTool('graphify_health', 'monograph_health'),
-];
+].filter((t) => t !== null);
 export default graphifyTools;
 //# sourceMappingURL=graphify-tools.js.map

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

@@ -13,8 +13,12 @@
 import { existsSync, readFileSync, statSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
-import { getProjectCwd } from './types.js';
+import { getProjectCwd, getMonomindDataRoot, migrateLegacyStoreFile } from './types.js';
 import { weightedTally } from '../consensus/tally.js';
+// Reuse agent-tools.ts's hardened store loader (50MB size cap + __proto__
+// rejection) instead of maintaining a second, weaker copy that reads the
+// same physical file — see loadAgentStore export note there.
+import { loadAgentStore } from './agent-tools.js';
 // Storage paths
 const STORAGE_DIR = '.monomind';
 const HIVE_DIR = 'hive-mind';
@@ -92,7 +96,7 @@ function tryResolveProposal(proposal, totalNodes) {
     return null;
 }
 function getHiveDir() {
-    return join(getProjectCwd(), STORAGE_DIR, HIVE_DIR);
+    return join(getMonomindDataRoot(), HIVE_DIR);
 }
 function getHivePath() {
     return join(getHiveDir(), HIVE_FILE);
@@ -107,6 +111,7 @@ const MAX_HIVE_STATE_BYTES = 10 * 1024 * 1024; // 10 MB
 function loadHiveState() {
     try {
         const path = getHivePath();
+        migrateLegacyStoreFile(path, join(HIVE_DIR, HIVE_FILE));
         if (existsSync(path) && statSync(path).size <= MAX_HIVE_STATE_BYTES) {
             const data = readFileSync(path, 'utf-8');
             return JSON.parse(data);
@@ -176,21 +181,10 @@ function getOrCreateSessionSecret() {
     }
 }
 // Import agent store helpers for spawn functionality
-import { existsSync as agentStoreExists, readFileSync as readAgentStore, writeFileSync as writeAgentStore, mkdirSync as mkdirAgentStore } from 'node:fs';
-// Canonical agent store path matches agent-tools.ts: .monomind/agents/store.json
-function loadAgentStore() {
-    const storePath = join(getProjectCwd(), '.monomind', 'agents', 'store.json');
-    try {
-        if (agentStoreExists(storePath)) {
-            return JSON.parse(readAgentStore(storePath, 'utf-8'));
-        }
-    }
-    catch { /* ignore */ }
-    return { agents: {} };
-}
+import { existsSync as agentStoreExists, writeFileSync as writeAgentStore, mkdirSync as mkdirAgentStore } from 'node:fs';
 const HIVE_RESERVED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 function saveAgentStore(store) {
-    const storeDir = join(getProjectCwd(), '.monomind', 'agents');
+    const storeDir = join(getMonomindDataRoot(), 'agents');
     if (!agentStoreExists(storeDir)) {
         mkdirAgentStore(storeDir, { recursive: true });
     }
@@ -284,6 +278,10 @@ export const hiveMindTools = [
             properties: {
                 topology: { type: 'string', enum: ['mesh', 'hierarchical', 'ring', 'star'], description: 'Network topology' },
                 queenId: { type: 'string', description: 'Initial queen agent ID' },
+                consensus: { type: 'string', enum: ['byzantine', 'bft', 'raft', 'quorum'], description: 'Consensus strategy to govern hive-mind_consensus propose/vote (gossip/crdt are planned but not implemented and fall back to byzantine). Default: byzantine.' },
+                maxAgents: { type: 'number', description: 'Maximum number of agents in the hive. Default: 15.' },
+                persist: { type: 'boolean', description: 'Whether to persist hive state to disk. Default: true.' },
+                memoryBackend: { type: 'string', description: 'Shared memory backend for the hive. Default: hybrid.' },
             },
         },
         handler: async (input) => {
@@ -294,32 +292,34 @@ export const hiveMindTools = [
             const queenId = typeof rawQueenId === 'string' && rawQueenId.length > MAX_QUEEN_ID_LEN
                 ? rawQueenId.slice(0, MAX_QUEEN_ID_LEN) : rawQueenId;
             const now = new Date().toISOString();
+            // Validate consensus strategy: gossip and crdt are planned but not implemented
+            const SUPPORTED_CONSENSUS = ['byzantine', 'bft', 'raft', 'quorum'];
+            const PLANNED_CONSENSUS = ['gossip', 'crdt'];
+            const requestedConsensus = input.consensus || 'byzantine';
+            const consensusWarning = PLANNED_CONSENSUS.includes(requestedConsensus)
+                ? `Strategy "${requestedConsensus}" is planned but not yet implemented; defaulting to "byzantine".`
+                : undefined;
+            const effectiveConsensus = PLANNED_CONSENSUS.includes(requestedConsensus)
+                ? 'byzantine'
+                : (SUPPORTED_CONSENSUS.includes(requestedConsensus) ? requestedConsensus : 'byzantine');
             const state = {
                 initialized: true,
                 hiveId,
                 topology: input.topology || 'mesh',
                 queen: { agentId: queenId, electedAt: now, term: 1 },
                 workers: [],
+                // Persist the chosen strategy on the hive state so hive-mind_consensus
+                // propose/vote default to it instead of silently using 'raft'.
+                // 'byzantine' is the CLI-facing name; the internal ConsensusStrategy type uses 'bft'.
+                consensusStrategy: (effectiveConsensus === 'byzantine' ? 'bft' : effectiveConsensus),
                 consensus: { pending: [], history: [] },
                 sharedMemory: {},
                 createdAt: now,
                 updatedAt: now,
             };
-            saveHiveState(state);
-            // Validate consensus strategy: gossip and crdt are planned but not implemented
-            const SUPPORTED_CONSENSUS = ['byzantine', 'bft', 'raft', 'quorum'];
-            const PLANNED_CONSENSUS = ['gossip', 'crdt'];
-            const requestedConsensus = input.consensus || 'byzantine';
-            const consensusWarning = PLANNED_CONSENSUS.includes(requestedConsensus)
-                ? `Strategy "${requestedConsensus}" is planned but not yet implemented; defaulting to "byzantine".`
-                : undefined;
-            const effectiveConsensus = PLANNED_CONSENSUS.includes(requestedConsensus)
-                ? 'byzantine'
-                : (SUPPORTED_CONSENSUS.includes(requestedConsensus) ? requestedConsensus : 'byzantine');
-            // Persist the chosen strategy on the hive state so hive-mind_consensus
-            // propose/vote default to it instead of silently using 'raft'.
-            // 'byzantine' is the CLI-facing name; the internal ConsensusStrategy type uses 'bft'.
-            state.consensusStrategy = (effectiveConsensus === 'byzantine' ? 'bft' : effectiveConsensus);
+            // Single write — a prior version of this handler saved state twice
+            // (once before setting consensusStrategy, once after), which was
+            // redundant.
             saveHiveState(state);
             return {
                 success: true,
@@ -357,7 +357,8 @@ export const hiveMindTools = [
             // Load agent store once for all workers
             const agentStore = loadAgentStore();
             // Compute real task metrics from task store
-            const taskStorePath = join(getProjectCwd(), '.monomind', 'tasks', 'store.json');
+            const taskStorePath = join(getMonomindDataRoot(), 'tasks', 'store.json');
+            migrateLegacyStoreFile(taskStorePath, join('tasks', 'store.json'));
             let pendingTaskCount = 0;
             let activeTaskCount = 0;
             let completedTaskCount = 0;
@@ -382,7 +383,14 @@ export const hiveMindTools = [
                 hiveId: state.hiveId ?? `hive-${state.createdAt ? new Date(state.createdAt).getTime() : Date.now()}`,
                 status: state.initialized ? 'active' : 'offline',
                 topology: state.topology,
-                consensus: 'byzantine', // Default consensus type
+                // Reflect the strategy actually chosen at hive-mind_init (persisted
+                // as state.consensusStrategy so it "actually governs voting" — see
+                // the field's doc comment) instead of hardcoding a default that
+                // ignored what was configured. 'bft' is the internal name for the
+                // CLI-facing 'byzantine' strategy.
+                consensus: state.consensusStrategy
+                    ? (state.consensusStrategy === 'bft' ? 'byzantine' : state.consensusStrategy)
+                    : 'byzantine',
                 queen: state.queen ? {
                     id: state.queen.agentId,
                     agentId: state.queen.agentId,
@@ -729,9 +737,18 @@ export const hiveMindTools = [
                     confidence: 1.0, // uniform until confidence-probe is wired
                 }));
                 const cpwbftTally = weightedTally(weightedVotes);
-                // O-Information gate: defer resolution if we haven't seen enough divergent rounds
+                // O-Information gate: defer resolution if we haven't seen enough divergent rounds.
+                // BUT: if every expected voter has already cast a vote (electorate
+                // exhausted), no more votes can ever arrive to produce a divergent
+                // round — a unanimous first-round vote would otherwise deadlock the
+                // proposal permanently since divergenceRoundsSeen only increments on
+                // disagreement. Treat electorate exhaustion as a terminal condition
+                // that opens the gate regardless of divergence.
+                const totalVotesCast = Object.keys(proposal.votes).length;
+                const electorateExhausted = totalNodes > 0 && totalVotesCast >= totalNodes;
                 const divergenceGateOpen = !proposal.minDivergenceRounds
-                    || (proposal.divergenceRoundsSeen ?? 0) >= proposal.minDivergenceRounds;
+                    || (proposal.divergenceRoundsSeen ?? 0) >= proposal.minDivergenceRounds
+                    || electorateExhausted;
                 // Try to resolve
                 const resolution = divergenceGateOpen ? tryResolveProposal(proposal, totalNodes) : null;
                 let resolved = false;