@cleocode/core 2026.4.31 → 2026.4.36

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

@@ -0,0 +1,80 @@
+/**
+ * Intelligence Hook Handlers — Wave 5-D/E of T549
+ *
+ * Best-effort intelligence side-effects wired into task lifecycle events.
+ *
+ * On task start → calculate risk; if riskScore exceeds the HIGH threshold
+ * (≥ 0.8), store a warning observation so future agents see it.
+ *
+ * All handlers are fire-and-forget: failures MUST NOT propagate or block the
+ * operation that triggered them.
+ *
+ * @task T549
+ * @epic T549
+ */
+
+import { hooks } from '../registry.js';
+import type { PreToolUsePayload } from '../types.js';
+
+// Risk thresholds — mirror RISK_THRESHOLDS in intelligence/prediction.ts
+const RISK_HIGH = 0.8;
+
+// ============================================================================
+// Task Start — Risk Detection
+// ============================================================================
+
+/**
+ * Handle task start: calculate risk and store a warning observation if the
+ * riskScore is at or above the HIGH threshold (≥ 0.8).
+ *
+ * Uses deferred imports so this module can be imported in environments where
+ * not all transitive dependencies (brain.db, tasks.db) are present.
+ *
+ * Best-effort: any error is silently swallowed.
+ */
+export async function handleTaskStartIntelligence(
+  projectRoot: string,
+  payload: PreToolUsePayload,
+): Promise<void> {
+  try {
+    // Deferred relative imports — avoids circular dependency issues and keeps
+    // this module loadable in environments where brain.db is not initialised.
+    const { getAccessor } = await import('../../store/data-accessor.js');
+    const { getBrainAccessor } = await import('../../store/brain-accessor.js');
+    const { calculateTaskRisk } = await import('../../intelligence/prediction.js');
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+    const [accessor, brain] = await Promise.all([
+      getAccessor(projectRoot),
+      getBrainAccessor(projectRoot),
+    ]);
+
+    const risk = await calculateTaskRisk(payload.taskId, accessor, brain);
+
+    if (risk.riskScore >= RISK_HIGH) {
+      const level = risk.riskScore >= 0.95 ? 'critical' : 'high';
+      const factorNames = risk.factors.map((f) => f.name).join(', ');
+      await observeBrain(projectRoot, {
+        text: `Risk alert for ${payload.taskId} (score ${risk.riskScore.toFixed(2)}): ${factorNames}. ${risk.recommendation}`,
+        title: `Task risk: ${level} — ${payload.taskId}`,
+        type: 'discovery',
+        sourceType: 'agent',
+      });
+    }
+  } catch {
+    // Best-effort — never block task start
+  }
+}
+
+// ============================================================================
+// Registration
+// ============================================================================
+
+hooks.register({
+  id: 'intelligence-task-start',
+  event: 'PreToolUse',
+  handler: handleTaskStartIntelligence,
+  // Priority 50: runs after brain-tool-start (100) so the task observation is
+  // already persisted before we assess risk.
+  priority: 50,
+});

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

@@ -13,6 +13,10 @@
  * T527: Removed duplicate session observeBrain writes — session data already
  *       lives in the sessions table; writing it again to brain_observations
  *       was pure noise.
+ * T549 Wave 3-E: Fire-and-forget sleep-time consolidation on session end.
+ *       Runs after backup (priority 5) so brain.db snapshot is captured first.
+ * T554: Fire-and-forget LLM reflector on session end. Runs at priority 4
+ *       (after consolidation at priority 5) to synthesize final session knowledge.
  */
 
 import { hooks } from '../registry.js';
@@ -109,6 +113,61 @@ export async function handleSessionEndBackup(
   }
 }
 
