@saulwade/swl-ses 2.5.3 → 2.6.0

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

@@ -0,0 +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 };

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

@@ -0,0 +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 };

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

@@ -0,0 +1,301 @@
+'use strict';
+
+/**
+ * index.js — Orquestador Fase A del ciclo autónomo (Fase 21, T-07,
+ * ADR-0041/0042, REQ-21-02/REQ-21-09). Compone las tres sub-fases
+ * deterministas bajo opt-out estricto (nace encendido; el off es sagrado), con lock de exclusión mutua propio
+ * (T-02) y telemetría no-op-aware.
+ *
+ * Orden de composición: writer-instintos → puente-degradacion →
+ * drenador-feedback. El writer corre primero porque sus transiciones
+ * (promoción/degradación por decay o harmful_ratio) son la fuente primaria
+ * de scoring de `instintos/proyecto.yaml`. El puente corre ANTES que el
+ * drenador para que las degradaciones del día detectadas en APRENDIZAJES.md
+ * (que bajan confidence de instintos derivados) ya queden reflejadas en el
+ * YAML antes de que el drenador consolide señales nuevas de
+ * `perfil-usuario.yaml` en esta misma corrida.
+ *
+ * Cada sub-fase corre en su propio try/catch: una falla no aborta las
+ * otras — se acumula en `errores[]` con el nombre de la sub-fase.
+ *
+ * Opt-OUT estricto (regla de negocio 1 de la Fase 21, reformulada 2026-07-10
+ * por decisión del usuario — el motor nace encendido): este orquestador es el
+ * ÚNICO punto que consulta `config.estaHabilitado()` — las libs de sub-fase
+ * son puras y no consultan config.
+ *
+ * Fase 22 (T-06, REQ-22-06): al final de una corrida CON acciones (nunca en
+ * un no-op — el detector no debe pagar su costo cuando no hubo nada que
+ * hacer), detecta candidatos a Fase B (`candidatos.detectar`) y, si hay ≥1
+ * nuevo y `estaFaseBHabilitada`, spawnea el runner headless como proceso
+ * detached fire-and-forget (`stdio:'ignore'` + `unref`, NUNCA `execSync` —
+ * dictamen PM3, `scheduler.js:126` bloquearía otros jobs). El spawner es
+ * inyectable (`opts.spawner`) para tests deterministas sin procesos reales;
+ * el default resuelve el CLI de Fase B con `require.resolve` tolerante
+ * (ausente en el destino ⇒ no spawnea, nunca crashea). El spawn NUNCA
+ * bloquea ni espera, y cualquier error se traga con razón registrada — el
+ * hook/CLI padre no debe morir por esto. La detección SIEMPRE corre en la
+ * rama con acciones (aunque Fase B esté apagada) porque el conteo de
+ * candidatos va a la telemetría igual.
+ *
+ * Zero-deps, CommonJS.
+ *
+ * @module scripts/lib/ciclo-autonomo/index
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const config = require('./config');
+const lock = require('./lock');
+const writerInstintos = require('./writer-instintos');
+const drenadorFeedback = require('./drenador-feedback');
+const puenteDegradacion = require('./puente-degradacion');
+const higieneNudges = require('./higiene-nudges');
+const candidatos = require('./candidatos');
+
+/** Razones de no-ejecución expuestas para consumo de tests/CLI. */
+const RAZONES = Object.freeze({
+  DESHABILITADO: 'deshabilitado',
+  LOCK_OCUPADO: 'lock ocupado',
+});
+
+const RUTA_TELEMETRIA_RELATIVA = path.join('evolution', 'ciclo-autonomo.jsonl');
+
+function rutaTelemetria(baseDir) {
+  return path.join(baseDir, '.planning', RUTA_TELEMETRIA_RELATIVA);
+}
+
+function contadoresVacios() {
+  return {
+    promovidos: 0, degradados: 0, archivados: 0, candidatosGlobal: 0,
+    bajados: 0, drenados: 0, archivadosCola: 0, descartados: 0,
+    nudgesAtendidos: 0, nudgesArchivados: 0,
+  };
+}
+
+/** Ejecuta una sub-fase con try/catch propio; una falla se acumula en errores[] sin abortar. */
+function correrSubFase(nombre, fn, errores) {
+  try {
+    return fn();
+  } catch (_err) {
+    errores.push(nombre);
+    return null;
+  }
+}
+
+/** Fecha-hora local legible ("YYYY-MM-DD HH:mm:ss") — NUNCA toISOString (gate C1). */
+function fechaHoraLocal(momento) {
+  return `${momento.toLocaleDateString('sv')} ${momento.toLocaleTimeString('sv')}`;
+}
+
+/** Suma las tres sub-fases en los totales acumulados de la corrida. */
+function acumularSubFases(baseDir, momento, errores) {
+  const totales = contadoresVacios();
+
+  const resWriter = correrSubFase(
+    'writer-instintos',
+    () => writerInstintos.aplicarTransiciones(baseDir, { ahora: momento }),
+    errores
+  );
+  if (resWriter) {
+    totales.promovidos += resWriter.promovidos;
+    totales.degradados += resWriter.degradados;
+    totales.archivados += resWriter.archivados;
+    totales.candidatosGlobal += resWriter.candidatosGlobal;
+  }
+
+  const resPuente = correrSubFase(
+    'puente-degradacion',
+    () => puenteDegradacion.puentear(baseDir, { ahora: momento }),
+    errores
+  );
+  if (resPuente) totales.bajados += resPuente.bajados;
+
+  const resDrenador = correrSubFase(
+    'drenador-feedback',
+    () => drenadorFeedback.drenar(baseDir, { ahora: momento }),
+    errores
+  );
+  if (resDrenador) {
+    totales.drenados += resDrenador.drenados;
+    totales.archivadosCola += resDrenador.archivados;
+    totales.descartados += resDrenador.descartados;
+  }
+
+  // Higiene del ciclo de nudges (T-09/REQ-21-05 y REQ-21-13): si el drenador
+  // consolidó señales al perfil, los nudges `perfil-usuario` pendientes quedan
+  // atendidos por el ciclo; los nudges sin accionar más viejos que la ventana
+  // se archivan sin procesar (misma ventana de 90 días del bootstrap).
+  const resHigiene = correrSubFase('higiene-nudges', () => {
+    const atendidos = totales.drenados > 0
+      ? higieneNudges.marcarAccionado(baseDir, { kinds: ['perfil-usuario'], por: 'ciclo-autonomo', ahora: momento })
+      : { marcados: 0 };
+    const viejos = higieneNudges.archivarViejos(baseDir, { ahora: momento });
+    return { atendidos: atendidos.marcados, archivados: viejos.archivados };
+  }, errores);
+  if (resHigiene) {
+    totales.nudgesAtendidos += resHigiene.atendidos;
+    totales.nudgesArchivados += resHigiene.archivados;
+  }
+
+  return totales;
+}
+
+/** Total de acciones que decide si la corrida es no-op (candidatosGlobal y descartados NO cuentan). */
+function totalAcciones(totales) {
+  return totales.promovidos + totales.degradados + totales.archivados
+    + totales.bajados + totales.drenados + totales.archivadosCola
+    + totales.nudgesAtendidos + totales.nudgesArchivados;
+}
+
+/**
+ * Resuelve la ruta del CLI de Fase B (`scripts/cli/ciclo-fase-b.js`, T-07)
+ * con `require.resolve` tolerante — ausente en este destino (p.ej. antes de
+ * que T-07 lo registre, o un downstream que no distribuye `scripts/cli/`)
+ * ⇒ `null`, nunca crashea.
+ */
+function resolverRutaCliFaseB() {
+  try {
+    return require.resolve('../../cli/ciclo-fase-b');
+  } catch (err) {
+    if (err && err.code !== 'MODULE_NOT_FOUND') throw err;
+    return null;
+  }
+}
+
+/**
+ * Spawner por defecto del runner de Fase B: proceso detached fire-and-forget
+ * (`stdio:'ignore'` + `unref`) — NUNCA `execSync` (dictamen PM3,
+ * `scheduler.js:126` bloquearía otros jobs). Si el CLI no resuelve en este
+ * destino, no spawnea y registra la razón en vez de crashear.
+ */
+function spawnerFaseBPorDefecto(baseDir) {
+  const rutaCli = resolverRutaCliFaseB();
+  if (!rutaCli) return { spawneado: false, razon: 'cli-no-resuelve' };
+
+  const hijo = spawn(process.execPath, [rutaCli, '--dry-run'], {
+    cwd: baseDir,
+    detached: true,
+    stdio: 'ignore',
+  });
+  hijo.unref();
+  return { spawneado: true, pid: hijo.pid };
+}
+
+/**
+ * Detecta candidatos a Fase B y, si hay nuevos y Fase B está habilitada,
+ * spawnea el runner headless. La detección SIEMPRE corre en este punto (para
+ * que el conteo llegue a telemetría aunque Fase B esté apagada); el spawn se
+ * traga cualquier error del `spawner` (inyectado o por defecto) sin
+ * propagarlo — el orquestador de Fase A nunca debe morir por esto.
+ *
+ * @param {string} baseDir
+ * @param {Date} momento
+ * @param {Function} [spawner] - Inyectable para tests; default: proceso real.
+ * @returns {{candidatosNuevos: number, faseBSpawneada: boolean}}
+ */
+function intentarSpawnFaseB(baseDir, momento, spawner) {
+  const deteccion = candidatos.detectar(baseDir, { ahora: momento });
+  const candidatosNuevos = deteccion.nuevos;
+
+  if (candidatosNuevos < 1 || !config.estaFaseBHabilitada(baseDir)) {
+    return { candidatosNuevos, faseBSpawneada: false };
+  }
+
+  const spawnearFn = typeof spawner === 'function' ? spawner : spawnerFaseBPorDefecto;
+  let resultado;
+  try {
+    resultado = spawnearFn(baseDir);
+  } catch (_err) {
+    // El spawn NUNCA debe tumbar al proceso padre (hook/CLI): se traga el error.
+    resultado = { spawneado: false, razon: 'spawn-lanzo-error' };
+  }
+
+  return { candidatosNuevos, faseBSpawneada: Boolean(resultado && resultado.spawneado) };
+}
+
+/** Append de una entrada de telemetría a `.planning/evolution/ciclo-autonomo.jsonl`. */
+function escribirTelemetria(baseDir, totales, errores, faseB) {
+  const ruta = rutaTelemetria(baseDir);
+  const dir = path.dirname(ruta);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const entrada = {
+    ts: new Date().toISOString(), // telemetría de evento puntual — no fecha de artefacto (gate C1 no aplica)
+    origen: 'ciclo-autonomo',
+    promovidos: totales.promovidos,
+    degradados: totales.degradados,
+    archivados: totales.archivados,
+    candidatosGlobal: totales.candidatosGlobal,
+    bajados: totales.bajados,
+    drenados: totales.drenados,
+    archivadosCola: totales.archivadosCola,
+    descartados: totales.descartados,
+    nudgesAtendidos: totales.nudgesAtendidos,
+    nudgesArchivados: totales.nudgesArchivados,
+    candidatosNuevos: faseB.candidatosNuevos,
+    faseBSpawneada: faseB.faseBSpawneada,
+    errores,
+  };
+  fs.appendFileSync(ruta, JSON.stringify(entrada) + '\n');
+}
+
+/**
+ * Corre la Fase A del ciclo autónomo sobre `baseDir`.
+ *
+ * @param {string} baseDir - Directorio raíz del proyecto.
+ * @param {{ahora?: Date, forzar?: boolean, spawner?: Function}} [opciones]
+ *   `spawner` es inyectable (T-06, REQ-22-06): reemplaza el spawn real del
+ *   runner de Fase B en tests deterministas.
+ * @returns {object} `{ejecutado:false, razon}` si no corrió;
+ *   `{ejecutado:true, acciones:0}` si no-op; o el detalle completo de la
+ *   corrida (totales + `errores[]` + `candidatosNuevos` + `faseBSpawneada`)
+ *   si hubo al menos una acción.
+ */
+function correrFaseA(baseDir, { ahora, forzar = false, spawner } = {}) {
+  if (!config.estaHabilitado(baseDir) && !forzar) {
+    return { ejecutado: false, razon: RAZONES.DESHABILITADO };
+  }
+
+  const momento = ahora || new Date();
+  const { acquired, priorMtime } = lock.adquirir(baseDir);
+  if (!acquired) {
+    return { ejecutado: false, razon: RAZONES.LOCK_OCUPADO };
+  }
+
+  try {
+    const errores = [];
+    const totales = acumularSubFases(baseDir, momento, errores);
+    const acciones = totalAcciones(totales);
+
+    if (acciones === 0 && errores.length === 0) {
+      // NO-OP: la corrida no cuenta como última corrida real.
+      lock.rollback(baseDir, priorMtime);
+      return { ejecutado: true, acciones: 0 };
+    }
+
+    const resultadoFaseB = intentarSpawnFaseB(baseDir, momento, spawner);
+
+    escribirTelemetria(baseDir, totales, errores, resultadoFaseB);
+    config.escribirConfig(baseDir, {
+      last_run: fechaHoraLocal(momento),
+      ultima_corrida: {
+        promovidos: totales.promovidos,
+        degradados: totales.degradados,
+        drenados: totales.drenados,
+        archivados: totales.archivadosCola,
+        bajados: totales.bajados,
+      },
+    });
+    lock.liberar(baseDir);
+
+    return { ejecutado: true, acciones, ...totales, errores, ...resultadoFaseB };
+  } catch (err) {
+    // Error catastrófico fuera de las sub-fases: revertir el lock y relanzar.
+    lock.rollback(baseDir, priorMtime);
+    throw err;
+  }
+}
+
+module.exports = { correrFaseA, RAZONES };

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

@@ -0,0 +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,
+};