moflo 4.10.2 → 4.10.4

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -6,6 +6,22 @@
 
 ---
 
+## Runtime Target: Claude Code Only
+
+**MoFlo targets Anthropic's Claude Code exclusively** — the CLI, IDE extensions (VS Code, JetBrains), and the web app at claude.ai/code. It is not a Claude Desktop integration and is never installed into Claude Desktop's config tree.
+
+| Tool | Status | Config paths moflo touches |
+|------|--------|----------------------------|
+| Claude Code (CLI, IDE extensions, web) | Sole supported target | `<project>/.mcp.json`, `<project>/.claude/settings.json`, `<project>/.moflo/`, `<project>/moflo.yaml` |
+| Claude Desktop (the macOS/Windows app) | **Out of scope — never** | None — moflo neither reads nor writes Claude Desktop config |
+| Other MCP-capable clients (Cline, Continue, etc.) | Unsupported, may incidentally work | None — bug reports require Claude Code reproduction |
+
+**Never** introduce a code path, search list, fixture, or doc that reads from or writes to `~/.claude/claude_desktop_config.json`, `~/Library/Application Support/Claude/`, or `%APPDATA%/Claude/`. Those are Claude **Desktop** paths. Including them in moflo's MCP-config search list caused issue #1126: a parseable Claude Desktop preferences file outranked a malformed project `.mcp.json`, masking the real failure and routing the auto-fixer down a no-op branch.
+
+The one ambiguous-looking path is Claude Code's user-level config at `~/.claude.json` (where `claude mcp add` writes). MoFlo doesn't author or rewrite that file either; the project-local `.mcp.json` written by `flo init` is the canonical surface moflo owns end-to-end.
+
+---
+
 ## Getting Started
 
 ### Installation

package/README.md

@@ -8,7 +8,7 @@
 
 ## TL;DR
 
-MoFlo makes your AI coding assistant remember what it learns, check what it knows before exploring files, and get smarter over time — all automatically. Install it, run `flo init`, restart your AI client, and everything just works: your docs and code are indexed on session start so the AI can search them instantly, gates prevent the AI from wasting tokens on blind exploration, task outcomes feed back into routing so it picks the right agent type next time, and context depletion warnings tell you when to start a fresh session. No configuration, no API keys, no cloud services — it all runs locally on your machine.
+MoFlo makes Claude Code remember what it learns, check what it knows before exploring files, and get smarter over time — all automatically. Install it, run `flo init`, restart Claude Code, and everything just works: your docs and code are indexed on session start so Claude can search them instantly, gates prevent Claude from wasting tokens on blind exploration, task outcomes feed back into routing so it picks the right agent type next time, and context depletion warnings tell you when to start a fresh session. No configuration, no API keys, no cloud services — it all runs locally on your machine.
 
 ## Quickstart
 
@@ -17,7 +17,7 @@ npm install --save-dev moflo
 flo init
 ```
 
-Restart Claude Code (or your MCP client). That's it — memory, indexing, gates, and routing are all active.
+Restart Claude Code. That's it — memory, indexing, gates, and routing are all active.
 
 Or — just ask Claude to install MoFlo into your project and initialize it!
 
@@ -44,7 +44,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.
-- **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.
+- **Claude Code is the only target** — MoFlo is built and shipped for Anthropic's Claude Code (CLI, IDE extensions, web). It is **not** a Claude Desktop integration: nothing reads from or writes to `~/.claude/claude_desktop_config.json` or `%APPDATA%/Claude/`, and adding paths there is always a bug. The MCP tools, memory system, and hooks could in principle work with any MCP-capable client, but Claude Code is the *only* surface we author for, test against, or accept bug reports on.
 - **GitHub-oriented** — The `/flo` skill, PR automation, 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** — Works identically on macOS, Linux, and Windows.
 
@@ -185,7 +185,7 @@ MoFlo automatically indexes three types of content on every session start, so yo
 
 ### How it works
 
-1. **Session start hook** — When your AI client starts a new session, MoFlo's `SessionStart` hook launches the indexers sequentially in a single background process. This runs silently — you can start working immediately.
+1. **Session start hook** — When Claude Code starts a new session, MoFlo's `SessionStart` hook launches the indexers sequentially in a single background process. This runs silently — you can start working immediately.
 2. **Incremental** — Each indexer tracks file modification times. Only files that changed since the last index run are re-processed. The first run on a large codebase may take a minute or two; subsequent runs typically finish in under a second.
 3. **Embedding generation** — Guidance chunks are embedded using MiniLM-L6-v2 (384 dimensions, WASM). These vectors are stored in the SQLite memory database and used for semantic search.
 4. **No blocking** — The indexers run in the background and don't block your session from starting. You can begin working immediately.
@@ -211,9 +211,9 @@ flo memory refresh           # Reindex everything + rebuild embeddings + vacuum
 
 ### Why this matters
 
-Without auto-indexing, your AI assistant starts every session with a blank slate — it doesn't know what documentation exists, where code lives, or what tests cover which files. It resorts to Glob/Grep exploration, which burns tokens and context window on rediscovery.
+Without auto-indexing, Claude Code starts every session with a blank slate — it doesn't know what documentation exists, where code lives, or what tests cover which files. It resorts to Glob/Grep exploration, which burns tokens and context window on rediscovery.
 
-With auto-indexing, the AI can search semantically ("how does auth work?") and get relevant documentation chunks ranked by similarity, or ask "where is the user model defined?" and get a direct answer from the code map — all without touching the filesystem.
+With auto-indexing, Claude can search semantically ("how does auth work?") and get relevant documentation chunks ranked by similarity, or ask "where is the user model defined?" and get a direct answer from the code map — all without touching the filesystem.
 
 ## The Gate System
 
@@ -261,7 +261,7 @@ You can also disable individual hooks in `.claude/settings.json` by removing the
 
 ## The `/flo` Skill
 
-Inside your AI client, the `/flo` (or `/fl`) slash command drives GitHub issue execution:
+Inside Claude Code, the `/flo` (or `/fl`) slash command drives GitHub issue execution:
 
 ```
 /flo <issue>                  # Full process (research → implement → test → PR)
