Plan de PTY y supervisión de procesos

1. Problema y objetivo

Necesitamos un ciclo de vida confiable único para la ejecución de comandos de larga duración en:

• Ejecuciones exec en primer plano
• Ejecuciones exec en segundo plano
• Acciones de seguimiento de process (poll, log, send-keys, paste, submit, kill, remove)
• Subprocesos del runner del agente CLI

El objetivo no es solo soportar PTY. El objetivo es propiedad predecible, cancelación, timeout y limpieza sin heurísticas inseguras de coincidencia de procesos.

2. Alcance y límites

• Mantener la implementación interna en src/process/supervisor.
• No crear un nuevo paquete para esto.
• Mantener compatibilidad con el comportamiento actual donde sea práctico.
• No ampliar el alcance a replay de terminal o persistencia de sesión tipo tmux.

3. Implementado en esta rama

Base del supervisor ya presente

• El módulo supervisor está en su lugar bajo src/process/supervisor/*.
• El runtime de exec y el runner CLI ya se enrutan a través del spawn y wait del supervisor.
• La finalización del registro es idempotente.

Completado en esta pasada

1. Contrato de comando PTY explícito
2. Desacoplamiento de tipos de la capa de procesos
3. Mejora de propiedad del ciclo de vida de herramientas de procesos
4. Valores por defecto únicos del watchdog
5. Limpieza de helpers muertos
6. Tests de ruta directa del supervisor agregados
7. Correcciones de brechas de confiabilidad completadas
8. Cobertura de casos extremos del contrato PTY agregada

4. Brechas restantes y decisiones

Estado de confiabilidad

Las dos brechas de confiabilidad requeridas para esta pasada están cerradas:

• process kill/remove ahora tiene un fallback de terminación real del SO cuando la búsqueda en el supervisor falla.
• La cancelación/timeout del hijo ahora usa semántica de kill del árbol de procesos para la ruta de kill por defecto.
• Se agregaron tests de regresión para ambos comportamientos.

Durabilidad y reconciliación al inicio

El comportamiento de reinicio ahora se define explícitamente como ciclo de vida solo en memoria.

• reconcileOrphans() permanece como no-op en src/process/supervisor/supervisor.ts por diseño.
• Las ejecuciones activas no se recuperan después del reinicio del proceso.
• Este límite es intencional para esta pasada de implementación para evitar riesgos de persistencia parcial.

9. Definición de completado

1. El supervisor es el propietario del ciclo de vida para las ejecuciones gestionadas.
2. El spawn PTY usa un contrato de comando explícito sin reconstrucción de argv.
3. La capa de procesos no tiene dependencia de tipos en la capa del agente para contratos stdin del supervisor.
4. Los valores por defecto del watchdog son de fuente única.
5. Los tests unitarios y e2e dirigidos permanecen en verde.
6. El límite de durabilidad ante reinicios está explícitamente documentado o completamente implementado.