@saulwade/swl-ses 1.0.1 → 1.1.2

package/hooks/lib/delegation-tracker.js

@@ -10,13 +10,32 @@
  *   - Blocked toolsets (sin delegación recursiva, sin memoria compartida)
  *   - Reporte estructurado con duración y métricas
  *
- * Estado: en memoria por sesión (se resetea al reiniciar Claude Code).
+ * Persistencia: estado serializado a `${TMPDIR}/swl-delegation-${sessionId}.json`.
+ * Como cada hook se invoca en proceso Node fresco, el estado en variables de
+ * módulo no sobrevive entre invocaciones — el archivo es la fuente de verdad.
+ *
+ * Reconciliación tras /compact, /clear o reinicio:
+ *   - El cliente Claude Code emite un nuevo session_id en esos eventos.
+ *   - Al pasar un sessionId nuevo a las funciones API, se lee/escribe un
+ *     archivo distinto, descartando el estado anterior automáticamente.
+ *   - `cleanupStaleSessions()` purga archivos cuya última escritura supera el
+ *     TTL (default 1h) — protege contra leaks por sesiones que terminan sin
+ *     señalizar fin.
+ *
+ * Compatibilidad: si no se pasa sessionId (modo legacy), se usa estado
+ * en memoria del proceso. Funciona para tests unitarios y para invocaciones
+ * dentro de un mismo proceso, NO para coordinación entre hooks distintos.
+ *
  * Integración: risk-scoring.js consulta profundidad, tracking-costos.js
  * captura métricas por subagente.
  *
  * @module hooks/lib/delegation-tracker
  */
 
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
 // ---------------------------------------------------------------------------
 // Constantes
 // ---------------------------------------------------------------------------
@@ -27,18 +46,96 @@ const MAX_DELEGATION_DEPTH = 2;
 /** Máximo de subagentes ejecutándose en paralelo. */
 const MAX_CONCURRENT_CHILDREN = 3;
 
+/** TTL de archivos de estado huérfanos (ms). Default 1h. */
+const STALE_TTL_MS = 60 * 60 * 1000;
+
 // ---------------------------------------------------------------------------
-// Estado en memoria (por sesión)
+// Persistencia file-based (por sessionId) y memoria (legacy / fallback)
 // ---------------------------------------------------------------------------
 
-/** Stack de delegaciones activas. */
-const _delegationStack = [];
+/** Estado en memoria del proceso (modo legacy, sin sessionId). */
+const _memState = {
+  delegationStack: [],
+  activeChildren: 0,
+  completedDelegations: [],
+};
+
+/** Path del archivo de estado para una sesión. */
+function _statePath(sessionId) {
+  return path.join(os.tmpdir(), `swl-delegation-${sessionId}.json`);
+}
 
-/** Contador de hijos activos. */
-let _activeChildren = 0;
+/** Lee el estado de una sesión desde archivo, o devuelve estado vacío. */
+function _readState(sessionId) {
+  if (!sessionId) return _memState;
+  try {
+    const raw = fs.readFileSync(_statePath(sessionId), 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      delegationStack:     Array.isArray(parsed.delegationStack)     ? parsed.delegationStack     : [],
+      activeChildren:      Number.isInteger(parsed.activeChildren)   ? parsed.activeChildren      : 0,
+      completedDelegations: Array.isArray(parsed.completedDelegations) ? parsed.completedDelegations : [],
+    };
+  } catch (_) {
+    return { delegationStack: [], activeChildren: 0, completedDelegations: [] };
+  }
+}
+
+/** Escribe el estado de una sesión a archivo (atómico-ish: write + rename). */
+function _writeState(sessionId, state) {
+  if (!sessionId) {
+    _memState.delegationStack      = state.delegationStack;
+    _memState.activeChildren       = state.activeChildren;
+    _memState.completedDelegations = state.completedDelegations;
+    return;
+  }
+  try {
+    const target = _statePath(sessionId);
+    const tmp    = target + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(state), 'utf8');
+    fs.renameSync(tmp, target);
+  } catch (_) {
+    // No bloquear el flujo si falla escritura — el módulo es advisory.
+  }
+}
 