@@ -272,7 +272,7 @@ Inside your AI client, the `/flo` (or `/fl`) slash command drives GitHub issue e
 /flo -n <issue>               # Normal mode (default, single agent, no swarm)
 ```
 
-For full options and details, type `/flo` with no arguments — your AI client will display the complete skill documentation. Also available as `/fl`.
+For full options and details, type `/flo` with no arguments — Claude Code will display the complete skill documentation. Also available as `/fl`.
 
 ### Epic handling
 
@@ -313,7 +313,7 @@ flo epic reset 42                          # Reset state for re-run
 
 ### What are spells?
 
-Spells are declarative YAML automations composed of pluggable step commands. They exist because shell scripts drift, ad-hoc prompts aren't reproducible, and CI/CD pipelines are the wrong tool for local automation. A spell is **deterministic** (same inputs → same steps), **reviewable** (a YAML file you read like a recipe), and **replayable** (re-cast it tomorrow and it behaves the same). Spells run from the CLI (`flo spell cast`), from an MCP tool call inside your AI client, or on a schedule.
+Spells are declarative YAML automations composed of pluggable step commands. They exist because shell scripts drift, ad-hoc prompts aren't reproducible, and CI/CD pipelines are the wrong tool for local automation. A spell is **deterministic** (same inputs → same steps), **reviewable** (a YAML file you read like a recipe), and **replayable** (re-cast it tomorrow and it behaves the same). Spells run from the CLI (`flo spell cast`), from an MCP tool call inside Claude Code, or on a schedule.
 
 ### How do they work?
 
@@ -425,7 +425,7 @@ For full configuration (`scheduler:` block in `moflo.yaml`), event types, and th
 
 ### Building spells with the `/spell-builder` skill
 
-Inside your AI client, use the `/spell-builder` skill to create, edit, and validate spell definitions interactively. The skill understands the full spell schema and available step commands, so you can describe what you want in natural language and it will generate the YAML:
+Inside Claude Code, use the `/spell-builder` skill to create, edit, and validate spell definitions interactively. The skill understands the full spell schema and available step commands, so you can describe what you want in natural language and it will generate the YAML:
 
 ```
 /spell-builder                           # Start the spell builder
@@ -507,7 +507,7 @@ flo diagnose --json              # JSON output for CI/automation
 
 #### `flo healer` — Health Check
 
-`flo healer` runs 28 parallel health checks against your environment and reports pass/warn/fail for each:
+`flo healer` runs 38 parallel health checks against your environment and reports pass/warn/fail for each:
 
 | Check | What it verifies |
 |-------|-----------------|
@@ -549,7 +549,8 @@ flo diagnose --json              # JSON output for CI/automation
 | Missing config file | Runs `config init` to generate defaults |
 | Status line not wired | Adds `statusLine` config block to `.claude/settings.json` |
 | Stale daemon lock | Removes stale `.moflo/daemon.lock` and restarts daemon |
