moflo 4.10.7 → 4.10.9

package/.claude/guidance/shipped/moflo-cli-reference.md

@@ -13,7 +13,7 @@
 | `init`      | 4           | Project initialization with wizard, presets, skills, hooks               |
 | `agent`     | 8           | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |
 | `swarm`     | 6           | Multi-agent swarm coordination and orchestration                         |
-| `memory`    | 11          | sql.js + HNSW vector search, 150x-12,500x faster                         |
+| `memory`    | 11          | node:sqlite + HNSW vector search, 150x-12,500x faster                    |
 | `mcp`       | 9           | MCP server management and tool execution                                 |
 | `task`      | 6           | Task creation, assignment, and lifecycle                                 |
 | `session`   | 7           | Session state management and persistence                                 |

package/.claude/guidance/shipped/moflo-memory-strategy.md

@@ -9,7 +9,7 @@
 Source files (`.claude/guidance/*.md`, `docs/**/*.md`, code, tests) flow through four stages:
 
 1. **Index** — `bin/index-*.mjs` chunks markdown on `##` headers and walks code/tests for structural facts
-2. **Store** — entries land in `.moflo/moflo.db` (SQLite via sql.js) with metadata + RAG links
+2. **Store** — entries land in `.moflo/moflo.db` (SQLite via Node 22's built-in `node:sqlite`) with metadata + RAG links
 3. **Embed** — `bin/build-embeddings.mjs` generates 384-dim vectors via `fastembed` (mandatory, see ADR-EMB-001)
 4. **Search** — `mcp__moflo__memory_search` (preferred), `npx flo memory search` (fallback), or `npx flo-search` (verbose) hit an HNSW index for nearest-neighbor lookup
 

package/.claude/guidance/shipped/moflo-yaml-reference.md

@@ -47,7 +47,7 @@ auto_index:
 
 # Memory backend
 memory:
-  backend: sql.js                 # sql.js (WASM) | json
+  backend: node-sqlite            # node-sqlite (default) | rvf (pure-TS fallback) | json (last resort). Passed to createDatabase() as the preferred provider (#1144).
   embedding_model: Xenova/all-MiniLM-L6-v2   # 384-dim neural embeddings
   namespace: default              # Default namespace for memory operations
 
@@ -156,9 +156,9 @@ CLAUDE_FLOW_LOG_LEVEL=info               # debug | info | warn | error
 # MCP Server (stdio transport — no port)
 CLAUDE_FLOW_MCP_TRANSPORT=stdio
 
-# Memory backend
-CLAUDE_FLOW_MEMORY_BACKEND=hybrid        # hybrid | sqlite | agentdb (legacy)
-CLAUDE_FLOW_MEMORY_TYPE=sqlite           # storage type override
+# Memory backend (legacy SystemConfig env vars — moflo.yaml `memory.backend` is the modern surface)
+CLAUDE_FLOW_MEMORY_BACKEND=sqlite        # informational only; not consumed by selectProvider
+CLAUDE_FLOW_MEMORY_TYPE=sqlite           # SystemConfig override (legacy)
 ```
 
 Variable names retain the `CLAUDE_FLOW_` prefix for backward compatibility with consumers upgraded from claude-flow.

package/.claude/skills/memory-optimization/SKILL.md

@@ -112,7 +112,7 @@ const stats = await mcp.memory_stats({});
 - **Don't rebuild the index on every test.** Use a module-level singleton + `beforeAll`. HNSW cold-boot is ~5s.
 - **Don't raise `ef` globally.** Raise it on the specific queries that need recall. Default is fine for 90% of calls.
 - **Don't quantize a small corpus.** Below ~500k vectors the RAM saving doesn't justify the recall cost.
-- **Don't measure in dev mode.** sql.js WASM behaves differently under `NODE_ENV=production`; benches should match the target.
+- **Don't measure in dev mode.** The memory stack behaves differently under `NODE_ENV=production`; benches should match the target.
 
 ## See Also
 

package/.claude/skills/memory-patterns/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: "memory-patterns"
-description: "Persistent memory patterns for moflo agents — session memory, long-term knowledge, pattern learning, and cross-session context via moflo's sql.js + HNSW vector store. Use when building stateful agents or assistants that need to remember across runs."
+description: "Persistent memory patterns for moflo agents — session memory, long-term knowledge, pattern learning, and cross-session context via moflo's node:sqlite + HNSW vector store. Use when building stateful agents or assistants that need to remember across runs."
 ---
 
 # MoFlo Memory Patterns
 
-Persistent, semantically-searchable memory for moflo-enabled projects. Backed by `.swarm/memory.db` (sql.js + HNSW vector index) and exposed through MCP tools.
+Persistent, semantically-searchable memory for moflo-enabled projects. Backed by `.moflo/moflo.db` (node:sqlite + HNSW vector index) and exposed through MCP tools.
 
 ## Core API
 
@@ -124,7 +124,7 @@ This is the same fan-out the `/flo` spell does — cheap (HNSW, parallel) and re
 
 ## Persistence & Indexing
 
-- File: `.swarm/memory.db` at project root (sql.js).
+- File: `.moflo/moflo.db` at project root (node:sqlite, Node 22+ built-in).
 - Embeddings: built by cli's embeddings module; indexed with HNSW from `src/cli/memory/`.
 - Cold-start cost: ~5 seconds to initialize HNSW. Tests should share a single instance (`beforeAll`, not `beforeEach`).
 - Namespace isolation: each namespace is a logical partition, but the HNSW index spans the table. Query time scales with `limit` and `threshold`, not total row count.

package/.claude/skills/vector-search/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: "vector-search"
-description: "Semantic vector search with moflo — RAG over your own documents, similarity matching, context-aware retrieval via HNSW (sql.js-backed). Use when building retrieval layers for chat, search, or context-assembly."
+description: "Semantic vector search with moflo — RAG over your own documents, similarity matching, context-aware retrieval via HNSW (node:sqlite-backed). Use when building retrieval layers for chat, search, or context-assembly."
 ---
 
 # MoFlo Vector Search (RAG)
 
-Semantic search over your own documents, backed by moflo's HNSW index in `.swarm/memory.db`. Small enough to ship in a devDependency; fast enough for interactive retrieval at 100k–1M vectors.
+Semantic search over your own documents, backed by moflo's HNSW index in `.moflo/moflo.db` (node:sqlite, Node 22+ built-in). Small enough to ship in a devDependency; fast enough for interactive retrieval at 100k–1M vectors.
 
 ## When to Use This vs `memory-patterns`
 

package/README.md

@@ -30,7 +30,7 @@ MoFlo makes deliberate choices so you don't have to:
 - **Fully self-contained** — No external services, no cloud dependencies, no API keys. Everything runs locally on your machine.
 - **Minimal dependencies** — small runtime dep set, all WASM or prebuilt binaries. No native compilation, no `node-gyp`, no platform-specific build steps.
 - **Node.js runtime** — Targets Node.js specifically. All scripts, hooks, and tooling are JavaScript/TypeScript. No Python, no Rust binaries, no native compilation.
-- **sql.js (WASM)** — The memory database uses sql.js, a pure WebAssembly build of SQLite. No native `better-sqlite3` bindings to compile, no platform-specific build steps. Works identically on Windows, macOS, and Linux.
+- **node:sqlite (built-in)** — The memory database uses Node 22's built-in SQLite engine. No `better-sqlite3` native bindings to compile, no WASM round-trip, no platform-specific build steps. Works identically on Windows, macOS, and Linux.
 - **Neural embeddings by default** — 384-dimensional embeddings using `all-MiniLM-L6-v2`. No hash fallback, no peer-optional setup, no install prompts — real semantic search works out of the box. A `postinstall` step trims the embedding runtime to your platform and strips GPU-only libraries the runtime never loads, reclaiming roughly 340 MB on Linux and 150 MB on Windows from a fresh install. Set `MOFLO_NO_PRUNE=1` to skip the trim, or `ONNXRUNTIME_NODE_INSTALL_CUDA=true` to keep CUDA GPU support.
 - **Full learning stack wired up OOTB** — All configured and functional from `flo init`, no manual setup:
   - **SONA** (Self-Optimizing Neural Architecture) — learns from task trajectories
@@ -537,7 +537,7 @@ flo diagnose --json              # JSON output for CI/automation
 | **MCP Spell Integration** | Bridge between MCP tools and spell engine functions correctly |
 | **Hook Execution** | Hook executor is functional and can fire hooks |
 | **Gate Health** | All gate cases, hook bindings, and state file are intact |
-| **MofloDb Bridge** | Memory DB adapter (sql.js + HNSW) is wired and routable |
+| **MofloDb Bridge** | Memory DB adapter (node:sqlite + HNSW) is wired and routable |
 | **Sandbox Tier** | Detects which sandbox backend is available (Docker / bwrap / sandbox-exec / none) |
 
 **Auto-fix mode** (`flo healer --fix`) attempts to repair each failing check automatically:
@@ -645,7 +645,7 @@ These are the backend systems that hooks and commands interact with.
 
 | System | What It Does | Why It Matters | Enabled OOTB |
 |--------|-------------|----------------|:---:|
-| **Semantic Memory** | SQLite database (sql.js/WASM) storing knowledge entries with 384-dim vector embeddings | Your AI assistant accumulates project knowledge across sessions instead of starting from scratch each time | Yes |
+| **Semantic Memory** | SQLite database (Node's built-in `node:sqlite`) storing knowledge entries with 384-dim vector embeddings | Your AI assistant accumulates project knowledge across sessions instead of starting from scratch each time | Yes |
 | **HNSW Vector Search** | Hierarchical Navigable Small World index for fast nearest-neighbor search | Searches across thousands of stored entries return in milliseconds instead of scanning linearly | Yes |
 | **Guidance Indexing** | Chunks markdown docs into overlapping segments, embeds each with MiniLM-L6-v2 | Your project documentation becomes searchable by meaning ("how does auth work?") not just keywords | Yes |
 | **Code Map** | Parses source files for exports, classes, functions, types | The AI can answer "where is X defined?" from the index instead of running Glob/Grep | Yes |
@@ -720,7 +720,7 @@ Routing outcomes persist across sessions. You can inspect them with `flo hooks p
 
 ### Memory & Knowledge Storage
 
-MoFlo uses a SQLite database (via sql.js/WASM — no native deps) to store three types of knowledge:
+MoFlo uses a SQLite database (via Node 22's built-in `node:sqlite` — no native deps) to store three types of knowledge:
 
 | Namespace | What's Stored | How It Gets There |
 |-----------|---------------|-------------------|
@@ -861,7 +861,7 @@ MoFlo started from [Ruflo/Claude Flow](https://github.com/ruvnet/ruflo) but is n
 
 My use case was just one of those many scenarios: day-to-day local coding, enhancing my normal Claude Code experience on a single project. The original supported this — it was all in there — but because the project served so many different needs, I found myself configuring and tailoring things for my specific setup each time I pulled in updates. That isn't a shortcoming of the original; it's the natural trade-off of a tool designed to be that flexible and powerful.
 
-So I started from that foundation and narrowed the focus to my particular corner of it. I baked in the defaults I kept setting manually, added automatic indexing and memory gating at session start, and tuned the out-of-box experience so that `npm install` and `flo init` gets you straight to coding. Over time MoFlo grew its own architecture (workspace collapse, in-tree fastembed runtime, sql.js + HNSW memory layer, spell engine, daemon-driven scheduling) and the two projects fully diverged.
+So I started from that foundation and narrowed the focus to my particular corner of it. I baked in the defaults I kept setting manually, added automatic indexing and memory gating at session start, and tuned the out-of-box experience so that `npm install` and `flo init` gets you straight to coding. Over time MoFlo grew its own architecture (workspace collapse, in-tree fastembed runtime, node:sqlite + HNSW memory layer, spell engine, daemon-driven scheduling) and the two projects fully diverged.
 
 If you're exploring the full breadth of agent orchestration, go look at [Ruflo/Claude Flow](https://github.com/ruvnet/ruflo) — it's the real deal. If your needs are similar to mine — a focused, opinionated local dev setup that just works — MoFlo is for you.
 

package/bin/hooks.mjs

@@ -36,14 +36,15 @@ const __dirname = dirname(__filename);
 // projects, so __dirname-relative paths break. findProjectRoot() works
 // everywhere and resolves identically to the TS bridge (see lib/moflo-paths.mjs).
 const projectRoot = findProjectRoot();
-const logFile = resolve(projectRoot, '.swarm/hooks.log');
+const logFile = resolve(projectRoot, '.moflo', 'logs', 'hooks.log');
+try { mkdirSync(dirname(logFile), { recursive: true }); } catch { /* best effort */ }
 const pm = createProcessManager(projectRoot);
 
 // Parse command line args
 const args = process.argv.slice(2);
 const hookType = args[0];
 
-// Simple log function - writes to .swarm/hooks.log
+// Simple log function - writes to .moflo/logs/hooks.log
 function log(level, message) {
   const timestamp = new Date().toISOString();
   const line = `[${timestamp}] [${level.toUpperCase()}] [${hookType || 'unknown'}] ${message}\n`;

package/bin/index-all.mjs

@@ -13,7 +13,7 @@
  * Spawned as a single detached background process by hooks.mjs session-start.
  */
 
-import { existsSync, appendFileSync, readFileSync } from 'fs';
+import { existsSync, appendFileSync, readFileSync, mkdirSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { spawn, spawnSync } from 'child_process';
@@ -43,7 +43,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // so __dirname-relative paths break. findProjectRoot() (lib/moflo-paths.mjs)
 // works in both locations and resolves identically to the TS bridge.
 const projectRoot = findProjectRoot();
-const LOG_PATH = resolve(projectRoot, '.swarm/hooks.log');
+const LOG_PATH = resolve(projectRoot, '.moflo', 'logs', 'hooks.log');
+try { mkdirSync(dirname(LOG_PATH), { recursive: true }); } catch { /* best effort */ }
 
 function log(msg) {
   const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);

package/bin/index-guidance.mjs

@@ -845,16 +845,16 @@ if (!skipEmbeddings && needsEmbeddings) {
 
   if (embeddingScript) {
     // Register the spawn with the shared ProcessManager (#886). Stdout/stderr
-    // route through `.swarm/background.log` (pm.spawn default) instead of the
-    // bespoke `.moflo/logs/embeddings.log` so the registry, dedup, and
-    // session-end drain stay consistent with every other tracked spawn.
+    // route through `.moflo/logs/background.log` (pm.spawn default) so the
+    // registry, dedup, and session-end drain stay consistent with every other
+    // tracked spawn.
     const pm = createProcessManager(projectRoot);
     const result = pm.spawn('node', [embeddingScript, '--namespace', NAMESPACE], `build-embeddings-${NAMESPACE}`);
     if (result.skipped) {
       log(`Background embedding already running (PID: ${result.pid})`);
     } else if (result.pid) {
       log(`Background embedding started (PID: ${result.pid})`);
-      log(`Log file: .swarm/background.log`);
+      log(`Log file: .moflo/logs/background.log`);
     } else {
       log('⚠️  Failed to spawn background embedding');
     }

package/bin/lib/daemon-port.mjs

@@ -0,0 +1,66 @@
+/**
+ * Pure-JS counterpart to src/cli/services/daemon-port.ts.
+ *
+ * Lives in bin/lib because session-start-launcher.mjs and other bin/ scripts
+ * run before any TS compilation has happened. The TS file is the canonical
+ * API; this file MUST stay algorithmically identical (asserted by
+ * `tests/system/daemon-port-twin.test.ts`).
+ *
+ * See `src/cli/services/daemon-port.ts` for the full doc + history.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const PORT_RANGE_BASE = 33000;
+export const PORT_RANGE_SIZE = 1000;
+export const LEGACY_DEFAULT_PORT = 3117;
+
+export function readEnvPortOverride() {
+  const raw = process.env.MOFLO_DAEMON_PORT;
+  if (!raw) return null;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1 || n > 65535) return null;
+  return n;
+}
+
+export function resolveProjectPort(projectRoot) {
+  const envPort = readEnvPortOverride();
+  if (envPort != null) return envPort;
+  const hash = createHash('sha256').update(projectRoot).digest();
+  return PORT_RANGE_BASE + (hash.readUInt16BE(0) % PORT_RANGE_SIZE);
+}
+
+export function resolveClientPort(projectRoot) {
+  const envPort = readEnvPortOverride();
+  if (envPort != null) return envPort;
+
+  try {
+    const lockFile = join(projectRoot, '.moflo', 'daemon.lock');
+    if (existsSync(lockFile)) {
+      const lock = JSON.parse(readFileSync(lockFile, 'utf-8'));
+      const lockPort = typeof lock?.port === 'number' ? lock.port : null;
+      if (lockPort && Number.isFinite(lockPort) && lockPort > 0 && lockPort < 65536) {
+        return lockPort;
+      }
+    }
+  } catch {
+    // fall through
+  }
+
+  return resolveProjectPort(projectRoot);
+}
+
+export function serverPortCandidates(projectRoot, maxAttempts = 10) {
+  const envPort = readEnvPortOverride();
+  if (envPort != null) return [envPort];
+
+  const base = resolveProjectPort(projectRoot);
+  const attempts = Math.min(Math.max(1, maxAttempts), PORT_RANGE_SIZE);
+  const ports = [];
+  for (let i = 0; i < attempts; i++) {
+    const candidate = PORT_RANGE_BASE + ((base - PORT_RANGE_BASE + i) % PORT_RANGE_SIZE);
+    ports.push(candidate);
+  }
+  return ports;
+}

package/bin/lib/process-manager.mjs

@@ -164,9 +164,9 @@ export function createProcessManager(root) {
         // This ensures errors from background indexers/pretrain are captured
         let stdio = 'ignore';
         try {
-          const swarmDir = resolve(projectRoot, '.swarm');
-          ensureDir(swarmDir);
-          const logPath = resolve(swarmDir, 'background.log');
+          const logsDir = resolve(projectRoot, '.moflo', 'logs');
+          ensureDir(logsDir);
+          const logPath = resolve(logsDir, 'background.log');
           const fd = openSync(logPath, 'a');
           stdio = ['ignore', fd, fd];
         } catch {

package/dist/src/cli/commands/daemon.js

@@ -32,13 +32,13 @@ import { errorDetail } from '../shared/utils/error-detail.js';
 export function resolveDashboardPort(flagValue, envValue) {
     const source = flagValue ?? envValue;
     if (!source)
-        return { ok: true, port: DEFAULT_DASHBOARD_PORT };
+        return { ok: true, port: DEFAULT_DASHBOARD_PORT, explicit: false };
     const parsed = parseInt(source, 10);
     if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
         const label = flagValue ? 'dashboard port' : 'MOFLO_DAEMON_PORT';
         return { ok: false, error: `Invalid ${label}: ${source} (must be 1-65535)` };
     }
-    return { ok: true, port: parsed };
+    return { ok: true, port: parsed, explicit: true };
 }
 // Start daemon subcommand
 const startCommand = {
@@ -76,6 +76,7 @@ const startCommand = {
             return { success: false, exitCode: 1 };
         }
         const dashboardPort = portResult.port;
+        const dashboardPortExplicit = portResult.explicit;
         // Parse resource threshold overrides from CLI flags
         const config = {};
         const rawMaxCpu = ctx.flags.maxCpuLoad;
@@ -109,7 +110,7 @@ const startCommand = {
         }
         // Background mode (default): fork a detached process
         if (!foreground) {
-            return startBackgroundDaemon(projectRoot, quiet, rawMaxCpu, rawMinMem, dashboardPort, noDashboard);
+            return startBackgroundDaemon(projectRoot, quiet, rawMaxCpu, rawMinMem, dashboardPortExplicit ? dashboardPort : undefined, noDashboard);
         }
         // Foreground mode: run in current process (blocks terminal)
         try {
@@ -151,7 +152,7 @@ const startCommand = {
                 const status = daemon.getStatus();
                 spinner.succeed('Worker daemon started (foreground mode)');
                 const { dashboard } = await attachDaemonServices(daemon, {
-                    projectRoot, noDashboard, dashboardPort, verbose: true,
+                    projectRoot, noDashboard, dashboardPort, dashboardPortExplicit, verbose: true,
                 });
                 output.writeln();
                 output.printBox([
@@ -207,7 +208,7 @@ const startCommand = {
             }
             else {
                 const daemon = await startDaemon(projectRoot, config);
-                await attachDaemonServices(daemon, { projectRoot, noDashboard, dashboardPort, verbose: false });
+                await attachDaemonServices(daemon, { projectRoot, noDashboard, dashboardPort, dashboardPortExplicit, verbose: false });
                 await new Promise(() => { }); // Keep alive
             }
             return { success: true };
@@ -243,15 +244,25 @@ async function attachDaemonServices(daemon, opts) {
     if (!opts.noDashboard) {
         try {
             dashboard = await startDashboard(daemon, {
-                port: opts.dashboardPort,
+                // Pass the resolved port only when the caller explicitly pinned it
+                // (CLI flag / env). Otherwise let startDashboard pick the
+                // deterministic per-project port via serverPortCandidates (#1145).
+                port: opts.dashboardPortExplicit ? opts.dashboardPort : undefined,
                 memory,
                 schedulerEnabledInConfig: schedulerConfig.enabled,
+                projectRoot: opts.projectRoot,
             });
             if (opts.verbose)
                 output.printSuccess(`The Luminarium: http://localhost:${dashboard.port}`);
         }
         catch (err) {
-            logWarn(`The Luminarium failed to start: ${errorDetail(err)}`);
+            // #1145 §9.4 — hard-fail on bind exhaustion. Pre-#1145 we swallowed
+            // this; the daemon stayed alive doing worker-only work while clients
+            // routed to whichever daemon happened to be on the legacy default
+            // port. Re-throw so the spawn launcher sees a non-zero exit and the
+            // healer flags the failure instead of silently continuing.
+            logWarn(`The Luminarium failed to bind — daemon will exit so clients don't silently route to a foreign daemon: ${errorDetail(err)}`);
+            throw err;
         }
     }
     if (!schedulerConfig.enabled) {
@@ -350,11 +361,14 @@ async function startBackgroundDaemon(projectRoot, quiet, maxCpuLoad, minFreeMemo
     if (minFreeMemory && SPAWN_NUMERIC_RE.test(minFreeMemory)) {
         spawnArgs.push('--min-free-memory', minFreeMemory);
     }
-    // Forward dashboard flags
+    // Forward dashboard flags. With #1145 the foreground child resolves its
+    // own deterministic per-project port when no `--dashboard-port` flag is
+    // passed — only forward the flag when the caller explicitly pinned it
+    // (signaled by `dashboardPort` being defined here).
     if (noDashboard) {
         spawnArgs.push('--no-dashboard');
     }
-    else if (dashboardPort && dashboardPort !== DEFAULT_DASHBOARD_PORT) {
+    else if (dashboardPort != null) {
         spawnArgs.push('--dashboard-port', String(dashboardPort));
     }
     const daemonEnv = {
@@ -413,7 +427,14 @@ async function startBackgroundDaemon(projectRoot, quiet, maxCpuLoad, minFreeMemo
     if (!quiet) {
         output.printSuccess(`Daemon started in background (PID: ${pid})`);
         if (!noDashboard) {
-            output.printInfo(`The Luminarium: http://localhost:${dashboardPort ?? DEFAULT_DASHBOARD_PORT}`);
+            if (dashboardPort != null) {
+                output.printInfo(`The Luminarium: http://localhost:${dashboardPort}`);
+            }
+            else {
+                // #1145 — port is project-deterministic and assigned at bind time;
+                // read it from .moflo/daemon.lock once the child finishes startup.
+                output.printInfo(`The Luminarium: see http://localhost:<port from .moflo/daemon.lock>`);
+            }
         }
         output.printInfo(`Logs: ${logFile}`);
         output.printInfo(`Stop with: claude-flow daemon stop`);

package/dist/src/cli/commands/doctor-checks-config.js

@@ -6,8 +6,9 @@
 import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import os from 'os';
-import { getDaemonLockHolder } from '../services/daemon-lock.js';
-import { legacyMemoryDbPath, memoryDbCandidatePaths, memoryDbPath, } from '../services/moflo-paths.js';
+import { findProjectDaemonPids, getDaemonLockHolder, getDaemonLockPayload, } from '../services/daemon-lock.js';
+import { resolveClientPort, LEGACY_DEFAULT_PORT, probeDaemonHealthWithRetry as probeDaemonHealthIdentity, normalizeProjectRoot, } from '../services/daemon-port.js';
+import { LEGACY_SWARM_DIR, memoryDbCandidatePaths, memoryDbPath, } from '../services/moflo-paths.js';
 import { probeDbIntegrity } from '../services/memory-db-integrity-repair.js';
 import { findProjectRoot } from '../services/project-root.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
@@ -102,6 +103,143 @@ export async function checkDaemonStatus() {
         return { name: 'Daemon Status', status: 'warn', message: `Unable to check: ${errorDetail(e)}`, fix: 'claude-flow daemon status' };
     }
 }
+/**
+ * Daemon identity check (#1145).
+ *
+ * Reads `.moflo/daemon.lock` → probes `/api/health` on the recorded port →
+ * confirms the daemon's reported `projectRoot` matches `findProjectRoot()`.
+ * Catches the silent cross-project routing class where two moflo daemons
+ * (e.g. moflo-dev + a consumer) share a port and the client hits the wrong
+ * one.
+ *
+ * Status semantics:
+ *   - `pass` — no daemon (cleanly absent) OR identity matches.
+ *   - `warn` — daemon has no port in lock (pre-#1145 daemon; harmless if
+ *     no collision, but should be recycled to upgrade).
+ *   - `fail` — `/api/health` reports a different project. Routing is
+ *     polluted; the healer fix kills the foreign-identity daemon and
+ *     respawns the local one.
+ */
+export async function checkDaemonIdentity(cwd = process.cwd()) {
+    const projectRoot = findProjectRoot({ cwd });
+    const payload = getDaemonLockPayload(projectRoot);
+    if (!payload) {
+        return {
+            name: 'Daemon Identity Match',
+            status: 'pass',
+            message: 'No daemon running (nothing to verify)',
+        };
+    }
+    // Lock present but no port field — pre-#1145 daemon. Identity check is
+    // best-effort; surface as warn so the user knows to recycle but don't
+    // hard-fail unless we can prove cross-project routing.
+    const portFromLock = payload.port;
+    const probePort = portFromLock ?? resolveClientPort(projectRoot);
+    if (!portFromLock) {
+        // Try the legacy default explicitly so consumers running an
+        // un-upgraded daemon still get a useful diagnostic.
+        const probe = await probeDaemonHealthIdentity(LEGACY_DEFAULT_PORT, 1500);
+        if (probe.kind === 'identity'
+            && normalizeProjectRoot(probe.projectRoot) !== normalizeProjectRoot(projectRoot)) {
+            return {
+                name: 'Daemon Identity Match',
+                status: 'fail',
+                message: `Daemon at 127.0.0.1:${LEGACY_DEFAULT_PORT} claims project '${probe.projectRoot}' — cross-project routing active`,
+                fix: 'flo healer --fix -c daemon-identity',
+            };
+        }
+        return {
+            name: 'Daemon Identity Match',
+            status: 'warn',
+            message: 'Daemon lock has no port field — pre-#1145 daemon; recycle to enable port discovery',
+            fix: 'flo healer --fix -c daemon-identity',
+        };
+    }
+    const probe = await probeDaemonHealthIdentity(probePort, 1500);
+    if (probe.kind === 'unreachable') {
+        return {
+            name: 'Daemon Identity Match',
+            status: 'warn',
+            message: `Daemon at 127.0.0.1:${probePort} unreachable on /api/health`,
+            fix: 'flo healer --fix -c daemon-identity',
+        };
+    }
+    if (probe.kind === 'legacy') {
+        return {
+            name: 'Daemon Identity Match',
+            status: 'warn',
+            message: `Daemon at 127.0.0.1:${probePort} has no /api/health (legacy) — recycle to upgrade`,
+            fix: 'flo healer --fix -c daemon-identity',
+        };
+    }
+    if (normalizeProjectRoot(probe.projectRoot) !== normalizeProjectRoot(projectRoot)) {
+        return {
+            name: 'Daemon Identity Match',
+            status: 'fail',
+            message: `Daemon at 127.0.0.1:${probePort} claims project '${probe.projectRoot}' but cwd is '${projectRoot}'`,
+            fix: 'flo healer --fix -c daemon-identity',
+        };
+    }
+    return {
+        name: 'Daemon Identity Match',
+        status: 'pass',
+        message: `OK (port ${probePort}, pid ${payload.pid})`,
+    };
+}
+/**
+ * Same-project orphan daemon check (#1150).
+ *
+ * Counts moflo daemon processes whose command line is rooted at THIS
+ * project's CLI binary. Healthy state: 0 (no daemon) or 1 (the lock-holder).
+ * Failure state: >1 — multiple daemons are racing for the indexer lock and
+ * writing to the same `daemon-state.json`.
+ *
+ * Distinct from `Daemon Identity Match`, which catches a DIFFERENT project's
+ * daemon answering on a port. This check catches multiple SAME-project
+ * daemons sharing the project root but with one of them holding a stale or
+ * unlinked lock (the orphan path).
+ *
+ * Status semantics:
+ *   - `pass` — 0 or 1 same-project daemon.
+ *   - `fail` — 2+ same-project daemons. Auto-fix terminates all but the
+ *     lock-recorded PID (or all + respawn if no lock matches a live one).
+ *     The "no live lock-holder" sub-case stays `fail` rather than `warn`:
+ *     a stale lock alongside live orphan daemons is a strictly worse state
+ *     than an orphan that the lock knows about, not a softer one.
+ *   - `warn` — the OS process scan itself failed (platform introspection
+ *     unavailable). The healer is offered as a fallback but isn't binding.
+ */
+export async function checkDaemonOrphan(cwd = process.cwd()) {
+    const projectRoot = findProjectRoot({ cwd });
+    let pids;
+    try {
+        pids = findProjectDaemonPids(projectRoot);
+    }
+    catch (e) {
+        return {
+            name: 'Daemon Orphan',
+            status: 'warn',
+            message: `Process scan failed: ${errorDetail(e)}`,
+        };
+    }
+    if (pids.length === 0) {
+        return { name: 'Daemon Orphan', status: 'pass', message: 'No daemon running (nothing to verify)' };
+    }
+    if (pids.length === 1) {
+        return { name: 'Daemon Orphan', status: 'pass', message: `1 daemon (pid ${pids[0]})` };
+    }
+    const lockHolder = getDaemonLockHolder(projectRoot);
+    const lockHolderInPids = lockHolder != null && pids.includes(lockHolder);
+    const orphanPids = lockHolderInPids ? pids.filter(p => p !== lockHolder) : pids;
+    return {
+        name: 'Daemon Orphan',
+        status: 'fail',
+        message: lockHolderInPids
+            ? `${pids.length} daemons for this project; lock holds pid ${lockHolder}, orphans: ${orphanPids.join(', ')}`
+            : `${pids.length} daemons for this project; no lock-holder identifiable, candidates: ${pids.join(', ')}`,
+        fix: 'flo healer --fix -c daemon-orphan',
+    };
+}
 export async function checkMemoryDatabase() {
     const root = process.cwd();
     const canonical = memoryDbPath(root);
@@ -115,14 +253,10 @@ export async function checkMemoryDatabase() {
         }
         const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
         if (dbPath === canonical) {
-            let message = `.moflo/moflo.db (${sizeMB} MB)`;
-            // Unfinished migration tail: source still present means the launcher's
-            // rename-to-.bak step failed (Windows lock most often). Flag so the user
-            // knows to clear the stale source.
-            if (existsSync(legacyMemoryDbPath(root))) {
-                message += ' — legacy .swarm/memory.db still present (delete it after confirming canonical is healthy)';
-            }
-            return { name: 'Memory Database', status: 'pass', message };
+            // Legacy `.swarm/memory.db` residue is owned by the separate
+            // `checkSwarmResidue` check so we keep this check focused on the
+            // canonical DB. That check carries the auto-fix.
+            return { name: 'Memory Database', status: 'pass', message: `.moflo/moflo.db (${sizeMB} MB)` };
         }
         return {
             name: 'Memory Database',
@@ -133,6 +267,44 @@ export async function checkMemoryDatabase() {
     }
     return { name: 'Memory Database', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };
 }
+/**
+ * Catches `.swarm/` residue that survived past the canonical migration:
+ *  - `memory.db` / `memory.db.bak` — stale once `.moflo/moflo.db` exists.
+ *  - `q-learning-model.json` / `model-router-state.json` — live router state
+ *    that pre-dates the `.moflo/movector/` defaults; migrate, don't delete.
+ *  - `hooks.log` / `background.log` — diagnostic logs the launcher used to
+ *    route to `.swarm/`; relocate to `.moflo/logs/`.
+ *
+ * Passes when `.swarm/` is absent OR contains nothing the migrator recognises.
+ * Otherwise warns with `fix: 'flo healer --fix -c swarm-residue'` so the auto-fix
+ * dispatcher (`fixSwarmLegacyResidue` in doctor-fixes.ts) can clean it up in
+ * one pass.
+ */
+export async function checkSwarmResidue() {
+    const root = findProjectRoot();
+    const swarmDir = join(root, LEGACY_SWARM_DIR);
+    if (!existsSync(swarmDir)) {
+        return { name: 'Swarm Residue', status: 'pass', message: 'No .swarm/ directory present' };
+    }
+    const artifacts = [
+        'memory.db',
+        'memory.db.bak',
+        'q-learning-model.json',
+        'model-router-state.json',
+        'hooks.log',
+        'background.log',
+    ];
+    const present = artifacts.filter(name => existsSync(join(swarmDir, name)));
+    if (present.length === 0) {
+        return { name: 'Swarm Residue', status: 'pass', message: '.swarm/ present but no known residue' };
+    }
+    return {
+        name: 'Swarm Residue',
+        status: 'warn',
+        message: `${present.length} legacy artifact(s) in .swarm/: ${present.join(', ')}`,
+        fix: 'flo healer --fix -c swarm-residue',
+    };
+}
 /**
  * Tier-1 corruption probe for `.moflo/moflo.db`. Runs `PRAGMA integrity_check`
  * via a raw node:sqlite readonly handle — bypasses `openBackend` because that