theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/scripts/hooks/session-start.js

@@ -0,0 +1,906 @@
+#!/usr/bin/env node
+/**
+ * Hook de SessionStart - Cargar el contexto previo al iniciar una sesión
+ *
+ * Multiplataforma (Windows, macOS, Linux)
+ *
+ * Se ejecuta cuando arranca una nueva sesión de Theus. Carga el resumen de la
+ * sesión más reciente en el contexto vía stdout, reporta las sesiones y skills
+ * aprendidas disponibles, y carga las reglas y contextos del plugin desde
+ * ${THEUS_PLUGIN_ROOT}/rules y ${THEUS_PLUGIN_ROOT}/contexts si existen.
+ */
+
+const {
+  getSessionsDir,
+  getSessionSearchDirs,
+  getLearnedSkillsDir,
+  getProjectName,
+  findFiles,
+  ensureDir,
+  readFile,
+  stripAnsi,
+  log
+} = require('../lib/utils');
+const { resolveProjectContext, writeSessionLease, resolveSessionId, getObserverDataDir } = require('../lib/observer-sessions');
+const { getPackageManager, getSelectionPrompt } = require('../lib/package-manager');
+const { listAliases } = require('../lib/session-aliases');
+const { detectProjectType } = require('../lib/project-detect');
+const path = require('path');
+const fs = require('fs');
+
+const DEFAULT_INSTINCT_CONFIDENCE_THRESHOLD = 0.7;
+const DEFAULT_MAX_INJECTED_INSTINCTS = 6;
+const MAX_INJECTED_LEARNED_SKILLS = 6;
+const MAX_LEARNED_SKILL_SUMMARY_CHARS = 220;
+const DEFAULT_SESSION_START_CONTEXT_MAX_CHARS = 8000;
+const DEFAULT_SESSION_RETENTION_DAYS = 30;
+const MAX_PLUGIN_RESOURCE_CHARS = 4000;
+const SESSION_START_MODE_INVALID = 'invalid';
+const SESSION_START_MODE_SKIP = 'skip';
+
+/**
+ * Resuelve una ruta del sistema de archivos a su forma canónica (real).
+ *
+ * Maneja symlinks y, en sistemas de archivos que no distinguen mayúsculas
+ * (macOS, Windows), normaliza el uso de mayúsculas para que las comparaciones
+ * de rutas sean confiables. Recurre a la ruta original si la resolución falla
+ * (p. ej., la ruta ya no existe).
+ *
+ * @param {string} p - La ruta a normalizar.
+ * @returns {string} La ruta canónica, o la original si la resolución falla.
+ */
+function normalizePath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function dedupeRecentSessions(searchDirs) {
+  const recentSessionsByName = new Map();
+
+  for (const [dirIndex, dir] of searchDirs.entries()) {
+    const matches = findFiles(dir, '*-session.tmp', { maxAge: 7 });
+
+    for (const match of matches) {
+      const basename = path.basename(match.path);
+      const current = {
+        ...match,
+        basename,
+        dirIndex,
+      };
+      const existing = recentSessionsByName.get(basename);
+
+      if (
+        !existing
+        || current.mtime > existing.mtime
+        || (current.mtime === existing.mtime && current.dirIndex < existing.dirIndex)
+      ) {
+        recentSessionsByName.set(basename, current);
+      }
+    }
+  }
+
+  return Array.from(recentSessionsByName.values())
+    .sort((left, right) => right.mtime - left.mtime || left.dirIndex - right.dirIndex);
+}
+
+/**
+ * Resuelve los días de retención de sesiones desde la variable de entorno
+ * THEUS_SESSION_RETENTION_DAYS.
+ *
+ * @returns {number|null} La ventana de retención en días, o `null` cuando el
+ *   usuario optó explícitamente por no purgar. Valores vacíos o basura caen
+ *   al valor por defecto {@link DEFAULT_SESSION_RETENTION_DAYS}.
+ */
+function getSessionRetentionDays() {
+  const raw = process.env.THEUS_SESSION_RETENTION_DAYS;
+  if (!raw) return DEFAULT_SESSION_RETENTION_DAYS;
+
+  const normalized = String(raw).trim().toLowerCase();
+  if (['0', 'off', 'false', 'disabled', 'never', 'none'].includes(normalized)) {
+    return null;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_SESSION_RETENTION_DAYS;
+}
+
+function isSessionStartContextDisabled() {
+  const raw = String(process.env.THEUS_SESSION_START_CONTEXT || '').trim().toLowerCase();
+  return ['0', 'false', 'off', 'none', 'disabled'].includes(raw);
+}
+
+function getSessionStartMaxContextChars() {
+  const raw = process.env.THEUS_SESSION_START_MAX_CHARS;
+  if (!raw) return DEFAULT_SESSION_START_CONTEXT_MAX_CHARS;
+
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : DEFAULT_SESSION_START_CONTEXT_MAX_CHARS;
+}
+
+/**
+ * Resuelve la confianza mínima que necesita un instinto para inyectarse en
+ * SessionStart. Sobrescribible vía `THEUS_INSTINCT_CONFIDENCE_THRESHOLD`
+ * (un número en [0, 1]); valores vacíos o fuera de rango caen al valor por
+ * defecto {@link DEFAULT_INSTINCT_CONFIDENCE_THRESHOLD}.
+ *
+ * @returns {number} El piso de confianza para instintos inyectados.
+ */
+function getInstinctConfidenceThreshold() {
+  const raw = process.env.THEUS_INSTINCT_CONFIDENCE_THRESHOLD;
+  if (!raw) return DEFAULT_INSTINCT_CONFIDENCE_THRESHOLD;
+
+  // Exigir un decimal plano (p. ej. "0.7", "1", "0.95") para que la basura al
+  // final ("0.7x") y la sintaxis numérica no decimal como "0x1" (hexadecimal)
+  // o "1e2" (exponente) se rechacen por completo en lugar de que Number() las
+  // acepte en silencio.
+  const normalized = raw.trim();
+  if (!/^\d+(\.\d+)?$/.test(normalized)) return DEFAULT_INSTINCT_CONFIDENCE_THRESHOLD;
+
+  const parsed = Number(normalized);
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1
+    ? parsed
+    : DEFAULT_INSTINCT_CONFIDENCE_THRESHOLD;
+}
+
+/**
+ * Resuelve la cantidad máxima de instintos inyectados en SessionStart.
+ * Sobrescribible vía `THEUS_MAX_INJECTED_INSTINCTS` (un entero positivo);
+ * valores vacíos o inválidos caen al valor por defecto
+ * {@link DEFAULT_MAX_INJECTED_INSTINCTS}.
+ *
+ * @returns {number} El tope de instintos inyectados.
+ */
+function getMaxInjectedInstincts() {
+  const raw = process.env.THEUS_MAX_INJECTED_INSTINCTS;
+  if (!raw) return DEFAULT_MAX_INJECTED_INSTINCTS;
+
+  // Exigir un entero no negativo plano para que "3.9", "6abc", "0x1"
+  // (hexadecimal) y "1e2" (exponente) se rechacen por completo y caigan al
+  // valor por defecto, en lugar de que parseInt trunque o Number() acepte
+  // sintaxis alternativa.
+  const normalized = raw.trim();
+  if (!/^\d+$/.test(normalized)) return DEFAULT_MAX_INJECTED_INSTINCTS;
+
+  const parsed = Number(normalized);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_INJECTED_INSTINCTS;
+}
+
+function parseSessionStartPayload(rawInput) {
+  const input = String(rawInput || '');
+  if (!input.trim()) return { mode: null, sessionId: null };
+
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    log(`[SessionStart] Payload de stdin inválido; se omite la inyección del resumen de la sesión previa. Longitud: ${input.length}`);
+    return { mode: SESSION_START_MODE_INVALID, sessionId: null };
+  }
+
+  const sessionId = payload && typeof payload.session_id === 'string' && payload.session_id.trim()
+    ? payload.session_id.trim()
+    : null;
+
+  const supportedModes = new Set(['startup', 'resume', 'clear', 'compact']);
+
+  if (payload.hook_event_name === 'SessionStart') {
+    const mode = typeof payload.source === 'string' ? payload.source.trim().toLowerCase() : '';
+    return { mode: supportedModes.has(mode) ? mode : SESSION_START_MODE_SKIP, sessionId };
+  }
+
+  return { mode: SESSION_START_MODE_SKIP, sessionId };
+}
+
+function limitSessionStartContext(additionalContext, maxChars = getSessionStartMaxContextChars()) {
+  const context = String(additionalContext || '');
+
+  if (context.length <= maxChars) {
+    return context;
+  }
+
+  const marker = '\n\n[SessionStart truncó el contexto. Define THEUS_SESSION_START_MAX_CHARS para subir el tope o THEUS_SESSION_START_CONTEXT=off para desactivar el contexto inyectado.]';
+  const prefixLength = Math.max(0, maxChars - marker.length);
+  log(`[SessionStart] Contexto adicional truncado de ${context.length} a ${maxChars} caracteres`);
+
+  return `${context.slice(0, prefixLength).trimEnd()}${marker}`.slice(0, maxChars);
+}
+
+function pruneExpiredSessions(searchDirs, retentionDays) {
+  const uniqueDirs = Array.from(new Set(searchDirs.filter(dir => typeof dir === 'string' && dir.length > 0)));
+  let removed = 0;
+
+  for (const dir of uniqueDirs) {
+    if (!fs.existsSync(dir)) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('-session.tmp')) continue;
+
+      const fullPath = path.join(dir, entry.name);
+      let stats;
+      try {
+        stats = fs.statSync(fullPath);
+      } catch {
+        continue;
+      }
+
+      const ageInDays = (Date.now() - stats.mtimeMs) / (1000 * 60 * 60 * 24);
+      if (ageInDays <= retentionDays) continue;
+
+      try {
+        fs.rmSync(fullPath, { force: true });
+        removed += 1;
+      } catch (error) {
+        log(`[SessionStart] Advertencia: no se pudo purgar la sesión expirada ${fullPath}: ${error.message}`);
+      }
+    }
+  }
+
+  return removed;
+}
+
+/**
+ * Carga los archivos Markdown de un directorio de recursos del plugin
+ * (${THEUS_PLUGIN_ROOT}/rules o ${THEUS_PLUGIN_ROOT}/contexts) si existen.
+ *
+ * @param {string} dirName - Nombre del subdirectorio dentro de la raíz del plugin.
+ * @param {string} label - Etiqueta visible del bloque inyectado.
+ * @returns {string} El bloque de contexto, o cadena vacía si no hay nada que cargar.
+ */
+/**
+ * Construye un índice compacto de las reglas del plugin
+ * (${THEUS_PLUGIN_ROOT}/rules/<grupo>/*.md) para inyectarlo como contexto.
+ *
+ * Las reglas están organizadas en subdirectorios por lenguaje/tema y suman
+ * decenas de archivos: inyectarlas completas reventaría el presupuesto de
+ * contexto de la sesión. En su lugar se inyecta el mapa de grupos y archivos
+ * con la instrucción de leer el archivo pertinente al trabajar en cada área.
+ *
+ * @returns {string} El bloque de índice, o cadena vacía si no hay reglas.
+ */
+function loadPluginRulesIndex() {
+  const pluginRoot = String(process.env.THEUS_PLUGIN_ROOT || '').trim();
+  if (!pluginRoot) return '';
+
+  const rulesDir = path.join(pluginRoot, 'rules');
+  if (!fs.existsSync(rulesDir)) return '';
+
+  let groups;
+  try {
+    groups = fs.readdirSync(rulesDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name)
+      .sort((a, b) => (a === 'common' ? -1 : b === 'common' ? 1 : a.localeCompare(b)));
+  } catch (error) {
+    log(`[SessionStart] Advertencia: no se pudo leer ${rulesDir}: ${error.message}`);
+    return '';
+  }
+
+  const lines = [];
+  for (const group of groups) {
+    let files;
+    try {
+      files = fs.readdirSync(path.join(rulesDir, group))
+        .filter(name => /\.md$/i.test(name))
+        .map(name => name.replace(/\.md$/i, ''))
+        .sort();
+    } catch {
+      continue;
+    }
+    if (files.length === 0) continue;
+    const nota = group === 'common' ? ' (aplican a todo el código, en cualquier lenguaje)' : '';
+    lines.push(`- ${group}${nota}: ${files.join(', ')}`);
+  }
+
+  if (lines.length === 0) return '';
+
+  log(`[SessionStart] Inyectando índice de reglas del plugin (${lines.length} grupos)`);
+  return [
+    'Reglas de calidad del arsenal:',
+    '',
+    `El plugin incluye reglas de estilo, patrones, seguridad y testing en \`${rulesDir}/<grupo>/<archivo>.md\`.`,
+    'Antes de escribir o revisar código de una de estas áreas, lee con la tool Read el archivo pertinente (como mínimo security y patterns del grupo, más los de common):',
+    ...lines,
+  ].join('\n');
+}
+
+function loadPluginResources(dirName, label) {
+  const pluginRoot = String(process.env.THEUS_PLUGIN_ROOT || '').trim();
+  if (!pluginRoot) return '';
+
+  const dir = path.join(pluginRoot, dirName);
+  if (!fs.existsSync(dir)) return '';
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+      .filter(entry => entry.isFile() && /\.md$/i.test(entry.name))
+      .sort((left, right) => left.name.localeCompare(right.name));
+  } catch (error) {
+    log(`[SessionStart] Advertencia: no se pudo leer ${dir}: ${error.message}`);
+    return '';
+  }
+
+  if (entries.length === 0) return '';
+
+  const parts = [];
+  let used = 0;
+  for (const entry of entries) {
+    const filePath = path.join(dir, entry.name);
+    const content = readFile(filePath);
+    if (!content) continue;
+
+    const trimmed = content.trim();
+    const remaining = MAX_PLUGIN_RESOURCE_CHARS - used;
+    if (remaining <= 0) {
+      parts.push(`- ${entry.name}: omitido por límite de tamaño`);
+      continue;
+    }
+
+    const slice = trimmed.length > remaining ? `${trimmed.slice(0, remaining).trimEnd()}\n[...truncado]` : trimmed;
+    used += slice.length;
+    parts.push(`### ${entry.name}\n${slice}`);
+  }
+
+  if (parts.length === 0) return '';
+
+  log(`[SessionStart] Cargando ${parts.length} archivo(s) de ${dirName}/ del plugin`);
+  return `${label}:\n\n${parts.join('\n\n')}`;
+}
+
+/**
+ * Selecciona la sesión que mejor coincide con el directorio de trabajo actual.
+ *
+ * Los archivos de sesión escritos por session-end.js contienen campos de
+ * encabezado como:
+ *   **Proyecto:** mi-proyecto
+ *   **Worktree:** /ruta/al/proyecto
+ *
+ * Esta función lee cada archivo de sesión una sola vez, cacheando su
+ * contenido, y devuelve tanto el objeto de sesión seleccionado como su
+ * contenido ya leído para evitar E/S duplicada en el llamador.
+ *
+ * Prioridad (de mayor a menor):
+ *   1. Coincidencia exacta de worktree (cwd) — la más reciente
+ *   2. Coincidencia por nombre de proyecto para sesiones legacy sin metadatos de Worktree
+ *   3. Sin inyección cuando las sesiones pertenecen a otro worktree/proyecto
+ *
+ * Las sesiones ya vienen ordenadas de más reciente a más antigua, así que la
+ * primera coincidencia de cada categoría gana.
+ *
+ * @param {Array<Object>} sessions - Lista de sesiones deduplicada, más recientes primero.
+ * @param {string} cwd - Directorio de trabajo actual (process.cwd()).
+ * @param {string} currentProject - Nombre del proyecto actual según getProjectName().
+ * @returns {{ session: Object, content: string, matchReason: string } | null}
+ *   La sesión que mejor coincide con su contenido cacheado y el motivo de la
+ *   coincidencia, o null si la lista está vacía o ningún archivo es legible.
+ */
+function selectMatchingSession(sessions, cwd, currentProject) {
+  if (sessions.length === 0) return null;
+
+  // Normalizar cwd una vez fuera del bucle para evitar syscalls repetidas
+  const normalizedCwd = normalizePath(cwd);
+
+  let projectMatch = null;
+  let projectMatchContent = null;
+  let readableSessions = 0;
+
+  for (const session of sessions) {
+    const content = readFile(session.path);
+    if (!content) continue;
+    readableSessions++;
+
+    // Extraer el campo **Worktree:**
+    const worktreeMatch = content.match(/\*\*Worktree:\*\*\s*(.+)$/m);
+    const sessionWorktree = worktreeMatch ? worktreeMatch[1].trim() : '';
+
+    // Coincidencia exacta de worktree — la mejor posible, retornar de inmediato.
+    // Normalizar ambas rutas para manejar symlinks y sistemas de archivos que
+    // no distinguen mayúsculas
+    if (sessionWorktree && normalizePath(sessionWorktree) === normalizedCwd) {
+      return { session, content, matchReason: 'worktree' };
+    }
+
+    // La coincidencia por nombre de proyecto solo es segura para archivos de
+    // sesión legacy escritos antes de que existieran los metadatos de
+    // Worktree. Un Worktree explícito distinto no es una coincidencia.
+    if (!projectMatch && currentProject && !sessionWorktree) {
+      const projectFieldMatch = content.match(/\*\*Proyecto:\*\*\s*(.+)$/m);
+      const sessionProject = projectFieldMatch ? projectFieldMatch[1].trim() : '';
+      if (sessionProject && sessionProject === currentProject) {
+        projectMatch = session;
+        projectMatchContent = content;
+      }
+    }
+  }
+
+  if (projectMatch) {
+    return { session: projectMatch, content: projectMatchContent, matchReason: 'project' };
+  }
+
+  log(readableSessions > 0
+    ? '[SessionStart] No se encontró una sesión que coincida por worktree/proyecto'
+    : '[SessionStart] Ningún archivo de sesión fue legible');
+  return null;
+}
+
+function parseInstinctFile(content) {
+  const instincts = [];
+  let current = null;
+  let inFrontmatter = false;
+  let contentLines = [];
+
+  for (const line of String(content).split('\n')) {
+    if (line.trim() === '---') {
+      if (inFrontmatter) {
+        inFrontmatter = false;
+      } else {
+        if (current && current.id) {
+          current.content = contentLines.join('\n').trim();
+          instincts.push(current);
+        }
+        current = {};
+        contentLines = [];
+        inFrontmatter = true;
+      }
+      continue;
+    }
+
+    if (inFrontmatter) {
+      const separatorIndex = line.indexOf(':');
+      if (separatorIndex === -1) continue;
+      const key = line.slice(0, separatorIndex).trim();
+      let value = line.slice(separatorIndex + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      if (key === 'confidence') {
+        const parsed = Number.parseFloat(value);
+        current[key] = Number.isFinite(parsed) ? parsed : 0.5;
+      } else {
+        current[key] = value;
+      }
+    } else if (current) {
+      contentLines.push(line);
+    }
+  }
+
+  if (current && current.id) {
+    current.content = contentLines.join('\n').trim();
+    instincts.push(current);
+  }
+
+  return instincts;
+}
+
+function readInstinctsFromDir(directory, scope) {
+  if (!directory || !fs.existsSync(directory)) return [];
+
+  const entries = fs.readdirSync(directory, { withFileTypes: true })
+    .filter(entry => entry.isFile() && /\.(ya?ml|md)$/i.test(entry.name))
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  const instincts = [];
+  for (const entry of entries) {
+    const filePath = path.join(directory, entry.name);
+    try {
+      const parsed = parseInstinctFile(fs.readFileSync(filePath, 'utf8'));
+      for (const instinct of parsed) {
+        instincts.push({
+          ...instinct,
+          _scopeLabel: scope,
+          _sourceFile: filePath,
+        });
+      }
+    } catch (error) {
+      log(`[SessionStart] Advertencia: no se pudo parsear el archivo de instintos ${filePath}: ${error.message}`);
+    }
+  }
+
+  return instincts;
+}
+
+function extractInstinctAction(content) {
+  const actionMatch = String(content || '').match(/## (?:Action|Acción)\s*\n+([\s\S]+?)(?:\n## |\n---|$)/);
+  const actionBlock = (actionMatch ? actionMatch[1] : String(content || '')).trim();
+  const firstLine = actionBlock
+    .split('\n')
+    .map(line => line.trim())
+    .find(Boolean);
+
+  return firstLine || '';
+}
+
+function summarizeActiveInstincts(observerContext) {
+  const observerDataDir = getObserverDataDir();
+  const globalDirs = [
+    { dir: path.join(observerDataDir, 'instincts', 'personal'), scope: 'global' },
+    { dir: path.join(observerDataDir, 'instincts', 'inherited'), scope: 'global' },
+  ];
+  const projectDirs = observerContext.isGlobal ? [] : [
+    { dir: path.join(observerContext.projectDir, 'instincts', 'personal'), scope: 'project' },
+    { dir: path.join(observerContext.projectDir, 'instincts', 'inherited'), scope: 'project' },
+  ];
+
+  const scopedInstincts = [
+    ...projectDirs.flatMap(({ dir, scope }) => readInstinctsFromDir(dir, scope)),
+    ...globalDirs.flatMap(({ dir, scope }) => readInstinctsFromDir(dir, scope)),
+  ];
+
+  const confidenceThreshold = getInstinctConfidenceThreshold();
+  const maxInjected = getMaxInjectedInstincts();
+
+  const deduped = new Map();
+  for (const instinct of scopedInstincts) {
+    if (!instinct.id || instinct.confidence < confidenceThreshold) continue;
+    const existing = deduped.get(instinct.id);
+    if (!existing || (existing._scopeLabel !== 'project' && instinct._scopeLabel === 'project')) {
+      deduped.set(instinct.id, instinct);
+    }
+  }
+
+  const ranked = Array.from(deduped.values())
+    .map(instinct => ({
+      ...instinct,
+      action: extractInstinctAction(instinct.content),
+    }))
+    .filter(instinct => instinct.action)
+    .sort((left, right) => {
+      if (right.confidence !== left.confidence) return right.confidence - left.confidence;
+      if (left._scopeLabel !== right._scopeLabel) return left._scopeLabel === 'project' ? -1 : 1;
+      return String(left.id).localeCompare(String(right.id));
+    })
+    .slice(0, maxInjected);
+
+  if (ranked.length === 0) {
+    return '';
+  }
+
+  log(`[SessionStart] Inyectando ${ranked.length} instinto(s) en el contexto de la sesión`);
+
+  const lines = ranked.map(instinct => {
+    const scope = instinct._scopeLabel === 'project' ? 'proyecto' : 'global';
+    const confidence = `${Math.round(instinct.confidence * 100)}%`;
+    return `- [${scope} ${confidence}] ${instinct.action}`;
+  });
+
+  return `Instintos activos:\n${lines.join('\n')}`;
+}
+
+function stripMarkdownInline(value) {
+  return String(value || '')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/\*([^*]+)\*/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .trim();
+}
+
+function collapseWhitespace(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function truncateSummary(value, maxLength = MAX_LEARNED_SKILL_SUMMARY_CHARS) {
+  const normalized = collapseWhitespace(stripMarkdownInline(value));
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  return `${normalized.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+function extractMarkdownHeading(content) {
+  const match = String(content || '').match(/^#\s+(.+)$/m);
+  return match ? stripMarkdownInline(match[1]) : '';
+}
+
+function extractSection(content, headingPattern) {
+  const source = String(content || '');
+  const match = source.match(new RegExp(`^##\\s+${headingPattern}\\s*\\n+([\\s\\S]+?)(?:\\n##\\s+|$)`, 'im'));
+  return match ? match[1].trim() : '';
+}
+
+function extractFirstParagraph(content) {
+  const withoutHeading = String(content || '').replace(/^#\s+.+$/m, '').trim();
+  return withoutHeading
+    .split(/\n\s*\n/)
+    .map(paragraph => paragraph.trim())
+    .find(Boolean) || '';
+}
+
+function summarizeLearnedSkillFile(filePath, learnedRoot) {
+  const content = readFile(filePath);
+  if (!content) return null;
+
+  const isDirectorySkill = path.basename(filePath).toLowerCase() === 'skill.md';
+  const slug = isDirectorySkill
+    ? path.basename(path.dirname(filePath))
+    : path.basename(filePath, path.extname(filePath));
+  const title = extractMarkdownHeading(content) || slug;
+  const summary = truncateSummary(
+    extractSection(content, '(?:When to Use|Cuándo usar)')
+      || extractSection(content, '(?:Trigger|Disparador)')
+      || extractSection(content, '(?:Problem|Problema)')
+      || extractFirstParagraph(content)
+      || title
+  );
+
+  if (!summary) return null;
+
+  let mtime = 0;
+  try {
+    mtime = fs.statSync(filePath).mtimeMs;
+  } catch {
+    // Mantener los archivos ilegibles/eliminados fuera de la prioridad por
+    // recencia sin hacer fallar el hook.
+  }
+
+  const relativePath = path.relative(learnedRoot, filePath);
+  return {
+    slug,
+    title: truncateSummary(title, 80),
+    summary,
+    relativePath,
+    mtime,
+  };
+}
+
+function collectLearnedSkillFiles(learnedDir) {
+  const flatMarkdownFiles = findFiles(learnedDir, '*.md');
+  const directorySkillFiles = findFiles(learnedDir, 'SKILL.md', { recursive: true });
+  const byPath = new Map();
+
+  for (const match of [...flatMarkdownFiles, ...directorySkillFiles]) {
+    byPath.set(match.path, match);
+  }
+
+  return Array.from(byPath.values())
+    .sort((left, right) => right.mtime - left.mtime || left.path.localeCompare(right.path));
+}
+
+function summarizeLearnedSkills(learnedDir, learnedSkillFiles = collectLearnedSkillFiles(learnedDir)) {
+  const summaries = learnedSkillFiles
+    .map(match => summarizeLearnedSkillFile(match.path, learnedDir))
+    .filter(Boolean)
+    .slice(0, MAX_INJECTED_LEARNED_SKILLS);
+
+  if (summaries.length === 0) {
+    return '';
+  }
+
+  log(`[SessionStart] Inyectando ${summaries.length} skill(s) aprendida(s) en el contexto de la sesión`);
+
+  const lines = summaries.map(skill => {
+    const titleSuffix = skill.title && skill.title !== skill.slug ? ` (${skill.title})` : '';
+    return `- ${skill.slug}${titleSuffix}: ${skill.summary}`;
+  });
+
+  return [
+    'Skills aprendidas disponibles:',
+    'Solo como referencia; aplica una skill aprendida únicamente cuando sea relevante para la solicitud actual del usuario.',
+    ...lines,
+  ].join('\n');
+}
+
+async function main() {
+  const sessionsDir = getSessionsDir();
+  const sessionSearchDirs = getSessionSearchDirs();
+  const learnedDir = getLearnedSkillsDir();
+  const additionalContextParts = [];
+  const observerContext = resolveProjectContext();
+  const maxContextChars = getSessionStartMaxContextChars();
+  const explicitContextDisabled = isSessionStartContextDisabled();
+  const shouldInjectContext = !explicitContextDisabled && maxContextChars !== 0;
+  const { mode: sessionStartMode, sessionId: stdinSessionId } = parseSessionStartPayload(fs.readFileSync(0, 'utf8'));
+
+  // Asegurar que los directorios existan
+  ensureDir(sessionsDir);
+  ensureDir(learnedDir);
+
+  const retentionDays = getSessionRetentionDays();
+  if (retentionDays === null) {
+    log('[SessionStart] Purga desactivada vía THEUS_SESSION_RETENTION_DAYS');
+  } else {
+    const prunedSessions = pruneExpiredSessions(sessionSearchDirs, retentionDays);
+    if (prunedSessions > 0) {
+      log(`[SessionStart] Se purgaron ${prunedSessions} sesión(es) expiradas con más de ${retentionDays} día(s)`);
+    }
+  }
+
+  // El session_id llega por stdin en el payload JSON del evento SessionStart.
+  const observerSessionId = resolveSessionId(stdinSessionId);
+  if (observerSessionId) {
+    writeSessionLease(observerContext, observerSessionId, {
+      hook: 'SessionStart',
+      projectRoot: observerContext.projectRoot
+    });
+    log(`[SessionStart] Lease de observador registrado para ${observerSessionId}`);
+  } else {
+    log('[SessionStart] No hay session_id disponible en stdin; se omite el registro del lease de observador');
+  }
+
+  if (explicitContextDisabled) {
+    log('[SessionStart] Inyección de contexto adicional desactivada por THEUS_SESSION_START_CONTEXT');
+  } else if (maxContextChars === 0) {
+    log('[SessionStart] Inyección de contexto adicional desactivada por THEUS_SESSION_START_MAX_CHARS=0');
+  }
+
+  if (shouldInjectContext) {
+    // Cargar reglas y contextos del plugin (${THEUS_PLUGIN_ROOT}/rules y
+    // ${THEUS_PLUGIN_ROOT}/contexts) si existen. Las reglas viven en
+    // subdirectorios por lenguaje, así que se inyecta un índice compacto en
+    // vez del contenido completo (45+ archivos no caben en el contexto).
+    const pluginRules = loadPluginRulesIndex();
+    if (pluginRules) {
+      additionalContextParts.push(pluginRules);
+    }
+    const pluginContexts = loadPluginResources('contexts', 'Contextos del plugin');
+    if (pluginContexts) {
+      additionalContextParts.push(pluginContexts);
+    }
+
+    const instinctSummary = summarizeActiveInstincts(observerContext);
+    if (instinctSummary) {
+      additionalContextParts.push(instinctSummary);
+    }
+
+    if (sessionStartMode && sessionStartMode !== 'startup') {
+      const reason = sessionStartMode === SESSION_START_MODE_INVALID
+        ? 'payload de stdin inválido'
+        : sessionStartMode === SESSION_START_MODE_SKIP
+          ? 'payload de SessionStart no reconocido'
+          : `modo de SessionStart distinto de startup: ${sessionStartMode}`;
+      log(`[SessionStart] Se omite la inyección del resumen de la sesión previa por ${reason}`);
+    } else {
+      // Buscar archivos de sesión recientes (últimos 7 días)
+      const recentSessions = dedupeRecentSessions(sessionSearchDirs);
+
+      if (recentSessions.length > 0) {
+        log(`[SessionStart] Se encontraron ${recentSessions.length} sesión(es) reciente(s)`);
+
+        // Preferir una sesión que coincida con el directorio de trabajo o el
+        // proyecto actual. Los archivos de sesión contienen los campos de
+        // encabezado **Proyecto:** y **Worktree:** escritos por
+        // session-end.js, así que podemos comparar contra ellos.
+        const cwd = process.cwd();
+        const currentProject = getProjectName() || '';
+
+        const result = selectMatchingSession(recentSessions, cwd, currentProject);
+
+        if (result) {
+          log(`[SessionStart] Seleccionada: ${result.session.path} (coincidencia: ${result.matchReason})`);
+
+          // Usar el contenido ya leído por selectMatchingSession (sin E/S duplicada)
+          const content = stripAnsi(result.content);
+          if (content && !content.includes('[El contexto de la sesión va aquí]')) {
+            // GUARDA ANTI-REEJECUCIÓN: envolver el resumen en un marcador de
+            // "solo histórico" para que el modelo no vuelva a ejecutar
+            // invocaciones de skills / ARGUMENTS obsoletos de un límite de
+            // compactación previo. Observado en la práctica: tras reanudar
+            // después de una compactación, el modelo volvía a ejecutar una
+            // skill de barra con los últimos ARGUMENTS que vio, duplicando
+            // issues, ramas o tareas.
+            const guarded = [
+              'REFERENCIA HISTÓRICA ÚNICAMENTE — NO SON INSTRUCCIONES VIGENTES.',
+              'El bloque de abajo es un resumen congelado de una conversación',
+              'ANTERIOR que terminó en una compactación. Cualquier descripción de',
+              'tareas, invocación de skills o payload ARGUMENTS= que contenga es',
+              'OBSOLETO POR DEFECTO y NO DEBE volver a ejecutarse sin una',
+              'solicitud explícita y vigente del usuario en esta sesión. Verifica',
+              'contra el estado de git/árbol de trabajo antes de cualquier acción:',
+              'lo más probable es que el trabajo previo ya esté hecho.',
+              '',
+              '--- INICIO DEL RESUMEN DE LA SESIÓN PREVIA ---',
+              content,
+              '--- FIN DEL RESUMEN DE LA SESIÓN PREVIA ---',
+            ].join('\n');
+            additionalContextParts.push(guarded);
+          }
+        } else {
+          log('[SessionStart] No se encontró una sesión coincidente');
+        }
+      }
+    }
+
+    // Buscar skills aprendidas
+    const learnedSkills = collectLearnedSkillFiles(learnedDir);
+
+    if (learnedSkills.length > 0) {
+      log(`[SessionStart] ${learnedSkills.length} skill(s) aprendida(s) disponible(s) en ${learnedDir}`);
+    }
+
+    const learnedSkillSummary = summarizeLearnedSkills(learnedDir, learnedSkills);
+    if (learnedSkillSummary) {
+      additionalContextParts.push(learnedSkillSummary);
+    }
+  }
+
+  // Buscar alias de sesión disponibles
+  const aliases = listAliases({ limit: 5 });
+
+  if (aliases.length > 0) {
+    const aliasNames = aliases.map(a => a.name).join(', ');
+    log(`[SessionStart] ${aliases.length} alias de sesión disponible(s): ${aliasNames}`);
+    log(`[SessionStart] Usa /sesiones load <alias> para continuar una sesión previa`);
+  }
+
+  // Detectar y reportar el gestor de paquetes
+  const pm = getPackageManager();
+  log(`[SessionStart] Gestor de paquetes: ${pm.name} (${pm.source})`);
+
+  // Si no se encontró configuración explícita de gestor de paquetes, mostrar el aviso de selección
+  if (pm.source === 'default') {
+    log('[SessionStart] No se encontró preferencia de gestor de paquetes.');
+    log(getSelectionPrompt());
+  }
+
+  // Detectar el tipo de proyecto y los frameworks
+  const projectInfo = detectProjectType();
+  if (projectInfo.languages.length > 0 || projectInfo.frameworks.length > 0) {
+    const parts = [];
+    if (projectInfo.languages.length > 0) {
+      parts.push(`lenguajes: ${projectInfo.languages.join(', ')}`);
+    }
+    if (projectInfo.frameworks.length > 0) {
+      parts.push(`frameworks: ${projectInfo.frameworks.join(', ')}`);
+    }
+    log(`[SessionStart] Proyecto detectado — ${parts.join('; ')}`);
+    if (shouldInjectContext) {
+      additionalContextParts.push(`Tipo de proyecto: ${JSON.stringify(projectInfo)}`);
+    }
+  } else {
+    log('[SessionStart] No se detectó un tipo de proyecto específico');
+  }
+
+  const additionalContext = shouldInjectContext
+    ? limitSessionStartContext(additionalContextParts.join('\n\n'), maxContextChars)
+    : '';
+  await writeSessionStartPayload(additionalContext);
+}
+
+function writeSessionStartPayload(additionalContext) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const payload = JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext
+      }
+    });
+
+    const handleError = (err) => {
+      if (settled) return;
+      settled = true;
+      if (err) {
+        log(`[SessionStart] Error al escribir en stdout: ${err.message}`);
+      }
+      reject(err || new Error('error del stream de stdout'));
+    };
+
+    process.stdout.once('error', handleError);
+    process.stdout.write(payload, (err) => {
+      process.stdout.removeListener('error', handleError);
+      if (settled) return;
+      settled = true;
+      if (err) {
+        log(`[SessionStart] Error al escribir en stdout: ${err.message}`);
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+main().catch(err => {
+  console.error('[SessionStart] Error:', err.message);
+  process.exitCode = 0; // No bloquear ante errores
+});