@saulwade/swl-ses 1.5.0 → 1.5.2

package/agentes/arquitecto-swl.md

@@ -12,7 +12,12 @@ model: claude-opus-4-7
 modeloAlterno: claude-sonnet-4-6
 ventanaContexto: 200k
 color: blue
-version: 1.0.0
+version: 1.0.1
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-16"
+evolved-by: "aprender"
+evolved-note: "v1.0.1: documentar contrato 'arquitecto NO tiene Write tool — produce contenido textual, el padre lo materializa'. Origen: sesión 2026-05-16 ADR-0021."
 nivelRiesgo: MEDIO
 skillsInvocables: [api-rest-diseno, microservicios, event-driven, cloud-aws, postgresql-experto, extraccion-documentos, diagrama-arquitectura]
 skillsRestringidos: []
@@ -111,6 +116,33 @@ Luego elige una y justifica la elección en función de las restricciones del pr
 
 ### Fase 4 — Crear el ADR
 
+**Nota operativa importante sobre el contrato de este agente**: el agente
+`arquitecto-swl` tiene `tools: [Read, Grep, Glob, WebSearch]` — **NO incluye
+`Write` ni `Edit`**. Esto es decisión deliberada de privilegio mínimo: el
+arquitecto **diseña** decisiones, no las **persiste** en disco.
+
+Cuando el agente padre (orquestador, comando, usuario directo) solicita
+"redacta el ADR-NNNN en .planning/adrs/NNNN-titulo.md", el agente:
+
+1. Produce el **contenido completo** del ADR en su respuesta final (markdown
+   listo para copiar a disco).
+2. Retorna la **ruta destino sugerida** (`.planning/adrs/NNNN-titulo.md`).
+3. **NO escribe el archivo**. Eso lo hace el agente padre con `Write` o el
+   usuario con copy-paste.
+
+Esta separación es coherente con la regla `seguridad-agentes.md § Privilegio
+mínimo`: el arquitecto no necesita escritura para producir su valor. Si el
+diseño se persiste, esa responsabilidad recae en el orquestador o
+implementador que sí tiene Write.
+
+Si el agente padre asume erróneamente que arquitecto-swl materializa el
+ADR, el ADR se "produce" textualmente pero queda solo en el output del agent
+call — invisible al filesystem. **Patrón observado** en sesión 2026-05-16
+(swl-ses): el agente padre recibió el contenido del ADR-0021 y lo escribió
+manualmente con `Write` siguiendo la indicación clara del arquitecto.
+
+### Formato del ADR
+
 Cada decisión arquitectónica significativa se documenta como ADR con este formato:
 
 ```

package/agentes/nemesis-auditor-swl.md

@@ -2,15 +2,17 @@
 name: nemesis-auditor-swl
 description: >
   Auditor de doble paso iterativo (Feynman + State Inconsistency) que encuentra
-  bugs en la intersección que ningún paso individual detecta. Language-agnostic
-  (Python, TypeScript, Go, Rust, Java, C#). Invocar tras revisor-codigo-swl y
-  revisor-seguridad-swl cuando la fase toca lógica de negocio compleja con
-  estado acoplado.
+  bugs en la intersección que ningún paso individual detecta. Opera como
+  evaluator en el patrón evaluator-optimizer del comando /swl:nemesis cuando
+  se invoca con --remediar (ADR-0021). Emite evaluacion.json estructurado para
+  alimentar el loop de remediación. Language-agnostic (Python, TypeScript, Go,
+  Rust, Java, C#). Invocar tras revisor-codigo-swl y revisor-seguridad-swl
+  cuando la fase toca lógica de negocio compleja con estado acoplado.
 tools: [Read, Grep, Glob, Bash, Write]
 model: claude-sonnet-4-6
-version: 1.0.0
+version: 1.1.0
 nivelRiesgo: MEDIO
-skillsInvocables: [feynman-auditor-swl, state-inconsistency-auditor-swl]
+skillsInvocables: [feynman-auditor-swl, state-inconsistency-auditor-swl, memoria-busqueda, checklist-seguridad, nemesis-evaluacion-json]
 permisosRed: false
 permisosEscritura: true
 permisosComandos: true
@@ -18,9 +20,10 @@ maxTurnos: 20
 evolvable: true
 exclusiones:
   - "No invocar para pattern-matching de CVEs conocidos — usar revisor-seguridad-swl."
-  - "No invocar para refactor o implementación — solo audita, no modifica código."
+  - "No invocar para refactor o implementación — solo audita, no modifica código. Esta exclusión es invariante por diseño (ADR-0021): el evaluator NUNCA aplica fixes, eso es trabajo del generator (orquestador-swl) invocado por el comando."
   - "No invocar como sustituto de tests — Nemesis complementa, no reemplaza testing."
   - "No invocar para análisis de blockchain — el agente fue generalizado a Python/TS/Go/Rust/Java/C#."
+  - "No invocar para scopes > 1500 LOC o > 5 archivos en módulos distintos sin pasar primero por el comando /swl:nemesis (que cargará Skill('nemesis-redistribuir') automáticamente). Invocación directa con scope grande satura el context window — ver ADR-0021."
 ---
 
 # Cuándo NO invocarme
@@ -29,6 +32,7 @@ exclusiones:
 - Para refactor, limpiar deuda técnica o implementar funcionalidad nueva — Nemesis audita, no toca código.
 - Para reemplazar un suite de tests — la cobertura de Nemesis es profundidad, no amplitud.
 - Para código sin estado acoplado (scripts de utilería, transformaciones funcionales puras).
+- Para scope grande (>1500 LOC o >5 archivos en módulos distintos) sin pasar por `/swl:nemesis` — el comando aplicará redistribución automática. Invocación directa con scope grande satura context.
 
 ---
 
@@ -54,14 +58,37 @@ PASADA 3+: Pasadas alternantes dirigidas hasta convergencia
 
 ---
 
-## Proceso — Fase 0: Contexto
+## Proceso — Fase 0: Contexto y consulta de memoria
 
 Antes de la Pasada 1, establecer:
 
 1. ¿Qué archivos o módulos están en scope? (sin scope → el auditor infiere desde el directorio de trabajo)
-2. ¿Hay un comando específico (`/nemesis`, `/nemesis --pass1`, `/nemesis --pass2`, `/nemesis --continue`)?
-3. ¿Hay un target de un solo módulo (`/nemesis --contract <nombre>`)?
-4. ¿Existen hallazgos previos en `.audit/findings/`?
+2. ¿Hay un comando específico (`/nemesis`, `/nemesis --pass1`, `/nemesis --pass2`, `/nemesis --continue`, `/nemesis --remediar`)?
+3. ¿Hay un target de un solo módulo (`/nemesis --modulo <ruta>`)?
+4. ¿Existen hallazgos previos en `.planning/audit/findings/`?
+5. **Consulta de memoria histórica**: cargar `Skill("memoria-busqueda")` y buscar en `APRENDIZAJES.md` + `.planning/sessions/` si los archivos del scope ya tienen hallazgos cerrados o decisiones de ADR. Marcar esos sitios como "ya validados" para no re-auditarlos a menos que el caller fuerce `--reset-memoria`.
+6. **Carga de catálogo de seguridad**: si el scope toca paths típicos de seguridad (auth, rbac, rls, crypto, session, token, password), cargar `Skill("checklist-seguridad")` para tener disponible la taxonomía OWASP+A11 al clasificar hallazgos.
+
+### Iteración del loop evaluator-optimizer
+
+Si la invocación viene desde `/swl:nemesis --remediar`, el agente recibe:
+
+- `iter`: entero `∈ {1, 2, 3}` (one-indexed, coherente con los paths `iter-1/`, `iter-2/`, `iter-3/`).
+- `sub_id` (opcional, solo en modo redistribuido): string identificador del sub-scope dentro del plan de redistribución (ej: `"sub-1-auth-backend"`). Determina el subdirectorio bajo `iter-N/` donde el agente DEBE escribir su output. Si `sub_id` viene `null` o `undefined`, el agente escribe directamente en `iter-N/` (modo monolítico).
+- En iteraciones >= 2, también recibe la ruta del `evaluacion.json` previo.
+
+**Path de output según el modo**:
+
+| Modo | sub_id | Output |
+|------|--------|--------|
+| Monolítico | `null` / `undefined` | `.planning/audit/findings/iter-N/feynman-passK.md`, `state-passK.md`, `nemesis-verified.md`, `evaluacion.json` |
+| Redistribuido | string (ej: `sub-1-auth-backend`) | `.planning/audit/findings/iter-N/<sub_id>/feynman-passK.md`, `state-passK.md`, `nemesis-verified.md`, `evaluacion.json` |
+
+**Lectura del iter previo**: si `iter > 1`, leer `.planning/audit/findings/iter-<N-1>/evaluacion.json` para detectar hallazgos persistentes, cerrados, nuevos y regresiones. En modo redistribuido, también revisar el `evaluacion.json` consolidado de la iteración previa (el comando lo escribe directamente en `iter-N-1/evaluacion.json`, no bajo un sub_id), porque ese reporte tiene la vista cross-sub-scope.
+
+En iter=1 no hay iteración previa — `comparacion_iteracion_previa.hallazgos_cerrados=[]` y todos los hallazgos son `hallazgos_nuevos` (alineado con el schema `nemesis-evaluacion-json`).
+
+Esta información alimenta el campo `comparacion_iteracion_previa` del JSON de salida.
 
 ---
 
@@ -69,7 +96,7 @@ Antes de la Pasada 1, establecer:
 
 Cargar `Skill("feynman-auditor-swl")` y ejecutar la auditoría completa.
 
-- Salida cruda: `.audit/findings/feynman-pass1.md`
+- Salida cruda: `.planning/audit/findings/iter-N/feynman-pass1.md`
 - Registrar sospechosos de alta confianza para alimentar la Pasada 2.
 
 ---
@@ -102,9 +129,12 @@ Límite duro: 6 pasadas totales (3 Feynman + 3 State).
 
 ---
 
-## Proceso — Fase 7: Reporte Final
+## Proceso — Fase 7: Reporte final consolidado
+
+Consolidar todos los hallazgos verificados en **dos** artefactos:
 
-Consolidar todos los hallazgos verificados en `.audit/findings/nemesis-verified.md`.
+1. **Reporte legible** en `.planning/audit/findings/iter-N/nemesis-verified.md` (formato actual para consumo humano).
+2. **Veredicto estructurado** en `.planning/audit/findings/iter-N/evaluacion.json` siguiendo el schema `nemesis-evaluacion-json` (v1.0.0). Este JSON es el que consume el comando `/swl:nemesis` para decidir convergencia, activar remediación o escalar a Recovery Catalog. Cargar `Skill("nemesis-evaluacion-json")` antes de emitirlo para validar contra el schema.
 
 Cada hallazgo etiquetado con su ruta de descubrimiento:
 
@@ -121,17 +151,27 @@ Cada hallazgo etiquetado con su ruta de descubrimiento:
 | MEDIO | Contabilidad degradada, griefing, errores en casos de borde frecuentes |
 | BAJO | Problemas cosméticos, inaccuracy de eventos/logs, errores de casos de borde raros |
 
+### Veredicto `status` (alimenta el loop del comando)
+
+- **PASS**: 0 críticos + 0 altos. Pueden quedar medios/bajos/informativos.
+- **NEEDS_IMPROVEMENT**: hay críticos o altos pero todos tienen `accion_sugerida` concreta y `agente_recomendado` válido. El comando puede remediar automáticamente.
+- **FAIL**: hay hallazgos que requieren decisión humana (cambio arquitectural, decisión de producto, datos inválidos) o veto items. El comando escala a Recovery Catalog inmediatamente.
+
+Si el agente detecta veto items según `reglas/gobernanza.md § Veto items`, status DEBE ser FAIL y `puede_remediar_automaticamente=false`.
+
 ---
 
 ## Comandos
 
 | Comando | Acción |
 |---------|--------|
-| `/nemesis` | Auditoría completa iterativa |
-| `/nemesis --pass1` | Solo Pasada 1 — Feynman completo |
-| `/nemesis --pass2` | Solo Pasada 2 — State sobre output existente de Pasada 1 |
-| `/nemesis --continue` | Continuar desde la última pasada |
-| `/nemesis --contract <nombre>` | Auditoría completa sobre un módulo específico |
+| `/swl:nemesis` | Auditoría completa iterativa (solo audita, sin remediar) |
+| `/swl:nemesis --remediar` | Loop evaluator-optimizer completo: audita → invoca orquestador-swl con hallazgos → re-audita. Max 3 iteraciones. Convergencia cuando status=PASS. |
+| `/swl:nemesis --pass1` | Solo Pasada 1 — Feynman completo |
+| `/swl:nemesis --pass2` | Solo Pasada 2 — State sobre output existente de Pasada 1 |
+| `/swl:nemesis --continue` | Continuar desde la última pasada |
+| `/swl:nemesis --modulo <ruta>` | Auditoría sobre un módulo específico |
+| `/swl:nemesis --redistribuir` | Forzar modo redistribuido (comando carga `Skill("nemesis-redistribuir")` aunque scope sea menor al umbral) |
 
 ---
 

package/bin/swl-mcp-server.js

@@ -1,214 +1,214 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * swl-mcp-server — Servidor MCP de solo lectura para exponer la memoria
- * de swl-ses a clientes MCP externos (Cursor, Codex CLI, Gemini CLI, etc.).
- *
- * v1.0.0 (ADR-0019 Sub-fase 3) — promovido de stub experimental a versión
- * estable con auth opt-in, caching mtime-based, telemetría JSONL y schema
- * versioning. Mantiene compatibilidad total con clientes existentes que
- * conectan sin auth (si `SWL_MCP_API_KEY` no está set, comportamiento idéntico
- * al stub v0.1.x).
- *
- * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
- *
- * Uso (cliente MCP):
- *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
- *     con stdio.
- *   - El cwd del proceso determina baseDir (override con `SWL_MCP_BASE_DIR`).
- *
- * Variables opt-in (env del server):
- *   - SWL_MCP_API_KEY      — Si set, requiere params._auth en cada tools/call.
- *   - SWL_MCP_CACHE_TTL_MS — TTL del cache mtime-based (default 60000).
- *   - SWL_MCP_METRICS      — Si "1" o "true", persiste metrics en
- *                            .planning/evolucion/mcp-metrics.jsonl.
- *
- * Schema versioning:
- *   - Cada handler declara `schemaVersion` en su definición.
- *   - El cliente puede inspeccionarlo via `tools/list` (campo `_schemaVersion`).
- *
- * Protocolo MCP soportado (subset):
- *   - initialize / initialized
- *   - tools/list
- *   - tools/call
- *   - ping
- */
-
-const path = require('path');
-
-const { HANDLERS } = require('../scripts/mcp-server/handlers');
-const { construirValidador } = require('../scripts/mcp-server/auth');
-const { construirTelemetria } = require('../scripts/mcp-server/telemetry');
-
-const SERVER_NAME = 'swl-mcp-server';
-const SERVER_VERSION = '1.0.0';
-const PROTOCOL_VERSION = '2024-11-05';
-
-const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
-const authValidator = construirValidador();
-const telemetry = construirTelemetria({ baseDir });
-
-// ── logging ───────────────────────────────────────────────────────────────────
-
-// Stderr para evitar contaminar stdout (que es JSON-RPC).
-function log(level, msg, data) {
-  const linea = JSON.stringify({
-    timestamp: new Date().toISOString(),
-    level,
-    msg,
-    ...(data ? { data } : {}),
-  });
-  process.stderr.write(linea + '\n');
-}
-
-// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
-
-function respuesta(id, result) {
-  return JSON.stringify({ jsonrpc: '2.0', id, result });
-}
-
-function errorResp(id, code, message) {
-  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
-}
-
-// ── routing ───────────────────────────────────────────────────────────────────
-
-function manejarInitialize(request) {
-  return respuesta(request.id, {
-    protocolVersion: PROTOCOL_VERSION,
-    capabilities: {
-      tools: { listChanged: false },
-    },
-    serverInfo: {
-      name: SERVER_NAME,
-      version: SERVER_VERSION,
-      authRequired: authValidator.requerida,
-      telemetryEnabled: telemetry.habilitada,
-    },
-  });
-}
-
-function manejarToolsList(request) {
-  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
-    name,
-    description: def.description,
-    inputSchema: def.inputSchema,
-    _schemaVersion: def.schemaVersion || '1.0.0',
-  }));
-  return respuesta(request.id, { tools });
-}
-
-function manejarToolsCall(request) {
-  const { name, arguments: args } = request.params || {};
-  const def = HANDLERS[name];
-  if (!def) {
-    return errorResp(request.id, -32601, `Tool no encontrado: ${name}`);
-  }
-  const inicio = Date.now();
-  try {
-    const result = def.handler(baseDir, args || {});
-    const duracionMs = Date.now() - inicio;
-    telemetry.registrar({ tool: name, durationMs: duracionMs, ok: true, baseDir });
-    return respuesta(request.id, {
-      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-    });
-  } catch (err) {
-    const duracionMs = Date.now() - inicio;
-    log('error', `Excepción en handler ${name}`, { error: err.message });
-    telemetry.registrar({ tool: name, durationMs: duracionMs, ok: false, error: err.message, baseDir });
-    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
-  }
-}
-
-/**
- * Punto de entrada del routing — público para tests.
- *
- * @param {object} request - Mensaje JSON-RPC parseado.
- * @returns {string|null} - String JSON-RPC respuesta o null (notification).
- */
-function rutear(request) {
-  // Auth gate: si SWL_MCP_API_KEY está set, validar antes de routing.
-  const auth = authValidator.validar(request);
-  if (!auth.ok) {
-    return errorResp(request.id, auth.code, auth.message);
-  }
-
-  switch (request.method) {
-    case 'initialize':
-      return manejarInitialize(request);
-    case 'initialized':
-    case 'notifications/initialized':
-      return null; // notification — sin respuesta
-    case 'tools/list':
-      return manejarToolsList(request);
-    case 'tools/call':
-      return manejarToolsCall(request);
-    case 'ping':
-      return respuesta(request.id, {});
-    default:
-      return errorResp(request.id, -32601, `Método no soportado: ${request.method}`);
-  }
-}
-
-// ── loop principal ────────────────────────────────────────────────────────────
-
-function arrancar() {
-  log('info', `${SERVER_NAME} v${SERVER_VERSION} iniciando`, {
-    baseDir,
-    authRequired: authValidator.requerida,
-    telemetryEnabled: telemetry.habilitada,
-  });
-
-  let buffer = '';
-
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', (chunk) => {
-    buffer += chunk;
-
-    // Cada mensaje JSON-RPC termina con \n
-    let nlIndex;
-    while ((nlIndex = buffer.indexOf('\n')) >= 0) {
-      const linea = buffer.slice(0, nlIndex).trim();
-      buffer = buffer.slice(nlIndex + 1);
-
-      if (!linea) continue;
-
-      let request;
-      try {
-        request = JSON.parse(linea);
-      } catch (err) {
-        log('error', 'JSON inválido recibido', { error: err.message, linea: linea.slice(0, 100) });
-        process.stdout.write(errorResp(null, -32700, 'Parse error') + '\n');
-        continue;
-      }
-
-      const respuestaStr = rutear(request);
-      if (respuestaStr) {
-        process.stdout.write(respuestaStr + '\n');
-      }
-    }
-  });
-
-  process.stdin.on('end', () => {
-    log('info', 'stdin cerrado, server termina');
-    process.exit(0);
-  });
-
-  // Manejo de errores no capturados — nunca crashear silenciosamente
-  process.on('uncaughtException', (err) => {
-    log('error', 'uncaughtException', { error: err.message, stack: err.stack });
-  });
-}
-
-if (require.main === module) {
-  arrancar();
-}
-
-module.exports = {
-  rutear,
-  arrancar,
-  SERVER_NAME,
-  SERVER_VERSION,
-  PROTOCOL_VERSION,
-};
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * swl-mcp-server — Servidor MCP de solo lectura para exponer la memoria
+ * de swl-ses a clientes MCP externos (Cursor, Codex CLI, Gemini CLI, etc.).
+ *
+ * v1.0.0 (ADR-0019 Sub-fase 3) — promovido de stub experimental a versión
+ * estable con auth opt-in, caching mtime-based, telemetría JSONL y schema
+ * versioning. Mantiene compatibilidad total con clientes existentes que
+ * conectan sin auth (si `SWL_MCP_API_KEY` no está set, comportamiento idéntico
+ * al stub v0.1.x).
+ *
+ * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
+ *
+ * Uso (cliente MCP):
+ *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
+ *     con stdio.
+ *   - El cwd del proceso determina baseDir (override con `SWL_MCP_BASE_DIR`).
+ *
+ * Variables opt-in (env del server):
+ *   - SWL_MCP_API_KEY      — Si set, requiere params._auth en cada tools/call.
+ *   - SWL_MCP_CACHE_TTL_MS — TTL del cache mtime-based (default 60000).
+ *   - SWL_MCP_METRICS      — Si "1" o "true", persiste metrics en
+ *                            .planning/evolucion/mcp-metrics.jsonl.
+ *
+ * Schema versioning:
+ *   - Cada handler declara `schemaVersion` en su definición.
+ *   - El cliente puede inspeccionarlo via `tools/list` (campo `_schemaVersion`).
+ *
+ * Protocolo MCP soportado (subset):
+ *   - initialize / initialized
+ *   - tools/list
+ *   - tools/call
+ *   - ping
+ */
+
+const path = require('path');
+
+const { HANDLERS } = require('../scripts/mcp-server/handlers');
+const { construirValidador } = require('../scripts/mcp-server/auth');
+const { construirTelemetria } = require('../scripts/mcp-server/telemetry');
+
+const SERVER_NAME = 'swl-mcp-server';
+const SERVER_VERSION = '1.0.0';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
+const authValidator = construirValidador();
+const telemetry = construirTelemetria({ baseDir });
+
+// ── logging ───────────────────────────────────────────────────────────────────
+
+// Stderr para evitar contaminar stdout (que es JSON-RPC).
+function log(level, msg, data) {
+  const linea = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    level,
+    msg,
+    ...(data ? { data } : {}),
+  });
+  process.stderr.write(linea + '\n');
+}
+
+// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
+
+function respuesta(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function errorResp(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+// ── routing ───────────────────────────────────────────────────────────────────
+
+function manejarInitialize(request) {
+  return respuesta(request.id, {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: {
+      tools: { listChanged: false },
+    },
+    serverInfo: {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+      authRequired: authValidator.requerida,
+      telemetryEnabled: telemetry.habilitada,
+    },
+  });
+}
+
+function manejarToolsList(request) {
+  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
+    name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+    _schemaVersion: def.schemaVersion || '1.0.0',
+  }));
+  return respuesta(request.id, { tools });
+}
+
+function manejarToolsCall(request) {
+  const { name, arguments: args } = request.params || {};
+  const def = HANDLERS[name];
+  if (!def) {
+    return errorResp(request.id, -32601, `Tool no encontrado: ${name}`);
+  }
+  const inicio = Date.now();
+  try {
+    const result = def.handler(baseDir, args || {});
+    const duracionMs = Date.now() - inicio;
+    telemetry.registrar({ tool: name, durationMs: duracionMs, ok: true, baseDir });
+    return respuesta(request.id, {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    });
+  } catch (err) {
+    const duracionMs = Date.now() - inicio;
+    log('error', `Excepción en handler ${name}`, { error: err.message });
+    telemetry.registrar({ tool: name, durationMs: duracionMs, ok: false, error: err.message, baseDir });
+    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
+  }
+}
+
+/**
+ * Punto de entrada del routing — público para tests.
+ *
+ * @param {object} request - Mensaje JSON-RPC parseado.
+ * @returns {string|null} - String JSON-RPC respuesta o null (notification).
+ */
+function rutear(request) {
+  // Auth gate: si SWL_MCP_API_KEY está set, validar antes de routing.
+  const auth = authValidator.validar(request);
+  if (!auth.ok) {
+    return errorResp(request.id, auth.code, auth.message);
+  }
+
+  switch (request.method) {
+    case 'initialize':
+      return manejarInitialize(request);
+    case 'initialized':
+    case 'notifications/initialized':
+      return null; // notification — sin respuesta
+    case 'tools/list':
+      return manejarToolsList(request);
+    case 'tools/call':
+      return manejarToolsCall(request);
+    case 'ping':
+      return respuesta(request.id, {});
+    default:
+      return errorResp(request.id, -32601, `Método no soportado: ${request.method}`);
+  }
+}
+
+// ── loop principal ────────────────────────────────────────────────────────────
+
+function arrancar() {
+  log('info', `${SERVER_NAME} v${SERVER_VERSION} iniciando`, {
+    baseDir,
+    authRequired: authValidator.requerida,
+    telemetryEnabled: telemetry.habilitada,
+  });
+
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+
+    // Cada mensaje JSON-RPC termina con \n
+    let nlIndex;
+    while ((nlIndex = buffer.indexOf('\n')) >= 0) {
+      const linea = buffer.slice(0, nlIndex).trim();
+      buffer = buffer.slice(nlIndex + 1);
+
+      if (!linea) continue;
+
+      let request;
+      try {
+        request = JSON.parse(linea);
+      } catch (err) {
+        log('error', 'JSON inválido recibido', { error: err.message, linea: linea.slice(0, 100) });
+        process.stdout.write(errorResp(null, -32700, 'Parse error') + '\n');
+        continue;
+      }
+
+      const respuestaStr = rutear(request);
+      if (respuestaStr) {
+        process.stdout.write(respuestaStr + '\n');
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    log('info', 'stdin cerrado, server termina');
+    process.exit(0);
+  });
+
+  // Manejo de errores no capturados — nunca crashear silenciosamente
+  process.on('uncaughtException', (err) => {
+    log('error', 'uncaughtException', { error: err.message, stack: err.stack });
+  });
+}
+
+if (require.main === module) {
+  arrancar();
+}
+
+module.exports = {
+  rutear,
+  arrancar,
+  SERVER_NAME,
+  SERVER_VERSION,
+  PROTOCOL_VERSION,
+};