@claude-flow/cli 3.39.2 → 3.40.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.39.2",
+    "version": "3.40.0",
     "files": {
       "auto-memory-hook.mjs": "85fe05c757421c52137c0bc8545a0896bab6b4714538c2a11d1d0835bfcc8c1c",
       "hook-handler.cjs": "209d9fafe10e17d1be0866727f6f9cf9ac66f9a0793f1c793a4f58319e8e4583",
@@ -8,6 +8,6 @@
       "statusline.cjs": "4a48353b4f1566fa4379b00fd0321b6676a22b6cc91fbbd8380ac5183d619468"
     }
   },
-  "signature": "k7dMs07mB2+Adq7BXfz0YD7oLqfFaFIptNwCrAzvwFlphXj9BYWLEDj55lNTnVxnhK+WsDU85A5e2OR7f4xkAQ==",
+  "signature": "faVaRzF1tnQZD/Yu/Tze+7hSyjEhSgbJ2GkqBtF1wsmRuUgZKsAcKJ70E5Je+Am5UH32ZEj3mfMmqwNlsAlACg==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "generation": 6,
-  "generatedAt": "2026-09-09T13:30:27.887Z",
-  "gitSha": "498a2387",
+  "generatedAt": "2026-09-09T23:09:38.206Z",
+  "gitSha": "e111bfbd",
   "catalog": {
     "agents": 167,
-    "tools": 397,
+    "tools": 402,
     "skills": 34
   },
   "benchmark": null

package/dist/src/commands/memory.js

