@monoes/monomindcli 2.0.3 → 2.1.3

package/.claude/helpers/handlers/gates-handler.cjs

@@ -6,7 +6,7 @@
  * @monomind/guidance package it mirrored has been removed.
  *
  * Gates enforced at runtime:
- *   pre-bash  → destructive-ops  (require-confirmation → block)
+ *   pre-bash  → destructive-ops  (hard block; no confirm-and-proceed path exists)
  *   pre-write → secrets          (block)
  */
 
@@ -32,8 +32,13 @@ const SECRET_PATTERNS = [
   /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{8,}['"]/gi,
   /(?:secret|password|passwd|pwd)\s*[:=]\s*['"][^'"]{8,}['"]/gi,
   /(?:token|bearer)\s*[:=]\s*['"][^'"]{10,}['"]/gi,
+  // Unquoted variants — env-style KEY equals value with no surrounding
+  // quotes (the single most common real leak pattern; the quoted patterns
+  // above never match a bare assignment in a shell export or .env file).
+  /(?:api[_-]?key|apikey|token|secret|password|passwd|pwd)\s*[:=]\s*[^\s'"]{8,}/gi,
   /-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----/g,
-  /sk-[a-zA-Z0-9]{20,}/g,
+  /sk-ant-[a-zA-Z0-9_-]{20,}/g,
+  /sk-[a-zA-Z0-9_-]{20,}/g,
   /ghp_[a-zA-Z0-9]{36}/g,
   /npm_[a-zA-Z0-9]{36}/g,
   /AKIA[0-9A-Z]{16}/g,
@@ -55,7 +60,7 @@ function checkDestructive(command) {
       return {
         triggered: true,
         matched: match[0],
-        reason: `Destructive operation detected: "${match[0]}". Confirm this is intentional and document a rollback plan before proceeding.`,
+        reason: `Destructive operation blocked: "${match[0]}". This hook always blocks (Claude Code's PreToolUse protocol has no confirm-and-proceed path) — there is no way to run this exact command after confirming. If it's genuinely intended, use a non-destructive equivalent instead (e.g. move the target aside, or scope the operation more narrowly).`,
       };
     }
   }
@@ -92,11 +97,14 @@ function handlePreBash(hCtx) {
 
   var result = checkDestructive(cmd);
   if (result.triggered) {
-    // Output block decision and set exit code 2 — both required by Claude Code PreToolUse protocol
-    console.log(JSON.stringify({
+    // Set exit code 2 to block, and write the reason to STDERR — per Claude
+    // Code's PreToolUse hook protocol, stdout JSON is only parsed when exit
+    // code is 0; at exit code 2 the caller reads the block reason from
+    // stderr instead, so putting it on stdout here would make it invisible.
+    process.stderr.write(JSON.stringify({
       decision: 'block',
       reason: '[gates] ' + result.reason,
-    }));
+    }) + '\n');
     process.exitCode = 2;
   }
 }
@@ -120,11 +128,12 @@ function handlePreWrite(hCtx) {
 
   var result = checkSecrets(content);
   if (result.triggered) {
-    // Output block decision and set exit code 2 — both required by Claude Code PreToolUse protocol
-    console.log(JSON.stringify({
+    // Set exit code 2 to block, and write the reason to STDERR — see the
+    // matching comment in handlePreBash for why stdout is the wrong stream.
+    process.stderr.write(JSON.stringify({
       decision: 'block',
       reason: '[gates] ' + result.reason,
-    }));
+    }) + '\n');
     process.exitCode = 2;
   }
 }

package/.claude/helpers/handlers/loops-status-handler.cjs

@@ -10,7 +10,7 @@ module.exports = {
     var loopsDir = path.join(CWD, '.monomind', 'loops');
     if (!fs.existsSync(loopsDir)) { console.log('No loops directory.'); return; }
     var files = fs.readdirSync(loopsDir).filter(function(f) {
-      return f.endsWith('.json') && !f.includes('-hil') && !f.endsWith('.stop');
+      return f.endsWith('.json') && !f.includes('-hil') && !f.endsWith('.stop') && !f.startsWith('._');
     }).slice(0, 200); // cap to prevent DoS via many files
     var STALE_MS = 6 * 60 * 60 * 1000;
     var now = Date.now();

package/.claude/helpers/handlers/route-handler.cjs

@@ -299,6 +299,35 @@ module.exports = {
             console.log('[CODEBASE] Graph index ' + mapData.graphStaleness.commitsBehind + ' commits behind HEAD — run monograph build');
           }
         }
+        // Graph gate connectivity nudge — the pre-search/pre-bash gate
+        // (utils/monograph.cjs _graphGateShouldBlock) hard-blocks the first
+        // Grep/Glob/bash-grep-or-find call each session until a real
+        // monograph_query/monograph_suggest call fires. If that block was
+        // never followed by a real graph call, the monomind MCP server is
+        // most likely not connected this session (config present but
+        // unapproved/not started) — surface it once so the user can fix the
+        // actual cause instead of the gate silently degrading to a no-op.
+        var graphGateFile = path.join(CWD, '.monomind', 'graph-gate-state.json');
+        var mcpWarnFile = path.join(CWD, '.monomind', 'mcp-not-connected-warned.json');
+        if (fs.existsSync(graphGateFile) && fs.statSync(graphGateFile).size < 4096) {
+          var gateState = JSON.parse(fs.readFileSync(graphGateFile, 'utf-8'));
+          var gateSessId = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+          if (gateState && gateState.sessionId === gateSessId && gateState.blockedOnce && !gateState.queried) {
+            var alreadyWarnedMcp = false;
+            if (fs.existsSync(mcpWarnFile)) {
+              try {
+                var mcpWarnData = JSON.parse(fs.readFileSync(mcpWarnFile, 'utf-8'));
+                if (mcpWarnData && mcpWarnData.sessionId === gateSessId) alreadyWarnedMcp = true;
+              } catch (e) { /* corrupt — warn again to be safe */ }
+            }
+            if (!alreadyWarnedMcp) {
+              console.log('[MCP] The graph gate blocked a search but no monograph_query/monograph_suggest call followed — the monomind MCP server is likely not connected this session. Run `claude mcp add monomind -- npx monomind@latest mcp start` (then restart), or approve the .mcp.json trust prompt if one is pending.');
+              try {
+                fs.writeFileSync(mcpWarnFile, JSON.stringify({ sessionId: gateSessId, warnedAt: new Date().toISOString() }));
+              } catch (e) { /* non-fatal */ }
+            }
+          }
+        }
         // Deep dive findings (god nodes, high-degree files from background analysis)
         var deepdiveFile = path.join(metricsDir, 'deepdive.json');
         if (fs.existsSync(deepdiveFile) && fs.statSync(deepdiveFile).size < 32768) {
@@ -327,15 +356,15 @@ module.exports = {
             }
           }
         }
-        // Performance metrics (daemon optimize worker)
+        // Performance metrics (optimize worker — a one-shot process, not a daemon)
         var perfFile = path.join(metricsDir, 'performance.json');
         if (fs.existsSync(perfFile) && fs.statSync(perfFile).size < 32768) {
           var perfData = JSON.parse(fs.readFileSync(perfFile, 'utf-8'));
-          if (perfData && perfData.memoryUsage) {
-            var rssBytes = perfData.memoryUsage.rss || 0;
+          if (perfData && perfData.workerProcessMemoryUsage) {
+            var rssBytes = perfData.workerProcessMemoryUsage.rss || 0;
             var rssMB = Math.round(rssBytes / (1024 * 1024));
             if (rssMB > 512) {
-              console.log('[PERF] Daemon RSS ' + rssMB + 'MB (>512MB threshold). Consider restarting daemon or reducing worker concurrency');
+              console.log('[PERF] optimize worker RSS ' + rssMB + 'MB (>512MB threshold) at last run — reflects that one-shot process, not a persistent daemon');
             }
           }
         }

package/.claude/helpers/handlers/session-handler.cjs

@@ -41,34 +41,46 @@ module.exports = {
       if (fs.existsSync(lastRoutePath) && (function() { try { return fs.statSync(lastRoutePath).size <= MAX_ROUTE; } catch(_) { return false; } }())) {
         var lastRoute = JSON.parse(fs.readFileSync(lastRoutePath, 'utf-8'));
 
-        // Derive sessionSuccess from git commits (strongest signal: user committed = success)
+        // Derive sessionSuccess. A commit alone is not proof of success — a
+        // session can commit a partial fix and then hit repeated failures —
+        // so recent intelligence-outcomes are checked FIRST and can veto a
+        // commit-based "true" when they show a majority of failures.
         try {
           var execSync = require('child_process').execSync;
-          var recentCommits = execSync('git log --oneline --since="30 minutes ago" 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
-          if (recentCommits.length > 0) {
-            sessionSuccess = true;
+
+          var outcomesSignal = null; // majority success/failure from intelligence-outcomes, if any
+          var outcomesPath = path.join(CWD, '.monomind', 'data', 'intelligence-outcomes.jsonl');
+          var MAX_OUTCOMES = 512 * 1024;
+          if (fs.existsSync(outcomesPath) && (function() { try { return fs.statSync(outcomesPath).size <= MAX_OUTCOMES; } catch(_) { return false; } }())) {
+            var windowMs = 30 * 60 * 1000;
+            var cutoff = Date.now() - windowMs;
+            var outcomeLines = fs.readFileSync(outcomesPath, 'utf-8').trim().split('\n').filter(Boolean);
+            var recent = outcomeLines.map(function(l) {
+              try { return JSON.parse(l); } catch { return null; }
+            }).filter(function(e) { return e && e.ts && e.ts >= cutoff; });
+            if (recent.length > 0) {
+              var failures = recent.filter(function(e) { return e.success === false; }).length;
+              outcomesSignal = failures / recent.length < 0.5;
+            }
+          }
+
+          if (outcomesSignal === false) {
+            // Recent tool/command outcomes were majority failures — this
+            // overrides a commit, since committing doesn't undo those failures.
+            sessionSuccess = false;
           } else {
-            // No commits — check if files were modified (work in progress, not failure)
-            var gitStatus = execSync('git diff --name-only 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
-            // Modified files = probably still working; no changes at all = exploration or failure
-            if (gitStatus.length === 0) {
-              // Fall back to intelligence-outcomes as a weak signal
-              var outcomesPath = path.join(CWD, '.monomind', 'data', 'intelligence-outcomes.jsonl');
-              var MAX_OUTCOMES = 512 * 1024;
-              if (fs.existsSync(outcomesPath) && (function() { try { return fs.statSync(outcomesPath).size <= MAX_OUTCOMES; } catch(_) { return false; } }())) {
-                var windowMs = 30 * 60 * 1000;
-                var cutoff = Date.now() - windowMs;
-                var outcomeLines = fs.readFileSync(outcomesPath, 'utf-8').trim().split('\n').filter(Boolean);
-                var recent = outcomeLines.map(function(l) {
-                  try { return JSON.parse(l); } catch { return null; }
-                }).filter(function(e) { return e && e.ts && e.ts >= cutoff; });
-                if (recent.length > 0) {
-                  var failures = recent.filter(function(e) { return e.success === false; }).length;
-                  sessionSuccess = failures / recent.length < 0.5;
-                }
+            var recentCommits = execSync('git log --oneline --since="30 minutes ago" 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
+            if (recentCommits.length > 0) {
+              sessionSuccess = true;
+            } else {
+              // No commits — check if files were modified (work in progress, not failure)
+              var gitStatus = execSync('git diff --name-only 2>/dev/null || true', { cwd: CWD, timeout: 3000, encoding: 'utf-8' }).trim();
+              // Modified files = probably still working; no changes at all = exploration or failure
+              if (gitStatus.length === 0 && outcomesSignal !== null) {
+                sessionSuccess = outcomesSignal;
               }
+              // else: modified files exist, or no evidence either way (leave null)
             }
-            // else: modified files exist — work in progress, not evidence either way (leave null)
           }
         } catch (e) { /* non-critical — leave null (no evidence) */ }
 
@@ -89,17 +101,48 @@ module.exports = {
           // Only write the success flag when derived from actual evidence (commits, outcomes)
           if (typeof sessionSuccess === 'boolean') feedbackEntry.intelligenceFeedback = sessionSuccess;
           fs.appendFileSync(feedbackPath, JSON.stringify(feedbackEntry) + '\n', 'utf-8');
-          // Rotate: keep last 1000 lines to prevent unbounded growth
+          // Rotate: keep last 1000 lines to prevent unbounded growth.
           try {
             var MAX_FEEDBACK = 512 * 1024; // 512 KiB
-            if (fs.existsSync(feedbackPath) && fs.statSync(feedbackPath).size > MAX_FEEDBACK) {
-              // File too large — emergency trim without full read
-              throw new Error('skip-rotation');
-            }
-            var raw = fs.readFileSync(feedbackPath, 'utf-8');
-            var lines = raw.split('\n').filter(Boolean);
-            if (lines.length > 1000) {
-              fs.writeFileSync(feedbackPath, lines.slice(-1000).join('\n') + '\n', 'utf-8');
+            var feedbackStat = fs.existsSync(feedbackPath) ? fs.statSync(feedbackPath) : null;
+            if (feedbackStat && feedbackStat.size > MAX_FEEDBACK) {
+              // Emergency tail-trim: the file is too large to comfortably read+split
+              // in full, so seek to a byte offset near the end, read only that tail,
+              // drop the first (possibly partial) line, and keep the rest — instead
+              // of the previous behavior which threw here and skipped trimming
+              // entirely, leaving the file to grow forever and permanently disabling
+              // consumers (router.cjs, route-handler.cjs) that bail out on oversized
+              // files.
+              var TAIL_BYTES = 256 * 1024; // ~256 KiB of tail content
+              var fd = fs.openSync(feedbackPath, 'r');
+              try {
+                var readSize = Math.min(TAIL_BYTES, feedbackStat.size);
+                var startOffset = feedbackStat.size - readSize;
+                var buf = Buffer.alloc(readSize);
+                fs.readSync(fd, buf, 0, readSize, startOffset);
+                var tailRaw = buf.toString('utf-8');
+                var tailLines = tailRaw.split('\n');
+                // Drop the first line if we didn't start at byte 0 — it's likely partial.
+                if (startOffset > 0) tailLines.shift();
+                var validTailLines = tailLines.filter(function(l) {
+                  if (!l) return false;
+                  try { JSON.parse(l); return true; } catch (eParse) { return false; }
+                });
+                var trimmedTail = validTailLines.slice(-1000);
+                var tmpFeedbackPath = feedbackPath + '.' + process.pid + '.tmp';
+                fs.writeFileSync(tmpFeedbackPath, trimmedTail.join('\n') + (trimmedTail.length > 0 ? '\n' : ''), 'utf-8');
+                fs.renameSync(tmpFeedbackPath, feedbackPath);
+              } finally {
+                fs.closeSync(fd);
+              }
+            } else {
+              var raw = fs.readFileSync(feedbackPath, 'utf-8');
+              var lines = raw.split('\n').filter(Boolean);
+              if (lines.length > 1000) {
+                var tmpFeedbackPath2 = feedbackPath + '.' + process.pid + '.tmp';
+                fs.writeFileSync(tmpFeedbackPath2, lines.slice(-1000).join('\n') + '\n', 'utf-8');
+                fs.renameSync(tmpFeedbackPath2, feedbackPath);
+              }
             }
           } catch (e2) { /* rotation is best-effort */ }
         }
@@ -141,19 +184,6 @@ module.exports = {
 
     // Memory Palace tombstone writes removed — redundant with raw session JSONL
 
-    // ── Context Persistence Auto-Archive ─────────────────────────────────
-    // Archive conversation context so it survives compaction and new sessions
-    try {
-      var cpHook = await import('file://' + path.join(__dirname, '..', 'context-persistence-hook.mjs'));
-      if (cpHook && cpHook.archive) {
-        await hCtx.runWithTimeout(function() { return cpHook.archive(); }, 'context-persistence.archive()');
-        console.log('[CONTEXT_PERSIST] Session transcript archived');
-      } else if (cpHook && cpHook.default && cpHook.default.archive) {
-        await hCtx.runWithTimeout(function() { return cpHook.default.archive(); }, 'context-persistence.archive()');
-        console.log('[CONTEXT_PERSIST] Session transcript archived');
-      }
-    } catch (e) { /* non-fatal — context-persistence may not export archive() */ }
-
     // ── Auto-populate: write session episode for every session ─────
     // Even solo sessions (no subagents) produce an episode so the
     // route handler can surface relevant past sessions.

package/.claude/helpers/handlers/session-restore-handler.cjs

@@ -206,18 +206,6 @@ module.exports = {
       }
     } catch (e) { /* non-fatal — hooks workers unavailable */ }
 
-    // Context Persistence Auto-Restore
-    try {
-      var cpHook = await import('file://' + path.join(helpersDir, 'context-persistence-hook.mjs'));
-      var restoreFn = (cpHook && cpHook.restore) || (cpHook && cpHook.default && cpHook.default.restore);
-      if (restoreFn) {
-        var restored = await runWithTimeout(function() { return restoreFn(); }, 'context-persistence.restore()');
-        if (restored && restored.turns > 0) {
-          console.log('[CONTEXT_RESTORED] ' + restored.turns + ' turns from previous session');
-        }
-      }
-    } catch (e) { /* non-fatal */ }
-
     // AgentKnowledgeBase — preload shared knowledge context on session restore.
     try {
       var knowledgeDir = path.join(CWD, '.monomind', 'knowledge');

package/.claude/helpers/handlers/task-handler.cjs

@@ -5,6 +5,8 @@
 
 const path = require('path');
 const fs = require('fs');
+const { purgeStaleRegistrations } = require('../utils/agent-registrations.cjs');
+const { atomicWriteFileSync, withLock } = require('../utils/fs-helpers.cjs');
 
 module.exports = {
   handlePreTask: async function(hCtx) {
@@ -50,36 +52,65 @@ module.exports = {
         intelligence.feedback(taskSuccess);
       } catch (e) { /* non-fatal */ }
     }
-    // Each TeammateIdle/TaskCompleted = one agent done → remove oldest registration (FIFO)
+    // Each TeammateIdle/TaskCompleted = one agent done → remove its registration.
     const regDir = path.join(CWD, '.monomind', 'agents', 'registrations');
     try {
       if (fs.existsSync(regDir)) {
         const files = fs.readdirSync(regDir).filter(f => f.endsWith('.json'));
-        if (files.length > 0) {
-          // Sort by mtime ascending (oldest first) and remove the oldest one
+        // P3-15: post-task (TeammateIdle/TaskCompleted) also fires for the MAIN
+        // session's own tasks — e.g. the team lead completing a self-assigned
+        // TaskList item — which never wrote an agent-start registration in the
+        // first place. Blindly popping the oldest registration on EVERY
+        // post-task event therefore deregistered an unrelated, still-running
+        // agent whenever the lead (not a subagent) finished a task, silently
+        // drifting the count negative-equivalent (undercounting active agents).
+        //
+        // Registrations now carry an `agentType` (agent-start-handler.cjs), and
+        // this hook's payload may carry the same identifying field under one of
+        // several possible names — mirroring the precedence agent-start-handler
+        // already uses to derive it. If this event carries NO such field at
+        // all, there's no evidence it corresponds to a real agent completion
+        // (as opposed to the main session's own task), so we skip touching
+        // registrations entirely rather than guessing via FIFO. When the field
+        // IS present, prefer removing the registration recorded with the SAME
+        // type; fall back to oldest-of-all only if no type match is found
+        // (e.g. a legacy registration written before this fix, with no
+        // agentType stored).
+        const completingType = hookInput.subagent_type || hookInput.agentType || hookInput.agent_type
+          || hookInput.agentSlug || hookInput.agent_slug || '';
+        if (files.length > 0 && completingType) {
           const sorted = files
-            .map(f => ({ f, mtime: (() => { try { return fs.statSync(path.join(regDir, f)).mtimeMs; } catch { return 0; } })() }))
+            .map(f => {
+              let mtime = 0, agentType = null;
+              try { mtime = fs.statSync(path.join(regDir, f)).mtimeMs; } catch { /* ignore */ }
+              try { agentType = JSON.parse(fs.readFileSync(path.join(regDir, f), 'utf-8')).agentType || null; } catch { /* ignore */ }
+              return { f, mtime, agentType };
+            })
             .sort((a, b) => a.mtime - b.mtime);
-          try { fs.unlinkSync(path.join(regDir, sorted[0].f)); } catch { /* ignore */ }
+          const typeMatch = sorted.find(r => r.agentType === completingType);
+          const toRemove = typeMatch || sorted[0];
+          try { fs.unlinkSync(path.join(regDir, toRemove.f)); } catch { /* ignore */ }
         }
-        // Also purge any stragglers older than 30 min
-        const now = Date.now();
-        for (const f of fs.readdirSync(regDir).filter(f => f.endsWith('.json'))) {
-          try { if (now - fs.statSync(path.join(regDir, f)).mtimeMs > 30 * 60 * 1000) fs.unlinkSync(path.join(regDir, f)); } catch { /* ignore */ }
-        }
-        const remaining = fs.readdirSync(regDir).filter(f => f.endsWith('.json')).length;
+        // Also purge any stragglers older than 30 min (shared with agent-start-handler.cjs)
+        const remaining = purgeStaleRegistrations(regDir) || 0;
+        // P2-21: shares a lock with agent-start-handler.cjs's swarm-activity.json
+        // writer (same path + '.lock') so the read-prevLastActive-then-write
+        // cycle can't race with that handler's concurrent write and silently
+        // drop whichever one wrote last — see that file for full rationale.
         const _actPath = path.join(CWD, '.monomind', 'metrics', 'swarm-activity.json');
-        let _prevLastActive = 0;
-        try { var _actSt = fs.statSync(_actPath); if (_actSt.size < 65536) { _prevLastActive = (JSON.parse(fs.readFileSync(_actPath, 'utf-8'))?.swarm?.lastActive) || 0; } } catch { /* ignore */ }
-        fs.writeFileSync(_actPath, JSON.stringify({
-          timestamp: new Date().toISOString(),
-          swarm: {
-            active: remaining > 0,
-            agent_count: remaining,
-            coordination_active: remaining > 0,
-            lastActive: Math.max(remaining, _prevLastActive), // preserve peak across completion
-          },
-        }));
+        withLock(_actPath + '.lock', function() {
+          let _prevLastActive = 0;
+          try { var _actSt = fs.statSync(_actPath); if (_actSt.size < 65536) { _prevLastActive = (JSON.parse(fs.readFileSync(_actPath, 'utf-8'))?.swarm?.lastActive) || 0; } } catch { /* ignore */ }
+          atomicWriteFileSync(_actPath, JSON.stringify({
+            timestamp: new Date().toISOString(),
+            swarm: {
+              active: remaining > 0,
+              agent_count: remaining,
+              coordination_active: remaining > 0,
+              lastActive: Math.max(remaining, _prevLastActive), // preserve peak across completion
+            },
+          }));
+        }, 5000);
       }
     } catch (e) { /* non-fatal */ }
 

package/.claude/helpers/hook-handler.cjs

@@ -55,6 +55,7 @@ const {
   getMonographSuggestions, getMonographNeighbors,
   _recordGraphTelemetry, _injectCompactGraphMap,
   _findAffectedTests, _maybeRebuildMonograph,
+  _graphGateShouldBlock, _graphGateMarkQueried,
 } = monograph;
 
 const {
@@ -136,9 +137,49 @@ async function _ensureHooksModule() {
       _hooksModule = null; // not built — bridge stays a fail-soft no-op
     }
   }
+  if (!_hooksModule) _warnHooksBridgeUnavailable();
   return _hooksModule;
 }
 
+// ── Visible one-time warning when the @monomind/hooks bridge fully fails ───
+// Both load paths above (bare specifier + dev-repo file:// fallback) failed:
+// the 15 background workers (metrics, security scan, DDD tracking, etc.) are
+// unavailable for the rest of this session. This is almost always because
+// @monomind/hooks was never resolvable from npm (it ships with
+// optionalDependencies:"*", which npm silently skips) — NOT a problem with
+// the user's own project setup. Historically this failed completely
+// silently (see docs/AUDIT-BACKLOG.md P1-1), burning debugging time on the
+// wrong target. Warned once per session (file-marker keyed by session id,
+// same pattern as the once-per-day update check below) since every hook
+// event is its own fresh `node` process and would otherwise spam this on
+// every single tool call.
+function _warnHooksBridgeUnavailable() {
+  try {
+    var sessId = String((hookInput && (hookInput.sessionId || hookInput.session_id)) || '');
+    var flagFile = path.join(CWD, '.monomind', 'hooks-bridge-warned.json');
+    var alreadyWarned = false;
+    if (sessId && fs.existsSync(flagFile)) {
+      try {
+        var flagData = JSON.parse(fs.readFileSync(flagFile, 'utf-8'));
+        if (flagData && flagData.sessionId === sessId) alreadyWarned = true;
+      } catch (e) { /* corrupt/unreadable flag file — warn again to be safe */ }
+    }
+    if (alreadyWarned) return;
+    process.stderr.write(
+      '[WARN] @monomind/hooks could not be loaded (bare specifier and dev-repo fallback both failed) — ' +
+      'background workers (metrics, security scan, DDD tracking, etc.) are unavailable this session. ' +
+      'This is not a problem with your project configuration — the package is not resolvable via npm ' +
+      'from this install. See docs/AUDIT-BACKLOG.md P1-1 or https://github.com/monoes/monomind/issues.\n'
+    );
+    if (sessId) {
+      try {
+        fs.mkdirSync(path.join(CWD, '.monomind'), { recursive: true });
+        fs.writeFileSync(flagFile, JSON.stringify({ sessionId: sessId, warnedAt: new Date().toISOString() }), 'utf-8');
+      } catch (e) { /* non-fatal — worst case we warn again next event */ }
+    }
+  } catch (e) { /* never let the warning itself break a hook event */ }
+}
+
 // ── Intelligence timeout protection (fixes #1530, #1531) ───────────────────
 var INTELLIGENCE_TIMEOUT_MS = 1500;
 function runWithTimeout(fn, label) {
@@ -351,11 +392,33 @@ const handlers = {
     h.handle(hCtx);
   },
 
-  'pre-bash': () => {
+  'pre-bash': async () => {
+    // SECURITY GATE FIRST — destructive-ops enforcement must never be
+    // starved by the slower enrichment work below (monograph hint lookups).
+    // Previously this ran LAST, after up to 10 monograph SQLite strategies,
+    // AND was fired without awaiting its promise — meaning the block
+    // decision (process.exitCode) could still be unset when the process
+    // exited under the global 5s safety timer (see main()'s
+    // `process.exit(0)`), i.e. the gate could fail OPEN under time
+    // pressure. Awaiting it first guarantees the block/allow decision is
+    // computed and set before any enrichment work even starts.
+    var gates = require('./handlers/gates-handler.cjs');
+    await gates.handlePreBash(hCtx);
+    if (process.exitCode === 2) return; // blocked — skip enrichment entirely
+
     var cmd = (hCtx.toolInput && (hCtx.toolInput.command || hCtx.toolInput.cmd)) || '';
     var isGrep = /\b(?:grep|rg|ag)\b/.test(cmd);
     var isFind = /\b(?:find|fd)\b/.test(cmd) && !isGrep;
     if (isGrep || isFind) {
+      var sessIdGate = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+      if (_graphGateShouldBlock(sessIdGate)) {
+        process.stderr.write(JSON.stringify({
+          decision: 'block',
+          reason: '[graph-gate] Call mcp__monomind__monograph_query or monograph_suggest before grep/rg/find for code exploration (CLAUDE.md). This blocks once per session — after your first monograph call (or this one warning), Bash grep/find work normally for the rest of the session.',
+        }) + '\n');
+        process.exitCode = 2;
+        return;
+      }
       var graphAssisted = false;
       if (_isGraphFresh()) {
         try {
@@ -596,9 +659,6 @@ const handlers = {
       else if (isGrep) _recordGraphTelemetry('bash_grep_call');
       else _recordGraphTelemetry('bash_find_call');
     }
-    // Enforcement gate: destructive operations
-    var gates = require('./handlers/gates-handler.cjs');
-    gates.handlePreBash(hCtx);
   },
 
   'pre-write': () => {
@@ -609,6 +669,15 @@ const handlers = {
 
   'pre-search': () => {
     var tool = hCtx.toolName || '';
+    var sessIdGate = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+    if (_graphGateShouldBlock(sessIdGate)) {
+      process.stderr.write(JSON.stringify({
+        decision: 'block',
+        reason: '[graph-gate] Call mcp__monomind__monograph_query or monograph_suggest before ' + (tool || 'Grep/Glob') + ' for code exploration (CLAUDE.md). This blocks once per session — after your first monograph call (or this one warning), search tools work normally for the rest of the session.',
+      }) + '\n');
+      process.exitCode = 2;
+      return;
+    }
     var graphResolved = false;
     try {
       var grepPattern = (typeof toolInput === 'object' && toolInput !== null)
@@ -767,6 +836,8 @@ const handlers = {
   'post-graph-tool': () => {
     // Record monograph MCP tool calls as graph wins
     _recordGraphTelemetry('monograph_call');
+    var sessIdGate = String((hCtx.hookInput && (hCtx.hookInput.sessionId || hCtx.hookInput.session_id)) || '');
+    _graphGateMarkQueried(sessIdGate);
   },
 
   'graph-status': () => {