200 lines
19 KiB
Markdown
200 lines
19 KiB
Markdown
# Аудит мультиагентного оркестратора — 2026-06-02
|
||
|
||
**Контекст:** глубокое ревью после ET-009, где автономность фактически отсутствовала
|
||
(0 из 6 этапов запустились сами; всё через base64-ручник).
|
||
|
||
**Объём аудита:**
|
||
- Код оркестратора: `launcher.py`, `stages.py`, `qg/checks.py`, `webhooks/{plane,gitea}.py`, `db.py`, `config.py`, `main.py`
|
||
- Инфраструктура: `Dockerfile`, `docker-compose.yml`
|
||
- Агентские инструкции: `analyst/architect/developer/reviewer/tester/deployer.md`
|
||
- Состояние: orchestrator DB (tasks + agent_runs), Plane
|
||
|
||
**Главный вывод из БД agent_runs:**
|
||
```
|
||
ET-009 (task 16): analyst/developer/reviewer — все exit=None (зомби, не дождались)
|
||
ET-008 (task 15): architect exit=-1 ×2, dev/reviewer exit=-9 (timeout kill)
|
||
Закономерность: НИ ОДИН прогон последних 2 задач не завершился чисто (exit=0 кроме analyst)
|
||
```
|
||
|
||
---
|
||
|
||
## 🔴 BLOCKER-уровень (убивают автономность)
|
||
|
||
### B-1. Нет `docker` бинарника в контейнере → launcher ломается в корне
|
||
**Где:** `docker-compose.yml` монтирует `/var/run/docker.sock`, но в `Dockerfile` ставится только `openssh-client git`. Бинарника `docker` НЕТ (проверено: `docker exec orchestrator which docker` → пусто).
|
||
|
||
**Последствие:** `launcher._write_task_file()` вызывает `docker run --rm -i python:3.12-slim ...` чтобы записать `.task-*.md` на хост. Но `docker` команды нет → запись падает или таск-файл не обновляется → агент читает СТАРЫЙ `.task-*.md` от предыдущей задачи.
|
||
|
||
**Это причина бага из ET-008:** architect v1 упал, прочитав `.task-arch.md` от другой задачи.
|
||
|
||
**Фикс (3 варианта, по возрастанию чистоты):**
|
||
- **F-1a (быстро):** добавить в Dockerfile `docker-ce-cli` (только клиент):
|
||
```dockerfile
|
||
RUN apt-get update -qq && apt-get install -y -qq ca-certificates curl gnupg openssh-client git \
|
||
&& install -m 0755 -d /etc/apt/keyrings \
|
||
&& curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc \
|
||
&& echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian bookworm stable" > /etc/apt/sources.list.d/docker.list \
|
||
&& apt-get update -qq && apt-get install -y -qq docker-ce-cli \
|
||
&& rm -rf /var/lib/apt/lists/*
|
||
```
|
||
- **F-1b (чище):** не использовать docker для записи файла вообще. `_write_task_file` пишет на хост-путь напрямую — но контейнер не видит host-путь как host-путь. Решение: writing в `/repos/<repo>/.task-*.md` (это уже смонтированный volume!) обычным `open(... ,"w")`. **Это самый правильный фикс — убирает docker-зависимость полностью.**
|
||
- **F-1c:** mount docker CLI бинарник с хоста (как уже сделано для node/claude): `-v /usr/bin/docker:/usr/bin/docker:ro`.
|
||
|
||
**Рекомендация: F-1b.** `repos_dir=/repos` уже примонтирован read-write. Запись `.task` файла должна идти туда напрямую — никакого docker.
|
||
|
||
---
|
||
|
||
### B-2. `subprocess.Popen` + потоки = зомби-процессы
|
||
**Где:** `launcher.launch()` → `subprocess.Popen(["bash","-c",cmd], stdout=PIPE, stderr=STDOUT)`, дальше `_monitor_agent` в daemon-потоке делает `proc.wait()`.
|
||
|
||
**Проблемы:**
|
||
1. **PIPE deadlock.** Claude CLI пишет много в stdout. `_monitor_agent` читает через `select`+`readline`, но если буфер переполняется ДО старта чтения (между Popen и стартом потока) — claude блокируется на write. При этом select-цикл ждёт 10с интервалами, а startup-timeout 120с убивает «молчащий» процесс, который на самом деле заблокирован на PIPE.
|
||
2. **Daemon-потоки.** `_monitor_agent` и `_watchdog` — `daemon=True`. При рестарте uvicorn / краше — потоки умирают, а дочерние claude-процессы остаются осиротевшими (зомби `Z`, parent=1). Никто не делает `wait()` → зомби висят.
|
||
3. **`exit=None` в БД.** Подтверждение: все ET-009 прогоны имеют `exit_code=None` — `_monitor_agent` поток не довёл `proc.wait()` до записи в БД.
|
||
|
||
**Фикс:**
|
||
- **F-2a:** не держать PIPE в памяти процесса-оркестратора. Перенаправлять stdout/stderr claude СРАЗУ в файл на уровне ОС: `subprocess.Popen(..., stdout=open(logpath,"w"), stderr=STDOUT)`. Тогда нет PIPE-deadlock, нет потока-читателя. Мониторинг — отдельным лёгким `poll()` по `proc.pid` или по mtime лог-файла.
|
||
- **F-2b (правильно):** вынести запуск агентов из in-process потоков в **очередь задач** (RQ / Celery / простой SQLite-backed worker loop). FastAPI webhook только кладёт job в очередь; отдельный worker-процесс запускает агента, ждёт, пишет результат. Рестарт uvicorn не убивает запущенных агентов; worker переподхватывает.
|
||
- **F-2c:** использовать `subprocess.run(timeout=...)` в worker'е вместо Popen+поток — синхронно, с гарантированным `wait()`, без зомби.
|
||
|
||
**Рекомендация: F-2a немедленно (1 строка убирает deadlock), F-2b как целевая архитектура.**
|
||
|
||
---
|
||
|
||
### B-3. Per-stage `.task-*.md` не пересоздаются надёжно
|
||
**Где:** `launcher.launch(task_content=...)` пишет таск-файл ТОЛЬКО если `task_content` передан. Но из-за B-1 запись падает молча. А агент в `cmd` читает `"$(cat {task_file})"` — если файл старый, агент работает по чужому ТЗ.
|
||
|
||
**Дополнительно:** каждый агент имеет ОТДЕЛЬНЫЙ task-файл (`.task-arch.md`, `.task-dev.md`...). Они коммитятся в репо (видны в `git diff` ET-009!) и тащатся между задачами. Это грязь в git-истории фичеветки.
|
||
|
||
**Фикс:**
|
||
- Писать таск-файл напрямую (см. F-1b), с проверкой что запись удалась (raise если нет).
|
||
- `.task-*.md` добавить в `.gitignore` репозитория enduro-trails — это рантайм-артефакт, не должен коммититься.
|
||
- Либо вообще не использовать файлы: передавать ТЗ агенту через `--append-system-prompt` или stdin, не через `cat файла`.
|
||
|
||
---
|
||
|
||
## 🟠 SERIOUS (ложные сигналы, неверная логика)
|
||
|
||
### S-1. Нет CI в Gitea → `check_ci_green` всегда false → ложные алерты
|
||
**Где:** `stages.py`: переход `development → review` имеет `qg: check_ci_green`. `check_ci_green` дёргает Gitea `/commits/{branch}/status`. В Gitea CI не настроен → status пустой/404 → возвращает `(False, "...")`.
|
||
|
||
**Последствие:** webhook `handle_ci_status` никогда не получает `state=success` (CI нет), поэтому автопереход на review НЕ происходит сам. А `handle_push`/прочее шлёт `notify_error` про «CI failed» на каждый push.
|
||
|
||
**Фикс:**
|
||
- **S-1a:** настроить минимальный CI в Gitea Actions (lint+test) — тогда статусы реальные. Это и есть «правильно».
|
||
- **S-1b (если CI пока не нужен):** заменить QG `check_ci_green` на файловый/локальный прогон тестов: оркестратор сам запускает `make test` в `/repos/<repo>` и判ает по exit-code. Не зависит от Gitea.
|
||
- **S-1c:** временно сделать `check_ci_green` → если CI не сконфигурирован (404/empty), не блокировать, а логировать `SKIPPED` и пропускать. Сейчас он жёстко false.
|
||
|
||
**Рекомендация: S-1b** — оркестратор сам гоняет тесты, детерминированно.
|
||
|
||
### S-2. Deployer запускается как агент, но реально не может в docker
|
||
**Где:** `stages.py` `testing → deploy` агент=`deployer`. `deployer.md` использует `Bash (git, curl, docker)`. Но claude-агент запускается в контексте, где docker недоступен (та же проблема B-1) ИЛИ на хосте по SSH — неоднозначно.
|
||
|
||
**Наблюдение на ET-009:** deployer смержил PR (через curl Gitea API — это сработало), но завис на `docker compose build` (docker недоступен). Деплой доделан вручную.
|
||
|
||
**Хорошая новость:** `deployer.md` УЖЕ написан правильно — деплой идёт через SSH-хук `enduro-deploy-hook.sh` на хост, а не через локальный docker. Проблема в том, что хук, видимо, не отработал/не существует.
|
||
|
||
**Фикс:**
|
||
- Проверить наличие `/home/slin/bin/enduro-deploy-hook.sh` и что он делает build+up+collector+smoke.
|
||
- Деплой-хук — единственное место, где должен жить docker. Агент только дёргает SSH.
|
||
- Убрать `docker` из дозволенных Bash deployer'а в промпте, чтобы не было соблазна.
|
||
|
||
### S-3. Rollback деплоера портит общий `/repos` checkout
|
||
**Где:** `deployer.md` шаг 6 rollback: `git checkout $LAST_TAG`. Это в общем `/repos/enduro-trails`, который шарят ВСЕ агенты и сам оркестратор.
|
||
|
||
**Последствие:** detached HEAD / переключение тега ломает состояние репо для следующих операций, конкурентных задач.
|
||
|
||
**Фикс:** rollback должен происходить на деплой-стороне (в деплой-хуке через теги/образы), НЕ через git checkout в shared-репо. Деплой и исходники должны быть разнесены.
|
||
|
||
### S-4. Shared mutable `/repos` checkout = гонки между задачами
|
||
**Где:** все агенты, webhooks, `_monitor_agent` делают `git checkout <branch>` в одном `/repos/<repo>`. Если две задачи активны — checkout одной перетирает рабочую копию другой.
|
||
|
||
**Последствие:** при параллельных задачах — хаос. На ET-009 это проявилось как «два коллектора» и путаница веток.
|
||
|
||
**Фикс:** **git worktree per task/branch.** `git worktree add /repos/_wt/<branch> <branch>` — изолированная рабочая копия на задачу. Агент работает в своём worktree. Убирает все гонки checkout.
|
||
|
||
### S-5. `check_reviewer_verdict` — хрупкий парсинг "APPROVED"/"REQUEST_CHANGES"
|
||
**Где:** `qg/checks.py` читает первые 5000 байт `12-review.md`, ищет подстроки `REQUEST_CHANGES`/`APPROVED`/`LGTM` в upper-case.
|
||
|
||
**Проблема:** если в отчёте есть таблица «F-01 ... APPROVED/REQUEST_CHANGES» как заголовки колонок (как в реальном ET-009 round-2 отчёте!) — парсер поймает оба и вернёт по порядку проверки. REQUEST_CHANGES проверяется первым → ложный fail при APPROVED-отчёте, где упомянут термин.
|
||
|
||
**Фикс:** ввести строгий машиночитаемый verdict. Reviewer ОБЯЗАН писать в YAML-фронтматтер `verdict: APPROVED|REQUEST_CHANGES` (как tester уже делает — `verdict: PASS`!). QG читает только фронтматтер, не весь текст.
|
||
|
||
---
|
||
|
||
## 🟡 MEDIUM (надёжность, наблюдаемость)
|
||
|
||
### M-1. Orphan-recovery слишком грубый
|
||
**Где:** `main.py` lifespan: `UPDATE agent_runs SET exit_code=-1 WHERE finished_at IS NULL AND started_at < now-35min`. Это маскирует зомби как «exit=-1», но не убивает реальные процессы и не перезапускает задачу. Просто «забывает» о них.
|
||
|
||
**Фикс:** при recovery — реально проверять/убивать pid, и ставить задачу в `blocked` с уведомлением, а не молча списывать.
|
||
|
||
### M-2. `AGENT_TIMEOUT=1800` хардкод, watchdog SIGKILL без cleanup
|
||
**Где:** `_watchdog` спит 1800с, потом `os.kill(pid, SIGKILL)`. SIGKILL не даёт claude корректно завершить запись файлов → возможны полу-записанные артефакты. Нет различения «медленный Opus» vs «завис».
|
||
|
||
**Фикс:** SIGTERM сначала (graceful), SIGKILL через grace-period. Таймаут — конфигурируемый per-agent (Opus-ревью дольше).
|
||
|
||
### M-3. Дубль логики автоперехода: `launcher._try_advance_stage` И `webhooks/plane._try_advance_stage`
|
||
**Где:** есть ДВА почти одинаковых `_try_advance_stage` — в launcher и в plane webhook. Разъезжаются по фиксам (Task 6/7/8 только в launcher).
|
||
|
||
**Фикс:** единый stage-engine модуль. Webhook и launcher вызывают одну функцию. Сейчас риск рассинхрона поведения.
|
||
|
||
### M-4. `_auto_merge_pr` — мёртвый код
|
||
**Где:** `launcher._auto_merge_pr` определён, но (по заметкам 01.06) хардкод убран, merge теперь делает deployer-агент. Метод висит неиспользуемым.
|
||
|
||
**Фикс:** удалить мёртвый код или явно задокументировать что не используется.
|
||
|
||
### M-5. Секреты и пути захардкожены в промптах
|
||
**Где:** `deployer.md`, агентские md содержат `82.22.50.71`, `admin`, URL'ы, имена хуков. При смене инфры — править в куче мест.
|
||
|
||
**Фикс:** инфра-параметры — через env/конфиг, в промпт подставлять. Промпт = роль, не инвентарь.
|
||
|
||
### M-6. `work_item_id` генерится из DB max, не из Plane sequence
|
||
**Где:** `db.get_next_work_item_id` берёт последний из tasks и +1. Но Plane sequence независим. Возможен рассинхрон ET-номеров между Plane и оркестратором.
|
||
|
||
**Фикс:** источник правды для номера — Plane sequence_id, мапить на ET-NNN детерминированно.
|
||
|
||
### M-7. Нет идемпотентности webhook'ов
|
||
**Где:** Gitea/Plane могут ретраить webhook. `events` логируются, но нет дедупа по event-id. Повторный webhook → повторный запуск агента.
|
||
|
||
**Фикс:** дедуп по `delivery-id`/event-uuid, хранить обработанные, игнорировать повторы.
|
||
|
||
---
|
||
|
||
## 🟢 LOW (косметика, гигиена)
|
||
|
||
- **L-1.** `STAGE_TRANSITIONS` комментарий «agent launched when entering NEXT stage» путаный — `get_agent_for_stage` возвращает агента ТЕКУЩЕГО перехода. Нейминг сбивает.
|
||
- **L-2.** Логи агентов в `/app/data/runs/{run_id}.log` — но при зомби они пустые. Нет ротации.
|
||
- **L-3.** Магические строки эмодзи как `\u2705` в коде вместо констант.
|
||
- **L-4.** `{src` — мусорная папка в корне репо орка (видно в `ls`).
|
||
- **L-5.** Нет тестов на launcher (только webhooks/qg). Самая хрупкая часть — без покрытия.
|
||
|
||
---
|
||
|
||
## 📋 Приоритизированный план устранения
|
||
|
||
### Спринт 1 — «вернуть автономность» (критично)
|
||
1. **B-1 (F-1b):** `_write_task_file` пишет в `/repos/<repo>/.task` напрямую через `open()`. Убрать docker-зависимость. *(1-2ч)*
|
||
2. **B-2 (F-2a):** Popen stdout → файл напрямую (не PIPE). Убрать поток-читатель. *(1-2ч)*
|
||
3. **B-3:** `.task-*.md` в `.gitignore`, проверка успешной записи. *(30мин)*
|
||
4. **S-5:** Reviewer пишет `verdict:` во фронтматтер; QG читает только его. *(1ч + правка reviewer.md)*
|
||
|
||
→ После спринта 1: pipeline должен пройти ET-009-подобную задачу БЕЗ ручника.
|
||
|
||
### Спринт 2 — «детерминизм и развязка»
|
||
5. **S-1b:** QG-тесты гоняет сам оркестратор (`make test`), не зависим от Gitea CI. *(2-3ч)*
|
||
6. **S-4:** git worktree per branch — изоляция задач. *(3-4ч)*
|
||
7. **S-2/S-3:** деплой только через SSH-хук, rollback на деплой-стороне, не в shared-репо. Проверить/написать `enduro-deploy-hook.sh`. *(2-3ч)*
|
||
8. **M-3:** единый stage-engine, убрать дубль `_try_advance_stage`. *(2ч)*
|
||
|
||
### Спринт 3 — «надёжность»
|
||
9. **F-2b:** очередь задач (SQLite-worker) вместо in-process daemon-потоков. *(день)*
|
||
10. **M-1, M-2:** нормальный orphan-recovery + graceful timeout. *(2-3ч)*
|
||
11. **M-7:** идемпотентность webhook'ов. *(2ч)*
|
||
12. **L-5:** тесты на launcher. *(полдня)*
|
||
|
||
---
|
||
|
||
## Резюме одной строкой
|
||
**Корень всех бед — два бага: (1) нет docker-бинарника → запись таск-файлов падает молча; (2) Popen+PIPE+daemon-поток → зомби и потеря exit-кода. Оба чинятся за полдня и убирают 90% ручника. Остальное — развязка задач (worktree), детерминизм QG (свои тесты вместо Gitea CI) и машиночитаемые вердикты.**
|