@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/ciclo-autonomo/guard-convivencia.js

@@ -1,139 +1,139 @@
-'use strict';
-
-/**
- * guard-convivencia.js — Guard de convivencia con una sesión interactiva de
- * Claude Code en la misma máquina (Fase 22, T-03, REQ-22-02).
- *
- * El runner headless de Fase B (`runner-fase-b.js`, T-05) NUNCA debe competir
- * por recursos/rate-limit con un usuario trabajando en una sesión interactiva.
- * Este módulo detecta si hay un proceso con imagen `claude` corriendo:
- * `tasklist /FO CSV /NH` en win32, `ps -eo comm=` en POSIX.
- *
- * El `detector` es INYECTABLE — una función sin argumentos que devuelve la
- * salida cruda del listado de procesos (string) o lanza. Los tests SIEMPRE
- * inyectan el detector; nunca se spawnea un proceso real en la suite. El
- * detector por defecto usa `child_process.spawnSync` con un timeout corto
- * (2s) para que un binario colgado nunca bloquee el runner.
- *
- * Semántica CONSERVADORA (dictamen adversarial, supuesto 2 del CONTEXTO):
- * proceso `claude` presente → diferir; ausente → no diferir; CUALQUIER fallo
- * de detección (spawn falla, binario ausente, timeout, salida ilegible) →
- * diferir también. Un falso positivo (diferir de más) es aceptable; competir
- * con un usuario interactivo no lo es. El guard NUNCA lanza hacia el caller.
- *
- * LIMITACIÓN DOCUMENTADA (fase dry-run, F22 no la resuelve): el detector
- * matchea por NOMBRE de imagen de proceso, no por árbol de PIDs. Si el propio
- * runner (headless, `node`) fuese lanzado como hijo de un proceso `claude`
- * padre (p. ej. invocado manualmente desde dentro de una sesión interactiva),
- * este guard lo tomaría como sesión interactiva activa y diferiría — no hay
- * forma de distinguir "mi propio ancestro" de "otra sesión del usuario" sin
- * caminar el árbol de procesos por PID/PPID, algo que el CONTEXTO de esta fase
- * no exige y el plan no especifica. El proceso `node` del propio runner NUNCA
- * cuenta como match (solo se busca la imagen `claude`), pero un ancestro
- * `claude` sí produce el mismo diferir que una sesión ajena. F24 (ciclo con
- * mutaciones reales) es quien debe afinar esta distinción si el patrón de
- * disparo cambia (p. ej. invocación manual desde dentro de una sesión).
- *
- * Zero-deps, CommonJS.
- *
- * @module scripts/lib/ciclo-autonomo/guard-convivencia
- */
-
-const { spawnSync } = require('child_process');
-
-/** Timeout del spawn de detección — nunca debe colgar el runner headless. */
-const TIMEOUT_MS = 2000;
-
-/** Nombre de imagen de proceso que identifica una sesión interactiva. */
-const NOMBRE_PROCESO = 'claude';
-
-/**
- * Resuelve el comando de listado de procesos según la plataforma. Puro y
- * exportado para poder verificar la selección win32/POSIX en tests sin
- * spawnear nada real.
- *
- * @param {string} plataforma - Típicamente `process.platform`.
- * @returns {{cmd: string, args: string[]}}
- */
-function resolverComando(plataforma) {
-  if (plataforma === 'win32') {
-    return { cmd: 'tasklist', args: ['/FO', 'CSV', '/NH'] };
-  }
-  return { cmd: 'ps', args: ['-eo', 'comm='] };
-}
-
-/**
- * Detector por defecto: spawnSync del listado de procesos de la plataforma.
- * Lanza si el spawn falla, sale con código distinto de 0, o no produce una
- * salida de texto utilizable — el caller (`evaluar`) trata cualquier lanzamiento
- * como fallo de detección conservador.
- *
- * @param {string} plataforma
- * @returns {string} Salida cruda del comando.
- */
-function detectorPorDefecto(plataforma) {
-  const { cmd, args } = resolverComando(plataforma);
-  const resultado = spawnSync(cmd, args, { timeout: TIMEOUT_MS, encoding: 'utf8' });
-
-  if (!resultado || resultado.error || resultado.status !== 0 || typeof resultado.stdout !== 'string') {
-    throw new Error(`guard-convivencia: "${cmd}" no produjo salida utilizable`);
-  }
-
-  return resultado.stdout;
-}
-
-/**
- * `true` si la salida cruda del listado de procesos contiene una imagen
- * `claude` (case-insensitive; matchea tanto `claude` como `claude.exe` en
- * una línea CSV de tasklist o en la salida de `ps -eo comm=`).
- *
- * @param {string} salidaCruda
- * @returns {boolean}
- */
-function contieneProcesoClaude(salidaCruda) {
-  return salidaCruda
-    .split(/\r?\n/)
-    .some((linea) => linea.toLowerCase().includes(NOMBRE_PROCESO));
-}
-
-/**
- * `true` si hay una sesión interactiva de Claude Code corriendo, según el
- * detector inyectado (o el detector por defecto para la plataforma dada).
- * Lanza si la detección falla — `evaluar` es quien decide el fallback
- * conservador; esta función expone el booleano crudo.
- *
- * @param {{detector?: () => string, plataforma?: string}} [opciones]
- * @returns {boolean}
- */
-function haySesionInteractiva({ detector, plataforma = process.platform } = {}) {
-  const salidaCruda = detector ? detector() : detectorPorDefecto(plataforma);
-  if (typeof salidaCruda !== 'string') {
-    throw new Error('guard-convivencia: el detector no devolvió una salida de texto');
-  }
-  return contieneProcesoClaude(salidaCruda);
-}
-
-/**
- * Evalúa si el runner de Fase B debe diferirse por convivencia con una
- * sesión interactiva. NUNCA lanza — cualquier error de detección se
- * convierte en `{diferir:true, razon:'deteccion-fallida'}` (conservador).
- *
- * @param {{detector?: () => string, plataforma?: string}} [opciones]
- * @returns {{diferir: boolean, razon?: string}}
- */
-function evaluar({ detector, plataforma } = {}) {
-  let activa;
-  try {
-    activa = haySesionInteractiva({ detector, plataforma });
-  } catch (_) {
-    return { diferir: true, razon: 'deteccion-fallida' };
-  }
-
-  if (activa) {
-    return { diferir: true, razon: 'sesion-interactiva' };
-  }
-
-  return { diferir: false };
-}
-
-module.exports = { evaluar, haySesionInteractiva, resolverComando };
+'use strict';
+
+/**
+ * guard-convivencia.js — Guard de convivencia con una sesión interactiva de
+ * Claude Code en la misma máquina (Fase 22, T-03, REQ-22-02).
+ *
+ * El runner headless de Fase B (`runner-fase-b.js`, T-05) NUNCA debe competir
+ * por recursos/rate-limit con un usuario trabajando en una sesión interactiva.
+ * Este módulo detecta si hay un proceso con imagen `claude` corriendo:
+ * `tasklist /FO CSV /NH` en win32, `ps -eo comm=` en POSIX.
+ *
+ * El `detector` es INYECTABLE — una función sin argumentos que devuelve la
+ * salida cruda del listado de procesos (string) o lanza. Los tests SIEMPRE
+ * inyectan el detector; nunca se spawnea un proceso real en la suite. El
+ * detector por defecto usa `child_process.spawnSync` con un timeout corto
+ * (2s) para que un binario colgado nunca bloquee el runner.
+ *
+ * Semántica CONSERVADORA (dictamen adversarial, supuesto 2 del CONTEXTO):
+ * proceso `claude` presente → diferir; ausente → no diferir; CUALQUIER fallo
+ * de detección (spawn falla, binario ausente, timeout, salida ilegible) →
+ * diferir también. Un falso positivo (diferir de más) es aceptable; competir
+ * con un usuario interactivo no lo es. El guard NUNCA lanza hacia el caller.
+ *
+ * LIMITACIÓN DOCUMENTADA (fase dry-run, F22 no la resuelve): el detector
+ * matchea por NOMBRE de imagen de proceso, no por árbol de PIDs. Si el propio
+ * runner (headless, `node`) fuese lanzado como hijo de un proceso `claude`
+ * padre (p. ej. invocado manualmente desde dentro de una sesión interactiva),
+ * este guard lo tomaría como sesión interactiva activa y diferiría — no hay
+ * forma de distinguir "mi propio ancestro" de "otra sesión del usuario" sin
+ * caminar el árbol de procesos por PID/PPID, algo que el CONTEXTO de esta fase
+ * no exige y el plan no especifica. El proceso `node` del propio runner NUNCA
+ * cuenta como match (solo se busca la imagen `claude`), pero un ancestro
+ * `claude` sí produce el mismo diferir que una sesión ajena. F24 (ciclo con
+ * mutaciones reales) es quien debe afinar esta distinción si el patrón de
+ * disparo cambia (p. ej. invocación manual desde dentro de una sesión).
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/guard-convivencia
+ */
+
+const { spawnSync } = require('child_process');
+
+/** Timeout del spawn de detección — nunca debe colgar el runner headless. */
+const TIMEOUT_MS = 2000;
+
+/** Nombre de imagen de proceso que identifica una sesión interactiva. */
+const NOMBRE_PROCESO = 'claude';
+
+/**
+ * Resuelve el comando de listado de procesos según la plataforma. Puro y
+ * exportado para poder verificar la selección win32/POSIX en tests sin
+ * spawnear nada real.
+ *
+ * @param {string} plataforma - Típicamente `process.platform`.
+ * @returns {{cmd: string, args: string[]}}
+ */
+function resolverComando(plataforma) {
+  if (plataforma === 'win32') {
+    return { cmd: 'tasklist', args: ['/FO', 'CSV', '/NH'] };
+  }
+  return { cmd: 'ps', args: ['-eo', 'comm='] };
+}
+
+/**
+ * Detector por defecto: spawnSync del listado de procesos de la plataforma.
+ * Lanza si el spawn falla, sale con código distinto de 0, o no produce una
+ * salida de texto utilizable — el caller (`evaluar`) trata cualquier lanzamiento
+ * como fallo de detección conservador.
+ *
+ * @param {string} plataforma
+ * @returns {string} Salida cruda del comando.
+ */
+function detectorPorDefecto(plataforma) {
+  const { cmd, args } = resolverComando(plataforma);
+  const resultado = spawnSync(cmd, args, { timeout: TIMEOUT_MS, encoding: 'utf8' });
+
+  if (!resultado || resultado.error || resultado.status !== 0 || typeof resultado.stdout !== 'string') {
+    throw new Error(`guard-convivencia: "${cmd}" no produjo salida utilizable`);
+  }
+
+  return resultado.stdout;
+}
+
+/**
+ * `true` si la salida cruda del listado de procesos contiene una imagen
+ * `claude` (case-insensitive; matchea tanto `claude` como `claude.exe` en
+ * una línea CSV de tasklist o en la salida de `ps -eo comm=`).
+ *
+ * @param {string} salidaCruda
+ * @returns {boolean}
+ */
+function contieneProcesoClaude(salidaCruda) {
+  return salidaCruda
+    .split(/\r?\n/)
+    .some((linea) => linea.toLowerCase().includes(NOMBRE_PROCESO));
+}
+
+/**
+ * `true` si hay una sesión interactiva de Claude Code corriendo, según el
+ * detector inyectado (o el detector por defecto para la plataforma dada).
+ * Lanza si la detección falla — `evaluar` es quien decide el fallback
+ * conservador; esta función expone el booleano crudo.
+ *
+ * @param {{detector?: () => string, plataforma?: string}} [opciones]
+ * @returns {boolean}
+ */
+function haySesionInteractiva({ detector, plataforma = process.platform } = {}) {
+  const salidaCruda = detector ? detector() : detectorPorDefecto(plataforma);
+  if (typeof salidaCruda !== 'string') {
+    throw new Error('guard-convivencia: el detector no devolvió una salida de texto');
+  }
+  return contieneProcesoClaude(salidaCruda);
+}
+
+/**
+ * Evalúa si el runner de Fase B debe diferirse por convivencia con una
+ * sesión interactiva. NUNCA lanza — cualquier error de detección se
+ * convierte en `{diferir:true, razon:'deteccion-fallida'}` (conservador).
+ *
+ * @param {{detector?: () => string, plataforma?: string}} [opciones]
+ * @returns {{diferir: boolean, razon?: string}}
+ */
+function evaluar({ detector, plataforma } = {}) {
+  let activa;
+  try {
+    activa = haySesionInteractiva({ detector, plataforma });
+  } catch (_) {
+    return { diferir: true, razon: 'deteccion-fallida' };
+  }
+
+  if (activa) {
+    return { diferir: true, razon: 'sesion-interactiva' };
+  }
+
+  return { diferir: false };
+}
+
+module.exports = { evaluar, haySesionInteractiva, resolverComando };

