claude-flow 3.7.0-alpha.44 → 3.7.0-alpha.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.7.0-alpha.44",
+  "version": "3.7.0-alpha.45",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

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

@@ -0,0 +1,149 @@
+/**
+ * Hive-Mind Consensus Runtime — ADR-095 G2.2.
+ *
+ * Before this module, `hive-mind_*` MCP tools were a JSON-file state machine
+ * that hand-rolled raft/byzantine/quorum voting on top of `state.consensus`
+ * and never touched `@claude-flow/swarm`'s real `ConsensusEngine`. That worked
+ * for a single MCP server but ignored every cross-host machinery G2 was meant
+ * to unlock: real RequestVote/AppendEntries RPCs, Ed25519-signed PBFT
+ * messages, FederationTransport over ADR-104 WS, BFT quorum derived from
+ * actual cluster size.
+ *
+ * This module owns a process-level `ConsensusEngine` plus a pluggable
+ * `ConsensusTransport`. `hive-mind_init` calls `init()` here; the consensus /
+ * broadcast / shutdown MCP tools delegate to it.
+ *
+ * Transport selection:
+ *   - `transport: 'local'`        → LocalTransport (in-process registry).
+ *                                    Matches the legacy single-process path;
+ *                                    real engine, just no WS.
+ *   - `transport: 'federation'`   → FederationTransport over an
+ *                                    agentic-flow/transport/loader wire.
+ *                                    Real cross-host messaging. Requires
+ *                                    `agentic-flow` to be resolvable; if
+ *                                    it's not, init returns
+ *                                    `transport: 'local'` with `degraded:
+ *                                    true` and a fallbackReason — the
+ *                                    engine still works locally, the caller
+ *                                    just knows the cross-host wire didn't
+ *                                    come up.
+ *   - `transport: 'auto'` (default)→ Probe for `agentic-flow`; if loadable
+ *                                    AND `peers` were supplied with
+ *                                    addresses, use federation; else local.
+ *
+ * Why peers are passed in (not auto-discovered): the federation plugin's
+ * DiscoveryService is the canonical source of peers, but wiring it into the
+ * MCP runtime is a separate concern (it has its own lifecycle / consent
+ * gates). Until that lands as G2.3, callers explicitly supply the peer
+ * list; the runtime is honest about what it received.
+ */
+import type { ConsensusEngine as ConsensusEngineType, ConsensusTransport as ConsensusTransportType, ConsensusVote, ConsensusProposal, ConsensusResult, ConsensusAlgorithm } from '@claude-flow/swarm';
+export type HiveTransportKind = 'local' | 'federation' | 'auto';
+export type HiveAlgorithm = 'raft' | 'byzantine' | 'gossip';
+export interface HivePeerConfig {
+    /** Consensus node id used by Raft/PBFT/Gossip as `from`. */
+    readonly nodeId: string;
+    /**
+     * Wire-level address (e.g. `wss://host:port`). Required for
+     * `transport: 'federation'`; ignored for `transport: 'local'`.
+     */
+    readonly address?: string;
+    /**
+     * Ed25519 SPKI PEM public key for inbound signature verification.
+     * When provided, FederationTransport will fail-closed on unverifiable
+     * messages from this peer.
+     */
+    readonly publicKeyPem?: string;
+}
+export interface HiveRuntimeInitOptions {
+    readonly nodeId: string;
+    readonly algorithm?: HiveAlgorithm;
+    readonly transport?: HiveTransportKind;
+    readonly peers?: readonly HivePeerConfig[];
+    /** Default per-send timeout for transports. */
+    readonly timeoutMs?: number;
+    /** Consensus threshold (0-1). Forwarded to ConsensusEngine. */
+    readonly threshold?: number;
+}
+export interface HiveRuntimeInitResult {
+    readonly initialized: true;
+    readonly nodeId: string;
+    readonly algorithm: HiveAlgorithm;
+    /** What we actually got — may differ from requested if federation degraded. */
+    readonly transport: 'local' | 'federation';
+    /** True when the caller asked for federation but we fell back to local. */
+    readonly degraded: boolean;
+    /** Human-readable reason for the degradation. */
+    readonly fallbackReason?: string;
+    readonly peerCount: number;
+    readonly source: 'engine';
+}
+export interface HiveRuntimeStatus {
+    readonly initialized: boolean;
+    readonly nodeId?: string;
+    readonly algorithm?: HiveAlgorithm;
+    readonly transport: 'local' | 'federation' | null;
+    readonly degraded: boolean;
+    readonly peers: readonly string[];
+    readonly engine: {
+        readonly algorithm: ConsensusAlgorithm;
+        readonly totalProposals: number;
+        readonly pendingProposals: number;
+        readonly acceptedProposals: number;
+        readonly rejectedProposals: number;
+        readonly expiredProposals: number;
+    } | null;
+}
+declare class HiveConsensusRuntime {
+    private engine;
+    private transport;
+    private wire;
+    private transportKind;
+    private nodeId;
+    private algorithm;
+    private peers;
+    private degraded;
+    private fallbackReason;
+    isInitialized(): boolean;
+    /**
+     * Lazy-initialize the consensus engine + transport. Idempotent on the
+     * same nodeId/algorithm/transport tuple — subsequent calls return the
+     * existing state. Different parameters trigger a clean shutdown + reinit.
+     */
+    init(opts: HiveRuntimeInitOptions): Promise<HiveRuntimeInitResult>;
+    /**
+     * Probe for the agentic-flow QUIC/WS transport loader. Returns the wire
+     * when loadable; an explanatory reason when not. Never throws — failure
+     * is data, not control flow, so the runtime can degrade cleanly.
+     */
+    private tryLoadFederationWire;
+    /** Propose a value through the real ConsensusEngine. */
+    propose(value: unknown, proposerId?: string): Promise<ConsensusProposal>;
+    /** Record a vote against an active proposal. */
+    vote(proposalId: string, vote: ConsensusVote): Promise<void>;
+    /**
+     * Block until a proposal resolves (accepted / rejected / expired).
+     * Used by the MCP tool when callers want a synchronous result instead
+     * of polling `proposal-status`.
+     */
+    awaitConsensus(proposalId: string): Promise<ConsensusResult>;
+    /**
+     * Broadcast a free-form payload to all known peers via the transport.
+     * Gossip-style, no reply expected. Wraps the payload so peers don't
+     * confuse it with protocol messages — `type: 'hive-broadcast'`.
+     */
+    broadcast(payload: unknown, priority?: 'low' | 'normal' | 'high' | 'critical'): Promise<{
+        delivered: number;
+        transport: 'local' | 'federation';
+    }>;
+    status(): HiveRuntimeStatus;
+    shutdown(): Promise<void>;
+    /** Test seam: replace the singleton's underlying engine + transport. */
+    __setForTest(engine: ConsensusEngineType, transport: ConsensusTransportType, nodeId: string, kind?: 'local' | 'federation'): void;
+    private toInitResult;
+}
+/** Process-level singleton — one engine per MCP server. */
+export declare const hiveConsensusRuntime: HiveConsensusRuntime;
+/** Re-export the singleton's type for tests / advanced consumers. */
+export type { HiveConsensusRuntime };
+//# sourceMappingURL=hive-consensus-runtime.d.ts.map

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

