Milestoner

Los agentes de código ya pueden correr durante horas. Lo que no pueden hacer es decirte, con honestidad, qué terminaron. Una sesión que reporta “todos los tests pasan” a las tres de la mañana dijo exactamente eso muchas veces antes, y nada en el código de salida distingue las veces que era cierto.

Milestoner es la capa alrededor de eso. Descomponés el trabajo en hitos con criterios de aceptación escritos antes de arrancar. El motor lanza una sesión headless nueva por hito, lee el pequeño archivo de resultado que la sesión deja atrás y califica la afirmación contra lo que realmente hay en disco: un test que pasa, un diff, un commit. Un hito marcado como hecho sin una línea de evidencia por criterio se degrada a incompleto y se reintenta. Bloqueado tiene que llegar con un diagnóstico: el síntoma exacto, todo lo que se intentó y la única acción más clara para una persona.

Las horas de ejecución van al agente. El diseño, la descomposición y los criterios de aceptación siguen siendo tuyos, y ese es el punto: la compuerta de evidencia solo significa algo cuando los criterios los escribió una persona.

Lo que el motor se niega a contar

La infraestructura no es fracaso. Una sesión que muere en segundos, choca contra un límite de uso o se cae dejando una transcripción casi vacía no consume un intento, y si se anuncia una hora de reinicio, se parsea y se espera. La vitalidad viene de señales laterales, directorios de código vigilados, archivos de resultados de tests y logs de herramientas, nunca de la transcripción, que se queda quieta durante una generación larga y crece mientras un agente narra un loop de reintentos.

Supervisar y corregir el rumbo

Una skill de Claude Code incluida convierte una segunda sesión en supervisor que se despierta cada diez minutos, lee la corrida y aplica un playbook acotado: sana, ambiente trabado, sesión colgada, esperando un límite, runner muerto, bloqueada de verdad. Toda su superficie de escritura es matar una sesión colgada, correr el adaptador de ambiente, relanzar el runner y agregar una línea al log. Nunca edita código del proyecto y nunca desbloquea un hito; eso sigue siendo una decisión humana. Una segunda skill, la planificadora, te entrevista y propone la descomposición en hitos para tu aprobación antes de escribir un solo prompt.

El steering corrige una corrida en vuelo sin matarla. Cada sesión que se lanza después recibe el texto incrustado como override sobre su prompt de hito, y cada intento registra el steering que estaba vigente. Un panel web local, solo loopback y con una clave de un solo uso en la URL, muestra el mismo estado que la CLI y llama a las mismas funciones, así que hay una sola traza de auditoría en vez de dos.

Publicación

En npm desde agosto de 2026 bajo licencia MIT. Corre en Windows, macOS y Linux y la CI ejercita los tres; las partes específicas de plataforma, matar un árbol de procesos completo y lanzar a través de un shim de npm bajo cmd.exe, viven dentro del motor. Requiere Node 20 o superior y una CLI de agente en el PATH, Claude Code por defecto.

La configuración por defecto corre el agente sin prompts de permisos, porque una sesión headless no puede responder uno. El README lo dice en negrita y te pide commitear antes. La plantilla de protocolo etiqueta cada hito verde, que es lo que convierte a git reset --hard <tag> en un rollback real.

Tecnología

• TypeScript compilado con tsup, distribuido como un único binario de CLI sin dependencias en runtime. Todo lo que necesita está en la biblioteca estándar de Node.
• Una máquina de estados en archivos. El motor es dueño de state.json; cada sesión escribe solo un pequeño result.json que se califica, se fusiona y se archiva. El estado nunca vive en una conversación, así que cada sesión arranca con contexto limpio.
• Supervisión de procesos sobre procesos hijos: una sesión headless de agente por hito, muerte del árbol de procesos completo con taskkill /T en Windows y con grupos de procesos POSIX en el resto, y un registro en ~/.milestoner/runs.json al que cada runner se suma al arrancar y del que se retira al salir, así que un runner que murió de noche es el que sigue listado.
• Vitalidad por mtime. Se consulta la fecha de modificación de directorios de código vigilados, archivos de resultados de tests y logs de herramientas; la transcripción nunca es señal a propósito, solo fuente del comando transcript, que la convierte en prosa.
• Un servidor HTTP local sobre el módulo http de Node, sin framework, con actualizaciones en streaming por Server-Sent Events. Solo loopback, con una clave de un solo uso en la URL, y las mismas funciones detrás de cada botón que llama la CLI.
• Reportes HTML autocontenidos, un archivo por corrida, sin assets externos.
• Tests en el runner integrado de Node (node:test), cubriendo el calificador, la compuerta del runner, el steering, el registro, el lint y la API HTTP. GitHub Actions corre la matriz en Ubuntu, macOS y Windows con Node 20, 22 y 24.
• Skills de Claude Code incluidas para el supervisor y el planificador, instaladas en .claude/skills/ por el propio binario para que nunca se distribuyan separadas del motor al que llaman.