moflo 4.10.6 → 4.10.8

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
 
@@ -101,9 +101,17 @@ status_line:
 sandbox:
   enabled: false                  # Set to true to wrap bash steps in an OS sandbox
   tier: auto                      # auto | denylist-only | full
+
+# Auto-update on session start (refreshes consumer assets when moflo upgrades)
+auto_update:
+  enabled: true                          # Master toggle for version-change auto-sync
+  scripts: true                          # Sync .claude/scripts/ from moflo bin/
+  helpers: true                          # Sync .claude/helpers/ from moflo source
+  hook_block_drift: warn                 # warn | regenerate | off
+  claudemd_injection_drift: regenerate   # warn | regenerate | off
 ```
 
-If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
+If your `moflo.yaml` predates the `sandbox:` or `auto_update:` blocks, they are auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
 
 ### Key Behaviors
 
@@ -128,6 +136,12 @@ If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the n
 | `sandbox.enabled: true` | Wrap bash steps in an OS sandbox (macOS/Linux/WSL) — absolute disable when `false`, regardless of tier |
 | `sandbox.tier: full` | Require OS sandbox; throw at runtime if the platform tool is unavailable |
 | `sandbox.tier: denylist-only` | Keep Layer 1 denylist only; skip OS isolation even when enabled |
+| `auto_update.enabled: false` | Disable all on-session auto-sync (scripts, helpers, drift checks) |
+| `auto_update.hook_block_drift: regenerate` | Auto-repair drift in `.claude/settings.json` hook block on session start (#881) |
+| `auto_update.hook_block_drift: off` | Skip hook-block drift detection entirely |
+| `auto_update.claudemd_injection_drift: regenerate` | Auto-refresh the MoFlo block in `CLAUDE.md` when it drifts from the current generator (#1142, default) |
+| `auto_update.claudemd_injection_drift: warn` | Print a drift notice on session start but leave `CLAUDE.md` unchanged |
+| `auto_update.claudemd_injection_drift: off` | Skip CLAUDE.md injection drift detection entirely |
 
 ---
 
@@ -142,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/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/session-start-launcher.mjs

@@ -640,7 +640,16 @@ try {
 // Controlled by `auto_update.enabled` in moflo.yaml (default: true).
 // When moflo is upgraded (npm install), scripts and helpers may be stale.
 // Detect version change and sync from source before running hooks.
-let autoUpdateConfig = { enabled: true, scripts: true, helpers: true, hookBlockDrift: 'warn' };
+let autoUpdateConfig = {
+  enabled: true,
+  scripts: true,
+  helpers: true,
+  hookBlockDrift: 'warn',
+  // #1142 — CLAUDE.md injection drift refresh mode (warn | regenerate | off,
+  // default regenerate). Defaults to regenerate because the consumer cannot
+  // refresh CLAUDE.md on their own — there is no other auto-refresh path.
+  claudemdInjectionDrift: 'regenerate',
+};
 try {
   const mofloYaml = resolve(projectRoot, 'moflo.yaml');
   if (existsSync(mofloYaml)) {
@@ -651,10 +660,13 @@ try {
     const helpersMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+helpers:\s*(true|false)/);
     // #881: hook-block drift detector (warn | regenerate | off; default warn)
     const driftMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+hook_block_drift:\s*(warn|regenerate|off)/);
+    // #1142: CLAUDE.md injection drift detector (warn | regenerate | off; default regenerate)
+    const claudemdMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+claudemd_injection_drift:\s*(warn|regenerate|off)/);
     if (enabledMatch) autoUpdateConfig.enabled = enabledMatch[1] === 'true';
     if (scriptsMatch) autoUpdateConfig.scripts = scriptsMatch[1] === 'true';
     if (helpersMatch) autoUpdateConfig.helpers = helpersMatch[1] === 'true';
     if (driftMatch) autoUpdateConfig.hookBlockDrift = driftMatch[1];
+    if (claudemdMatch) autoUpdateConfig.claudemdInjectionDrift = claudemdMatch[1];
   }
 } catch (err) {
   // Defaults (all true) keep the upgrade flow alive but the user should
@@ -1414,23 +1426,185 @@ async function runHookBlockDriftCheck() {
   };
 }
 
-try {
-  if (autoUpdateConfig.enabled && autoUpdateConfig.hookBlockDrift !== 'off') {
-    const result = await runHookBlockDriftCheck();
-    if (result) {
+// ── 3a-vii. CLAUDE.md injection drift detection (#1142) ──────────────────
+// Refresh the consumer's `<root>/CLAUDE.md` MoFlo block when it has drifted
+// from what `claudemd-generator.ts` currently produces. The launcher's
+// stages 3/3b refresh shipped guidance files on every version change, but
+// CLAUDE.md was only rewritten by explicit `flo init` / `flo-setup` — so
+// consumers carried stale injection content (with the legacy `shipped/`
+// guidance paths, for example) for as long as they didn't re-run init.
+//
+// Modes (`auto_update.claudemd_injection_drift` in moflo.yaml):
+//   regenerate  — replace the drifted block in place (default; the consumer
+//                 has no other path to refresh CLAUDE.md)
+//   warn        — print a one-line drift summary to stdout
+//   off         — skip detection entirely
+//
+// Fast-path: `.moflo/claudemd-injection-cache.json` records the last clean
+// run. If CLAUDE.md + the generator module both still match the cached
+// mtimes, skip the readFile + dynamic import.
+async function runClaudeMdInjectionDriftCheck() {
+  const claudeMdPath = resolve(projectRoot, 'CLAUDE.md');
+  let claudeMdStat;
+  try { claudeMdStat = statSync(claudeMdPath); } catch { return null; }
+
+  // Locate the generator and the drift service. Both must be present —
+  // generator owns the canonical content, drift service owns the marker
+  // logic. Use bin/lib/moflo-resolve.mjs path resolution semantics
+  // (covers consumer node_modules + dev source tree). Two candidates each.
+  const generatorCandidates = [
+    resolve(projectRoot, 'node_modules/moflo/dist/src/cli/init/claudemd-generator.js'),
+    resolve(projectRoot, 'dist/src/cli/init/claudemd-generator.js'),
+  ];
+  const driftCandidates = [
+    resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/claudemd-injection.js'),
+    resolve(projectRoot, 'dist/src/cli/services/claudemd-injection.js'),
+  ];
+  let generatorPath = null, generatorStat = null;
+  for (const p of generatorCandidates) {
+    try { generatorStat = statSync(p); generatorPath = p; break; } catch { /* try next */ }
+  }
+  let driftPath = null, driftStat = null;
+  for (const p of driftCandidates) {
+    try { driftStat = statSync(p); driftPath = p; break; } catch { /* try next */ }
+  }
+  if (!generatorPath || !driftPath) return null;
+
+  // Use the max mtime of the two modules so any update to either invalidates
+  // the cache. Both are co-bumped on publish so this is normally one mtime.
+  const moduleMtimeMs = Math.max(generatorStat.mtimeMs, driftStat.mtimeMs);
+
+  // Cache short-circuits any (claudeMdMtime, moduleMtime, state) triple
+  // match — not just 'in-sync'. A drifted consumer in warn mode still emits
+  // the nudge once on first detection, then stays silent until something
+  // actually changes (CLAUDE.md mtime bumps from a user edit, or moflo
+  // upgrade bumps moduleMtimeMs). Without this, every session re-does the
+  // full slow path (3 statSync + readFile + 2 dynamic imports + generator
+  // call) for non-in-sync consumers in perpetuity.
+  const cachePath = join(mofloDir(projectRoot), 'claudemd-injection-cache.json');
+  let cached = null;
+  try { cached = JSON.parse(readFileSync(cachePath, 'utf-8')); } catch { /* missing or corrupt */ }
+  if (
+    cached &&
+    cached.claudeMdMtimeMs === claudeMdStat.mtimeMs &&
+    cached.moduleMtimeMs === moduleMtimeMs &&
+    typeof cached.state === 'string'
+  ) return null;
+
+  // Try-catch around the dynamic imports handles the file disappearing
+  // between statSync and import (TOCTOU); other load errors surface as
+  // an emitWarning so a transitive dependency failure isn't invisible
+  // (mirrors the silent-catch lesson — see feedback_consumer_blast_radius).
+  let genMod = null, driftMod = null;
+  try {
+    genMod = await import(pathToFileURL(generatorPath).href);
+    driftMod = await import(pathToFileURL(driftPath).href);
+  } catch (err) {
+    emitWarning(`CLAUDE.md drift check skipped (${errMessage(err)})`);
+    return null;
+  }
+  if (typeof genMod.generateClaudeMd !== 'function') return null;
+  if (typeof driftMod.computeInjectionDrift !== 'function') return null;
+  if (typeof driftMod.applyInjectionReplacement !== 'function') return null;
+
+  const claudeMdContents = readFileSync(claudeMdPath, 'utf-8');
+  const canonical = genMod.generateClaudeMd({});
+  const report = driftMod.computeInjectionDrift(claudeMdContents, canonical);
+
+  let finalState = report.state;
+  let finalMtime = claudeMdStat.mtimeMs;
+
+  // Treat both 'drifted' and 'legacy-marker' as repairable in regenerate mode.
+  // 'no-marker' means the user removed the inject deliberately — don't re-add
+  // it on every session start; that's a re-init operation, not a drift fix.
+  // 'no-file' is unreachable here because statSync already succeeded.
+  const repairable = report.state === 'drifted' || report.state === 'legacy-marker';
+  if (repairable) {
+    const wantRegenerate = autoUpdateConfig.claudemdInjectionDrift === 'regenerate';
+    if (wantRegenerate) {
+      const result = driftMod.applyInjectionReplacement(claudeMdContents, canonical);
+      if (result.changed && typeof result.contents === 'string') {
+        writeFileSync(claudeMdPath, result.contents);
+        finalState = 'in-sync';
+        try { finalMtime = statSync(claudeMdPath).mtimeMs; } catch { /* keep prior */ }
+        emitMutation(
+          'refreshed CLAUDE.md MoFlo block',
+          `replaced ${report.state} block with current generator output`,
+        );
+      }
+    } else {
+      // warn mode — surface a one-line summary on stdout for Claude/user.
       try {
-        mkdirSync(mofloDir(projectRoot), { recursive: true });
-        writeFileSync(result.cachePath, JSON.stringify({
-          settingsMtimeMs: result.settingsMtimeMs,
-          moduleMtimeMs: result.moduleMtimeMs,
-          consumerHash: result.consumerHash,
-          referenceHash: result.referenceHash,
-        }));
-      } catch { /* cache is opportunistic — non-fatal */ }
+        process.stdout.write(
+          `moflo: CLAUDE.md injection ${report.state}; run \`flo doctor claudemd-drift\` or set auto_update.claudemd_injection_drift: regenerate in moflo.yaml\n`,
+        );
+      } catch { /* broken stdout — non-fatal */ }
+    }
+  } else if (report.state === 'no-marker') {
+    // Distinct from the drift cases — surface once via warn channel so a
+    // user who didn't run init still sees a nudge, but never auto-mutate.
+    if (autoUpdateConfig.claudemdInjectionDrift !== 'off') {
+      try {
+        process.stdout.write(
+          `moflo: CLAUDE.md has no MoFlo injection block; run \`npx flo-setup\` to add one\n`,
+        );
+      } catch { /* broken stdout — non-fatal */ }
     }
   }
