claude-flow 3.41.4 → 3.42.1

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

@@ -238,6 +238,58 @@ async function describeBackend() {
         return 'sqlite';
     }
 }
+/** #3311: one page per round trip, so a store larger than one page is
+ * counted rather than silently cut off at the old hardcoded 100000. */
+const MEMORY_STATS_PAGE = 10000;
+/** #3311: a hard stop so a `total` that never agrees with the rows returned
+ * cannot spin forever. Reaching it is reported as a truncated count, not as
+ * a complete one. */
+const MEMORY_STATS_MAX_PAGES = 200;
+/**
+ * Page through the store and return every row, or the first failure.
+ *
+ * The old call asked for `limit: 100000` in one shot and read only
+ * `entries`/`total` off the result — so a bigger store had its namespace
+ * breakdown and embedding coverage computed from a prefix, and a listing
+ * that reported `success: false` was read as an empty one.
+ */
+async function collectAllEntries(listEntries) {
+    const entries = [];
+    let total = 0;
+    for (let page = 0; page < MEMORY_STATS_MAX_PAGES; page++) {
+        const result = await listEntries({ limit: MEMORY_STATS_PAGE, offset: entries.length });
+        if (!result.success) {
+            return { success: false, entries, total: result.total ?? total, error: result.error };
+        }
+        total = result.total;
+        entries.push(...result.entries);
+        if (result.entries.length === 0 || entries.length >= total)
+            break;
+    }
+    return { success: true, entries, total };
+}
+/** #3311: unavailable is its own answer. The zeros this replaces were
+ * indistinguishable from a store that really is empty. */
+function memoryStatsUnavailable(error) {
+    return { initialized: null, available: false, error };
+}
+/**
+ * Version and feature labels from the initialization probe.
+ *
+ * Metadata only. The probe reads a whole-image snapshot that cannot see live
+ * WAL frames, so it is allowed to fail without that meaning the store is
+ * missing — which is exactly the conflation #3311 reports.
+ */
+async function readMemoryStatusLabels() {
+    try {
+        const { checkMemoryInitialization } = await getMemoryFunctions();
+        const status = await checkMemoryInitialization();
+        return { version: status.version, features: status.features };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Ensure memory database is initialized and migrate legacy data if needed.
  * #1606: Wrapped in try/catch to prevent process-level crashes that kill
@@ -704,41 +756,60 @@ export const memoryTools = [
         },
         handler: async () => {
             await ensureInitialized();
-            const { checkMemoryInitialization, listEntries } = await getMemoryFunctions();
+            const { listEntries } = await getMemoryFunctions();
+            // #3311: the store's own listing decides whether memory is there.
+            // `checkMemoryInitialization` opens a whole-image sql.js snapshot of
+            // the main database file, which cannot include live SQLite WAL frames
+            // — so a store the bridge reads and searches perfectly well came back
+            // `initialized: false` from this tool alone. The probe is still read
+            // below, for the version and feature labels it is the only source of,
+            // but it no longer gets to overrule a working store.
+            let listing;
             try {
-                const status = await checkMemoryInitialization();
-                const allEntries = await listEntries({ limit: 100000 });
-                // Count by namespace
-                const namespaces = {};
-                let withEmbeddings = 0;
-                for (const entry of allEntries.entries) {
-                    namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;
-                    if (entry.hasEmbedding)
-                        withEmbeddings++;
-                }
-                return {
-                    initialized: status.initialized,
-                    totalEntries: allEntries.total,
-                    entriesWithEmbeddings: withEmbeddings,
-                    embeddingCoverage: allEntries.total > 0
-                        ? `${((withEmbeddings / allEntries.total) * 100).toFixed(1)}%`
-                        : '0%',
-                    namespaces,
-                    backend: await describeBackend(),
-                    version: status.version || '3.0.0',
-                    features: status.features || {
-                        vectorEmbeddings: true,
-                        hnswIndex: true,
-                        semanticSearch: true,
-                    },
-                };
+                listing = await collectAllEntries(listEntries);
             }
             catch (error) {
-                return {
-                    initialized: false,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
+                return memoryStatsUnavailable(error instanceof Error ? error.message : 'Unknown error');
+            }
+            if (!listing.success) {
+                // A failed query is not an empty store. Reporting zeros here is
+                // what made a WAL refusal look like "you have no memories".
+                return memoryStatsUnavailable(listing.error || 'listEntries reported failure');
             }
+            // Object.create(null): a namespace literally named `__proto__` is a
+            // legal key, and assigning it on an object literal sets the prototype
+            // instead of counting anything — so that namespace's entries vanished
+            // from the breakdown while still being counted in the total.
+            const namespaces = Object.create(null);
+            let withEmbeddings = 0;
+            for (const entry of listing.entries) {
+                namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;
+                if (entry.hasEmbedding)
+                    withEmbeddings++;
+            }
+            const counted = listing.entries.length;
+            const status = await readMemoryStatusLabels();
+            return {
+                initialized: true,
+                totalEntries: listing.total,
+                entriesCounted: counted,
+                // The breakdown below covers `entriesCounted` rows, which is every
+                // row unless the listing was truncated; say so rather than letting
+                // a partial count read as the whole store.
+                ...(counted < listing.total ? { truncated: true } : {}),
+                entriesWithEmbeddings: withEmbeddings,
+                embeddingCoverage: counted > 0
+                    ? `${((withEmbeddings / counted) * 100).toFixed(1)}%`
+                    : '0%',
+                namespaces: { ...namespaces },
+                backend: await describeBackend(),
+                version: status.version || '3.0.0',
+                features: status.features || {
+                    vectorEmbeddings: true,
+                    hnswIndex: true,
+                    semanticSearch: true,
+                },
+            };
         },
     },
     {

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

@@ -0,0 +1,126 @@
+/**
+ * MCP Governance Policy Enforcer (opt-in).
+ *
+ * `.harness/mcp-policy.json` declares governance intent (defaultDeny,
+ * auditLog, maxToolCallsPerTurn, dangerousPatterns, ...) for the claude-flow
+ * MCP server, but until now nothing in the running server (mcp-server.ts)
+ * ever read it: `harness mcp-scan` grades the file's *posture* offline, the
+ * live `tools/call` dispatch never consulted it. Any connected MCP client
+ * could call every registered tool with no audit trail and no call budget.
+ *
+ * This module wires the two policy fields that are actually in this
+ * server's jurisdiction, per the policy file's own rationale comment
+ * (`dangerousPatterns` / `allowShell` / `allowNetwork` / `allowFileWrite`
+ * describe the native-Claude-Code-tool layer — Bash/Write/Edit/WebFetch —
+ * not this MCP server's memory_-, hooks_-, agentdb_-prefixed tool surface,
+ * so they are intentionally left unenforced here):
+ *   - `auditLog`: append a JSONL record for every `tools/call`.
+ *   - `maxToolCallsPerTurn`: bound calls per MCP *session* (one stdio
+ *     process lifetime), deny once exceeded.
+ *
+ * Fully opt-in via `RUFLO_MCP_ENFORCE_POLICY=1` (or `true`). Unset/false
+ * means every function below is a no-op on the hot path — the pre-existing
+ * `tools/call` behavior is unchanged.
+ *
+ * FAIL-CLOSED once enforcement is enabled (PR #3139 review round 1):
+ * a missing/malformed policy file, or a failed mandatory audit-log write,
+ * denies the call rather than silently degrading to unrestricted execution.
+ * The whole point of opting in is a restriction that actually holds; an
+ * enforcement flag that quietly falls back to "no restriction" on its own
+ * misconfiguration defeats the feature. See `evaluateToolCall()`.
+ *
+ * Known scope limits (disclosed, not fixed here):
+ *   - Only wired into the stdio `tools/call` dispatch
+ *     (`MCPServerManager.handleMCPMessage`). The separate HTTP/websocket
+ *     path (`startHttpServer()`, via `@claude-flow/mcp`) does not call
+ *     this module and is unaffected even when this flag is set.
+ *
+ * `maxToolCallsPerTurn` reset semantics (dream-cycle 2026-09-01, follow-up
+ * to 2026-08-31 review round 1): despite the field's name, the original
+ * implementation enforced a *session-lifetime cumulative* cap that never
+ * reset — a long-lived stdio session could exhaust the budget under
+ * entirely legitimate use and stay locked out until the MCP server process
+ * restarted. Research that night (see the dream-cycle gist) found: (1) the
+ * MCP spec only mandates "rate limit tool invocations" with zero mechanism
+ * guidance, and its 2026-07-28 revision (SEP-2567) is actively removing the
+ * session concept from the protocol entirely; (2) every framework/product
+ * that gets this right (FastMCP's rate-limiting middleware, the PolicyLayer
+ * MCP firewall, Cloudflare's public rate limiter) anchors the reset to
+ * wall-clock time, not to a turn or session counter that never decays —
+ * a turn-count reset is gameable by a chatty loop re-arming its own budget,
+ * which wall-clock time is not. This module now enforces a *sliding
+ * wall-clock window*: `maxToolCallsPerTurn` calls are allowed per rolling
+ * `turnWindowMs` (default 60000) per session, keyed by call timestamp so
+ * calls fall out of the window as time passes rather than accumulating
+ * forever. `now` is an injectable parameter (defaults to `Date.now`) so
+ * production callers need no change and tests stay fully deterministic via
+ * `vi.useFakeTimers()`.
+ */
+export interface McpPolicy {
+    schema?: number;
+    policyVersion?: number;
+    harnessId?: string;
+    defaultDeny?: boolean;
+    auditLog?: boolean;
+    requireApprovalForDangerous?: boolean;
+    toolTimeoutMs?: number;
+    /**
+     * Despite the name, this is a WALL-CLOCK rate limit, not a literal
+     * conversational-turn counter — MCP has no protocol-level concept of a
+     * "turn" to count against (confirmed: the spec is silent on it, and its
+     * 2026-07-28 revision removes the session concept entirely). Enforced as
+     * "at most this many calls in any rolling `turnWindowMs` window" per
+     * session. Treat it, and document it to callers, as rate limiting.
+     */
+    maxToolCallsPerTurn?: number;
+    /** Rolling window (ms) over which `maxToolCallsPerTurn` is counted. Default 60000. */
+    turnWindowMs?: number;
+    dangerousPatterns?: string[];
+    approvedServers?: string[];
+    [key: string]: unknown;
+}
+export declare function isPolicyEnforcementEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function loadMcpPolicy(policyPath?: string): McpPolicy | null;
+/** Test-only: clear per-session call state between test cases. */
+export declare function resetPolicyEnforcerState(): void;
+export interface PolicyCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Checks (and, if allowed, records) a tool call against
+ * `policy.maxToolCallsPerTurn`, counted over a sliding window of
+ * `policy.turnWindowMs` (default 60000ms) rather than the session's whole
+ * lifetime. Calls older than the window are pruned before comparing count
+ * to limit, so a session that pauses gets its budget back rather than
+ * staying denied until the process restarts. `now` defaults to `Date.now`
+ * for production callers; tests inject a controlled clock instead.
+ */
+export declare function checkAndRecordCall(policy: McpPolicy, sessionId: string, now?: number): PolicyCheckResult;
+export interface AuditLogEntry {
+    timestamp: string;
+    sessionId: string;
+    toolName: string;
+    allowed: boolean;
+    reason?: string;
+}
+/** Test-only: redirect the audit log to a temp file instead of the default path. */
+export declare function setAuditLogPathForTesting(p: string | null): void;
+export declare function getAuditLogPath(): string;
+/**
+ * Appends one JSONL audit record. Returns `true` if `policy.auditLog` is not
+ * set (nothing was required) or the write succeeded; `false` only when
+ * `auditLog` is required and the write itself failed (disk full, unwritable
+ * path, etc). Never throws — the caller (`evaluateToolCall`) decides what a
+ * failed *mandatory* write means for the call (fail-closed: deny it).
+ */
+export declare function appendAuditLog(policy: McpPolicy, entry: AuditLogEntry): boolean;
+/**
+ * Single enforcement entry point for a `tools/call` dispatch. Combines, in
+ * order: fail-closed on a missing/malformed policy, the per-session call
+ * budget, and fail-closed on a failed mandatory audit-log write. `policy`
+ * is the result of `loadMcpPolicy()` — pass `null` straight through when it
+ * failed to load, rather than re-deciding that here.
+ */
+export declare function evaluateToolCall(policy: McpPolicy | null, sessionId: string, toolName: string, now?: number): PolicyCheckResult;
+//# sourceMappingURL=policy-enforcer.d.ts.map

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

@@ -0,0 +1,177 @@
+/**
+ * MCP Governance Policy Enforcer (opt-in).
+ *
+ * `.harness/mcp-policy.json` declares governance intent (defaultDeny,
+ * auditLog, maxToolCallsPerTurn, dangerousPatterns, ...) for the claude-flow
+ * MCP server, but until now nothing in the running server (mcp-server.ts)
+ * ever read it: `harness mcp-scan` grades the file's *posture* offline, the
+ * live `tools/call` dispatch never consulted it. Any connected MCP client
+ * could call every registered tool with no audit trail and no call budget.
+ *
+ * This module wires the two policy fields that are actually in this
+ * server's jurisdiction, per the policy file's own rationale comment
+ * (`dangerousPatterns` / `allowShell` / `allowNetwork` / `allowFileWrite`
+ * describe the native-Claude-Code-tool layer — Bash/Write/Edit/WebFetch —
+ * not this MCP server's memory_-, hooks_-, agentdb_-prefixed tool surface,
+ * so they are intentionally left unenforced here):
+ *   - `auditLog`: append a JSONL record for every `tools/call`.
+ *   - `maxToolCallsPerTurn`: bound calls per MCP *session* (one stdio
+ *     process lifetime), deny once exceeded.
+ *
+ * Fully opt-in via `RUFLO_MCP_ENFORCE_POLICY=1` (or `true`). Unset/false
+ * means every function below is a no-op on the hot path — the pre-existing
+ * `tools/call` behavior is unchanged.
+ *
+ * FAIL-CLOSED once enforcement is enabled (PR #3139 review round 1):
+ * a missing/malformed policy file, or a failed mandatory audit-log write,
+ * denies the call rather than silently degrading to unrestricted execution.
+ * The whole point of opting in is a restriction that actually holds; an
+ * enforcement flag that quietly falls back to "no restriction" on its own
+ * misconfiguration defeats the feature. See `evaluateToolCall()`.
+ *
+ * Known scope limits (disclosed, not fixed here):
+ *   - Only wired into the stdio `tools/call` dispatch
+ *     (`MCPServerManager.handleMCPMessage`). The separate HTTP/websocket
+ *     path (`startHttpServer()`, via `@claude-flow/mcp`) does not call
+ *     this module and is unaffected even when this flag is set.
+ *
+ * `maxToolCallsPerTurn` reset semantics (dream-cycle 2026-09-01, follow-up
+ * to 2026-08-31 review round 1): despite the field's name, the original
+ * implementation enforced a *session-lifetime cumulative* cap that never
+ * reset — a long-lived stdio session could exhaust the budget under
+ * entirely legitimate use and stay locked out until the MCP server process
+ * restarted. Research that night (see the dream-cycle gist) found: (1) the
+ * MCP spec only mandates "rate limit tool invocations" with zero mechanism
+ * guidance, and its 2026-07-28 revision (SEP-2567) is actively removing the
+ * session concept from the protocol entirely; (2) every framework/product
+ * that gets this right (FastMCP's rate-limiting middleware, the PolicyLayer
+ * MCP firewall, Cloudflare's public rate limiter) anchors the reset to
+ * wall-clock time, not to a turn or session counter that never decays —
+ * a turn-count reset is gameable by a chatty loop re-arming its own budget,
+ * which wall-clock time is not. This module now enforces a *sliding
+ * wall-clock window*: `maxToolCallsPerTurn` calls are allowed per rolling
+ * `turnWindowMs` (default 60000) per session, keyed by call timestamp so
+ * calls fall out of the window as time passes rather than accumulating
+ * forever. `now` is an injectable parameter (defaults to `Date.now`) so
+ * production callers need no change and tests stay fully deterministic via
+ * `vi.useFakeTimers()`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+export function isPolicyEnforcementEnabled(env = process.env) {
+    const v = env.RUFLO_MCP_ENFORCE_POLICY;
+    return v === '1' || (v ?? '').toLowerCase() === 'true';
+}
+export function loadMcpPolicy(policyPath = path.join(process.cwd(), '.harness', 'mcp-policy.json')) {
+    try {
+        const raw = fs.readFileSync(policyPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+const DEFAULT_TURN_WINDOW_MS = 60_000;
+const sessionState = new Map();
+/** Test-only: clear per-session call state between test cases. */
+export function resetPolicyEnforcerState() {
+    sessionState.clear();
+}
+/**
+ * Checks (and, if allowed, records) a tool call against
+ * `policy.maxToolCallsPerTurn`, counted over a sliding window of
+ * `policy.turnWindowMs` (default 60000ms) rather than the session's whole
+ * lifetime. Calls older than the window are pruned before comparing count
+ * to limit, so a session that pauses gets its budget back rather than
+ * staying denied until the process restarts. `now` defaults to `Date.now`
+ * for production callers; tests inject a controlled clock instead.
+ */
+export function checkAndRecordCall(policy, sessionId, now = Date.now()) {
+    const limit = policy.maxToolCallsPerTurn;
+    if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0) {
+        return { allowed: true };
+    }
+    const configuredWindow = policy.turnWindowMs;
+    const windowMs = typeof configuredWindow === 'number' && Number.isFinite(configuredWindow) && configuredWindow > 0
+        ? configuredWindow
+        : DEFAULT_TURN_WINDOW_MS;
+    const state = sessionState.get(sessionId) ?? { callTimes: [] };
+    const cutoff = now - windowMs;
+    state.callTimes = state.callTimes.filter((t) => t > cutoff);
+    if (state.callTimes.length >= limit) {
+        sessionState.set(sessionId, state);
+        return {
+            allowed: false,
+            reason: `maxToolCallsPerTurn (${limit}) exceeded within the last ${windowMs}ms for this session`,
+        };
+    }
+    state.callTimes.push(now);
+    sessionState.set(sessionId, state);
+    return { allowed: true };
+}
+let auditLogPathOverride = null;
+/** Test-only: redirect the audit log to a temp file instead of the default path. */
+export function setAuditLogPathForTesting(p) {
+    auditLogPathOverride = p;
+}
+function defaultAuditLogPath() {
+    return path.join(os.tmpdir(), 'ruflo-mcp-audit.jsonl');
+}
+export function getAuditLogPath() {
+    return auditLogPathOverride ?? defaultAuditLogPath();
+}
+/**
+ * Appends one JSONL audit record. Returns `true` if `policy.auditLog` is not
+ * set (nothing was required) or the write succeeded; `false` only when
+ * `auditLog` is required and the write itself failed (disk full, unwritable
+ * path, etc). Never throws — the caller (`evaluateToolCall`) decides what a
+ * failed *mandatory* write means for the call (fail-closed: deny it).
+ */
+export function appendAuditLog(policy, entry) {
+    if (!policy.auditLog)
+        return true;
+    try {
+        fs.appendFileSync(getAuditLogPath(), `${JSON.stringify(entry)}\n`, 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Single enforcement entry point for a `tools/call` dispatch. Combines, in
+ * order: fail-closed on a missing/malformed policy, the per-session call
+ * budget, and fail-closed on a failed mandatory audit-log write. `policy`
+ * is the result of `loadMcpPolicy()` — pass `null` straight through when it
+ * failed to load, rather than re-deciding that here.
+ */
+export function evaluateToolCall(policy, sessionId, toolName, now = Date.now()) {
+    if (policy === null) {
+        return {
+            allowed: false,
+            reason: 'RUFLO_MCP_ENFORCE_POLICY is set but .harness/mcp-policy.json is missing or invalid — failing closed',
+        };
+    }
+    const budget = checkAndRecordCall(policy, sessionId, now);
+    const auditOk = appendAuditLog(policy, {
+        timestamp: new Date(now).toISOString(),
+        sessionId,
+        toolName,
+        allowed: budget.allowed,
+        reason: budget.reason,
+    });
+    if (!budget.allowed)
+        return budget;
+    if (!auditOk) {
+        return {
+            allowed: false,
+            reason: 'audit log write failed and policy.auditLog is required — failing closed',
+        };
+    }
+    return { allowed: true };
+}
+//# sourceMappingURL=policy-enforcer.js.map

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

@@ -1,3 +1,4 @@
+import { relayPayload } from './x-federation-tools.js';
 // ADR-125 precedence: explicit tool args (metaLlmUrl / gatewayUrl) take precedence over the
 // SERAPHINA_METALLM_URL / RUFLO_X_GATEWAY_URL env vars, which precede the defaults.
 const META_LLM = (override) => (override || process.env.SERAPHINA_METALLM_URL || 'https://api.cognitum.one').replace(/\/$/, '');
@@ -14,7 +15,9 @@ async function gatewayRead(uri, gatewayUrl) {
     const text = await res.text();
     const line = text.split('\n').find((l) => l.startsWith('data:'));
     const p = JSON.parse(line ? line.slice(5) : text);
-    return JSON.parse(p.result?.contents?.[0]?.text ?? '{}');
+    // roster and claims are relay-sourced and therefore fenced (#3300). These values
+    // are indexed directly below, so take the payload, not the envelope.
+    return relayPayload(p.result?.contents?.[0]?.text ?? '{}');
 }
 async function gatewaySync(sinceSeconds, limit, gatewayUrl) {
     const res = await fetch(`${GATEWAY(gatewayUrl)}/mcp`, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
@@ -22,7 +25,9 @@ async function gatewaySync(sinceSeconds, limit, gatewayUrl) {
     const text = await res.text();
     const line = text.split('\n').find((l) => l.startsWith('data:'));
     const p = JSON.parse(line ? line.slice(5) : text);
-    return JSON.parse(p.result?.content?.[0]?.text ?? '{}');
+    // federation_sync is relay-sourced and therefore fenced (#3300); `.messages` is
+    // read directly below, so an envelope here would silently mean "empty swarm".
+    return relayPayload(p.result?.content?.[0]?.text ?? '{}');
 }
 export async function askSeraphina(goal, opts = {}) {
     // Credential: intentionally env-only (never a CLI flag). Registered in audit-env-var-precedence.mjs.

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

@@ -8,5 +8,17 @@
  * `ruv://federation/registry` resource), not through these gateway-identity tools.
  */
 import type { MCPTool } from './types.js';
+export declare function parseGatewayText(text: string): Record<string, unknown>;
+/**
+ * The payload, for consumers INSIDE this package that immediately index the
+ * value (`recent.messages`, `Object.keys(roster)`).
+ *
+ * At the MCP boundary we return the whole envelope so the caller can see whose
+ * words these are. Internally that shape is a hazard: reading `.messages` off an
+ * envelope yields undefined and `Object.keys()` yields the envelope's own five
+ * keys, so a miscount looks like a real answer. Never do a bare property read on
+ * a parseGatewayText result — come through here.
+ */
+export declare function relayPayload(text: string): Record<string, unknown>;
 export declare const xFederationTools: MCPTool[];
 //# sourceMappingURL=x-federation-tools.d.ts.map

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

@@ -18,18 +18,100 @@ async function gatewayRpc(method, params, gatewayUrl) {
         throw new Error(`x.ruv.io: ${payload.error.message ?? 'rpc error'}`);
     return payload.result;
 }
+/**
+ * Relay-sourced gateway responses are not bare JSON. Since #3300 the gateway
+ * wraps anything published by other federation members in a provenance envelope
+ * (plugins/ruflo-x-gateway/src/untrusted.mjs): several lines of gateway-authored
+ * prose, then the JSON body between a matched
+ * `<<<UNTRUSTED_RELAY_DATA <uuid>>>>` / `<<<END_UNTRUSTED_RELAY_DATA <uuid>>>>`
+ * pair. `JSON.parse` on the whole string fails on the first prose word, which is
+ * the `Unexpected token 'T', "The block "...` seen from every federation read.
+ *
+ * Three things keep a publisher from closing the block early, and it is worth
+ * being precise about which one is doing the work today:
+ *   1. The body is JSON.stringify'd, so it is a SINGLE line — a publisher's text
+ *      cannot contain a raw newline, and the markers below are newline-anchored.
+ *      This is what actually neutralises forged markers in relay content today.
+ *   2. The token backreference: a forged END carrying any other token does not
+ *      terminate the region. This is the defence that survives (1) — if the body
+ *      is ever pretty-printed, it becomes the only one left. It is tested
+ *      directly rather than incidentally, so it cannot be refactored away quietly.
+ *   3. Exactly one opening marker is permitted. `fenceUntrusted` splices its
+ *      `note` verbatim BEFORE the fence, so a caller that ever interpolates
+ *      relay-derived text into a note could otherwise smuggle in a complete
+ *      earlier envelope; first-match-wins would return it, with untrusted:false.
+ *
+ * We deliberately return the WHOLE envelope (`untrusted`, `provenance`, `relay`,
+ * `retrievedAt`, `data`) rather than lifting `data` out of it. The point of the
+ * envelope is that a caller can tell whose words these are; quietly unwrapping to
+ * the payload would restore valid JSON by discarding the labelling that made it
+ * safe to read. Unfenced responses (the registry resource, gateway-authored
+ * errors) parse unchanged.
+ */
+const UNTRUSTED_FENCE = /<<<UNTRUSTED_RELAY_DATA ([0-9a-fA-F-]{36})>>>\n([\s\S]*?)\n<<<END_UNTRUSTED_RELAY_DATA \1>>>/;
+// Count only NEWLINE-ANCHORED opening markers. A marker inside the body is just
+// characters — the body is one JSON line, so it can never be preceded by a raw
+// newline and can never open a fence. Counting raw occurrences instead would make
+// a publisher able to hard-fail every read simply by typing the marker into a
+// message, which trades a parse bug for a denial of service.
+const OPEN_MARKER_ANCHORED = /(?:^|\n)<<<UNTRUSTED_RELAY_DATA /g;
+export function parseGatewayText(text) {
+    // One response carries exactly one envelope. More than one means something
+    // upstream spliced an envelope-shaped string into the response, and picking
+    // either is a guess — refuse rather than choose.
+    const opens = (text.match(OPEN_MARKER_ANCHORED) ?? []).length;
+    if (opens > 1) {
+        throw new Error('x.ruv.io: response carries more than one untrusted-data envelope (tampered response)');
+    }
+    const fenced = UNTRUSTED_FENCE.exec(text);
+    if (fenced)
+        return JSON.parse(fenced[2]);
+    // An opening marker with no matching close is a truncated or tampered response.
+    // Fail loudly: parsing the remainder would silently drop relay content.
+    if (opens === 1) {
+        throw new Error('x.ruv.io: untrusted-data envelope is unterminated (truncated or tampered response)');
+    }
+    return JSON.parse(text);
+}
+/**
+ * The payload, for consumers INSIDE this package that immediately index the
+ * value (`recent.messages`, `Object.keys(roster)`).
+ *
+ * At the MCP boundary we return the whole envelope so the caller can see whose
+ * words these are. Internally that shape is a hazard: reading `.messages` off an
+ * envelope yields undefined and `Object.keys()` yields the envelope's own five
+ * keys, so a miscount looks like a real answer. Never do a bare property read on
+ * a parseGatewayText result — come through here.
+ */
+export function relayPayload(text) {
+    const parsed = parseGatewayText(text);
+    return (parsed.untrusted === true && parsed.data !== undefined
+        ? parsed.data
+        : parsed);
+}
 async function gatewayTool(name, args) {
     const { gatewayUrl, ...rest } = args;
     const r = (await gatewayRpc('tools/call', { name, arguments: rest }, gatewayUrl));
-    const text = r.content?.[0]?.text ?? '{}';
-    const parsed = JSON.parse(text);
-    if (r.isError || parsed.error)
-        throw new Error(String(parsed.error ?? 'gateway tool error'));
+    const raw = r.content?.[0]?.text ?? '{}';
+    // An isError result is the SDK's createToolError, whose message is raw text and
+    // not JSON. Parsing first turns "private channels cannot be published…" into
+    // "Unexpected token 'p'" — the same class of bug this parser exists to fix.
+    if (r.isError) {
+        let msg = raw;
+        try {
+            msg = String(parseGatewayText(raw).error ?? raw);
+        }
+        catch { /* raw text: use as-is */ }
+        throw new Error(msg || 'gateway tool error');
+    }
+    const parsed = parseGatewayText(raw);
+    if (parsed.error)
+        throw new Error(String(parsed.error));
     return parsed;
 }
 async function gatewayResource(uri, gatewayUrl) {
     const r = (await gatewayRpc('resources/read', { uri }, gatewayUrl));
-    return JSON.parse(r.contents?.[0]?.text ?? '{}');
+    return parseGatewayText(r.contents?.[0]?.text ?? '{}');
 }
 // Credential: intentionally env-only (a secret must never be a CLI flag — it would land in
 // shell history / process lists). Registered in scripts/audit-env-var-precedence.mjs.

package/v3/@claude-flow/cli/dist/src/memory/intelligence.d.ts

@@ -178,13 +178,25 @@ declare class LocalReasoningBank {
      */
     store(pattern: Omit<StoredPattern, 'usageCount' | 'createdAt' | 'lastUsedAt'> & Partial<StoredPattern>): void;
     /**
-     * Find similar patterns by embedding
+     * Find similar patterns by embedding.
+     *
+     * `confidence` on each result is the pattern's own learned reliability
+     * (unchanged from storage) — NOT how well it matches this query. The
+     * per-query cosine score is returned separately as `similarity`. Callers
+     * that want "how good a semantic match is this" must read `.similarity`;
+     * callers that want "how reliable has this pattern proven to be" read
+     * `.confidence`. Prior to this fix both were conflated (confidence was
+     * overwritten with the cosine score), which silently broke any consumer
+     * that needed to tell them apart (found during the 2026-09-12 dream-cycle
+     * intelligence-surface review).
      */
     findSimilar(queryEmbedding: number[], options: {
         k?: number;
         threshold?: number;
         type?: string;
-    }): StoredPattern[];
+    }): (StoredPattern & {
+        similarity: number;
+    })[];
     /**
      * Optimized cosine similarity
      */