@cleocode/core 2026.4.31 → 2026.4.35

package/src/hooks/handlers/watchdog-hooks.ts

@@ -0,0 +1,187 @@
+/**
+ * Watchdog Scheduler Hook Handlers
+ *
+ * Starts a periodic health-check timer when a session begins and stops it when
+ * the session ends. One watchdog per project root, enforced by a module-level
+ * Map keyed on the resolved project root.
+ *
+ * Each 60-second tick:
+ * 1. Detects agents with a stale heartbeat (> STALE_THRESHOLD_MS)
+ * 2. Records each crash as a learning event in brain.db
+ * 3. Attempts recovery (status reset to 'starting') for all crashed agents
+ * 4. Fires the `onPatrol` hook for observability
+ *
+ * Best-effort contract: the watchdog NEVER crashes or throws. Any tick failure
+ * is swallowed so the timer continues. Any error in the start/stop handlers is
+ * also swallowed so it never blocks session operations.
+ *
+ * Gated behind `brain.autoCapture` config — the watchdog does NOT start unless
+ * auto-capture is enabled.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T549
+ * @epic T5149
+ */
+
+import { hooks } from '../registry.js';
+import type { OnPatrolPayload, SessionEndPayload, SessionStartPayload } from '../types.js';
+import { isAutoCaptureEnabled, isMissingBrainSchemaError } from './handler-helpers.js';
+
+// ---------------------------------------------------------------------------
+// Module-level watchdog state
+// ---------------------------------------------------------------------------
+
+/** One active timer per project root (resolved path). */
+const activeWatchdogs = new Map<string, ReturnType<typeof setInterval>>();
+
+/** Interval between watchdog ticks in milliseconds. */
+const WATCHDOG_INTERVAL_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// Watchdog tick
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute one watchdog patrol tick.
+ *
+ * Steps:
+ * 1. detectCrashedAgents — find and mark stale agents as 'crashed'
+ * 2. processAgentLifecycleEvent — write failure events to brain.db for each
+ * 3. recoverCrashedAgents — reset crashed agents to 'starting'
+ * 4. hooks.dispatch('onPatrol') — emit observability event
+ *
+ * Any thrown error is caught and logged as a warning; the timer continues.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+async function runWatchdogTick(projectRoot: string): Promise<void> {
+  try {
+    const { detectCrashedAgents, STALE_THRESHOLD_MS } = await import(
+      '../../agents/health-monitor.js'
+    );
+    const { recoverCrashedAgents } = await import('../../agents/retry.js');
+    const { processAgentLifecycleEvent } = await import('../../agents/execution-learning.js');
+
+    // Step 1: Detect and mark crashed agents
+    const crashed = await detectCrashedAgents(STALE_THRESHOLD_MS, projectRoot);
+
+    // Step 2: Record each crash as a brain learning event
+    for (const agent of crashed) {
+      try {
+        await processAgentLifecycleEvent(
+          {
+            agentId: agent.id,
+            agentType:
+              (agent.agentType as import('../../agents/agent-schema.js').AgentType) ?? 'custom',
+            taskId: agent.taskId ?? 'unknown',
+            taskType: 'unknown',
+            outcome: 'failure',
+            errorMessage: 'Heartbeat timeout — agent presumed crashed',
+            errorType: 'retriable',
+            sessionId: agent.sessionId ?? undefined,
+          },
+          projectRoot,
+        );
+      } catch (err) {
+        if (!isMissingBrainSchemaError(err)) {
+          console.warn('[watchdog] Failed to record agent crash event:', err);
+        }
+      }
+    }
+
+    // Step 3: Attempt recovery for all crashed agents
+    if (crashed.length > 0) {
+      await recoverCrashedAgents(STALE_THRESHOLD_MS, projectRoot);
+    }
+
+    // Step 4: Fire onPatrol for observability
+    const patrolPayload: OnPatrolPayload = {
+      timestamp: new Date().toISOString(),
+      watcherId: 'health-watchdog',
+      patrolType: 'health',
+      scope: `crashed=${crashed.length}`,
+    };
+    await hooks.dispatch('onPatrol', projectRoot, patrolPayload);
+  } catch (err) {
+    // Best-effort — never crash the watchdog timer
+    console.warn('[watchdog] Tick failed:', err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle SessionStart — start the watchdog timer for this project root.
+ *
+ * Idempotent: if a watchdog is already running for this root (e.g. a second
+ * session in the same process), the existing timer is reused.
+ *
+ * Gated behind `brain.autoCapture` — watchdog does not start unless auto-capture
+ * is enabled. This aligns with all other brain-capture hooks.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param _payload - SessionStart payload (unused).
+ */
+export async function handleWatchdogStart(
+  projectRoot: string,
+  _payload: SessionStartPayload,
+): Promise<void> {
+  try {
+    if (!(await isAutoCaptureEnabled(projectRoot))) return;
+
+    // Idempotency guard — one watchdog per project root
+    if (activeWatchdogs.has(projectRoot)) return;
+
+    const timer = setInterval(() => {
+      void runWatchdogTick(projectRoot);
+    }, WATCHDOG_INTERVAL_MS);
+
+    activeWatchdogs.set(projectRoot, timer);
+  } catch {
+    // Never block session start on watchdog errors
+  }
+}
+
+/**
+ * Handle SessionEnd — stop the watchdog timer for this project root.
+ *
+ * Safe to call when no watchdog is running (no-op).
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param _payload - SessionEnd payload (unused).
+ */
+export async function handleWatchdogStop(
+  projectRoot: string,
+  _payload: SessionEndPayload,
+): Promise<void> {
+  try {
+    const timer = activeWatchdogs.get(projectRoot);
+    if (timer) {
+      clearInterval(timer);
+      activeWatchdogs.delete(projectRoot);
+    }
+  } catch {
+    // Never block session end on watchdog errors
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+
+hooks.register({
+  id: 'watchdog-session-start',
+  event: 'SessionStart',
+  handler: handleWatchdogStart,
+  priority: 50,
+});
+
+hooks.register({
+  id: 'watchdog-session-end',
+  event: 'SessionEnd',
+  handler: handleWatchdogStop,
+  priority: 50,
+});

package/src/injection.ts

@@ -16,7 +16,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { getAgentsHome, getCleoHome, getCleoTemplatesTildePath } from './paths.js';
@@ -68,6 +68,32 @@ async function removeStaleAgentInjection(projectRoot: string): Promise<boolean>
   return true;
 }
 
+/**
+ * Strip hardcoded `<!-- gitnexus:start -->...<!-- gitnexus:end -->` blocks
+ * from AGENTS.md. These blocks are replaced by the `@.cleo/nexus-bridge.md`
+ * reference which contains auto-generated code intelligence content (T552).
+ *
+ * Also strips any other known vendor marker blocks using the same pattern
+ * (e.g. `<!-- gitnexus:start -->...<!-- gitnexus:end -->`).
+ *
+ * @param filePath - Absolute path to the file to strip
+ * @returns True if the file was modified, false otherwise
+ */
+export async function stripGitNexusBlocks(filePath: string): Promise<boolean> {
+  if (!existsSync(filePath)) return false;
+  const content = await readFile(filePath, 'utf8');
+  // Strip <!-- gitnexus:start --> ... <!-- gitnexus:end --> blocks (case-insensitive markers)
+  const stripped = content.replace(
+    /\n?<!--\s*gitnexus:start\s*-->[\s\S]*?<!--\s*gitnexus:end\s*-->\n?/gi,
+    '',
+  );
+  if (stripped !== content) {
+    await writeFile(filePath, stripped, 'utf8');
+    return true;
+  }
+  return false;
+}
+
 // ── Ensure injection ─────────────────────────────────────────────────
 
 /**
@@ -78,7 +104,7 @@ async function removeStaleAgentInjection(projectRoot: string): Promise<boolean>
  *
  * Target architecture:
  *   CLAUDE.md/GEMINI.md -> @AGENTS.md (via injectAll)
- *   AGENTS.md -> @~/.agents/AGENTS.md + @.cleo/project-context.json + @.cleo/memory-bridge.md
+ *   AGENTS.md -> @~/.agents/AGENTS.md + @.cleo/project-context.json + @.cleo/memory-bridge.md + @.cleo/nexus-bridge.md
  *
  * @task T4682
  */
@@ -114,6 +140,13 @@ export async function ensureInjection(projectRoot: string): Promise<ScaffoldResu
       actions.push('removed deprecated AGENT-INJECTION.md');
     }
 
+    // Step 0b: Strip hardcoded gitnexus blocks from AGENTS.md (T552)
+    // These are replaced by the @.cleo/nexus-bridge.md reference.
+    const removedGitNexus = await stripGitNexusBlocks(join(projectRoot, 'AGENTS.md'));
+    if (removedGitNexus) {
+      actions.push('removed hardcoded gitnexus block from AGENTS.md');
+    }
+
     // Step 1: Inject @AGENTS.md into all provider instruction files
     const injectionContent = buildInjectionContent({ references: ['@AGENTS.md'] });
     const results = await injectAll(providers, projectRoot, 'project', injectionContent);
@@ -140,6 +173,12 @@ export async function ensureInjection(projectRoot: string): Promise<ScaffoldResu
     agentsMdLines.push('@.cleo/memory-bridge.md');
   }
 
+  // Nexus bridge: auto-generated code intelligence summary (T552)
+  const nexusBridgePath = join(projectRoot, '.cleo', 'nexus-bridge.md');
+  if (existsSync(nexusBridgePath)) {
+    agentsMdLines.push('@.cleo/nexus-bridge.md');
+  }
+
   // Contributor project warning (ADR-029): inject dev-channel guidance when
   // this project IS the CLEO source repo, so agents use cleo-dev not @latest.
   const contributorBlock = buildContributorInjectionBlock(projectRoot);

package/src/internal.ts

@@ -75,6 +75,19 @@ export type { HookEvent, ProviderHookEvent } from './hooks/provider-hooks.js';
 export { isProviderHookEvent } from './hooks/types.js';
 // Init (additional)
 export { isAutoInitEnabled } from './init.js';
+export type {
+  AdaptiveValidationSuggestion,
+  GateFocusRecommendation,
+  StorePredictionOptions,
+  VerificationConfidenceScore,
+} from './intelligence/adaptive-validation.js';
+// Intelligence — adaptive validation (suggestGateFocus, scoreVerificationConfidence)
+export {
+  predictAndStore,
+  scoreVerificationConfidence,
+  storePrediction,
+  suggestGateFocus,
+} from './intelligence/adaptive-validation.js';
 export {
   analyzeChangeImpact,
   analyzeTaskImpact,
@@ -173,10 +186,13 @@ export { runBrainMaintenance } from './memory/brain-maintenance.js';
 export type { PurgeResult } from './memory/brain-purge.js';
 export { purgeBrainNoise } from './memory/brain-purge.js';
 export type {
+  BudgetedEntry,
+  BudgetedResult,
+  BudgetedRetrievalOptions,
   PopulateEmbeddingsOptions,
   PopulateEmbeddingsResult,
 } from './memory/brain-retrieval.js';
-export { populateEmbeddings } from './memory/brain-retrieval.js';
+export { populateEmbeddings, retrieveWithBudget } from './memory/brain-retrieval.js';
 export { migrateClaudeMem } from './memory/claude-mem-migration.js';
 // Memory — engine-compat
 export {
@@ -437,6 +453,9 @@ export { createBackup, listBackups, restoreFromBackup } from './store/backup.js'
 // Backup portability — bundle packer (T311 / T347)
 export type { PackBundleInput, PackBundleResult } from './store/backup-pack.js';
 export { packBundle } from './store/backup-pack.js';
+export type { BrainDataAccessor } from './store/brain-accessor.js';
+// Brain accessor — for intelligence domain handler construction
+export { getBrainAccessor } from './store/brain-accessor.js';
 export { getBrainDb, getBrainNativeDb } from './store/brain-sqlite.js';
 export type { LegacyCleanupResult, StrayNexusCleanupResult } from './store/cleanup-legacy.js';
 export {
@@ -867,7 +886,11 @@ export type {
   BrainTimelineNeighborRow,
 } from './memory/brain-row-types.js';
 // Memory (additional)
-export { generateContextAwareContent, writeMemoryBridge } from './memory/memory-bridge.js';
+export {
+  generateContextAwareContent,
+  refreshMemoryBridge,
+  writeMemoryBridge,
+} from './memory/memory-bridge.js';
 export type { SessionMemoryContext } from './memory/session-memory.js';
 export {
   buildSummarizationPrompt,
@@ -881,6 +904,12 @@ export {
   discoverRelated as nexusDiscoverRelated,
   searchAcrossProjects as nexusSearchAcrossProjects,
 } from './nexus/discover.js';
+// Nexus — bridge (code intelligence summary for agents)
+export {
+  generateNexusBridgeContent,
+  refreshNexusBridge,
+  writeNexusBridge,
+} from './nexus/nexus-bridge.js';
 // Nexus — readRegistry (exported as nexusReadRegistry to avoid name clash with skills readRegistry)
 export { readRegistry as nexusReadRegistry } from './nexus/registry.js';
 // Nexus — transfer

package/src/memory/brain-consolidator.ts

@@ -0,0 +1,344 @@
+/**
+ * Brain Consolidator — contradiction detection for the CLEO BRAIN memory system.
+ *
+ * Implements heuristic contradiction detection based on keyword polarity flip.
+ * No LLM required — uses negation markers to identify entries that assert
+ * opposing claims about the same subject.
+ *
+ * When a contradiction is detected:
+ *   1. A 'contradicts' edge is created in brain_page_edges (both directions).
+ *   2. The lower-quality entry's qualityScore is reduced by 0.15.
+ *
+ * All operations are BEST-EFFORT — failures never crash the consolidator.
+ *
+ * @task T549 Wave 3-C
+ * @epic T549
+ */
+
+import { getBrainDb, getBrainNativeDb } from '../store/brain-sqlite.js';
+import { typedAll } from '../store/typed-query.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** A detected contradiction between two memory entries. */
+export interface ContradictionResult {
+  /** ID of the first entry in the contradiction pair. */
+  entryAId: string;
+  /** ID of the second entry in the contradiction pair. */
+  entryBId: string;
+  /** Which entry was considered the "contradicted" one (lower quality). */
+  contradictedId: string;
+  /** Table name where the entries live. */
+  table: string;
+  /** Shared keywords that connected the two entries. */
+  sharedKeywords: string[];
+  /** Negation markers found in one of the entries. */
+  negationMarkers: string[];
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Minimum number of shared keywords to consider two entries related. */
+const MIN_SHARED_KEYWORDS = 3;
+
+/**
+ * Negation markers that, when present in one entry but not the other,
+ * indicate a potential contradiction.
+ */
+const NEGATION_MARKERS = [
+  'not',
+  'never',
+  'deprecated',
+  'removed',
+  'replaced',
+  'avoid',
+  'no longer',
+  'do not',
+  "don't",
+  'disabled',
+  'deleted',
+  'dropped',
+  'broken',
+  'invalid',
+  'obsolete',
+  'reverted',
+  'undone',
+  'superseded',
+] as const;
+
+/** Stop words excluded from keyword extraction (matches brain-lifecycle stop words). */
+const STOP_WORDS = new Set([
+  'the',
+  'a',
+  'an',
+  'is',
+  'are',
+  'was',
+  'were',
+  'be',
+  'been',
+  'being',
+  'have',
+  'has',
+  'had',
+  'do',
+  'does',
+  'did',
+  'will',
+  'would',
+  'could',
+  'should',
+  'may',
+  'might',
+  'shall',
+  'can',
+  'to',
+  'of',
+  'in',
+  'for',
+  'on',
+  'with',
+  'at',
+  'by',
+  'from',
+  'as',
+  'into',
+  'through',
+  'and',
+  'but',
+  'or',
+  'nor',
+  'so',
+  'yet',
+  'this',
+  'that',
+  'these',
+  'those',
+  'it',
+  'its',
+  'not',
+  'no',
+]);
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Extract significant keywords from text for overlap comparison.
+ * Filters stop words and tokens shorter than 4 characters.
+ */
+function extractKeywords(text: string): Set<string> {
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s\-_]/g, ' ')
+    .split(/\s+/);
+  const keywords = new Set<string>();
+  for (const w of words) {
+    if (w.length >= 4 && !STOP_WORDS.has(w)) {
+      keywords.add(w);
+    }
+  }
+  return keywords;
+}
+
+/**
+ * Find negation markers present in the text.
+ */
+function findNegationMarkers(text: string): string[] {
+  const lower = text.toLowerCase();
+  return NEGATION_MARKERS.filter((marker) => lower.includes(marker));
+}
+
+/**
+ * Return the intersection of two keyword sets.
+ */
+function keywordIntersection(a: Set<string>, b: Set<string>): string[] {
+  const result: string[] = [];
+  for (const w of a) {
+    if (b.has(w)) result.push(w);
+  }
+  return result;
+}
+
+// ============================================================================
+// Row types for raw SQL queries
+// ============================================================================
+
+interface EntryRow {
+  id: string;
+  text: string;
+  quality_score: number | null;
+}
+
+// ============================================================================
+// Main Export
+// ============================================================================
+
+/**
+ * Detect contradiction pairs across all verified memory entries.
+ *
+ * For each verified entry:
+ *   1. Find entries with >= MIN_SHARED_KEYWORDS shared keywords.
+ *   2. Check for negation markers in one but not the other.
+ *   3. If contradiction detected: create 'contradicts' graph edges.
+ *   4. Lower quality score of the contradicted (lower quality) entry by 0.15.
+ *
+ * Only considers entries where invalid_at IS NULL (currently valid).
+ * Short-circuits after 50 contradiction pairs to limit consolidation cost.
+ *
+ * @param projectRoot - Project root directory for brain.db resolution
+ * @returns List of contradiction pairs found
+ */
+export async function detectContradictions(projectRoot: string): Promise<ContradictionResult[]> {
+  await getBrainDb(projectRoot);
+  const nativeDb = getBrainNativeDb();
+  if (!nativeDb) return [];
+
+  const results: ContradictionResult[] = [];
+  const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+  // Process each table that holds verified entries
+  const tables: Array<{ table: string; textCol: string }> = [
+    { table: 'brain_observations', textCol: 'narrative' },
+    { table: 'brain_learnings', textCol: 'insight' },
+    { table: 'brain_patterns', textCol: 'pattern' },
+    { table: 'brain_decisions', textCol: 'decision' },
+  ];
+
+  for (const { table, textCol } of tables) {
+    if (results.length >= 50) break;
+
+    let entries: EntryRow[] = [];
+    try {
+      // Only examine verified, valid entries for contradiction scanning
+      entries = typedAll<EntryRow>(
+        nativeDb.prepare(`
+          SELECT id, COALESCE(${textCol}, '') AS text, quality_score
+          FROM ${table}
+          WHERE invalid_at IS NULL
+            AND verified = 1
+          LIMIT 200
+        `),
+      );
+    } catch {
+      // Table or column may not exist — best-effort
+      continue;
+    }
+
+    if (entries.length < 2) continue;
+
+    // Extract keywords for all entries up front
+    const keywordMap = new Map<string, Set<string>>();
+    const negationMap = new Map<string, string[]>();
+    for (const entry of entries) {
+      keywordMap.set(entry.id, extractKeywords(entry.text));
+      negationMap.set(entry.id, findNegationMarkers(entry.text));
+    }
+
+    // Compare all pairs — O(n²) but capped at 200 entries (40k ops max)
+    for (let i = 0; i < entries.length; i++) {
+      if (results.length >= 50) break;
+      const entryA = entries[i]!;
+      const keywordsA = keywordMap.get(entryA.id)!;
+      const negationsA = negationMap.get(entryA.id)!;
+
+      for (let j = i + 1; j < entries.length; j++) {
+        if (results.length >= 50) break;
+        const entryB = entries[j]!;
+        const keywordsB = keywordMap.get(entryB.id)!;
+        const negationsB = negationMap.get(entryB.id)!;
+
+        // Step 1: Need sufficient shared keywords to be "about the same thing"
+        const shared = keywordIntersection(keywordsA, keywordsB);
+        if (shared.length < MIN_SHARED_KEYWORDS) continue;
+
+        // Step 2: Check for negation polarity flip — one entry negates the other
+        // A contradiction occurs when one entry has negation markers that the other lacks
+        const negationsOnlyInA = negationsA.filter((m) => !negationsB.includes(m));
+        const negationsOnlyInB = negationsB.filter((m) => !negationsA.includes(m));
+        const negationFlip = negationsOnlyInA.length > 0 || negationsOnlyInB.length > 0;
+
+        if (!negationFlip) continue;
+
+        // Found a contradiction pair
+        const negMarkers = [...negationsOnlyInA, ...negationsOnlyInB];
+
+        // The contradicted entry is the lower-quality one
+        const qualA = entryA.quality_score ?? 0.5;
+        const qualB = entryB.quality_score ?? 0.5;
+        const contradictedId = qualA <= qualB ? entryA.id : entryB.id;
+        const winningId = contradictedId === entryA.id ? entryB.id : entryA.id;
+
+        results.push({
+          entryAId: entryA.id,
+          entryBId: entryB.id,
+          contradictedId,
+          table,
+          sharedKeywords: shared.slice(0, 10),
+          negationMarkers: negMarkers.slice(0, 5),
+        });
+
+        // Step 3: Create 'contradicts' graph edges (best-effort)
+        const nodeA = buildNodeId(table, entryA.id);
+        const nodeB = buildNodeId(table, entryB.id);
+
+        try {
+          nativeDb
+            .prepare(`
+              INSERT OR IGNORE INTO brain_page_edges
+                (from_id, to_id, edge_type, weight, provenance, created_at)
+              VALUES (?, ?, 'contradicts', 0.8, 'consolidation:contradiction', ?)
+            `)
+            .run(nodeA, nodeB, now);
+          nativeDb
+            .prepare(`
+              INSERT OR IGNORE INTO brain_page_edges
+                (from_id, to_id, edge_type, weight, provenance, created_at)
+              VALUES (?, ?, 'contradicts', 0.8, 'consolidation:contradiction', ?)
+            `)
+            .run(nodeB, nodeA, now);
+        } catch {
+          /* graph population is best-effort */
+        }
+
+        // Step 4: Lower quality of the contradicted entry by 0.15
+        try {
+          nativeDb
+            .prepare(`
+              UPDATE ${table}
+              SET quality_score = MAX(0.0, COALESCE(quality_score, 0.5) - 0.15),
+                  updated_at = ?
+              WHERE id = ?
+            `)
+            .run(now, contradictedId);
+          // Also ensure the winning entry's quality is noted
+          void winningId; // used above for clarity
+        } catch {
+          /* best-effort */
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Build the graph node ID for a given table + entry ID combination.
+ * Mirrors the convention used in graph-auto-populate.ts.
+ */
+function buildNodeId(table: string, entryId: string): string {
+  const typeMap: Record<string, string> = {
+    brain_observations: 'observation',
+    brain_learnings: 'learning',
+    brain_patterns: 'pattern',
+    brain_decisions: 'decision',
+  };
+  const type = typeMap[table] ?? 'entry';
+  return `${type}:${entryId}`;
+}