--- work_item: ORCH-109 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-14 model_used: claude-opus-4-8 --- # 01 — BRD (бизнес-требования): ORCH-109 — timeout budgets + launch-time model telemetry для developer/reviewer Work Item: **ORCH-109** · Repo: **orchestrator** · Стадия: analysis ## 1. Бизнес-контекст и проблема Инцидент **ORCH-104** (runs 658/659/660, прод-watchdog 1800s) вскрыл **два независимых дефекта** в подсистеме запуска агентов и телеметрии: **Дефект A — недостаточный wall-clock бюджет для тяжёлых ролей.** Агенты `developer` и `reviewer` на сложных задачах **честно** упираются в общий тайм-аут `agent_timeout_seconds = 1800` и убиваются watchdog'ом (`launcher._watchdog → stop_process`, exit 143 / -9). Этот тайм-аут — единый для ВСЕХ ролей, хотя `developer` (effort `xhigh`, кодирующая роль) и `reviewer` объективно требуют больше времени, чем механические роли (`tester`/`deployer`, effort `medium`). Существует механизм per-agent override (`_resolve_timeout` + `agent_timeout_overrides_json`), но в проде он пуст → все роли получают 1800s. **Дефект B — потеря модели в телеметрии при оборванном прогоне.** Модель агента (`agent_runs.model`) пишется **только постфактум** — из финального usage-JSON прогона в `launcher._monitor_agent → usage.record_usage` (`_extract_model`). Убитый по тайм-ауту прогон **не успевает эмитить финальный JSON** → `_extract_model` возвращает `None` → `record_usage` пишет `model=COALESCE(None, model)` = остаётся **NULL**. В результате карточка Telegram-трекера (`notifications._stage_line`) и снимок `GET /metrics`/`GET /queue` (`db.get_running_agents`) показывают `model=null` именно тогда, когда что-то пошло не так — в момент, когда модель/эффорт критичны для разбора инцидента. Существующий прецедент уже решает половину задачи: **эффорт стампится в момент launch** (`launcher._spawn`, ORCH-087, `UPDATE agent_runs SET effort=?`), потому что CLI его в result-JSON не возвращает. Модель резолвится в той же точке (`resolve_agent_model`, строка 559), но **в БД на launch не пишется** — стампится только эффорт. ORCH-109 распространяет ту же гарантию на модель. **Сопутствующие проверки (производные от A и B):** - Поведение оборванного (timeout-killed) прогона в трекере и status-комментариях: модель и эффорт должны быть видны даже если финальный JSON не записан. - Нужен ли отдельный guard: не пускать timeout-killed `developer`/`reviewer` автоматически дальше по конвейеру (`development → review`, `review → testing`) без явного salvage-режима. **Установленные факты (по коду, не изобретать):** - `agent_runs.model` — колонка `TEXT` (NULLABLE), уже существует (`db._ensure_column`); **миграция не нужна**. - `record_usage` уже использует `model=COALESCE(?, model)` — то есть постфактум-парс уже **сохраняет** ранее проставленное значение и не затирает его `NULL`'ом. Не хватает только записи на launch. - `_resolve_timeout(agent)` уже умеет per-agent override через `agent_timeout_overrides_json`; малформный JSON → откат на глобальный дефолт + лог (never-break). - Кросс-инвариант reaper: `reaper_max_running_s = 3600` с зафиксированным в `config.py` правилом «MUST be > max agent_timeout + grace» (Tier-3 backstop job-reaper'а, ORCH-065). ## 2. Объём (scope) ### В объёме - **Launch-time стамп модели:** записывать резолвенную `resolve_agent_model(...)` в `agent_runs.model` в момент launch (`launcher._spawn`), рядом со стампом эффорта (ORCH-087). - **Конфигурируемый поднятый wall-clock бюджет для `developer` и `reviewer`** через config-override, **без изменения** бюджета остальных ролей (`analyst`/`architect`/`tester`/`deployer`). - **Сохранение постфактум-enrich:** `usage.record_usage` остаётся источником обогащения модели/токенов/стоимости из usage-JSON, но **перестаёт быть единственным источником истины** о модели (launch-стамп — первичный, JSON — уточняющий). - **Видимость при timeout/kill:** строка стадии трекера и status-комментарии показывают реальные модель + эффорт для оборванного прогона (model не `null`). - **Guard анти-salvage:** гарантия (и регресс-тест), что timeout-killed прогон (`exit_code != 0`, в т.ч. -9/-15/143) **не продвигает** стадию автоматически в следующую без явного решения. - **Обновление документации/комментариев** по конфигу тайм-аутов (`config.py`, `.env.example`). - **Тесты**, покрывающие все перечисленные FR. ### Вне объёма - Изменение model-routing: все 6 агентов остаются на `claude-opus-4-8` (ORCH-41 G3 не включается). - Любые изменения `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключей / схемы БД (колонка `agent_runs.model` уже есть — миграции нет). - Изменение тайм-аута для ролей кроме `developer`/`reviewer`. - **Salvage / возобновление** недоделанной работы убитого прогона (поднять «как было», дописать, переиспользовать частичный результат) — в объёме ТОЛЬКО гарантия не-продвижения, не salvage. - Изменения транспорта Telegram/Plane (`send_telegram`/комментарии) — только использование уже доступных полей. - Перезапуск/деплой прод-контейнера в рамках задачи (self-hosting безопасность). ## 3. Заинтересованные стороны - **Заказчик/Owner (Слава)** — инициатор; нуждается в надёжной телеметрии для разбора инцидентов и в адекватных бюджетах тяжёлых ролей при пакетном автономном прогоне (эпик ORCH-088). - **Оператор self-hosting** — потребитель карточки трекера и `GET /metrics`/`GET /queue`; без модели в карточке теряет ключевой контекст инцидента. - **Сам конвейер (self-hosting)** — затрагивается поведение запуска агентов; общий прод-инстанс обслуживает и enduro-trails (тайм-аут — глобальная per-agent настройка, не repo-scoped). ## 4. Бизнес-требования (BR) - **BR-1** — Резолвенная модель агента сохраняется в `agent_runs.model` **в момент launch**, рядом с эффортом, а не только постфактум из usage-JSON. Значение присутствует на строке прогона с момента запуска и переживает любой исход прогона. - **BR-2** — Постфактум-парс usage/model (`usage.record_usage`) сохраняется как **обогащение**, но **не как единственный источник истины**: при отсутствии/обрыве финального JSON launch-стамп модели не теряется. - **BR-3** — Wall-clock тайм-аут для `developer` и `reviewer` поднимается и **настраивается через config-override**, **без изменения** тайм-аута остальных ролей; механизм покрыт тестом/проверкой. - **BR-4** — При timeout/kill (оборванный прогон без финального JSON) строка стадии в трекере и status-комментарии показывают **реальную модель (не `null`) и эффорт**. - **BR-5** — Timeout-killed прогон `developer`/`reviewer` **не продвигается** автоматически на следующую стадию без явного salvage-режима; поведение зафиксировано регресс-тестом. (Анализ определяет, нужен ли отдельный guard поверх существующей гарантии «advance только при чистом exit + зелёный QG».) - **BR-6** — Документация и комментарии по конфигу тайм-аутов обновлены (паспорт изменения внутри `config.py` + `.env.example`). ## 5. Нефункциональные требования (NFR) - **NFR-1 — Обратная совместимость / нулевая регрессия.** Стамп модели аддитивен (колонка уже существует, миграции нет). Дефолтный тайм-аут ролей, кроме `developer`/`reviewer`, не меняется; при пустом override-конфиге поведение байт-в-байт прежнее. - **NFR-2 — never-raise / never-break.** Сбой стампа модели (ошибка БД) **не блокирует** launch (та же `try/except`-изоляция, что у стампа эффорта). Малформный/невалидный timeout-конфиг → откат на глобальный дефолт + WARNING, прогон не падает. - **NFR-3 — Неприкосновенность контрактов.** `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/ `coverage_status:`), схема БД — **не трогаются**. - **NFR-4 — Сохранение reaper-инварианта.** Любой поднятый бюджет `developer`/`reviewer` обязан сохранять `reaper_max_running_s > max(резолвенный тайм-аут любого агента) + agent_kill_grace_seconds` (Tier-3 backstop ORCH-065); иначе job-reaper может реапнуть **здоровый** долгоиграющий прогон до срабатывания его собственного watchdog'а. Если новый бюджет нарушает неравенство — `reaper_max_running_s` поднимается синхронно (решение архитектора). - **NFR-5 — Self-hosting безопасность.** Изменение не рестартит/не роняет прод-контейнер, не трогает deploy-путь, безопасно для общего инстанса (enduro-trails не затронут негативно). - **NFR-6 — Наблюдаемость in-flight.** Модель становится видна в `GET /metrics`/`GET /queue` (`db.get_running_agents`) **во время** прогона, а не только после завершения (побочное улучшение launch-стампа). ## 6. Допущения и ограничения - Тайм-аут — **глобальная per-agent** настройка (не repo-scoped): поднятие бюджета `developer`/`reviewer` действует на все репо. Для enduro это благоприятно/нейтрально. - Колонка `agent_runs.model` уже существует и NULLABLE — повторная запись/COALESCE безопасны. - CLI не возвращает effort в result-JSON (причина launch-стампа эффорта ORCH-087); модель в JSON возвращается, но только при успешном финале — отсюда необходимость launch-стампа модели. - Точные числовые значения новых бюджетов (`developer`/`reviewer`) и способ их конфигурации (выделенные ключи vs `agent_timeout_overrides_json`) — решение архитектора/Owner в рамках FR-3; BRD фиксирует только **способность + инвариант NFR-4 + тест**. - Salvage недоделанной работы — отдельная возможность, вне этой задачи. ## 7. Критерии успеха Модель агента видна (не `null`) в трекере, status-комментариях и `/metrics` для ЛЮБОГО исхода прогона, включая timeout-kill; бюджеты `developer`/`reviewer` подняты и конфигурируемы без влияния на прочие роли и без нарушения reaper-инварианта; timeout-killed прогон не «протекает» в следующую стадию; всё покрыто тестами; конфиг задокументирован. Детальные PASS/FAIL — `03-acceptance-criteria.md`. ## 8. Риски - **R-1** — Поднятие бюджета выше `reaper_max_running_s − grace` → ложный reap здорового прогона (NFR-4). Митигируется sanity-тестом конфига и/или синхронным поднятием `reaper_max_running_s`. - **R-2** — Постфактум-enrich затирает корректный launch-стамп при странном JSON. Митигируется семантикой COALESCE (NULL не затирает) + тестом enrich-кейсов. - **R-3** — Гонка двух писателей `exit_code` (`_record_kill` = -9 и `_monitor_agent` = `proc.wait()`) не должна влиять на телеметрию модели (модель — отдельная колонка). Подтверждается тестом FR-4. - **R-4** — Глобальность тайм-аута: поднятие для enduro-developer могло бы маскировать зависший прогон. Митигируется тем, что Tier-3 backstop reaper'а сохраняется (NFR-4). Детали рисков и архитектурные трейд-оффы — `10-tech-risks.md` (заполняет архитектор).