01 — Business Requirements Document (BRD)

Work Item: ORCH-044 Title: Надёжность запуска агента: preflight ловит auth+битый флаг, --effort фикс Приоритет: Высокий (надёжность конвейера) Автор запроса: Слава, 05.06 («почему перед стартом аналитика не прошла проверка?»)

1. Контекст и инцидент (05.06)

Задача ORCH-17 застряла на стадии Analysis ~30 минут. Аналитик-агент стартовал и мгновенно «умирал»: run-лог — пустой файл (0 байт), а job в очереди оставался в состоянии running (вечное зависание без сигнала).

Корневые причины (две, наложились):

claude Not logged in после ребилда контейнера — токен/сессия не поднялись.
Флаг --effort в связке с --print --output-format json (CLI 2.1.142) гасил весь stdout — claude завершался с пустым выводом.

Главная системная проблема: preflight-проверка пропустила обе битые задачи в работу — она слепа к авторизации и не ловит «битый флаг → пустой вывод».

2. Проблема (как есть)

P1. Дыра в preflight (главное). src/preflight.py сознательно проверяет только (a) os.path.exists(CLAUDE_BIN) и (b) claude --version (timeout 5s, без токенов). Но --version отвечает успешно даже когда claude НЕ залогинен (версия — локальная информация). Итог: preflight=ok, а реальный запуск падает Not logged in. Preflight слеп к авторизации и пропускает заведомо нерабочие задачи в очередь.
P2. --effort ломает вывод. Флаг --effort <low..max> совместно с --print/--output-format json в CLI 2.1.142 даёт пустой stdout — агент молча умирает. Сейчас effort отключён в проде хотфиксом (.env: ORCH_AGENT_EFFORT_*=""), но дефолты в src/config.py всё ещё high/medium, а документация (INFRA.md, internals.md, ORCH-41) описывает effort как рабочую фичу. Несоответствие кода/доков/прода.
P3. Пустой лог ≠ провал. Агент с пустым run-логом (0 байт) и exit 0 трактуется как успех (_finalize_job → done, авто-advance стадии) либо вечно висит running. Ни watchdog, ни ретрай не срабатывают. Нет сигнала об инциденте.

3. Бизнес-последствия

Любой сбой авторизации или несовместимости флага → тихое зависание задачи без алерта.
Блокируется конвейер всех проектов (общий инстанс/очередь, self-hosting) — как было с ORCH-17 (30 мин простоя, ручное вмешательство).
Деградация доверия к автономности оркестратора: «проверка перед стартом» не работает.

4. Цель

Сделать запуск агента отказоустойчивым по входу и по выходу:

Preflight ловит отсутствие/протухание авторизации дёшево и без траты токенов до того, как job будет заклеймлен.
Разобраться с --effort и привести код/доки/прод к одному непротиворечивому состоянию.
Пустой/невалидный результат запуска трактуется как провал (job → failed), чтобы сработали watchdog/ретрай и алерт, а не вечное зависание.

5. Заинтересованные стороны

Owner/Слава — инициатор, требует «проверки перед стартом».
Все проекты на инстансе (enduro-trails и self-hosting ORCH) — страдают от простоя.
Агенты конвейера — analyst/architect/... — все запускаются через единый launcher.

6. Объём (Scope)

В объёме:

Дешёвая token-free проверка авторизации в preflight.
Расследование и решение по --effort (вернуть корректно ИЛИ задокументировать как unsupported и убрать из кода/дефолтов/доков).
Детекция «пустой лог / нет валидного result-JSON» как провала job с корректным переводом в failed и срабатыванием ретрая/алерта.
Обновление документации (INFRA.md / internals.md / CHANGELOG) в том же PR.

Вне объёма:

Prompt-ping (ping→pong) — запрещено (жжёт rate limit). Только локальные/дешёвые проверки.
Реформа circuit breaker / backoff-логики (используем существующие механизмы).
Изменение схемы стадий/конвейера.
Автоматический re-login claude (восстановление авторизации) — отдельная задача.

7. Бизнес-правила

BR-1: Preflight не тратит токены и не делает сетевых вызовов к API модели.
BR-2: Протухшая/нечитаемая авторизация → preflight=fail → job не клеймится (остаётся queued), пишется warning, при необходимости — алерт/брейкер.
BR-3: Пустой run-лог ИЛИ отсутствие валидного result-JSON при exit 0 → job failed (никогда не done и не вечный running).
BR-4: Никаких --no-verify/обхода хуков без явного одобрения Owner.
BR-5: Код, дефолты config.py, прод .env и документация по --effort должны быть взаимно непротиворечивы после задачи.

8. Критерии успеха (бизнес-уровень)

Симуляция «не залогинен» → preflight ловит до клейма, job не стартует впустую.
Симуляция «пустой лог + exit 0» → job становится failed, срабатывает ретрай/алерт.
Состояние --effort однозначно: либо работает с json-форматом, либо удалён из активного пути и доков (без «мёртвого» флага в дефолтах).
Инцидент класса ORCH-17 больше не приводит к тихому 30-минутному зависанию.

9. Связанные материалы

src/preflight.py, src/queue_worker.py, src/agents/launcher.py, src/config.py
docs/history/LESSONS_ORCH-017.md, docs/history/LESSONS_2026-06-05.md
ORCH-41 (effort/model resolver), ORCH-1 (очередь/resilience), ORCH-7 (watchdog)

7.8 KiB Raw Blame History Unescape Escape