claude-flow 3.41.4 → 3.42.1

package/v3/@claude-flow/cli/dist/src/commands/hive-mind.js

@@ -13,6 +13,7 @@ import { mkdir, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { resolveClaudeLaunchCommand } from '../runtime/claude-command.js';
+import { getHiveTokenForCli } from '../mcp-tools/hive-mind-tools.js';
 // Hive topologies
 const TOPOLOGIES = [
     { value: 'hierarchical', label: 'Hierarchical', hint: 'Queen-led with worker agents' },
@@ -977,7 +978,7 @@ const joinCommand = {
             return { success: false, exitCode: 1 };
         }
         try {
-            const result = await callMCPTool('hive-mind_join', { agentId, role: ctx.flags.role });
+            const result = await callMCPTool('hive-mind_join', { agentId, role: ctx.flags.role, hiveToken: getHiveTokenForCli() });
             if (!result.success) {
                 output.printError(result.error || 'Failed');
                 return { success: false, exitCode: 1 };
@@ -1003,7 +1004,7 @@ const leaveCommand = {
             return { success: false, exitCode: 1 };
         }
         try {
-            const result = await callMCPTool('hive-mind_leave', { agentId });
+            const result = await callMCPTool('hive-mind_leave', { agentId, hiveToken: getHiveTokenForCli() });
             if (!result.success) {
                 output.printError(result.error || 'Failed');
                 return { success: false, exitCode: 1 };
@@ -1032,7 +1033,7 @@ const consensusCommand = {
     action: async (ctx) => {
         const action = ctx.flags.action || 'list';
         try {
-            const result = await callMCPTool('hive-mind_consensus', { action, proposalId: ctx.flags.proposalId, type: ctx.flags.type, value: ctx.flags.value, vote: ctx.flags.vote === 'yes', voterId: ctx.flags.voterId });
+            const result = await callMCPTool('hive-mind_consensus', { action, proposalId: ctx.flags.proposalId, type: ctx.flags.type, value: ctx.flags.value, vote: ctx.flags.vote === 'yes', voterId: ctx.flags.voterId, hiveToken: getHiveTokenForCli() });
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
                 return { success: true, data: result };

package/v3/@claude-flow/cli/dist/src/commands/swarm.js

@@ -8,6 +8,56 @@ import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { swarmJoinCommand } from './agntcy/swarm-join.js';
 import * as fs from 'fs';
 import * as path from 'path';
+// Read the CLI-side swarm state file (`.swarm/state.json`), written by
+// `swarm init` and rewritten by `swarm start` / `swarm stop`.
+function readLocalSwarmState() {
+    const swarmStateFile = path.join(process.cwd(), '.swarm', 'state.json');
+    if (!fs.existsSync(swarmStateFile))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(swarmStateFile, 'utf-8'));
+    }
+    catch {
+        // Ignore parse errors
+        return null;
+    }
+}
+// Resolve the id of the current swarm. Three writers persist it, under two
+// different keys and in two different files:
+//
+//   `.swarm/state.json`                    `id`                 ← `swarm init`
+//   `.swarm/state.json`                    `swarmId`            ← `swarm start`
+//   `.claude-flow/swarm/swarm-state.json`  `swarms[id].swarmId` ← MCP `swarm_init`
+//
+// The status payload used to read only the first key of the first file, so a
+// Claude Code session (which drives the MCP path) reported an active swarm
+// with agents but no usable id. Check every writer, most local first.
+function resolveSwarmId(swarmState) {
+    // A state file left behind by a previous `swarm stop` must not shadow a
+    // swarm that is still live in the MCP store — otherwise `stop` names the
+    // dead id while `swarm_shutdown`'s own "most recent running" fallback
+    // terminates a different swarm.
+    if (swarmState?.status !== 'stopped') {
+        const fromState = swarmState?.id ?? swarmState?.swarmId;
+        if (typeof fromState === 'string' && fromState)
+            return fromState;
+    }
+    try {
+        const storePath = path.join(process.cwd(), '.claude-flow', 'swarm', 'swarm-state.json');
+        if (!fs.existsSync(storePath))
+            return null;
+        const store = JSON.parse(fs.readFileSync(storePath, 'utf-8'));
+        // Most recently updated swarm that has not been shut down.
+        const live = Object.values(store.swarms ?? {})
+            .filter(swarm => swarm.status !== 'terminated')
+            .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime());
+        return live[0]?.swarmId ?? null;
+    }
+    catch {
+        // Ignore — an unreadable MCP store just means no id to resolve.
+        return null;
+    }
+}
 // Get dynamic swarm status from memory/session files
 function getSwarmStatus(swarmId) {
     const swarmDir = path.join(process.cwd(), '.swarm');
@@ -17,16 +67,7 @@ function getSwarmStatus(swarmId) {
         path.join(process.cwd(), '.claude', 'memory.db'),
     ];
     // Check for active swarm state file
-    const swarmStateFile = path.join(swarmDir, 'state.json');
-    let swarmState = null;
-    if (fs.existsSync(swarmStateFile)) {
-        try {
-            swarmState = JSON.parse(fs.readFileSync(swarmStateFile, 'utf-8'));
-        }
-        catch {
-            // Ignore parse errors
-        }
-    }
+    const swarmState = readLocalSwarmState();
     // Count active agents from process files
     let activeAgents = 0;
     let totalAgents = 0;
@@ -175,10 +216,22 @@ function getSwarmStatus(swarmId) {
         status = 'completed';
     }
     else if (swarmState) {
-        status = 'ready';
+        // The file's own lifecycle state wins over the "a file exists, so we are
+        // ready" default — a swarm explicitly recorded as stopped is not ready.
+        // Live agents still win above: they are observed reality, whereas the file
+        // records an intent that may be stale.
+        status = swarmState.status === 'stopped' ? 'stopped' : 'ready';
     }
+    // Resolve once — the id also settles whether there is a swarm to report.
+    // An MCP `swarm_init` with no agents spawned yet leaves no `.swarm/state.json`
+    // and no agent store, so without this the payload contradicted itself:
+    // a real `id` alongside `hasActiveSwarm: false`.
+    const resolvedId = swarmId || resolveSwarmId(swarmState);
     return {
-        id: swarmId || swarmState?.id || 'no-active-swarm',
+        // `null` when genuinely unknown — never a sentinel string. `status` and
+        // `hasActiveSwarm` already carry the "no active swarm" fact, and a
+        // consumer reading `.id` must get an id or nothing.
+        id: resolvedId,
         topology: swarmState?.topology || 'none',
         status,
         objective: swarmState?.objective || 'No active objective',
@@ -290,7 +343,13 @@ function getSwarmStatus(swarmId) {
             }
             return { consensusRounds, messagesSent, conflictsResolved };
         })(),
-        hasActiveSwarm: !!swarmState || totalAgents > 0
+        // A state file left behind by `swarm stop` is not an active swarm — without
+        // this it claimed one it could not name (`id: null`, zero agents), which is
+        // the same contradiction from the other side. Live agents or a resolvable
+        // id still count, so a stopped file never masks real activity.
+        hasActiveSwarm: (!!swarmState && swarmState.status !== 'stopped')
+            || totalAgents > 0
+            || resolvedId !== null
     };
 }
 // Swarm topologies
@@ -630,6 +689,9 @@ const startCommand = {
         if (!fs.existsSync(swarmDir))
             fs.mkdirSync(swarmDir, { recursive: true });
         const executionState = {
+            // `id` mirrors what `swarm init` writes so both files share one key;
+            // `swarmId` stays for existing files and readers.
+            id: swarmId,
             swarmId,
             objective,
             strategy,
@@ -673,7 +735,7 @@ const statusCommand = {
             output.writeln();
             return { success: true, data: status };
         }
-        output.writeln(output.bold(`Swarm Status: ${status.id}`));
+        output.writeln(output.bold(`Swarm Status: ${status.id ?? output.dim('unknown id')}`));
         output.writeln();
         // Progress bar
         output.writeln(`Overall Progress: ${output.progressBar(status.progress, 100, 40)}`);
@@ -747,10 +809,16 @@ const stopCommand = {
         }
     ],
     action: async (ctx) => {
-        const swarmId = ctx.args[0];
+        // Bare `swarm stop` used to hard-fail, and no CLI surface handed out an
+        // id to pass (there is no `swarm list`). Default to the persisted swarm;
+        // an explicit argument still wins.
+        const swarmId = ctx.args[0] || resolveSwarmId(readLocalSwarmState());
         const force = ctx.flags.force;
         if (!swarmId) {
-            output.printError('Swarm ID is required');
+            output.printError('No swarm found to stop');
+            output.writeln(output.dim('  Find an id with: claude-flow swarm status --format json   (the "id" field)'));
+            output.writeln(output.dim('  Or pass one:     claude-flow swarm stop <swarm-id>'));
+            output.writeln(output.dim('  Or start one:    claude-flow swarm init'));
             return { success: false, exitCode: 1 };
         }
         if (ctx.interactive && !force) {
@@ -810,11 +878,14 @@ const scaleCommand = {
         }
     ],
     action: async (ctx) => {
-        const swarmId = ctx.args[0];
+        // Same resolution as `stop` — the id is persisted, so don't demand it.
+        const swarmId = ctx.args[0] || resolveSwarmId(readLocalSwarmState());
         const targetAgents = ctx.flags.agents;
         const agentType = ctx.flags.type;
         if (!swarmId) {
-            output.printError('Swarm ID is required');
+            output.printError('No swarm found to scale');
+            output.writeln(output.dim('  Find an id with: claude-flow swarm status --format json   (the "id" field)'));
+            output.writeln(output.dim('  Or pass one:     claude-flow swarm scale <swarm-id> --agents N'));
             return { success: false, exitCode: 1 };
         }
         if (!targetAgents) {

package/v3/@claude-flow/cli/dist/src/init/claudemd-generator.js

@@ -258,7 +258,7 @@ function performanceSection() {
 
 - Always benchmark before AND after optimization
 - Always profile before optimizing — never guess bottlenecks
-- Use HNSW/DiskANN for vector search, Int8 quantization for memory reduction
+- Use HNSW for vector search, Int8 quantization for memory reduction — measure the actual speedup/recall on your own corpus via \`node scripts/benchmark-intelligence.mjs --only=hnsw\` rather than trusting a hardcoded multiplier (recall@10 varies by corpus size — 0.99 at N=5k, 0.92 at N=20k on the reference host, dream-cycle 2026-08-30)
 
 \`\`\`bash
 npx @claude-flow/cli@latest performance benchmark --suite all
@@ -293,7 +293,7 @@ function intelligenceSystem() {
 Pipeline: **RETRIEVE** (vector search) → **JUDGE** (success/failure) → **DISTILL** (extract patterns) → **CONSOLIDATE** (persist)
 
 - **ONNX Embeddings**: all-MiniLM-L6-v2, 384-dim
-- **HNSW/DiskANN**: 150x-12,500x faster search
+- **HNSW**: faster than brute-force search, magnitude scales with corpus size — reproduce with \`node scripts/benchmark-intelligence.mjs --only=hnsw\` rather than a hardcoded multiplier
 - **SONA**: Sub-millisecond pattern adaptation
 - **Claude Bridge**: Auto-imports \`~/.claude/projects/*/memory/*.md\` into AgentDB`;
 }

package/v3/@claude-flow/cli/dist/src/mcp-server.js

@@ -26,6 +26,7 @@ import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { trackRequest } from './mcp-tools/request-tracker.js';
+import { isPolicyEnforcementEnabled, loadMcpPolicy, evaluateToolCall, } from './mcp-tools/policy-enforcer.js';
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -503,6 +504,17 @@ export class MCPServerManager extends EventEmitter {
                             error: { code: -32601, message: `Tool not found: ${toolName}` },
                         };
                     }
+                    if (isPolicyEnforcementEnabled()) {
+                        const check = evaluateToolCall(loadMcpPolicy(), sessionId, toolName);
+                        if (!check.allowed) {
+                            trackRequest(toolName, false);
+                            return {
+                                jsonrpc: '2.0',
+                                id: message.id,
+                                error: { code: -32001, message: `Policy denied: ${check.reason}` },
+                            };
+                        }
+                    }
                     try {
                         const result = await callMCPTool(toolName, toolParams, { sessionId });
                         trackRequest(toolName, true);

package/v3/@claude-flow/cli/dist/src/mcp-tools/agentbbs-tools.d.ts

@@ -35,5 +35,20 @@
  * @module @claude-flow/cli/mcp-tools/agentbbs
  */
 import type { MCPTool } from './types.js';
+/** Last envelope's seq by scanning only the file tail; full-read fallback keeps it exact. */
+export declare function nextSeq(path: string): number;
+/** Timestamp (ms) of the most recent PeerHello for a room, or -Infinity if none. */
+export declare function lastPeerHelloMs(logPath: string): number;
+/**
+ * Whether a `register` call should append a PeerHello: only for a genuinely new
+ * registration, or once the heartbeat window has elapsed since the last one.
+ * A re-register within the window is a retry and must NOT spam a near-identical
+ * hello. Pure — the decision the handler makes, exported for test.
+ */
+export declare function shouldEmitHello(alreadyRegistered: boolean, nowMs: number, lastHelloMs: number, windowSecs: number): boolean;
+/** Collapse duplicate envelopeIds, preserving order (first occurrence wins). Pure. */
+export declare function dedupEnvelopes<T extends {
+    envelopeId: string;
+}>(list: T[]): T[];
 export declare const agentbbsTools: MCPTool[];
 //# sourceMappingURL=agentbbs-tools.d.ts.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/agentbbs-tools.js

@@ -34,7 +34,7 @@
  *
  * @module @claude-flow/cli/mcp-tools/agentbbs
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { resolve, isAbsolute, join } from 'node:path';
 import { randomBytes, createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
@@ -133,12 +133,83 @@ function readEnvelopes(path) {
     }
     return out;
 }
-function nextSeq(path) {
+// Tail of the log we scan to find the last seq. Envelopes are small; one line
+// always fits well inside this. Reading only the tail keeps append O(1) instead
+// of O(n) as a room log grows (ADR-164 §3.2.2 requires monotonic seq, and a
+// full re-parse on every publish was the cost).
+const SEQ_TAIL_BYTES = 65536;
+/** Last envelope's seq by scanning only the file tail; full-read fallback keeps it exact. */
+export function nextSeq(path) {
+    if (!existsSync(path))
+        return 1;
+    try {
+        const size = statSync(path).size;
+        if (size === 0)
+            return 1;
+        const start = Math.max(0, size - SEQ_TAIL_BYTES);
+        const fd = openSync(path, 'r');
+        let text;
+        try {
+            const buf = Buffer.alloc(size - start);
+            readSync(fd, buf, 0, buf.length, start);
+            text = buf.toString('utf-8');
+        }
+        finally {
+            closeSync(fd);
+        }
+        // If we started mid-file the first fragment may be a partial line — drop it.
+        const lines = text.split(/\r?\n/).filter(l => l.trim());
+        const candidates = start > 0 && lines.length > 1 ? lines.slice(1) : lines;
+        for (let i = candidates.length - 1; i >= 0; i--) {
+            try {
+                const e = JSON.parse(candidates[i]);
+                if (typeof e.seq === 'number')
+                    return e.seq + 1;
+            }
+            catch { /* keep scanning upward for the last parseable line */ }
+        }
+    }
+    catch { /* fall through to the exact full-read path */ }
+    // Fallback: whole-file parse (rare — huge single line, or a tail with no seq).
     const env = readEnvelopes(path);
     if (env.length === 0)
         return 1;
     return (env[env.length - 1].seq ?? env.length) + 1;
 }
+/** Window within which a fresh PeerHello is suppressed as a duplicate (heartbeat, not spam). */
+const HELLO_WINDOW_SECS = Number(process.env.FEDERATION_BBS_HELLO_WINDOW_SECS ?? 60);
+/** Timestamp (ms) of the most recent PeerHello for a room, or -Infinity if none. */
+export function lastPeerHelloMs(logPath) {
+    if (!existsSync(logPath))
+        return -Infinity;
+    const env = readEnvelopes(logPath);
+    for (let i = env.length - 1; i >= 0; i--) {
+        if (env[i].msgType === 'PeerHello') {
+            const t = Date.parse(env[i].timestamp);
+            return Number.isNaN(t) ? -Infinity : t;
+        }
+    }
+    return -Infinity;
+}
+/**
+ * Whether a `register` call should append a PeerHello: only for a genuinely new
+ * registration, or once the heartbeat window has elapsed since the last one.
+ * A re-register within the window is a retry and must NOT spam a near-identical
+ * hello. Pure — the decision the handler makes, exported for test.
+ */
+export function shouldEmitHello(alreadyRegistered, nowMs, lastHelloMs, windowSecs) {
+    return !alreadyRegistered || nowMs - lastHelloMs >= windowSecs * 1000;
+}
+/** Collapse duplicate envelopeIds, preserving order (first occurrence wins). Pure. */
+export function dedupEnvelopes(list) {
+    const seen = new Set();
+    return list.filter(e => {
+        if (seen.has(e.envelopeId))
+            return false;
+        seen.add(e.envelopeId);
+        return true;
+    });
+}
 /**
  * Ephemeral per-process Ed25519 keypair for human-join token signing.
  * Phase 1 contract: keys are NOT persisted across process restart — every
@@ -212,6 +283,7 @@ export const agentbbsTools = [
             const registryPath = roomsRegistryPath(basePath);
             const registry = existsSync(registryPath) ? JSON.parse(readFileSync(registryPath, 'utf-8')) : {};
             // Idempotent — re-registering the same label updates timestamp but keeps id stable.
+            const alreadyRegistered = roomId in registry;
             const entry = {
                 roomId,
                 roomLabel,
@@ -220,17 +292,25 @@ export const agentbbsTools = [
             };
             registry[roomId] = entry;
             writeFileSync(registryPath, JSON.stringify(registry, null, 2));
-            // Emit a synthetic PeerHello envelope into the room log so watchers see the join.
+            // Emit a PeerHello only when it carries information: a genuinely new
+            // registration, or a heartbeat refresh once HELLO_WINDOW_SECS has elapsed.
+            // A re-register within the window is a retry/no-op — appending a
+            // near-identical hello every call is the spam ADR-164 dedup guards against
+            // (observed live: one node published 8 near-identical PeerHellos).
             const logPath = roomLogPath(basePath, roomId);
-            const env = {
-                envelopeId: base64url(randomBytes(12)),
-                roomId,
-                seq: nextSeq(logPath),
-                msgType: 'PeerHello',
-                payload: { roomLabel, trustLevel: 'attested' },
-                timestamp: entry.registeredAt,
-            };
-            appendFileSync(logPath, JSON.stringify(env) + '\n');
+            const nowMs = Date.parse(entry.registeredAt);
+            const helloEmitted = shouldEmitHello(alreadyRegistered, nowMs, lastPeerHelloMs(logPath), HELLO_WINDOW_SECS);
+            if (helloEmitted) {
+                const env = {
+                    envelopeId: base64url(randomBytes(12)),
+                    roomId,
+                    seq: nextSeq(logPath),
+                    msgType: 'PeerHello',
+                    payload: { roomLabel, trustLevel: 'attested' },
+                    timestamp: entry.registeredAt,
+                };
+                appendFileSync(logPath, JSON.stringify(env) + '\n');
+            }
             // nodeId: deterministic per (cwd, roomId) so re-registers reuse identity.
             const nodeId = createHash('sha256')
                 .update(`agentbbs:node:${basePath}:${roomId}`)
@@ -241,6 +321,7 @@ export const agentbbsTools = [
                 roomId,
                 nodeId,
                 trustLevel: 'attested',
+                helloEmitted,
             };
         },
     },
@@ -357,13 +438,16 @@ export const agentbbsTools = [
                 const idx = all.findIndex(e => e.envelopeId === sinceEnvelopeId);
                 slice = idx >= 0 ? all.slice(idx + 1) : all;
             }
-            const envelopes = slice.slice(-limit);
+            // Dedup by envelopeId before applying the limit — a relay replay or a
+            // double-append must not surface the same envelope twice to a watcher.
+            const deduped = dedupEnvelopes(slice);
+            const envelopes = deduped.slice(-limit);
             return {
                 success: true,
                 roomId,
                 envelopes,
                 count: envelopes.length,
-                hasMore: slice.length > envelopes.length,
+                hasMore: deduped.length > envelopes.length,
             };
         },
     },

package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-tools.js

@@ -303,13 +303,24 @@ export const agentdbPatternSearch = {
                 // Tier 1 — semantic
                 let results = [];
                 let tier = 'semantic';
+                // #3325: a thrown error and a genuine zero-match were indistinguishable
+                // — `catch {}` discarded the former, `semantic?.results ?? []` treated
+                // `{success: false, error}` (which searchEntries returns WITHOUT
+                // throwing) as the latter. Capture whichever fires so a caller that
+                // lands on tier=substring can tell why, instead of source-reading.
+                let semanticError;
                 try {
                     const semantic = await searchEntries({ query, namespace: 'pattern', limit: topK });
+                    if (semantic && semantic.success === false) {
+                        semanticError = semantic.error ?? 'searchEntries returned success:false';
+                    }
                     results = (semantic?.results ?? [])
                         .map(parseEntry)
                         .filter((r) => r !== null);
                 }
-                catch { /* fall through to tier 2 */ }
+                catch (err) {
+                    semanticError = sanitizeError(err);
+                }
                 // Tier 2 — substring scan (catches just-written entries before HNSW indexes them).
                 // #2226: listEntries returns metadata only (no content/value — see open #2014),
                 // so parseEntry would always null out here. Fetch each entry's content by key via
@@ -358,6 +369,11 @@ export const agentdbPatternSearch = {
                     reason: result ? `reasoningBank-empty:${result.controller ?? 'unknown'}` : 'reasoningBank-unavailable:registry-null',
                     controller: 'memory-store-fallback',
                     tier,
+                    // #3325: when tier=substring because tier 1 hit a real error (thrown,
+                    // or {success:false, error}) rather than a genuine zero-match,
+                    // surface why — otherwise a hard failure and an honest "not found"
+                    // are indistinguishable from the response alone.
+                    ...(tier === 'substring' && semanticError ? { semanticError } : {}),
                     note: result
                         ? `ReasoningBank returned 0 results; tier=${tier} from pattern namespace.`
                         : `ReasoningBank controller unavailable; tier=${tier} from pattern namespace.`,

package/v3/@claude-flow/cli/dist/src/mcp-tools/hive-mind-tools.d.ts

@@ -4,5 +4,13 @@
  * Tool definitions for collective intelligence and swarm coordination.
  */
 import { type MCPTool } from './types.js';
+/**
+ * Read the current hiveToken directly off disk, for same-machine callers
+ * that already have filesystem access to hive state (the CLI's own
+ * `hive-mind join/leave/consensus` subcommands) -- NOT exposed over any MCP
+ * tool response (in particular, not hive-mind_status), since that's a
+ * remote-reachable surface a capability token must not leak through.
+ */
+export declare function getHiveTokenForCli(): string | undefined;
 export declare const hiveMindTools: MCPTool[];
 //# sourceMappingURL=hive-mind-tools.d.ts.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/hive-mind-tools.js

@@ -5,6 +5,7 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText } from './validate-input.js';
 // Storage paths
@@ -83,6 +84,36 @@ function tryResolveProposal(proposal, totalNodes) {
     }
     return null;
 }
+/**
+ * Verify a caller-supplied hiveToken against the one minted by hive-mind_init,
+ * using a constant-time comparison (bearer-token capability check -- callers
+ * that never joined, and callers that guess/omit the token, get identical
+ * rejection). Returns an error string on failure, or null on success.
+ */
+function requireHiveToken(state, suppliedToken) {
+    if (!state.hiveToken) {
+        return 'Hive-mind has no capability token minted (re-run hive-mind_init)';
+    }
+    if (typeof suppliedToken !== 'string' || !suppliedToken) {
+        return 'hiveToken is required';
+    }
+    const expected = Buffer.from(state.hiveToken, 'utf-8');
+    const actual = Buffer.from(suppliedToken, 'utf-8');
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+        return 'Invalid hiveToken';
+    }
+    return null;
+}
+/**
+ * Read the current hiveToken directly off disk, for same-machine callers
+ * that already have filesystem access to hive state (the CLI's own
+ * `hive-mind join/leave/consensus` subcommands) -- NOT exposed over any MCP
+ * tool response (in particular, not hive-mind_status), since that's a
+ * remote-reachable surface a capability token must not leak through.
+ */
+export function getHiveTokenForCli() {
+    return loadHiveState().hiveToken;
+}
 function getHiveDir() {
     return join(getProjectCwd(), STORAGE_DIR, HIVE_DIR);
 }
@@ -248,6 +279,14 @@ export const hiveMindTools = [
                 electedAt: new Date().toISOString(),
                 term: 1,
             };
+            // Mint a capability token on first init; a re-init (topology/consensus
+            // change on an already-initialized hive) keeps the existing token and
+            // roster rather than silently invalidating workers who already hold
+            // it -- only re-generated if somehow absent (e.g. state predates this
+            // field).
+            if (!state.hiveToken) {
+                state.hiveToken = randomBytes(32).toString('hex');
+            }
             saveHiveState(state);
             return {
                 success: true,
@@ -256,6 +295,7 @@ export const hiveMindTools = [
                 consensus: state.consensusStrategy,
                 queenId,
                 status: 'initialized',
+                hiveToken: state.hiveToken,
                 config: {
                     topology: state.topology,
                     consensus: state.consensusStrategy,
@@ -375,8 +415,9 @@ export const hiveMindTools = [
             properties: {
                 agentId: { type: 'string', description: 'Agent ID to join' },
                 role: { type: 'string', enum: ['worker', 'specialist', 'scout'], description: 'Agent role in hive' },
+                hiveToken: { type: 'string', description: 'Capability token minted by hive-mind_init' },
             },
-            required: ['agentId'],
+            required: ['agentId', 'hiveToken'],
         },
         handler: async (input) => {
             const state = loadHiveState();
@@ -389,6 +430,13 @@ export const hiveMindTools = [
             if (!state.initialized) {
                 return { success: false, error: 'Hive-mind not initialized' };
             }
+            // Fail-closed: an unrecognized/missing token makes no membership
+            // change at all -- state.workers is untouched, not just left
+            // unsaved (the write below never happens on this path).
+            const tokenError = requireHiveToken(state, input.hiveToken);
+            if (tokenError) {
+                return { success: false, agentId, error: tokenError };
+            }
             if (!state.workers.includes(agentId)) {
                 state.workers.push(agentId);
                 saveHiveState(state);
@@ -410,8 +458,9 @@ export const hiveMindTools = [
             type: 'object',
             properties: {
                 agentId: { type: 'string', description: 'Agent ID to remove' },
+                hiveToken: { type: 'string', description: 'Capability token minted by hive-mind_init' },
             },
-            required: ['agentId'],
+            required: ['agentId', 'hiveToken'],
         },
         handler: async (input) => {
             const state = loadHiveState();
@@ -421,6 +470,12 @@ export const hiveMindTools = [
                 if (!v.valid)
                     return { success: false, agentId, error: v.error };
             }
+            // Fail-closed: a denied caller makes no membership change -- the
+            // splice/save below is unreachable on this path.
+            const tokenError = requireHiveToken(state, input.hiveToken);
+            if (tokenError) {
+                return { success: false, agentId, error: tokenError };
+            }
             const index = state.workers.indexOf(agentId);
             if (index > -1) {
                 state.workers.splice(index, 1);
@@ -448,6 +503,7 @@ export const hiveMindTools = [
                 value: { description: 'Proposal value (for propose)' },
                 vote: { type: 'boolean', description: 'Vote (true=for, false=against)' },
                 voterId: { type: 'string', description: 'Voter agent ID' },
+                hiveToken: { type: 'string', description: 'Capability token minted by hive-mind_init (required to vote)' },
                 strategy: { type: 'string', enum: ['bft', 'raft', 'quorum'], description: 'Consensus strategy (default: raft)' },
                 quorumPreset: { type: 'string', enum: ['unanimous', 'majority', 'supermajority'], description: 'Quorum threshold preset (for quorum strategy, default: majority)' },
                 term: { type: 'number', description: 'Term number (for raft strategy)' },
@@ -531,6 +587,28 @@ export const hiveMindTools = [
                 if (!voterId) {
                     return { action, error: 'voterId is required for voting' };
                 }
+                // Fail-closed: a denied caller records no vote at all -- the
+                // votes[voterId] write below is unreachable on this path, and
+                // nothing about the proposal (vote tallies, status) changes.
+                const tokenError = requireHiveToken(state, input.hiveToken);
+                if (tokenError) {
+                    return { action, error: tokenError, proposalId: proposal.proposalId };
+                }
+                // voterId was previously trusted as-is: any caller-supplied string
+                // was recorded into proposal.votes and counted toward
+                // calculateRequiredVotes()'s threshold (derived from
+                // state.workers.length), with no check that it named a worker who
+                // actually joined this hive-mind. That let a single caller cross
+                // any strategy's quorum (raft/bft/quorum alike) by voting under
+                // fabricated ids — a Sybil attack on consensus, not merely a
+                // double-vote. Require the voter to be a registered worker.
+                if (!state.workers.includes(voterId)) {
+                    return {
+                        action,
+                        error: `Voter ${voterId} is not a registered hive-mind worker`,
+                        proposalId: proposal.proposalId,
+                    };
+                }
                 const voteValue = input.vote;
                 const proposalStrategy = proposal.strategy || 'raft';
                 const required = calculateRequiredVotes(proposalStrategy, totalNodes, proposal.quorumPreset);