@claude-flow/cli 3.44.0 → 3.46.0

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

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.44.0",
+    "version": "3.46.0",
     "files": {
       "auto-memory-hook.mjs": "85fe05c757421c52137c0bc8545a0896bab6b4714538c2a11d1d0835bfcc8c1c",
       "hook-handler.cjs": "209d9fafe10e17d1be0866727f6f9cf9ac66f9a0793f1c793a4f58319e8e4583",
@@ -9,6 +9,6 @@
       "router.js": "b6998397e7883191b62229ccdc66fb87f1ccca1d5b2039ecb8c1e686d1ad81f8"
     }
   },
-  "signature": "vl9y84CRx7XaIXMi3iD1q3UVqeUvGsvpwjXkhMuA42myuVhCbgtnSNM9W8M3Pv9Odqy5qucwwDsz7MB7mUqDBg==",
+  "signature": "LwKXka3qAKGSIVpcv4vpg5vlv8CFHolvyCQwzW0hNvPIn7Un3+qpidc7drdoDzsrNyzx3gnZJBFEWeXxlTabDA==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -19,6 +19,8 @@
 
 # Ruflo
 
+[English](README.md) · [简体中文](README.zh-CN.md)
+
 **An agent meta-harness for Claude Code and Codex.**
 
 [![RuFlo Explained — build an AI team that plans, remembers, tests, and improves](docs/assets/ruflo-explained/ch14.jpg)](docs/ruflo-explained.md)

package/bin/cli.js

@@ -164,6 +164,8 @@ const isMCPMode = !process.stdin.isTTY
 if (isMCPMode) {
   // Run MCP server mode
   const { listMCPTools, callMCPTool, hasTool } = await import('../dist/src/mcp-client.js');
+  const { isPolicyEnforcementEnabled, loadMcpPolicy, evaluateToolCall } =
+    await import('../dist/src/mcp-tools/policy-enforcer.js');
 
   const VERSION = '3.0.0';
   const sessionId = `mcp-${Date.now()}-${randomUUID().slice(0, 8)}`;
@@ -287,6 +289,17 @@ if (isMCPMode) {
           };
         }
 
