---
kind: epic
slug: apps-orchestrator
title: apps/orchestrator — role dispatch and gate pauses
plan_slug: automation-foundation
status: done
priority: P1
tenant_id: global
cursor_epic_id: null
updated_at: "2026-08-03"
---

# Epic objective

Long-running **`apps/orchestrator`** service: Redis job queue, convoy state machine driver, role dispatcher. Inspired by Symphony **concepts** (stall detection, token logging) — **not** Symphony codebase.

On **Go**: enqueue planning roles serially (ia → ux → architect), stop at `convoy_review`; after Gate 1, dispatch implementer jobs (parallel when `slice_dependencies` allow); fan-out audit jobs; stop at `pr_review` and post-merge gates.

**Parallel implementer fan-out:** When multiple implementer jobs target the same Mac inference host, orchestrator should pass the same `qwen-coder-mlx` alias to each job; operator must run a batching-capable MLX server (mlx-openai-server) — see `docs/adr-model-routing.md` § Local MLX. Cap concurrent implementers per host in orchestrator config if OOM occurs (agent-pipeline multitask playbook).

Each job calls `resolveModel(workspace, roleId, convoy, brief)` and passes `ResolvedModel` to worker.

## In scope / out of scope

**In scope**

- `apps/orchestrator` package in monorepo.
- Redis queue (existing infra).
- Deploy on Coolify beside `web`.
- Stall detection → `agent_runs` / convoy `blocked`.

**Out of scope**

- Worker implementation (Epic 7).
- Symphony / Linear integration.

## Dependencies

- Epic 1 (`resolveModel`).
- Epic 3 (repo link for clone path).
- Epic 4 (transitions).
- Epic 5 (gates — for dogfood; orchestrator can run in dry-run before UI).

## Blocks

- Epic 7 (worker consumes jobs).

## Acceptance criteria

- [x] Dry-run: orchestrator logs next role for a convoy without worker.
- [ ] Live: one implementer brief dispatched and paused correctly at gate.

## Tasks

- [x] [Task-shared-orchestrator-driver](./Task-shared-orchestrator-driver.md)
- [x] [Task-apps-orchestrator-service](./Task-apps-orchestrator-service.md)

## Follow-on tasks (Autensa benchmark)

| Task | Link |
|------|------|
| Agent health auto-nudge & zombie recovery | [Task-orchestrator-auto-nudge](./Task-orchestrator-auto-nudge.md) |

## Note

Supersedes [Epic-optional-orchestrator](../../Plan-agent-coordination/Epic-optional-orchestrator/Epic-optional-orchestrator.md) deferred stub with a concrete Echodo-native design.