+/**
+ * Handle SessionEnd — fire-and-forget sleep-time memory consolidation.
+ *
+ * T549 Wave 3-E: Runs the full consolidation pipeline (dedup, quality recompute,
+ * tier promotion, contradiction detection, soft eviction, graph strengthening,
+ * summary generation) in the background after the session backup has completed.
+ *
+ * Uses setImmediate to yield control so the session end flow completes before
+ * consolidation begins. Consolidation errors are caught and logged to console.warn
+ * — they MUST NOT block session end or throw to callers.
+ *
+ * Priority 5 ensures this runs last (after backup at priority 10).
+ */
+export async function handleSessionEndConsolidation(
+  projectRoot: string,
+  _payload: SessionEndPayload,
+): Promise<void> {
+  // Schedule consolidation to run after the current event loop turn.
+  // This ensures the session end response reaches the caller before
+  // consolidation begins, matching the "sleep-time compute" pattern.
+  setImmediate(async () => {
+    try {
+      const { runConsolidation } = await import('../../memory/brain-lifecycle.js');
+      await runConsolidation(projectRoot);
+    } catch (err) {
+      console.warn('[consolidation] Session-end consolidation failed:', err);
+    }
+  });
+}
+
+/**
+ * Handle SessionEnd — fire-and-forget LLM reflector synthesis.
+ *
+ * T554: Runs the Reflector after the consolidation pass (priority 5) to
+ * synthesize session observations into durable patterns and learnings.
+ *
+ * Uses setImmediate to yield control before the LLM call. Errors are caught
+ * and logged — they MUST NOT block session end or throw to callers.
+ *
+ * Priority 4 ensures this runs after consolidation (priority 5).
+ */
+export async function handleSessionEndReflector(
+  projectRoot: string,
+  payload: SessionEndPayload,
+): Promise<void> {
+  setImmediate(async () => {
+    try {
+      const { runReflector } = await import('../../memory/observer-reflector.js');
+      await runReflector(projectRoot, payload.sessionId);
+    } catch (err) {
+      console.warn('[reflector] Session-end reflector failed:', err);
+    }
+  });
+}
+
 // Register handlers on module load
 hooks.register({
   id: 'brain-session-start',
@@ -133,3 +192,22 @@ hooks.register({
   handler: handleSessionEndBackup,
   priority: 10,
 });
+
+// Priority 5 runs AFTER backup (priority 10) — consolidation is purely
+// additive and should not delay the backup point-in-time snapshot.
+hooks.register({
+  id: 'consolidation-session-end',
+  event: 'SessionEnd',
+  handler: handleSessionEndConsolidation,
+  priority: 5,
+});
+
+// Priority 4 runs AFTER consolidation (priority 5) — reflector synthesizes
+// the final session knowledge using observations that consolidation may have
+// updated (tier promotions, dedup).
+hooks.register({
+  id: 'reflector-session-end',
+  event: 'SessionEnd',
+  handler: handleSessionEndReflector,
+  priority: 4,
+});

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

@@ -5,6 +5,7 @@
  * Auto-registers on module load.
  *
  * T138: Triggers memory bridge refresh after task completion.
+ * T554: Triggers LLM observer after task completion when observation count ≥ threshold.
  */
 
 import { hooks } from '../registry.js';
@@ -37,6 +38,7 @@ export async function handleToolStart(
  * Handle PostToolUse (maps to task.complete in CLEO, canonical: was onToolComplete)
  *
  * T138: Refresh memory bridge after task completion.
+ * T554: Fire-and-forget LLM observer when observation count ≥ threshold.
  */
 export async function handleToolComplete(
   projectRoot: string,
@@ -55,6 +57,18 @@ export async function handleToolComplete(
     if (!isMissingBrainSchemaError(err)) throw err;
   }
 
+  // T554: Fire-and-forget observer — runs after observation is stored so the
+  // new observation is included in the count. setImmediate ensures the task
+  // complete response reaches the caller before the LLM call begins.
+  setImmediate(async () => {
+    try {
+      const { runObserver } = await import('../../memory/observer-reflector.js');
+      await runObserver(projectRoot);
+    } catch {
+      // Observer errors must never surface to the task complete flow
+    }
+  });
+
   // T138: Refresh memory bridge after task completes (best-effort)
   await maybeRefreshMemoryBridge(projectRoot);
 }

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 {
@@ -866,8 +885,20 @@ export type {
   BrainSearchHit,
   BrainTimelineNeighborRow,
 } from './memory/brain-row-types.js';
+// Memory — LLM extraction gate (additional)
+export type {
+  ExtractedMemory,
+  ExtractFromTranscriptOptions,
+  ExtractionReport,
+  ExtractionType,
+} from './memory/llm-extraction.js';
+export { extractFromTranscript as llmExtractFromTranscript } from './memory/llm-extraction.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 +912,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