+        if (isPolicyEnforcementEnabled()) {
+          const check = evaluateToolCall(loadMcpPolicy(), sessionId, toolName);
+          if (!check.allowed) {
+            return {
+              jsonrpc: '2.0',
+              id: message.id,
+              error: { code: -32001, message: `Policy denied: ${check.reason}` },
+            };
+          }
+        }
+
         try {
           const result = await callMCPTool(toolName, toolParams, { sessionId });
           return {

package/bin/mcp-server.js

@@ -28,6 +28,11 @@ console.log = (...args) => {
 };
 
 import { listMCPTools, callMCPTool, hasTool } from '../dist/src/mcp-client.js';
+import {
+  isPolicyEnforcementEnabled,
+  loadMcpPolicy,
+  evaluateToolCall,
+} from '../dist/src/mcp-tools/policy-enforcer.js';
 
 const VERSION = '3.0.0';
 const sessionId = `mcp-${Date.now()}-${randomUUID().slice(0, 8)}`;
@@ -173,6 +178,17 @@ async function handleMessage(message) {
           };
         }
 
+        if (isPolicyEnforcementEnabled()) {
+          const check = evaluateToolCall(loadMcpPolicy(), sessionId, toolName);
+          if (!check.allowed) {
+            return {
+              jsonrpc: '2.0',
+              id: message.id,
+              error: { code: -32001, message: `Policy denied: ${check.reason}` },
+            };
+          }
+        }
+
         try {
           const result = await callMCPTool(toolName, toolParams, { sessionId });
           return {

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 6,
-  "generatedAt": "2026-09-23T18:40:54.000Z",
-  "gitSha": "0a96fb88",
+  "generatedAt": "2026-09-26T22:32:39.004Z",
+  "gitSha": "39ea61fd",
   "catalog": {
     "agents": 167,
     "tools": 418,

package/dist/src/commands/doctor.d.ts

@@ -11,7 +11,19 @@ interface HealthCheck {
     message: string;
     fix?: string;
 }
+/** ADR-122 Phase 0: probe only the CLI version, without launching a browser. */
+export declare function evaluateAgentBrowserVersion(rawOutput: string): HealthCheck;
+export declare function checkAgentBrowserVersion(probe?: () => Promise<string>): Promise<HealthCheck>;
 export declare function checkMemoryPersistenceDriver(): Promise<HealthCheck>;
+/**
+ * #3392: pure verdict for "does the @claude-flow/memory the CLI loads satisfy
+ * the range the CLI declares?". `npx @claude-flow/cli@latest` reuses one npx
+ * cache directory across CLI versions, and npm keeps an already-installed
+ * dependency that still satisfies a caret range, so a stale memory could
+ * survive a CLI upgrade with no error. Exported for unit testing.
+ */
+export declare function evaluateMemoryPackageVersion(declared: string | null, installed: string | null): HealthCheck;
+export declare function checkMemoryPackageVersion(): Promise<HealthCheck>;
 export declare const doctorCommand: Command;
 export default doctorCommand;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/src/commands/doctor.js

@@ -9,13 +9,15 @@ import { existsSync, readFileSync, statSync, openSync, readSync, closeSync } fro
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
-import { execSync, exec } from 'child_process';
+import { execSync, exec, execFile } from 'child_process';
 import { promisify } from 'util';
 import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';
 import { isEncryptedBlob } from '../encryption/vault.js';
-import { resolveMemoryPackageFromProject, readMemoryPackageVersion, recordMemoryPackagePath, } from '../init/memory-package-resolver.js';
+import * as semver from 'semver';
+import { resolveMemoryPackageFromProject, resolveMemoryPackageFromCli, readMemoryPackageVersion, recordMemoryPackagePath, } from '../init/memory-package-resolver.js';
 // Promisified exec with proper shell and env inheritance for cross-platform support
 const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 /**
  * Execute command asynchronously with proper environment inheritance
  * Critical for Windows where PATH may not be inherited properly
@@ -61,6 +63,39 @@ async function checkNpmVersion() {
         return { name: 'npm Version', status: 'fail', message: 'npm not found', fix: 'Install Node.js from https://nodejs.org' };
     }
 }
+/** ADR-122 Phase 0: probe only the CLI version, without launching a browser. */
+export function evaluateAgentBrowserVersion(rawOutput) {
+    const name = 'agent-browser CLI (ADR-122)';
+    const fix = 'npm install -g agent-browser@latest';
+    const versionOutput = rawOutput.trim().replace(/\x1b\[[0-9;]*m/g, '');
+    const match = /^(?:agent-browser(?:\s+version)?\s+)?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\s|$)/i.exec(versionOutput);
+    const version = match ? semver.parse(match[1]) : null;
+    if (!version) {
+        return { name, status: 'warn', message: `Unable to parse agent-browser version${versionOutput ? `: ${versionOutput.slice(0, 120)}` : ' (empty output)'}. Browser MCP tools may be unavailable.`, fix };
+    }
+    if (semver.lt(version, '0.27.0')) {
+        return { name, status: 'warn', message: `v${version.version} is below the ADR-122 v0.27.0 minimum for browser MCP tools`, fix };
+    }
+    return { name, status: 'pass', message: `v${version.version} meets the ADR-122 v0.27.0 minimum for browser MCP tools` };
+}
+export async function checkAgentBrowserVersion(probe = async () => {
+    const { stdout } = await execFileAsync('agent-browser', ['--version'], {
+        encoding: 'utf8', timeout: 3000, maxBuffer: 16 * 1024, windowsHide: true,
+    });
+    return String(stdout);
+}) {
+    try {
+        return evaluateAgentBrowserVersion(await probe());
+    }
+    catch (error) {
+        const name = 'agent-browser CLI (ADR-122)';
+        const fix = 'npm install -g agent-browser@latest';
+        const code = error.code;
+        return code === 'ENOENT'
+            ? { name, status: 'warn', message: 'Not found on PATH; @claude-flow/browser and browser MCP tools need agent-browser v0.27.0 or newer', fix }
+            : { name, status: 'warn', message: `Version check failed: ${error instanceof Error ? error.message : String(error)}`, fix };
+    }
+}
 // Check config file
 async function checkConfigFile() {
     // JSON configs (parse-validated). The first three are LEGACY shapes from
@@ -305,6 +340,22 @@ async function resolveMemoryDbPath() {
             return p;
     return null;
 }
+/** Native AgentDB writes to a plaintext sibling of the sql.js memory file.
+ * Probe only stores that already exist: projects without the native bridge
+ * should not acquire an extra warning just by running doctor (#3195). */
+async function existingNativeAgentDbPaths() {
+    const candidates = new Set();
+    try {
+        const { getMemoryRoot, resolveDbPath } = await import('../memory/memory-initializer.js');
+        candidates.add(join(getMemoryRoot(), 'agentdb-memory.db'));
+        // Explicit CLAUDE_FLOW_DB_PATH callers may put the sibling elsewhere.
+        candidates.add(join(dirname(resolveDbPath()), 'agentdb-memory.db'));
+    }
+    catch {
+        candidates.add(join(process.cwd(), '.swarm', 'agentdb-memory.db'));
+    }
+    return [...candidates].filter((path) => existsSync(path));
+}
 /** Open a sql.js Database over an on-disk file, returning null when the
  * file can't be opened as a SQLite database (encrypted / corrupted / not
  * a database). Callers decide whether that's warn or fail. */
@@ -506,6 +557,79 @@ async function checkMemoryStructuralIntegrity() {
         catch { /* best-effort */ }
     }
 }
+/** Check the AgentDB authority independently from the legacy memory.db.
+ * Opening read-only with SQLite keeps WAL commits visible without mutating
+ * either store; the existing legacy health checks retain their own scope. */
+async function checkNativeAgentDbStructuralIntegrity(dbPath) {
+    const NAME = 'Native AgentDB Structural Integrity (quick_check)';
+    if (!existsSync(dbPath)) {
+        return { name: NAME, status: 'warn', message: `${dbPath} disappeared before the native check could run` };
+    }
+    if (isMemoryDbEncryptedAtRest(dbPath)) {
+        return {
+            name: NAME,
+            status: 'fail',
+            message: `${dbPath} — RFE1-encrypted; native AgentDB requires a plaintext SQLite file`,
+            fix: `back up ${dbPath} and restore a usable native AgentDB database`,
+        };
+    }
+    let Database;
+    try {
+        Database = (await import('better-sqlite3')).default;
+    }
+    catch {
+        return {
+            name: NAME,
+            status: 'warn',
+            message: `${dbPath} — better-sqlite3 not installed; native AgentDB structural health is unverified`,
+            fix: 'install better-sqlite3 with npm install scripts enabled, then rerun this check',
+        };
+    }
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    }
+    catch (error) {
+        if (isNativeSqliteBindingUnavailable(error)) {
+            return nativeBindingUnavailableCheck(NAME, dbPath, error, '[native AgentDB structural health unverified]');
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: NAME,
+            status: 'fail',
+            message: `${dbPath} — better-sqlite3 failed to open: ${message} [native AgentDB]`,
+            fix: `back up ${dbPath} and its WAL sidecars, then restore a known-good native AgentDB database`,
+        };
+    }
+    try {
+        const rows = db.pragma('quick_check');
+        const values = rows.map((row) => String(Object.values(row)[0]));
+        if (values.length === 1 && values[0] === 'ok') {
+            return { name: NAME, status: 'pass', message: `${dbPath} — PRAGMA quick_check: ok [native AgentDB, WAL-aware]` };
+        }
+        return {
+            name: NAME,
+            status: 'fail',
+            message: `${dbPath} — PRAGMA quick_check: ${values.slice(0, 3).join('; ')}${values.length > 3 ? ` (+${values.length - 3} more)` : ''} [native AgentDB]`,
+            fix: `back up ${dbPath} and its WAL sidecars, then restore a known-good native AgentDB database`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: NAME,
+            status: 'fail',
+            message: `${dbPath} — quick_check probe threw: ${message} [native AgentDB]`,
+            fix: `back up ${dbPath} and its WAL sidecars, then restore a known-good native AgentDB database`,
+        };
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* best-effort */ }
+    }
+}
 // #2968/#3321 — read-only native SQLite capability probe. A skipped
 // postinstall can leave the wrapper importable but its binding unavailable.
 // Schema size cannot identify the runtime driver or the database's history:
@@ -1045,6 +1169,70 @@ async function checkLearningBridge() {
         fix: 'npm i -D @claude-flow/memory   (optional dep appears absent — likely --omit=optional install)',
     };
 }
+/**
+ * #3392: pure verdict for "does the @claude-flow/memory the CLI loads satisfy
+ * the range the CLI declares?". `npx @claude-flow/cli@latest` reuses one npx
+ * cache directory across CLI versions, and npm keeps an already-installed
+ * dependency that still satisfies a caret range, so a stale memory could
+ * survive a CLI upgrade with no error. Exported for unit testing.
+ */
+export function evaluateMemoryPackageVersion(declared, installed) {
+    const NAME = '@claude-flow/memory version';
+    if (!declared) {
+        return { name: NAME, status: 'warn', message: 'could not read the @claude-flow/memory range declared by @claude-flow/cli' };
+    }
+    if (!installed) {
+        return {
+            name: NAME,
+            status: 'warn',
+            message: `@claude-flow/memory is not resolvable from the CLI (declared ${declared}) — memory features fall back to degraded paths`,
+            fix: `npm install @claude-flow/memory@${declared} --include=optional`,
+        };
+    }
+    if (!semver.validRange(declared) || !semver.valid(installed)) {
+        return { name: NAME, status: 'warn', message: `cannot compare installed ${installed} against declared ${declared}` };
+    }
+    if (semver.satisfies(installed, declared, { includePrerelease: true })) {
+        return { name: NAME, status: 'pass', message: `v${installed} satisfies declared ${declared}` };
+    }
+    // warn, not fail: a dev/hoisted layout can legitimately differ, and doctor's
+    // exit code must not depend on which copy a package manager happened to hoist.
+    return {
+        name: NAME,
+        status: 'warn',
+        message: `installed v${installed} does not satisfy declared ${declared} — a stale cached copy is running, so fixes shipped in a newer @claude-flow/memory are silently absent`,
+        fix: `rm -rf "$(npm config get cache)/_npx" && npx @claude-flow/cli@latest doctor   # or: npm install @claude-flow/memory@${declared}`,
+    };
+}
+export async function checkMemoryPackageVersion() {
+    try {
+        // Walk up from this module to the CLI package root (npx cache, global,
+        // project-local and monorepo dev all resolve the same way).
+        let declared = null;
+        let dir = dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 8 && declared === null; i++) {
+            const pj = join(dir, 'package.json');
+            if (existsSync(pj)) {
+                try {
+                    const pkg = JSON.parse(readFileSync(pj, 'utf-8'));
+                    if (pkg.name === '@claude-flow/cli') {
+                        declared = pkg.optionalDependencies?.['@claude-flow/memory'] ?? pkg.dependencies?.['@claude-flow/memory'] ?? null;
+                        break;
+                    }
+                }
+                catch { /* keep walking */ }
+            }
+            dir = dirname(dir);
+        }
+        // Resolve exactly as the CLI's own runtime does (its module context),
+        // not from process.cwd() — that would report the project's copy instead.
+        const distPath = resolveMemoryPackageFromCli();
+        return evaluateMemoryPackageVersion(declared, distPath ? readMemoryPackageVersion(distPath) : null);
+    }
+    catch (err) {
+        return { name: '@claude-flow/memory version', status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 // Check API keys
 async function checkApiKeys() {
     const keys = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'OPENAI_API_KEY'];
@@ -2272,7 +2460,7 @@ export const doctorCommand = {
         {
             name: 'component',
             short: 'c',
-            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, mcp-overhead, claude, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, typesafe, metaharness)',
+            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, mcp-overhead, claude, browser, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, typesafe, metaharness)',
             type: 'string'
         },
         {
@@ -2379,11 +2567,14 @@ export const doctorCommand = {
         output.writeln(output.dim('System diagnostics and health check'));
         output.writeln(output.dim('─'.repeat(50)));
         output.writeln();
+        const nativeAgentDbChecks = (await existingNativeAgentDbPaths())
+            .map((dbPath) => () => checkNativeAgentDbStructuralIntegrity(dbPath));
         const allChecks = [
             checkVersionFreshness,
             checkNodeVersion,
             checkNpmVersion,
             checkClaudeCode,
+            checkAgentBrowserVersion, // ADR-122 Phase 0 — browser runtime compatibility
             checkGit,
             checkGitRepo,
             checkConfigFile,
@@ -2391,8 +2582,10 @@ export const doctorCommand = {
             checkDaemonStatus,
             checkMemoryDatabase,
             checkMemoryStructuralIntegrity, // #2737 — bounded, native quick_check on every default run
+            ...nativeAgentDbChecks, // #3195 — verify each present native authority file
             checkMemoryPersistenceDriver, // #2968/#3321 — read-only native capability probe
             checkLearningBridge, // #2545 — can the auto-memory hook actually load @claude-flow/memory?
+            checkMemoryPackageVersion, // #3392 — loaded @claude-flow/memory must satisfy the CLI's declared range
             checkApiKeys,
             checkMcpServers,
             checkMcpSchemaOverhead, // #2726 — fixed tools/list prompt cost
@@ -2423,18 +2616,22 @@ export const doctorCommand = {
             'node': checkNodeVersion,
             'npm': checkNpmVersion,
             'claude': checkClaudeCode,
+            'browser': checkAgentBrowserVersion,
             'config': checkConfigFile,
             'stale-settings': checkStaleSettingsNpx, // #2448
             'daemon': checkDaemonStatus,
             'memory': [
                 checkMemoryDatabase, // existing: exists + statable (unchanged)
                 checkMemoryIntegrity, // #2677 check 1: sql.js open + PRAGMA integrity_check
+                ...nativeAgentDbChecks, // #3195: present AgentDB authority, checked independently
                 checkMemoryPersistenceDriver, // #2968/#3321: read-only native capability probe
+                checkMemoryPackageVersion, // #3392: loaded memory package satisfies the declared range
                 checkMemoryContent, // #2677 check 2: memory_entries content coverage
                 checkMemoryEmbeddingCoverage, // #2677 check 3: vector coverage on populated rows
                 checkMemoryReflexionCoverage, // #2677 check 6: episodes are retrievable
                 checkMemoryCritiqueCoverage, // #2677 check 6: feedback carries lessons
             ],
+            'memory-package': checkMemoryPackageVersion, // #3392
             'learning': checkLearningBridge, // #2545
             'learning-bridge': checkLearningBridge, // #2545
             'api': checkApiKeys,

package/dist/src/commands/embeddings.js

@@ -679,7 +679,12 @@ const initCommand = {
             if (!fs.existsSync(modelDir)) {
                 fs.mkdirSync(modelDir, { recursive: true });
             }
-            // Download model if requested
+            // Download model if requested. #3376: record what actually happened
+            // instead of assuming the download ran — `getEmbeddings()` returns null
+            // whenever the optional @claude-flow/embeddings package is absent, which
+            // is every plain `npm i -g ruflo` install.
+            let modelDownloaded = false;
+            let modelSkipReason = null;
             if (download) {
                 spinner.setText(`Downloading ONNX model: ${model}...`);
                 const embeddings = await getEmbeddings();
@@ -687,13 +692,19 @@ const initCommand = {
                     await embeddings.downloadEmbeddingModel(model, modelDir, (p) => {
                         spinner.setText(`Downloading ${model}... ${p.percent.toFixed(0)}%`);
                     });
+                    modelDownloaded = true;
                 }
                 else {
-                    // Embeddings package not available — skip download
-                    await new Promise(r => setTimeout(r, 500));
-                    output.writeln(output.dim('  (Skipped — @claude-flow/embeddings not installed)'));
+                    // No download happened. That is the outcome of this command, not an
+                    // aside — reported below via spinner.fail + a warning, never as a
+                    // dimmed note on a success path. No fake progress delay: there is
+                    // nothing in progress.
+                    modelSkipReason = '@claude-flow/embeddings is not installed';
                 }
             }
+            else {
+                modelSkipReason = 'download disabled by --no-download';
+            }
             // Write embeddings config
             spinner.setText('Writing configuration...');
             const dimension = model.includes('mpnet') ? 768 : 384;
@@ -702,6 +713,12 @@ const initCommand = {
                 modelPath: modelDir,
                 dimension,
                 cacheSize,
+                // #3376: additive, optional fields. `modelPath` keeps its old meaning
+                // (the directory the model belongs in), but it no longer implies a
+                // model is in it — `modelDownloaded` says whether one is. Readers that
+                // predate these keys are unaffected; they ignore unknown properties.
+                modelDownloaded,
+                ...(modelSkipReason ? { modelSkipReason } : {}),
                 hyperbolic: {
                     enabled: hyperbolic,
                     curvature,
@@ -716,7 +733,15 @@ const initCommand = {
                 initialized: new Date().toISOString(),
             };
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-            spinner.succeed('Embedding subsystem initialized');
+            // A download that was asked for and did not happen is a failed init:
+            // the only substantive step of `embeddings init` did not run. #3376.
+            const downloadSkipped = download && !modelDownloaded;
+            if (downloadSkipped) {
+                spinner.fail('Embedding model NOT downloaded — embedding subsystem is not ready');
+            }
+            else {
+                spinner.succeed('Embedding subsystem initialized');
+            }
             output.writeln();
             output.printTable({
                 columns: [
@@ -725,6 +750,7 @@ const initCommand = {
                 ],
                 data: [
                     { setting: 'Model', value: model },
+                    { setting: 'Model Status', value: modelDownloaded ? output.success('Downloaded') : output.error('NOT downloaded') },
                     { setting: 'Dimension', value: String(dimension) },
                     { setting: 'Cache Size', value: String(cacheSize) + ' entries' },
                     { setting: 'Hyperbolic', value: hyperbolic ? `${output.success('Enabled')} (c=${curvature})` : output.dim('Disabled') },
@@ -733,6 +759,20 @@ const initCommand = {
                     { setting: 'Config', value: configPath },
                 ],
             });
+            if (downloadSkipped) {
+                output.writeln();
+                output.printWarning(`No embedding model was installed: ${modelSkipReason}.`);
+                output.printWarning('Until a real embedder is present, embeddings fall back to hash vectors, which carry no semantic meaning.');
+                output.printInfo(`Configuration was still written to ${configPath}, recording "modelDownloaded": false.`);
+                output.writeln();
+                output.writeln(output.dim('To finish initializing:'));
+                output.printList([
+                    'npm install @claude-flow/embeddings   - the package this command downloads with; then: embeddings init --force',
+                    'npm install ruvector                  - the other real embedder ruflo accepts; needs no download step',
+                    'embeddings init --no-download --force - keep this configuration without a model (exits 0)',
+                ]);
+                return { success: false, exitCode: 1, data: config };
+            }
             output.writeln();
             if (hyperbolic) {
                 output.printBox([
@@ -1182,8 +1222,11 @@ const modelsCommand = {
                 }
             }
             else {
-                await new Promise(r => setTimeout(r, 500));
-                spinner.succeed(`Download skipped — @claude-flow/embeddings not installed`);
+                // #3376, same class as `init`: nothing was downloaded, so this is a
+                // failure, not a success with a caveat. No fake progress delay either.
+                spinner.fail(`Download skipped — @claude-flow/embeddings is not installed`);
+                output.printWarning(`"${download}" was not downloaded. Install @claude-flow/embeddings to enable model downloads.`);
+                return { success: false, exitCode: 1 };
             }
             return { success: true };
         }

package/dist/src/commands/init.js

@@ -113,7 +113,9 @@ export function runCodexInitializerCli(cwd, options) {
 // init) and scripted `--format json` output.
 async function maybeAutoDetectCodex(ctx, options) {
     try {
-        if (ctx.flags['no-codex-detect'] === true)
+        // The CLI parser turns `--no-codex-detect` into `codexDetect: false`.
+        // Retain the literal key for programmatic CommandContext callers.
+        if (ctx.flags.codexDetect === false || ctx.flags['no-codex-detect'] === true)
             return;
         if (ctx.flags.format === 'json')
             return; // scripted output stays pure
@@ -295,7 +297,8 @@ function isBloatedRufloSkillDir(dir) {
 }
 async function maybeInstallSkillsSh(ctx) {
     try {
-        if (ctx.flags['no-skills-sh'] === true)
+        // The CLI parser turns `--no-skills-sh` into `skillsSh: false`.
+        if (ctx.flags.skillsSh === false || ctx.flags['no-skills-sh'] === true)
             return;
         if (ctx.flags.format === 'json')
             return;

package/dist/src/commands/mcp.js

@@ -66,6 +66,11 @@ const startCommand = {
             description: 'Tools to advertise (comma-separated categories, prefixes, exact names, or "all")',
             type: 'string'
         },
+        {
+            name: 'request-timeout-ms',
+            description: 'HTTP request timeout in milliseconds (default 30000; env RUFLO_MCP_REQUEST_TIMEOUT_MS)',
+            type: 'number'
+        },
         {
             name: 'daemon',
             short: 'd',
@@ -84,6 +89,7 @@ const startCommand = {
     examples: [
         { 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 -d', description: 'Start as daemon' },
         { command: 'claude-flow mcp start -f', description: 'Force restart (kill existing)' }
     ],
@@ -94,6 +100,15 @@ 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)) {
+            output.printError('Request timeout must be an integer from 1 to 3600000 milliseconds');
+            return { success: false, exitCode: 1 };
+        }
         const daemon = ctx.flags.daemon ?? false;
         const force = ctx.flags.force ?? false;
         output.writeln();
@@ -104,10 +119,17 @@ const startCommand = {
         // PID file exists, which would cause us to SIGKILL ourselves)
         const existingStatus = await getMCPServerStatus();
         const isSelfDetected = existingStatus.pid === process.pid;
-        if (existingStatus.running && !isSelfDetected) {
-            // For stdio transport, always force restart since we can't health check it
-            // For other transports, check health unless --force is specified
-            const shouldForceRestart = force || transport === 'stdio';
+        // #3364: only a port-bound transport (http/websocket) is single-instance.
+        // A stdio server belongs to the client that spawned it, over that client's
+        // own pipes, and any number run side by side. The PID file is a single
+        // slot per os.tmpdir(), so for stdio "already running" only ever meant
+        // "some other server is recorded" — and force-restarting SIGKILLed it
+        // (another terminal's stdio server, or a live http server). Stdio now
+        // kills a recorded server only when explicitly asked with --force.
+        const isSingleInstance = transport !== 'stdio';
+        if (existingStatus.running && !isSelfDetected && (isSingleInstance || force)) {
+            // --force always restarts; otherwise check health (http/websocket)
+            const shouldForceRestart = force;
             if (!shouldForceRestart) {
                 // Verify the server is actually healthy/responsive
                 const manager = getServerManager();
@@ -143,6 +165,7 @@ const startCommand = {
             host,
             port,
             tools: !tools || tools === 'all' ? 'all' : tools.split(','),
+            ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
             daemonize: daemon,
         };
         try {