@@ -352,7 +352,14 @@ const searchCommand = {
             name: 'threshold',
             description: 'Similarity threshold (0-1)',
             type: 'number',
-            default: 0.7
+            // MUST stay <= 0.4. The recall fusion in bridgeSearchEntries scores a
+            // full-coverage exact-keyword hit as 0.6*max(0,semantic) + 0.4*lexical,
+            // so when the semantic cosine is <= 0 (routine for a one-word query) a
+            // perfect keyword match tops out at exactly 0.40. #2790 raised this
+            // default to 0.7, which silently re-broke #2558: `memory search` matched
+            // content word-for-word and still returned nothing. Regression guard:
+            // __tests__/memory-search-recall-2558.test.ts.
+            default: 0.3
         },
         {
             name: 'type',
@@ -421,7 +428,7 @@ const searchCommand = {
         // coalescing preserves an explicit zero. Fallback aligned with the
         // option's declared `default: 0.7` (was `0.3` — the two disagreed
         // and --help advertised a default the code did not honor).
-        const threshold = ctx.flags.threshold ?? 0.7;
+        const threshold = ctx.flags.threshold ?? 0.3;
         const searchType = ctx.flags.type || 'semantic';
         const buildHnsw = (ctx.flags['build-hnsw'] || ctx.flags.buildHnsw);
         const requestedIntent = ctx.flags.intent || 'mixed';

package/dist/src/log-filters.d.ts

@@ -40,7 +40,7 @@ declare const STDERR_REDIRECT_PREFIXES: string[];
 declare const AGENTDB_MOCK_FALLBACK_DROP_PREFIXES: string[];
 declare const shouldRedirectToStderr: (msg: unknown) => boolean;
 declare const isAgentdbMockFallbackNoise: (msg: unknown) => boolean;
-declare const origWarn: (...data: any[]) => void;
-declare const origLog: (...data: any[]) => void;
-declare const origError: (...data: any[]) => void;
+declare const origWarn: (message?: any, ...optionalParams: any[]) => void;
+declare const origLog: (message?: any, ...optionalParams: any[]) => void;
+declare const origError: (message?: any, ...optionalParams: any[]) => void;
 //# sourceMappingURL=log-filters.d.ts.map

package/dist/src/mcp-tools/agentbbs-federation.d.ts

@@ -0,0 +1,178 @@
+/**
+ * agentbbs Phase 2 — cross-host federation.
+ *
+ * Phase 1 (`agentbbs-tools.ts`) gives every host an append-only room log at
+ * `<basePath>/room-<roomId>.jsonl`, and derives `roomId` deterministically from
+ * the room label. Two independent hosts that register `#sales` therefore
+ * compute the *same* roomId without ever talking to each other. That is the
+ * property this module builds on.
+ *
+ * ## Why a signed union-merge, and not a consensus protocol
+ *
+ * A room log is an append-only set of immutable envelopes. Two hosts that each
+ * append locally hold two subsets of the same logical set, so reconciling them
+ * is a set union — there is no conflicting write to arbitrate, and therefore
+ * nothing for a consensus round to decide. Union is commutative, associative
+ * and idempotent, which makes sync order-independent and safe to retry: pulling
+ * the same peer twice, or pulling A-then-B versus B-then-A, converges on the
+ * same log. That is a CRDT (a grow-only set keyed by `envelopeId`), and it is
+ * strictly cheaper and less failure-prone than the Byzantine agreement the
+ * plugin README gestures at.
+ *
+ * What union does *not* give you is authenticity. If any peer can inject an
+ * envelope, the merge faithfully replicates forgeries. So every envelope is
+ * Ed25519-signed by its originating node, and a receiver verifies the signature
+ * against the *pinned* public key it recorded when the peer was added — not
+ * against a key carried in the envelope, which would let an attacker sign with
+ * their own key and claim any origin. Trust is pinned at peer-add time; the
+ * wire is treated as hostile.
+ *
+ * ## Transport
+ *
+ * Pull-based HTTP. A node serves `GET /agentbbs/v1/rooms/:roomId/envelopes?since=N`
+ * and peers poll it. Pull is deliberate: it needs no inbound connectivity from
+ * the peer's side, survives a node being offline (it just catches up later),
+ * and gives the *receiver* control over how much it ingests. Push would invert
+ * that and make every node an unauthenticated write target.
+ *
+ * Designed for a private overlay (Tailscale/WireGuard) where the network
+ * already authenticates the host. Signatures mean a compromised or hostile peer
+ * still cannot forge another node's envelopes. See `bindHost` on serve() — it
+ * binds loopback by default, and binding a routable interface is an explicit
+ * operator choice.
+ *
+ * ## Bounds
+ *
+ * Every ingest path is bounded: envelope count per sync, byte size per envelope,
+ * total bytes per response, peer count, and hop count. An unbounded merge from
+ * an untrusted peer is a memory-exhaustion primitive, so limits are enforced on
+ * the *receiving* side where they cannot be negotiated away by the sender.
+ *
+ * @module @claude-flow/cli/mcp-tools/agentbbs-federation
+ */
+import { type Server } from 'node:http';
+/** Max envelopes accepted from one peer in one sync. */
+export declare const MAX_ENVELOPES_PER_SYNC = 5000;
+/** Max serialized bytes for a single envelope. */
+export declare const MAX_ENVELOPE_BYTES: number;
+/** Max total bytes read from one peer response. */
+export declare const MAX_SYNC_RESPONSE_BYTES: number;
+/** Max peers in the registry. */
+export declare const MAX_PEERS = 256;
+/** Max federation hops before an envelope stops propagating. */
+export declare const MAX_HOPS = 8;
+/** Per-request timeout when pulling from a peer. */
+export declare const SYNC_TIMEOUT_MS = 15000;
+export interface NodeIdentity {
+    nodeId: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: string;
+}
+export interface FederationPeer {
+    nodeId: string;
+    url: string;
+    publicKey: string;
+    label?: string;
+    addedAt: string;
+    lastSyncedAt?: string;
+    lastSeq?: Record<string, number>;
+}
+export interface SignedEnvelope {
+    envelopeId: string;
+    roomId: string;
+    seq: number;
+    msgType: string;
+    payload: unknown;
+    timestamp: string;
+    origin?: string;
+    hops?: number;
+    signature?: string;
+}
+/**
+ * Deterministic byte string an envelope's signature covers.
+ *
+ * Field order is fixed here rather than relying on `JSON.stringify` key order,
+ * because a receiver must reconstruct byte-identical input from a payload that
+ * survived a JSON round trip. `payload` is canonicalized recursively with
+ * sorted keys for the same reason: `{a:1,b:2}` and `{b:2,a:1}` are the same
+ * value and must not produce different signatures.
+ *
+ * `hops` is deliberately excluded — it is mutated in transit by design, so
+ * including it would invalidate the signature at the first relay.
+ */
+export declare function canonicalEnvelopeBytes(env: SignedEnvelope): Uint8Array;
+/**
+ * Load or create this host's long-lived Ed25519 identity.
+ *
+ * Phase 1 minted an ephemeral key per process, which is fine for local token
+ * signing but useless across hosts: a peer cannot pin a key that changes on
+ * every restart. This persists one, 0600, and derives a stable nodeId from the
+ * public key so identity is verifiable rather than self-asserted.
+ */
+export declare function getNodeIdentity(basePath: string): Promise<NodeIdentity>;
+export declare function signEnvelope(basePath: string, env: SignedEnvelope): Promise<SignedEnvelope>;
+/**
+ * Verify an envelope against a public key the caller already trusts.
+ *
+ * The key is passed in rather than read from the envelope on purpose: an
+ * envelope-carried key proves only that the sender holds *a* key, not that they
+ * are who the `origin` field claims. Callers pass the key pinned at peer-add.
+ */
+export declare function verifyEnvelope(env: SignedEnvelope, publicKeyHex: string): Promise<boolean>;
+export declare function readPeers(basePath: string): FederationPeer[];
+/**
+ * Reject anything that is not a plain http(s) URL to a host.
+ *
+ * Blocks credentials-in-URL (they would be logged), and non-http schemes such
+ * as `file:` which would turn a peer entry into a local file read.
+ */
+export declare function validatePeerUrl(raw: string): string;
+export declare function addPeer(basePath: string, input: {
+    nodeId: string;
+    url: string;
+    publicKey: string;
+    label?: string;
+}): FederationPeer;
+export declare function removePeer(basePath: string, nodeId: string): boolean;
+export declare function readEnvelopes(basePath: string, roomId: string): SignedEnvelope[];
+export declare function validateRoomId(roomId: string): string;
+export interface MergeResult {
+    merged: number;
+    skippedDuplicate: number;
+    skippedUnverified: number;
+    skippedOversize: number;
+    skippedHopLimit: number;
+}
+/**
+ * Union-merge verified envelopes from a peer into the local room log.
+ *
+ * Idempotent: `envelopeId` is the merge key, so replaying the same batch is a
+ * no-op. Anything that fails verification is dropped and counted rather than
+ * quarantined — a receiver has no use for an envelope it cannot attribute.
+ */
+export declare function mergeEnvelopes(basePath: string, roomId: string, incoming: SignedEnvelope[], peerPublicKey: string): Promise<MergeResult>;
+/** Pull one room from one peer and merge what verifies. */
+export declare function syncRoomFromPeer(basePath: string, peer: FederationPeer, roomId: string, fetchImpl?: typeof fetch): Promise<MergeResult & {
+    peerNodeId: string;
+    roomId: string;
+}>;
+/**
+ * Serve this node's room logs for peers to pull.
+ *
+ * Binds loopback unless the caller explicitly asks otherwise, so starting a
+ * server never silently exposes room contents on a routable interface. Read
+ * only by construction: there is no route that mutates state, which removes the
+ * whole class of unauthenticated-write attacks that a push design would open.
+ */
+export declare function serveFederation(basePath: string, opts?: {
+    port?: number;
+    bindHost?: string;
+}): Promise<{
+    server: Server;
+    port: number;
+    host: string;
+}>;
+/** Constant-time compare for any future shared-secret paths. */
+export declare function safeEqual(a: string, b: string): boolean;
+//# sourceMappingURL=agentbbs-federation.d.ts.map

package/dist/src/mcp-tools/agentbbs-federation.js

@@ -0,0 +1,447 @@
+/**
+ * agentbbs Phase 2 — cross-host federation.
+ *
+ * Phase 1 (`agentbbs-tools.ts`) gives every host an append-only room log at
+ * `<basePath>/room-<roomId>.jsonl`, and derives `roomId` deterministically from
+ * the room label. Two independent hosts that register `#sales` therefore
+ * compute the *same* roomId without ever talking to each other. That is the
+ * property this module builds on.
+ *
+ * ## Why a signed union-merge, and not a consensus protocol
+ *
+ * A room log is an append-only set of immutable envelopes. Two hosts that each
+ * append locally hold two subsets of the same logical set, so reconciling them
+ * is a set union — there is no conflicting write to arbitrate, and therefore
+ * nothing for a consensus round to decide. Union is commutative, associative
+ * and idempotent, which makes sync order-independent and safe to retry: pulling
+ * the same peer twice, or pulling A-then-B versus B-then-A, converges on the
+ * same log. That is a CRDT (a grow-only set keyed by `envelopeId`), and it is
+ * strictly cheaper and less failure-prone than the Byzantine agreement the
+ * plugin README gestures at.
+ *
+ * What union does *not* give you is authenticity. If any peer can inject an
+ * envelope, the merge faithfully replicates forgeries. So every envelope is
+ * Ed25519-signed by its originating node, and a receiver verifies the signature
+ * against the *pinned* public key it recorded when the peer was added — not
+ * against a key carried in the envelope, which would let an attacker sign with
+ * their own key and claim any origin. Trust is pinned at peer-add time; the
+ * wire is treated as hostile.
+ *
+ * ## Transport
+ *
+ * Pull-based HTTP. A node serves `GET /agentbbs/v1/rooms/:roomId/envelopes?since=N`
+ * and peers poll it. Pull is deliberate: it needs no inbound connectivity from
+ * the peer's side, survives a node being offline (it just catches up later),
+ * and gives the *receiver* control over how much it ingests. Push would invert
+ * that and make every node an unauthenticated write target.
+ *
+ * Designed for a private overlay (Tailscale/WireGuard) where the network
+ * already authenticates the host. Signatures mean a compromised or hostile peer
+ * still cannot forge another node's envelopes. See `bindHost` on serve() — it
+ * binds loopback by default, and binding a routable interface is an explicit
+ * operator choice.
+ *
+ * ## Bounds
+ *
+ * Every ingest path is bounded: envelope count per sync, byte size per envelope,
+ * total bytes per response, peer count, and hop count. An unbounded merge from
+ * an untrusted peer is a memory-exhaustion primitive, so limits are enforced on
+ * the *receiving* side where they cannot be negotiated away by the sender.
+ *
+ * @module @claude-flow/cli/mcp-tools/agentbbs-federation
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+/** Max envelopes accepted from one peer in one sync. */
+export const MAX_ENVELOPES_PER_SYNC = 5_000;
+/** Max serialized bytes for a single envelope. */
+export const MAX_ENVELOPE_BYTES = 64 * 1024;
+/** Max total bytes read from one peer response. */
+export const MAX_SYNC_RESPONSE_BYTES = 16 * 1024 * 1024;
+/** Max peers in the registry. */
+export const MAX_PEERS = 256;
+/** Max federation hops before an envelope stops propagating. */
+export const MAX_HOPS = 8;
+/** Per-request timeout when pulling from a peer. */
+export const SYNC_TIMEOUT_MS = 15_000;
+const ROOM_ID_RE = /^[A-Za-z0-9_.\-:/@#]+$/;
+const NODE_ID_RE = /^[0-9a-f]{16}$/;
+const HEX64_RE = /^[0-9a-f]{64}$/;
+let _edMod = null;
+async function loadEd25519() {
+    if (!_edMod)
+        _edMod = await import('@noble/ed25519');
+    return _edMod;
+}
+function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+function hex(buf) {
+    return Buffer.from(buf).toString('hex');
+}
+function unhex(s) {
+    return new Uint8Array(Buffer.from(s, 'hex'));
+}
+/**
+ * Deterministic byte string an envelope's signature covers.
+ *
+ * Field order is fixed here rather than relying on `JSON.stringify` key order,
+ * because a receiver must reconstruct byte-identical input from a payload that
+ * survived a JSON round trip. `payload` is canonicalized recursively with
+ * sorted keys for the same reason: `{a:1,b:2}` and `{b:2,a:1}` are the same
+ * value and must not produce different signatures.
+ *
+ * `hops` is deliberately excluded — it is mutated in transit by design, so
+ * including it would invalidate the signature at the first relay.
+ */
+export function canonicalEnvelopeBytes(env) {
+    const canon = (v) => {
+        if (v === null || typeof v !== 'object')
+            return v;
+        if (Array.isArray(v))
+            return v.map(canon);
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            out[k] = canon(v[k]);
+        }
+        return out;
+    };
+    const material = JSON.stringify({
+        envelopeId: env.envelopeId,
+        roomId: env.roomId,
+        seq: env.seq,
+        msgType: env.msgType,
+        timestamp: env.timestamp,
+        origin: env.origin ?? '',
+        payload: canon(env.payload),
+    });
+    return new TextEncoder().encode(material);
+}
+function identityPath(basePath) {
+    return join(basePath, 'node-identity.json');
+}
+function peersPath(basePath) {
+    return join(basePath, 'peers.json');
+}
+function roomLogPath(basePath, roomId) {
+    return join(basePath, `room-${roomId}.jsonl`);
+}
+/**
+ * Load or create this host's long-lived Ed25519 identity.
+ *
+ * Phase 1 minted an ephemeral key per process, which is fine for local token
+ * signing but useless across hosts: a peer cannot pin a key that changes on
+ * every restart. This persists one, 0600, and derives a stable nodeId from the
+ * public key so identity is verifiable rather than self-asserted.
+ */
+export async function getNodeIdentity(basePath) {
+    ensureDir(basePath);
+    const p = identityPath(basePath);
+    if (existsSync(p)) {
+        const parsed = JSON.parse(readFileSync(p, 'utf-8'));
+        if (!NODE_ID_RE.test(parsed.nodeId ?? '') || !HEX64_RE.test(parsed.publicKey ?? '')) {
+            throw new Error('node-identity.json is malformed');
+        }
+        return parsed;
+    }
+    const ed = await loadEd25519();
+    const priv = ed.utils?.randomPrivateKey ? ed.utils.randomPrivateKey() : new Uint8Array(randomBytes(32));
+    const pub = await (ed.getPublicKeyAsync ?? ed.getPublicKey)(priv);
+    const publicKey = hex(pub);
+    const identity = {
+        nodeId: createHash('sha256').update(`agentbbs:node:${publicKey}`).digest('hex').slice(0, 16),
+        publicKey,
+        privateKey: hex(priv),
+        createdAt: new Date().toISOString(),
+    };
+    writeFileSync(p, JSON.stringify(identity, null, 2) + '\n', { mode: 0o600 });
+    try {
+        chmodSync(p, 0o600);
+    }
+    catch { /* best effort on filesystems without modes */ }
+    return identity;
+}
+export async function signEnvelope(basePath, env) {
+    const id = await getNodeIdentity(basePath);
+    const ed = await loadEd25519();
+    const withOrigin = { ...env, origin: id.nodeId, hops: env.hops ?? 0 };
+    const sig = await (ed.signAsync ?? ed.sign)(canonicalEnvelopeBytes(withOrigin), unhex(id.privateKey));
+    return { ...withOrigin, signature: hex(sig) };
+}
+/**
+ * Verify an envelope against a public key the caller already trusts.
+ *
+ * The key is passed in rather than read from the envelope on purpose: an
+ * envelope-carried key proves only that the sender holds *a* key, not that they
+ * are who the `origin` field claims. Callers pass the key pinned at peer-add.
+ */
+export async function verifyEnvelope(env, publicKeyHex) {
+    if (!env.signature || !HEX64_RE.test(publicKeyHex))
+        return false;
+    if (!/^[0-9a-f]{128}$/.test(env.signature))
+        return false;
+    try {
+        const ed = await loadEd25519();
+        return await (ed.verifyAsync ?? ed.verify)(unhex(env.signature), canonicalEnvelopeBytes(env), unhex(publicKeyHex));
+    }
+    catch {
+        return false;
+    }
+}
+export function readPeers(basePath) {
+    const p = peersPath(basePath);
+    if (!existsSync(p))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf-8'));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writePeers(basePath, peers) {
+    ensureDir(basePath);
+    writeFileSync(peersPath(basePath), JSON.stringify(peers, null, 2) + '\n');
+}
+/**
+ * Reject anything that is not a plain http(s) URL to a host.
+ *
+ * Blocks credentials-in-URL (they would be logged), and non-http schemes such
+ * as `file:` which would turn a peer entry into a local file read.
+ */
+export function validatePeerUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new Error('peer url is not a valid URL');
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+        throw new Error('peer url must be http or https');
+    }
+    if (u.username || u.password)
+        throw new Error('peer url must not embed credentials');
+    return u.origin;
+}
+export function addPeer(basePath, input) {
+    if (!NODE_ID_RE.test(input.nodeId ?? ''))
+        throw new Error('nodeId must be 16 lowercase hex chars');
+    if (!HEX64_RE.test(input.publicKey ?? ''))
+        throw new Error('publicKey must be 64 lowercase hex chars');
+    const url = validatePeerUrl(String(input.url));
+    const peers = readPeers(basePath);
+    if (peers.length >= MAX_PEERS)
+        throw new Error(`peer registry is full (${MAX_PEERS})`);
+    const existing = peers.find(p => p.nodeId === input.nodeId);
+    if (existing) {
+        // Re-pinning a different key for a known nodeId is how a key-substitution
+        // attack would present. Require an explicit remove first.
+        if (existing.publicKey !== input.publicKey) {
+            throw new Error(`nodeId ${input.nodeId} is already pinned to a different publicKey; remove it first`);
+        }
+        existing.url = url;
+        if (input.label)
+            existing.label = input.label;
+        writePeers(basePath, peers);
+        return existing;
+    }
+    const peer = {
+        nodeId: input.nodeId,
+        url,
+        publicKey: input.publicKey,
+        label: input.label,
+        addedAt: new Date().toISOString(),
+        lastSeq: {},
+    };
+    peers.push(peer);
+    writePeers(basePath, peers);
+    return peer;
+}
+export function removePeer(basePath, nodeId) {
+    const peers = readPeers(basePath);
+    const next = peers.filter(p => p.nodeId !== nodeId);
+    if (next.length === peers.length)
+        return false;
+    writePeers(basePath, next);
+    return true;
+}
+export function readEnvelopes(basePath, roomId) {
+    const p = roomLogPath(basePath, roomId);
+    if (!existsSync(p))
+        return [];
+    const out = [];
+    for (const line of readFileSync(p, 'utf-8').split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip malformed */ }
+    }
+    return out;
+}
+export function validateRoomId(roomId) {
+    if (!roomId || typeof roomId !== 'string')
+        throw new Error('roomId is required');
+    if (roomId.length > 128)
+        throw new Error('roomId exceeds 128 chars');
+    // Also blocks path traversal: `.` is allowed but `/` segments cannot form
+    // `..` without tripping the explicit check below.
+    if (!ROOM_ID_RE.test(roomId))
+        throw new Error('roomId has invalid characters');
+    if (roomId.includes('..'))
+        throw new Error('roomId must not contain ..');
+    return roomId;
+}
+/**
+ * Union-merge verified envelopes from a peer into the local room log.
+ *
+ * Idempotent: `envelopeId` is the merge key, so replaying the same batch is a
+ * no-op. Anything that fails verification is dropped and counted rather than
+ * quarantined — a receiver has no use for an envelope it cannot attribute.
+ */
+export async function mergeEnvelopes(basePath, roomId, incoming, peerPublicKey) {
+    validateRoomId(roomId);
+    ensureDir(basePath);
+    const result = {
+        merged: 0, skippedDuplicate: 0, skippedUnverified: 0, skippedOversize: 0, skippedHopLimit: 0,
+    };
+    const existing = readEnvelopes(basePath, roomId);
+    const seen = new Set(existing.map(e => e.envelopeId));
+    const logPath = roomLogPath(basePath, roomId);
+    const batch = incoming.slice(0, MAX_ENVELOPES_PER_SYNC);
+    for (const env of batch) {
+        if (!env || typeof env !== 'object' || typeof env.envelopeId !== 'string') {
+            result.skippedUnverified++;
+            continue;
+        }
+        if (env.roomId !== roomId) {
+            result.skippedUnverified++;
+            continue;
+        }
+        if (seen.has(env.envelopeId)) {
+            result.skippedDuplicate++;
+            continue;
+        }
+        if (JSON.stringify(env).length > MAX_ENVELOPE_BYTES) {
+            result.skippedOversize++;
+            continue;
+        }
+        if ((env.hops ?? 0) >= MAX_HOPS) {
+            result.skippedHopLimit++;
+            continue;
+        }
+        if (!(await verifyEnvelope(env, peerPublicKey))) {
+            result.skippedUnverified++;
+            continue;
+        }
+        appendFileSync(logPath, JSON.stringify({ ...env, hops: (env.hops ?? 0) + 1 }) + '\n');
+        seen.add(env.envelopeId);
+        result.merged++;
+    }
+    return result;
+}
+/** Pull one room from one peer and merge what verifies. */
+export async function syncRoomFromPeer(basePath, peer, roomId, fetchImpl = fetch) {
+    validateRoomId(roomId);
+    const since = peer.lastSeq?.[roomId] ?? 0;
+    const url = `${peer.url}/agentbbs/v1/rooms/${encodeURIComponent(roomId)}/envelopes?since=${since}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SYNC_TIMEOUT_MS);
+    let body;
+    try {
+        const res = await fetchImpl(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+        if (!res.ok)
+            throw new Error(`peer ${peer.nodeId} returned ${res.status}`);
+        const text = await res.text();
+        if (text.length > MAX_SYNC_RESPONSE_BYTES)
+            throw new Error(`peer ${peer.nodeId} response exceeds size cap`);
+        body = JSON.parse(text);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const envelopes = Array.isArray(body?.envelopes) ? body.envelopes : [];
+    const merged = await mergeEnvelopes(basePath, roomId, envelopes, peer.publicKey);
+    const peers = readPeers(basePath);
+    const rec = peers.find(p => p.nodeId === peer.nodeId);
+    if (rec) {
+        rec.lastSyncedAt = new Date().toISOString();
+        rec.lastSeq = rec.lastSeq ?? {};
+        const maxSeq = envelopes.reduce((m, e) => Math.max(m, Number(e.seq) || 0), since);
+        rec.lastSeq[roomId] = maxSeq;
+        writePeers(basePath, peers);
+    }
+    return { ...merged, peerNodeId: peer.nodeId, roomId };
+}
+/**
+ * Serve this node's room logs for peers to pull.
+ *
+ * Binds loopback unless the caller explicitly asks otherwise, so starting a
+ * server never silently exposes room contents on a routable interface. Read
+ * only by construction: there is no route that mutates state, which removes the
+ * whole class of unauthenticated-write attacks that a push design would open.
+ */
+export function serveFederation(basePath, opts = {}) {
+    const host = opts.bindHost ?? '127.0.0.1';
+    const server = createServer((req, res) => {
+        const send = (code, obj) => {
+            const buf = Buffer.from(JSON.stringify(obj));
+            res.writeHead(code, { 'content-type': 'application/json', 'content-length': buf.length });
+            res.end(buf);
+        };
+        try {
+            if (req.method !== 'GET')
+                return send(405, { error: 'method-not-allowed' });
+            const u = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+            if (u.pathname === '/agentbbs/v1/identity') {
+                const p = identityPath(basePath);
+                if (!existsSync(p))
+                    return send(404, { error: 'no-identity' });
+                const id = JSON.parse(readFileSync(p, 'utf-8'));
+                // Never serve privateKey.
+                return send(200, { nodeId: id.nodeId, publicKey: id.publicKey, createdAt: id.createdAt });
+            }
+            const m = u.pathname.match(/^\/agentbbs\/v1\/rooms\/([^/]+)\/envelopes$/);
+            if (m) {
+                let roomId;
+                try {
+                    roomId = validateRoomId(decodeURIComponent(m[1]));
+                }
+                catch (e) {
+                    return send(400, { error: e.message });
+                }
+                const since = Math.max(0, Math.trunc(Number(u.searchParams.get('since') ?? 0)) || 0);
+                const all = readEnvelopes(basePath, roomId);
+                const out = all.filter(e => (Number(e.seq) || 0) > since).slice(0, MAX_ENVELOPES_PER_SYNC);
+                return send(200, { roomId, since, count: out.length, envelopes: out });
+            }
+            return send(404, { error: 'not-found' });
+        }
+        catch (e) {
+            return send(500, { error: 'internal' });
+        }
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port ?? 0, host, () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            resolve({ server, port, host });
+        });
+    });
+}
+/** Constant-time compare for any future shared-secret paths. */
+export function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+//# sourceMappingURL=agentbbs-federation.js.map

package/dist/src/mcp-tools/agentbbs-tools.d.ts

@@ -21,6 +21,17 @@
  *     so callers see one contract regardless of install state
  *   - Phase 1: polling-based watch (streaming subscriptions are Phase 4)
  *
+ * Presence check: the published `agentbbs` package (as of 0.2.1) is a CLI-only
+ * launcher — a `bin` script with no importable JS entry point (no `main` /
+ * `exports` field) — that downloads/builds a Rust binary and shells out to it.
+ * `await import('agentbbs')` can therefore never resolve, even when the CLI is
+ * correctly installed and on PATH: there is no module for Node to find. This
+ * previously made every tool report `degraded: true` unconditionally,
+ * regardless of install state. Detect real availability instead by probing the
+ * CLI itself, matching how the rest of this codebase treats optional
+ * command-line tools (`shutil.which()`-style guards) rather than assuming a
+ * package shape the dependency doesn't have.
+ *
  * @module @claude-flow/cli/mcp-tools/agentbbs
  */
 import type { MCPTool } from './types.js';

package/dist/src/mcp-tools/agentbbs-tools.js

@@ -21,33 +21,51 @@
  *     so callers see one contract regardless of install state
  *   - Phase 1: polling-based watch (streaming subscriptions are Phase 4)
  *
+ * Presence check: the published `agentbbs` package (as of 0.2.1) is a CLI-only
+ * launcher — a `bin` script with no importable JS entry point (no `main` /
+ * `exports` field) — that downloads/builds a Rust binary and shells out to it.
+ * `await import('agentbbs')` can therefore never resolve, even when the CLI is
+ * correctly installed and on PATH: there is no module for Node to find. This
+ * previously made every tool report `degraded: true` unconditionally,
+ * regardless of install state. Detect real availability instead by probing the
+ * CLI itself, matching how the rest of this codebase treats optional
+ * command-line tools (`shutil.which()`-style guards) rather than assuming a
+ * package shape the dependency doesn't have.
+ *
  * @module @claude-flow/cli/mcp-tools/agentbbs
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
 import { resolve, isAbsolute, join } from 'node:path';
 import { randomBytes, createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { getNodeIdentity, signEnvelope, addPeer, removePeer, readPeers, syncRoomFromPeer, serveFederation, validateRoomId as fedValidateRoomId, MAX_PEERS, MAX_HOPS, } from './agentbbs-federation.js';
 import { getProjectCwd } from './types.js';
-const PACKAGE_NAME = 'agentbbs';
-// Cache: amortize dynamic-import cost across handler calls.
-// null = not yet attempted; false = unavailable; module = loaded.
-let _agentbbsMod = null;
-let _loadAttempted = false;
-async function loadAgentbbs() {
-    if (_loadAttempted)
-        return _agentbbsMod || null;
-    _loadAttempted = true;
+const CLI_NAME = 'agentbbs';
+// Cache: amortize the subprocess probe cost across handler calls within a
+// process. null = not yet probed; boolean = probe result.
+let _cliAvailable = null;
+function agentbbsCliAvailable() {
+    if (_cliAvailable !== null)
+        return _cliAvailable;
+    const bin = process.env.AGENTBBS_BIN || CLI_NAME;
     try {
-        _agentbbsMod = await import(PACKAGE_NAME);
-        return _agentbbsMod;
+        // On Windows npm's global-install shim is `agentbbs.cmd`, and
+        // child_process cannot spawn a .cmd without going through cmd.exe, which
+        // is what resolves the PATHEXT extension. POSIX keeps shell:false so the
+        // AGENTBBS_BIN override is never shell-interpreted — same convention as
+        // browser-tools.ts and commands/init.ts.
+        execFileSync(bin, ['--version'], {
+            stdio: 'ignore',
+            timeout: 5000,
+            shell: process.platform === 'win32',
+            windowsHide: true,
+        });
+        _cliAvailable = true;
     }
-    catch (err) {
-        if (err && (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND' ||
-            /Cannot find (module|package)/i.test(String(err?.message)))) {
-            _agentbbsMod = false;
-            return null;
-        }
-        throw err;
+    catch {
+        _cliAvailable = false;
     }
+    return _cliAvailable;
 }
 function degradedResult(reason) {
     return { success: true, degraded: true, reason };
@@ -128,12 +146,22 @@ function nextSeq(path) {
  * agentbbs server's responsibility (nonce JTI tracking, per ADR-164 §3.2.4).
  * Phase 2+ will wire this to the existing federation Ed25519 keypair.
  */
+// Use @noble/ed25519 (already a hard dep of @claude-flow/cli for IPFS
+// signing). Memoized behind one loader — two separate dynamic `import()`
+// call sites for the same bare specifier in this module tripped up the
+// test runner's dependency pre-bundling (surfaced once federation_bbs_
+// human_join actually ran instead of always short-circuiting to degraded).
+let _edMod = null;
+async function loadEd25519() {
+    if (!_edMod)
+        _edMod = await import('@noble/ed25519');
+    return _edMod;
+}
 let _signingKey = null;
 async function getSigningKey() {
     if (_signingKey)
         return _signingKey;
-    // Use @noble/ed25519 (already a hard dep of @claude-flow/cli for IPFS signing).
-    const ed = await import('@noble/ed25519');
+    const ed = await loadEd25519();
     const priv = ed.utils.randomPrivateKey
         ? ed.utils.randomPrivateKey()
         : randomBytes(32);
@@ -177,8 +205,7 @@ export const agentbbsTools = [
             // to mask malformed requests.
             const roomLabel = validateRoomLabel(String(input.roomLabel));
             const basePath = resolveBasePath(input.basePath);
-            const api = await loadAgentbbs();
-            if (!api)
+            if (!agentbbsCliAvailable())
                 return degradedResult('agentbbs-not-found');
             ensureDir(basePath);
             const roomId = roomIdFromLabel(roomLabel);
@@ -260,20 +287,24 @@ export const agentbbsTools = [
             if (typeof input.payload !== 'object' || input.payload === null) {
                 throw new Error('payload must be a JSON object');
             }
-            const api = await loadAgentbbs();
-            if (!api)
+            if (!agentbbsCliAvailable())
                 return degradedResult('agentbbs-not-found');
             ensureDir(basePath);
             const logPath = roomLogPath(basePath, roomId);
-            const env = {
+            const base = {
                 envelopeId: base64url(randomBytes(12)),
                 roomId,
                 seq: nextSeq(logPath),
                 msgType,
                 payload: input.payload,
                 timestamp: new Date().toISOString(),
-                signature: input.signature ? String(input.signature) : undefined,
             };
+            // Phase 2: sign with this host's persistent node identity so peers can
+            // attribute and verify the envelope after a cross-host merge. An
+            // explicitly supplied signature is preserved rather than overwritten.
+            const env = input.signature
+                ? { ...base, signature: String(input.signature) }
+                : (await signEnvelope(basePath, base));
             appendFileSync(logPath, JSON.stringify(env) + '\n');
             // Phase 1: recipientHopCount is always 0 (single-node). Phase 4+ will
             // surface real hop counts from the WG mesh transport.
@@ -314,8 +345,7 @@ export const agentbbsTools = [
         handler: async (input) => {
             const basePath = resolveBasePath(input.basePath);
             const roomId = validateRoomId(String(input.roomId));
-            const api = await loadAgentbbs();
-            if (!api)
+            if (!agentbbsCliAvailable())
                 return degradedResult('agentbbs-not-found');
             const limitRaw = typeof input.limit === 'number' ? input.limit : 50;
             const limit = Math.max(1, Math.min(500, Math.trunc(limitRaw)));
@@ -358,8 +388,7 @@ export const agentbbsTools = [
         },
         handler: async (input) => {
             const roomId = validateRoomId(String(input.roomId));
-            const api = await loadAgentbbs();
-            if (!api)
+            if (!agentbbsCliAvailable())
                 return degradedResult('agentbbs-not-found');
             const ttlRaw = typeof input.ttlSeconds === 'number' ? input.ttlSeconds : 300;
             const ttlSeconds = Math.max(30, Math.min(900, Math.trunc(ttlRaw)));
@@ -368,7 +397,7 @@ export const agentbbsTools = [
             const nonce = base64url(randomBytes(16));
             const payload = { roomId, nonce, expiresAt };
             const canonical = JSON.stringify(payload);
-            const ed = await import('@noble/ed25519');
+            const ed = await loadEd25519();
             const { priv, pub } = await getSigningKey();
             const sigBytes = await (ed.signAsync ?? ed.sign)(new TextEncoder().encode(canonical), priv);
             // Token format: base64url(JSON{payload, sig, pub}). Single string, easy
@@ -390,5 +419,136 @@ export const agentbbsTools = [
             };
         },
     },
+    // ---------------------------------------------------------------- Phase 2
+    {
+        name: 'federation_bbs_identity',
+        description: "agentbbs Phase 2 — return this host's persistent federation node identity (nodeId + Ed25519 public key), creating it on first call. Give the nodeId and publicKey to a peer so they can pin you with federation_bbs_peer_add. The private key never leaves this host and is never returned. Use when you are bootstrapping a new host into the federation and a peer needs something to pin. Reading node-identity.json directly is wrong because it also holds the private key, and the file is created lazily so it may not exist yet.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: { type: 'string', description: 'Override the .agentbbs directory.' },
+            },
+        },
+        handler: async (input) => {
+            const basePath = resolveBasePath(input.basePath);
+            if (!agentbbsCliAvailable())
+                return degradedResult('agentbbs-not-found');
+            const id = await getNodeIdentity(basePath);
+            return { success: true, nodeId: id.nodeId, publicKey: id.publicKey, createdAt: id.createdAt };
+        },
+    },
+    {
+        name: 'federation_bbs_peer_add',
+        description: `agentbbs Phase 2 — pin a remote federation peer by nodeId, URL and Ed25519 public key. The key is pinned at add time and every envelope merged from this peer is verified against it, so a hostile peer cannot forge another node's envelopes. Re-adding a known nodeId with a different key is refused; remove it first. Max ${MAX_PEERS} peers. Use when you have a peer's identity out of band and want to start syncing with it. Trusting a key carried inside an incoming envelope is wrong because that only proves the sender holds some key, not that they are the node they claim to be.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                nodeId: { type: 'string', description: "Peer's 16-hex nodeId from its federation_bbs_identity." },
+                url: { type: 'string', description: 'Peer base URL, e.g. http://100.104.125.72:7777' },
+                publicKey: { type: 'string', description: "Peer's 64-hex Ed25519 public key." },
+                label: { type: 'string', description: 'Optional human label.' },
+                basePath: { type: 'string' },
+            },
+            required: ['nodeId', 'url', 'publicKey'],
+        },
+        handler: async (input) => {
+            const basePath = resolveBasePath(input.basePath);
+            if (!agentbbsCliAvailable())
+                return degradedResult('agentbbs-not-found');
+            const peer = addPeer(basePath, {
+                nodeId: String(input.nodeId),
+                url: String(input.url),
+                publicKey: String(input.publicKey),
+                label: input.label ? String(input.label) : undefined,
+            });
+            return { success: true, peer: { nodeId: peer.nodeId, url: peer.url, label: peer.label, addedAt: peer.addedAt } };
+        },
+    },
+    {
+        name: 'federation_bbs_peers',
+        description: 'agentbbs Phase 2 — list pinned federation peers with last-sync state. Public keys are returned so an operator can compare a pin against what the peer reports; private material is never included. Use when you want to audit who this host will accept envelopes from, or unpin a peer. Editing peers.json by hand is wrong because a malformed entry silently disables verification for that peer on the next sync.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                remove: { type: 'string', description: 'Optional nodeId to unpin instead of listing.' },
+                basePath: { type: 'string' },
+            },
+        },
+        handler: async (input) => {
+            const basePath = resolveBasePath(input.basePath);
+            if (!agentbbsCliAvailable())
+                return degradedResult('agentbbs-not-found');
+            if (input.remove) {
+                const removed = removePeer(basePath, String(input.remove));
+                return { success: true, removed, nodeId: String(input.remove) };
+            }
+            return { success: true, peers: readPeers(basePath) };
+        },
+    },
+    {
+        name: 'federation_bbs_serve',
+        description: 'agentbbs Phase 2 — start the read-only pull endpoint peers fetch from (GET /agentbbs/v1/rooms/:roomId/envelopes). Binds 127.0.0.1 unless bindHost is given explicitly, so room contents are never exposed on a routable interface by accident. There is no route that mutates state. Use when this host needs to be reachable by peers that pull from it. Exposing the .agentbbs directory over a static file server is wrong because that would serve node-identity.json, which contains the private key.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                port: { type: 'number', description: 'Port to listen on. 0 picks a free one.' },
+                bindHost: { type: 'string', description: 'Interface to bind. Defaults to 127.0.0.1; set a tailnet IP to federate.' },
+                basePath: { type: 'string' },
+            },
+        },
+        handler: async (input) => {
+            const basePath = resolveBasePath(input.basePath);
+            if (!agentbbsCliAvailable())
+                return degradedResult('agentbbs-not-found');
+            const { port, host } = await serveFederation(basePath, {
+                port: typeof input.port === 'number' ? input.port : undefined,
+                bindHost: input.bindHost ? String(input.bindHost) : undefined,
+            });
+            const id = await getNodeIdentity(basePath);
+            return { success: true, listening: `http://${host}:${port}`, nodeId: id.nodeId, publicKey: id.publicKey };
+        },
+    },
+    {
+        name: 'federation_bbs_sync',
+        description: `agentbbs Phase 2 — pull a room from pinned peers and union-merge what verifies. Merge is keyed on envelopeId so it is idempotent and order-independent; unsigned, misattributed, oversize and over-hop (>${MAX_HOPS}) envelopes are dropped and counted rather than merged. Use after publish to propagate, or on a timer to converge. Use when you want to converge this host's rooms with its peers, on demand or on a timer. Copying room-*.jsonl between machines is wrong because it bypasses signature verification, dedupe and the hop limit, so a single hostile or looping file can corrupt the log.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                roomId: { type: 'string', description: 'Room to sync. Same label yields the same roomId on every host.' },
+                nodeId: { type: 'string', description: 'Optional single peer to sync from; default is all pinned peers.' },
+                basePath: { type: 'string' },
+            },
+            required: ['roomId'],
+        },
+        handler: async (input) => {
+            const basePath = resolveBasePath(input.basePath);
+            const roomId = fedValidateRoomId(String(input.roomId));
+            if (!agentbbsCliAvailable())
+                return degradedResult('agentbbs-not-found');
+            const all = readPeers(basePath);
+            const targets = input.nodeId ? all.filter(p => p.nodeId === String(input.nodeId)) : all;
+            if (targets.length === 0)
+                return { success: true, roomId, peersSynced: 0, results: [], note: 'no pinned peers' };
+            const results = [];
+            for (const peer of targets) {
+                try {
+                    results.push(await syncRoomFromPeer(basePath, peer, roomId));
+                }
+                catch (e) {
+                    // One unreachable peer must not fail the whole sync — the merge is
+                    // idempotent, so this peer simply catches up on the next run.
+                    results.push({ peerNodeId: peer.nodeId, roomId, error: e.message,
+                        merged: 0, skippedDuplicate: 0, skippedUnverified: 0, skippedOversize: 0, skippedHopLimit: 0 });
+                }
+            }
+            return {
+                success: true,
+                roomId,
+                peersSynced: results.length,
+                totalMerged: results.reduce((n, r) => n + (r.merged || 0), 0),
+                results,
+            };
+        },
+    },
 ];
 //# sourceMappingURL=agentbbs-tools.js.map

package/dist/src/services/harness-project-anchor.js

@@ -17,14 +17,25 @@ function normalizeHash(value) {
     return trimmed.startsWith('sha256:') ? trimmed : `sha256:${trimmed}`;
 }
 function containedPath(projectRoot, requested) {
-    const root = realpathSync(resolve(projectRoot));
-    const absolute = isAbsolute(requested) ? resolve(requested) : resolve(root, requested);
-    const lexical = relative(root, absolute);
-    if (lexical === '..' || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) {
+    // The project root has two equally valid spellings when its path crosses a
+    // symlink — on macOS `/tmp/x` and `/private/tmp/x` name the same directory.
+    // Comparing a realpath'd root against a NON-realpath'd candidate (as this
+    // did) makes every such project look like an escape, so a project anchored
+    // anywhere under a symlink was rejected outright. Compare like with like:
+    // the lexical guard accepts either spelling of the root, and the symlink
+    // guard below still resolves the target and re-checks it physically.
+    const rootLexical = resolve(projectRoot);
+    const rootPhysical = realpathSync(rootLexical);
+    const absolute = isAbsolute(requested) ? resolve(requested) : resolve(rootLexical, requested);
+    const escapes = (base) => {
+        const rel = relative(base, absolute);
+        return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+    };
+    if (escapes(rootLexical) && escapes(rootPhysical)) {
         throw new Error('flywheel anchor path must stay inside project root');
     }
     const actual = realpathSync(absolute);
-    const physical = relative(root, actual);
+    const physical = relative(rootPhysical, actual);
     if (physical === '..' || physical.startsWith(`..${sep}`) || isAbsolute(physical)) {
         throw new Error('flywheel anchor symlink escapes project root');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.39.2",
+  "version": "3.40.0",
   "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",