claude-flow 3.57.1 → 3.58.0

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

@@ -2333,6 +2333,19 @@ const workerListCommand = {
         }
     }
 };
+// Render the status hooks_worker-dispatch actually returned. Only a status that
+// means work finished may read as "completed" (#4196).
+function dispatchStatusLabel(status) {
+    switch (status) {
+        case 'dispatched': return output.highlight('dispatched (background)');
+        case 'queued': return output.highlight('queued (daemon)');
+        case 'no-daemon': return output.warning('no-daemon (not run)');
+        case 'mcp-only': return output.warning('mcp-only (not queued)');
+        case 'synthetic-completed': return output.warning('recorded (no work executed)');
+        case 'completed': return output.success('completed');
+        default: return output.dim(String(status));
+    }
+}
 const workerDispatchCommand = {
     name: 'dispatch',
     description: 'Dispatch a background worker for analysis/optimization',
@@ -2386,9 +2399,15 @@ const workerDispatchCommand = {
                     { field: 'Description', value: result.config.description },
                     { field: 'Est. Duration', value: result.config.estimatedDuration },
                     { field: 'Capabilities', value: result.config.capabilities.join(', ') },
-                    { field: 'Status', value: result.status === 'dispatched' ? output.highlight('dispatched (background)') : output.success('completed') },
+                    { field: 'Status', value: dispatchStatusLabel(result.status) },
                 ],
             });