-/** Historial de delegaciones completadas (para métricas). */
-const _completedDelegations = [];
+/**
+ * Purga archivos de estado de sesiones huérfanas.
+ * Una sesión "muerta" es la que no recibió update en STALE_TTL_MS.
+ *
+ * Llamar al iniciar trabajo nuevo o desde `/swl:salud` para evitar leaks.
+ *
+ * @param {number} [ttlMs=STALE_TTL_MS] - TTL en ms.
+ * @returns {{ removed: string[], kept: string[] }}
+ */
+function cleanupStaleSessions(ttlMs = STALE_TTL_MS) {
+  const tmpDir = os.tmpdir();
+  const removed = [];
+  const kept    = [];
+  const now     = Date.now();
+  let entries;
+  try {
+    entries = fs.readdirSync(tmpDir);
+  } catch (_) {
+    return { removed, kept };
+  }
+  for (const entry of entries) {
+    if (!/^swl-delegation-.+\.json$/.test(entry)) continue;
+    const fullPath = path.join(tmpDir, entry);
+    try {
+      const stat = fs.statSync(fullPath);
+      if (now - stat.mtimeMs > ttlMs) {
+        fs.unlinkSync(fullPath);
+        removed.push(entry);
+      } else {
+        kept.push(entry);
+      }
+    } catch (_) {
+      // Archivo desapareció en condición de carrera — ignorar.
+    }
+  }
+  return { removed, kept };
+}
 
 // ---------------------------------------------------------------------------
 // API pública
@@ -47,26 +144,29 @@ const _completedDelegations = [];
 /**
  * Verifica si una delegación es permitida.
  *
- * @param {string} agentName - Nombre del agente que solicita delegar.
+ * @param {string} agentName    - Nombre del agente que solicita delegar.
+ * @param {string} [sessionId]  - ID de sesión Claude Code. Si se omite, usa
+ *                                estado en memoria (modo legacy).
  * @returns {{ allowed: boolean, reason?: string, depth?: number }}
  */
