@saulwade/swl-ses 2.6.0 → 2.6.1

package/scripts/lib/ciclo-autonomo/lock.js

@@ -1,124 +1,124 @@
-'use strict';
-
-/**
- * Lock propio del ciclo autónomo — envuelve `hooks/lib/consolidation-lock.js`
- * con lockfile dedicado `.ciclo-autonomo-lock` en `.planning/` (Fase 21,
- * T-02). Garantiza exclusión mutua entre el scheduler cron y el fallback de
- * `session-briefing` (REQ-21-11, T-11) sin compartir el lockfile de
- * auto-consolidación (`.consolidation-lock`) — corridas concurrentes de
- * ambos motores no se bloquean entre sí.
- *
- * Diferencia deliberada frente al patrón original: `liberar()` SÍ libera el
- * mutex de inmediato (borra el lockfile) en vez de solo tocar su mtime. El
- * módulo original está pensado para un daemon de sesión donde "liberar"
- * significa "marcar el mtime como última corrida exitosa" y el siguiente
- * intento normalmente lo hace un proceso nuevo (PID distinto, el anterior ya
- * murió). El ciclo autónomo, en cambio, corre como invocación CLI de un solo
- * tiro (`swl-ses ciclo-autonomo`) y el guard de "mínimo 24h entre corridas"
- * lo evalúa el caller (T-11, fallback de `session-briefing`) leyendo
- * `ultimaCorridaMs()` — no el propio lock. Por eso "última corrida" se
- * persiste aparte, en el marcador `.planning/evolution/.ciclo-last-run`
- * (epoch ms en texto plano), en vez de reusar el mtime del lockfile: si
- * reusáramos el mtime, `liberar()` no podría borrar el archivo sin perder
- * ese dato.
- *
- * Zero-deps, CommonJS.
- *
- * @module scripts/lib/ciclo-autonomo/lock
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const {
-  tryAcquireLock,
-  rollbackLock,
-  lockPath,
-} = require('../../../hooks/lib/consolidation-lock');
-const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
-
-/** Nombre del lockfile propio del ciclo (independiente del de auto-consolidación). */
-const LOCK_FILENAME = '.ciclo-autonomo-lock';
-
-/** Ruta relativa del marcador de última corrida exitosa (epoch ms). */
-const MARCADOR_RELATIVO = path.join('evolution', '.ciclo-last-run');
-
-/**
- * Ruta absoluta del marcador de última corrida.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @returns {string}
- */
-function rutaMarcador(baseDir) {
-  return path.join(baseDir, '.planning', MARCADOR_RELATIVO);
-}
-
-/**
- * Intenta adquirir el lock del ciclo autónomo.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @returns {{ acquired: boolean, priorMtime: number }}
- */
-function adquirir(baseDir) {
-  return tryAcquireLock(baseDir, { lockFilename: LOCK_FILENAME });
-}
-
-/**
- * Libera el lock tras una corrida exitosa: borra el lockfile (mutex libre de
- * inmediato) y registra el epoch ms de la corrida en el marcador de última
- * corrida. El marcador es best-effort — un fallo al escribirlo no debe
- * tumbar el ciclo (ya completó su trabajo real).
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- */
-function liberar(baseDir) {
-  const lp = lockPath(baseDir, { lockFilename: LOCK_FILENAME });
-  try {
-    fs.unlinkSync(lp);
-  } catch {
-    // Ya no existía o no se pudo borrar — no bloqueante.
-  }
-
-  try {
-    atomicWriteSync(rutaMarcador(baseDir), String(Date.now()), 'utf8');
-  } catch {
-    // Best-effort: el marcador no es crítico para la corrida ya completada.
-  }
-}
-
-/**
- * Revierte el lock tras una corrida fallida o no-op: restaura el mtime
- * previo (o borra el lockfile si no existía antes de adquirir). NO toca el
- * marcador de última corrida — una corrida fallida/no-op no cuenta como
- * "última corrida".
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {number} priorMtime - Epoch ms devuelto por `adquirir()`.
- */
-function rollback(baseDir, priorMtime) {
-  rollbackLock(baseDir, priorMtime, { lockFilename: LOCK_FILENAME });
-}
-
-/**
- * Epoch ms de la última corrida exitosa registrada por `liberar()`.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @returns {number|null} Epoch ms, o `null` si nunca hubo una corrida.
- */
-function ultimaCorridaMs(baseDir) {
-  try {
-    const crudo = fs.readFileSync(rutaMarcador(baseDir), 'utf8').trim();
-    const ms = Number(crudo);
-    return Number.isFinite(ms) ? ms : null;
-  } catch {
-    return null;
-  }
-}
-
-module.exports = {
-  adquirir,
-  liberar,
-  rollback,
-  ultimaCorridaMs,
-  LOCK_FILENAME,
-};
+'use strict';
+
+/**
+ * Lock propio del ciclo autónomo — envuelve `hooks/lib/consolidation-lock.js`
+ * con lockfile dedicado `.ciclo-autonomo-lock` en `.planning/` (Fase 21,
+ * T-02). Garantiza exclusión mutua entre el scheduler cron y el fallback de
+ * `session-briefing` (REQ-21-11, T-11) sin compartir el lockfile de
+ * auto-consolidación (`.consolidation-lock`) — corridas concurrentes de
+ * ambos motores no se bloquean entre sí.
+ *
+ * Diferencia deliberada frente al patrón original: `liberar()` SÍ libera el
+ * mutex de inmediato (borra el lockfile) en vez de solo tocar su mtime. El
+ * módulo original está pensado para un daemon de sesión donde "liberar"
+ * significa "marcar el mtime como última corrida exitosa" y el siguiente
+ * intento normalmente lo hace un proceso nuevo (PID distinto, el anterior ya
+ * murió). El ciclo autónomo, en cambio, corre como invocación CLI de un solo
+ * tiro (`swl-ses ciclo-autonomo`) y el guard de "mínimo 24h entre corridas"
+ * lo evalúa el caller (T-11, fallback de `session-briefing`) leyendo
+ * `ultimaCorridaMs()` — no el propio lock. Por eso "última corrida" se
+ * persiste aparte, en el marcador `.planning/evolution/.ciclo-last-run`
+ * (epoch ms en texto plano), en vez de reusar el mtime del lockfile: si
+ * reusáramos el mtime, `liberar()` no podría borrar el archivo sin perder
+ * ese dato.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/lock
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  tryAcquireLock,
+  rollbackLock,
+  lockPath,
+} = require('../../../hooks/lib/consolidation-lock');
+const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
+
+/** Nombre del lockfile propio del ciclo (independiente del de auto-consolidación). */
+const LOCK_FILENAME = '.ciclo-autonomo-lock';
+
+/** Ruta relativa del marcador de última corrida exitosa (epoch ms). */
+const MARCADOR_RELATIVO = path.join('evolution', '.ciclo-last-run');
+
+/**
+ * Ruta absoluta del marcador de última corrida.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {string}
+ */
+function rutaMarcador(baseDir) {
+  return path.join(baseDir, '.planning', MARCADOR_RELATIVO);
+}
+
+/**
+ * Intenta adquirir el lock del ciclo autónomo.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {{ acquired: boolean, priorMtime: number }}
+ */
+function adquirir(baseDir) {
+  return tryAcquireLock(baseDir, { lockFilename: LOCK_FILENAME });
+}
+
+/**
+ * Libera el lock tras una corrida exitosa: borra el lockfile (mutex libre de
+ * inmediato) y registra el epoch ms de la corrida en el marcador de última
+ * corrida. El marcador es best-effort — un fallo al escribirlo no debe
+ * tumbar el ciclo (ya completó su trabajo real).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ */
+function liberar(baseDir) {
+  const lp = lockPath(baseDir, { lockFilename: LOCK_FILENAME });
+  try {
+    fs.unlinkSync(lp);
+  } catch {
+    // Ya no existía o no se pudo borrar — no bloqueante.
+  }
+
+  try {
+    atomicWriteSync(rutaMarcador(baseDir), String(Date.now()), 'utf8');
+  } catch {
+    // Best-effort: el marcador no es crítico para la corrida ya completada.
+  }
+}
+
+/**
+ * Revierte el lock tras una corrida fallida o no-op: restaura el mtime
+ * previo (o borra el lockfile si no existía antes de adquirir). NO toca el
+ * marcador de última corrida — una corrida fallida/no-op no cuenta como
+ * "última corrida".
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {number} priorMtime - Epoch ms devuelto por `adquirir()`.
+ */
+function rollback(baseDir, priorMtime) {
+  rollbackLock(baseDir, priorMtime, { lockFilename: LOCK_FILENAME });
+}
+
+/**
+ * Epoch ms de la última corrida exitosa registrada por `liberar()`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @returns {number|null} Epoch ms, o `null` si nunca hubo una corrida.
+ */
+function ultimaCorridaMs(baseDir) {
+  try {
+    const crudo = fs.readFileSync(rutaMarcador(baseDir), 'utf8').trim();
+    const ms = Number(crudo);
+    return Number.isFinite(ms) ? ms : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  adquirir,
+  liberar,
+  rollback,
+  ultimaCorridaMs,
+  LOCK_FILENAME,
+};

package/scripts/lib/ciclo-autonomo/presupuesto.js

@@ -1,122 +1,122 @@
-'use strict';
-
-/**
- * presupuesto.js — Contador de presupuesto USD/mes de la Fase B del ciclo
- * autónomo (Fase 22, T-04, ADR-0042 gate G-B, REQ-22-03).
- *
- * Lleva la cuenta del gasto mensual sobre los campos `gasto_mes`/`mes`/
- * `pausado_por_presupuesto` de `ciclo-config.json` (extendidos en T-01,
- * `config.js`). El mes se calcula en hora LOCAL —
- * `toLocaleDateString('sv').slice(0,7)` → `YYYY-MM` (gate C1: NUNCA
- * `toISOString()`, desde México la tarde ya es "mañana" en UTC.
- *
- * El reset mensual es EFECTIVO en lectura: `estado`/`puedeGastar`/
- * `estaPausado` ven el contador en cero y despausado en cuanto cambia el mes,
- * SIN escribir a disco. La persistencia real del reset ocurre recién cuando
- * `registrarGasto` corre (mismo patrón que "el reset lo aplica quien
- * escribe", no quien lee).
- *
- * Zero-deps (solo `config.js`), CommonJS.
- *
- * @module scripts/lib/ciclo-autonomo/presupuesto
- */
-
-const config = require('./config');
-
-/**
- * Clave de mes en formato local `YYYY-MM` (gate C1: local, nunca UTC).
- *
- * @param {Date} [ahora]
- * @returns {string}
- */
-function mesActual(ahora) {
-  const momento = ahora || new Date();
-  return momento.toLocaleDateString('sv').slice(0, 7);
-}
-
-/**
- * Estado efectivo del presupuesto para el mes de `ahora`. Si el `mes` en
- * disco difiere del actual, devuelve el contador reseteado SIN persistirlo
- * (la persistencia real la hace `registrarGasto`).
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {{ahora?: Date}} [opciones]
- * @returns {{gasto_mes: number, mes: string, pausado_por_presupuesto: boolean, tope: number}}
- */
-function estado(baseDir, { ahora } = {}) {
-  const cfg = config.leerConfig(baseDir);
-  const mes = mesActual(ahora);
-
-  if (cfg.mes !== mes) {
-    return { gasto_mes: 0, mes, pausado_por_presupuesto: false, tope: cfg.presupuesto_usd_mes };
-  }
-
-  return {
-    gasto_mes: cfg.gasto_mes,
-    mes: cfg.mes,
-    pausado_por_presupuesto: cfg.pausado_por_presupuesto,
-    tope: cfg.presupuesto_usd_mes,
-  };
-}
-
-/**
- * `true` si la Fase B está pausada por presupuesto para el mes de `ahora`.
- * Un cambio de mes despausa automáticamente (reset efectivo, sin escribir).
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {{ahora?: Date}} [opciones]
- * @returns {boolean}
- */
-function estaPausado(baseDir, { ahora } = {}) {
-  return estado(baseDir, { ahora }).pausado_por_presupuesto;
-}
-
-/**
- * Evalúa si se puede gastar `usd` adicionales sin cruzar el presupuesto
- * mensual ni estar ya pausado. NUNCA muta el config — es una consulta pura.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {number} usd - Gasto adicional a evaluar (0 = solo verificar estado).
- * @param {{ahora?: Date}} [opciones]
- * @returns {{permitido: boolean, razon?: string}}
- */
-function puedeGastar(baseDir, usd, { ahora } = {}) {
-  const st = estado(baseDir, { ahora });
-
-  if (st.pausado_por_presupuesto) {
-    return { permitido: false, razon: 'pausado-presupuesto' };
-  }
-  if (st.gasto_mes + usd > st.tope) {
-    return { permitido: false, razon: 'excede-tope' };
-  }
-  return { permitido: true };
-}
-
-/**
- * Registra un gasto de `usd` en el mes de `ahora`: resetea el contador si el
- * mes cambió, acumula `gasto_mes`, y marca `pausado_por_presupuesto:true` si
- * el acumulado CRUZA (supera) el tope mensual. Persiste siempre con
- * `escribirConfig` (atomic) — incluso con `usd:0`, que es como el runner de
- * Fase B (T-05) registra una corrida dry-run: el contador es infra, no gasta.
- *
- * @param {string} baseDir - Directorio raíz del proyecto.
- * @param {number} usd - Gasto a acumular (0 = solo inicializa/preserva el mes).
- * @param {{ahora?: Date}} [opciones]
- * @returns {{gasto_mes: number, mes: string, pausado_por_presupuesto: boolean}}
- */
-function registrarGasto(baseDir, usd, { ahora } = {}) {
-  const st = estado(baseDir, { ahora });
-  const gastoNuevo = st.gasto_mes + usd;
-  const pausado = st.pausado_por_presupuesto || gastoNuevo > st.tope;
-
-  const siguiente = {
-    mes: st.mes,
-    gasto_mes: gastoNuevo,
-    pausado_por_presupuesto: pausado,
-  };
-  config.escribirConfig(baseDir, siguiente);
-
-  return siguiente;
-}
-
-module.exports = { mesActual, estado, estaPausado, puedeGastar, registrarGasto };
+'use strict';
+
+/**
+ * presupuesto.js — Contador de presupuesto USD/mes de la Fase B del ciclo
+ * autónomo (Fase 22, T-04, ADR-0042 gate G-B, REQ-22-03).
+ *
+ * Lleva la cuenta del gasto mensual sobre los campos `gasto_mes`/`mes`/
+ * `pausado_por_presupuesto` de `ciclo-config.json` (extendidos en T-01,
+ * `config.js`). El mes se calcula en hora LOCAL —
+ * `toLocaleDateString('sv').slice(0,7)` → `YYYY-MM` (gate C1: NUNCA
+ * `toISOString()`, desde México la tarde ya es "mañana" en UTC.
+ *
+ * El reset mensual es EFECTIVO en lectura: `estado`/`puedeGastar`/
+ * `estaPausado` ven el contador en cero y despausado en cuanto cambia el mes,
+ * SIN escribir a disco. La persistencia real del reset ocurre recién cuando
+ * `registrarGasto` corre (mismo patrón que "el reset lo aplica quien
+ * escribe", no quien lee).
+ *
+ * Zero-deps (solo `config.js`), CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/presupuesto
+ */
+
+const config = require('./config');
+
+/**
+ * Clave de mes en formato local `YYYY-MM` (gate C1: local, nunca UTC).
+ *
+ * @param {Date} [ahora]
+ * @returns {string}
+ */
+function mesActual(ahora) {
+  const momento = ahora || new Date();
+  return momento.toLocaleDateString('sv').slice(0, 7);
+}
+
+/**
+ * Estado efectivo del presupuesto para el mes de `ahora`. Si el `mes` en
+ * disco difiere del actual, devuelve el contador reseteado SIN persistirlo
+ * (la persistencia real la hace `registrarGasto`).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{gasto_mes: number, mes: string, pausado_por_presupuesto: boolean, tope: number}}
+ */
+function estado(baseDir, { ahora } = {}) {
+  const cfg = config.leerConfig(baseDir);
+  const mes = mesActual(ahora);
+
+  if (cfg.mes !== mes) {
+    return { gasto_mes: 0, mes, pausado_por_presupuesto: false, tope: cfg.presupuesto_usd_mes };
+  }
+
+  return {
+    gasto_mes: cfg.gasto_mes,
+    mes: cfg.mes,
+    pausado_por_presupuesto: cfg.pausado_por_presupuesto,
+    tope: cfg.presupuesto_usd_mes,
+  };
+}
+
+/**
+ * `true` si la Fase B está pausada por presupuesto para el mes de `ahora`.
+ * Un cambio de mes despausa automáticamente (reset efectivo, sin escribir).
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {boolean}
+ */
+function estaPausado(baseDir, { ahora } = {}) {
+  return estado(baseDir, { ahora }).pausado_por_presupuesto;
+}
+
+/**
+ * Evalúa si se puede gastar `usd` adicionales sin cruzar el presupuesto
+ * mensual ni estar ya pausado. NUNCA muta el config — es una consulta pura.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {number} usd - Gasto adicional a evaluar (0 = solo verificar estado).
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{permitido: boolean, razon?: string}}
+ */
+function puedeGastar(baseDir, usd, { ahora } = {}) {
+  const st = estado(baseDir, { ahora });
+
+  if (st.pausado_por_presupuesto) {
+    return { permitido: false, razon: 'pausado-presupuesto' };
+  }
+  if (st.gasto_mes + usd > st.tope) {
+    return { permitido: false, razon: 'excede-tope' };
+  }
+  return { permitido: true };
+}
+
+/**
+ * Registra un gasto de `usd` en el mes de `ahora`: resetea el contador si el
+ * mes cambió, acumula `gasto_mes`, y marca `pausado_por_presupuesto:true` si
+ * el acumulado CRUZA (supera) el tope mensual. Persiste siempre con
+ * `escribirConfig` (atomic) — incluso con `usd:0`, que es como el runner de
+ * Fase B (T-05) registra una corrida dry-run: el contador es infra, no gasta.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {number} usd - Gasto a acumular (0 = solo inicializa/preserva el mes).
+ * @param {{ahora?: Date}} [opciones]
+ * @returns {{gasto_mes: number, mes: string, pausado_por_presupuesto: boolean}}
+ */
+function registrarGasto(baseDir, usd, { ahora } = {}) {
+  const st = estado(baseDir, { ahora });
+  const gastoNuevo = st.gasto_mes + usd;
+  const pausado = st.pausado_por_presupuesto || gastoNuevo > st.tope;
+
+  const siguiente = {
+    mes: st.mes,
+    gasto_mes: gastoNuevo,
+    pausado_por_presupuesto: pausado,
+  };
+  config.escribirConfig(baseDir, siguiente);
+
+  return siguiente;
+}
+
+module.exports = { mesActual, estado, estaPausado, puedeGastar, registrarGasto };