package/scripts/lib/ciclo-autonomo/higiene-nudges.js

@@ -1,112 +1,112 @@
-'use strict';
-
-/**
- * Higiene del ciclo de nudges (T-09, Fase 21 — ADR-0041).
- *
- * Opera sobre `.planning/evolution/nudges.jsonl` con formato compatible con
- * `hooks/lib/nudge-tracker.js` ({id, kind, target, ts, accionado,
- * accionado_ts, accionado_por}), pero con `baseDir` inyectable — el tracker
- * fija sus rutas al cwd del require y no sirve para el motor ni para tests
- * en sandbox.
- *
- *   - marcarAccionado(baseDir, {id | kinds, por, ahora}) → {marcados}
- *   - archivarViejos(baseDir, {ahora, dias=90})          → {archivados}
- *
- * Zero-deps. Reescritura completa vía atomic-write; líneas con schema viejo
- * o corruptas se conservan intactas (nunca se pierden por higiene).
- */
-
-const fs = require('fs');
-const path = require('path');
-const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
-
-const DIAS_VENTANA_DEFAULT = 90;
-
-function rutaNudges(baseDir) {
-  return path.join(baseDir, '.planning', 'evolution', 'nudges.jsonl');
-}
-
-function rutaArchive(baseDir) {
-  return path.join(baseDir, '.planning', 'evolution', 'nudges.archive.jsonl');
-}
-
-// Lee el JSONL preservando las líneas crudas: las que no parsean se devuelven
-// con `nudge: null` para reescribirlas tal cual (tolerancia sin pérdida).
-function leerLineas(baseDir) {
-  const ruta = rutaNudges(baseDir);
-  if (!fs.existsSync(ruta)) return null;
-  return fs
-    .readFileSync(ruta, 'utf8')
-    .split('\n')
-    .filter((l) => l.trim() !== '')
-    .map((cruda) => {
-      try {
-        return { cruda, nudge: JSON.parse(cruda) };
-      } catch {
-        return { cruda, nudge: null };
-      }
-    });
-}
-
-function escribirLineas(baseDir, lineas) {
-  const contenido = lineas.map((l) => l.cruda).join('\n') + (lineas.length ? '\n' : '');
-  atomicWriteSync(rutaNudges(baseDir), contenido, 'utf8');
-}
-
-/**
- * Marca nudges como accionados, por `id` exacto o por lista de `kinds`
- * (solo los aún no accionados). Nunca pisa un `accionado_por` previo.
- */
-function marcarAccionado(baseDir, { id, kinds, por = 'desconocido', ahora = new Date() } = {}) {
-  const lineas = leerLineas(baseDir);
-  if (!lineas) return { marcados: 0 };
-
-  let marcados = 0;
-  for (const linea of lineas) {
-    const n = linea.nudge;
-    if (!n || n.accionado === true) continue;
-    const porId = id != null && n.id === id;
-    const porKind = Array.isArray(kinds) && kinds.includes(n.kind);
-    if (!porId && !porKind) continue;
-
-    n.accionado = true;
-    n.accionado_ts = ahora.toISOString();
-    n.accionado_por = por;
-    linea.cruda = JSON.stringify(n);
-    marcados++;
-  }
-
-  if (marcados > 0) escribirLineas(baseDir, lineas);
-  return { marcados };
-}
-
-/**
- * Mueve al archive los nudges SIN accionar con `ts` más viejo que la ventana.
- * Los nudges sin `ts` parseable y las líneas corruptas se conservan activos
- * (mejor conservar de más que archivar señal viva).
- */
-function archivarViejos(baseDir, { ahora = new Date(), dias = DIAS_VENTANA_DEFAULT } = {}) {
-  const lineas = leerLineas(baseDir);
-  if (!lineas) return { archivados: 0 };
-
-  const limiteMs = ahora.getTime() - dias * 24 * 3600 * 1000;
-  const activos = [];
-  const archivados = [];
-
-  for (const linea of lineas) {
-    const n = linea.nudge;
-    const tsMs = n && n.ts ? Date.parse(n.ts) : NaN;
-    const esViejoSinAccionar = n && n.accionado !== true && Number.isFinite(tsMs) && tsMs < limiteMs;
-    (esViejoSinAccionar ? archivados : activos).push(linea);
-  }
-
-  if (archivados.length > 0) {
-    const bloque = archivados.map((l) => l.cruda).join('\n') + '\n';
-    fs.appendFileSync(rutaArchive(baseDir), bloque, 'utf8');
-    escribirLineas(baseDir, activos);
-  }
-
-  return { archivados: archivados.length };
-}
-
-module.exports = { marcarAccionado, archivarViejos, DIAS_VENTANA_DEFAULT };
+'use strict';
+
+/**
+ * Higiene del ciclo de nudges (T-09, Fase 21 — ADR-0041).
+ *
+ * Opera sobre `.planning/evolution/nudges.jsonl` con formato compatible con
+ * `hooks/lib/nudge-tracker.js` ({id, kind, target, ts, accionado,
+ * accionado_ts, accionado_por}), pero con `baseDir` inyectable — el tracker
+ * fija sus rutas al cwd del require y no sirve para el motor ni para tests
+ * en sandbox.
+ *
+ *   - marcarAccionado(baseDir, {id | kinds, por, ahora}) → {marcados}
+ *   - archivarViejos(baseDir, {ahora, dias=90})          → {archivados}
+ *
+ * Zero-deps. Reescritura completa vía atomic-write; líneas con schema viejo
+ * o corruptas se conservan intactas (nunca se pierden por higiene).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
+
+const DIAS_VENTANA_DEFAULT = 90;
+
+function rutaNudges(baseDir) {
+  return path.join(baseDir, '.planning', 'evolution', 'nudges.jsonl');
+}
+
+function rutaArchive(baseDir) {
+  return path.join(baseDir, '.planning', 'evolution', 'nudges.archive.jsonl');
+}
+
+// Lee el JSONL preservando las líneas crudas: las que no parsean se devuelven
+// con `nudge: null` para reescribirlas tal cual (tolerancia sin pérdida).
+function leerLineas(baseDir) {
+  const ruta = rutaNudges(baseDir);
+  if (!fs.existsSync(ruta)) return null;
+  return fs
+    .readFileSync(ruta, 'utf8')
+    .split('\n')
+    .filter((l) => l.trim() !== '')
+    .map((cruda) => {
+      try {
+        return { cruda, nudge: JSON.parse(cruda) };
+      } catch {
+        return { cruda, nudge: null };
+      }
+    });
+}
+
+function escribirLineas(baseDir, lineas) {
+  const contenido = lineas.map((l) => l.cruda).join('\n') + (lineas.length ? '\n' : '');
+  atomicWriteSync(rutaNudges(baseDir), contenido, 'utf8');
+}
+
+/**
+ * Marca nudges como accionados, por `id` exacto o por lista de `kinds`
+ * (solo los aún no accionados). Nunca pisa un `accionado_por` previo.
+ */
+function marcarAccionado(baseDir, { id, kinds, por = 'desconocido', ahora = new Date() } = {}) {
+  const lineas = leerLineas(baseDir);
+  if (!lineas) return { marcados: 0 };
+
+  let marcados = 0;
+  for (const linea of lineas) {
+    const n = linea.nudge;
+    if (!n || n.accionado === true) continue;
+    const porId = id != null && n.id === id;
+    const porKind = Array.isArray(kinds) && kinds.includes(n.kind);
+    if (!porId && !porKind) continue;
+
+    n.accionado = true;
+    n.accionado_ts = ahora.toISOString();
+    n.accionado_por = por;
+    linea.cruda = JSON.stringify(n);
+    marcados++;
+  }
+
+  if (marcados > 0) escribirLineas(baseDir, lineas);
+  return { marcados };
+}
+
+/**
+ * Mueve al archive los nudges SIN accionar con `ts` más viejo que la ventana.
+ * Los nudges sin `ts` parseable y las líneas corruptas se conservan activos
+ * (mejor conservar de más que archivar señal viva).
+ */
+function archivarViejos(baseDir, { ahora = new Date(), dias = DIAS_VENTANA_DEFAULT } = {}) {
+  const lineas = leerLineas(baseDir);
+  if (!lineas) return { archivados: 0 };
+
+  const limiteMs = ahora.getTime() - dias * 24 * 3600 * 1000;
+  const activos = [];
+  const archivados = [];
+
+  for (const linea of lineas) {
+    const n = linea.nudge;
+    const tsMs = n && n.ts ? Date.parse(n.ts) : NaN;
+    const esViejoSinAccionar = n && n.accionado !== true && Number.isFinite(tsMs) && tsMs < limiteMs;
+    (esViejoSinAccionar ? archivados : activos).push(linea);
+  }
+
+  if (archivados.length > 0) {
+    const bloque = archivados.map((l) => l.cruda).join('\n') + '\n';
+    fs.appendFileSync(rutaArchive(baseDir), bloque, 'utf8');
+    escribirLineas(baseDir, activos);
+  }
+
+  return { archivados: archivados.length };
+}
+
+module.exports = { marcarAccionado, archivarViejos, DIAS_VENTANA_DEFAULT };