@claude-flow/cli 3.41.4 → 3.42.1

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

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

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

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

package/dist/src/mcp-tools/hive-mind-tools.d.ts

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

package/dist/src/mcp-tools/hive-mind-tools.js

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

package/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/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