Optimiza el ciclo de vida de procesos con OpenClaw

¿Alguna vez has tenido que lidiar con procesos “zombie” que se quedan colgados en tu servidor? Gestionar el ciclo de vida de comandos de larga duración en Node.js puede volverse un caos rápidamente si no tienes un control estricto sobre quién es el dueño de cada proceso.

Si estás cansado de usar heurísticas poco seguras para intentar emparejar procesos o de limpiezas que fallan cuando más las necesitas, este plan de supervisión es para ti. Queremos que la ejecución de comandos sea predecible y sólida.

1. Problema y objetivo

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

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

El objetivo no es solo dar soporte a PTY. El objetivo es tener una propiedad, cancelación, tiempo de espera (timeout) y limpieza predecibles, sin usar heurísticas inseguras para emparejar procesos.

2. Alcance y límites

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

3. Implementado en esta rama

Base del Supervisor ya presente

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

Fase completada

1. Contrato de comando PTY explícito

• SpawnInput ahora es una unión discriminada en src/process/supervisor/types.ts.
• Las ejecuciones de PTY requieren ptyCommand en lugar de reutilizar el argv genérico.
• El Supervisor ya no reconstruye cadenas de comandos PTY a partir de uniones de argv en src/process/supervisor/supervisor.ts.
• El runtime de Exec ahora pasa ptyCommand directamente en src/agents/bash-tools.exec-runtime.ts.

2. Desacoplamiento de tipos de la capa de proceso

• Los tipos del Supervisor ya no importan SessionStdin de los agents.
• El contrato de stdin local del proceso vive en src/process/supervisor/types.ts (ManagedRunStdin).
• Los adaptadores ahora dependen solo de tipos a nivel de proceso:
  • src/process/supervisor/adapters/child.ts
  • src/process/supervisor/adapters/pty.ts

3. Mejora de la propiedad del ciclo de vida de las herramientas de proceso

• src/agents/bash-tools.process.ts ahora solicita la cancelación a través del supervisor primero.
• process kill/remove ahora usan la terminación fallback de process-tree cuando falla la búsqueda en el supervisor.
• remove mantiene un comportamiento de eliminación determinista al descartar las entradas de sesión en ejecución inmediatamente después de solicitar la terminación.

4. Fuente única para valores por defecto del watchdog

• Se agregaron valores por defecto compartidos en src/agents/cli-watchdog-defaults.ts.
• src/agents/cli-backends.ts consume estos valores compartidos.
• src/agents/cli-runner/reliability.ts consume los mismos valores compartidos.

5. Limpieza de helpers muertos

• Se eliminó la ruta del helper killSession que no se usaba en src/agents/bash-tools.shared.ts.

6. Pruebas de ruta directa del supervisor añadidas

• Se añadió src/agents/bash-tools.process.supervisor.test.ts para cubrir el enrutamiento de kill y remove a través de la cancelación del supervisor.

7. Correcciones de brechas de fiabilidad completadas

• src/agents/bash-tools.process.ts ahora recurre a la terminación real del proceso a nivel de OS cuando falla la búsqueda en el supervisor.
• src/process/supervisor/adapters/child.ts ahora usa semántica de terminación process-tree para las rutas de kill por cancelación/timeout por defecto.
• Se añadió la utilidad compartida process-tree en src/process/kill-tree.ts.

8. Cobertura de casos de borde del contrato PTY añadida

• Se añadió src/process/supervisor/supervisor.pty-command.test.ts para el reenvío literal de comandos PTY y el rechazo de comandos vacíos.
• Se añadió src/process/supervisor/adapters/child.test.ts para el comportamiento de kill de process-tree en la cancelación del adaptador child.

4. Brechas pendientes y decisiones

Estado de fiabilidad

Las dos brechas de fiabilidad requeridas para esta fase ya están cerradas:

• process kill/remove ahora tiene un fallback real de terminación de OS cuando falla la búsqueda en el supervisor.
• La cancelación/timeout de child ahora usa la semántica de kill de process-tree para la ruta de kill por defecto.
• Se añadieron pruebas de regresión para ambos comportamientos.
• Las brechas de fiabilidad críticas han sido resueltas.

Durabilidad y reconciliación de inicio

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

• reconcileOrphans() sigue siendo un 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 en esta fase de implementación para evitar riesgos de persistencia parcial.
• El sistema prioriza la limpieza sobre la recuperación de estados huérfanos.

Seguimiento de mantenibilidad

1. runExecProcess en src/agents/bash-tools.exec-runtime.ts todavía maneja múltiples responsabilidades y puede dividirse en helpers enfocados en un seguimiento posterior.