-} catch (err) {
-  emitWarning(`hook-block drift check skipped (${errMessage(err)})`);
+
+  return {
+    cachePath,
+    claudeMdMtimeMs: finalMtime,
+    moduleMtimeMs,
+    state: finalState,
+  };
+}
+
+// Run the two drift detectors (settings.json hook block + CLAUDE.md
+// injection) in parallel. Both do their own statSync → cache compare →
+// dynamic import dance; the work is independent and the file targets are
+// different, so Promise.all halves cold-path latency on every session start.
+// Cache-hit fast paths return null with no work — Promise.all is still
+// trivially correct there.
+{
+  const hookEnabled = autoUpdateConfig.enabled && autoUpdateConfig.hookBlockDrift !== 'off';
+  const claudemdEnabled = autoUpdateConfig.enabled && autoUpdateConfig.claudemdInjectionDrift !== 'off';
+  const [hookResult, claudemdResult] = await Promise.all([
+    hookEnabled
+      ? runHookBlockDriftCheck().catch((err) => {
+          emitWarning(`hook-block drift check skipped (${errMessage(err)})`);
+          return null;
+        })
+      : Promise.resolve(null),
+    claudemdEnabled
+      ? runClaudeMdInjectionDriftCheck().catch((err) => {
+          emitWarning(`CLAUDE.md injection drift check skipped (${errMessage(err)})`);
+          return null;
+        })
+      : Promise.resolve(null),
+  ]);
+
+  if (hookResult) {
+    try {
+      mkdirSync(mofloDir(projectRoot), { recursive: true });
+      writeFileSync(hookResult.cachePath, JSON.stringify({
+        settingsMtimeMs: hookResult.settingsMtimeMs,
+        moduleMtimeMs: hookResult.moduleMtimeMs,
+        consumerHash: hookResult.consumerHash,
+        referenceHash: hookResult.referenceHash,
+      }));
+    } catch { /* cache is opportunistic — non-fatal */ }
+  }
+  if (claudemdResult) {
+    try {
+      mkdirSync(mofloDir(projectRoot), { recursive: true });
+      writeFileSync(claudemdResult.cachePath, JSON.stringify({
+        claudeMdMtimeMs: claudemdResult.claudeMdMtimeMs,
+        moduleMtimeMs: claudemdResult.moduleMtimeMs,
+        state: claudemdResult.state,
+      }));
+    } catch { /* cache is opportunistic — non-fatal */ }
+  }
 }
 
 // ── 3b. Ensure shipped guidance files exist (even without version change) ──

