wiki/tasks/orchestrator/reports/dev-2026-06-04-observability-fixes.md

Dev Report: orchestrator — 4 правки наблюдаемости + вторая дверь баг-8

Дата: 2026-06-04 Статус: DONE

Задача

Одна ветка fix/observability-and-merge-gate, один PR. 4 правки:

1. КРИТ: merge-вебхук при current_stage=="deploy" НЕ ставит done (gated by deployer verdict).
2. КРИТ: токены — показывать полный вход (input + cache_read + cache_creation), хранить cache_creation.
3. deploy→done success → Plane в терминальный Done.
4. Все агенты прикладывают ссылку на свой артефакт в финиш-коммент.

Результат — сдача

• PR: #20 — admin/orchestrator#20 (open, НЕ смержен)
• Ветка: fix/observability-and-merge-gate (от актуального main 2629dff)
• Commit: 61e26a8
• pytest (вся сюита): 244 passed, 9 failed
  • Baseline был 227 passed + 10 failed. Добавлено 17 новых тестов (227→244).
  • 9 failed = подмножество off-limits HMAC/401 группы. 10-й off-limits тест (test_plane_webhook_generates_sequential_ids) падает только в изоляции, а в полной сюите проходит из-за порядка/состояния DB — это pre-existing флак внутри off-limits группы, не связан с правками. Ни один НЕ off-limits тест не падает.

Что изменилось в каждой правке

Правка 1 — src/webhooks/gitea.py (merge-gate, баг-8 вторая дверь)

В ветке action=="closed" and pr.get("merged") добавлен ранний return при current_stage == "deploy" (только лог, без update_task_stage / advance_stage — чтобы не было гонки). Для всех остальных стадий поведение merge→done сохранено. deployer мержит PR в начале работы → merge-вебхук больше не фейк-завершает задачу; done на deploy решает только check_deploy_status через advance_stage.

Правка 2 — src/usage.py + src/db.py (полный вход токенов)

• db.py: idempotent миграция _ensure_column(agent_runs, "cache_creation_tokens", "INTEGER").
• parse_usage_from_text: добавлен cache_creation_tokens из cache_creation_input_tokens.
• record_usage: пишет новую колонку.
• Новый fmt_in(): in_total = input + cache_read + cache_creation, cached = cache_read + cache_creation. Формат 8.5M in (8.4M cached); при cached==0 — просто 45.2k in (обратно совместимо).
• usage_comment: использует fmt_in().
• task_usage_summary: total_in = SUM(input+cache_read+cache_creation), отдельно total_cached, per_agent теперь 5-кортежи; COALESCE(...,0) для NULL.
• task_summary_comment: показывает <total_in> вход (<cached> cached) / <out> выход · <cost>.
• cost_usd НЕ тронут.

Правка 3 — src/stage_engine.py + src/plane_sync.py (Plane→Done)

• plane_sync.py: новый set_issue_done() → _set_issue_state_direct(PLANE_STATES["done"]) (маппинг PLANE_STATES НЕ менялся).
• stage_engine.advance_stage: в Advance-блоке при next_stage == "done" и наличии work_item_id вызывается set_issue_done(work_item_id) (в try/except). Теперь успешный deploy→done гарантированно доводит Plane до терминального Done (раньше застревал на In Progress, т.к. merge-вебхук обходил флоу).

Правка 4 — src/usage.py + src/agents/launcher.py (ссылки на артефакты)

• usage.py: usage_comment принимает опц. repo/branch/work_item_id/pr_number; новая artifact_links() строит markdown-ссылки через gitea_public_url (fallback gitea_url): reviewer→12-review.md, tester→13-test-report.md, deployer→14-deploy-log.md, architect→06-adr/, developer→PR+branch. Отсутствующий контекст/артефакт → ссылка пропускается, не падает. analyst не тронут.
• launcher._post_usage_comments: прокидывает repo/branch/work_item_id; для developer резолвит номер открытого PR (_open_pr_number).

Изменённые файлы

• src/webhooks/gitea.py — merge-gate на deploy
• src/db.py — миграция cache_creation_tokens
• src/usage.py — парсинг/формат/summary/artifact_links
• src/plane_sync.py — set_issue_done
• src/stage_engine.py — терминальный Plane Done на deploy→done
• src/agents/launcher.py — контекст ссылок + _open_pr_number
• tests/test_usage.py — +12 тестов (cache_creation, формат cached/без, summary, ссылки)
• tests/test_webhooks.py — +2 теста (merge на deploy→не done; merge не-deploy→done)
• tests/test_stage_engine.py — +2 теста (deploy→done форсит Plane Done; не-терминал не форсит)

Проблемы и решения

• pytest нельзя запустить из репо напрямую (pycache принадлежит root, нет venv). Решение: запуск внутри контейнера orchestrator из смонтированного /repos/orchestrator с PYTHONDONTWRITEBYTECODE=1 -p no:cacheprovider.
• .env.bak-* файлы в репо untracked — НЕ добавлял в коммит (staged только 9 целевых файлов).
• Существующий тест test_usage_comment_format остался зелёным: при cache=0 in_total == input_tokens, формат 45.2k in без скобки — обратная совместимость сохранена.

Не сделано (по ТЗ)

• PR НЕ смержен — оставлен на ревью Стрим (PR #20, open).
• PLANE_STATES маппинг, HMAC, gitea_public_url конфиг, conftest.py, status-only verdict-модель — не тронуты.