@saulwade/swl-ses 2.5.2 → 2.6.0

package/hooks/lib/merkle-audit.js

@@ -18,8 +18,34 @@
 const crypto = require('crypto');
 const fs     = require('fs');
 
-function _sha256(data) {
-  return crypto.createHash('sha256').update(data).digest('hex');
+/**
+ * Hash de cada entrada de la cadena. Si `SWL_AUDIT_HMAC_KEY` está definida, usa
+ * HMAC-SHA256 con esa clave; si no, SHA256 plano (default zero-config).
+ *
+ * MODELO DE AMENAZA (resuelve el residual "SHA256 sin clave"):
+ *  - SIN clave (default): la cadena es tamper-EVIDENTE ante corrupción
+ *    accidental (escrituras parciales, error de disco, edición por una
+ *    herramienta buggy) y ediciones parciales. NO defiende contra quien tenga
+ *    acceso de escritura Y pueda recomputar hashes — pero en una máquina local
+ *    de un solo usuario ESE es el dueño, que es la raíz de confianza: no hay
+ *    adversario distinto del dueño. Correcto por diseño para audit local.
+ *  - CON clave en env (opt-in): defiende contra un adversario a nivel de
+ *    ARCHIVO —dependencia npm maliciosa, ransomware, conflicto de sync— que
+ *    puede escribir `.planning/` pero NO leer el entorno del proceso del hook.
+ *    Sin la clave del env no puede forjar HMACs válidos → la manipulación se
+ *    detecta. NO defiende contra quien lea el env del proceso (el dueño);
+ *    para eso hace falta anclaje externo (publicar el último hash en un store
+ *    append-only inmutable), fuera del alcance de este módulo.
+ *  - La clave vive en el ENV (no en disco): `setx SWL_AUDIT_HMAC_KEY <valor>`
+ *    o export. Cambiar la clave inicia una época nueva e invalida cadenas
+ *    previas (esperado). Cargar la clave desde el env en cada llamada para
+ *    respetar rotación sin reiniciar procesos de larga vida.
+ */
+function _hash(data) {
+  const clave = process.env.SWL_AUDIT_HMAC_KEY;
+  return clave
+    ? crypto.createHmac('sha256', clave).update(data).digest('hex')
+    : crypto.createHash('sha256').update(data).digest('hex');
 }
 
 function crearEntrada(datos, hashAnterior) {
@@ -32,7 +58,7 @@ function crearEntrada(datos, hashAnterior) {
     result: datos.result || 'ok',
     prev: hashAnterior,
   });
-  const hash = _sha256(payload);
+  const hash = _hash(payload);
   return { payload, hash };
 }
 
@@ -56,12 +82,38 @@ function appendAudit(rutaArchivo, datos) {
   return hash;
 }
 