package/bin/setup-project.mjs

@@ -37,16 +37,14 @@ import { mofloInternalURL } from './lib/moflo-resolve.mjs';
 // works identically from bin/ (canonical) or from .claude/scripts/ (synced copy).
 const mofloRoot = dirname(fileURLToPath(mofloInternalURL('package.json')));
 
-// Single source of truth: claudemd-generator.ts owns the section content.
-// Use the shared mofloInternalURL helper so the script works identically when
-// invoked from bin/ (canonical) or from .claude/scripts/ (synced copy).
-const {
-  generateClaudeMd,
-  MARKER_START,
-  MARKER_END,
-  LEGACY_MARKER_STARTS,
-  LEGACY_MARKER_ENDS,
-} = await import(mofloInternalURL('dist/src/cli/init/claudemd-generator.js'));
+// Single source of truth: claudemd-generator.ts owns the section content,
+// claudemd-injection.ts owns the marker-replace logic. Use the shared
+// mofloInternalURL helper so the script works identically when invoked
+// from bin/ (canonical) or from .claude/scripts/ (synced copy).
+const { generateClaudeMd } = await import(mofloInternalURL('dist/src/cli/init/claudemd-generator.js'));
+const { applyInjectionReplacement, computeInjectionDrift } = await import(
+  mofloInternalURL('dist/src/cli/services/claudemd-injection.js')
+);
 
 const args = process.argv.slice(2);
 const updateOnly = args.includes('--update');