-| MCP server not configured | Runs `claude mcp add moflo` to register the server |
+| Malformed `.mcp.json` (e.g. unescaped Windows paths) | Backs up the broken file as `.mcp.json.malformed-<ts>`, regenerates a clean one, verifies it parses (#1126) |
+| MCP server missing from a valid `.mcp.json` | Runs `claude mcp add moflo` to register the server |
 | Claude Code CLI missing | Installs `@anthropic-ai/claude-code` globally |
 | Zombie processes | Kills orphaned MoFlo processes (tracked + OS-level scan) |
 
@@ -658,7 +659,7 @@ These are the backend systems that hooks and commands interact with.
 | **EWC++ Consolidation** | Elastic Weight Consolidation that prevents catastrophic forgetting | New learning doesn't overwrite patterns from earlier sessions | Yes |
 | **Session Persistence** | Stop hook exports session metrics; SessionStart hook restores prior state | Patterns learned on Monday are available on Friday | Yes |
 | **Status Line** | Live dashboard showing git branch, session state, memory stats, MCP status | At-a-glance visibility into what MoFlo is doing | Yes |
-| **MCP Tool Server** | 100+ MCP tools for memory, hooks, coordination, spells, swarm, etc. (schemas deferred by default) | Enables AI clients to interact with MoFlo programmatically | Yes (deferred) |
+| **MCP Tool Server** | 80+ MCP tools for memory, hooks, coordination, spells, swarm, etc. (schemas deferred by default) | Lets Claude Code call MoFlo functionality directly | Yes (deferred) |
 
 ### Systems (available but off by default)
 
@@ -670,11 +671,11 @@ These are the backend systems that hooks and commands interact with.
 
 ## The Two-Layer Task System
 
-MoFlo doesn't replace your AI client's task system — it wraps it. Your client (Claude Code, Cursor, or any MCP-capable tool) handles spawning agents and running code. MoFlo adds a coordination layer on top that handles memory, routing, and learning.
+MoFlo doesn't replace Claude Code's task system — it wraps it. Claude Code handles spawning agents and running code. MoFlo adds a coordination layer on top that handles memory, routing, and learning.
 
 ```
 ┌──────────────────────────────────────────────────┐
-│  YOUR AI CLIENT (Execution Layer)                │
+│  CLAUDE CODE (Execution Layer)                   │
 │  Spawns agents, runs code, streams output        │
 │  TaskCreate → Agent → TaskUpdate → results       │
 ├──────────────────────────────────────────────────┤
@@ -688,14 +689,14 @@ Here's how a typical task flows through both layers:
 
 1. **MoFlo routes** — Before work starts, MoFlo analyzes the prompt and recommends an agent type and model tier via hook or MCP tool.
 2. **MoFlo gates** — Before an agent can spawn, MoFlo verifies that memory was searched and a task was registered. This prevents blind exploration.
-3. **Your client executes** — The actual agent runs through your client's native task system. MoFlo doesn't manage the agent — your client handles execution, output, and completion.
+3. **Claude Code executes** — The actual agent runs through Claude Code's native task system. MoFlo doesn't manage the agent — Claude Code handles execution, output, and completion.
 4. **MoFlo learns** — After the agent finishes, MoFlo records what worked (or didn't) in its memory database. Successful patterns feed into future routing.
 
-The key insight: **your client handles execution, MoFlo handles knowledge.** Your client is good at spawning agents and running code. MoFlo is good at remembering what happened, routing to the right agent, and ensuring prior knowledge is checked before exploring from scratch.
+The key insight: **Claude Code handles execution, MoFlo handles knowledge.** Claude Code is good at spawning agents and running code. MoFlo is good at remembering what happened, routing to the right agent, and ensuring prior knowledge is checked before exploring from scratch.
 
-For complex work, MoFlo structures tasks into waves — a research wave discovers context, then an implementation wave acts on it — with dependencies tracked through both the client's task system and MoFlo's coordination layer. The full integration pattern is documented in `.claude/guidance/moflo-claude-swarm-cohesion.md`.
+For complex work, MoFlo structures tasks into waves — a research wave discovers context, then an implementation wave acts on it — with dependencies tracked through both Claude Code's task system and MoFlo's coordination layer. The full integration pattern is documented in `.claude/guidance/moflo-claude-swarm-cohesion.md`.
 
-The `/flo` skill ties both systems together for GitHub issues — driving the full process (research → enhance → implement → test → simplify → PR) with your client's agents for execution and MoFlo's memory for continuity.
+The `/flo` skill ties both systems together for GitHub issues — driving the full process (research → enhance → implement → test → simplify → PR) with Claude Code's agents for execution and MoFlo's memory for continuity.
 
 ### Intelligent Agent Routing
 

package/bin/session-start-launcher.mjs

@@ -358,10 +358,67 @@ function fireAndForget(cmd, args, label) {
   }
 }
 
+// Cross-platform sync sleep — Atomics.wait parks the thread at the OS level
+// without burning CPU (same primitive as src/cli/shared/utils/atomic-file-
+// write.ts:131). Used by stopDaemon's liveness polling between graceful and
+// forced termination so we never unlink the lockfile while the daemon is
+// still running.
+const STOP_SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+function sleepSyncMs(ms) {
+  Atomics.wait(STOP_SLEEP_BUF, 0, 0, ms);
+}
+
+// PID liveness check. EPERM means the process exists but is owned by another
+// user — treat as alive (matches the canonical isAlive in process-manager.mjs
+// after #1061; the prior `catch { return false; }` falsely reported foreign-
+// owned daemons as dead and let the lockfile be unlinked under them).
+//
+// Linux zombie handling: on Linux, `kill(pid, 0)` returns success for zombie
+// processes (exited but not yet reaped by their parent). A zombie can't write
+// to the DB, hold locks, or do anything else stopDaemon cares about — treating
+// it as alive exhausts the kill budget polling a corpse, then preserves the
+// lockfile under a dead process. Production never hits this (the daemon is
+// detached and reaped by init/systemd within ~ms), but a misbehaving parent
+// can keep a daemon zombified, and the launcher's vitest harness reproduces
+// the case deterministically (#1083 CI failure on ubuntu-latest). Read
+// /proc/<pid>/stat (fixed-format, cheap) and treat 'Z' as dead.
+function isDaemonPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+  if (process.platform === 'linux') {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+      // Format: "pid (comm) state ..." — comm can contain spaces/parens, so
+      // parse from the LAST ')' to skip it safely.
+      const lastParen = stat.lastIndexOf(')');
+      if (lastParen !== -1 && stat.charAt(lastParen + 2) === 'Z') return false;
+    } catch (err) {
+      // ENOENT = pid vanished between kill(0) and the read — already dead.
+      if (err && err.code === 'ENOENT') return false;
+      // Anything else (e.g. /proc unavailable) — keep the kill(0) verdict.
+    }
+  }
+  return true;
+}
+
 // Stop the daemon recorded in `lockFile` (if any) without restarting. Used by
 // the upgrade flow before any DB work — the daemon must not be holding old
 // path resolution in memory, and a concurrent sql.js flush would clobber the
-// cherry-picked rows. Returns true when a live PID was actually killed.
+// cherry-picked rows. Returns true when a live PID was confirmed dead (or the
+// PID was already gone when we read the lockfile).
+//
+// Escalation mirrors src/cli/commands/daemon.ts:killBackgroundDaemon so the
+// launcher's upgrade path and `flo daemon stop` behave identically: graceful
+// signal → wait → liveness check → force kill. The prior implementation sent
+// bare `process.kill(pid, 'SIGTERM')` on every platform, which on Windows
+// either silently force-kills or fails entirely depending on the process; in
+// either case the catch swallowed the outcome and the lockfile was unlinked.
+// The daemon (if it survived) then re-wrote the lockfile with its stale PID +
+// pre-upgrade version, defeating the section-3a-pre version-skew recovery and
+// leaving the statusline stuck on `📊 ?` until manual `flo daemon restart`.
 //
 // Section 4's `hooks.mjs session-start` spawn is responsible for starting a
 // fresh daemon under the current code; this function intentionally does not.
@@ -372,11 +429,61 @@ function stopDaemon(lockFile) {
     const lock = JSON.parse(readFileSync(lockFile, 'utf-8'));
     if (typeof lock?.pid === 'number' && lock.pid > 0) stalePid = lock.pid;
   } catch { /* malformed lock — fall through to unlink */ }
-  if (stalePid !== null) {
-    try { process.kill(stalePid, 'SIGTERM'); } catch { /* already dead */ }
+
+  let killed = false;
+  if (stalePid !== null && isDaemonPidAlive(stalePid)) {
+    // Graceful signal — platform-aware. On Windows, `process.kill(pid, 'SIGTERM')`
+    // silently force-kills (skipping the daemon's shutdown handlers that flush
+    // sql.js + release lock cleanly), so use bare `taskkill` (no /F) for a
+    // close-event signal.
+    try {
+      if (process.platform === 'win32') {
+        execFileSync('taskkill', ['/PID', String(stalePid)], { windowsHide: true, timeout: 5000 });
+      } else {
+        process.kill(stalePid, 'SIGTERM');
+      }
+    } catch { /* signal/spawn failed — fall through to liveness poll + force */ }
+
+    // Poll for death up to 3s. The daemon's shutdown handler does a final
+    // sql.js dump + lock release, which under load can take ~1s.
+    const gracefulDeadline = Date.now() + 3000;
+    while (Date.now() < gracefulDeadline) {
+      if (!isDaemonPidAlive(stalePid)) { killed = true; break; }
+      sleepSyncMs(100);
+    }
+
+    // Force-kill if still alive.
+    if (!killed) {
+      try {
+        if (process.platform === 'win32') {
+          execFileSync('taskkill', ['/F', '/T', '/PID', String(stalePid)], { windowsHide: true, timeout: 5000 });
+        } else {
+          process.kill(stalePid, 'SIGKILL');
+        }
+      } catch { /* dead or unreachable */ }
+      // Short grace period for OS reap.
+      const forceDeadline = Date.now() + 1000;
+      while (Date.now() < forceDeadline) {
+        if (!isDaemonPidAlive(stalePid)) { killed = true; break; }
+        sleepSyncMs(100);
+      }
+    }
+
+    if (!killed) {
+      // Daemon survived both signals. Leave the lockfile in place so the next
+      // session can see the stale PID and retry — unlinking now would let the
+      // surviving daemon re-write the lockfile with its stale PID + version,
+      // perpetuating the loop this fix exists to break.
+      emitWarning(`stopDaemon: PID ${stalePid} did not exit after SIGTERM+force-kill; lockfile preserved`);
+      return false;
+    }
+  } else if (stalePid !== null) {
+    // PID was in the lockfile but the process is already gone — clean unlink.
+    killed = true;
   }
+
   try { unlinkSync(lockFile); } catch { /* non-fatal */ }
-  return stalePid !== null;
+  return killed;
 }
 
 // Stop-and-restart helper for the stale-daemon branch (section 3a-pre). The
@@ -720,7 +827,7 @@ try {
 
       // ── Sync .claude/agents/ + .claude/skills/ recursively (#948) ──────
       // Pre-#948, agents and skills weren't manifest-tracked at all, so any
-      // file moflo retired (e.g. the 49 ruflo-aspirational agents in #932 or
+      // file moflo retired (e.g. the 49 aspirational agents in #932 or
       // skill-builder in #945) would linger forever in consumer projects —
       // Claude Code kept loading them on every prompt, paying the per-prompt
       // roster tokens we just spent #932 fixing. Walking these dirs through

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

@@ -9,11 +9,12 @@ import os from 'os';
 import { getDaemonLockHolder } from '../services/daemon-lock.js';
 import { legacyMemoryDbPath, 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';
 export async function checkConfigFile() {
     // JSON configs (parse-validated). LEGACY-CONFIG: `.claude-flow.json` and
     // `claude-flow.config.json` filenames are still recognised so consumers
-    // upgrading from pre-#699 moflo builds (upstream Ruflo) keep working
+    // upgrading from pre-#699 moflo builds keep working
     // without manual rename. Drift guard exempts these via LEGACY-CONFIG marker.
     const jsonPaths = [
         '.moflo/config.json',
@@ -195,9 +196,9 @@ export async function checkMemoryDbIntegrity(cwd = process.cwd()) {
  * Standard MCP-config search paths: home (Claude Desktop on macOS/Linux),
  * XDG config dir, project-local `.mcp.json`, and APPDATA on Windows.
  *
- * Shared by `checkMcpServers` (which inspects the FIRST config it finds and
- * reports on flo presence) and `checkDaemonWriteRouting` (which COUNTS
- * servers across all paths to detect the multi-process-clobber hazard).
+ * Shared by `checkMcpServers` (which inspects configs and reports on moflo
+ * presence) and `checkDaemonWriteRouting` (which COUNTS servers across all
+ * paths to detect the multi-process-clobber hazard).
  */
 function mcpConfigSearchPaths(cwd) {
     return [
@@ -226,25 +227,102 @@ function countMcpServers(cwd) {
     }
     return total;
 }
-export async function checkMcpServers() {
-    for (const configPath of mcpConfigSearchPaths(process.cwd())) {
-        if (existsSync(configPath)) {
-            try {
-                const content = JSON.parse(readFileSync(configPath, 'utf8'));
-                const servers = content.mcpServers || content.servers || {};
-                const count = Object.keys(servers).length;
-                const hasClaudeFlow = 'moflo' in servers || 'claude-flow' in servers || 'claude-flow_alpha' in servers || 'ruflo' in servers || 'ruflo_alpha' in servers;
-                if (hasClaudeFlow) {
-                    return { name: 'MCP Servers', status: 'pass', message: `${count} servers (flo configured)` };
-                }
-                return { name: 'MCP Servers', status: 'warn', message: `${count} servers (flo not found)`, fix: 'claude mcp add ruflo -- npx -y ruflo@latest mcp start' };
-            }
-            catch {
-                // continue to next path
-            }
+/**
+ * Inspect the project's `.mcp.json` (the file `flo init` writes and Claude
+ * Code reads at the project level) and report whether moflo is present,
+ * absent, or the file is malformed.
+ *
+ * Scope: deliberately project-only. We previously also scanned
+ * `~/.claude/claude_desktop_config.json` and `%APPDATA%/Claude/...` — Claude
+ * **Desktop** paths — which is a separate Anthropic product that doesn't
+ * host moflo's MCP server. The old wide scan caused #1126: a Claude
+ * Desktop preferences-only APPDATA file outranked a malformed project
+ * `.mcp.json`, surfacing "0 servers (flo not found)" while the actually
+ * broken project file went unrepaired. Claude Code stores user-level MCP
+ * registrations under `~/.claude.json` `projects[<path>].mcpServers`, but
+ * that's Claude Code internal state we don't author or rewrite; the
+ * project file is the canonical surface moflo owns end-to-end.
+ *
+ * Multi-writer / cross-ecosystem MCP-process counting still uses the wider
+ * `mcpConfigSearchPaths` via `countMcpServers` in
+ * `checkDaemonWriteRouting` — that check has a legitimate reason to see
+ * Claude Desktop processes.
+ *
+ * Exported so the auto-fixer (doctor-fixes.ts) can detect a malformed
+ * `.mcp.json` and regenerate it. Project root resolves via
+ * `findProjectRoot()` so a consumer running `flo healer` from a
+ * subdirectory still discovers the project file.
+ */
+export function inspectMcpConfigs(cwd = process.cwd()) {
+    // Callers wanting project-root resolution pass it in (see `checkMcpServers`
+    // below). Defaulting to `process.cwd()` matches the established pattern in
+    // sibling checks (`checkMemoryDbIntegrity`, `countMcpServers`) and avoids a
+    // redundant FS walk on every doctor pass.
+    const configPath = join(cwd, '.mcp.json');
+    // Single read with the existence/parse branches handled by the catch —
+    // dropping the pre-`existsSync` guard closes a TOCTOU window where the
+    // file is deleted between the check and the read.
+    let content;
+    try {
+        content = JSON.parse(readFileSync(configPath, 'utf8'));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            return { status: 'not_found' };
         }
+        return { status: 'malformed', path: configPath, parseError: errorDetail(e) };
+    }
+    const serversValue = content.mcpServers ?? content.servers;
+    const servers = (serversValue && typeof serversValue === 'object')
+        ? serversValue
+        : {};
+    const count = Object.keys(servers).length;
+    const hasMoflo = 'moflo' in servers || 'claude-flow' in servers || 'claude-flow_alpha' in servers;
+    if (hasMoflo) {
+        return { status: 'valid_with_moflo', path: configPath, count };
+    }
+    return { status: 'valid_no_moflo', path: configPath, count };
+}
+export async function checkMcpServers(cwd = findProjectRoot()) {
+    const result = inspectMcpConfigs(cwd);
+    switch (result.status) {
+        case 'valid_with_moflo':
+            return { name: 'MCP Servers', status: 'pass', message: `${result.count} servers (moflo configured)` };
+        case 'valid_no_moflo':
+            return {
+                name: 'MCP Servers',
+                status: 'warn',
+                message: `${result.count} servers (moflo not registered)`,
+                fix: 'claude mcp add moflo -- npx -y moflo mcp start',
+            };
+        case 'malformed':
+            // #1126: distinguish "config malformed" from "moflo missing". Previously
+            // the loop silently caught the JSON.parse error and fell through,
+            // reporting "0 servers (flo not found)" — which led users to run
+            // `claude mcp add` against a still-broken file that would never parse.
+            // Now we surface the parse error and direct them at the auto-fixer
+            // that regenerates the file from `generateMCPJson`.
+            return {
+                name: 'MCP Servers',
+                status: 'warn',
+                message: `malformed JSON at ${result.path}: ${result.parseError}`,
+                fix: 'flo healer --fix -c mcp-servers',
+            };
+        case 'not_found':
+            return {
+                name: 'MCP Servers',
+                status: 'warn',
+                message: 'No MCP config found',
+                fix: 'claude mcp add moflo -- npx -y moflo mcp start',
+            };
     }
-    return { name: 'MCP Servers', status: 'warn', message: 'No MCP config found', fix: 'claude mcp add moflo npx moflo mcp start' };
+    // Compile-time exhaustiveness guard: if a future status variant is added to
+    // `inspectMcpConfigs`'s return type without a matching case above, this
+    // assignment fails to compile (`string` is not assignable to `never`),
+    // forcing a corresponding update here. Better than a silent `default:`
+    // branch swallowing the new case as if it were `not_found`.
+    const _exhaustive = result.status;
+    return _exhaustive;
 }
 // Catches three failure modes (#895):
 //   1. File missing — session-start should have created it; warn user that

package/dist/src/cli/commands/doctor-fixes.js

@@ -9,9 +9,12 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { join } from 'path';
 import { output } from '../output.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
+import { atomicWriteFileSync } from '../shared/utils/atomic-file-write.js';
 import { repairHookWiring } from '../services/hook-wiring.js';
 import { getDaemonLockHolder } from '../services/daemon-lock.js';
+import { findProjectRoot } from '../services/project-root.js';
 import { findZombieProcesses } from './doctor-zombies.js';
+import { inspectMcpConfigs } from './doctor-checks-config.js';
 import { installClaudeCode, runCommand } from './doctor-checks-runtime.js';
 /** Run a shell command as a fix action. Returns true on exit code 0. */
 async function runFixCommand(cmd) {
@@ -200,6 +203,46 @@ export async function autoFixCheck(check) {
             return runFixCommand('npx moflo embeddings init --force');
         },
         'MCP Servers': async () => {
+            // #1126: distinguish "malformed JSON" from "moflo missing from valid
+            // config". The previous fix always ran `claude mcp add` — a no-op when
+            // the project-local `.mcp.json` was unparseable, because the command
+            // doesn't touch malformed project files.
+            const projectRoot = findProjectRoot();
+            const inspection = inspectMcpConfigs(projectRoot);
+            if (inspection.status === 'malformed' && inspection.path) {
+                try {
+                    // Filesystem-safe timestamp: Date.now() is a digit-only integer so
+                    // no `:` escape needed (per dogfooding.md § 6 cross-platform primitives).
+                    const backupPath = `${inspection.path}.malformed-${Date.now()}`;
+                    // The backup is a brand-new file at a unique timestamped path with
+                    // no concurrent readers — a plain writeFileSync is enough; the
+                    // atomic ceremony is only worth its cost when replacing a file a
+                    // running process might re-open mid-write.
+                    writeFileSync(backupPath, readFileSync(inspection.path, 'utf8'), 'utf-8');
+                    const { generateMCPJson } = await import('../init/mcp-generator.js');
+                    const { DEFAULT_INIT_OPTIONS } = await import('../init/types.js');
+                    const regenerated = generateMCPJson({ ...DEFAULT_INIT_OPTIONS, targetDir: projectRoot });
+                    // Confirm the regenerated content parses before clobbering the
+                    // (broken) original — refuse to repair if our own generator emits
+                    // unparseable JSON for any reason (defense in depth against a future
+                    // generator regression silently emitting bad escapes again).
+                    JSON.parse(regenerated);
+                    // Atomic swap so a concurrent reader (e.g. Claude Code re-scanning
+                    // .mcp.json during the fix) never sees a truncated file. The
+                    // Windows-AV-lock verify window inside atomicWriteFileSync (#1015)
+                    // gates the rename until the new bytes are readable.
+                    atomicWriteFileSync(inspection.path, regenerated);
+                    output.writeln(output.dim(`  Regenerated ${inspection.path}; backup at ${backupPath}.`));
+                    return true;
+                }
+                catch (e) {
+                    output.writeln(output.warning(`  Regeneration failed: ${errorDetail(e)}`));
+                    return false;
+                }
+            }
+            // Valid config exists but moflo isn't registered — fall back to the
+            // claude-cli flow. This is the original behavior for the
+            // valid_no_moflo / not_found states.
             return runFixCommand('claude mcp add moflo -- npx -y moflo mcp start');
         },
         'Claude Code CLI': async () => {

package/dist/src/cli/commands/doctor-version.js

@@ -27,7 +27,7 @@ function readCurrentVersion() {
                     const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
                     if (pkg.version &&
                         typeof pkg.name === 'string' &&
-                        (pkg.name === 'moflo' || pkg.name === 'claude-flow' || pkg.name === 'ruflo')) {
+                        (pkg.name === 'moflo' || pkg.name === 'claude-flow')) {
                         return pkg.version;
                     }
                 }

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

@@ -62,8 +62,6 @@ const commandLoaders = {
     benchmark: () => import('./benchmark.js'),
     // Guidance Control Plane
     guidance: () => import('./guidance.js'),
-    // RVFA Appliance Management
-    appliance: () => import('./appliance.js'),
     // MoFlo Spell Gates
     gate: () => import('./gate.js'),
     // Feature Orchestrator
@@ -137,7 +135,6 @@ import { issuesCommand } from './issues.js';
 import updateCommand from './update.js';
 import { processCommand } from './process.js';
 import { guidanceCommand } from './guidance.js';
-import { applianceCommand } from './appliance.js';
 import { diagnoseCommand } from './diagnose.js';
 import { githubCommand } from './github.js';
 // Pre-populate cache with core commands
@@ -184,7 +181,6 @@ export { performanceCommand } from './performance.js';
 export { securityCommand } from './security.js';
 export { hiveMindCommand } from './hive-mind.js';
 export { guidanceCommand } from './guidance.js';
-export { applianceCommand } from './appliance.js';
 export { diagnoseCommand } from './diagnose.js';
 export { githubCommand } from './github.js';
 // Lazy-loaded command re-exports (for backwards compatibility, but async-only)
@@ -209,7 +205,6 @@ export async function getRouteCommand() { return loadCommand('route'); }
 export async function getProgressCommand() { return loadCommand('progress'); }
 export async function getIssuesCommand() { return loadCommand('issues'); }
 export async function getGuidanceCommand() { return loadCommand('guidance'); }
-export async function getApplianceCommand() { return loadCommand('appliance'); }
 /**
  * Core commands loaded synchronously (available immediately)
  * Advanced commands loaded on-demand for faster startup
@@ -285,7 +280,6 @@ export const commandsByCategory = {
         issuesCommand,
         updateCommand,
         processCommand,
-        applianceCommand,
         githubCommand,
     ],
 };

package/dist/src/cli/init/executor.js

@@ -70,8 +70,8 @@ const COMMANDS_MAP = {};
  * Agents to copy based on configuration. Exported for integrity tests.
  *
  * Each value is a directory name under `.claude/agents/` that ships in the
- * moflo package. After #932 retired ~50 ruflo-aspirational agents, the set
- * is narrowed to actual development specialties Claude is likely to invoke.
+ * moflo package. After #932 retired ~50 aspirational agents, the set is
+ * narrowed to actual development specialties Claude is likely to invoke.
  */
 export const AGENTS_MAP = {
     core: ['core'],

package/dist/src/cli/mcp-tools/swarm-tools.js

@@ -12,7 +12,7 @@ import { getSwarmCoordinator, isSwarmCoordinatorInitialized, } from './swarm-coo
 import { scaleHandler, SCALE_STRATEGIES, TARGET_AGENTS_MIN, TARGET_AGENTS_MAX, } from './swarm-scale-handler.js';
 import { findProjectRoot } from '../services/project-root.js';
 import { MOFLO_DIR } from '../services/moflo-paths.js';
-// Inputs accepted by the MCP layer (covers Ruflo aliases). The coordinator's
+// Inputs accepted by the MCP layer (covers legacy aliases). The coordinator's
 // TopologyType is narrower: 'mesh' | 'hierarchical' | 'centralized' | 'hybrid'.
 const TOPOLOGY_MAP = {
     hierarchical: 'hierarchical',
@@ -23,9 +23,8 @@ const TOPOLOGY_MAP = {
     'hierarchical-mesh': 'hybrid',
     hybrid: 'hybrid',
 };
-// Ported from Ruflo v3/mcp/tools/swarm-tools.ts. `unanimous`/`weighted`/
-// `majority` are the user-facing aliases; the coordinator only speaks
-// `byzantine`/`raft`/`gossip`/`paxos`.
+// `unanimous`/`weighted`/`majority` are the user-facing aliases; the
+// coordinator only speaks `byzantine`/`raft`/`gossip`/`paxos`.
 const CONSENSUS_MAP = {
     unanimous: { algorithm: 'byzantine', threshold: 1.0 },
     byzantine: { algorithm: 'byzantine', threshold: 1.0 },