orchestrator/docs/work-items/ORCH-044/12-review.md

type, work_item_id, verdict, version

type	work_item_id	verdict	version
review	ORCH-044	APPROVED	1

Review ORCH-044

Summary

PR закрывает две системные дыры слоя запуска агента (инцидент ORCH-17): P1 — token-free auth-гейт в preflight, P3 — «пустой лог / нет result-JSON ⇒ провал». P2 (--effort) корректно исключён из scope владельцем и вынесен в ORCH-50 — код effort (_spawn, resolve_agent_effort, agent_effort_*) не тронут, что соответствует коррекции в 02-trz.md и ADR-001.

Реализация полностью соответствует ТЗ и ADR-001. Документация обновлена в том же PR (README.md, internals.md, INFRA.md, CHANGELOG.md, ADR заведён). Тесты зелёные (pytest tests/ -q → 504 passed; новые test_preflight_auth.py + test_empty_log_failure.py покрывают AC-1…AC-6, AC-10…AC-14). Verdict: APPROVED.

Соответствие ТЗ / AC

• P1 (TR-1.1…1.7): preflight._check_auth() — чтение <AGENT_HOME>/.credentials.json, валидация claudeAiOauth.accessToken + expiresAt (epoch ms, skew), never-raise fail-safe. Путь резолвится от AgentLauncher.AGENT_HOME (новый _agent_home(), зеркально _claude_bin()), а не от HOME процесса орка (TR-1.3 ✓). Встроено в кешируемый _compute() (TR-1.4 ✓). Гейтинг клейма не требовал правок _drain_once (TR-1.5 ✓ — подтверждено test_worker_does_not_claim_when_auth_fails). AC-1/2/3/4/5/6 покрыты тестами.
• P3 (TR-3.1…3.5): _validate_result() (лог непустой + trailing result-JSON по контракту usage._extract_last_json_object), success = exit 0 AND result_ok. Побочные эффекты успеха (_post_usage_comments, _try_advance_stage) выполняются только при success; при пустом результате — Telegram-алерт + маршрутизация в провал через _finalize_job(result_ok=False). Реальный exit_code пишется в agent_runs без искажения (отдельный флаг — A4 из ADR). AC-10/11/12/13/14 покрыты тестами (включая test_never_running_after_empty_result, permanent/transient-классификацию).
• P1b защитная сетка: _handle_auth_marker() + is_auth_failure_text() сбрасывают preflight-кеш при маркере разлогина в логе пути провала; не transient, breaker не крутится.

Соответствие ADR

Реализация дословно следует ADR-001 (§P1 шаги 1–6, §P3 валидация + finalize, §Конфигурация: preflight_check_auth/claude_credentials_path/auth_expiry_skew_seconds). Альтернативы A4/A5 отражены в коде (отдельный result_ok вместо подмены exit_code; общий TTL вместо отдельного кеша). Verified: usage._extract_last_json_object и preflight.reset_cache существуют.

Findings

P0 — Blocker

• нет

P1 — Must fix

• нет

P2 — Should fix

• нет (опционально: PydanticDeprecation warning в config.py:4 — предсуществующий, вне scope ORCH-044).

Документация

Обновлена корректно и в том же PR (правило агентов №2/№6, AC-15):

• docs/architecture/README.md — описание Preflight (auth) и Agent Launcher (валидация результата);
• docs/architecture/internals.md — §4 «Валидация результата», постфактум auth-детекция, таблица resilience, диаграмма _finalize_job(result_ok);
• docs/operations/INFRA.md — env-карта (3 новые настройки) + раздел «Preflight auth-гейт» с риском R-1;
• CHANGELOG.md — запись [Unreleased] / Added;
• ADR 06-adr/ADR-001-preflight-auth-and-empty-result-failure.md заведён; 10-tech-risks.md присутствует.

Self-hosting (AC-17)

Изменения только в слое preflight/launch — не требуют рестарта прод-контейнера в рамках задачи. Выкатка через обязательный staging-гейт (8501) перед прод. Риск ложноположительного auth-fail (R-1) митигирован тумблером ORCH_PREFLIGHT_CHECK_AUTH и проверкой на staging.