@@ -150,65 +148,47 @@ function cleanupLegacyBootstrap(projectRoot) {
 
 function updateClaudeMd(projectRoot) {
   const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+  const existed = existsSync(claudeMdPath);
+  const content = existed ? readFileSync(claudeMdPath, 'utf-8') : null;
 
-  if (!existsSync(claudeMdPath)) {
-    if (checkOnly) {
-      log('⚠️  No CLAUDE.md found');
-      return false;
-    }
-    log('📝 Creating CLAUDE.md with subagent protocol section');
-    writeFileSync(claudeMdPath, `# Project Configuration\n\n${CLAUDE_MD_SECTION}\n`, 'utf-8');
-    return true;
-  }
+  // Single source of truth for the marker-replace logic lives in
+  // src/cli/services/claudemd-injection.ts. Classify state for logging,
+  // then apply (or report) the replacement.
+  const report = computeInjectionDrift(content, CLAUDE_MD_SECTION);
 
-  const content = readFileSync(claudeMdPath, 'utf-8');
-
-  // Check for current or legacy markers and replace
-  const allStarts = [MARKER_START, ...LEGACY_MARKER_STARTS];
-  const allEnds = [MARKER_END, ...LEGACY_MARKER_ENDS];
-
-  for (let i = 0; i < allStarts.length; i++) {
-    if (content.includes(allStarts[i])) {
-      const startIdx = content.indexOf(allStarts[i]);
-      const endIdx = content.indexOf(allEnds[i]);
-
-      if (endIdx > startIdx) {
-        // If current markers and content matches, we're up to date
-        if (i === 0) {
-          const existingSection = content.substring(startIdx, endIdx + allEnds[i].length);
-          if (existingSection === CLAUDE_MD_SECTION) {
-            log('✅ CLAUDE.md moflo section is current');
-            return true;
-          }
-        }
-
-        // Replace (current or legacy) with new section
-        if (!checkOnly) {
-          const updated = content.substring(0, startIdx) + CLAUDE_MD_SECTION + content.substring(endIdx + allEnds[i].length);
-          writeFileSync(claudeMdPath, updated, 'utf-8');
-          log(i === 0 ? '📝 Updated CLAUDE.md moflo section' : '📝 Replaced legacy CLAUDE.md section with minimal moflo injection');
-        } else {
-          log('⚠️  CLAUDE.md moflo section needs update');
-        }
-        return true;
-      }
-    }
+  if (report.state === 'in-sync') {
+    log('✅ CLAUDE.md moflo section is current');
+    return true;
   }
 
+  // `updateOnly` is informational — refresh the bootstrap mirror file but
+  // leave CLAUDE.md alone unless an inject already exists.
   if (updateOnly) {
-    log('⚠️  CLAUDE.md has no moflo section (run without --update to add)');
-    return false;
+    if (!existed) { log('⚠️  No CLAUDE.md found'); return false; }
+    if (report.state === 'no-marker') {
+      log('⚠️  CLAUDE.md has no moflo section (run without --update to add)');
+      return false;
+    }
+    // Existing block (current or legacy) + drift → fall through to write.
   }
 
   if (checkOnly) {
-    log('⚠️  CLAUDE.md missing subagent protocol section');
+    if (!existed) { log('⚠️  No CLAUDE.md found'); return false; }
+    if (report.state === 'no-marker') { log('⚠️  CLAUDE.md missing subagent protocol section'); return false; }
+    log('⚠️  CLAUDE.md moflo section needs update');
     return false;
   }
 
-  // Append section to end of CLAUDE.md
-  const separator = content.endsWith('\n') ? '\n' : '\n\n';
-  writeFileSync(claudeMdPath, content + separator + CLAUDE_MD_SECTION + '\n', 'utf-8');
-  log('📝 Added subagent protocol section to CLAUDE.md');
+  const result = applyInjectionReplacement(content, CLAUDE_MD_SECTION);
+  if (!result.changed) return true;
+  writeFileSync(claudeMdPath, result.contents, 'utf-8');
+
+  switch (report.state) {
+    case 'no-file':       log('📝 Creating CLAUDE.md with subagent protocol section'); break;
+    case 'no-marker':     log('📝 Added subagent protocol section to CLAUDE.md'); break;
+    case 'legacy-marker': log('📝 Replaced legacy CLAUDE.md section with minimal moflo injection'); break;
+    case 'drifted':       log('📝 Updated CLAUDE.md moflo section'); break;
+  }
   return true;
 }