moflo 4.8.0 → 4.8.1

package/.claude/settings.local.json

@@ -8,7 +8,10 @@
       "Bash(tasklist.exe /FI \"IMAGENAME eq node.exe\" /V)",
       "Bash(powershell.exe -NoProfile -Command \"Get-Process node -ErrorAction SilentlyContinue | Select-Object Id,ProcessName,StartTime,CommandLine | Format-Table -AutoSize\")",
       "Bash(npm version:*)",
-      "Bash(gh pr:*)"
+      "Bash(gh pr:*)",
+      "mcp__claude-flow__memory_store",
+      "mcp__claude-flow__memory_retrieve",
+      "mcp__claude-flow__memory_search"
     ]
   }
 }

package/.claude/workflow-state.json

@@ -1,9 +1,5 @@
 {
-  "tasksCreated": false,
-  "taskCount": 0,
-  "memorySearched": false,
-  "memoryRequired": true,
-  "interactionCount": 10,
-  "sessionStart": null,
-  "lastBlockedAt": "2026-03-21T05:00:01.929Z"
+  "tasksCreated": true,
+  "taskCount": 1,
+  "memorySearched": true
 }

package/README.md

@@ -4,6 +4,8 @@
 
 # MoFlo
 
+**⚠️ MoFlo is experimental software. APIs, commands, and behavior may change without notice.**
+
 **An opinionated fork of [Ruflo/Claude Flow](https://github.com/ruvnet/ruflo), optimized for local development.**
 
 MoFlo adds automatic code and guidance cataloging along with memory gating on top of the original Ruflo/Claude Flow orchestration engine. Where the upstream project provides raw building blocks, MoFlo ships opinionated defaults — workflow gates that enforce memory-first patterns, semantic indexing that runs at session start, and learned routing that improves over time — so you get a productive setup from `flo init` without manual tuning.
@@ -30,7 +32,7 @@ MoFlo makes deliberate choices so you don't have to:
 - **Task registration before agents** — Sub-agents can't spawn until work is tracked. Prevents runaway agent proliferation.
 - **Learned routing** — Task outcomes feed back into the routing system automatically. No manual configuration needed — it gets smarter with use.
 - **Incremental indexing** — Guidance and code map indexes run on every session start but skip unchanged files. Fast after the first run.
-- **AI client agnostic** — Works with any MCP-capable AI client. We develop and test with Claude Code, but the MCP tools, memory system, and hooks are client-independent.
+- **Built for Claude Code, works with others** — We develop and test exclusively with Claude Code. The MCP tools, memory system, and hooks are client-independent and should work with any MCP-capable AI client, but Claude Code is the only tested target.
 - **GitHub-oriented** — The `/flo` skill, PR workflows, and issue tracking are built around GitHub. With Claude's help, you can adapt them to your own issue tracker and source control system.
 - **Cross-platform** — Forward-slash path normalization, no `sh -c` shell commands, `windowsHide` on all spawn calls.
 

package/bin/build-embeddings.mjs

@@ -20,7 +20,8 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { resolve, dirname } from 'path';
-import initSqlJs from 'sql.js';
+import { mofloResolveURL } from './lib/moflo-resolve.mjs';
+const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 function findProjectRoot() {
   let dir = process.cwd();
@@ -227,7 +228,7 @@ async function loadTransformersModel() {
   log('Attempting to load Transformers.js neural model...');
 
   try {
-    const { env, pipeline: createPipeline } = await import('@xenova/transformers');
+    const { env, pipeline: createPipeline } = await import(mofloResolveURL('@xenova/transformers'));
     env.allowLocalModels = false;
     env.backends.onnx.wasm.numThreads = 1;
 
@@ -310,6 +311,25 @@ function updateEmbedding(db, id, embedding, model) {
   stmt.free();
 }
 
+function getNamespaceStats(db) {
+  const stmt = db.prepare(`
+    SELECT
+      namespace,
+      COUNT(*) as total,
+      SUM(CASE WHEN embedding IS NOT NULL AND embedding != '' AND embedding_model != 'domain-aware-hash-v1' THEN 1 ELSE 0 END) as vectorized,
+      SUM(CASE WHEN embedding IS NULL OR embedding = '' THEN 1 ELSE 0 END) as missing,
+      SUM(CASE WHEN embedding_model = 'domain-aware-hash-v1' THEN 1 ELSE 0 END) as hash_only
+    FROM memory_entries
+    WHERE status = 'active'
+    GROUP BY namespace
+    ORDER BY namespace
+  `);
+  const results = [];
+  while (stmt.step()) results.push(stmt.getAsObject());
+  stmt.free();
+  return results;
+}
+
 function getEmbeddingStats(db) {
   const stmtTotal = db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE status = 'active'`);
   const total = stmtTotal.step() ? stmtTotal.getAsObject() : { cnt: 0 };
@@ -426,7 +446,6 @@ async function main() {
       }
     }
   }
-  db.close();
 
   console.log('');
   log('═══════════════════════════════════════════════════════════');
@@ -445,7 +464,44 @@ async function main() {
       log(`    - ${m.embedding_model}: ${m.cnt}`);
     }
   }
+  log('');
+
+  // Per-namespace health report
+  const nsStats = getNamespaceStats(db);
+  if (nsStats.length > 0) {
+    log('  Namespace Health:');
+    log('  ┌─────────────────┬───────┬────────────┬─────────┬───────────┐');
+    log('  │ Namespace       │ Total │ Vectorized │ Missing │ Hash-Only │');
+    log('  ├─────────────────┼───────┼────────────┼─────────┼───────────┤');
+    let hasWarnings = false;
+    for (const ns of nsStats) {
+      const name = String(ns.namespace).padEnd(15);
+      const total = String(ns.total).padStart(5);
+      const vectorized = String(ns.vectorized).padStart(10);
+      const missing = String(ns.missing).padStart(7);
+      const hashOnly = String(ns.hash_only).padStart(9);
+      const warn = (ns.missing > 0 || ns.hash_only > 0) ? ' ⚠' : '  ';
+      log(`  │ ${name} │${total} │${vectorized} │${missing} │${hashOnly} │${warn}`);
+      if (ns.missing > 0 || ns.hash_only > 0) hasWarnings = true;
+    }
+    log('  └─────────────────┴───────┴────────────┴─────────┴───────────┘');
+    if (hasWarnings) {
+      log('');
+      log('  ⚠ Some namespaces have entries without Xenova embeddings.');
+      log('  Run with --force to re-embed all entries:');
+      log('    node node_modules/moflo/bin/build-embeddings.mjs --force');
+      if (!useTransformers) {
+        log('');
+        log('  ⚠ Xenova model not available — using hash fallback.');
+        log('  Install @xenova/transformers for neural embeddings:');
+        log('    npm install @xenova/transformers');
+      }
+    }
+  }
+
   log('═══════════════════════════════════════════════════════════');
+
+  db.close();
 }
 
 main().catch(err => {

package/bin/generate-code-map.mjs

@@ -30,7 +30,9 @@ import { resolve, dirname, relative, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { execSync, spawn } from 'child_process';
-import initSqlJs from 'sql.js';
+import { mofloResolveURL } from './lib/moflo-resolve.mjs';
+const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
+
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 

package/bin/index-guidance.mjs

@@ -25,7 +25,9 @@
 import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
 import { resolve, dirname, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
-import initSqlJs from 'sql.js';
+import { mofloResolveURL } from './lib/moflo-resolve.mjs';
+const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
+
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 

package/bin/lib/moflo-resolve.mjs

@@ -0,0 +1,14 @@
+/**
+ * Shared dependency resolver for moflo bin scripts.
+ * Resolves packages from moflo's own node_modules (not the consuming project's).
+ * On Windows, converts native paths to file:// URLs required by ESM import().
+ */
+
+import { createRequire } from 'module';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __require = createRequire(fileURLToPath(import.meta.url));
+
+export function mofloResolveURL(specifier) {
+  return pathToFileURL(__require.resolve(specifier)).href;
+}

package/bin/semantic-search.mjs

@@ -16,7 +16,8 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
-import initSqlJs from 'sql.js';
+import { mofloResolveURL } from './lib/moflo-resolve.mjs';
+const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 function findProjectRoot() {
   let dir = process.cwd();
@@ -34,6 +35,8 @@ const DB_PATH = resolve(projectRoot, '.swarm/memory.db');
 const EMBEDDING_DIMS = 384;
 const EMBEDDING_MODEL_NEURAL = 'Xenova/all-MiniLM-L6-v2';
 const EMBEDDING_MODEL_HASH = 'domain-aware-hash-v1';
+// 'onnx' is a legacy alias for the Xenova model — treat them as compatible vector spaces
+const NEURAL_ALIASES = new Set([EMBEDDING_MODEL_NEURAL, 'onnx']);
 
 // Parse args
 const args = process.argv.slice(2);
@@ -58,7 +61,7 @@ let useTransformers = false;
 
 async function loadTransformersModel() {
   try {
-    const { env, pipeline: createPipeline } = await import('@xenova/transformers');
+    const { env, pipeline: createPipeline } = await import(mofloResolveURL('@xenova/transformers'));
     env.allowLocalModels = false;
     env.backends.onnx.wasm.numThreads = 1;
 
@@ -251,7 +254,8 @@ async function generateQueryEmbedding(queryText, db) {
   if (debug) console.error(`[semantic-search] Stored model: ${storedModel}`);
 
   // If stored embeddings are neural, try to use neural for query too
-  if (storedModel === EMBEDDING_MODEL_NEURAL) {
+  // Accept both canonical name and legacy 'onnx' tag (both use the same Xenova pipeline)
+  if (storedModel === EMBEDDING_MODEL_NEURAL || storedModel === 'onnx') {
     await loadTransformersModel();
     if (useTransformers) {
       const neuralEmb = await generateNeuralEmbedding(queryText);
@@ -325,8 +329,9 @@ async function semanticSearch(queryText, options = {}) {
   while (stmt.step()) {
     const entry = stmt.getAsObject();
     try {
-      // Skip entries with mismatched embedding model (incompatible vector spaces)
-      if (entry.embedding_model && entry.embedding_model !== queryModel) continue;
+      const storedIsNeural = NEURAL_ALIASES.has(entry.embedding_model);
+      const queryIsNeural = NEURAL_ALIASES.has(queryModel);
+      if (entry.embedding_model && entry.embedding_model !== queryModel && !(storedIsNeural && queryIsNeural)) continue;
 
       const embedding = JSON.parse(entry.embedding);
       if (!Array.isArray(embedding) || embedding.length !== EMBEDDING_DIMS) continue;

package/bin/session-start-launcher.mjs

@@ -120,6 +120,20 @@ try {
         }
       }
 
+      // Sync guidance bootstrap file (moflo-bootstrap.md)
+      // Ensures subagents can read guidance directly from disk
+      const bootstrapSrc = resolve(projectRoot, 'node_modules/moflo/.claude/guidance/agent-bootstrap.md');
+      const guidanceDir = resolve(projectRoot, '.claude/guidance');
+      const bootstrapDest = resolve(guidanceDir, 'moflo-bootstrap.md');
+      if (existsSync(bootstrapSrc)) {
+        try {
+          if (!existsSync(guidanceDir)) mkdirSync(guidanceDir, { recursive: true });
+          const header = '<!-- AUTO-GENERATED by moflo session-start. Do not edit — changes will be overwritten. -->\n<!-- Source: node_modules/moflo/.claude/guidance/agent-bootstrap.md -->\n\n';
+          const content = readFileSync(bootstrapSrc, 'utf-8');
+          writeFileSync(bootstrapDest, header + content);
+        } catch { /* non-fatal */ }
+      }
+
       // Write version stamp
       try {
         const cfDir = resolve(projectRoot, '.claude-flow');
@@ -132,6 +146,20 @@ try {
   // Non-fatal — scripts will still work, just may be stale
 }
 
+// ── 3b. Ensure guidance bootstrap file exists (even without version change) ──
+// Subagents need this file on disk for direct reads without memory search.
+try {
+  const bootstrapSrc = resolve(projectRoot, 'node_modules/moflo/.claude/guidance/agent-bootstrap.md');
+  const guidanceDir = resolve(projectRoot, '.claude/guidance');
+  const bootstrapDest = resolve(guidanceDir, 'moflo-bootstrap.md');
+  if (existsSync(bootstrapSrc) && !existsSync(bootstrapDest)) {
+    if (!existsSync(guidanceDir)) mkdirSync(guidanceDir, { recursive: true });
+    const header = '<!-- AUTO-GENERATED by moflo session-start. Do not edit — changes will be overwritten. -->\n<!-- Source: node_modules/moflo/.claude/guidance/agent-bootstrap.md -->\n\n';
+    const content = readFileSync(bootstrapSrc, 'utf-8');
+    writeFileSync(bootstrapDest, header + content);
+  }
+} catch { /* non-fatal */ }
+
 // ── 4. Spawn background tasks ───────────────────────────────────────────────
 const localCli = resolve(projectRoot, 'node_modules/moflo/src/@claude-flow/cli/bin/cli.js');
 const hasLocalCli = existsSync(localCli);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.0",
+  "version": "4.8.1",
   "description": "MoFlo — AI agent orchestration for Claude Code. Forked from ruflo/claude-flow with patches applied to source, plus feature-level orchestration.",
   "main": "dist/index.js",
   "type": "module",
@@ -62,8 +62,8 @@
   "dependencies": {
     "@ruvector/learning-wasm": "^0.1.29",
     "js-yaml": "^4.1.1",
-    "semver": "^7.6.0",
-    "sql.js": "^1.12.0",
+    "semver": "^7.7.4",
+    "sql.js": "^1.14.1",
     "zod": "^3.22.4"
   },
   "optionalDependencies": {
@@ -81,11 +81,11 @@
   },
   "devDependencies": {
     "@types/bcrypt": "^5.0.2",
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.19.37",
     "eslint": "^8.0.0",
-    "moflo": "^4.7.4",
+    "moflo": "^4.8.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.0.0",
+    "typescript": "^5.9.3",
     "vitest": "^4.0.0"
   },
   "engines": {

package/src/@claude-flow/cli/dist/src/appliance/ruvllm-bridge.js

@@ -14,6 +14,7 @@
  */
 import { readdir, stat } from 'node:fs/promises';
 import { join, extname, basename } from 'node:path';
+import { mofloImport } from '../services/moflo-require.js';
 const DEFAULT_CONFIG = {
     modelsDir: './models', defaultModel: '', maxTokens: 512,
     temperature: 0.7, contextSize: 4096, kvCachePath: '', verbose: false,
@@ -281,12 +282,7 @@ export function getRuvllmBridge(config) {
 export function resetRuvllmBridge() { instance = null; }
 /** Check whether @ruvector/core is importable without loading the bridge. */
 export async function isRuvllmAvailable() {
-    try {
-        await import('@ruvector/core');
-        return true;
-    }
-    catch {
-        return false;
-    }
+    const mod = await mofloImport('@ruvector/core');
+    return mod !== null;
 }
 //# sourceMappingURL=ruvllm-bridge.js.map

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

@@ -10,6 +10,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync, exec } from 'child_process';
 import { promisify } from 'util';
+import { getDaemonLockHolder, releaseDaemonLock } from '../services/daemon-lock.js';
 // Promisified exec with proper shell and env inheritance for cross-platform support
 const execAsync = promisify(exec);
 /**
@@ -406,6 +407,69 @@ async function checkAgenticFlow() {
         return { name: 'agentic-flow', status: 'warn', message: 'Check failed' };
     }
 }
+// Find and optionally kill orphaned moflo/claude-flow node processes
+async function findZombieProcesses(kill = false) {
+    const legitimatePid = getDaemonLockHolder(process.cwd());
+    const currentPid = process.pid;
+    const parentPid = process.ppid;
+    const found = [];
+    let killed = 0;
+    try {
+        if (process.platform === 'win32') {
+            // Windows: use WMIC to find node processes with moflo/claude-flow in command line
+            const result = execSync('powershell -NoProfile -Command "Get-CimInstance Win32_Process -Filter \\"Name=\'node.exe\'\\" | Select-Object ProcessId,CommandLine | Format-Table -AutoSize -Wrap"', { encoding: 'utf-8', timeout: 10000, windowsHide: true });
+            const lines = result.split('\n');
+            for (const line of lines) {
+                if (/moflo|claude-flow|flo\s+(hooks|gate|mcp|daemon)/i.test(line)) {
+                    const pidMatch = line.match(/^\s*(\d+)/);
+                    if (pidMatch) {
+                        const pid = parseInt(pidMatch[1], 10);
+                        // Skip our own process, parent, and the legitimate daemon
+                        if (pid === currentPid || pid === parentPid || pid === legitimatePid)
+                            continue;
+                        found.push(pid);
+                    }
+                }
+            }
+        }
+        else {
+            // Unix/macOS: use ps to find node processes
+            const result = execSync('ps aux | grep -E "node.*(moflo|claude-flow)" | grep -v grep', { encoding: 'utf-8', timeout: 5000 });
+            const lines = result.trim().split('\n');
+            for (const line of lines) {
+                const parts = line.trim().split(/\s+/);
+                const pid = parseInt(parts[1], 10);
+                if (pid === currentPid || pid === parentPid || pid === legitimatePid)
+                    continue;
+                found.push(pid);
+            }
+        }
+    }
+    catch {
+        // No matches found (grep exits non-zero) or command failed
+    }
+    if (kill && found.length > 0) {
+        for (const pid of found) {
+            try {
+                if (process.platform === 'win32') {
+                    execSync(`taskkill /F /PID ${pid}`, { timeout: 5000, windowsHide: true });
+                }
+                else {
+                    process.kill(pid, 'SIGKILL');
+                }
+                killed++;
+            }
+            catch {
+                // Process may have already exited
+            }
+        }
+        // Clean up stale daemon lock if we killed the holder
+        if (legitimatePid && found.includes(legitimatePid)) {
+            releaseDaemonLock(process.cwd(), legitimatePid, true);
+        }
+    }
+    return { found: found.length, killed, pids: found };
+}
 // Format health check result
 function formatCheck(check) {
     const icon = check.status === 'pass' ? output.success('✓') :
@@ -444,12 +508,20 @@ export const doctorCommand = {
             description: 'Verbose output',
             type: 'boolean',
             default: false
+        },
+        {
+            name: 'kill-zombies',
+            short: 'k',
+            description: 'Find and kill orphaned moflo/claude-flow node processes',
+            type: 'boolean',
+            default: false
         }
     ],
     examples: [
         { command: 'claude-flow doctor', description: 'Run full health check' },
         { command: 'claude-flow doctor --fix', description: 'Show fixes for issues' },
         { command: 'claude-flow doctor --install', description: 'Auto-install missing dependencies' },
+        { command: 'claude-flow doctor --kill-zombies', description: 'Find and kill zombie processes' },
         { command: 'claude-flow doctor -c version', description: 'Check for stale npx cache' },
         { command: 'claude-flow doctor -c claude', description: 'Check Claude Code CLI only' }
     ],
@@ -458,11 +530,53 @@ export const doctorCommand = {
         const autoInstall = ctx.flags.install;
         const component = ctx.flags.component;
         const verbose = ctx.flags.verbose;
+        const killZombies = ctx.flags['kill-zombies'];
         output.writeln();
         output.writeln(output.bold('MoFlo Doctor'));
         output.writeln(output.dim('System diagnostics and health check'));
         output.writeln(output.dim('─'.repeat(50)));
         output.writeln();
+        // Handle --kill-zombies early
+        if (killZombies) {
+            output.writeln(output.bold('Zombie Process Scan'));
+            output.writeln();
+            // First scan without killing to show what would be killed
+            const scan = await findZombieProcesses(false);
+            if (scan.found === 0) {
+                output.writeln(output.success('  No orphaned moflo processes found'));
+            }
+            else {
+                output.writeln(output.warning(`  Found ${scan.found} orphaned process(es): PIDs ${scan.pids.join(', ')}`));
+                // Kill them
+                const result = await findZombieProcesses(true);
+                if (result.killed > 0) {
+                    output.writeln(output.success(`  Killed ${result.killed} zombie process(es)`));
+                }
+                if (result.killed < result.found) {
+                    output.writeln(output.warning(`  ${result.found - result.killed} process(es) could not be killed`));
+                }
+            }
+            output.writeln();
+            output.writeln(output.dim('─'.repeat(50)));
+            output.writeln();
+        }
+        const checkZombieProcesses = async () => {
+            try {
+                const scan = await findZombieProcesses(false);
+                if (scan.found === 0) {
+                    return { name: 'Zombie Processes', status: 'pass', message: 'No orphaned processes' };
+                }
+                return {
+                    name: 'Zombie Processes',
+                    status: 'warn',
+                    message: `${scan.found} orphaned process(es) (PIDs: ${scan.pids.join(', ')})`,
+                    fix: 'moflo doctor --kill-zombies'
+                };
+            }
+            catch {
+                return { name: 'Zombie Processes', status: 'pass', message: 'Check skipped' };
+            }
+        };
         const allChecks = [
             checkVersionFreshness,
             checkNodeVersion,
@@ -476,7 +590,8 @@ export const doctorCommand = {
             checkMcpServers,
             checkDiskSpace,
             checkBuildTools,
-            checkAgenticFlow
+            checkAgenticFlow,
+            checkZombieProcesses
         ];
         const componentMap = {
             'version': checkVersionFreshness,

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

@@ -13,6 +13,7 @@
  * Created with ❤️ by motailz.com
  */
 import { output } from '../output.js';
+import { mofloImport } from '../services/moflo-require.js';
 // Dynamic imports for embeddings package (optional — may not be installed)
 async function getEmbeddings() {
     try {
@@ -135,7 +136,7 @@ const searchCommand = {
                 return { success: false, exitCode: 1 };
             }
             // Load sql.js
-            const initSqlJs = (await import('sql.js')).default;
+            const initSqlJs = (await mofloImport('sql.js')).default;
             const SQL = await initSqlJs();
             const fileBuffer = fs.readFileSync(fullDbPath);
             const db = new SQL.Database(fileBuffer);
@@ -378,7 +379,7 @@ const collectionsCommand = {
                 return { success: true, data: [] };
             }
             // Load sql.js and query real data
-            const initSqlJs = (await import('sql.js')).default;
+            const initSqlJs = (await mofloImport('sql.js')).default;
             const SQL = await initSqlJs();
             const fileBuffer = fs.readFileSync(fullDbPath);
             const db = new SQL.Database(fileBuffer);
@@ -1200,7 +1201,7 @@ const cacheCommand = {
                 }
                 // Try to count real entries via sql.js
                 try {
-                    const initSqlJs = (await import('sql.js')).default;
+                    const initSqlJs = (await mofloImport('sql.js')).default;
                     const SQL = await initSqlJs();
                     const fileBuffer = fs.readFileSync(resolvedDbPath);
                     const db = new SQL.Database(fileBuffer);

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

@@ -6,6 +6,7 @@ import { output } from '../output.js';
 import { confirm } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { storeCommand } from './transfer-store.js';
+import { mofloImport } from '../services/moflo-require.js';
 // Hook types
 const HOOK_TYPES = [
     { value: 'pre-edit', label: 'Pre-Edit', hint: 'Get context before editing files' },
@@ -3074,7 +3075,7 @@ const tokenOptimizeCommand = {
         let reasoningBank = null;
         try {
             // Check if agentic-flow v3 is available
-            const rb = await import('agentic-flow/reasoningbank').catch(() => null);
+            const rb = await mofloImport('agentic-flow/reasoningbank');
             if (rb) {
                 agenticFlowAvailable = true;
                 if (typeof rb.retrieveMemories === 'function') {
@@ -3083,7 +3084,7 @@ const tokenOptimizeCommand = {
             }
             else {
                 // Legacy check for older agentic-flow
-                const af = await import('agentic-flow').catch(() => null);
+                const af = await mofloImport('agentic-flow');
                 if (af)
                     agenticFlowAvailable = true;
             }

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

@@ -9,6 +9,7 @@ import { output } from '../output.js';
 import { confirm } from '../prompt.js';
 import { getServerManager, getMCPServerStatus, } from '../mcp-server.js';
 import { listMCPTools, callMCPTool, hasTool } from '../mcp-client.js';
+import { acquireDaemonLock, releaseDaemonLock, getDaemonLockHolder } from '../services/daemon-lock.js';
 // MCP tools categories
 const TOOL_CATEGORIES = [
     { value: 'coordination', label: 'Coordination', hint: 'Swarm and agent coordination tools' },
@@ -97,14 +98,19 @@ const startCommand = {
         output.writeln();
         output.printInfo('Starting MCP Server...');
         output.writeln();
-        // Check if already running
+        // Check daemon lock first — prevents duplicate MCP servers across all platforms
+        const projectRoot = process.cwd();
+        const lockHolder = getDaemonLockHolder(projectRoot);
+        if (lockHolder && lockHolder !== process.pid && !force) {
+            output.printWarning(`MCP Server already running (PID: ${lockHolder}, detected via daemon lock)`);
+            output.writeln(output.dim('Use --force to override, or stop the existing server first'));
+            return { success: true };
+        }
+        // Check if already running via server status
         const existingStatus = await getMCPServerStatus();
         if (existingStatus.running) {
-            // 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';
-            if (!shouldForceRestart) {
-                // Verify the server is actually healthy/responsive
+            // For non-stdio transports, check health unless --force is specified
+            if (!force && transport !== 'stdio') {
                 const manager = getServerManager();
                 const health = await manager.checkHealth();
                 if (health.healthy) {
@@ -113,26 +119,36 @@ const startCommand = {
                     return { success: false, exitCode: 1 };
                 }
             }
-            // Force restart or unresponsive - auto-recover
-            output.printWarning(`MCP Server (PID: ${existingStatus.pid}) - restarting...`);
-            try {
-                // Force kill the existing process
-                if (existingStatus.pid) {
-                    try {
-                        process.kill(existingStatus.pid, 'SIGKILL');
-                    }
-                    catch {
-                        // Process may already be dead
+            if (force) {
+                // Force restart — kill existing and continue
+                output.printWarning(`MCP Server (PID: ${existingStatus.pid}) - restarting...`);
+                try {
+                    if (existingStatus.pid) {
+                        try {
+                            process.kill(existingStatus.pid, 'SIGKILL');
+                        }
+                        catch {
+                            // Process may already be dead
+                        }
                     }
+                    const manager = getServerManager();
+                    await manager.stop();
+                    // Release stale daemon lock from old process
+                    releaseDaemonLock(projectRoot, existingStatus.pid || 0, true);
+                    output.writeln(output.dim('  Cleaned up existing server'));
+                }
+                catch {
+                    // Continue anyway - the stop/cleanup may partially fail
                 }
-                const manager = getServerManager();
-                await manager.stop();
-                output.writeln(output.dim('  Cleaned up existing server'));
-            }
-            catch {
-                // Continue anyway - the stop/cleanup may partially fail
             }
         }
+        // Acquire daemon lock for the new server
+        const lockResult = acquireDaemonLock(projectRoot);
+        if (!lockResult.acquired) {
+            output.printWarning(`Cannot acquire daemon lock (held by PID: ${lockResult.holder})`);
+            output.writeln(output.dim('Use --force to override'));
+            return { success: true };
+        }
         const options = {
             transport,
             host,