@@ -0,0 +1,296 @@
+/**
+ * Hive-Mind Consensus Runtime — ADR-095 G2.2.
+ *
+ * Before this module, `hive-mind_*` MCP tools were a JSON-file state machine
+ * that hand-rolled raft/byzantine/quorum voting on top of `state.consensus`
+ * and never touched `@claude-flow/swarm`'s real `ConsensusEngine`. That worked
+ * for a single MCP server but ignored every cross-host machinery G2 was meant
+ * to unlock: real RequestVote/AppendEntries RPCs, Ed25519-signed PBFT
+ * messages, FederationTransport over ADR-104 WS, BFT quorum derived from
+ * actual cluster size.
+ *
+ * This module owns a process-level `ConsensusEngine` plus a pluggable
+ * `ConsensusTransport`. `hive-mind_init` calls `init()` here; the consensus /
+ * broadcast / shutdown MCP tools delegate to it.
+ *
+ * Transport selection:
+ *   - `transport: 'local'`        → LocalTransport (in-process registry).
+ *                                    Matches the legacy single-process path;
+ *                                    real engine, just no WS.
+ *   - `transport: 'federation'`   → FederationTransport over an
+ *                                    agentic-flow/transport/loader wire.
+ *                                    Real cross-host messaging. Requires
+ *                                    `agentic-flow` to be resolvable; if
+ *                                    it's not, init returns
+ *                                    `transport: 'local'` with `degraded:
+ *                                    true` and a fallbackReason — the
+ *                                    engine still works locally, the caller
+ *                                    just knows the cross-host wire didn't
+ *                                    come up.
+ *   - `transport: 'auto'` (default)→ Probe for `agentic-flow`; if loadable
+ *                                    AND `peers` were supplied with
+ *                                    addresses, use federation; else local.
+ *
+ * Why peers are passed in (not auto-discovered): the federation plugin's
+ * DiscoveryService is the canonical source of peers, but wiring it into the
+ * MCP runtime is a separate concern (it has its own lifecycle / consent
+ * gates). Until that lands as G2.3, callers explicitly supply the peer
+ * list; the runtime is honest about what it received.
+ */
+class HiveConsensusRuntime {
+    engine = null;
+    transport = null;
+    wire = null;
+    transportKind = null;
+    nodeId = null;
+    algorithm = 'raft';
+    peers = [];
+    degraded = false;
+    fallbackReason;
+    isInitialized() {
+        return this.engine !== null;
+    }
+    /**
+     * Lazy-initialize the consensus engine + transport. Idempotent on the
+     * same nodeId/algorithm/transport tuple — subsequent calls return the
+     * existing state. Different parameters trigger a clean shutdown + reinit.
+     */
+    async init(opts) {
+        const requestedAlgorithm = opts.algorithm ?? 'raft';
+        const requestedTransport = opts.transport ?? 'auto';
+        const peers = [...(opts.peers ?? [])];
+        // If already initialized with the same shape, return existing state.
+        if (this.engine && this.nodeId === opts.nodeId && this.algorithm === requestedAlgorithm) {
+            return this.toInitResult();
+        }
+        // Different shape — tear down before re-instantiating.
+        if (this.engine) {
+            await this.shutdown();
+        }
+        const swarm = await import('@claude-flow/swarm');
+        // Resolve transport. 'auto' prefers federation when the loader is
+        // available AND we have peer addresses; otherwise local.
+        let resolvedKind;
+        let resolvedTransport;
+        let degraded = false;
+        let fallbackReason;
+        if (requestedTransport === 'local') {
+            resolvedKind = 'local';
+            resolvedTransport = new swarm.LocalTransport(opts.nodeId, {
+                defaultTimeoutMs: opts.timeoutMs,
+            });
+        }
+        else {
+            // 'federation' or 'auto' → probe agentic-flow loader.
+            const probe = await this.tryLoadFederationWire(opts);
+            if (probe.wire) {
+                // Build the addressOf map from peers config.
+                const addressMap = new Map();
+                const pubkeyMap = new Map();
+                for (const p of peers) {
+                    if (p.address)
+                        addressMap.set(p.nodeId, p.address);
+                    if (p.publicKeyPem)
+                        pubkeyMap.set(p.nodeId, p.publicKeyPem);
+                }
+                this.wire = probe.wire;
+                resolvedKind = 'federation';
+                resolvedTransport = new swarm.FederationTransport(probe.wire, {
+                    nodeId: opts.nodeId,
+                    addressOf: (id) => addressMap.get(id),
+                    peerIds: () => peers.map(p => p.nodeId),
+                    defaultTimeoutMs: opts.timeoutMs,
+                    resolvePeerPublicKey: pubkeyMap.size > 0 ? (id) => pubkeyMap.get(id) : undefined,
+                });
+            }
+            else {
+                // Couldn't load federation wire. 'federation' requested → degrade
+                // honestly. 'auto' → silently fall back to local.
+                if (requestedTransport === 'federation') {
+                    degraded = true;
+                    fallbackReason = probe.reason ?? 'agentic-flow loader unavailable';
+                }
+                resolvedKind = 'local';
+                resolvedTransport = new swarm.LocalTransport(opts.nodeId, {
+                    defaultTimeoutMs: opts.timeoutMs,
+                });
+            }
+        }
+        // Build the engine with the resolved transport. We pass `transport`
+        // through `config.transport` (typed `unknown` on `ConsensusConfig` in
+        // swarm's types.ts — the engine narrows it via a structural check).
+        const engine = new swarm.ConsensusEngine(opts.nodeId, {
+            algorithm: requestedAlgorithm,
+            threshold: opts.threshold ?? 0.66,
+            timeoutMs: opts.timeoutMs ?? 30_000,
+            maxRounds: 10,
+            requireQuorum: true,
+            transport: resolvedTransport,
+        });
+        await engine.initialize();
+        // Register peers with the consensus engine so its protocol-internal
+        // bookkeeping (Raft's `peers` map, BFT's node set, gossip neighbors)
+        // matches the transport's peer list.
+        for (const p of peers) {
+            if (p.nodeId === opts.nodeId)
+                continue;
+            engine.addNode(p.nodeId);
+        }
+        this.engine = engine;
+        this.transport = resolvedTransport;
+        this.transportKind = resolvedKind;
+        this.nodeId = opts.nodeId;
+        this.algorithm = requestedAlgorithm;
+        this.peers = peers;
+        this.degraded = degraded;
+        this.fallbackReason = fallbackReason;
+        return this.toInitResult();
+    }
+    /**
+     * Probe for the agentic-flow QUIC/WS transport loader. Returns the wire
+     * when loadable; an explanatory reason when not. Never throws — failure
+     * is data, not control flow, so the runtime can degrade cleanly.
+     */
+    async tryLoadFederationWire(_opts) {
+        // agentic-flow is an *optional* peer dep — when it isn't installed,
+        // dynamic import throws and we degrade. The bare-string specifier
+        // is wrapped in a `new Function(...)` so the TS compiler doesn't try
+        // to resolve types at build time (the same pattern the federation
+        // plugin's loader uses, see ADR-120 step 2 comments).
+        const importDynamic = new Function('s', 'return import(s)');
+        let mod;
+        try {
+            mod = await importDynamic('agentic-flow/transport/loader');
+        }
+        catch (err) {
+            return { wire: null, reason: `agentic-flow not installed (${err.message ?? 'unknown'})` };
+        }
+        const m = mod;
+        const fn = typeof m.loadQuicTransport === 'function'
+            ? m.loadQuicTransport
+            : m.default?.loadQuicTransport;
+        if (typeof fn !== 'function') {
+            return { wire: null, reason: 'agentic-flow loader does not expose loadQuicTransport' };
+        }
+        try {
+            const wire = await fn();
+            if (!wire || typeof wire.send !== 'function' || typeof wire.onMessage !== 'function') {
+                return { wire: null, reason: 'agentic-flow loader returned a wire without send/onMessage' };
+            }
+            return { wire };
+        }
+        catch (err) {
+            return { wire: null, reason: `agentic-flow loader threw: ${err.message ?? 'unknown'}` };
+        }
+    }
+    /** Propose a value through the real ConsensusEngine. */
+    async propose(value, proposerId) {
+        if (!this.engine)
+            throw new Error('hive-consensus-runtime: not initialized');
+        return this.engine.propose(value, proposerId ?? this.nodeId ?? 'unknown');
+    }
+    /** Record a vote against an active proposal. */
+    async vote(proposalId, vote) {
+        if (!this.engine)
+            throw new Error('hive-consensus-runtime: not initialized');
+        await this.engine.vote(proposalId, vote);
+    }
+    /**
+     * Block until a proposal resolves (accepted / rejected / expired).
+     * Used by the MCP tool when callers want a synchronous result instead
+     * of polling `proposal-status`.
+     */
+    async awaitConsensus(proposalId) {
+        if (!this.engine)
+            throw new Error('hive-consensus-runtime: not initialized');
+        return this.engine.awaitConsensus(proposalId);
+    }
+    /**
+     * Broadcast a free-form payload to all known peers via the transport.
+     * Gossip-style, no reply expected. Wraps the payload so peers don't
+     * confuse it with protocol messages — `type: 'hive-broadcast'`.
+     */
+    async broadcast(payload, priority = 'normal') {
+        if (!this.transport)
+            throw new Error('hive-consensus-runtime: not initialized');
+        const peers = this.transport.peers();
+        await this.transport.broadcast({
+            type: 'hive-broadcast',
+            payload: { value: payload, priority, sentAt: new Date().toISOString() },
+        });
+        return { delivered: peers.length, transport: this.transportKind };
+    }
+    status() {
+        if (!this.engine || !this.transport) {
+            return {
+                initialized: false,
+                transport: null,
+                degraded: false,
+                peers: [],
+                engine: null,
+            };
+        }
+        return {
+            initialized: true,
+            nodeId: this.nodeId,
+            algorithm: this.algorithm,
+            transport: this.transportKind,
+            degraded: this.degraded,
+            peers: [...this.transport.peers()],
+            engine: this.engine.getStats(),
+        };
+    }
+    async shutdown() {
+        const engine = this.engine;
+        const transport = this.transport;
+        const wire = this.wire;
+        this.engine = null;
+        this.transport = null;
+        this.wire = null;
+        this.transportKind = null;
+        this.nodeId = null;
+        this.peers = [];
+        this.degraded = false;
+        this.fallbackReason = undefined;
+        if (engine) {
+            try {
+                await engine.shutdown();
+            }
+            catch { /* best-effort */ }
+        }
+        if (transport) {
+            try {
+                await transport.close();
+            }
+            catch { /* best-effort */ }
+        }
+        if (wire && typeof wire.close === 'function') {
+            try {
+                await wire.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    /** Test seam: replace the singleton's underlying engine + transport. */
+    __setForTest(engine, transport, nodeId, kind = 'local') {
+        this.engine = engine;
+        this.transport = transport;
+        this.nodeId = nodeId;
+        this.transportKind = kind;
+    }
+    toInitResult() {
+        return {
+            initialized: true,
+            nodeId: this.nodeId,
+            algorithm: this.algorithm,
+            transport: this.transportKind,
+            degraded: this.degraded,
+            fallbackReason: this.fallbackReason,
+            peerCount: this.peers.length,
+            source: 'engine',
+        };
+    }
+}
+/** Process-level singleton — one engine per MCP server. */
+export const hiveConsensusRuntime = new HiveConsensusRuntime();
+//# sourceMappingURL=hive-consensus-runtime.js.map

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

@@ -2,6 +2,13 @@
  * Hive-Mind MCP Tools for CLI
  *
  * Tool definitions for collective intelligence and swarm coordination.
+ *
+ * ADR-095 G2.2 — these tools now delegate inter-node consensus to the real
+ * `@claude-flow/swarm` ConsensusEngine via `hive-consensus-runtime`. The
+ * legacy JSON-state-machine voting (in `hive-mind_consensus`'s 'propose' /
+ * 'vote' / 'status' / 'list' actions) remains as a fallback when the
+ * runtime isn't initialized — preserves backward compatibility for callers
+ * that skip `hive-mind_init` or run in a swarm-less context.
  */
 import { type MCPTool } from './types.js';
 export declare const hiveMindTools: MCPTool[];

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

@@ -2,11 +2,19 @@
  * Hive-Mind MCP Tools for CLI
  *
  * Tool definitions for collective intelligence and swarm coordination.
+ *
+ * ADR-095 G2.2 — these tools now delegate inter-node consensus to the real
+ * `@claude-flow/swarm` ConsensusEngine via `hive-consensus-runtime`. The
+ * legacy JSON-state-machine voting (in `hive-mind_consensus`'s 'propose' /
+ * 'vote' / 'status' / 'list' actions) remains as a fallback when the
+ * runtime isn't initialized — preserves backward compatibility for callers
+ * that skip `hive-mind_init` or run in a swarm-less context.
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText } from './validate-input.js';
+import { hiveConsensusRuntime } from './hive-consensus-runtime.js';
 // Storage paths
 const STORAGE_DIR = '.claude-flow';
 const HIVE_DIR = 'hive-mind';
@@ -227,6 +235,33 @@ export const hiveMindTools = [
                     description: 'Consensus strategy. Default: raft (anti-drift). Use byzantine for f<n/3 fault tolerance.',
                 },
                 queenId: { type: 'string', description: 'Initial queen agent ID' },
+                // ADR-095 G2.2 — pluggable transport for the underlying consensus
+                // engine. 'local' (default) preserves single-process behavior;
+                // 'federation' wires Raft/PBFT/Gossip over ADR-104 WS via
+                // agentic-flow; 'auto' picks federation when reachable + peers
+                // supplied, else local.
+                transport: {
+                    type: 'string',
+                    enum: ['local', 'federation', 'auto'],
+                    description: 'Consensus transport. local=in-process; federation=ADR-104 WS (cross-host); auto=federation if reachable, else local. Default: auto.',
+                },
+                // ADR-095 G2.2 — peers for the consensus engine. When transport is
+                // 'federation' or 'auto', each peer should include a wire address
+                // (e.g. wss://host:8443) and optionally an Ed25519 public key PEM
+                // for inbound signature verification.
+                peers: {
+                    type: 'array',
+                    description: 'Consensus peer list. Each entry: { nodeId, address?, publicKeyPem? }.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            nodeId: { type: 'string' },
+                            address: { type: 'string' },
+                            publicKeyPem: { type: 'string' },
+                        },
+                        required: ['nodeId'],
+                    },
+                },
             },
         },
         handler: async (input) => {
@@ -249,6 +284,39 @@ export const hiveMindTools = [
                 term: 1,
             };
             saveHiveState(state);
+            // ADR-095 G2.2 — bring up the real consensus runtime so subsequent
+            // hive-mind_consensus / hive-mind_broadcast calls go through the
+            // engine + transport instead of the JSON state machine. Done after
+            // saveHiveState so a runtime failure doesn't leave persisted state
+            // inconsistent — we surface the runtime error in the response but
+            // the hive itself stays initialized at the file-state layer.
+            const requestedTransport = input.transport || 'auto';
+            // Map the wider consensus strategy enum to the runtime's algorithm.
+            // 'crdt' and 'quorum' don't have engine implementations; they keep
+            // the legacy state-machine voting and we tag the runtime as 'raft'
+            // (the safe default — quorum semantics are layered on by the
+            // state-machine code in hive-mind_consensus below).
+            const runtimeAlgorithm = requestedConsensus === 'byzantine' ? 'byzantine'
+                : requestedConsensus === 'gossip' ? 'gossip'
+                    : 'raft';
+            const peers = Array.isArray(input.peers)
+                ? input.peers.filter((p) => {
+                    return !!p && typeof p === 'object' && typeof p.nodeId === 'string';
+                })
+                : [];
+            let runtimeResult = null;
+            let runtimeError;
+            try {
+                runtimeResult = await hiveConsensusRuntime.init({
+                    nodeId: queenId,
+                    algorithm: runtimeAlgorithm,
+                    transport: requestedTransport,
+                    peers,
+                });
+            }
+            catch (err) {
+                runtimeError = err instanceof Error ? err.message : String(err);
+            }
             return {
                 success: true,
                 hiveId,
@@ -264,6 +332,22 @@ export const hiveMindTools = [
                     memoryBackend: input.memoryBackend || 'hybrid',
                 },
                 createdAt: state.createdAt,
+                // ADR-095 G2.2 — runtime observability so callers know which
+                // transport / algorithm is actually live.
+                runtime: runtimeResult
+                    ? {
+                        engine: 'enabled',
+                        algorithm: runtimeResult.algorithm,
+                        transport: runtimeResult.transport,
+                        degraded: runtimeResult.degraded,
+                        fallbackReason: runtimeResult.fallbackReason,
+                        peerCount: runtimeResult.peerCount,
+                    }
+                    : {
+                        engine: 'unavailable',
+                        error: runtimeError,
+                        note: 'Consensus engine could not be brought up — legacy state-machine voting will be used for hive-mind_consensus / broadcast.',
+                    },
             };
         },
     },
