@saulwade/swl-ses 1.0.0

package/scripts/lib/notificaciones-telegram.js

@@ -0,0 +1,1107 @@
+'use strict';
+
+/**
+ * Flujo reutilizable de configuración de notificaciones Telegram.
+ *
+ * Usado por:
+ *   - scripts/instalador.js (paso 9 opt-in)
+ *   - /swl:notificaciones init (Slice 005)
+ *
+ * SEGURIDAD:
+ *   - El token NUNCA se loggea. Solo se muestra longitud y primeros 3 chars.
+ *   - El .env se escribe en ~/.claude/notifications/ (fuera del repo).
+ *   - Permisos 0o600 en POSIX; en Windows la ACL del sistema ya protege
+ *     %USERPROFILE%\.claude\.
+ *   - Validación post-escritura con JSON.parse + rollback si falla.
+ *   - Backup obligatorio de settings.json antes de cada merge.
+ *
+ * ADR-0009: esta función es la ÚNICA excepción a la regla
+ * "SWL solo registra hooks a nivel proyecto" (hooks-settings.js).
+ * Aplica exclusivamente bajo opt-in explícito del usuario.
+ *
+ * @module scripts/lib/notificaciones-telegram
+ */
+
+const fs             = require('node:fs');
+const path           = require('node:path');
+const os             = require('node:os');
+const readline       = require('node:readline');
+const { execFileSync } = require('node:child_process');
+
+const { atomicWriteSync, atomicWriteJSON } = require('../../hooks/lib/atomic-write');
+// IMPORTANTE: usar require sin destructuring para que los mocks de tests funcionen.
+// El destructuring captura la referencia local original y los mocks posteriores
+// no tienen efecto. Con el módulo completo, hooksSettings.mergeHooksGlobales(...)
+// siempre resuelve la propiedad en tiempo de ejecución. (Fix Slice 015-A)
+const hooksSettings = require('./hooks-settings');
+
+// ---------------------------------------------------------------------------
+// Rutas canónicas (NUNCA dentro del repo)
+// ---------------------------------------------------------------------------
+
+const DIR_NOTIFICACIONES  = path.join(os.homedir(), '.claude', 'notifications');
+const RUTA_PID_DAEMON     = path.join(DIR_NOTIFICACIONES, 'bot.pid');
+const RUTA_BIN_DAEMON     = path.resolve(__dirname, '..', '..', 'bin', 'swl-telegram-bot.js');
+const RUTA_ENV           = path.join(DIR_NOTIFICACIONES, '.env');
+const RUTA_BASELINE      = path.join(DIR_NOTIFICACIONES, 'baseline-hooks.json');
+const RUTA_SETTINGS_GLOBAL = path.join(os.homedir(), '.claude', 'settings.json');
+
+// ---------------------------------------------------------------------------
+// Directorio global de hooks (~/.claude/hooks/)
+// ---------------------------------------------------------------------------
+
+/** Directorio destino donde se copian los hooks para ejecución global. */
+const HOOKS_GLOBAL_DIR = path.join(os.homedir(), '.claude', 'hooks');
+
+/**
+ * Lista de archivos a copiar desde <repo>/hooks/ a ~/.claude/hooks/.
+ * Se preserva la estructura lib/ para que los requires relativos funcionen.
+ *
+ * Orden importa para resolución de dependencias: lib/ primero, hooks raíz después.
+ */
+const HOOKS_A_COPIAR = [
+  'lib/atomic-write.js',         // dependencia de auto-restaurar y notificacion
+  'lib/telegram-cliente.js',
+  'lib/telegram-config.js',
+  'notificacion-telegram.js',
+  'notificacion-telegram-notification.js',
+  'notificacion-telegram-subagent.js',
+  'auto-restaurar-settings.js',
+];
+
+// Hooks SWL que se registran en el settings global bajo opt-in
+const HOOKS_SWL_NOTIFICACIONES = [
+  {
+    evento: 'Stop',
+    matcher: '',
+    archivo: 'notificacion-telegram.js',
+  },
+  {
+    evento: 'Notification',
+    matcher: '',
+    archivo: 'notificacion-telegram.js',
+  },
+  {
+    evento: 'SubagentStop',
+    matcher: '',
+    archivo: 'notificacion-telegram.js',
+  },
+  {
+    evento: 'SessionStart',
+    matcher: '',
+    archivo: 'auto-restaurar-settings.js',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Copia de hooks a ~/.claude/hooks/ (REM-A, REM-E)
+// ---------------------------------------------------------------------------
+
+/**
+ * Copia los archivos de hook desde el repo swl-ses a ~/.claude/hooks/.
+ * Preserva la estructura lib/ para que los requires relativos funcionen.
+ *
+ * Verifica que cada archivo origen existe ANTES de copiar (REM-E).
+ * Si algún origen falta, lanza con mensaje claro que indica la ruta esperada.
+ *
+ * @param {string} [hooksOrigenOverride] - Para tests: sobreescribir el directorio origen.
+ * @param {string} [hooksGlobalDirOverride] - Para tests: sobreescribir el directorio destino.
+ * @returns {{ directorio: string, archivos: string[] }}
+ * @throws {Error} Si algún archivo origen no existe o la copia falla.
+ */
+function _copiarHooksGlobales(hooksOrigenOverride, hooksGlobalDirOverride) {
+  // __dirname apunta a <repo-swl>/scripts/lib/ → subir 2 niveles → <repo-swl>/hooks/
+  const hooksOrigen   = hooksOrigenOverride || path.resolve(__dirname, '..', '..', 'hooks');
+  const hooksDestino  = hooksGlobalDirOverride || HOOKS_GLOBAL_DIR;
+
+  // Crear directorios destino si no existen
+  if (!fs.existsSync(hooksDestino)) {
+    fs.mkdirSync(hooksDestino, { recursive: true });
+  }
+  const libDestino = path.join(hooksDestino, 'lib');
+  if (!fs.existsSync(libDestino)) {
+    fs.mkdirSync(libDestino, { recursive: true });
+  }
+
+  const copiados = [];
+  for (const rel of HOOKS_A_COPIAR) {
+    const origen  = path.join(hooksOrigen, rel);
+    const destino = path.join(hooksDestino, rel);
+
+    // REM-E: verificar que el archivo origen existe
+    if (!fs.existsSync(origen)) {
+      throw new Error(
+        `Hook origen no encontrado: ${origen}. ` +
+        `Verifica que swl-ses está instalado correctamente en: ${hooksOrigen}`
+      );
+    }
+
+    fs.copyFileSync(origen, destino);
+
+    // REM-E: verificar integridad post-copia (existe + tamaño > 0)
+    const stats = fs.statSync(destino);
+    if (stats.size === 0) {
+      throw new Error(
+        `Hook copiado con tamaño 0: ${destino}. ` +
+        `El archivo origen puede estar corrupto: ${origen}`
+      );
+    }
+
+    copiados.push(rel);
+  }
+
+  // Loggear en init.log solo paths y nombres — NUNCA secrets
+  const logPath  = path.join(DIR_NOTIFICACIONES, 'init.log');
+  const logLinea = `[${new Date().toISOString()}] hooks copiados a ${hooksDestino}: ${copiados.join(', ')}\n`;
+  try { fs.appendFileSync(logPath, logLinea, 'utf8'); } catch (_) {}
+
+  return { directorio: hooksDestino, archivos: copiados };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica que una ruta está dentro del directorio ~/.claude/notifications/
+ * y nunca dentro de un repositorio git.
+ *
+ * @param {string} ruta - Ruta absoluta a verificar.
+ * @returns {boolean} true si la ruta es segura.
+ */
+function _esRutaSegura(ruta) {
+  const rutaNorm = path.resolve(ruta);
+  const dirNorm  = path.resolve(DIR_NOTIFICACIONES);
+  return rutaNorm.startsWith(dirNorm);
+}
+
+/**
+ * Oculta un token para logging: muestra primeros 3 chars + ***.
+ * NUNCA loggear el token completo.
+ *
+ * @param {string} token
+ * @returns {string}
+ */
+function _ocultarToken(token) {
+  if (!token || token.length < 4) return '***';
+  return token.slice(0, 3) + '*** (long: ' + token.length + ')';
+}
+
+/**
+ * Genera el contenido del archivo .env con las credenciales.
+ * Preserva caracteres especiales (`:`, `=`, `_`) sin escape adicional.
+ *
+ * @param {string} token
+ * @param {string} chatId
+ * @returns {string}
+ */
+function _generarContenidoEnv(token, chatId) {
+  return [
+    '# Credenciales de notificaciones Telegram — generado por swl-ses',
+    '# Este archivo vive en ~/.claude/notifications/ (fuera del repo, permisos 600)',
+    '# El token NO se commitea al repositorio.',
+    '# Para revocar: /swl:notificaciones disable',
+    '',
+    `TELEGRAM_BOT_TOKEN=${token}`,
+    `TELEGRAM_CHAT_ID=${chatId}`,
+    '',
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Validación de formato de credenciales Telegram
+// ---------------------------------------------------------------------------
+
+/**
+ * Regex para validar el formato del token de bot de Telegram.
+ * Formato esperado: <digits>:<alphanum~35chars> — entregado por BotFather.
+ * Ejemplo válido: 7123456789:AAHkjdhsjkhd-sdfJKH987jklsd_xyzABCDEF
+ *
+ * NUNCA loggear el valor del token — solo longitud y booleano de validez.
+ */
+const RX_TOKEN_TELEGRAM = /^\d+:[A-Za-z0-9_-]{20,}$/;
+
+/**
+ * Regex para validar el chat_id de Telegram.
+ * Puede ser positivo (chat privado) o negativo (grupo/supergrupo).
+ */
+const RX_CHAT_ID = /^-?\d+$/;
+
+/**
+ * Valida el formato del token de Telegram sin loggear su valor.
+ *
+ * @param {string} token
+ * @returns {boolean}
+ */
+function _validarFormatoToken(token) {
+  if (!token || typeof token !== 'string') return false;
+  return RX_TOKEN_TELEGRAM.test(token);
+}
+
+/**
+ * Valida el formato del chat_id de Telegram.
+ *
+ * @param {string} chatId
+ * @returns {boolean}
+ */
+function _validarFormatoChatId(chatId) {
+  if (!chatId || typeof chatId !== 'string') return false;
+  return RX_CHAT_ID.test(chatId);
+}
+
+/**
+ * Crea un backup del .env existente antes de sobreescribirlo.
+ * El backup se almacena en el mismo directorio con timestamp Unix en el nombre.
+ * NUNCA loggea el contenido del .env — solo el path del backup.
+ *
+ * @param {string} rutaEnv - Ruta del .env a respaldar.
+ * @returns {{ ok: boolean, rutaBackup?: string, error?: string }}
+ */
+function _respaldarEnvExistente(rutaEnv) {
+  try {
+    // Solo respaldar si existe y tiene contenido de credenciales válidas
+    if (!fs.existsSync(rutaEnv)) return { ok: true };
+    const contenido = fs.readFileSync(rutaEnv, 'utf8');
+    if (!contenido.includes('TELEGRAM_BOT_TOKEN=')) return { ok: true };
+
+    const ts = Date.now();
+    const rutaBackup = rutaEnv + `.swl-backup-${ts}`;
+    // Copiar con permisos 600 en POSIX
+    const writeOpts = { encoding: 'utf8' };
+    if (process.platform !== 'win32') writeOpts.mode = 0o600;
+    fs.writeFileSync(rutaBackup, contenido, writeOpts);
+
+    // Loggear en init.log solo el path y timestamp — NUNCA el contenido
+    const logPath = path.join(DIR_NOTIFICACIONES, 'init.log');
+    const logLinea = `[${new Date(ts).toISOString()}] backup creado: ${rutaBackup}\n`;
+    try { fs.appendFileSync(logPath, logLinea, 'utf8'); } catch (_) {}
+
+    return { ok: true, rutaBackup };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Lee credenciales de forma interactiva usando node:readline.
+ * Valida el formato antes de aceptar. Permite hasta MAX_REINTENTOS intentos.
+ * Muestra instrucciones cortas con links a BotFather y /quien.
+ *
+ * @returns {Promise<{ token: string, chatId: string } | null>} null si el
+ *   usuario cancela o agota los reintentos.
+ */
+async function leerCredencialesInteractivo() {
+  const MAX_REINTENTOS = 3;
+
+  const rl = readline.createInterface({
+    input:  process.stdin,
+    output: process.stdout,
+  });
+
+  const preguntar = (msg) => new Promise((resolve) => {
+    rl.question(msg, (resp) => resolve(resp.trim()));
+  });
+
+  try {
+    console.log('');
+    console.log('  Instrucciones para obtener las credenciales:');
+    console.log('  1. Crea un bot en https://t.me/BotFather con /newbot');
+    console.log('  2. Copia el token que te entrega.');
+    console.log('  3. Envía /quien al bot para obtener tu chat_id.');
+    console.log('');
+    console.log('  El token NO se commitea al repositorio.');
+    console.log('  Se almacena en ~/.claude/notifications/.env (fuera del repo, permisos 600).');
+    console.log('');
+
+    // Leer y validar token con retry
+    let token = null;
+    for (let intento = 1; intento <= MAX_REINTENTOS; intento++) {
+      const valorToken = await preguntar('  TELEGRAM_BOT_TOKEN: ');
+      if (!valorToken) {
+        console.log('  Token vacío — cancelando.');
+        return null;
+      }
+      if (_validarFormatoToken(valorToken)) {
+        token = valorToken;
+        break;
+      }
+      const restantes = MAX_REINTENTOS - intento;
+      if (restantes > 0) {
+        console.log(`  Token con formato inválido. Esperado: <digits>:<alphanum> (~46 chars de BotFather)`);
+        console.log(`  Ejemplo: 7123456789:AAHkjdhsjkhd-sdfJKH987jklsd_xyzABCDEF`);
+        console.log(`  (longitud=${valorToken.length}, formato_valido=false) — ${restantes} intento(s) restante(s).`);
+      } else {
+        console.log(`  Token con formato inválido (longitud=${valorToken.length}, formato_valido=false). Máximo de reintentos alcanzado.`);
+      }
+    }
+    if (!token) return null;
+
+    // Leer y validar chatId con retry
+    let chatId = null;
+    for (let intento = 1; intento <= MAX_REINTENTOS; intento++) {
+      const valorChatId = await preguntar('  TELEGRAM_CHAT_ID: ');
+      if (!valorChatId) {
+        console.log('  Chat ID vacío — cancelando.');
+        return null;
+      }
+      if (_validarFormatoChatId(valorChatId)) {
+        chatId = valorChatId;
+        break;
+      }
+      const restantes = MAX_REINTENTOS - intento;
+      if (restantes > 0) {
+        console.log(`  Chat ID con formato inválido. Esperado: número entero positivo o negativo.`);
+        console.log(`  Ejemplo: -1001234567890  o  123456789`);
+        console.log(`  (formato_valido=false) — ${restantes} intento(s) restante(s).`);
+      } else {
+        console.log(`  Chat ID con formato inválido. Máximo de reintentos alcanzado.`);
+      }
+    }
+    if (!chatId) return null;
+
+    return { token, chatId };
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Genera el JSON de baseline-hooks: la lista de hooks que el hook
+ * SessionStart usará para restaurar settings.json si se pierden.
+ *
+ * SIEMPRE usa paths absolutos a ~/.claude/hooks/ para que los hooks
+ * funcionen desde cualquier directorio de trabajo (cwd).
+ *
+ * @param {string} [hooksGlobalDirOverride] - Para tests: sobreescribir el dir global.
+ * @returns {object} Objeto JSON listo para escribir.
+ */
+function _generarBaselineHooks(hooksGlobalDirOverride) {
+  const hooksDir = hooksGlobalDirOverride || HOOKS_GLOBAL_DIR;
+  const baseline = { hooks: {} };
+
+  for (const h of HOOKS_SWL_NOTIFICACIONES) {
+    if (!baseline.hooks[h.evento]) {
+      baseline.hooks[h.evento] = [];
+    }
+    // Evitar duplicar el mismo archivo en el mismo evento
+    const yaExiste = baseline.hooks[h.evento].some(
+      entry => (entry.hooks || []).some(x => x.command && x.command.includes(h.archivo))
+    );
+    if (!yaExiste) {
+      // REM-B: SIEMPRE path absoluto — nunca path relativo
+      const rutaAbs     = path.join(hooksDir, h.archivo).replace(/\\/g, '/');
+      const comandoNode = `node "${rutaAbs}"`;
+      baseline.hooks[h.evento].push({
+        matcher: h.matcher,
+        hooks: [{ type: 'command', command: comandoNode }],
+      });
+    }
+  }
+
+  return baseline;
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Inicializa la configuración de notificaciones Telegram.
+ *
+ * Flujo:
+ *   1. Verificar feature flag SWL_NOTIFICACIONES_TELEGRAM=0
+ *   2. Si no-TTY y sin flags headless → saltar
+ *   3. Preguntar opt-in (TTY) o usar credenciales de flags (headless)
+ *   4. Si respuesta n → omitir sin tocar nada
+ *   5. Obtener credenciales (interactivo o flags)
+ *   6. Verificar seguridad de ruta del .env
+ *   7. Crear ~/.claude/notifications/ si no existe
+ *   8. Escribir .env con modo 600 en POSIX
+ *   9. Generar baseline-hooks.json
+ *  10. Merge en ~/.claude/settings.json (backup + validación + rollback)
+ *
+ * @param {object} opciones
+ * @param {string}  [opciones.token]        - Token provisto por flag (modo headless).
+ * @param {string}  [opciones.chatId]       - Chat ID provisto por flag (modo headless).
+ * @param {boolean} [opciones.esTty]        - Si el proceso corre en TTY.
+ * @param {boolean} [opciones.omitir]       - Forzar omisión sin preguntar.
+ * @param {boolean} [opciones.sobreescribir] - Sobreescribir .env existente sin preguntar.
+ * @param {boolean} [opciones.dryRun]       - Mostrar qué se haría sin tocar nada.
+ * @param {string}  [opciones.hooksDir]     - Directorio de hooks instalados.
+ * @param {string}  [opciones._settingsPathOverride] - EXCLUSIVO para tests: ruta de settings.json
+ *   alternativa. El prefijo _ señala que es parámetro de test — producción NUNCA lo pasa.
+ *   Evita que los tests escriban al ~/.claude/settings.json REAL del usuario. (Fix Slice 015-B)
+ * @param {string}  [opciones._envPathOverride] - EXCLUSIVO para tests: ruta de .env alternativa.
+ *   El prefijo _ señala que es parámetro de test — producción NUNCA lo pasa.
+ *   Evita que los tests escriban al ~/.claude/notifications/.env REAL del usuario. (Fix v5.12.2)
+ * @returns {Promise<{ resultado: string, detalle?: string }>}
+ *   resultado: 'completado' | 'omitido' | 'error'
+ */
+async function init(opciones = {}) {
+  const {
+    token:        tokenFlag  = null,
+    chatId:       chatIdFlag = null,
+    esTty:        esTty      = !!process.stdin.isTTY,
+    omitir:       omitir     = false,
+    sobreescribir: sobreescribir = false,
+    dryRun:       dryRun     = false,
+    hooksDir:     hooksDir   = null,
+    // Overrides para tests — permiten inyectar directorios temporales
+    _hooksOrigenOverride:    _hooksOrigenOverride    = null,
+    _hooksGlobalDirOverride: _hooksGlobalDirOverride = null,
+    // EXCLUSIVO para tests: ruta alternativa de settings.json — ver Fix Slice 015-B
+    _settingsPathOverride:   _settingsPathOverride   = null,
+    // EXCLUSIVO para tests: ruta alternativa del .env — ver Fix v5.12.2
+    _envPathOverride:        _envPathOverride        = null,
+  } = opciones;
+
+  // Ruta efectiva del .env: override para tests, canónica en producción
+  const envPath = _envPathOverride || RUTA_ENV;
+
+  // Feature flag de emergencia — desactivación sin tocar settings
+  if (process.env.SWL_NOTIFICACIONES_TELEGRAM === '0') {
+    console.log('  [notificaciones] SWL_NOTIFICACIONES_TELEGRAM=0 — omitido por variable de entorno.');
+    return { resultado: 'omitido', detalle: 'feature flag desactivado' };
+  }
+
+  if (omitir) {
+    return { resultado: 'omitido', detalle: 'omisión forzada' };
+  }
+
+  const modoHeadless = tokenFlag !== null && chatIdFlag !== null;
+
+  // En modo no-TTY sin flags headless → saltar automáticamente
+  if (!esTty && !modoHeadless) {
+    console.log('  [notificaciones] omitido en modo no-interactivo (usar /swl:notificaciones init para activarlo después).');
+    return { resultado: 'omitido', detalle: 'modo no-TTY sin flags headless' };
+  }
+
+  let token  = tokenFlag;
+  let chatId = chatIdFlag;
+
+  // Modo interactivo (TTY, sin flags headless)
+  if (!modoHeadless && esTty) {
+    // Detectar .env preexistente
+    if (fs.existsSync(envPath) && !sobreescribir) {
+      console.log('');
+      console.log('  [notificaciones] Ya existe ~/.claude/notifications/.env con credenciales.');
+      const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const reusar = await new Promise((resolve) => {
+        rl2.question('  ¿Reusar las credenciales existentes? [S/n] ', (resp) => {
+          rl2.close();
+          const r = resp.trim().toLowerCase();
+          resolve(r === '' || r === 's' || r === 'si' || r === 'sí' || r === 'y');
+        });
+      });
+
+      if (reusar) {
+        // Solo hacer merge en settings global sin reescribir .env
+        // REM-B: pasar override para que mergeHooksGlobales use ruta absoluta
+        return _soloMergeSettings(_hooksGlobalDirOverride, dryRun, _settingsPathOverride);
+      }
+    }
+
+    // Preguntar opt-in
+    console.log('');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const habilitarNotif = await new Promise((resolve) => {
+      rl.question(
+        '  ¿Habilitar notificaciones Telegram al final de cada turno? [s/N] ',
+        (resp) => {
+          rl.close();
+          const r = resp.trim().toLowerCase();
+          resolve(r === 's' || r === 'si' || r === 'sí' || r === 'y');
+        }
+      );
+    });
+
+    if (!habilitarNotif) {
+      console.log('  [notificaciones] omitidas.');
+      return { resultado: 'omitido', detalle: 'usuario respondió n' };
+    }
+
+    const creds = await leerCredencialesInteractivo();
+    if (!creds) {
+      return { resultado: 'omitido', detalle: 'usuario canceló ingreso de credenciales' };
+    }
+    token  = creds.token;
+    chatId = creds.chatId;
+  }
+
+  // Headless con .env preexistente: reusar silenciosamente si no se pide sobreescribir
+  if (modoHeadless && fs.existsSync(envPath) && !sobreescribir) {
+    console.log('  [notificaciones] Reusando .env existente (usar --sobreescribir para reemplazar).');
+    // REM-B: pasar override para que mergeHooksGlobales use ruta absoluta
+    return _soloMergeSettings(_hooksGlobalDirOverride, dryRun, _settingsPathOverride);
+  }
+
+  // Validar que tenemos credenciales
+  if (!token || !chatId) {
+    return { resultado: 'error', detalle: 'credenciales incompletas (token y chatId son requeridos)' };
+  }
+
+  // Validar formato de token — NUNCA loggear el valor
+  if (!_validarFormatoToken(token)) {
+    const msg = `Token con formato inválido (longitud=${token.length}, formato_valido=false). Esperado: <digits>:<alphanum> (~46 chars de BotFather).`;
+    if (modoHeadless) {
+      process.stderr.write(`[notificaciones] Error: ${msg}\n`);
+      return { resultado: 'error', detalle: msg };
+    }
+    return { resultado: 'error', detalle: msg };
+  }
+
+  // Validar formato de chatId
+  if (!_validarFormatoChatId(chatId)) {
+    const msg = `Chat ID con formato inválido. Esperado: número entero positivo o negativo (ej: -1001234567890).`;
+    if (modoHeadless) {
+      process.stderr.write(`[notificaciones] Error: ${msg}\n`);
+      return { resultado: 'error', detalle: msg };
+    }
+    return { resultado: 'error', detalle: msg };
+  }
+
+  // Verificar seguridad de ruta — .env NUNCA dentro del repo
+  // En modo test con _envPathOverride, saltamos la validación de ruta canónica
+  // porque el override apunta a un tmpDir fuera de DIR_NOTIFICACIONES (eso es correcto).
+  if (!_envPathOverride && !_esRutaSegura(envPath)) {
+    return {
+      resultado: 'error',
+      detalle: `Ruta insegura detectada: ${envPath} no está dentro de ${DIR_NOTIFICACIONES}. Abortando.`,
+    };
+  }
+
+  if (dryRun) {
+    console.log('');
+    console.log('  [dry-run] Archivos que se crearían/modificarían:');
+    console.log(`    COPIAR ${HOOKS_A_COPIAR.length} hook(s) → ~/.claude/hooks/`);
+    console.log(`    CREAR  ${envPath} (modo 600 en POSIX)`);
+    console.log(`    CREAR  ${RUTA_BASELINE}`);
+    console.log(`    MERGE  ${RUTA_SETTINGS_GLOBAL} (backup antes de modificar)`);
+    console.log('');
+    return { resultado: 'omitido', detalle: 'dry-run: sin cambios aplicados' };
+  }
+
+  // REM-A: copiar hooks al directorio global ANTES de registrar en settings.
+  // Garantiza que Claude Code siempre encuentre los archivos en ~/.claude/hooks/
+  // independientemente del proyecto activo al ejecutarse el Stop hook.
+  try {
+    const copiaRes = _copiarHooksGlobales(_hooksOrigenOverride, _hooksGlobalDirOverride);
+    console.log(`  [notificaciones] ${copiaRes.archivos.length} hook(s) copiados a: ${copiaRes.directorio}`);
+  } catch (err) {
+    console.error(`  ! [notificaciones] Error copiando hooks: ${err.message}`);
+    return { resultado: 'error', detalle: `No se pudieron copiar los hooks globales: ${err.message}` };
+  }
+
+  // Crear directorio si no existe
+  if (!fs.existsSync(DIR_NOTIFICACIONES)) {
+    fs.mkdirSync(DIR_NOTIFICACIONES, { recursive: true });
+  }
+
+  // Respaldar .env preexistente ANTES de sobreescribir (REM-2)
+  // Protege contra el incidente del 2026-04-24 donde init() sobreescribió
+  // credenciales válidas durante una validación manual del flujo.
+  const backupRes = _respaldarEnvExistente(envPath);
+  if (!backupRes.ok) {
+    console.error(`  ! [notificaciones] Advertencia: no se pudo crear backup del .env: ${backupRes.error}`);
+    // No es fatal — continuamos con la escritura
+  } else if (backupRes.rutaBackup) {
+    console.log(`  [notificaciones] Backup del .env anterior: ${backupRes.rutaBackup}`);
+  }
+
+  // Escribir .env — atómico, con permisos 0o600 aplicados desde la creación (REM-1)
+  // Elimina la race condition entre escritura y chmod posterior.
+  const contenidoEnv = _generarContenidoEnv(token, chatId);
+  atomicWriteSync(envPath, contenidoEnv, 'utf8', { mode: 0o600 });
+
+  console.log(`  [notificaciones] Token configurado: ${_ocultarToken(token)}`);
+  console.log(`  [notificaciones] Chat ID configurado: ${chatId.slice(0, -4).replace(/./g, '*')}${chatId.slice(-4)}`);
+  console.log(`  [notificaciones] .env escrito en: ${envPath}`);
+
+  // Generar baseline-hooks.json — REM-B: siempre usa path absoluto a ~/.claude/hooks/
+  const baseline = _generarBaselineHooks(_hooksGlobalDirOverride);
+  atomicWriteJSON(RUTA_BASELINE, baseline);
+  console.log(`  [notificaciones] baseline-hooks.json escrito en: ${RUTA_BASELINE}`);
+
+  // Merge en settings global
+  const mergeResult = await _soloMergeSettings(_hooksGlobalDirOverride, false, _settingsPathOverride);
+  if (mergeResult.resultado === 'error') {
+    return mergeResult;
+  }
+
+  return {
+    resultado: 'completado',
+    detalle:   `token=${_ocultarToken(token)}, chatId configurado, baseline y settings actualizados`,
+  };
+}
+
+/**
+ * Hace el merge de hooks SWL en settings global sin tocar el .env.
+ * Usado cuando el .env ya existe y solo se necesita restaurar la entrada en settings.
+ *
+ * @param {string|null} hooksGlobalDirOverride  - Override de directorio para tests; si null usa HOOKS_GLOBAL_DIR.
+ * @param {boolean}     dryRun
+ * @param {string|null} settingsPathOverride    - EXCLUSIVO para tests: sobreescribir ruta del settings.json.
+ *   En producción, pasar null (usa RUTA_SETTINGS_GLOBAL). El guion bajo en los llamadores
+ *   señala que es parámetro de test únicamente.
+ * @returns {Promise<{ resultado: string, detalle?: string }>}
+ */
+async function _soloMergeSettings(hooksGlobalDirOverride, dryRun, settingsPathOverride) {
+  const settingsPath = settingsPathOverride || RUTA_SETTINGS_GLOBAL;
+
+  if (dryRun) {
+    console.log(`  [dry-run] MERGE  ${settingsPath} (backup antes de modificar)`);
+    return { resultado: 'omitido', detalle: 'dry-run: merge de settings no aplicado' };
+  }
+
+  // REM-B: siempre usar directorio global absoluto — nunca ruta relativa
+  const hooksDir = hooksGlobalDirOverride || HOOKS_GLOBAL_DIR;
+
+  try {
+    const entries = HOOKS_SWL_NOTIFICACIONES.map(h => ({
+      evento:   h.evento,
+      matcher:  h.matcher,
+      archivo:  h.archivo,
+      hooksDir: hooksDir,
+    }));
+
+    const res = hooksSettings.mergeHooksGlobales(settingsPath, entries);
+    if (res.error) {
+      console.error(`  ! [notificaciones] Error en merge de settings: ${res.error}`);
+      return { resultado: 'error', detalle: res.error };
+    }
+    const detalleMigrados = res.migrados > 0 ? `, ${res.migrados} migrados a ruta absoluta` : '';
+    console.log(`  [notificaciones] settings.json global actualizado (${res.agregados} hook(s) agregados${detalleMigrados}, ${res.preservados} preservados).`);
+    return { resultado: 'completado', detalle: `settings actualizado (${res.agregados} hooks)` };
+  } catch (err) {
+    console.error(`  ! [notificaciones] Error inesperado en merge de settings: ${err.message}`);
+    return { resultado: 'error', detalle: err.message };
+  }
+}
+
+/**
+ * Retorna el estado actual de la configuración de notificaciones.
+ * NUNCA incluye el valor del token — solo metadata.
+ *
+ * @returns {object}
+ */
+function status() {
+  const envExiste = fs.existsSync(RUTA_ENV);
+  let tokenConfigurado = false;
+  let chatIdConfigurado = false;
+  let chatIdParcial = null;
+  let proyectosSilenciados = [];
+
+  if (envExiste) {
+    try {
+      const contenido = fs.readFileSync(RUTA_ENV, 'utf8');
+      for (const linea of contenido.split(/\r?\n/)) {
+        const recortada = linea.trim();
+        if (!recortada || recortada.startsWith('#')) continue;
+        const posIgual = recortada.indexOf('=');
+        if (posIgual === -1) continue;
+        const nombre = recortada.slice(0, posIgual).trim();
+        const valor  = recortada.slice(posIgual + 1).trim().replace(/^["']|["']$/g, '');
+        if (nombre === 'TELEGRAM_BOT_TOKEN' && valor) {
+          tokenConfigurado = true;
+          // NUNCA incluir el token en el retorno
+        }
+        if (nombre === 'TELEGRAM_CHAT_ID' && valor) {
+          chatIdConfigurado = true;
+          // Solo últimos 4 dígitos
+          chatIdParcial = valor.length > 4
+            ? '...' + valor.slice(-4)
+            : valor;
+        }
+      }
+    } catch (_) {
+      // Si no se puede leer, dejar flags en false
+    }
+  }
+
+  // Leer proyectos silenciados
+  const rutaMuted = path.join(DIR_NOTIFICACIONES, 'muted.json');
+  try {
+    if (fs.existsSync(rutaMuted)) {
+      const muted = JSON.parse(fs.readFileSync(rutaMuted, 'utf8'));
+      if (Array.isArray(muted)) proyectosSilenciados = muted;
+    }
+  } catch (_) { /* muted.json corrupto — ignorar */ }
+
+  return {
+    envExiste,
+    tokenConfigurado,
+    chatIdConfigurado,
+    chatIdParcial,       // últimos 4 dígitos o null
+    proyectosSilenciados,
+    // Campos reservados para Slices futuros
+    botDaemonActivo:     null,  // Slice 006
+    autostartInstalado:  null,  // Slice 008
+  };
+}
+
+/**
+ * Deshabilita las notificaciones Telegram:
+ *   - Quita entries SWL de ~/.claude/settings.json (preserva ajenos)
+ *   - Si conservarEnv=false, elimina el .env
+ *   - NO detiene el daemon (Slice 006)
+ *
+ * @param {object} [opciones]
+ * @param {boolean} [opciones.confirmar=false]            - Si ya se confirmó por UI.
+ * @param {boolean} [opciones.conservarEnv=true]          - Si conservar el .env.
+ * @param {string|null} [opciones._settingsPathOverride]  - EXCLUSIVO para tests: ruta alternativa del settings.json.
+ * @param {string|null} [opciones._envPathOverride]       - EXCLUSIVO para tests: ruta alternativa del .env.
+ *   El prefijo _ señala que es parámetro de test — producción NUNCA lo pasa. (Fix v5.12.2)
+ * @returns {{ resultado: string, detalle?: string }}
+ */
+function disable(opciones = {}) {
+  const {
+    confirmar              = false,
+    conservarEnv           = true,
+    _settingsPathOverride  = null,  // EXCLUSIVO para tests — ver Fix Slice 015-B
+    _envPathOverride       = null,  // EXCLUSIVO para tests — ver Fix v5.12.2
+  } = opciones;
+
+  if (!confirmar) {
+    return {
+      resultado: 'error',
+      detalle:   'Se requiere confirmar (pasar confirmar: true). Ejecuta /swl:notificaciones disable para el flujo interactivo.',
+    };
+  }
+
+  const settingsPath = _settingsPathOverride || RUTA_SETTINGS_GLOBAL;
+  const envPath      = _envPathOverride      || RUTA_ENV;
+
+  // Quitar entries SWL del settings global
+  try {
+    const res = hooksSettings.desregistrarHooksGlobales(settingsPath);
+    console.log(`  [notificaciones] ${res.eliminados} hook(s) SWL eliminados de settings.json (${res.preservados} preservados).`);
+  } catch (err) {
+    console.error(`  ! [notificaciones] Error al quitar hooks: ${err.message}`);
+    return { resultado: 'error', detalle: err.message };
+  }
+
+  // Eliminar .env si se pide
+  if (!conservarEnv && fs.existsSync(envPath)) {
+    try {
+      fs.unlinkSync(envPath);
+      console.log(`  [notificaciones] .env eliminado.`);
+    } catch (err) {
+      console.error(`  ! [notificaciones] No se pudo eliminar .env: ${err.message}`);
+    }
+  }
+
+  return { resultado: 'completado', detalle: 'hooks removidos de settings global' };
+}
+
+// ---------------------------------------------------------------------------
+// Gestión del daemon bidireccional (bot.*)
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee el PID almacenado en el archivo de PID del daemon.
+ * Retorna null si no existe o no es un número válido.
+ *
+ * @returns {number|null}
+ */
+function _leerPid() {
+  try {
+    if (!fs.existsSync(RUTA_PID_DAEMON)) return null;
+    const contenido = fs.readFileSync(RUTA_PID_DAEMON, 'utf8').trim();
+    const pid = parseInt(contenido, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Verifica si un proceso con el PID dado está activo.
+ * Usa `process.kill(pid, 0)` que lanza si el proceso no existe.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function _procesoActivo(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Retorna si el daemon del bot está activo según el archivo PID.
+ *
+ * @returns {{ activo: boolean, pid: number|null }}
+ */
+function botStatus() {
+  const pid = _leerPid();
+  const activo = _procesoActivo(pid);
+
+  // Limpiar PID obsoleto si el proceso ya no existe
+  if (pid && !activo) {
+    try { fs.unlinkSync(RUTA_PID_DAEMON); } catch (_) {}
+  }
+
+  return { activo, pid: activo ? pid : null };
+}
+
+/**
+ * Inicia el daemon del bot en background.
+ *
+ * El daemon se inicia desacoplado del proceso actual (detached: true, stdio: 'ignore')
+ * para que sobreviva al cierre del proceso padre. El PID se escribe en bot.pid.
+ *
+ * @returns {{ ok: boolean, mensaje?: string, error?: string, pid?: number }}
+ */
+function botStart() {
+  // Verificar que el binario existe
+  if (!fs.existsSync(RUTA_BIN_DAEMON)) {
+    return { ok: false, error: `El daemon no existe: ${RUTA_BIN_DAEMON}` };
+  }
+
+  // Verificar que no está ya corriendo
+  const { activo, pid: pidExistente } = botStatus();
+  if (activo) {
+    return { ok: true, mensaje: `El bot ya está corriendo (PID ${pidExistente}).` };
+  }
+
+  // Crear directorio de logs si no existe
+  try {
+    if (!fs.existsSync(DIR_NOTIFICACIONES)) {
+      fs.mkdirSync(DIR_NOTIFICACIONES, { recursive: true });
+    }
+  } catch (err) {
+    return { ok: false, error: `No se pudo crear directorio de logs: ${err.message}` };
+  }
+
+  // Iniciar el proceso desacoplado
+  let child;
+  try {
+    const stdoutLog = path.join(DIR_NOTIFICACIONES, 'bot.stdout.log');
+    const stderrLog = path.join(DIR_NOTIFICACIONES, 'bot.stderr.log');
+    const outFd     = fs.openSync(stdoutLog, 'a');
+    const errFd     = fs.openSync(stderrLog, 'a');
+
+    const { spawn } = require('node:child_process');
+    child = spawn(process.execPath, [RUTA_BIN_DAEMON], {
+      detached: true,
+      stdio:    ['ignore', outFd, errFd],
+    });
+    child.unref();
+    fs.closeSync(outFd);
+    fs.closeSync(errFd);
+  } catch (err) {
+    return { ok: false, error: `No se pudo iniciar el daemon: ${err.message}` };
+  }
+
+  const pid = child.pid;
+
+  // Escribir el PID en archivo
+  try {
+    fs.writeFileSync(RUTA_PID_DAEMON, String(pid), 'utf8');
+  } catch (err) {
+    return { ok: false, error: `Daemon iniciado (PID ${pid}) pero no se pudo escribir bot.pid: ${err.message}` };
+  }
+
+  return { ok: true, mensaje: `Bot iniciado (PID ${pid}).`, pid };
+}
+
+/**
+ * Detiene el daemon del bot enviando SIGTERM al PID almacenado.
+ * Elimina el archivo bot.pid al terminar.
+ *
+ * @returns {{ ok: boolean, mensaje?: string, error?: string }}
+ */
+function botStop() {
+  const { activo, pid } = botStatus();
+
+  if (!activo || !pid) {
+    return { ok: true, mensaje: 'El bot no estaba corriendo.' };
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (err) {
+    return { ok: false, error: `No se pudo detener el proceso (PID ${pid}): ${err.message}` };
+  }
+
+  // Eliminar el archivo PID
+  try {
+    if (fs.existsSync(RUTA_PID_DAEMON)) {
+      fs.unlinkSync(RUTA_PID_DAEMON);
+    }
+  } catch (_) {
+    // No es fatal si no se puede eliminar el PID
+  }
+
+  return { ok: true, mensaje: `Bot detenido (PID ${pid}).` };
+}
+
+/**
+ * Reinicia el daemon: detiene si está corriendo y lo vuelve a iniciar.
+ *
+ * @returns {{ ok: boolean, mensaje?: string, error?: string, pid?: number }}
+ */
+function botRestart() {
+  const stopRes = botStop();
+  if (!stopRes.ok) {
+    return stopRes;
+  }
+
+  // Pequeña espera síncrona para que el proceso termine de limpiar recursos
+  // Usar un loop de spin corto sin setTimeout (tests deterministas)
+  const inicio = Date.now();
+  while (Date.now() - inicio < 500) {
+    const { activo } = botStatus();
+    if (!activo) break;
+  }
+
+  return botStart();
+}
+
+/**
+ * Despacha la instalación del autostart al módulo del OS correspondiente.
+ *
+ * @returns {{ ok: boolean, mensaje?: string, error?: string }}
+ */
+function botEnableAutostart() {
+  const platform = process.platform;
+
+  if (platform === 'win32') {
+    const { install } = require('./autostart-windows');
+    return install();
+  }
+  if (platform === 'linux') {
+    const { install } = require('./autostart-linux');
+    return install();
+  }
+  if (platform === 'darwin') {
+    const { install } = require('./autostart-macos');
+    return install();
+  }
+
+  return {
+    ok:    false,
+    error: `Plataforma no soportada para autostart: ${platform}. Soportadas: win32, linux, darwin.`,
+  };
+}
+
+/**
+ * Despacha la desinstalación del autostart al módulo del OS correspondiente.
+ *
+ * @returns {{ ok: boolean, mensaje?: string, error?: string }}
+ */
+function botDisableAutostart() {
+  const platform = process.platform;
+
+  if (platform === 'win32') {
+    const { uninstall } = require('./autostart-windows');
+    return uninstall();
+  }
+  if (platform === 'linux') {
+    const { uninstall } = require('./autostart-linux');
+    return uninstall();
+  }
+  if (platform === 'darwin') {
+    const { uninstall } = require('./autostart-macos');
+    return uninstall();
+  }
+
+  return {
+    ok:    false,
+    error: `Plataforma no soportada para autostart: ${platform}. Soportadas: win32, linux, darwin.`,
+  };
+}
+
+/**
+ * Repara una instalación rota de hooks de Telegram.
+ *
+ * Ejecuta dos acciones correctivas:
+ *   1. Re-copia los 7 archivos de hook a ~/.claude/hooks/ (idempotente).
+ *   2. Llama a _soloMergeSettings() que invoca mergeHooksGlobales con el
+ *      mecanismo de migración REM-C: detecta entradas con ruta relativa del
+ *      mismo hook y las reemplaza por la ruta absoluta sin duplicar.
+ *
+ * Diseñado para usuarios que activaron notificaciones antes de v5.12.0 y
+ * tienen entradas como `node hooks/notificacion-telegram.js` en settings.json.
+ *
+ * @param {object} opciones
+ * @param {string}  [opciones._hooksOrigenOverride]    - Override para tests.
+ * @param {string}  [opciones._hooksGlobalDirOverride] - Override para tests.
+ * @param {string|null} [opciones._settingsPathOverride] - EXCLUSIVO para tests: ruta alternativa del settings.json.
+ * @param {string|null} [opciones._envPathOverride]      - EXCLUSIVO para tests: ruta alternativa del .env.
+ *   repair() actualmente no escribe el .env (solo re-copia hooks y merge settings),
+ *   pero el parámetro se acepta para uniformidad con init()/disable() y tests futuros.
+ *   (Fix v5.12.2)
+ * @returns {Promise<{ resultado: string, detalle?: string }>}
+ */
+async function repair(opciones = {}) {
+  const {
+    _hooksOrigenOverride:    _hooksOrigenOverride    = null,
+    _hooksGlobalDirOverride: _hooksGlobalDirOverride = null,
+    _settingsPathOverride:   _settingsPathOverride   = null,  // EXCLUSIVO para tests — ver Fix Slice 015-B
+    // _envPathOverride aceptado por uniformidad — repair no escribe .env actualmente
+    // eslint-disable-next-line no-unused-vars
+    _envPathOverride:        _envPathOverride        = null,  // EXCLUSIVO para tests — ver Fix v5.12.2
+  } = opciones;
+
+  console.log('  [notificaciones] Iniciando reparación de hooks...');
+
+  // Paso 1: re-copiar hooks
+  try {
+    const copiaRes = _copiarHooksGlobales(_hooksOrigenOverride, _hooksGlobalDirOverride);
+    console.log(`  [notificaciones] ${copiaRes.archivos.length} hook(s) copiados a: ${copiaRes.directorio}`);
+  } catch (err) {
+    console.error(`  ! [notificaciones] Error copiando hooks: ${err.message}`);
+    return { resultado: 'error', detalle: `No se pudieron copiar los hooks: ${err.message}` };
+  }
+
+  // Paso 2: merge/migrar entradas en settings.json (REM-C: relativo → absoluto)
+  const mergeResult = await _soloMergeSettings(_hooksGlobalDirOverride, false, _settingsPathOverride);
+  if (mergeResult.resultado === 'error') {
+    return mergeResult;
+  }
+
+  console.log('  [notificaciones] Reparación completada. Hooks registrados con rutas absolutas.');
+  return {
+    resultado: 'completado',
+    detalle: 'hooks copiados y settings migrados a rutas absolutas',
+  };
+}
+
+module.exports = {
+  init,
+  repair,
+  status,
+  disable,
+  leerCredencialesInteractivo,
+  // API del daemon
+  botStart,
+  botStop,
+  botStatus,
+  botRestart,
+  botEnableAutostart,
+  botDisableAutostart,
+  // Exportar para tests
+  _esRutaSegura,
+  _ocultarToken,
+  _generarContenidoEnv,
+  _generarBaselineHooks,
+  _copiarHooksGlobales,
+  _leerPid,
+  _procesoActivo,
+  _validarFormatoToken,
+  _validarFormatoChatId,
+  _respaldarEnvExistente,
+  RUTA_ENV,
+  RUTA_BASELINE,
+  RUTA_SETTINGS_GLOBAL,
+  DIR_NOTIFICACIONES,
+  RUTA_PID_DAEMON,
+  RUTA_BIN_DAEMON,
+  HOOKS_GLOBAL_DIR,
+  HOOKS_A_COPIAR,
+};