-function verificarCadena(rutaArchivo) {
+/**
+ * Verifica la integridad de la cadena Merkle de un archivo de auditoría.
+ *
+ * @param {string} rutaArchivo
+ * @param {object} [opts]
+ * @param {string} [opts.hashInicial] - Hash del que la cadena continúa. Por
+ *   defecto el génesis ('0'*64). Tras una rotación, el archivo activo empieza
+ *   en una entrada cuyo `prev` apunta a una entrada ya archivada (no al
+ *   génesis) — pasar aquí el `hashInicial` del checkpoint
+ *   (`.checkpoint-<archivo>.json`) para validar el activo como CONTINUACIÓN de
+ *   la cadena archivada, sin falso positivo de rotura (nemesis iter-1 S3-5).
+ *
+ *   LÍMITE (re-auditoría nemesis iter-2): con `hashInicial` esto prueba la
+ *   consistencia INTERNA del activo, NO que continúe la cadena archivada — el
+ *   check `prev===hashInicial` de la entrada-0 es tautológico si `hashInicial`
+ *   viene del propio checkpoint auto-derivado. Un consumidor que quiera probar
+ *   la continuidad archivo↔activo debe recomputar independientemente el hash de
+ *   la última entrada del `.gz` archivado y verificar que coincide con
+ *   `hashInicial`. La fuerza criptográfica de la cadena depende de `_hash`
+ *   (ver su docstring): SHA256 plano (accidental) o HMAC con `SWL_AUDIT_HMAC_KEY`
+ *   (defensa contra manipulación a nivel de archivo sin la clave del env).
+ *   verificarCadena usa la MISMA función `_hash`, así que recomputa con la
+ *   clave activa del env — verificar con la clave con que se escribió.
+ */
+function verificarCadena(rutaArchivo, opts = {}) {
   if (!fs.existsSync(rutaArchivo)) return { valido: true, entradas: 0 };
 
   const contenido = fs.readFileSync(rutaArchivo, 'utf8').trim();
   const lineas = contenido.split('\n').filter(Boolean);
-  let hashEsperado = '0'.repeat(64);
+  let hashEsperado = (typeof opts.hashInicial === 'string' && opts.hashInicial)
+    ? opts.hashInicial
+    : '0'.repeat(64);
   let roturaEn = -1;
 
   for (let i = 0; i < lineas.length; i++) {
@@ -73,7 +125,7 @@ function verificarCadena(rutaArchivo) {
       }
       const { hash: storedHash, ...resto } = entrada;
       const payloadRecalc = JSON.stringify(resto);
-      const hashRecalc = _sha256(payloadRecalc);
+      const hashRecalc = _hash(payloadRecalc);
       if (hashRecalc !== storedHash) {
         roturaEn = i;
         break;

package/hooks/lib/nudge-tracker.js

@@ -22,6 +22,7 @@
  */
 
 const fs   = require('fs');
+const { raizProyecto } = require('./raiz-proyecto');
 const path = require('path');
 
 // Escritura atómica para reescritura completa del JSONL (marcar accionado).
@@ -45,7 +46,7 @@ try {
 // Configuración
 // ---------------------------------------------------------------------------
 
-const DIR_EVOL = path.join(process.cwd(), '.planning', 'evolution');
+const DIR_EVOL = path.join(raizProyecto(process.cwd()), '.planning', 'evolution');
 const LOG_PATH = path.join(DIR_EVOL, 'nudges.jsonl');
 const ALERT_PATH = path.join(DIR_EVOL, 'alertas-persistentes.json');
 

package/hooks/lib/otlp-exporter.js

@@ -19,6 +19,7 @@
  */
 
 const fs     = require('fs');
+const { raizProyecto } = require('./raiz-proyecto');
 const path   = require('path');
 const crypto = require('crypto');
 const http   = require('http');
@@ -277,7 +278,7 @@ class OtlpLocalProcessor extends TracingProcessor {
   constructor(cwd) {
     super();
     /** @type {string} */
-    this._cwd = String(cwd || process.cwd());
+    this._cwd = String(cwd || raizProyecto(process.cwd()));
   }
 
   /**

package/hooks/lib/propose-step.js

@@ -20,6 +20,7 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./raiz-proyecto');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
@@ -209,7 +210,7 @@ const UMBRAL = {
 };
 
 function telemetriaPath(baseDir) {
-  return path.join(baseDir || process.cwd(), ...TELE_PATH);
+  return path.join(baseDir || raizProyecto(process.cwd()), ...TELE_PATH);
 }
 
 function _catVacia() {
@@ -332,7 +333,7 @@ function main(argv) {
   for (const a of args) {
     if (a.startsWith('--rango=')) rango = a.slice('--rango='.length);
   }
-  const baseDir = process.cwd();
+  const baseDir = raizProyecto(process.cwd());
   const { paths, diff } = _gitDiff(rango);
   const { señales } = evaluarSenales(paths, diff);
   registrarPropose(baseDir, señales);

package/hooks/lib/raiz-proyecto.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * raiz-proyecto.js — Resolución de la raíz del proyecto para hooks que
+ * escriben telemetría/memoria en `.planning/`.
+ *
+ * El CWD de arranque de una sesión NO es la frontera del proyecto: en un
+ * monorepo con sesiones abiertas en subdirectorios (`backend/`, `frontend/`),
+ * anclar `.planning/` a `process.cwd()` fragmenta la memoria del proyecto en
+ * árboles huérfanos (DT-HOOKS-RAIZ-GIT; misma clase que el fix de
+ * proteccion-rutas). La frontera correcta es la raíz del repositorio git,
+ * con una excepción: un sub-proyecto anidado que ya tiene su propio
+ * `.planning/` REAL (con marcadores de proyecto) conserva su árbol local.
+ *
+ * Reglas de resolución (en orden):
+ *   1. Ascendiendo desde `desde`, el primer directorio cuyo `.planning/`
+ *      contiene un marcador de proyecto (PROYECTO.md, HOJA-RUTA.md,
+ *      ESTADO.md) gana — respeta sub-proyectos legítimos en monorepos.
+ *      Un `.planning/` sin marcadores (solo telemetría huérfana de hooks)
+ *      NO cuenta: eso es el síntoma del bug, no un proyecto.
+ *   2. Si ningún nivel tiene `.planning/` real, gana la raíz del repo git
+ *      (`.git` como directorio o como archivo — worktrees).
+ *   3. Sin `.git` alcanzable: fallback al propio `desde`.
+ *
+ * La ascensión se detiene en el HOME del usuario (sin incluirlo) cuando se
+ * llega ahí subiendo: un dotfiles-repo en `~` no debe capturar la memoria
+ * de un proyecto sin git que viva debajo.
+ *
+ * Zero-deps (regla de hooks/lib/). Consumidor inicial:
+ * hooks/extraccion-aprendizajes.js; la flota completa migró el 2026-07-10
+ * (cierre de DT-HOOKS-RAIZ-GIT).
+ *
+ * LÍMITE DE USO (hallazgo revisor-seguridad 2026-07-10): esta ancla es SOLO
+ * para DATOS (.planning/, instintos/, lecturas de config del proyecto).
+ * NUNCA resolver con ella EJECUTABLES ni módulos a require()/spawn(): la
+ * raíz resuelta pertenece al árbol del proyecto, y un repositorio no
+ * confiable puede plantar el script (marcador .planning/PROYECTO.md +
+ * scripts/x.js hostil = ejecución de código al disparar el hook). Los
+ * ejecutables de la distribución SWL se resuelven desde __dirname
+ * (ubicación instalada del hook). Test guardián:
+ * tests/hooks/ejecutables-desde-instalacion.test.js.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const MARCADORES_PROYECTO = ['PROYECTO.md', 'HOJA-RUTA.md', 'ESTADO.md'];
+const MAX_NIVELES = 40;
+
+/**
+ * ¿El directorio tiene un `.planning/` de proyecto real (no huérfano)?
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function tienePlanningReal(dir) {
+  try {
+    return MARCADORES_PROYECTO.some(m =>
+      fs.existsSync(path.join(dir, '.planning', m))
+    );
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Resuelve la raíz del proyecto a la que deben anclarse las escrituras
+ * de `.planning/`.
+ *
+ * @param {string} [desde] - Directorio de partida (default: process.cwd()).
+ * @returns {string} Ruta absoluta de la raíz del proyecto.
+ */
+function raizProyecto(desde) {
+  const inicio = path.resolve(desde || process.cwd());
+  let actual = inicio;
+  let homedir = null;
+  try {
+    homedir = path.resolve(os.homedir());
+  } catch (_) { /* sin home resolvible — seguir sin el guard */ }
+
+  for (let i = 0; i < MAX_NIVELES; i++) {
+    // Frontera del HOME: si llegamos aquí ASCENDIENDO, no seguir — un
+    // dotfiles-repo en ~ no es la raíz de un proyecto que vive debajo.
+    if (homedir && actual === homedir && i > 0) break;
+
+    if (tienePlanningReal(actual)) return actual;
+
+    try {
+      if (fs.existsSync(path.join(actual, '.git'))) return actual;
+    } catch (_) {
+      break;
+    }
+
+    const padre = path.dirname(actual);
+    if (padre === actual) break; // raíz del filesystem
+    actual = padre;
+  }
+
+  return inicio;
+}
+
+module.exports = { raizProyecto, tienePlanningReal };

package/hooks/lib/run-log.js

@@ -38,6 +38,7 @@
  */
 
 const fs      = require('fs');
+const { raizProyecto } = require('./raiz-proyecto');
 const path    = require('path');
 const readline = require('readline');
 const os      = require('os');
@@ -50,7 +51,7 @@ const os      = require('os');
  * Directorio donde se almacenan los JSONL de runs.
  * Relativo al cwd del proceso (raíz del proyecto SWL).
  */
-const RUNS_DIR = path.join(process.cwd(), '.planning', 'runs');
+const RUNS_DIR = path.join(raizProyecto(process.cwd()), '.planning', 'runs');
 
 /**
  * Número máximo de runs a mantener por directorio.

package/hooks/lib/singleton-guard.js

@@ -25,9 +25,10 @@
  */
 
 const fs = require('fs');
+const { raizProyecto } = require('./raiz-proyecto');
 const path = require('path');
 
-const DIR_LOCKS = path.join(process.cwd(), '.planning', 'locks');
+const DIR_LOCKS = path.join(raizProyecto(process.cwd()), '.planning', 'locks');
 const STALE_MS_DEFAULT = 5 * 60 * 1000; // 5 minutos
 const locksAdquiridos = new Set();
 let handlersRegistrados = false;
@@ -59,8 +60,58 @@ function pidVivo(pid) {
 }
 
 /**
- * Intenta adquirir el lock. Retorna true si se adquirió, false si otro
- * proceso lo tiene activo.
+ * Escribe el lockfile con exclusión atómica (O_EXCL vía flag 'wx'): falla con
+ * EEXIST si el archivo ya existe, sin ventana check-then-write. Es lo que
+ * garantiza la exclusión mutua real entre DOS procesos simultáneos —
+ * fs.existsSync + fs.writeFileSync NO la garantiza (ambos ven no-existe y
+ * ambos escriben; hallazgo re-auditoría nemesis iter-2).
+ *
+ * @param {string} ruta
+ * @param {string} nombre
+ * @returns {boolean} true si este proceso creó el lock.
+ */
+function crearLockExclusivo(ruta, nombre) {
+  try {
+    const fd = fs.openSync(ruta, 'wx'); // O_CREAT | O_EXCL | O_WRONLY
+    try {
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, ts: new Date().toISOString(), nombre }));
+    } finally {
+      fs.closeSync(fd);
+    }
+    return true;
+  } catch (err) {
+    if (err.code === 'EEXIST') return false;
+    return false;
+  }
+}
+
+/**
+ * ¿Un CONTENIDO de lock ya leído es tomable? (proceso muerto, edad > staleMs,
+ * o contenido corrupto/nulo). Trabaja sobre el objeto, no re-lee el archivo —
+ * clave para el takeover: la decisión de remover se toma sobre el MISMO
+ * contenido que se acaba de leer bajo el guard, sin un segundo read que
+ * reintroduzca TOCTOU.
+ * @returns {boolean}
+ */
+function contenidoTomable(contenido, staleMs) {
+  if (!contenido || typeof contenido.pid === 'undefined') return true; // corrupto/nulo → tomable
+  const edad = Date.now() - Date.parse(contenido.ts);
+  const vivo = pidVivo(contenido.pid);
+  return !(vivo && edad < staleMs);
+}
+
+/**
+ * ¿El lock existente (en disco) es tomable? Lee el archivo y delega en
+ * contenidoTomable.
+ * @returns {boolean}
+ */
+function lockTomable(ruta, staleMs) {
+  return contenidoTomable(leerLock(ruta), staleMs);
+}
+
+/**
+ * Intenta adquirir el lock con exclusión ATÓMICA (O_EXCL). Retorna true si se
+ * adquirió, false si otro proceso lo tiene activo.
  *
  * @param {string} nombre - Identificador del lock (ej: 'auto-evolucion').
  * @param {object} [opts]
@@ -72,38 +123,113 @@ function adquirir(nombre, opts = {}) {
   ensureDir();
   const ruta = rutaLock(nombre);
 
-  // Verificar lock existente
-  if (fs.existsSync(ruta)) {
-    try {
-      const contenido = JSON.parse(fs.readFileSync(ruta, 'utf8'));
-      const edad = Date.now() - Date.parse(contenido.ts);
-      const vivo = pidVivo(contenido.pid);
+  // Caso primario: crear el lock de forma atómica. Dos procesos frescos
+  // simultáneos sobre un lock inexistente → solo UNO gana el O_EXCL.
+  if (crearLockExclusivo(ruta, nombre)) {
+    locksAdquiridos.add(nombre);
+    registrarHandlersCleanup();
+    return true;
+  }
 
-      if (vivo && edad < staleMs) {
-        // Lock activo y proceso vivo → no adquirir
-        return false;
-      }
-      // Lock stale o proceso muerto → tomar posesión
-    } catch {
-      // Lock corrupto → sobrescribir
+  // El lock existe. Si parece tomable (muerto/stale/corrupto), removerlo de
+  // forma SERIALIZADA (ver takeoverStaleSerializado) y reintentar el O_EXCL.
+  if (lockTomable(ruta, staleMs)) {
+    takeoverStaleSerializado(ruta, staleMs);
+    if (crearLockExclusivo(ruta, nombre)) {
+      locksAdquiridos.add(nombre);
+      registrarHandlersCleanup();
+      return true;
     }
   }
 
-  // Escribir lock con PID actual
+  return false;
+}
+
+/** Lee el contenido {pid, ts} del lock, o null si no existe/corrupto. */
+function leerLock(ruta) {
   try {
-    fs.writeFileSync(ruta, JSON.stringify({
-      pid: process.pid,
-      ts: new Date().toISOString(),
-      nombre,
-    }), 'utf8');
-    locksAdquiridos.add(nombre);
-    registrarHandlersCleanup();
-    return true;
+    return JSON.parse(fs.readFileSync(ruta, 'utf8'));
   } catch {
-    return false;
+    return null;
   }
 }
 
+// Un token de takeover se considera leaked (dueño muerto a mitad) si supera
+// esto: la sección crítica del takeover es de µs, así que segundos = fuga.
+const TAKEOVER_TOKEN_STALE_MS = 5000;
+
+/**
+ * Remueve un lock stale de forma SERIALIZADA y sin ventana de create fresco.
+ *
+ * La clase de bug que dos rondas de re-auditoría destaparon: cualquier diseño
+ * que "saque" el stale del path (unlink ciego, rename-out) abre una ventana en
+ * la que `ruta` queda libre y un proceso fresco puede colarse con O_EXCL, y
+ * luego el remover restaura/recrea encima → DOS holders. El fix de CLASE:
+ *
+ * 1. Serializar el takeover con un token O_EXCL (`<ruta>.takeover`): solo UN
+ *    taker entra a la sección crítica; los demás salen (otro lo maneja).
+ * 2. Dentro del token, re-leer `ruta` y `unlinkSync` SOLO si sigue tomable
+ *    (muerto/stale/corrupto). `ruta` está PRESENTE hasta ese unlink → ningún
+ *    create fresco puede colarse antes (falla EEXIST). Si el contenido pasó a
+ *    ser un lock VIVO distinto (otro tomó posesión legítima), NO se toca.
+ *
+ * Tras esto, el `crearLockExclusivo` del caller compite limpio por O_EXCL: si
+ * un proceso fresco ganó la ventana unlink→create, el caller falla EEXIST en
+ * vez de clobberear. Nunca dos holders.
+ *
+ * El token puede quedar leaked si el taker muere a mitad; se reclama por edad
+ * (>TAKEOVER_TOKEN_STALE_MS), acotando el bloqueo a segundos.
+ *
+ * @param {string} ruta
+ * @param {number} staleMs
+ */
+function takeoverStaleSerializado(ruta, staleMs) {
+  const token = `${ruta}.takeover`;
+  if (!adquirirTokenTakeover(token)) return; // otro taker está removiendo el stale
+  try {
+    const actual = leerLock(ruta);
+    if (contenidoTomable(actual, staleMs)) {
+      try { fs.unlinkSync(ruta); } catch { /* ya removido */ }
+    }
+    // else: `ruta` pasó a ser un lock VIVO legítimo — no tocar.
+  } finally {
+    try { fs.unlinkSync(token); } catch { /* nada */ }
+  }
+}
+
+/**
+ * Adquiere el token de takeover (O_EXCL). Si existe pero está leaked, lo reclama
+ * una vez. Un token queda leaked SOLO si el taker murió dentro de su sección
+ * crítica (leer+unlink, del orden de µs). Dos señales de leak, en orden:
+ *   1. pid del token MUERTO → el taker crasheó → reclamo INSTANTÁNEO (sin
+ *      esperar TAKEOVER_TOKEN_STALE_MS). Es el caso realista (SIGKILL/crash) y
+ *      con esto la ventana de bloqueo del leak baja de segundos a ~0.
+ *   2. pid vivo pero token viejo (>TAKEOVER_TOKEN_STALE_MS) → taker atascado
+ *      (patológico para una sección de µs) → reclamo por edad.
+ * El reclamo final es un crearLockExclusivo (O_EXCL): si dos takers reclaman a
+ * la vez, solo uno crea el token. Límite inherente (documentado): con locks de
+ * archivo zero-dep no hay exclusión mutua PERFECTA para el reclamo de stale
+ * —igual que proper-lockfile—; el riesgo residual es una carrera compuesta
+ * (leak en µs + doble-reclamo simultáneo) de probabilidad despreciable.
+ * @returns {boolean}
+ */
+function adquirirTokenTakeover(token) {
+  if (crearLockExclusivo(token, 'takeover')) return true;
+  const contenido = leerLock(token);
+  const pidMuerto = contenido && typeof contenido.pid !== 'undefined' && !pidVivo(contenido.pid);
+  let viejo = false;
+  try {
+    viejo = (Date.now() - fs.statSync(token).mtimeMs) > TAKEOVER_TOKEN_STALE_MS;
+  } catch {
+    return crearLockExclusivo(token, 'takeover'); // desapareció entre create y stat → reintentar
+  }
+  if (pidMuerto || viejo) {
+    try { fs.unlinkSync(token); } catch { /* otro lo removió */ }
+    return crearLockExclusivo(token, 'takeover');
+  }
+  return false;
+}
+
 /**
  * Libera el lock. Idempotente.
  *
@@ -123,6 +249,67 @@ function liberar(nombre) {
   locksAdquiridos.delete(nombre);
 }
 
+/**
+ * Sleep SÍNCRONO sin quemar CPU (Atomics.wait sobre un buffer efímero).
+ * Los hooks son procesos cortos de un solo propósito — bloquear el event
+ * loop unos ms para serializar un RMW es aceptable y evita el busy-loop.
+ * @param {number} ms
+ */
+function dormirSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    // SharedArrayBuffer no disponible: degradar a busy-wait acotado.
+    const fin = Date.now() + ms;
+    while (Date.now() < fin) { /* espera */ }
+  }
+}
+
+/**
+ * Ejecuta `fn` dentro de una sección crítica serializada por lock, con
+ * reintentos de adquisición (poll). Para RMW de archivos compartidos que NO
+ * deben perder datos por race (APRENDIZAJES.md) o cuyo incremento puede
+ * omitirse bajo contención (dirty.json).
+ *
+ * @param {string} nombre - Identificador del lock.
+ * @param {Function} fn - Trabajo a ejecutar dentro de la sección crítica.
+ * @param {object} [opts]
+ * @param {number} [opts.maxWaitMs=1000] - Tope total de espera para adquirir.
+ * @param {number} [opts.pollMs=25] - Intervalo entre intentos.
+ * @param {number} [opts.staleMs] - Se pasa a adquirir().
+ * @param {'ejecutar'|'omitir'} [opts.siNoAdquiere='ejecutar'] - Qué hacer si
+ *   no se adquiere el lock dentro de maxWaitMs: `ejecutar` corre fn igual
+ *   (best-effort, no pierde datos — la ventana de race ya se redujo al mínimo);
+ *   `omitir` salta fn (el trabajo es descartable, ej. un contador).
+ * @returns {{ejecutado:boolean, conLock:boolean}}
+ */
+function conLockRetry(nombre, fn, opts = {}) {
+  const maxWaitMs = opts.maxWaitMs != null ? opts.maxWaitMs : 1000;
+  const pollMs = opts.pollMs != null ? opts.pollMs : 25;
+  const siNoAdquiere = opts.siNoAdquiere || 'ejecutar';
+  const deadline = Date.now() + maxWaitMs;
+
+  let adquirido = adquirir(nombre, { staleMs: opts.staleMs });
+  while (!adquirido && Date.now() < deadline) {
+    dormirSync(pollMs);
+    adquirido = adquirir(nombre, { staleMs: opts.staleMs });
+  }
+
+  if (!adquirido) {
+    if (siNoAdquiere === 'omitir') return { ejecutado: false, conLock: false };
+    // best-effort: correr sin lock (mejor que perder el dato)
+    try { fn(); } finally { /* sin lock que liberar */ }
+    return { ejecutado: true, conLock: false };
+  }
+
+  try {
+    fn();
+    return { ejecutado: true, conLock: true };
+  } finally {
+    liberar(nombre);
+  }
+}
+
 /**
  * Libera todos los locks adquiridos por este proceso.
  * Invocado por handlers de SIGTERM/SIGINT/exit.
@@ -155,5 +342,9 @@ module.exports = {
   adquirir,
   liberar,
   liberarTodos,
-  _internals: { pidVivo, rutaLock, STALE_MS_DEFAULT },
+  conLockRetry,
+  _internals: {
+    pidVivo, rutaLock, dormirSync, crearLockExclusivo, lockTomable, contenidoTomable,
+    leerLock, takeoverStaleSerializado, adquirirTokenTakeover, STALE_MS_DEFAULT,
+  },
 };

package/hooks/lib/telegram-cliente.js

@@ -117,9 +117,16 @@ function _esperar(ms) {
 /**
  * Envía un mensaje de Telegram con escape HTML, truncado y reintentos.
  *
- * Solo reintenta en errores 5xx (falla de servidor). Los errores 4xx
- * (credenciales inválidas, chat no encontrado) no se reintentan porque
- * volver a intentar no resolvería el problema.
+ * Solo reintenta en errores 5xx (falla de servidor con no-entrega confirmada).
+ * NO reintenta en:
+ *  - 4xx (credenciales inválidas, chat no encontrado): reintentar no ayuda.
+ *  - statusCode 0 (timeout o error de red): la entrega es INDETERMINADA — el
+ *    POST /sendMessage pudo LLEGAR a Telegram y solo perderse la respuesta
+ *    (ECONNRESET tras enviar). Como sendMessage NO es idempotente, reintentar
+ *    DUPLICA el mensaje. Esa era la causa raíz de la triplicación de
+ *    notificaciones (diagnóstico 2026-07-11): una conexión inestable entregaba
+ *    el mensaje 1-3 veces mientras el hook logueaba un solo "ok". Se prefiere
+ *    perder una notificación best-effort ante un fallo de red a triplicarla.
  *
  * @param {string} token   - Token del bot (`123:ABC...`).
  * @param {string} chatId  - ID numérico del chat destino.
@@ -133,21 +140,23 @@ async function enviarMensaje(token, chatId, texto, opts = {}) {
   for (let intento = 0; intento < REINTENTOS_MAX; intento++) {
     const resultado = await _intentarEnvio(token, chatId, textoPrepado, opts);
 
-    if (resultado.cuerpo === 'timeout') {
-      return { ok: false, statusCode: 0, error: 'timeout' };
-    }
-
     if (resultado.ok) {
       return { ok: true, statusCode: resultado.statusCode };
     }
 
+    // Entrega INDETERMINADA (timeout o error de red): NO reintentar — un
+    // reintento duplicaría un mensaje que quizá ya se entregó.
+    if (resultado.statusCode === 0) {
+      return { ok: false, statusCode: 0, error: resultado.cuerpo === 'timeout' ? 'timeout' : 'network-error' };
+    }
+
     // Errores 4xx: no reintentar (credenciales inválidas, chat inexistente, etc.)
     if (resultado.statusCode >= 400 && resultado.statusCode < 500) {
       const etiqueta = resultado.statusCode === 401 ? 'unauthorized' : `http-${resultado.statusCode}`;
       return { ok: false, statusCode: resultado.statusCode, error: etiqueta };
     }
 
-    // Error de red (statusCode 0) o 5xx: reintento con backoff exponencial
+    // Solo 5xx (falla de servidor con no-entrega): reintento con backoff.
     if (intento < REINTENTOS_MAX - 1) {
       await _esperar(BACKOFF_BASE_MS * Math.pow(2, intento));
     }

package/hooks/preservar-estado-pre-compact.js

@@ -20,6 +20,7 @@
  */
 
 const fs   = require('fs');
+const { raizProyecto } = require('./lib/raiz-proyecto');
 const path = require('path');
 
 // Atomic write para backups pre-compact (.planning/backups/). Si la
@@ -32,7 +33,7 @@ try {
   atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
 }
 
-const CWD = process.cwd();
+const CWD = raizProyecto(process.cwd());
 
 // ---------------------------------------------------------------------------
 // Archivos de estado a preservar