@@ -442,7 +526,7 @@ export const hiveMindTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['propose', 'vote', 'status', 'list'], description: 'Consensus action' },
+                action: { type: 'string', enum: ['propose', 'vote', 'status', 'list', 'engine-stats'], description: 'Consensus action' },
                 proposalId: { type: 'string', description: 'Proposal ID (for vote/status)' },
                 type: { type: 'string', description: 'Proposal type (for propose)' },
                 value: { description: 'Proposal value (for propose)' },
@@ -452,6 +536,12 @@ export const hiveMindTools = [
                 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)' },
                 timeoutMs: { type: 'number', description: 'Timeout in ms for raft re-proposal (default: 30000)' },
+                // ADR-095 G2.2 — route through the real consensus engine when set.
+                // Default false to preserve backward compatibility for callers that
+                // depend on the JSON-state-machine semantics (BFT detection across
+                // proposals, quorum presets, etc.).
+                useEngine: { type: 'boolean', description: 'Route propose/vote through the real ConsensusEngine (ADR-095 G2.2). Requires hive-mind_init to have brought up the runtime.' },
+                confidence: { type: 'number', description: 'Vote confidence 0-1 (only used when useEngine is true).' },
             },
             required: ['action'],
         },
@@ -475,6 +565,63 @@ export const hiveMindTools = [
             const action = input.action;
             const strategy = input.strategy || 'raft';
             const totalNodes = state.workers.length || 1;
+            // ADR-095 G2.2 — engine-stats surfaces the live runtime state.
+            // Returns a 'not-initialized' shape (not an error) when the runtime
+            // is offline so monitoring tools don't have to special-case startup.
+            if (action === 'engine-stats') {
+                const status = hiveConsensusRuntime.status();
+                return { action, ...status };
+            }
+            // ADR-095 G2.2 — when useEngine is true and the runtime is up,
+            // propose/vote go through the real ConsensusEngine. Falls back to
+            // the JSON-state-machine path below when the runtime isn't
+            // initialized, so callers that don't ask for engine routing get
+            // the legacy behavior.
+            const useEngine = input.useEngine === true && hiveConsensusRuntime.isInitialized();
+            if (useEngine && action === 'propose') {
+                try {
+                    const proposal = await hiveConsensusRuntime.propose(input.value, input.voterId || (state.queen?.agentId ?? 'queen'));
+                    return {
+                        action,
+                        proposalId: proposal.id,
+                        type: input.type || 'general',
+                        strategy: hiveConsensusRuntime.status().algorithm,
+                        status: proposal.status,
+                        term: proposal.term,
+                        engine: 'enabled',
+                        transport: hiveConsensusRuntime.status().transport,
+                    };
+                }
+                catch (err) {
+                    return { action, error: `consensus engine propose failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            if (useEngine && action === 'vote') {
+                const voterId = input.voterId;
+                if (!voterId)
+                    return { action, error: 'voterId is required for voting' };
+                if (!input.proposalId)
+                    return { action, error: 'proposalId is required for voting' };
+                try {
+                    await hiveConsensusRuntime.vote(input.proposalId, {
+                        voterId,
+                        approve: input.vote,
+                        confidence: typeof input.confidence === 'number' ? input.confidence : 1.0,
+                        timestamp: new Date(),
+                    });
+                    return {
+                        action,
+                        proposalId: input.proposalId,
+                        voterId,
+                        vote: input.vote,
+                        engine: 'enabled',
+                        transport: hiveConsensusRuntime.status().transport,
+                    };
+                }
+                catch (err) {
+                    return { action, error: `consensus engine vote failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
             if (action === 'propose') {
                 const proposalId = `proposal-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
                 const quorumPreset = input.quorumPreset || 'majority';
@@ -750,24 +897,46 @@ export const hiveMindTools = [
                     return { success: false, error: v.error };
             }
             const messageId = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-            // Store in shared memory
+            const priority = input.priority || 'normal';
+            // Store in shared memory (always — this is the durable record).
             const messages = state.sharedMemory.broadcasts || [];
             messages.push({
                 messageId,
                 message: input.message,
-                priority: input.priority || 'normal',
+                priority,
                 fromId: input.fromId || 'system',
                 timestamp: new Date().toISOString(),
             });
             // Keep only last 100 broadcasts
             state.sharedMemory.broadcasts = messages.slice(-100);
             saveHiveState(state);
+            // ADR-095 G2.2 — when the consensus runtime is up, also push the
+            // broadcast over its transport so cross-process / cross-host
+            // peers actually receive it. Local-only runtimes still benefit
+            // (in-process peers get a real handler invocation).
+            let transportDelivered;
+            let transportKind;
+            let transportError;
+            if (hiveConsensusRuntime.isInitialized()) {
+                try {
+                    const res = await hiveConsensusRuntime.broadcast({ messageId, message: input.message, fromId: input.fromId || 'system' }, priority);
+                    transportDelivered = res.delivered;
+                    transportKind = res.transport;
+                }
+                catch (err) {
+                    transportError = err instanceof Error ? err.message : String(err);
+                }
+            }
             return {
                 success: true,
                 messageId,
                 recipients: state.workers.length,
-                priority: input.priority || 'normal',
+                priority,
                 broadcastAt: new Date().toISOString(),
+                transport: transportKind
+                    ? { kind: transportKind, delivered: transportDelivered }
+                    : { kind: 'state-machine-only', note: 'runtime offline — broadcast persisted to sharedMemory only' },
+                ...(transportError ? { transportError } : {}),
             };
         },
     },
@@ -818,6 +987,17 @@ export const hiveMindTools = [
             // Keep history for reference
             state.sharedMemory = {};
             saveHiveState(state);
+            // ADR-095 G2.2 — tear down the consensus runtime alongside the
+            // file-state. Best-effort: a runtime that's already offline is
+            // not an error.
+            let runtimeShutdown = false;
+            try {
+                if (hiveConsensusRuntime.isInitialized()) {
+                    await hiveConsensusRuntime.shutdown();
+                    runtimeShutdown = true;
+                }
+            }
+            catch { /* best-effort */ }
             return {
                 success: true,
                 shutdownAt: shutdownTime,
@@ -825,6 +1005,7 @@ export const hiveMindTools = [
                 workersTerminated: workerCount,
                 previousQueen,
                 consensusCleared: pendingConsensus,
+                runtimeShutdown,
                 message: `Hive-mind shutdown complete. ${workerCount} workers terminated.`,
             };
         },

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.7.0-alpha.44",
+  "version": "3.7.0-alpha.45",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -105,7 +105,8 @@
     "yaml": "^2.8.0",
     "@claude-flow/memory": "^3.0.0-alpha.17",
     "@claude-flow/embeddings": "^3.0.0-alpha.18",
-    "@claude-flow/security": "^3.0.0-alpha.8"
+    "@claude-flow/security": "^3.0.0-alpha.8",
+    "@claude-flow/swarm": "^3.0.0-alpha.8"
   },
   "optionalDependencies": {
     "@claude-flow/aidefence": "^3.0.2",