+            // The tool says why it could not run the worker (e.g. no daemon); show it
+            // rather than letting a recorded-only dispatch read as finished work (#4196).
+            if (result.note) {
+                output.writeln();
+                output.printWarning(result.note);
+            }
             if (background) {
                 output.writeln();
                 output.writeln(output.dim(`Check status: claude-flow hooks worker status --id ${result.workerId}`));

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

@@ -34,6 +34,14 @@ function formatUptime(seconds) {
     const mins = Math.floor((seconds % 3600) / 60);
     return `${hours}h ${mins}m`;
 }
+function readIntegerOption(flags, name, envName) {
+    const camelName = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const input = flags[camelName] ?? flags[name] ?? process.env[envName];
+    return input === undefined ? undefined : Number(input);
+}
+function isOutOfRange(value, min, max) {
+    return value !== undefined && (!Number.isSafeInteger(value) || value < min || value > max);
+}
 // Start MCP server
 const startCommand = {
     name: 'start',
@@ -71,6 +79,31 @@ const startCommand = {
             description: 'HTTP request timeout in milliseconds (default 30000; env RUFLO_MCP_REQUEST_TIMEOUT_MS)',
             type: 'number'
         },
+        {
+            name: 'rate-limit-per-ip',
+            description: 'HTTP requests allowed per client IP per window (env RUFLO_MCP_RATE_LIMIT_PER_IP)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-window-ms',
+            description: 'HTTP rate limit window in milliseconds (env RUFLO_MCP_RATE_LIMIT_WINDOW_MS)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-per-session',
+            description: 'Request burst allowed per MCP session, refilled over 10s; also bounded by the server-wide bucket (env RUFLO_MCP_RATE_LIMIT_PER_SESSION)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-global-rps',
+            description: 'Server-wide requests per second across all sessions (env RUFLO_MCP_RATE_LIMIT_GLOBAL_RPS)',
+            type: 'number'
+        },
+        {
+            name: 'rate-limit-global-burst',
+            description: 'Server-wide request burst across all sessions (env RUFLO_MCP_RATE_LIMIT_GLOBAL_BURST)',
+            type: 'number'
+        },
         {
             name: 'auth-token-file',
             description: 'Read the HTTP bearer token from this file (http transport). Preferred over --auth-token; env RUFLO_MCP_HTTP_TOKEN also works',
@@ -100,6 +133,7 @@ const startCommand = {
         { command: 'claude-flow mcp start', description: 'Start with defaults (stdio)' },
         { command: 'claude-flow mcp start -p 8080 -t http', description: 'Start HTTP server' },
         { command: 'claude-flow mcp start -t http --request-timeout-ms 120000', description: 'Allow slower cold-start HTTP tools' },
+        { command: 'claude-flow mcp start -t http --rate-limit-per-ip 600 --rate-limit-per-session 500 --rate-limit-global-burst 1000', description: 'Raise rate limits for a shared control plane' },
         { command: 'RUFLO_MCP_HTTP_TOKEN=<16+ chars> claude-flow mcp start -t http', description: 'HTTP server requiring "Authorization: Bearer <token>" on every request (except GET /health)' },
         { command: 'RUFLO_MCP_HTTP_TOKEN=<16+ chars> claude-flow mcp start -t http --host 0.0.0.0', description: 'Non-loopback bind: allowed only with a token (or RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1)' },
         { command: 'claude-flow mcp start -d', description: 'Start as daemon' },
@@ -112,15 +146,36 @@ const startCommand = {
         const tools = ctx.flags.tools
             || process.env.CLAUDE_FLOW_MCP_TOOLS
             || 'all';
-        const timeoutInput = ctx.flags.requestTimeoutMs
-            ?? ctx.flags['request-timeout-ms']
-            ?? process.env.RUFLO_MCP_REQUEST_TIMEOUT_MS;
-        const requestTimeoutMs = timeoutInput === undefined ? undefined : Number(timeoutInput);
-        if (requestTimeoutMs !== undefined &&
-            (!Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 1 || requestTimeoutMs > 3_600_000)) {
+        const requestTimeoutMs = readIntegerOption(ctx.flags, 'request-timeout-ms', 'RUFLO_MCP_REQUEST_TIMEOUT_MS');
+        if (isOutOfRange(requestTimeoutMs, 1, 3_600_000)) {
             output.printError('Request timeout must be an integer from 1 to 3600000 milliseconds');
             return { success: false, exitCode: 1 };
         }
+        const rateLimitPerIp = readIntegerOption(ctx.flags, 'rate-limit-per-ip', 'RUFLO_MCP_RATE_LIMIT_PER_IP');
+        if (isOutOfRange(rateLimitPerIp, 1, 100_000)) {
+            output.printError('HTTP rate limit must be an integer from 1 to 100000 requests per window');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitWindowMs = readIntegerOption(ctx.flags, 'rate-limit-window-ms', 'RUFLO_MCP_RATE_LIMIT_WINDOW_MS');
+        if (isOutOfRange(rateLimitWindowMs, 1000, 3_600_000)) {
+            output.printError('Rate limit window must be an integer from 1000 to 3600000 milliseconds');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitPerSession = readIntegerOption(ctx.flags, 'rate-limit-per-session', 'RUFLO_MCP_RATE_LIMIT_PER_SESSION');
+        if (isOutOfRange(rateLimitPerSession, 1, 10_000)) {
+            output.printError('Session rate limit must be an integer from 1 to 10000 requests');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitGlobalRps = readIntegerOption(ctx.flags, 'rate-limit-global-rps', 'RUFLO_MCP_RATE_LIMIT_GLOBAL_RPS');
+        if (isOutOfRange(rateLimitGlobalRps, 1, 10_000)) {
+            output.printError('Global rate limit must be an integer from 1 to 10000 requests per second');
+            return { success: false, exitCode: 1 };
+        }
+        const rateLimitGlobalBurst = readIntegerOption(ctx.flags, 'rate-limit-global-burst', 'RUFLO_MCP_RATE_LIMIT_GLOBAL_BURST');
+        if (isOutOfRange(rateLimitGlobalBurst, 1, 20_000)) {
+            output.printError('Global rate limit burst must be an integer from 1 to 20000 requests');
+            return { success: false, exitCode: 1 };
+        }
         let authToken;
         try {
             authToken = resolveMcpHttpAuthToken({
@@ -189,6 +244,11 @@ const startCommand = {
             port,
             tools: !tools || tools === 'all' ? 'all' : tools.split(','),
             ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+            ...(rateLimitPerIp === undefined ? {} : { rateLimitPerIp }),
+            ...(rateLimitWindowMs === undefined ? {} : { rateLimitWindowMs }),
+            ...(rateLimitPerSession === undefined ? {} : { rateLimitPerSession }),
+            ...(rateLimitGlobalRps === undefined ? {} : { rateLimitGlobalRps }),
+            ...(rateLimitGlobalBurst === undefined ? {} : { rateLimitGlobalBurst }),
             ...(authToken ? { authToken } : {}),
             daemonize: daemon,
         };

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

@@ -16,6 +16,7 @@ import { existsSync } from 'node:fs';
 import { siblingAgentDbPath } from '../memory/memory-bridge.js';
 import { validateIdentifier } from '../mcp-tools/validate-input.js';
 import { memoryKeyError } from '../mcp-tools/memory-tools.js';
+import { memoryPeek } from '../memory/memory-peek.js';
 /**
  * #3228: a miss in one store is not a miss in the memory.
  *
@@ -659,7 +660,9 @@ const searchCommand = {
                     });
                     return {
                         results: r.results.map(e => ({
-                            id: e.id,
+                            // #2271: searchEntries() ids are truncated to 12 chars and collide
+                            // for entries written within ~2.8h; SmartRetrieval dedupes on id.
+                            id: JSON.stringify([e.namespace, e.key]),
                             key: e.key,
                             content: e.content,
                             score: e.score,
@@ -1221,6 +1224,54 @@ const statsCommand = {
         }
     }
 };
+// #3508: read-only route/peek — which store files this cwd resolves to,
+// their row counts and last write, without creating or initializing
+// anything. Unlike `stats`, this never calls into the MCP tool layer (no
+// `authorizeMcpTool` receipt, no `ensureInitialized()`): it reads both
+// files directly, in-process, read-only.
+const peekCommand = {
+    name: 'peek',
+    description: 'Report which memory store files this cwd resolves to, their row counts and last write — read-only, creates nothing',
+    options: [DB_PATH_OPTION],
+    action: async (ctx) => {
+        try {
+            const result = await memoryPeek({ path: ctx.flags.path });
+            if (ctx.flags.format === 'json') {
+                output.printJson(result);
+                return { success: true, data: result };
+            }
+            output.writeln();
+            output.writeln(output.bold('Memory Peek'));
+            output.writeln();
+            output.writeln(`cwd: ${result.cwd}`);
+            output.writeln(`root: ${result.root.path} (source: ${result.root.source})`);
+            output.writeln();
+            output.printTable({
+                columns: [
+                    { key: 'role', header: 'Role', width: 6 },
+                    { key: 'path', header: 'Path', width: 40 },
+                    { key: 'exists', header: 'Exists', width: 8 },
+                    { key: 'rows', header: 'Rows', width: 8, align: 'right' },
+                    { key: 'lastWrite', header: 'Last Write', width: 24 },
+                ],
+                data: result.stores.map((store) => ({
+                    role: store.role,
+                    path: store.path,
+                    exists: store.exists ? 'yes' : 'no',
+                    rows: store.encrypted ? 'encrypted' : (store.rows === null ? 'unknown' : String(store.rows)),
+                    lastWrite: store.lastWrite ?? 'N/A',
+                })),
+            });
+            output.writeln();
+            output.writeln(`Shared keys (same namespace+key in both stores): ${result.sharedKeys === null ? 'unknown' : result.sharedKeys}`);
+            return { success: true, data: result };
+        }
+        catch (error) {
+            output.printError(`Failed to peek: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return { success: false, exitCode: 1 };
+        }
+    }
+};
 // Configure command
 const configureCommand = {
     name: 'configure',
@@ -1592,6 +1643,13 @@ const exportCommand = {
                 namespace: ctx.flags.namespace,
                 includeVectors: ctx.flags.includeVectors ?? true,
             });
+            // memory_export reports failure as { error } rather than throwing; without
+            // this check the command printed "Exported to undefined" and then crashed
+            // reading result.exported.entries (#4204).
+            if (!result || result.error || !result.exported) {
+                output.printError(`Export error: ${result?.error ?? 'memory_export returned no export summary'}`);
+                return { success: false, exitCode: 1 };
+            }
             output.printSuccess(`Exported to ${result.outputPath}`);
             output.printList([
                 `Entries: ${result.exported.entries}`,
@@ -1657,6 +1715,21 @@ const importCommand = {
                 namespace: ctx.flags.namespace,
                 dbPath: resolveDbPath(ctx.flags.path),
             });
+            // memory_import reports a bad file as { error } rather than throwing, and
+            // a partial write as { success: false, error, imported }. Without this the
+            // command printed "Imported from undefined" and crashed on result.imported,
+            // or reported success for an import that dropped entries.
+            const failure = result?.error;
+            if (!result || failure || result.success === false || !result.imported) {
+                output.printError(`Import error: ${failure ?? 'memory_import returned no import summary'}`);
+                if (result?.imported) {
+                    output.printList([
+                        `Entries imported: ${result.imported.entries}`,
+                        `Failed: ${result.failed ?? 'unknown'}`,
+                    ]);
+                }
+                return { success: false, exitCode: 1 };
+            }
             output.printSuccess(`Imported from ${result.inputPath}`);
             output.printList([
                 `Entries: ${result.imported.entries}`,
@@ -2014,12 +2087,13 @@ const classifyCommand = {
 export const memoryCommand = {
     name: 'memory',
     description: 'Memory management commands',
-    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, purgeCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand, backupCommand, classifyCommand, selectOperatorCommand],
+    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, purgeCommand, statsCommand, peekCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand, backupCommand, classifyCommand, selectOperatorCommand],
     options: [],
     examples: [
         { command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },
         { command: 'claude-flow memory search -q "auth patterns"', description: 'Search memory' },
-        { command: 'claude-flow memory stats', description: 'Show statistics' }
+        { command: 'claude-flow memory stats', description: 'Show statistics' },
+        { command: 'claude-flow memory peek', description: 'Read-only: which store files this cwd resolves to, rows, last write' }
     ],
     action: async (ctx) => {
         output.writeln();
@@ -2036,6 +2110,7 @@ export const memoryCommand = {
             `${output.highlight('list')}       - List memory entries`,
             `${output.highlight('delete')}     - Delete memory entry`,
             `${output.highlight('stats')}      - Show statistics`,
+            `${output.highlight('peek')}       - Read-only: resolved store files, rows, last write (creates nothing)`,
             `${output.highlight('configure')}  - Configure backend`,
             `${output.highlight('cleanup')}    - Clean expired entries`,
             `${output.highlight('compress')}   - Compress database`,

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

@@ -111,6 +111,12 @@ const runCommand = {
                     dryRun,
                 },
             });
+            const runError = toolError(result);
+            if (runError || !result.metrics) {
+                spinner.fail('Workflow failed');
+                output.printError(`Workflow error: ${runError ?? 'workflow_run returned no workflow summary'}`);
+                return { success: false, exitCode: 1 };
+            }
             if (dryRun) {
                 spinner.succeed('Workflow validated successfully');
             }
@@ -277,6 +283,11 @@ const listCommand = {
                 status: status || 'all',
                 limit,
             });
+            const listError = toolError(result);
+            if (listError || !Array.isArray(result.workflows)) {
+                output.printError(`Failed to list workflows: ${listError ?? 'workflow_list returned no workflows'}`);
+                return { success: false, exitCode: 1 };
+            }
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
                 return { success: true, data: result };
@@ -290,13 +301,19 @@ const listCommand = {
             }
             output.printTable({
                 columns: [
-                    { key: 'id', header: 'ID', width: 15 },
-                    { key: 'template', header: 'Template', width: 15 },
+                    { key: 'id', header: 'ID', width: 30 },
+                    { key: 'name', header: 'Name', width: 24 },
                     { key: 'status', header: 'Status', width: 12, format: formatStageStatus },
-                    { key: 'progress', header: 'Progress', width: 10, align: 'right', format: (v) => `${v}%` },
-                    { key: 'startedAt', header: 'Started', width: 20, format: (v) => new Date(String(v)).toLocaleString() }
+                    { key: 'steps', header: 'Steps', width: 6, align: 'right' },
+                    { key: 'createdAt', header: 'Created', width: 20, format: (v) => new Date(String(v)).toLocaleString() }
                 ],
-                data: result.workflows
+                data: result.workflows.map(w => ({
+                    id: w.workflowId,
+                    name: w.name,
+                    status: w.status,
+                    steps: w.stepCount,
+                    createdAt: w.createdAt,
+                }))
             });
             output.writeln();
             output.printInfo(`Total: ${result.total} workflows`);
@@ -335,30 +352,37 @@ const statusCommand = {
         try {
             const result = await callMCPTool('workflow_status', {
                 workflowId,
+                verbose: true,
             });
+            const statusError = toolError(result);
+            if (statusError) {
+                output.printError(`Failed to get status: ${statusError}`);
+                return { success: false, exitCode: 1 };
+            }
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
                 return { success: true, data: result };
             }
+            const started = result.startedAt ? Date.parse(result.startedAt) : NaN;
+            const ended = result.completedAt ? Date.parse(result.completedAt) : Date.now();
             output.writeln();
             output.printBox([
-                `ID: ${result.id}`,
-                `Template: ${result.template}`,
+                `ID: ${result.workflowId}`,
+                `Name: ${result.name}`,
                 `Status: ${formatStageStatus(result.status)}`,
-                `Progress: ${result.progress}%`,
-                `Duration: ${(result.metrics.duration / 1000).toFixed(1)}s`,
-                `Tokens: ${result.metrics.tokensUsed.toLocaleString()}`,
-                `Agents: ${result.metrics.agentsSpawned}`
+                `Progress: ${Math.round(result.progress)}% (${result.completedSteps}/${result.totalSteps} steps)`,
+                ...(Number.isNaN(started) ? [] : [`Duration: ${((ended - started) / 1000).toFixed(1)}s`]),
+                ...(result.error ? [`Error: ${result.error}`] : []),
             ].join('\n'), 'Workflow Status');
             output.writeln();
-            output.writeln(output.bold('Stage Progress'));
+            output.writeln(output.bold('Step Progress'));
             output.printTable({
                 columns: [
-                    { key: 'name', header: 'Stage', width: 20 },
+                    { key: 'name', header: 'Step', width: 24 },
+                    { key: 'type', header: 'Type', width: 10 },
                     { key: 'status', header: 'Status', width: 12, format: formatStageStatus },
-                    { key: 'agents', header: 'Agents', width: 25, format: (v) => Array.isArray(v) ? v.length.toString() : '0' }
                 ],
-                data: result.stages
+                data: result.steps ?? []
             });
             return { success: true, data: result };
         }
@@ -408,6 +432,11 @@ const stopCommand = {
                 workflowId,
                 graceful: !force,
             });
+            const stopError = toolError(result);
+            if (stopError || result.stopped !== true) {
+                output.printError(`Failed to stop workflow: ${stopError ?? 'the workflow was not stopped'}`);
+                return { success: false, exitCode: 1 };
+            }
             output.printSuccess(`Workflow ${workflowId} stopped`);
             return { success: true, data: result };
         }
@@ -556,6 +585,17 @@ export const workflowCommand = {
     }
 };
 // Helper functions
+/**
+ * The workflow MCP tools report failure as `{ error }` (or `{ success: false, error }`)
+ * instead of throwing, so a command that reads the result without checking it prints
+ * a false success or crashes on a field the error result does not have.
+ */
+function toolError(result) {
+    const r = result;
+    if (!r)
+        return 'the workflow tool returned no result';
+    return typeof r.error === 'string' && r.error.length > 0 ? r.error : undefined;
+}
 function formatStageStatus(status) {
     const statusStr = String(status);
     switch (statusStr) {

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

@@ -18,7 +18,7 @@ import { generatePreCommitHook, generatePostCommitHook, generateSessionManager,
 import { getInstalledCliVersion, HELPERS_STAMP_FILE } from './helper-refresh.js';
 import { generateClaudeMd } from './claudemd-generator.js';
 import { recordMemoryPackagePath } from './memory-package-resolver.js';
-import { ensureCommonJsCompanions } from './helper-companions.js';
+import { COMMONJS_COMPANION_HELPERS, ensureCommonJsCompanions } from './helper-companions.js';
 import { scanSettingsForRisk, formatRiskFindingsAsWarnings } from './settings-risk-scanner.js';
 import { AUTO_MEMORY_HOOK_TIMEOUT_S, helperHookCommand, helperScopeFor, helperStatusLineCommand, pinToUserHelpers } from './helper-commands.js';
 /**
@@ -548,10 +548,14 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 catch { }
             }
         }
-        // #3555: the refreshed hook-handler requires the .cjs companions; older
-        // installs only have session.js / memory.js, which can't load in ESM.
-        for (const name of await ensureCommonJsCompanions(path.join(targetDir, '.claude', 'helpers'))) {
-            result.created.push(`.claude/helpers/${name}`);
+        // #4198: refresh existing companions too, so upgraded hook handlers never
+        // keep obsolete session/memory logic. Generate from the CLI trust root.
+        const helpersDir = path.join(targetDir, '.claude', 'helpers');
+        const existingCompanions = new Set(COMMONJS_COMPANION_HELPERS.filter((name) => fs.existsSync(path.join(helpersDir, name))));
+        for (const name of await ensureCommonJsCompanions(helpersDir, true)) {
+            const changes = existingCompanions.has(name)
+                ? result.updated : result.created;
+            changes.push(`.claude/helpers/${name}`);
         }
         // Stamp the installed version so the startup auto-refresh treats these as
         // current (no redundant re-copy on the next command).

package/v3/@claude-flow/cli/dist/src/init/helper-companions.d.ts

@@ -1,3 +1,3 @@
 export declare const COMMONJS_COMPANION_HELPERS: readonly ["session.cjs", "memory.cjs"];
-export declare function ensureCommonJsCompanions(helpersDir: string): Promise<string[]>;
+export declare function ensureCommonJsCompanions(helpersDir: string, force?: boolean): Promise<string[]>;
 //# sourceMappingURL=helper-companions.d.ts.map

package/v3/@claude-flow/cli/dist/src/init/helper-companions.js

@@ -7,13 +7,14 @@
  * `.js` copies, which the refreshed hook-handler no longer requires, so the
  * refresh writes any missing `.cjs` companion from the CLI's own compiled
  * generators (the trust root; no external file to verify). Stale `.js` copies
- * are left in place and ignored. Existing `.cjs` files are never overwritten.
+ * are left in place and ignored. Existing `.cjs` files are preserved during
+ * startup refresh; an explicit init upgrade replaces them from the generators.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 export const COMMONJS_COMPANION_HELPERS = ['session.cjs', 'memory.cjs'];
-export async function ensureCommonJsCompanions(helpersDir) {
-    const missing = COMMONJS_COMPANION_HELPERS.filter((name) => !fs.existsSync(path.join(helpersDir, name)));
+export async function ensureCommonJsCompanions(helpersDir, force = false) {
+    const missing = COMMONJS_COMPANION_HELPERS.filter((name) => force || !fs.existsSync(path.join(helpersDir, name)));
     if (missing.length === 0)
         return [];
     const gen = await import('./helpers-generator.js');

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

@@ -30,6 +30,11 @@ export interface MCPServerOptions {
     daemonize?: boolean;
     timeout?: number;
     requestTimeoutMs?: number;
+    rateLimitPerIp?: number;
+    rateLimitWindowMs?: number;
+    rateLimitPerSession?: number;
+    rateLimitGlobalRps?: number;
+    rateLimitGlobalBurst?: number;
     /**
      * Bearer token every HTTP request must present (`Authorization: Bearer <token>`).
      * http transport only. Prefer RUFLO_MCP_HTTP_TOKEN / a token file over this

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

@@ -103,6 +103,10 @@ function processStartToken(pid) {
         return undefined;
     }
 }
+function definedFields(fields) {
+    const entries = Object.entries(fields).filter(([, value]) => value !== undefined);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
 /**
  * Hosts treated as same-machine-only for MCP HTTP tool-call authorization
  * purposes (see startHttpServer's non-loopback authorization gate below).
@@ -134,6 +138,26 @@ export function isUnauthenticatedHttpAllowed(env = process.env) {
 export function shouldRefuseUnauthenticatedHttp(host, env = process.env, authenticated = false) {
     return !isLoopbackHost(host) && !authenticated && !isUnauthenticatedHttpAllowed(env);
 }
+/** The limits @claude-flow/mcp applies when a rate limit option is unset. */
+const DEFAULT_RATE_LIMITS = {
+    rateLimitPerIp: 120,
+    rateLimitPerSession: 50,
+    rateLimitGlobalRps: 100,
+    rateLimitGlobalBurst: 200,
+};
+const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
+/**
+ * Rate limit options that are looser than the @claude-flow/mcp defaults. A
+ * shorter window counts as looser.
+ */
+function raisedRateLimits(options) {
+    const raised = Object.keys(DEFAULT_RATE_LIMITS)
+        .filter((name) => (options[name] ?? 0) > DEFAULT_RATE_LIMITS[name]);
+    if ((options.rateLimitWindowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS) < DEFAULT_RATE_LIMIT_WINDOW_MS) {
+        raised.push('rateLimitWindowMs');
+    }
+    return raised;
+}
 /** Printable ASCII without space (RFC 6750 token-ish), 16-512 chars. */
 const AUTH_TOKEN_PATTERN = /^[\x21-\x7e]{16,512}$/;
 /**
@@ -822,6 +846,15 @@ export class MCPServerManager extends EventEmitter {
                 'RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1 to acknowledge the risk and proceed ' +
                 '(e.g. when a trusted reverse proxy or network boundary already enforces auth).');
         }
+        const raised = raisedRateLimits(this.options);
+        if (raised.length > 0 && !isLoopbackHost(this.options.host) && !authToken) {
+            // RUFLO_MCP_ALLOW_UNAUTHENTICATED_HTTP=1 lets an open server start, but
+            // anyone who can reach it should not also get more than the default
+            // request budget.
+            throw new Error(`Refusing to raise MCP rate limits (${raised.join(', ')}) above the defaults on non-loopback ` +
+                `host "${this.options.host}" without a bearer token. Set RUFLO_MCP_HTTP_TOKEN (or ` +
+                '--auth-token-file), or bind to a loopback host (127.0.0.1, ::1, or localhost).');
+        }
         // Dynamically import the MCP server package
         // FIX for issue #942: Use proper package import instead of broken relative path
         const { createMCPServer } = await import('@claude-flow/mcp');
@@ -867,6 +900,12 @@ export class MCPServerManager extends EventEmitter {
             enableMetrics: true,
             enableCaching: true,
             requestTimeout: this.options.requestTimeoutMs,
+            rateLimit: definedFields({ windowMs: this.options.rateLimitWindowMs, limit: this.options.rateLimitPerIp }),
+            sessionRateLimit: definedFields({
+                requestsPerSecond: this.options.rateLimitGlobalRps,
+                burstSize: this.options.rateLimitGlobalBurst,
+                perSessionLimit: this.options.rateLimitPerSession,
+            }),
             auth: authToken
                 ? { enabled: true, method: 'token', tokens: [authToken] }
                 : undefined,

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

@@ -216,6 +216,7 @@ export const agentTools = [
             properties: {
                 agentType: { type: 'string', description: 'Type of agent to spawn' },
                 agentId: { type: 'string', description: 'Optional custom agent ID' },
+                name: { type: 'string', description: 'Optional display name for the agent (shown by agent_list, agent_status and ruflo-console)' },
                 // #2085 — accept swarmId so spawned agents register in the
                 // swarm.agents array that swarm_status reports. Omit to register
                 // with the most-recently-created swarm.
@@ -241,6 +242,18 @@ export const agentTools = [
             }
             const agentId = input.agentId || `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
             const agentType = input.agentType;
+            // #4300 — older callers (including `agent spawn` before this fix) send
+            // the name only as metadata.name.
+            const metadata = input.metadata;
+            const rawName = input.name ?? metadata?.name;
+            let name;
+            if (rawName !== undefined && rawName !== '') {
+                const vName = validateText(rawName, 'name', 200);
+                if (!vName.valid) {
+                    return { success: false, error: `Input validation failed: ${vName.error}` };
+                }
+                name = vName.sanitized;
+            }
             const config = input.config || {};
             // Add explicit model to config if provided
             if (input.model) {
@@ -262,6 +275,7 @@ export const agentTools = [
             const agent = {
                 agentId,
                 agentType,
+                ...(name ? { name } : {}),
                 status: 'idle',
                 health: 1.0,
                 taskCount: 0,
@@ -347,6 +361,7 @@ export const agentTools = [
                 success: true,
                 agentId,
                 agentType: agent.agentType,
+                ...(agent.name ? { name: agent.name } : {}),
                 model: agent.model,
                 modelRoutedBy: routingResult.routedBy,
                 ...(routingResult.modelId ? { modelId: routingResult.modelId } : {}),
@@ -501,6 +516,7 @@ export const agentTools = [
                 return {
                     agentId: agent.agentId,
                     agentType: agent.agentType,
+                    ...(agent.name ? { name: agent.name } : {}),
                     status: agent.status,
                     health: agent.health,
                     taskCount: agent.taskCount,
@@ -525,6 +541,7 @@ export const agentTools = [
             properties: {
                 status: { type: 'string', description: 'Filter by status' },
                 domain: { type: 'string', description: 'Filter by domain' },
+                agentType: { type: 'string', description: 'Filter by agent type' },
                 includeTerminated: { type: 'boolean', description: 'Include terminated agents' },
             },
         },
@@ -539,6 +556,11 @@ export const agentTools = [
                 if (!v.valid)
                     return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
             }
+            if (input.agentType) {
+                const v = validateIdentifier(input.agentType, 'agentType');
+                if (!v.valid)
+                    return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
+            }
             let agents = Object.values(loadAllAgents()); // #1916: includes hive-mind-spawned workers
             // Filter by status
             if (input.status) {
@@ -551,10 +573,15 @@ export const agentTools = [
             if (input.domain) {
                 agents = agents.filter(a => a.domain === input.domain);
             }
+            // Filter by agent type
+            if (input.agentType) {
+                agents = agents.filter(a => a.agentType === input.agentType);
+            }
             return {
                 agents: agents.map(a => ({
                     agentId: a.agentId,
                     agentType: a.agentType,
+                    ...(a.name ? { name: a.name } : {}),
                     status: a.status,
                     health: a.health,
                     taskCount: a.taskCount,
@@ -565,6 +592,7 @@ export const agentTools = [
                 filters: {
                     status: input.status,
                     domain: input.domain,
+                    agentType: input.agentType,
                     includeTerminated: input.includeTerminated,
                 },
             };