---
id: 11093
title: Migrate Daemon Supervision to AgentOrchestrator
state: CLOSED
labels:
  - enhancement
  - ai
  - refactoring
  - architecture
assignees:
  - neo-gemini-pro
createdAt: '2026-05-10T02:34:08Z'
updatedAt: '2026-05-10T10:40:46Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11093'
author: neo-gemini-pro
commentsCount: 0
parentIssue: 11077
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-10T10:40:46Z'
---
# Migrate Daemon Supervision to AgentOrchestrator

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
- [ ] `AgentOrchestrator.mjs` configures and runs `chroma`, `bridge-daemon`, and `mlx` via `ProcessSupervisorService`.
- [ ] `DatabaseLifecycleService.mjs` no longer imports or uses `spawn`/`kill` or `child_process`.
- [ ] Bridge daemon and MLX process spawning are similarly centralized.

## 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"

## Timeline

- 2026-05-10T02:34:09Z @neo-gemini-pro added the `enhancement` label
- 2026-05-10T02:34:10Z @neo-gemini-pro added the `ai` label
- 2026-05-10T02:34:10Z @neo-gemini-pro added the `refactoring` label
- 2026-05-10T02:34:10Z @neo-gemini-pro added the `architecture` label
- 2026-05-10T02:34:15Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-05-10T02:34:22Z @neo-gemini-pro added parent issue #11077
- 2026-05-10T02:43:56Z @neo-gemini-pro cross-referenced by PR #11096
- 2026-05-10T02:55:24Z @neo-gemini-pro referenced in commit `8a1014a` - "feat(ai): Centralize daemon supervision (#11093)"
- 2026-05-10T02:55:24Z @neo-gemini-pro referenced in commit `bdc4bd0` - "fix(ai): add daemon restart throttling and fix test fixtures (#11093)"
- 2026-05-10T10:34:11Z @neo-gemini-pro referenced in commit `36a7fac` - "feat(ai): Centralize daemon supervision (#11093)"
- 2026-05-10T10:34:11Z @neo-gemini-pro referenced in commit `f25d93a` - "fix(ai): add daemon restart throttling and fix test fixtures (#11093)"
- 2026-05-10T10:35:36Z @neo-gemini-pro referenced in commit `6bab587` - "feat(ai): Centralize daemon supervision (#11093)"
- 2026-05-10T10:35:36Z @neo-gemini-pro referenced in commit `f38e815` - "fix(ai): add daemon restart throttling and fix test fixtures (#11093)"
- 2026-05-10T10:40:46Z @tobiu referenced in commit `7e59638` - "feat(ai): Centralize daemon supervision (#11093) (#11096)

* feat(ai): Centralize daemon supervision (#11093)

* fix(ai): add daemon restart throttling and fix test fixtures (#11093)

---------

Co-authored-by: neo-gemini-pro <neo-gemini-pro@users.noreply.github.com>"
- 2026-05-10T10:40:46Z @tobiu closed this issue
- 2026-05-10T11:10:37Z @neo-opus-ada cross-referenced by PR #11101
- 2026-05-10T12:13:58Z @neo-opus-ada cross-referenced by #11077
- 2026-05-11T21:33:33Z @neo-opus-ada cross-referenced by #11022

