Origin Session ID: d5ed6767-0292-46bf-9346-439f268048ec
Context
The M4 Architectural Convergence (Epic #11077) mandates that the AgentOrchestrator act as the centralized systemd-like supervisor for all Neo.mjs daemons. Currently, MCP servers manage their own child processes (e.g., DatabaseLifecycleService for Chroma), leading to orphan processes, race conditions, and scattered lifecycle logic.
The Problem
Decentralized process management creates cross-agent termination friction and leaves orphaned daemons when MCP servers exit ungracefully. DatabaseLifecycleService and other MCP-specific lifecycle classes conflate process supervision with service health observation.
The Architectural Reality
ai/agent/AgentOrchestrator.mjs (formerly Orchestrator) is the designated central supervisor.ai/daemons/services/ProcessSupervisorService.mjs is the hardened substrate extracted in M3.5 for managing child processes, PID files, and restarts.ai/services/knowledge-base/DatabaseLifecycleService.mjs currently directly spawns the Chroma database process.
The Fix
Migrate the supervision of maintenance daemons (chroma, bridge-daemon, and mlx) to AgentOrchestrator using ProcessSupervisorService. Strip process management (spawn/kill) from DatabaseLifecycleService and related MCP lifecycle services, converting them into read-only health observers.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
AgentOrchestrator.mjs |
M4 Epic #11077 |
Spawns and supervises chroma, bridge-daemon, mlx |
Log errors if daemon fails to start |
None |
Process PID files properly written and recovered |
DatabaseLifecycleService |
M4 Epic #11077 |
Stripped of spawn/kill. Becomes read-only health observer |
Assume dead if ping fails |
None |
Tests verify it only checks health, doesn't spawn |
Acceptance Criteria
Out of Scope
- Extracting new task coordinators.
- Modifying the underlying daemon logic (Chroma, Bridge, MLX code remains unchanged).
Avoided Traps / Gold Standards Rejected
- Adding
pm2 / systemd: Rejected because Neo.mjs requires a zero-config, portable sandbox on operator machines. AgentOrchestrator must fulfill this role natively.
- Polling health registry for auto-start: Rejected. The Orchestrator should explicitly manage the process lifecycle via definitions, rather than reacting to missing services from a registry.
Related
- Sub-issue of Epic #11077
- Builds on M3.5 extraction of
ProcessSupervisorService (#11044).
Retrieval Hint: "Migrate Daemon Supervision to AgentOrchestrator", "ProcessSupervisorService chroma bridge mlx"
Origin Session ID: d5ed6767-0292-46bf-9346-439f268048ec
Context
The M4 Architectural Convergence (Epic #11077) mandates that the
AgentOrchestratoract as the centralized systemd-like supervisor for all Neo.mjs daemons. Currently, MCP servers manage their own child processes (e.g.,DatabaseLifecycleServicefor Chroma), leading to orphan processes, race conditions, and scattered lifecycle logic.The Problem
Decentralized process management creates cross-agent termination friction and leaves orphaned daemons when MCP servers exit ungracefully.
DatabaseLifecycleServiceand other MCP-specific lifecycle classes conflate process supervision with service health observation.The Architectural Reality
ai/agent/AgentOrchestrator.mjs(formerly Orchestrator) is the designated central supervisor.ai/daemons/services/ProcessSupervisorService.mjsis the hardened substrate extracted in M3.5 for managing child processes, PID files, and restarts.ai/services/knowledge-base/DatabaseLifecycleService.mjscurrently directly spawns the Chroma database process.The Fix
Migrate the supervision of maintenance daemons (
chroma,bridge-daemon, andmlx) toAgentOrchestratorusingProcessSupervisorService. Strip process management (spawn/kill) fromDatabaseLifecycleServiceand related MCP lifecycle services, converting them into read-only health observers.Contract Ledger Matrix
AgentOrchestrator.mjschroma,bridge-daemon,mlxDatabaseLifecycleServicespawn/kill. Becomes read-only health observerAcceptance Criteria
AgentOrchestrator.mjsconfigures and runschroma,bridge-daemon, andmlxviaProcessSupervisorService.DatabaseLifecycleService.mjsno longer imports or usesspawn/killorchild_process.Out of Scope
Avoided Traps / Gold Standards Rejected
pm2/systemd: Rejected because Neo.mjs requires a zero-config, portable sandbox on operator machines.AgentOrchestratormust fulfill this role natively.Related
ProcessSupervisorService(#11044).Retrieval Hint: "Migrate Daemon Supervision to AgentOrchestrator", "ProcessSupervisorService chroma bridge mlx"