-function canDelegate(agentName) {
-  const currentDepth = _delegationStack.length;
+function canDelegate(agentName, sessionId) {
+  const state = _readState(sessionId);
+  const currentDepth = state.delegationStack.length;
 
   if (currentDepth >= MAX_DELEGATION_DEPTH) {
     return {
       allowed: false,
       reason: `Profundidad máxima de delegación alcanzada (${MAX_DELEGATION_DEPTH}). ` +
-              `Stack actual: ${_delegationStack.map(d => d.agentName).join(' → ')}. ` +
+              `Stack actual: ${state.delegationStack.map(d => d.agentName).join(' → ')}. ` +
               `No se permite delegación adicional para prevenir recursión.`,
     };
   }
 
-  if (_activeChildren >= MAX_CONCURRENT_CHILDREN) {
+  if (state.activeChildren >= MAX_CONCURRENT_CHILDREN) {
     return {
       allowed: false,
       reason: `Máximo de subagentes concurrentes alcanzado (${MAX_CONCURRENT_CHILDREN}). ` +
-              `Activos: ${_delegationStack.filter(d => d.active).map(d => d.agentName).join(', ')}. ` +
+              `Activos: ${state.delegationStack.filter(d => d.active).map(d => d.agentName).join(', ')}. ` +
               `Esperar a que terminen antes de delegar.`,
     };
   }
@@ -77,23 +177,26 @@ function canDelegate(agentName) {
 /**
  * Registra el inicio de una delegación.
  *
- * @param {string} agentName - Nombre del agente delegado.
- * @param {string} [taskId]  - ID de la tarea (para correlación).
+ * @param {string} agentName    - Nombre del agente delegado.
+ * @param {string} [taskId]     - ID de la tarea (para correlación).
+ * @param {string} [sessionId]  - ID de sesión Claude Code.
  * @returns {string} ID único de la delegación (para trackDelegationComplete).
  */
-function trackDelegationStart(agentName, taskId) {
+function trackDelegationStart(agentName, taskId, sessionId) {
+  const state = _readState(sessionId);
   const delegationId = `del-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
 
-  _delegationStack.push({
+  state.delegationStack.push({
     delegationId,
     agentName,
     taskId: taskId || delegationId,
-    depth: _delegationStack.length,
+    depth: state.delegationStack.length,
     startTime: Date.now(),
     active: true,
   });
 
-  _activeChildren++;
+  state.activeChildren += 1;
+  _writeState(sessionId, state);
   return delegationId;
 }
 
@@ -105,18 +208,19 @@ function trackDelegationStart(agentName, taskId) {
  * @param {string} [result.status='completed'] - Estado final.
  * @param {number} [result.tokensUsed]         - Tokens consumidos.
  * @param {number} [result.toolCalls]          - Herramientas invocadas.
+ * @param {string} [sessionId]  - ID de sesión Claude Code.
  * @returns {object|null} Métricas de la delegación, o null si no se encontró.
  */
-function trackDelegationComplete(delegationId, result = {}) {
-  const idx = _delegationStack.findIndex(d => d.delegationId === delegationId);
+function trackDelegationComplete(delegationId, result = {}, sessionId) {
+  const state = _readState(sessionId);
+  const idx = state.delegationStack.findIndex(d => d.delegationId === delegationId);
   if (idx < 0) return null;
 
-  const entry = _delegationStack[idx];
+  const entry = state.delegationStack[idx];
   entry.active = false;
-  _activeChildren = Math.max(0, _activeChildren - 1);
+  state.activeChildren = Math.max(0, state.activeChildren - 1);
 
-  // Remover del stack
-  _delegationStack.splice(idx, 1);
+  state.delegationStack.splice(idx, 1);
 
   const completed = {
     delegationId,
@@ -129,19 +233,17 @@ function trackDelegationComplete(delegationId, result = {}) {
     toolCalls: result.toolCalls || 0,
   };
 
-  _completedDelegations.push(completed);
-
-  // Mantener solo las últimas 50 delegaciones completadas
-  if (_completedDelegations.length > 50) {
-    _completedDelegations.shift();
-  }
+  state.completedDelegations.push(completed);
+  if (state.completedDelegations.length > 50) state.completedDelegations.shift();
 
+  _writeState(sessionId, state);
   return completed;
 }
 
 /**
  * Obtiene el estado actual de delegación.
  *
+ * @param {string} [sessionId]  - ID de sesión Claude Code.
  * @returns {{
  *   currentDepth: number,
  *   activeChildren: number,
@@ -151,19 +253,20 @@ function trackDelegationComplete(delegationId, result = {}) {
  *   recentCompleted: object[]
  * }}
  */
-function getDelegationState() {
+function getDelegationState(sessionId) {
+  const state = _readState(sessionId);
   return {
-    currentDepth: _delegationStack.length,
-    activeChildren: _activeChildren,
+    currentDepth: state.delegationStack.length,
+    activeChildren: state.activeChildren,
     maxDepth: MAX_DELEGATION_DEPTH,
     maxConcurrent: MAX_CONCURRENT_CHILDREN,
-    stack: _delegationStack.map(d => ({
+    stack: state.delegationStack.map(d => ({
       agent: d.agentName,
       depth: d.depth,
       elapsedMs: Date.now() - d.startTime,
       active: d.active,
     })),
-    recentCompleted: _completedDelegations.slice(-10),
+    recentCompleted: state.completedDelegations.slice(-10),
   };
 }
 
@@ -171,19 +274,32 @@ function getDelegationState() {
  * Calcula el factor de riesgo adicional por profundidad de delegación.
  * Diseñado para integrarse con risk-scoring.js.
  *
+ * @param {string} [sessionId]  - ID de sesión Claude Code.
  * @returns {number} Factor entre 0.0 y 0.30 (0.15 por nivel de profundidad).
  */
-function getDelegationRiskFactor() {
-  return Math.min(_delegationStack.length * 0.15, 0.30);
+function getDelegationRiskFactor(sessionId) {
+  const state = _readState(sessionId);
+  return Math.min(state.delegationStack.length * 0.15, 0.30);
 }
 
 /**
- * Resetea el estado de delegación (para tests o nueva sesión).
+ * Resetea el estado de delegación (para tests o reconciliación explícita).
+ *
+ * @param {string} [sessionId]  - ID de sesión a resetear. Si se omite, resetea
+ *                                el estado en memoria (modo legacy).
  */
-function reset() {
-  _delegationStack.length = 0;
-  _activeChildren = 0;
-  _completedDelegations.length = 0;
+function reset(sessionId) {
+  if (!sessionId) {
+    _memState.delegationStack.length = 0;
+    _memState.activeChildren = 0;
+    _memState.completedDelegations.length = 0;
+    return;
+  }
+  try {
+    fs.unlinkSync(_statePath(sessionId));
+  } catch (_) {
+    // No existe → ya está reseteado.
+  }
 }
 
 module.exports = {
@@ -193,6 +309,8 @@ module.exports = {
   getDelegationState,
   getDelegationRiskFactor,
   reset,
+  cleanupStaleSessions,
   MAX_DELEGATION_DEPTH,
   MAX_CONCURRENT_CHILDREN,
+  STALE_TTL_MS,
 };

package/hooks/lib/evolution-tracker.js

@@ -19,6 +19,15 @@
 const fs   = require('fs');
 const path = require('path');
 
+// Escritura atómica obligatoria (regla CLAUDE.md). Fallback defensivo.
+let atomicWriteSync, atomicWriteJSON;
+try {
+  ({ atomicWriteSync, atomicWriteJSON } = require('./atomic-write'));
+} catch {
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
 // ---------------------------------------------------------------------------
 // Constantes
 // ---------------------------------------------------------------------------
@@ -167,7 +176,7 @@ function markAsEvolved(filePath, meta) {
     frontmatter = frontmatter.trimEnd() + '\n' + newFields.join('\n');
 
     const newContent = prefix + frontmatter + suffix + rest;
-    fs.writeFileSync(filePath, newContent, 'utf8');
+    atomicWriteSync(filePath, newContent, 'utf8');
 
     return { marked: true };
   } catch (err) {
@@ -200,7 +209,7 @@ function _writeSidecar(filePath, meta) {
     ...(meta.note && { evolvedNote: meta.note }),
   };
 
-  fs.writeFileSync(sidecarPath, JSON.stringify(data, null, 2), 'utf8');
+  atomicWriteJSON(sidecarPath, data);
   return { marked: true };
 }
 
@@ -368,7 +377,7 @@ function mergeEvolved(destino, origen, versionNueva) {
       ]).flat(),
     ].join('\n');
 
-    fs.writeFileSync(diffPath, diffContent, 'utf8');
+    atomicWriteSync(diffPath, diffContent, 'utf8');
 
     return { merged: true, diffPath, diffsCount: diffs.length };
   } catch (err) {

package/hooks/lib/memory-search.js

@@ -499,8 +499,66 @@ function fetch(baseDir, id) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Instrumentación de utilidad — registra cada búsqueda a JSONL para que
+// metricas-evolucion.js pueda calcular utilidad como proxy.
+//
+// Formato del registro:
+//   { ts, sessionId, op: 'search'|'timeline'|'fetch', query, resultsCount,
+//     baseDir }
+//
+// Opt-out: SWL_MEMORY_TELEMETRY=0 desactiva el logging.
+// ---------------------------------------------------------------------------
+
+function _logUsage(op, baseDir, query, resultsCount) {
+  if (process.env.SWL_MEMORY_TELEMETRY === '0') return;
+  try {
+    const dir = path.join(baseDir, '.planning', 'evolucion');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const entry = {
+      ts: new Date().toISOString(),
+      sessionId: String(process.env.SWL_SESSION_ID || process.env.CLAUDE_SESSION_ID || 'default'),
+      op,
+      query: typeof query === 'string' ? query.slice(0, 200) : String(query || '').slice(0, 200),
+      resultsCount: Number.isInteger(resultsCount) ? resultsCount : 0,
+    };
+    fs.appendFileSync(
+      path.join(dir, 'memory-usage.jsonl'),
+      JSON.stringify(entry) + '\n',
+      'utf8',
+    );
+  } catch { /* nunca bloquear por fallo de telemetría */ }
+}
+
+const _searchInstrumented = (baseDir, query, filtros = {}) => {
+  const results = search(baseDir, query, filtros);
+  _logUsage('search', baseDir, query, Array.isArray(results) ? results.length : 0);
+  return results;
+};
+
+const _timelineInstrumented = (baseDir, ids) => {
+  const results = timeline(baseDir, ids);
+  const idsCount = Array.isArray(ids) ? ids.length : 0;
+  _logUsage('timeline', baseDir, `[${idsCount} ids]`, Array.isArray(results) ? results.length : 0);
+  return results;
+};
+
+const _fetchInstrumented = (baseDir, id) => {
+  const result = fetch(baseDir, id);
+  _logUsage('fetch', baseDir, String(id), result ? 1 : 0);
+  return result;
+};
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
 
-module.exports = { search, timeline, fetch };
+module.exports = {
+  search:   _searchInstrumented,
+  timeline: _timelineInstrumented,
+  fetch:    _fetchInstrumented,
+  // Versiones sin instrumentación, para tests internos.
+  _searchRaw:   search,
+  _timelineRaw: timeline,
+  _fetchRaw:    fetch,
+};

package/hooks/lib/nudge-tracker.js

@@ -23,6 +23,15 @@
 
 const fs   = require('fs');
 const path = require('path');
+
+// Escritura atómica para reescritura completa del JSONL (marcar accionado).
+// El append diario sigue usando appendFileSync (ver más abajo).
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require('./atomic-write'));
+} catch {
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+}
 const crypto = require('crypto');
 
 let atomicWriteJSON;
@@ -161,7 +170,7 @@ function markAccionado(id, by = 'desconocido') {
   ensureDir();
   const lines = entries.map(e => JSON.stringify(e)).join('\n') + '\n';
   try {
-    fs.writeFileSync(LOG_PATH, lines, 'utf8');
+    atomicWriteSync(LOG_PATH, lines, 'utf8');
     return true;
   } catch {
     return false;

package/hooks/lib/provenance-tracker.js

@@ -29,6 +29,14 @@
 const fs   = require('fs');
 const path = require('path');
 
+// Escritura atómica obligatoria para meta.json (regla CLAUDE.md).
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('./atomic-write'));
+} catch {
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
 // ---------------------------------------------------------------------------
 // Constantes
 // ---------------------------------------------------------------------------
@@ -93,13 +101,13 @@ function registrarProveniencia(componentDir, datos) {
       Object.assign(existing, meta);
       existing.history = existing.history.slice(-5); // Máximo 5 entradas de historial
 
-      fs.writeFileSync(metaPath, JSON.stringify(existing, null, 2), 'utf8');
+      atomicWriteJSON(metaPath, existing);
     } catch {
       // Error leyendo existente — sobrescribir
-      fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+      atomicWriteJSON(metaPath, meta);
     }
   } else {
-    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+    atomicWriteJSON(metaPath, meta);
   }
 }