moflo 4.9.10 → 4.9.12

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

@@ -552,4 +552,66 @@ 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',
+        };
+    }
+    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';
@@ -1114,12 +1114,37 @@ function killTrackedProcesses() {
     catch { /* ok */ }
     return killed;
 }
+// Read the set of moflo background PIDs registered with the shared
+// ProcessManager (.moflo/background-pids.json). These are legitimate tracked
+// background tasks (sequential indexer chain, daemon, MCP servers spawned by
+// session-start) — they are detached:true by design so their parents have
+// already exited, but they are NOT orphans. Without this allow-set,
+// findZombieProcesses() flags every running indexer step as a zombie.
+function readTrackedBackgroundPids() {
+    const result = new Set();
+    const registryFile = join(process.cwd(), '.moflo', 'background-pids.json');
+    try {
+        if (!existsSync(registryFile))
+            return result;
+        const entries = JSON.parse(readFileSync(registryFile, 'utf-8'));
+        if (!Array.isArray(entries))
+            return result;
+        for (const entry of entries) {
+            if (entry && typeof entry.pid === 'number' && entry.pid > 0) {
+                result.add(entry.pid);
+            }
+        }
+    }
+    catch { /* malformed or unreadable — treat as empty */ }
+    return result;
+}
 // Find and optionally kill orphaned moflo/claude-flow node processes.
 // A process is only "orphaned" if its parent is no longer alive — meaning
 // nothing will clean it up. MCP servers spawned by a live Claude Code session
 // have a live parent (claude.exe) and must not be flagged.
 async function findZombieProcesses(kill = false) {
     const legitimatePid = getDaemonLockHolder(process.cwd());
+    const trackedPids = readTrackedBackgroundPids();
     const currentPid = process.pid;
     const parentPid = process.ppid;
     const found = [];
@@ -1161,6 +1186,11 @@ async function findZombieProcesses(kill = false) {
     for (const { pid, ppid } of candidates) {
         if (pid === currentPid || pid === parentPid || pid === legitimatePid)
             continue;
+        // Tracked background tasks (indexer chain, etc.) are detached:true so their
+        // parent is dead by design. The ProcessManager registry tells us they are
+        // legitimate, not orphaned.
+        if (trackedPids.has(pid))
+            continue;
         if (isProcessAlive(ppid))
             continue;
         // Defense-in-depth: detached daemons have dead parents by design.
@@ -1518,6 +1548,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
@@ -1565,6 +1596,8 @@ export const doctorCommand = {
             'hooks': checkHookExecution,
             'gates': checkGateHealth,
             'gate': checkGateHealth,
+            'hook-drift': checkHookBlockDrift,
+            'drift': checkHookBlockDrift,
             'sandbox': checkSandboxTier,
             'sandbox-tier': checkSandboxTier,
             'moflodb': checkMofloDbBridge,

package/dist/src/cli/config/moflo-config.js

@@ -59,11 +59,11 @@ const DEFAULT_CONFIG = {
     models: {
         default: 'opus',
         research: 'sonnet',
-        review: 'opus',
+        review: 'sonnet',
         test: 'sonnet',
     },
     model_routing: {
-        enabled: false,
+        enabled: true,
         confidence_threshold: 0.85,
         cost_optimization: true,
         circuit_breaker: true,
@@ -82,6 +82,7 @@ const DEFAULT_CONFIG = {
         enabled: true,
         scripts: true,
         helpers: true,
+        hook_block_drift: 'warn',
     },
     sandbox: {
         enabled: false,
@@ -205,6 +206,12 @@ function mergeConfig(raw, root) {
             enabled: raw.auto_update?.enabled ?? raw.autoUpdate?.enabled ?? DEFAULT_CONFIG.auto_update.enabled,
             scripts: raw.auto_update?.scripts ?? raw.autoUpdate?.scripts ?? DEFAULT_CONFIG.auto_update.scripts,
             helpers: raw.auto_update?.helpers ?? raw.autoUpdate?.helpers ?? DEFAULT_CONFIG.auto_update.helpers,
+            hook_block_drift: (() => {
+                const v = raw.auto_update?.hook_block_drift ?? raw.autoUpdate?.hookBlockDrift;
+                return v === 'regenerate' || v === 'off' || v === 'warn'
+                    ? v
+                    : DEFAULT_CONFIG.auto_update.hook_block_drift;
+            })(),
         },
         sandbox: {
             enabled: raw.sandbox?.enabled ?? DEFAULT_CONFIG.sandbox.enabled,
@@ -385,7 +392,7 @@ models:
 # When enabled, overrides the static model preferences above
 # by analyzing task complexity and routing to the cheapest capable model.
 model_routing:
-  enabled: false                   # Set to true to enable dynamic routing
+  enabled: true                    # Set to false to pin to the static models above
   confidence_threshold: 0.85       # Min confidence before escalating to a more capable model
   cost_optimization: true          # Prefer cheaper models when confidence is high
   circuit_breaker: true            # Penalize models that fail repeatedly
@@ -398,6 +405,10 @@ 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
+                                 # warn = print drift summary on session start (default)
+                                 # regenerate = auto-add missing hooks (only when no customisations)
+                                 # off = skip detection entirely
 
 # OS-level sandbox for spell bash steps
 # Denylist always runs regardless of this setting

package/dist/src/cli/index.js

@@ -11,6 +11,7 @@ import { suggestCommand } from './suggest.js';
 import { runStartupUpdateCheck } from './update/index.js';
 import { loadMofloConfig } from './config/moflo-config.js';
 import { getDaemonLockHolder } from './services/daemon-lock.js';
+import { registerBackgroundPid } from './services/process-registry.js';
 import { VERSION } from './version.js';
 export { VERSION };
 const LONG_RUNNING_COMMANDS = ['mcp', 'daemon'];
@@ -461,6 +462,23 @@ export class CLI {
                 env: { ...process.env, CLAUDE_FLOW_DAEMON: '1' },
             });
         child.unref();
+        // Register the spawned daemon PID with the shared ProcessManager so that
+        // pm.killAll() (called by the session-end hook) can reap it, AND doctor's
+        // zombie scan recognises it as a tracked process rather than an orphan.
+        // Without this, every consumer's first `flo doctor` after a CLI command
+        // sees the auto-started daemon as a "zombie" because its parent (this
+        // CLI process) has already exited. SYNCHRONOUS — must complete before any
+        // concurrent doctor scan runs the registry read.
+        if (child.pid) {
+            try {
+                registerBackgroundPid(projectRoot, child.pid, 'daemon', spawnArgs.slice(1).join(' '));
+            }
+            catch {
+                // Registration is non-essential — daemon still works, just not visible
+                // to PM-aware tooling. Stay silent to keep maybeAutoStartDaemon a
+                // fire-and-forget helper.
+            }
+        }
     }
     /**
      * Load configuration file

package/dist/src/cli/init/moflo-init.js

@@ -382,17 +382,19 @@ status_line:
   show_mcp: true
 
 # Model preferences (haiku, sonnet, opus)
+# These are static fallbacks. When model_routing.enabled is true (default),
+# the dynamic router takes precedence based on task complexity.
 models:
-  default: opus        # Model for general tasks
+  default: opus        # Model for general tasks (kept high for unknowns)
   research: sonnet     # Model for research/exploration agents
-  review: opus         # Model for code review agents
+  review: sonnet       # Code review never needs opus reasoning
   test: sonnet         # Model for test-writing agents
 
 # Intelligent model routing (auto-selects haiku/sonnet/opus per task)
 # When enabled, overrides the static model preferences above
 # by analyzing task complexity and routing to the cheapest capable model.
 model_routing:
-  enabled: false                   # Set to true to enable dynamic routing
+  enabled: true                    # Set to false to pin to the static models above
   confidence_threshold: 0.85       # Min confidence before escalating to a more capable model
   cost_optimization: true          # Prefer cheaper models when confidence is high
   circuit_breaker: true            # Penalize models that fail repeatedly
@@ -498,8 +500,13 @@ function generateHooks(root, force, answers) {
                 "hooks": [{ "type": "command", "command": gateHook('record-skill-run'), "timeout": 2000 }]
             },
             {
+                // Use gateHook (not gate) so the wrapper forwards Claude Code's session_id as
+                // HOOK_SESSION_ID — record-memory-searched needs this to mark the per-actor map
+                // (memorySearchedBy[sid]) that check-before-read consults under #838's per-actor gating.
+                // Without it, the legacy boolean is set but the per-actor map stays empty, and the gate
+                // blocks every Read forever within the turn (issue #879).
                 "matcher": "mcp__moflo__memory_",
-                "hooks": [{ "type": "command", "command": gate('record-memory-searched'), "timeout": 3000 }]
+                "hooks": [{ "type": "command", "command": gateHook('record-memory-searched'), "timeout": 3000 }]
             },
             {
                 "matcher": "^mcp__moflo__memory_store$",
@@ -511,6 +518,14 @@ function generateHooks(root, force, answers) {
                 "hooks": [
                     { "type": "command", "command": `node "$CLAUDE_PROJECT_DIR/.claude/helpers/prompt-hook.mjs"`, "timeout": 3000 }
                 ]
+            },
+            {
+                // prompt-reminder is REQUIRED to reset memorySearched/memorySearchedBy on each
+                // new prompt and reclassify memoryRequired. Without it, gate state leaks across
+                // prompts. Separate hook entry so a prompt-hook.mjs exception doesn't skip the reset.
+                "hooks": [
+                    { "type": "command", "command": gateHook('prompt-reminder'), "timeout": 3000 }
+                ]
             }
         ],
         "SubagentStart": [

package/dist/src/cli/init/settings-generator.js

@@ -270,9 +270,14 @@ function generateHooksConfig(config) {
                 hooks: [{ type: 'command', command: gateHookCmd('record-skill-run'), timeout: 2000 }],
             },
             {
-                // Simplified matcher — anchored regex with parens doesn't match MCP tool names reliably
+                // Simplified matcher — anchored regex with parens doesn't match MCP tool names reliably.
+                // Use gateHookCmd (not gateCmd) so the wrapper forwards Claude Code's session_id as
+                // HOOK_SESSION_ID — record-memory-searched needs this to mark the per-actor map
+                // (memorySearchedBy[sid]) that check-before-read consults under #838's per-actor gating.
+                // Without it, the legacy boolean is set but the per-actor map stays empty, and the gate
+                // blocks every Read forever within the turn (issue #879).
                 matcher: 'mcp__moflo__memory_',
-                hooks: [{ type: 'command', command: gateCmd('record-memory-searched'), timeout: 3000 }],
+                hooks: [{ type: 'command', command: gateHookCmd('record-memory-searched'), timeout: 3000 }],
             },
             {
                 matcher: '^TaskUpdate$',
@@ -284,7 +289,12 @@ function generateHooksConfig(config) {
             },
         ];
     }
-    // UserPromptSubmit — gate reminders + intelligent task routing
+    // UserPromptSubmit — gate reminders + intelligent task routing.
+    // The prompt-reminder hook is REQUIRED — it resets memorySearched / memorySearchedBy
+    // and reclassifies memoryRequired from the new prompt. Without it, gate state leaks
+    // across prompts: a previous turn's "satisfied" state survives, OR a previous turn's
+    // "armed" state never clears. Two separate hook entries (not chained) so an exception
+    // in prompt-hook.mjs doesn't skip the reset.
     if (config.userPromptSubmit) {
         hooks.UserPromptSubmit = [
             {
@@ -292,6 +302,11 @@ function generateHooksConfig(config) {
                     { type: 'command', command: promptHookCmd(), timeout: 3000 },
                 ],
             },
+            {
+                hooks: [
+                    { type: 'command', command: gateHookCmd('prompt-reminder'), timeout: 3000 },
+                ],
+            },
         ];
     }
     // SubagentStart — inject directive for subagents to read guidance protocol

package/dist/src/cli/services/daemon-readiness.js

@@ -12,6 +12,7 @@ import { spawn } from 'child_process';
 import { getDaemonLockHolder } from './daemon-lock.js';
 import { isDaemonInstalled, installDaemonService } from './daemon-service.js';
 import { locateMofloCliBin } from './moflo-require.js';
+import { registerBackgroundPid } from './process-registry.js';
 /**
  * Ensure the daemon is ready for scheduled spell execution.
  *
@@ -115,6 +116,17 @@ async function defaultStartDaemon(projectRoot) {
                 env: daemonEnv,
             });
         child.unref();
+        // Register the spawned daemon PID with the shared ProcessManager (parity
+        // with src/cli/index.ts maybeAutoStartDaemon). Without this, doctor's
+        // zombie scan flags this detached process as orphaned because its parent
+        // (this CLI invocation) exits as soon as ensureDaemonForScheduling
+        // resolves.
+        if (child.pid) {
+            try {
+                registerBackgroundPid(projectRoot, child.pid, 'daemon', spawnArgs.slice(1).join(' '));
+            }
+            catch { /* registration is non-essential */ }
+        }
         // Poll for daemon lock acquisition (up to 2s, checking every 200ms)
         for (let i = 0; i < 10; i++) {
             await new Promise(r => setTimeout(r, 200));

package/dist/src/cli/services/hook-block-hash.js

@@ -0,0 +1,320 @@
+/**
+ * Settings.json hook-block drift detection (#881).
+ *
+ * Hashes the consumer's `.claude/settings.json` `hooks` block and the
+ * reference hook block that `generateHooksConfig()` would produce for the
+ * current moflo version.  When the hashes differ, the session-start launcher
+ * surfaces the diff (or, in `regenerate` mode, adds purely-additive missing
+ * hooks).  This is the broader complement to the per-bug `repairHookWiring`
+ * and `rewriteIncorrectHookWiring` rules — it catches drift in any direction,
+ * including future hook events we haven't shipped yet.
+ *
+ * IMPORTANT: This module must remain self-contained with ZERO imports from
+ * other moflo modules (mirrors the constraint on `services/hook-wiring.ts`).
+ * It is dynamically imported at runtime by `bin/session-start-launcher.mjs`
+ * in consumer projects, where transitive dependencies may not resolve.
+ *
+ * The reference hook block is duplicated from `init/settings-generator.ts`
+ * on purpose — the launcher cannot pull in `init/types.js` at runtime, and a
+ * unit test (`hook-block-hash.test.ts`) asserts the two stay in sync.
+ */
+import { createHash } from 'crypto';
+export const DRIFT_MODES = ['warn', 'regenerate', 'off'];
+// ────────────────────────────────────────────────────────────────────────────
+// Reference hook block — kept in sync with init/settings-generator.ts
+// ────────────────────────────────────────────────────────────────────────────
+const HELPERS_PREFIX = '$CLAUDE_PROJECT_DIR/.claude/helpers';
+const SCRIPTS_PREFIX = '$CLAUDE_PROJECT_DIR/.claude/scripts';
+/** Build a `node "<helper> <subcommand>"` hook entry. */
+const helperHook = (helper, sub, timeout) => ({
+    type: 'command',
+    command: `node "${HELPERS_PREFIX}/${helper}"${sub ? ` ${sub}` : ''}`,
+    timeout,
+});
+/** Build a `node "<scripts/file>"` hook entry (no subcommand). */
+const scriptHook = (file, timeout) => ({
+    type: 'command',
+    command: `node "${SCRIPTS_PREFIX}/${file}"`,
+    timeout,
+});
+const gateHook = (sub, timeout) => helperHook('gate-hook.mjs', sub, timeout);
+const gateCjs = (sub, timeout) => helperHook('gate.cjs', sub, timeout);
+const handler = (sub, timeout) => helperHook('hook-handler.cjs', sub, timeout);
+const autoMemory = (sub, timeout) => helperHook('auto-memory-hook.mjs', sub, timeout);
+/**
+ * Build the reference hook block — the canonical block `generateHooksConfig()`
+ * produces with all hook flags enabled (the default for `flo init`).
+ *
+ * If you change `generateHooksConfig()` in `init/settings-generator.ts`, also
+ * change this function — and the unit test `getReferenceHookBlock matches
+ * generateHooksConfig` will fail until the two agree.
+ */
+export function getReferenceHookBlock() {
+    return {
+        PreToolUse: [
+            { matcher: '^(Write|Edit|MultiEdit)$', hooks: [handler('post-edit', 5000)] },
+            { matcher: '^(Glob|Grep)$', hooks: [gateHook('check-before-scan', 3000)] },
+            { matcher: '^Read$', hooks: [gateHook('check-before-read', 3000)] },
+            {
+                matcher: '^Bash$',
+                hooks: [gateHook('check-dangerous-command', 2000), gateHook('check-before-pr', 2000)],
+            },
+        ],
+        PostToolUse: [
+            {
+                matcher: '^(Write|Edit|MultiEdit)$',
+                hooks: [handler('post-edit', 5000), gateHook('reset-edit-gates', 2000)],
+            },
+            { matcher: '^Agent$', hooks: [handler('post-task', 5000)] },
+            { matcher: '^TaskCreate$', hooks: [gateCjs('record-task-created', 2000)] },
+            {
+                matcher: '^Bash$',
+                hooks: [gateHook('check-bash-memory', 2000), gateHook('record-test-run', 2000)],
+            },
+            { matcher: '^Skill$', hooks: [gateHook('record-skill-run', 2000)] },
+            { matcher: 'mcp__moflo__memory_', hooks: [gateHook('record-memory-searched', 3000)] },
+            { matcher: '^TaskUpdate$', hooks: [gateCjs('check-task-transition', 2000)] },
+            { matcher: '^mcp__moflo__memory_store$', hooks: [gateCjs('record-learnings-stored', 2000)] },
+        ],
+        UserPromptSubmit: [
+            { hooks: [helperHook('prompt-hook.mjs', '', 3000)] },
+            { hooks: [gateHook('prompt-reminder', 3000)] },
+        ],
+        SubagentStart: [
+            { hooks: [helperHook('subagent-start.cjs', '', 2000)] },
+        ],
+        SessionStart: [
+            {
+                hooks: [scriptHook('session-start-launcher.mjs', 3000), autoMemory('import', 8000)],
+            },
+        ],
+        Stop: [
+            { hooks: [handler('session-end', 5000), autoMemory('sync', 10000)] },
+        ],
+        PreCompact: [
+            { hooks: [gateCjs('compact-guidance', 3000)] },
+        ],
+        Notification: [
+            { hooks: [handler('notification', 3000)] },
+        ],
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Normalisation + hashing
+// ────────────────────────────────────────────────────────────────────────────
+function normaliseHookEntry(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.command !== 'string')
+        return null;
+    return {
+        type: typeof r.type === 'string' ? r.type : 'command',
+        command: r.command.replace(/\s+/g, ' ').trim(),
+        timeout: typeof r.timeout === 'number' && isFinite(r.timeout) ? r.timeout : 0,
+    };
+}
+function normaliseHookBlock(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const hooksIn = Array.isArray(r.hooks) ? r.hooks : [];
+    const hooks = hooksIn.map(normaliseHookEntry).filter((h) => h !== null);
+    if (hooks.length === 0)
+        return null;
+    hooks.sort((a, b) => a.command.localeCompare(b.command));
+    const out = { hooks };
+    if (typeof r.matcher === 'string' && r.matcher.length > 0)
+        out.matcher = r.matcher;
+    return out;
+}
+/**
+ * Produce a stable, sorted view of a hook tree suitable for hashing or diffing.
+ * Drops unknown keys, coerces missing fields to defaults, and sorts events,
+ * matchers, and commands so semantically-equal trees compare equal.
+ */
+export function normaliseHooks(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const events = raw;
+    const out = {};
+    const eventNames = Object.keys(events).sort();
+    for (const event of eventNames) {
+        const arr = events[event];
+        if (!Array.isArray(arr))
+            continue;
+        const blocks = arr
+            .map(normaliseHookBlock)
+            .filter((b) => b !== null);
+        if (blocks.length === 0)
+            continue;
+        blocks.sort((a, b) => {
+            const am = a.matcher ?? '';
+            const bm = b.matcher ?? '';
+            if (am !== bm)
+                return am.localeCompare(bm);
+            return (a.hooks[0]?.command ?? '').localeCompare(b.hooks[0]?.command ?? '');
+        });
+        out[event] = blocks;
+    }
+    return out;
+}
+function hashNormalised(tree) {
+    return createHash('sha256').update(JSON.stringify(tree)).digest('hex').slice(0, 16);
+}
+/**
+ * Hash a hook tree.  Stable across runs (deterministic normalisation), and
+ * insensitive to key order, whitespace inside commands, or matcher block
+ * grouping.  Returns a 16-char hex prefix of sha256 — long enough to make
+ * collisions a non-concern for the small space of valid hook trees while
+ * staying readable in launcher output.
+ */
+export function computeHookBlockHash(raw) {
+    return hashNormalised(normaliseHooks(raw));
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Diff
+// ────────────────────────────────────────────────────────────────────────────
+function entryKey(event, matcher, command) {
+    return `${event} ${matcher} ${command}`;
+}
+function flatten(tree) {
+    const out = new Map();
+    for (const event of Object.keys(tree)) {
+        for (const block of tree[event]) {
+            const matcher = block.matcher ?? '';
+            for (const hook of block.hooks) {
+                const entry = { event, matcher, command: hook.command };
+                out.set(entryKey(event, matcher, hook.command), entry);
+            }
+        }
+    }
+    return out;
+}
+let cachedReference = null;
+function getCachedReference() {
+    if (!cachedReference) {
+        const tree = getReferenceHookBlock();
+        const normalised = normaliseHooks(tree);
+        cachedReference = { tree, normalised, hash: hashNormalised(normalised), flat: flatten(normalised) };
+    }
+    return cachedReference;
+}
+/**
+ * Compare a consumer hook block against the reference and report what's
+ * missing / extra.  Pass an explicit `referenceHooks` to test against a
+ * frozen reference (used by tests); omit it to use the current moflo
+ * reference from `getReferenceHookBlock()` (memoised — built once per process).
+ */
+export function computeHookBlockDrift(consumerHooks, referenceHooks) {
+    const consumerNormalised = normaliseHooks(consumerHooks);
+    const consumerHash = hashNormalised(consumerNormalised);
+    const consumerFlat = flatten(consumerNormalised);
+    let referenceHash;
+    let referenceFlat;
+    if (referenceHooks === undefined) {
+        const ref = getCachedReference();
+        referenceHash = ref.hash;
+        referenceFlat = ref.flat;
+    }
+    else {
+        const refNormalised = normaliseHooks(referenceHooks);
+        referenceHash = hashNormalised(refNormalised);
+        referenceFlat = flatten(refNormalised);
+    }
+    const missing = [];
+    for (const [k, v] of referenceFlat) {
+        if (!consumerFlat.has(k))
+            missing.push(v);
+    }
+    const extra = [];
+    for (const [k, v] of consumerFlat) {
+        if (!referenceFlat.has(k))
+            extra.push(v);
+    }
+    return {
+        consumerHash,
+        referenceHash,
+        drifted: consumerHash !== referenceHash,
+        missing,
+        extra,
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Settings.json helpers — shared between launcher + doctor
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * True when the user has set `claudeFlow.hooks.locked: true` in their
+ * settings.json — a sentinel that suppresses drift surfacing entirely.
+ */
+export function isHookBlockLocked(settings) {
+    const root = settings;
+    const cf = root?.claudeFlow;
+    const hooks = cf?.hooks;
+    return hooks?.locked === true;
+}
+/**
+ * Additively repair drift: for every entry in `report.missing`, locate the
+ * corresponding hook in the reference block and graft it into the consumer's
+ * settings.  Only safe when `report.extra.length === 0` — otherwise the
+ * caller should fall back to `warn` mode to avoid clobbering customisations.
+ *
+ * Mutates `settings` in place; caller is responsible for writing the file.
+ */
+export function applyAdditiveRegeneration(settings, report) {
+    if (report.missing.length === 0)
+        return { settings, added: 0 };
+    const ref = getCachedReference().tree;
+    const hooks = (settings.hooks ?? {});
+    let added = 0;
+    for (const miss of report.missing) {
+        const arr = Array.isArray(hooks[miss.event]) ? hooks[miss.event] : [];
+        let block = arr.find(b => (b?.matcher ?? '') === miss.matcher);
+        if (!block) {
+            block = { hooks: [] };
+            if (miss.matcher)
+                block.matcher = miss.matcher;
+            arr.push(block);
+        }
+        if (!Array.isArray(block.hooks))
+            block.hooks = [];
+        const refArr = ref[miss.event] ?? [];
+        const refBlock = refArr.find(b => (b?.matcher ?? '') === miss.matcher);
+        const refHook = refBlock?.hooks.find(h => h.command === miss.command);
+        if (refHook && !block.hooks.some(h => h?.command === miss.command)) {
+            block.hooks.push(refHook);
+            added++;
+        }
+        hooks[miss.event] = arr;
+    }
+    if (added > 0)
+        settings.hooks = hooks;
+    return { settings, added };
+}
+/**
+ * Format a drift report for human-readable output (multi-line, no colour).
+ * Used by `flo doctor` and the session-start launcher's stdout summary.
+ */
+export function formatDriftReport(report) {
+    if (!report.drifted) {
+        return `hook block matches reference (${report.consumerHash})`;
+    }
+    const lines = [];
+    lines.push(`hook block drift detected (consumer ${report.consumerHash} vs reference ${report.referenceHash})`);
+    if (report.missing.length > 0) {
+        lines.push(`  ${report.missing.length} missing:`);
+        for (const m of report.missing) {
+            const m2 = m.matcher ? ` ${m.matcher}` : '';
+            lines.push(`    - ${m.event}${m2}: ${m.command}`);
+        }
+    }
+    if (report.extra.length > 0) {
+        lines.push(`  ${report.extra.length} extra (likely customisations):`);
+        for (const e of report.extra) {
+            const m2 = e.matcher ? ` ${e.matcher}` : '';
+            lines.push(`    + ${e.event}${m2}: ${e.command}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=hook-block-hash.js.map