@saulwade/swl-ses 1.0.0

package/hooks/auto-evolucion.js

@@ -0,0 +1,666 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: auto-evolucion.js
+ * Tipo: SubagentStop (async: true — fire-and-forget)
+ *
+ * Registra la terminación de cada subagente SWL en un log JSONL y, cuando
+ * un mismo agente acumula suficientes señales de baja calidad o alta fricción,
+ * emite un nudge por stderr sugiriendo invocar /swl:evolucionar.
+ *
+ * Señales registradas por agente:
+ *   - status:failed          — el agente terminó con error
+ *   - trivial                — ≤5 tool calls (se descarta del análisis)
+ *   - tool_calls             — número de tool calls totales
+ *   - duracion_ms            — tiempo de ejecución
+ *   - tipo_fallo             — clasificación del fallo (AGP Reflect, Zhang 2026 §3.2.2)
+ *                              uno de: bad_output_format, tool_error, timeout,
+ *                              schema_violation, task_incomplete, unknown
+ *
+ * Umbrales (configurables vía env):
+ *   SWL_AUTOEVOL_FALLOS      (default 3)   — fallos en 14 días → nudge
+ *   SWL_AUTOEVOL_RUNS        (default 10)  — corridas en 14 días → sugerir revisión
+ *   SWL_AUTOEVOL_THROTTLE_H  (default 24)  — horas entre nudges del mismo agente
+ *   SWL_DRIFT_THROTTLE_H     (default 24)  — horas entre chequeos globales de drift
+ *   SWL_DRIFT_DISABLED=1                   — desactiva por completo el drift-detector
+ *
+ * El hook nunca bloquea (siempre exit 0). Zero-dependencies.
+ * NO invoca agentes — solo registra y sugiere.
+ *
+ * convergence-detector (REC-D03): invocado en cada SubagentStop cuando hay ≥6
+ * invocaciones de herramienta en las trazas del día para el agente actual.
+ * Emite un nudge tipo 'loop' independiente del gate de fallos/volumen.
+ *
+ * drift-detector (REC-D07): invocado con throttle propio (SWL_DRIFT_THROTTLE_H)
+ * sobre los últimos JSONL de trazas. Opt-out via SWL_DRIFT_DISABLED=1.
+ *
+ * @see hooks/auto-consolidacion.js  (patrón anti-spam con flag)
+ * @see agentes/auto-evolucion-swl.md (agente que se invoca tras el nudge)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+let nudgeTracker;
+try {
+  nudgeTracker = require('./lib/nudge-tracker');
+} catch {
+  nudgeTracker = null;
+}
+
+let reflect;
+try {
+  reflect = require('./lib/reflect-classifier');
+} catch {
+  reflect = null;
+}
+
+let convergenceDetector;
+try {
+  convergenceDetector = require('./lib/convergence-detector');
+} catch {
+  convergenceDetector = null;
+}
+
+let driftDetector;
+try {
+  driftDetector = require('../scripts/lib/drift-detector');
+} catch {
+  driftDetector = null;
+}
+
+let singletonGuard;
+try {
+  singletonGuard = require('./lib/singleton-guard');
+} catch {
+  singletonGuard = null;
+}
+
+// ---------------------------------------------------------------------------
+// Configuración
+// ---------------------------------------------------------------------------
+
+const UMBRAL_FALLOS        = parseInt(process.env.SWL_AUTOEVOL_FALLOS     || '3',  10);
+const UMBRAL_RUNS          = parseInt(process.env.SWL_AUTOEVOL_RUNS       || '10', 10);
+const THROTTLE_HORAS       = parseInt(process.env.SWL_AUTOEVOL_THROTTLE_H || '24', 10);
+const DRIFT_THROTTLE_HORAS = parseInt(process.env.SWL_DRIFT_THROTTLE_H    || '24', 10);
+const VENTANA_DIAS         = 14;
+const MIN_TOOL_CALLS       = 5;   // por debajo se considera trivial
+const MIN_INVOCACIONES_LOOP = 6;  // mínimo para que el ratio de convergencia sea significativo
+
+const DIR_AUTOEVOL  = path.join(process.cwd(), '.planning', 'auto-evolucion');
+const DIR_TRACES    = path.join(process.cwd(), '.planning', 'traces');
+const LOG_PATH      = path.join(DIR_AUTOEVOL, 'agentes.jsonl');
+const NUDGES_PATH   = path.join(DIR_AUTOEVOL, 'nudges.json');
+
+// ---------------------------------------------------------------------------
+// Utilidades de filesystem (zero-deps)
+// ---------------------------------------------------------------------------
+
+function ensureDir(dir) {
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+}
+
+function append(obj) {
+  ensureDir(DIR_AUTOEVOL);
+  try {
+    fs.appendFileSync(LOG_PATH, JSON.stringify(obj) + '\n', 'utf8');
+  } catch { /* ignore */ }
+}
+
+function leerNudges() {
+  try {
+    return JSON.parse(fs.readFileSync(NUDGES_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function escribirNudges(obj) {
+  ensureDir(DIR_AUTOEVOL);
+  try {
+    fs.writeFileSync(NUDGES_PATH, JSON.stringify(obj, null, 2), 'utf8');
+  } catch { /* ignore */ }
+}
+
+/**
+ * Lee las últimas N entradas del JSONL (sin cargar todo si es grande).
+ * Para el tamaño esperado (log de agentes) una lectura simple es suficiente.
+ */
+function leerLog() {
+  try {
+    const raw = fs.readFileSync(LOG_PATH, 'utf8');
+    return raw
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Clasificador de tipo_fallo — vive en hooks/lib/reflect-classifier.js
+// (AGP Reflect, Zhang 2026 §3.2.2)
+// ---------------------------------------------------------------------------
+
+function clasificarTipoFallo(data, response) {
+  if (reflect) return reflect.clasificarTipoFallo(data, response);
+  return null; // fallback silencioso: si falta el modulo, el hook no bloquea
+}
+
+// ---------------------------------------------------------------------------
+// Análisis de payload de SubagentStop
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrae la info relevante del payload que Claude Code pasa al hook.
+ * Campos esperados (best-effort; varían según harness):
+ *   - session_id
+ *   - tool_name (= "Agent")
+ *   - tool_input.subagent_type  (ej. "implementador-swl")
+ *   - tool_response / tool_result
+ *   - duration_ms (si el harness lo provee)
+ */
+function analizarPayload(data) {
+  const toolName = String(data.tool_name || data.tool?.name || '');
+  if (toolName !== 'Agent') return null;
+
+  const subagentType =
+    data.tool_input?.subagent_type ||
+    data.tool?.input?.subagent_type ||
+    data.subagent_type ||
+    'desconocido';
+
+  // Solo trackeamos agentes SWL (los demás no tenemos potestad de evolucionar)
+  if (!/-swl$/.test(subagentType)) return null;
+
+  const response = data.tool_response || data.tool_result || {};
+  const status = response.is_error || response.status === 'failed' ? 'failed' : 'success';
+
+  // Número de tool calls — lo estimamos por longitud de mensajes si está disponible
+  const mensajes = response.messages || response.mensajes || [];
+  const toolCalls = Array.isArray(mensajes)
+    ? mensajes.filter(m => m && (m.type === 'tool_use' || m.role === 'tool')).length
+    : 0;
+
+  const duracionMs =
+    data.duration_ms ||
+    response.duration_ms ||
+    response.uso?.duration_ms ||
+    null;
+
+  const tipoFallo = status === 'failed'
+    ? clasificarTipoFallo(data, response)
+    : null;
+
+  return {
+    ts: new Date().toISOString(),
+    sessionId: String(data.session_id || 'default'),
+    agente: subagentType,
+    status,
+    toolCalls,
+    trivial: toolCalls > 0 && toolCalls < MIN_TOOL_CALLS,
+    duracionMs,
+    tipo_fallo: tipoFallo,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Gates para emitir nudge
+// ---------------------------------------------------------------------------
+
+function filtrarVentana(entradas, dias) {
+  const limite = Date.now() - dias * 24 * 3600 * 1000;
+  return entradas.filter(e => {
+    const t = Date.parse(e.ts);
+    return Number.isFinite(t) && t >= limite;
+  });
+}
+
+function resumenPorAgente(entradasVentana) {
+  const resumen = {};
+  for (const e of entradasVentana) {
+    if (!resumen[e.agente]) {
+      resumen[e.agente] = { runs: 0, fallos: 0, triviales: 0, fallos_por_tipo: {} };
+    }
+    const r = resumen[e.agente];
+    if (e.trivial) r.triviales++;
+    else {
+      r.runs++;
+      if (e.status === 'failed') {
+        r.fallos++;
+        const tipo = e.tipo_fallo || 'unknown';
+        r.fallos_por_tipo[tipo] = (r.fallos_por_tipo[tipo] || 0) + 1;
+      }
+    }
+  }
+  return resumen;
+}
+
+/**
+ * Determina el tipo_fallo dominante y retorna un diagnóstico estructurado
+ * listo para propagar al nudge. Delega al módulo reflect-classifier.
+ */
+function construirDiagnosis(resumenAgente) {
+  if (reflect) return reflect.construirDiagnosis(resumenAgente);
+  return null;
+}
+
+function debeEmitirNudge(agente, resumen, nudges) {
+  const r = resumen[agente];
+  if (!r) return null;
+
+  const ultimoNudge = nudges[agente];
+  if (ultimoNudge) {
+    const horas = (Date.now() - Date.parse(ultimoNudge)) / 3600000;
+    if (horas < THROTTLE_HORAS) return null;
+  }
+
+  if (r.fallos >= UMBRAL_FALLOS) {
+    return {
+      razon: 'fallos',
+      detalle: `${r.fallos} fallos en ${VENTANA_DIAS} días`,
+    };
+  }
+  if (r.runs >= UMBRAL_RUNS) {
+    return {
+      razon: 'volumen',
+      detalle: `${r.runs} corridas no triviales en ${VENTANA_DIAS} días`,
+    };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Convergence detector — gate de loop (REC-D03)
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee las invocaciones de herramienta del agente desde los JSONL de trazas.
+ *
+ * El formato nativo de otlp-exporter es:
+ *   { traceId, spanId, nombre, inicio, fin, duracionMs, estado, atributos }
+ * donde `nombre` es tipo "agent:nombre-swl" o "skill:nombre-skill".
+ *
+ * Retorna array de { tool: string } compatible con calcularScoreConvergencia.
+ * Nunca lanza — retorna [] ante cualquier falla.
+ *
+ * @param {string} agente       - Nombre del agente SWL (sin prefijo, ej: "implementador-swl")
+ * @param {number} [diasAtras]  - Cuántos días de traces revisar (1 = solo hoy, 2 = hoy y ayer)
+ * @returns {Array<{tool: string}>}
+ */
+function leerInvocacionesDelAgente(agente, diasAtras = 1) {
+  const invocaciones = [];
+  try {
+    const ahora = new Date();
+    for (let i = 0; i < diasAtras; i++) {
+      const fecha = new Date(ahora.getTime() - i * 24 * 3600 * 1000)
+        .toISOString()
+        .slice(0, 10);
+      const rutaJsonl = path.join(DIR_TRACES, `${fecha}.jsonl`);
+      if (!fs.existsSync(rutaJsonl)) continue;
+
+      let contenido;
+      try {
+        contenido = fs.readFileSync(rutaJsonl, 'utf8');
+      } catch {
+        continue;
+      }
+
+      const lineas = contenido.split(/\r?\n/).filter(Boolean);
+      for (const linea of lineas) {
+        let evento;
+        try {
+          evento = JSON.parse(linea);
+        } catch {
+          continue;
+        }
+
+        // El campo nombre puede ser "agent:nombre-swl", "skill:nombre", etc.
+        // Filtramos eventos asociados al agente actual.
+        const nombre = String(evento.nombre || '');
+        const esDelAgente =
+          nombre === `agent:${agente}` ||
+          nombre.includes(agente) ||
+          (evento.atributos?.agente === agente) ||
+          (evento.atributos?.agent === agente);
+
+        if (!esDelAgente) continue;
+
+        // Extraemos el nombre del tool/skill del evento como la herramienta invocada.
+        // En el formato OTLP-lite el "tool" es el nombre del span.
+        const tool = nombre || 'unknown';
+        invocaciones.push({ tool });
+      }
+    }
+  } catch {
+    // Fallback silencioso — el hook no debe crashear por traces inexistentes
+  }
+  return invocaciones;
+}
+
+/**
+ * Determina si hay throttle activo para el nudge de loop del agente.
+ *
+ * Usa la clave "<agente>::loop" en el objeto nudges con el mismo
+ * throttle configurado en THROTTLE_HORAS.
+ *
+ * @param {string} agente
+ * @param {object} nudges
+ * @returns {boolean} true si debe omitir el nudge de loop
+ */
+function estaThrottledLoop(agente, nudges) {
+  const clave = `${agente}::loop`;
+  const ultimo = nudges[clave];
+  if (!ultimo) return false;
+  const horas = (Date.now() - Date.parse(ultimo)) / 3600000;
+  return horas < THROTTLE_HORAS;
+}
+
+// ---------------------------------------------------------------------------
+// Drift detector automático (REC-D07)
+// ---------------------------------------------------------------------------
+
+/**
+ * Retorna las rutas de los últimos N archivos JSONL de traces ordenados
+ * por fecha descendente (más reciente primero).
+ *
+ * @param {number} [max=5]
+ * @returns {string[]}
+ */
+function rutasTracesRecientes(max) {
+  const n = max || 5;
+  try {
+    if (!fs.existsSync(DIR_TRACES)) return [];
+    const archivos = fs.readdirSync(DIR_TRACES)
+      .filter(f => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
+      .sort()
+      .reverse()
+      .slice(0, n);
+    return archivos.map(f => path.join(DIR_TRACES, f));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Ejecuta el drift-detector de forma automática con throttle propio.
+ *
+ * Respeta la clave "__drift__::global" en el objeto nudges para evitar
+ * correr en cada invocación de subagente (sería costoso).
+ *
+ * Opt-out completo con SWL_DRIFT_DISABLED=1.
+ *
+ * @param {object} nudges  - Objeto de nudges leído de disco (se muta in-place)
+ */
+function ejecutarDriftAutomatico(nudges) {
+  if (process.env.SWL_DRIFT_DISABLED === '1') return;
+  if (!driftDetector) return;
+
+  // Throttle: no correr si ya se corrió en las últimas DRIFT_THROTTLE_HORAS
+  const claveThrottle = '__drift__::global';
+  const ultimoDrift = nudges[claveThrottle];
+  if (ultimoDrift) {
+    const horas = (Date.now() - Date.parse(ultimoDrift)) / 3600000;
+    if (horas < DRIFT_THROTTLE_HORAS) return;
+  }
+
+  // Actualizar throttle inmediatamente para que invocaciones concurrentes no dupliquen
+  nudges[claveThrottle] = new Date().toISOString();
+
+  try {
+    const rutas = rutasTracesRecientes(5);
+    if (rutas.length === 0) return;
+
+    // Usar la traza más reciente como fuente principal de drift.
+    // detectarDrift acepta una sola rutaJsonl — pasamos el archivo más reciente.
+    const resultado = driftDetector.detectarDrift({
+      rutaJsonl: rutas[0],
+      ventanaDias: 7,
+      baselineSemanasBase: 4,
+      umbralPct: 10,
+    });
+
+    if (!resultado) return;
+    if (resultado.estado_global !== 'warn' && resultado.estado_global !== 'critico') return;
+
+    // Filtrar solo las métricas que driftearon
+    const driftsSig = (resultado.drifts || []).filter(d => d.estado !== 'ok');
+    if (driftsSig.length === 0) return;
+
+    // Emitir nudge por stderr
+    const lineasDrift = driftsSig.map(d =>
+      `    • ${d.metrica}: ${d.driftPct > 0 ? '+' : ''}${d.driftPct}% (${d.estado})`
+    );
+    const mensajeDrift = [
+      '',
+      `[auto-evolución] Drift detectado en trazas de agentes (estado: ${resultado.estado_global}).`,
+      '  Métricas con variación significativa:',
+      ...lineasDrift,
+      '  Considera revisar el ciclo de evolución:',
+      '    /swl:evolucionar',
+      '',
+    ].join('\n');
+    process.stderr.write(mensajeDrift);
+
+    // Registrar en nudge-tracker
+    if (nudgeTracker) {
+      try {
+        // Drift crítico → repair/high; drift warn → repair/medium
+        const esCritico = resultado.estado_global === 'critico';
+        nudgeTracker.emit({
+          kind: 'drift-detectado',
+          target: '__global__',
+          message: mensajeDrift.trim(),
+          source: 'hooks/auto-evolucion.js',
+          mutation_category: 'repair',
+          risk_level: esCritico ? 'high' : 'medium',
+          data: {
+            estado_global: resultado.estado_global,
+            drifts: driftsSig,
+          },
+        });
+      } catch { /* silencioso */ }
+    }
+
+  } catch {
+    // Fallback silencioso — el drift no debe bloquear el hook principal
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+
+// Solo registrar listeners de stdin en modo CLI. Cuando se importa como
+// módulo (tests de integración), los listeners mantendrían el event loop
+// vivo hasta que stdin emita 'end' — evento que nunca llega cuando el
+// runner hereda stdin del proceso padre — y la suite de tests cuelga
+// hasta el timeout. El hook real invocado por Claude Code siempre se
+// ejecuta como require.main, así que el CLI behavior se preserva intacto.
+if (require.main === module) {
+let inputRaw = '';
+process.stdin.on('data', chunk => { inputRaw += chunk; });
+
+process.stdin.on('end', () => {
+  // Singleton guard: si otra instancia del hook está corriendo (poco probable
+  // en SubagentStop pero posible con eventos concurrentes), salir silenciosamente.
+  // Lock stale tras 5 min (el hook normalmente corre en < 1s).
+  if (singletonGuard && !singletonGuard.adquirir('auto-evolucion', { staleMs: 300000 })) {
+    return;
+  }
+
+  try {
+    const data = JSON.parse(inputRaw);
+    const entrada = analizarPayload(data);
+    if (!entrada) { if (singletonGuard) singletonGuard.liberar('auto-evolucion'); return; }
+
+    // 1. Registrar en el log JSONL
+    append(entrada);
+
+    // 2. Si fue trivial, no analizamos nudges
+    if (entrada.trivial) { if (singletonGuard) singletonGuard.liberar('auto-evolucion'); return; }
+
+    // 3. Cargar histórico en ventana y evaluar gates
+    const historico = leerLog();
+    const ventana   = filtrarVentana(historico, VENTANA_DIAS);
+    const resumen   = resumenPorAgente(ventana);
+
+    const nudges  = leerNudges();
+    const decision = debeEmitirNudge(entrada.agente, resumen, nudges);
+
+    // 4. Gate de loop (convergence-detector, REC-D03)
+    let loopInfo = null;
+    if (convergenceDetector) {
+      try {
+        const invocaciones = leerInvocacionesDelAgente(entrada.agente, 1);
+        if (invocaciones.length >= MIN_INVOCACIONES_LOOP) {
+          loopInfo = convergenceDetector.detectarLoop({ invocaciones });
+        }
+      } catch { /* fallback silencioso */ }
+    }
+
+    // Mapeo razón → (mutation_category, risk_level) según Evolver GEP.
+    // repair: corrige regresión observable; optimize: mejora sin bug; innovate: capacidad nueva.
+    const clasificarRazon = (razon) => {
+      if (razon === 'fallos' || razon === 'loop') return { mutation_category: 'repair', risk_level: 'high' };
+      if (razon === 'volumen') return { mutation_category: 'optimize', risk_level: 'medium' };
+      if (razon === 'drift') return { mutation_category: 'repair', risk_level: 'medium' };
+      return { mutation_category: undefined, risk_level: undefined };
+    };
+
+    // 5. Emitir nudge de loop si aplica (gate independiente del de fallos/volumen)
+    if (loopInfo?.estaEnLoop && !estaThrottledLoop(entrada.agente, nudges)) {
+      const mensajeLoop = [
+        '',
+        `[auto-evolución] Posible loop detectado en "${entrada.agente}".`,
+        `  Ratio calls/tools: ${Math.round(loopInfo.ratio * 100) / 100}  (umbral ${loopInfo.umbralUsado})`,
+        `  Invocaciones: ${loopInfo.totalCalls}  Tools únicos: ${loopInfo.uniqueTools}`,
+        `  Considera revisar el diseño del agente:`,
+        `    /swl:evolucionar ${entrada.agente}`,
+        '',
+      ].join('\n');
+
+      process.stderr.write(mensajeLoop);
+
+      // Registrar throttle del loop por separado
+      nudges[`${entrada.agente}::loop`] = new Date().toISOString();
+
+      if (nudgeTracker) {
+        try {
+          const clasif = clasificarRazon('loop');
+          nudgeTracker.emit({
+            kind: 'auto-evolucion',
+            target: entrada.agente,
+            message: mensajeLoop.trim(),
+            source: 'hooks/auto-evolucion.js',
+            mutation_category: clasif.mutation_category,
+            risk_level: clasif.risk_level,
+            data: {
+              razon: 'loop',
+              ratio: loopInfo.ratio,
+              totalCalls: loopInfo.totalCalls,
+              uniqueTools: loopInfo.uniqueTools,
+              umbralUsado: loopInfo.umbralUsado,
+            },
+          });
+        } catch { /* silencioso */ }
+      }
+    }
+
+    // 6. Si no hay decision de nudge principal, pasar al drift y salir
+    if (!decision) {
+      escribirNudges(nudges);
+      ejecutarDriftAutomatico(nudges);
+      escribirNudges(nudges);
+      if (singletonGuard) singletonGuard.liberar('auto-evolucion');
+      return;
+    }
+
+    // 7. Construir diagnosis semántico (AGP Reflect)
+    const diagnosis = construirDiagnosis(resumen[entrada.agente]);
+
+    // 8. Emitir nudge principal (stderr, visible al modelo como contexto)
+    const lineas = [
+      '',
+      `[auto-evolución] Agente "${entrada.agente}" acumuló señales para evolución.`,
+      `  Motivo: ${decision.razon} — ${decision.detalle}.`,
+    ];
+    if (diagnosis) {
+      lineas.push(`  Tipo de fallo dominante: ${diagnosis.tipo_fallo} (${diagnosis.conteo_dominante}/${diagnosis.total_fallos} fallos).`);
+      lineas.push(`  Hipotesis de mejora: ${diagnosis.hint_mejora}.`);
+    }
+    // Incluir info de loop en el nudge principal si también está activo
+    if (loopInfo?.estaEnLoop) {
+      lineas.push(`  Además: loop detectado (ratio ${Math.round(loopInfo.ratio * 100) / 100}, umbral ${loopInfo.umbralUsado}).`);
+    }
+    lineas.push(`  Considera invocar:`);
+    lineas.push(`    /swl:evolucionar ${entrada.agente}`);
+    lineas.push(`  (o el agente auto-evolucion-swl con foco en "${entrada.agente}")`);
+    lineas.push('');
+    const mensaje = lineas.join('\n');
+    process.stderr.write(mensaje);
+
+    // 9. Registrar timestamp del nudge para throttle
+    nudges[entrada.agente] = new Date().toISOString();
+    escribirNudges(nudges);
+
+    // 10. Registrar en nudge-tracker para medir tasa de acción
+    if (nudgeTracker) {
+      try {
+        const clasif = clasificarRazon(decision.razon);
+        nudgeTracker.emit({
+          kind: 'auto-evolucion',
+          target: entrada.agente,
+          message: mensaje.trim(),
+          source: 'hooks/auto-evolucion.js',
+          mutation_category: clasif.mutation_category,
+          risk_level: clasif.risk_level,
+          data: {
+            razon:     decision.razon,
+            detalle:   decision.detalle,
+            diagnosis,
+            loop:      loopInfo?.estaEnLoop ? loopInfo : null,
+          },
+        });
+      } catch { /* silencioso */ }
+    }
+
+    // 11. Drift automático (REC-D07) al final
+    ejecutarDriftAutomatico(nudges);
+    escribirNudges(nudges);
+
+  } catch (err) {
+    // Hook nunca bloquea, pero deja traza diagnóstica para no perder
+    // regresiones silenciosas en el ciclo de auto-evolución.
+    process.stderr.write(`[auto-evolucion] error interno: ${String(err.message || err).slice(0, 120)}\n`);
+  } finally {
+    if (singletonGuard) singletonGuard.liberar('auto-evolucion');
+  }
+});
+}
+
+// ---------------------------------------------------------------------------
+// Exports para tests unitarios
+// (el entrypoint de stdin solo corre cuando se ejecuta directamente)
+// ---------------------------------------------------------------------------
+
+if (require.main !== module) {
+  module.exports = {
+    leerInvocacionesDelAgente,
+    ejecutarDriftAutomatico,
+    estaThrottledLoop,
+    rutasTracesRecientes,
+    // Exponer para tests de integración completos
+    _internals: {
+      analizarPayload,
+      filtrarVentana,
+      resumenPorAgente,
+      debeEmitirNudge,
+      construirDiagnosis,
+    },
+  };
+}