moflo 4.9.11 → 4.9.13

package/bin/hooks.mjs

@@ -22,7 +22,7 @@
 import { spawn } from 'child_process';
 import { existsSync, appendFileSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { createProcessManager } from './lib/process-manager.mjs';
 import { shouldDaemonAutoStart } from './lib/daemon-config.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
@@ -520,7 +520,7 @@ let _getDaemonLockHolder = null;
 try {
   const daemonLockPath = resolve(__dirname, '..', 'src', '@claude-flow', 'cli', 'dist', 'src', 'services', 'daemon-lock.js');
   if (existsSync(daemonLockPath)) {
-    const mod = await import('file://' + daemonLockPath.replace(/\\/g, '/'));
+    const mod = await import(pathToFileURL(daemonLockPath).href);
     _getDaemonLockHolder = mod.getDaemonLockHolder;
   }
 } catch { /* fallback below */ }

package/bin/index-guidance.mjs

@@ -28,6 +28,7 @@ import { fileURLToPath } from 'url';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath } from './lib/moflo-paths.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
+import { createProcessManager } from './lib/process-manager.mjs';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
@@ -872,36 +873,25 @@ if (!skipEmbeddings && needsEmbeddings) {
   console.log('');
   log('Spawning embedding generation in background...');
 
-  const { spawn } = await import('child_process');
-
   const embeddingScript = resolveMofloBin(
     projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
   );
 
   if (embeddingScript) {
-    const embeddingArgs = ['--namespace', NAMESPACE];
-
-    // Create log file for background process output
-    const logDir = resolve(projectRoot, '.moflo/logs');
-    if (!existsSync(logDir)) {
-      mkdirSync(logDir, { recursive: true });
+    // 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.
+    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`);
+    } else {
+      log('⚠️  Failed to spawn background embedding');
     }
-    const logFile = resolve(logDir, 'embeddings.log');
-    const { openSync } = await import('fs');
-    const out = openSync(logFile, 'a');
-    const err = openSync(logFile, 'a');
-
-    // Spawn in background - don't wait for completion
-    const proc = spawn('node', [embeddingScript, ...embeddingArgs], {
-      stdio: ['ignore', out, err],
-      cwd: projectRoot,
-      detached: true,
-      windowsHide: true  // Suppress command windows on Windows
-    });
-    proc.unref();  // Allow parent to exit independently
-
-    log(`Background embedding started (PID: ${proc.pid})`);
-    log(`Log file: .moflo/logs/embeddings.log`);
   } else {
     log('⚠️  Embedding script not found, skipping embedding generation');
   }

package/bin/index-patterns.mjs

@@ -27,11 +27,11 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { resolve, dirname, relative, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
-import { spawn } from 'child_process';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
+import { createProcessManager } from './lib/process-manager.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -342,20 +342,23 @@ async function main() {
   // Save hash
   writeFileSync(HASH_CACHE_PATH, currentHash, 'utf-8');
 
-  // Trigger embedding generation in background
+  // Trigger embedding generation in background. Register with the shared
+  // ProcessManager (#886) so doctor's zombie scan allowlists it and the
+  // session-end / smoke-teardown drain reaps it. Stable label dedupes against
+  // the index-all chain's later `build-embeddings` step when both run within
+  // the same lock window.
   try {
     const embeddingScript = resolveMofloBin(
       projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
     );
     if (embeddingScript) {
-      const child = spawn('node', [embeddingScript, '--namespace', NAMESPACE], {
-        cwd: projectRoot,
-        detached: true,
-        stdio: 'ignore',
-        windowsHide: true,
-      });
-      child.unref();
-      debug('Embedding generation started in background');
+      const pm = createProcessManager(projectRoot);
+      const result = pm.spawn('node', [embeddingScript, '--namespace', NAMESPACE], `build-embeddings-${NAMESPACE}`);
+      if (result.skipped) {
+        debug(`Embedding generation already running (PID: ${result.pid})`);
+      } else if (result.pid) {
+        debug(`Embedding generation started in background (PID: ${result.pid})`);
+      }
     }
   } catch { /* ignore */ }
 

package/bin/session-start-launcher.mjs

@@ -10,7 +10,7 @@
 import { spawn, execFileSync } from 'child_process';
 import { existsSync, readFileSync, writeFileSync, copyFileSync, unlinkSync, readdirSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname, join } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { mofloDir } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
@@ -218,11 +218,17 @@ try {
   // own errors if the DB is still broken.
 }
 
-// ── 0d. Clear post-install restart notice when version is current (#867) ───
+// ── 0d. Silently clear post-install restart notice when version is current (#867, #887) ─
 // scripts/post-install-notice.mjs drops `.moflo/restart-pending.json` on every
 // `npm install moflo`. The UserPromptSubmit hook surfaces it on every prompt
 // until cleared, so this session only sees the message between install and
 // the FIRST restart that actually picks up the new bits.
+//
+// Cleanup is silent (#887): the user already saw + acted on the restart prompt
+// — surfacing a "cleared notice" line on the very next session reads like an
+// error in additionalContext and inflates mutationCount, which would also fire
+// the closing "starting background tasks" framing. Both are noise on a
+// successful post-restart session.
 try {
   const pendingPath = join(mofloDir(projectRoot), 'restart-pending.json');
   const pkgPath = resolve(projectRoot, 'node_modules/moflo/package.json');
@@ -231,7 +237,6 @@ try {
   if (pending && typeof pending.version === 'string' && pending.version === installedVersion) {
     unlinkSync(pendingPath);
     try { unlinkSync(join(mofloDir(projectRoot), 'last-install-banner.json')); } catch { /* tracker may not exist */ }
-    emitMutation('cleared post-install restart notice', `${installedVersion} now running`);
   }
 } catch { /* file missing or malformed — silent fast-path */ }
 
@@ -304,7 +309,7 @@ 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 };
+let autoUpdateConfig = { enabled: true, scripts: true, helpers: true, hookBlockDrift: 'warn' };
 try {
   const mofloYaml = resolve(projectRoot, 'moflo.yaml');
   if (existsSync(mofloYaml)) {
@@ -313,9 +318,12 @@ try {
     const enabledMatch = yamlContent.match(/auto_update:\s*\n\s+enabled:\s*(true|false)/);
     const scriptsMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+scripts:\s*(true|false)/);
     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)/);
     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];
   }
 } catch (err) {
   // Defaults (all true) keep the upgrade flow alive but the user should
@@ -401,7 +409,7 @@ try {
         ];
         const cherryPickPath = cherryPickPaths.find((p) => existsSync(p));
         if (cherryPickPath) {
-          const mod = await import(`file://${cherryPickPath.replace(/\\/g, '/')}`);
+          const mod = await import(pathToFileURL(cherryPickPath).href);
           if (typeof mod.cherryPickLearningsFromLegacy === 'function') {
             const result = await mod.cherryPickLearningsFromLegacy({ projectRoot });
             if (result.copied > 0) {
@@ -850,7 +858,7 @@ try {
       ];
       const hwPath = hwPaths.find(p => existsSync(p));
       if (hwPath) {
-        const mod = await import(`file://${hwPath.replace(/\\/g, '/')}`);
+        const mod = await import(pathToFileURL(hwPath).href);
         if (typeof mod.rewriteIncorrectHookWiring === 'function') {
           const { rewrites } = mod.rewriteIncorrectHookWiring(settings);
           if (rewrites.length > 0) {
@@ -881,6 +889,158 @@ try {
   emitWarning(`settings.json migration failed (${errMessage(err)})`);
 }
 
+// ── 3a-vi. Hook-block drift detection (#881) ───────────────────────────────
+// Hash the consumer's settings.json hook block against the reference block
+// `generateHooksConfig()` would produce for this moflo version. Catches
+// drift the per-bug `repairHookWiring` / `rewriteIncorrectHookWiring` rules
+// don't cover (future hook events, partial migrations, hand-edited commands).
+// Runs every session under `auto_update.enabled`, not only on version change.
+//
+// Modes (`auto_update.hook_block_drift` in moflo.yaml):
+//   warn        — print a one-line summary + diff to stdout (default)
+//   regenerate  — additively add missing hooks; falls back to warn when the
+//                 consumer has extra (custom) hooks, to avoid clobbering
+//   off         — skip entirely
+//
+// Also respects a `claudeFlow.hooks.locked: true` sentinel in settings.json
+// — if set, the user has explicitly opted out of drift surfacing.
+// Fast-path: `.moflo/hook-drift-cache.json` records the last clean run. If
+// settings.json + the dist module both still match the cached mtimes and the
+// cached check was clean (consumerHash === referenceHash), skip readFile +
+// JSON.parse + dynamic import entirely. This block runs every session; the
+// cache makes it ~free in the steady state.
+//
+// Returns the values to persist on the slow path, or null when skipped
+// (cache hit, no settings.json, no dist module, locked, etc.). Pulled out
+// to keep the guard chain flat — the original inline form was 9 levels deep.
+async function runHookBlockDriftCheck() {
+  const settingsPath = resolve(projectRoot, '.claude', 'settings.json');
+  let settingsStat;
+  try { settingsStat = statSync(settingsPath); } catch { return null; }
+
+  // statSync each candidate doubles as existence check + provides the mtime
+  // we need for the cache key, avoiding the existsSync→import TOCTOU pattern.
+  const hbhCandidates = [
+    resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/hook-block-hash.js'),
+    resolve(projectRoot, 'dist/src/cli/services/hook-block-hash.js'),
+  ];
+  let hbhPath = null;
+  let hbhStat = null;
+  for (const p of hbhCandidates) {
+    try { hbhStat = statSync(p); hbhPath = p; break; } catch { /* try next */ }
+  }
+  if (!hbhPath) return null;
+
+  // Fast-path requires consumerHash === referenceHash (a previously *clean*
+  // run). A drifted-but-cached state still needs to re-emit the warning each
+  // session, so we always re-do the work in that case.
+  const cachePath = join(mofloDir(projectRoot), 'hook-drift-cache.json');
+  let cached = null;
+  try { cached = JSON.parse(readFileSync(cachePath, 'utf-8')); } catch { /* missing or corrupt */ }
+  if (
+    cached &&
+    cached.settingsMtimeMs === settingsStat.mtimeMs &&
+    cached.moduleMtimeMs === hbhStat.mtimeMs &&
+    cached.consumerHash === cached.referenceHash
+  ) return null;
+
+  // Try-catch around the dynamic import handles the file disappearing
+  // between statSync and import (TOCTOU); module-load errors fall through.
+  let mod = null;
+  try { mod = await import(pathToFileURL(hbhPath).href); } catch { /* TOCTOU or load error — skip */ return null; }
+  if (typeof mod.computeHookBlockDrift !== 'function') return null;
+
+  const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  if (typeof mod.isHookBlockLocked === 'function' && mod.isHookBlockLocked(settings)) return null;
+
+  const report = mod.computeHookBlockDrift(settings.hooks || {});
+  let regenerated = false;
+
+  if (report.drifted) {
+    const wantRegenerate = autoUpdateConfig.hookBlockDrift === 'regenerate';
+    // #896: regenerate is wholesale when available — the additive variant
+    // can't drop stale extras (e.g. the `gate.cjs session-reset` SessionStart
+    // hook removed in #842), which is the very case consumers hit. Older
+    // moflo installs without `applyWholesaleRegeneration` fall back to the
+    // additive path, which still heals purely-additive drift.
+    const wholesale = wantRegenerate && typeof mod.applyWholesaleRegeneration === 'function';
+    const additiveSafe = wantRegenerate && !wholesale &&
+      report.extra.length === 0 && typeof mod.applyAdditiveRegeneration === 'function';
+    if (wholesale) {
+      const { added, removed } = mod.applyWholesaleRegeneration(settings, report);
+      if (added > 0 || removed > 0) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        regenerated = true;
+        const parts = [];
+        if (added > 0) parts.push(`added ${plural(added, 'missing entry')}`);
+        if (removed > 0) parts.push(`removed ${plural(removed, 'stale entry')}`);
+        emitMutation(
+          'regenerated hook block',
+          `${parts.join(', ')} (drift ${report.consumerHash} → ${report.referenceHash})`,
+        );
+      }
+    } else if (additiveSafe) {
+      const { added } = mod.applyAdditiveRegeneration(settings, report);
+      if (added > 0) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        regenerated = true;
+        emitMutation(
+          'regenerated hook block',
+          `added ${plural(added, 'missing hook entry')} (drift ${report.consumerHash} → ${report.referenceHash})`,
+        );
+      }
+    } else {
+      const parts = [];
+      if (report.missing.length > 0) parts.push(plural(report.missing.length, 'missing entry'));
+      if (report.extra.length > 0) parts.push(`${plural(report.extra.length, 'custom hook')} preserved`);
+      const reason = parts.join(', ') || 'reordered';
+      // stdout (not stderr) so Claude sees this in `additionalContext` and
+      // surfaces it to the user — not a mutation since we didn't change anything.
+      try {
+        process.stdout.write(
+          `moflo: hook block drift (${reason}); run \`flo doctor hook-drift\` or set auto_update.hook_block_drift: regenerate in moflo.yaml\n`,
+        );
+      } catch { /* broken stdout — non-fatal */ }
+    }
+  }
+
+  // Regeneration mutated settings.json — re-stat for the fresh mtime so next
+  // session's fast-path matches; otherwise reuse the stat we already have.
+  let finalSettingsMtime = settingsStat.mtimeMs;
+  if (regenerated) {
+    try { finalSettingsMtime = statSync(settingsPath).mtimeMs; } catch { /* keep prior */ }
+  }
+  // After successful regeneration consumerHash matches referenceHash by construction.
+  const finalConsumerHash = regenerated ? report.referenceHash : report.consumerHash;
+
+  return {
+    cachePath,
+    settingsMtimeMs: finalSettingsMtime,
+    moduleMtimeMs: hbhStat.mtimeMs,
+    consumerHash: finalConsumerHash,
+    referenceHash: report.referenceHash,
+  };
+}
+
+try {
+  if (autoUpdateConfig.enabled && autoUpdateConfig.hookBlockDrift !== 'off') {
+    const result = await runHookBlockDriftCheck();
+    if (result) {
+      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 */ }
+    }
+  }
+} catch (err) {
+  emitWarning(`hook-block drift check skipped (${errMessage(err)})`);
+}
+
 // ── 3b. Ensure shipped guidance files exist (even without version change) ──
 // Subagents need these files on disk for direct reads without memory search.
 // Also prunes top-level mirrors whose source no longer exists in shipped/
@@ -962,6 +1122,40 @@ try {
   }
 } catch { /* non-fatal */ }
 
+// ── 3d-yaml-create. Create moflo.yaml if missing (#895) ────────────────────
+// Sibling self-heal to 3d-yaml: that block APPENDS new sections to existing
+// yaml; this block CREATES the file from the canonical template when no yaml
+// exists at all. Without it, consumers picking up new defaults via npm-install
+// (e.g. PR #894 flipped model_routing.enabled to true) have no surface to
+// see/tune them — the DEFAULT_CONFIG fallback is invisible.
+//
+// Runs BEFORE 3d-yaml so the appender has a file to work with on the same
+// session. Steady-state hot path: the existsSync check below short-circuits
+// before any module load, so consumers with an existing yaml pay one stat call.
+try {
+  if (!existsSync(resolve(projectRoot, 'moflo.yaml'))) {
+    const tplPaths = [
+      resolve(projectRoot, 'node_modules/moflo/dist/src/cli/init/moflo-yaml-template.js'),
+      resolve(projectRoot, 'dist/src/cli/init/moflo-yaml-template.js'),
+    ];
+    const tplPath = tplPaths.find((p) => existsSync(p));
+    if (tplPath) {
+      const { ensureMofloYamlExists } = await import(pathToFileURL(tplPath).href);
+      const result = ensureMofloYamlExists(projectRoot);
+      if (result?.created) {
+        emitMutation(
+          'created moflo.yaml',
+          'review defaults — model routing, sandbox, gates, hooks',
+        );
+      }
+    }
+  }
+} catch (err) {
+  // Non-fatal — DEFAULT_CONFIG fallback still gives correct behavior; user
+  // just loses the visible/tunable surface until next session retries (#854).
+  emitWarning(`moflo.yaml create skipped (${errMessage(err)})`);
+}
+
 // ── 3d-yaml. Append missing top-level sections to moflo.yaml ───────────────
 // Users must never be required to re-run `moflo init` after a version bump.
 // When moflo ships a new top-level config section (e.g. sandbox:), append it
@@ -976,7 +1170,7 @@ try {
   const upgraderPath = upgraderPaths.find((p) => existsSync(p));
   const mofloYaml = resolve(projectRoot, 'moflo.yaml');
   if (upgraderPath && existsSync(mofloYaml)) {
-    const { ensureYamlSections } = await import(`file://${upgraderPath.replace(/\\/g, '/')}`);
+    const { ensureYamlSections } = await import(pathToFileURL(upgraderPath).href);
     const appended = ensureYamlSections(mofloYaml);
     if (Array.isArray(appended) && appended.length > 0) {
       emitMutation(
@@ -995,7 +1189,7 @@ try {
   const localShimLib = resolve(projectRoot, 'bin/lib/install-global-shim.mjs');
   const shimPath = existsSync(shimLib) ? shimLib : existsSync(localShimLib) ? localShimLib : null;
   if (shimPath) {
-    const { installGlobalShim } = await import(`file://${shimPath.replace(/\\/g, '/')}`);
+    const { installGlobalShim } = await import(pathToFileURL(shimPath).href);
     const shimResult = installGlobalShim({ silent: true });
     if (shimResult?.installed) {
       emitMutation('installed global flo shim', 'bare `flo` now resolves to project install');
@@ -1022,7 +1216,7 @@ try {
   ];
   const migrationPath = migrationPaths.find((p) => existsSync(p));
   if (migrationPath) {
-    const mod = await import(`file://${migrationPath.replace(/\\/g, '/')}`);
+    const mod = await import(pathToFileURL(migrationPath).href);
     if (typeof mod.runEmbeddingsMigrationIfNeeded === 'function') {
       await mod.runEmbeddingsMigrationIfNeeded({
         out: process.stderr,
@@ -1058,7 +1252,7 @@ try {
   ];
   const purgePath = purgePaths.find((p) => existsSync(p));
   if (purgePath) {
-    const { purgeSoftDeletedEntries } = await import(`file://${purgePath.replace(/\\/g, '/')}`);
+    const { purgeSoftDeletedEntries } = await import(pathToFileURL(purgePath).href);
     const result = await purgeSoftDeletedEntries();
     if (result?.purged > 0) {
       emitMutation(
@@ -1090,7 +1284,7 @@ try {
   ];
   const purgePath = purgePaths.find((p) => existsSync(p));
   if (purgePath) {
-    const { purgeEphemeralNamespaces } = await import(`file://${purgePath.replace(/\\/g, '/')}`);
+    const { purgeEphemeralNamespaces } = await import(pathToFileURL(purgePath).href);
     const result = await purgeEphemeralNamespaces();
     if (result?.purged > 0) {
       emitMutation(

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

@@ -552,4 +552,80 @@ export async function checkGateHealth() {
         message: `${caseCount} gate cases, ${hookCount} hook bindings, state file OK`,
     };
 }
+/**
+ * Hash-based hook-block drift check (#881). Complements `checkGateHealth`'s
+ * required-pattern probe by detecting drift in *any* direction — missing
+ * events, modified commands, future hook events not yet covered by
+ * `REQUIRED_HOOK_WIRING`. Uses the self-contained `hook-block-hash` module so
+ * the same logic runs in `flo doctor`, the launcher, and unit tests.
+ *
+ * Reports `pass` when no drift, `warn` with a count summary when drift exists.
+ * Never `fail` — drift is informational; the user (or `regenerate` mode) is
+ * responsible for deciding what to do.
+ */
+export async function checkHookBlockDrift() {
+    const projectDir = findConsumerProjectDir();
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (!existsSync(settingsPath)) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'warn',
+            message: '.claude/settings.json not found',
+            fix: 'npx moflo init',
+        };
+    }
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    }
+    catch (e) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'warn',
+            message: `cannot parse .claude/settings.json: ${errorDetail(e)}`,
+        };
+    }
+    const { computeHookBlockDrift, isHookBlockLocked } = await import('../services/hook-block-hash.js');
+    if (isHookBlockLocked(settings)) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'pass',
+            message: 'drift check skipped — claudeFlow.hooks.locked: true',
+        };
+    }
+    // #896: respect `auto_update.hook_block_drift: off` — opt-out for consumers
+    // who explicitly don't want drift surfaced (mirrors the launcher's behaviour).
+    try {
+        const { loadMofloConfig } = await import('../config/moflo-config.js');
+        const cfg = loadMofloConfig(projectDir);
+        if (cfg.auto_update.hook_block_drift === 'off') {
+            return {
+                name: 'Hook Block Drift',
+                status: 'pass',
+                message: 'drift check skipped — auto_update.hook_block_drift: off',
+            };
+        }
+    }
+    catch { /* config read failure — fall through to drift check */ }
+    const report = computeHookBlockDrift(settings.hooks ?? {});
+    if (!report.drifted) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'pass',
+            message: `hook block matches reference (${report.consumerHash})`,
+        };
+    }
+    const parts = [];
+    parts.push(`drift ${report.consumerHash} vs ${report.referenceHash}`);
+    if (report.missing.length > 0)
+        parts.push(`${report.missing.length} missing`);
+    if (report.extra.length > 0)
+        parts.push(`${report.extra.length} custom`);
+    return {
+        name: 'Hook Block Drift',
+        status: 'warn',
+        message: parts.join(', '),
+        fix: 'set auto_update.hook_block_drift: regenerate in moflo.yaml, or claudeFlow.hooks.locked: true to suppress',
+    };
+}
 //# sourceMappingURL=doctor-checks-deep.js.map

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

@@ -12,7 +12,7 @@ import { execSync, exec } from 'child_process';
 import { promisify } from 'util';
 import os from 'os';
 import { getDaemonLockHolder, releaseDaemonLock, isDaemonProcess } from '../services/daemon-lock.js';
-import { checkSubagentHealth, checkSpellExecution, checkMcpToolInvocation, checkHookExecution, checkMcpSpellIntegration, checkGateHealth, checkMofloDbBridge, getMofloRoot, } from './doctor-checks-deep.js';
+import { checkSubagentHealth, checkSpellExecution, checkMcpToolInvocation, checkHookExecution, checkMcpSpellIntegration, checkGateHealth, checkHookBlockDrift, checkMofloDbBridge, getMofloRoot, } from './doctor-checks-deep.js';
 import { checkEmbeddingHygiene } from './doctor-embedding-hygiene.js';
 import { checkSwarmFunctional, checkHiveMindFunctional, } from './doctor-checks-swarm.js';
 import { checkMemoryAccessFunctional } from './doctor-checks-memory-access.js';
@@ -773,6 +773,52 @@ async function fixGateHealthHooks() {
         return false;
     }
 }
+// Check moflo.yaml exists and contains all required top-level sections (#895).
+// Catches three failure modes:
+//   1. File missing — session-start should have created it; warn user that
+//      defaults are invisible/untunable.
+//   2. File empty / unreadable — corrupted by half-write or filesystem error.
+//   3. Top-level sections missing — partial yaml from manual edit or stale
+//      copy from a moflo version that didn't ship a section yet. The
+//      session-start yaml-upgrader would normally backfill these, but the
+//      diagnostic surfaces it for users who never restarted.
+//
+// Exported so tests can exercise it end-to-end against a temp project root
+// without mutating process.cwd() (which fights vitest's parallel test runner).
+export async function checkMofloYamlCompliance(cwd = process.cwd()) {
+    const yamlPath = join(cwd, 'moflo.yaml');
+    // Lazy-import the validator so doctor doesn't pull in fs walks on the
+    // happy path of unrelated checks.
+    const { validateMofloYaml } = await import('../init/moflo-yaml-template.js');
+    const result = validateMofloYaml(yamlPath);
+    if (!result.exists) {
+        return {
+            name: 'moflo.yaml',
+            status: 'warn',
+            message: 'moflo.yaml not found — defaults are in effect but not visible/tunable',
+            fix: 'Restart Claude Code (session-start auto-creates) or run `npx moflo init`',
+        };
+    }
+    if (result.valid) {
+        return { name: 'moflo.yaml', status: 'pass', message: `Compliant (${yamlPath})` };
+    }
+    const parseIssue = result.issues.find((i) => i.kind !== 'missing-section');
+    if (parseIssue) {
+        return {
+            name: 'moflo.yaml',
+            status: 'fail',
+            message: `${parseIssue.kind}: ${parseIssue.detail}`,
+            fix: 'Inspect/repair moflo.yaml, or `mv moflo.yaml moflo.yaml.bak && npx moflo init`',
+        };
+    }
+    // Missing sections — recoverable on next session-start via yaml-upgrader.
+    return {
+        name: 'moflo.yaml',
+        status: 'warn',
+        message: `Missing sections: ${result.missingSections.join(', ')}`,
+        fix: 'Restart Claude Code (yaml-upgrader auto-appends) or `npx moflo init --force`',
+    };
+}
 // Check test directories configured in moflo.yaml
 async function checkTestDirs() {
     const yamlPath = join(process.cwd(), 'moflo.yaml');
@@ -1529,6 +1575,7 @@ export const doctorCommand = {
             checkGit,
             checkGitRepo,
             checkConfigFile,
+            checkMofloYamlCompliance,
             checkStatusLine,
             checkDaemonStatus,
             checkMemoryDatabase,
@@ -1548,6 +1595,7 @@ export const doctorCommand = {
             checkMcpSpellIntegration,
             checkHookExecution,
             checkGateHealth,
+            checkHookBlockDrift,
             checkMofloDbBridge,
             // Issue #818 / epic #798 — coordinator-path tripwires. They share the
             // singleton coordinator with checkSubagentHealth above and assert by
@@ -1569,6 +1617,8 @@ export const doctorCommand = {
             'npm': checkNpmVersion,
             'claude': checkClaudeCode,
             'config': checkConfigFile,
+            'yaml': checkMofloYamlCompliance,
+            'moflo-yaml': checkMofloYamlCompliance,
             'statusline': checkStatusLine,
             'status-line': checkStatusLine,
             'daemon': checkDaemonStatus,
@@ -1595,6 +1645,8 @@ export const doctorCommand = {
             'hooks': checkHookExecution,
             'gates': checkGateHealth,
             'gate': checkGateHealth,
+            'hook-drift': checkHookBlockDrift,
+            'drift': checkHookBlockDrift,
             'sandbox': checkSandboxTier,
             'sandbox-tier': checkSandboxTier,
             'moflodb': checkMofloDbBridge,