5. Plan de implementación

La fase de implementación para los elementos requeridos de fiabilidad y contrato está completa.

Completado:

• Fallback de terminación real para process kill/remove
• Cancelación de process-tree para la ruta de kill por defecto del adaptador child
• Pruebas de regresión para el kill de fallback
• Pruebas de regresión para la ruta de kill del adaptador child
• Pruebas de casos de borde de comandos PTY bajo ptyCommand explícito
• Límite de reinicio explícito en memoria con reconcileOrphans() como no-op por diseño

Seguimiento opcional:

• Dividir runExecProcess en helpers enfocados sin alterar el comportamiento

6. Mapa de archivos

Process supervisor

• src/process/supervisor/types.ts actualizado con entrada de spawn discriminada y contrato de stdin local de proceso.
• src/process/supervisor/supervisor.ts actualizado para usar ptyCommand explícito.
• src/process/supervisor/adapters/child.ts y src/process/supervisor/adapters/pty.ts desacoplados de los tipos de agent.
• src/process/supervisor/registry.ts la finalización idempotente se mantiene sin cambios.

Integración de Exec y proceso

• src/agents/bash-tools.exec-runtime.ts actualizado para pasar el comando PTY explícitamente y mantener la ruta de fallback.
• src/agents/bash-tools.process.ts actualizado para cancelar vía supervisor con terminación fallback real de process-tree.
• src/agents/bash-tools.shared.ts se eliminó la ruta directa del helper de kill.
• src/process/kill-tree.ts utilidad compartida para manejo de árboles de procesos.

Fiabilidad de CLI

• src/agents/cli-watchdog-defaults.ts añadido como base compartida.
• src/agents/cli-backends.ts y src/agents/cli-runner/reliability.ts ahora consumen los mismos valores por defecto.

7. Ejecución de validación en esta fase

Unit tests:

pnpm vitest src/process/supervisor/registry.test.ts
pnpm vitest src/process/supervisor/supervisor.test.ts
pnpm vitest src/process/supervisor/supervisor.pty-command.test.ts
pnpm vitest src/process/supervisor/adapters/child.test.ts
pnpm vitest src/agents/cli-backends.test.ts
pnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.ts
pnpm vitest src/agents/bash-tools.process.poll-timeout.test.ts
pnpm vitest src/agents/bash-tools.process.supervisor.test.ts
pnpm vitest src/process/exec.test.ts

E2E targets:

pnpm vitest src/agents/cli-runner.test.ts
pnpm vitest run src/agents/bash-tools.exec.pty-fallback.test.ts src/agents/bash-tools.exec.background-abort.test.ts src/agents/bash-tools.process.send-keys.test.ts

Nota sobre Typecheck:

• Usa pnpm build (y pnpm check para el gate completo de lint/docs) en este repo. Las notas antiguas que mencionan pnpm tsgo están obsoletas.

8. Garantías operativas preservadas

• El comportamiento de endurecimiento (hardening) del entorno de Exec no ha cambiado.
• El flujo de aprobación y lista de permitidos (allowlist) no ha cambiado.
• La sanitización de salida y los límites de salida no han cambiado.
• El adaptador PTY sigue garantizando la resolución del wait en kill forzado y la disposición de listeners.

9. Definición de terminado

1. El Supervisor es el dueño del ciclo de vida de las ejecuciones gestionadas.
2. El spawn de PTY usa un contrato de comando explícito sin reconstrucción de argv.
3. La capa de proceso no tiene dependencia de tipos con la capa de agent para los contratos de stdin del supervisor.
4. Los valores por defecto del watchdog provienen de una única fuente.
5. Las pruebas unitarias y e2e dirigidas siguen en verde.
6. El límite de durabilidad ante reinicios está explícitamente documentado o implementado por completo.

10. Resumen

La rama ahora tiene una estructura de supervisión coherente y más segura:

• Contrato PTY explícito
• Capas de proceso más limpias
• Ruta de cancelación dirigida por el supervisor para operaciones de proceso
• Terminación fallback real cuando falla la búsqueda en el supervisor
• Cancelación de process-tree para rutas de kill por defecto en ejecuciones child
• Valores por defecto de watchdog unificados
• Límite de reinicio explícito en memoria (sin reconciliación de huérfanos tras reinicio en esta fase)
• Limpieza de helpers de terminación obsoletos

AI Setup Assistant

Próximos pasos

• Revisa la documentación de Process Supervisor
• Explora los Bash Tools