From f120e4bd8f37c7dc9b871810031daf594cefcef0 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 01:37:27 +0300 Subject: [PATCH] architect(ET): auto-commit from architect run_id=733 --- docs/architecture/README.md | 7 + .../adr-0048-deterministic-staging-runner.md | 92 +++++ docs/architecture/internals.md | 14 + .../ADR-001-deterministic-staging-runner.md | 335 ++++++++++++++++++ .../ORCH-115/07-infra-requirements.md | 61 ++++ .../ORCH-115/08-data-requirements.md | 43 +++ docs/work-items/ORCH-115/10-tech-risks.md | 44 +++ 7 files changed, 596 insertions(+) create mode 100644 docs/architecture/adr/adr-0048-deterministic-staging-runner.md create mode 100644 docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md create mode 100644 docs/work-items/ORCH-115/07-infra-requirements.md create mode 100644 docs/work-items/ORCH-115/08-data-requirements.md create mode 100644 docs/work-items/ORCH-115/10-tech-risks.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 848b8ed..32e54ba 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -10,6 +10,7 @@ - **Review/Test Parsers** (`src/review_parse.py`, ORCH-046) — defensive-извлечение дословного must-fix текста из артефактов для встраивания в `task_desc` заворота: `extract_review_findings` (P0/P1 из `12-review.md`), `extract_test_failures` (фрагмент тела `13-test-report.md`). Контракт «never raise»: любая ошибка → `""`. - **Quality Gates** (`src/qg/checks.py`) — проверки выхода со стадии, реестр `QG_CHECKS`. - **Agent Launcher** (`src/agents/launcher.py`) — запуск Claude CLI агентов в изолированном git worktree, мониторинг, auto-advance. Модель/эффорт каждого агента резолвятся из config (`resolve_agent_model`/`resolve_agent_effort`, ORCH-41), а не из frontmatter промпта. **ORCH-74:** имя модели валидируется форматом `^claude-…$` (`is_valid_model`) перед `--model`; невалидное → лог + откат на следующий уровень/CLI-дефолт (never-break, как `VALID_EFFORTS` для эффорта). Тот же предикат гардит inline-чтение `--fallback-model`. **ORCH-109 ([adr-0040](adr/adr-0040-agent-timeout-budgets-and-launch-model-stamp.md)):** (1) резолвенная **модель стампится в `agent_runs.model` в момент launch** (`_spawn`, объединённый `UPDATE … SET model=?, effort=?` рядом со стампом эффорта ORCH-087; пустой резолв → `NULL`; never-raise) → модель видна не-`null` при любом исходе прогона, включая timeout-kill (`exit_code=-9`), и in-flight в `GET /metrics`/`GET /queue` (`get_running_agents` уже отдаёт `model`); постфактум `record_usage` (`model=COALESCE(?, model)`) остаётся **обогащением**, не единственным источником истины. (2) **Per-role wall-clock бюджеты** через выделенные ключи `agent_timeout_developer_s=3600`/`agent_timeout_reviewer_s=3000` (лестница `_resolve_timeout`: `agent_timeout_overrides_json` → выделенный ключ роли → `agent_timeout_seconds=1800`; прочие роли — байт-в-байт; малформный/вне-диапазонный конфиг → дефолт + WARNING). Инвариант reaper ORCH-065 сохранён синхронным поднятием `reaper_max_running_s` 3600→**5400** (`5400 > max(timeout)3600 + grace20`). FR-5 анти-salvage — структурно: продвижение гейтится `if exit_code==0`, timeout-kill → `_finalize_job` (retry/fail), не advance. `STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД не тронуты. +- **Staging-runner** (`src/staging_runner.py`, ORCH-115 — [adr-0048](adr/adr-0048-deterministic-staging-runner.md)) — чистый **never-raise** leaf (паттерн `self_deploy`/`proc_group`/`staging_verdict`), заменяющий **LLM-агента `deployer` на стадии `deploy-staging`** детерминированным кодом (первый реализованный срез determinization-roadmap, A6/`replace-deterministic-now`). Перехват в `launch_job` **до `_spawn`** (рядом с D1/D2 `deploy-finalizer`/`post-deploy-monitor`): дискриминатор — **стадия задачи** `deploy-staging` **И** `applies(repo)` (kill-switch `staging_runner_enabled` + скоуп `staging_runner_repos`, пусто → self-hosting only), `should_intercept` never-raise → `False` → штатный `_spawn` (fail-safe к LLM). Раннер (зеркало `run_deploy_finalizer`) исполняет ту же staging-сюиту (`docker exec orchestrator-staging … staging_check.py`) через `proc_group` (tree-kill, таймаут `staging_runner_timeout_s=600`), маппит exit-код единым контрактом `self_deploy.map_exit_code_to_status` (`0→SUCCESS`/иначе→`FAILED`; ORCH-061 infra-tolerance остаётся внутри `staging_check.py`), пишет `15-staging-log.md` (тот же machine-key `staging_status:`, `author_agent: staging-runner`/`model_used: n/a`) + best-effort push в фичеветку, и вызывает **существующий** `advance_stage(current_stage="deploy-staging", finished_agent="deployer")` — без новых рёбер/исходов; transition-lease ORCH-114 берётся внутри `advance_stage` (раннер не трогает). **Двухуровневый исход (анти-ORCH-110):** сюита исполнилась → verdict→advance (FAILED → тот же откат `deploy-staging → development` + developer-retry, что у LLM); tool-error/таймаут → bounded defer (`staging_runner_infra_max_retries`) → fail-closed `FAILED` + alert на исчерпании (инфра ≠ код-фейл, никогда тихий advance/ложный green). `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_staging_status`/`_parse_staging_status`/machine-verdict/схема БД — **байт-в-байт не тронуты** (замена *продюсера*, не гейта). Наблюдаемость — in-process счётчики + блок `staging_runner` в `GET /queue`. Откат — `ORCH_STAGING_RUNNER_ENABLED=false` (прежний LLM-deployer-путь байт-в-байт). Детали — `docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md`. - **Queue** (`src/queue_worker.py`, ORCH-1) — персистентная очередь задач (SQLite `jobs`), atomic claim, max_concurrency, ретраи, restart-safe. **ORCH-026:** `claim_next_job` гейтит задачи с незавершёнными зависимостями (`job_deps`, `NOT EXISTS`) без занятия слота; декларации/циклы — leaf `src/task_deps.py`. - **Job-reaper** (`src/job_reaper.py`, ORCH-065 — [adr-0011](adr/adr-0011-job-reaper-lease-reclaim.md)) — фоновый daemon-поток (каркас `reconciler`), стартует/останавливается в `main.lifespan` (после `reconciler.start()` / перед `worker.stop()`). Детектирует «мёртвый» `running`-job **без рестарта** процесса (Tier-1 мёртвый `jobs.pid` после `reaper_dead_ticks` тиков; Tier-2 `agent_runs.exit_code` записан, а job ещё `running`; Tier-3 backstop `reaper_max_running_s`) и приводит строку к корректному статусу через те же контракты (`_try_advance_stage`/`_finalize_job`, gate-driven; exit≠0/неизвестно → `attempts`. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схемы существующих таблиц — байт-в-байт. Подробнее ниже (§ «Единое владение side-effectful переходами»). Детали — `docs/work-items/ORCH-114/06-adr/ADR-001-transition-ownership-lease-and-stage-cas.md`. @@ -441,6 +442,12 @@ ORCH-079 синхронизирует витрину с кодом и закры control-path-инвариант сверки с `src/qg/checks.py` и фиксацию avoidable-набора). - **Норматив сопровождения:** менял места вызова LLM **или** потребителя вердикта в `src/qg/checks.py` → обнови карту/разметку и политику в том же PR. +- **Первый срез реализован (ORCH-115 — [adr-0048](adr/adr-0048-deterministic-staging-runner.md)):** + rank-1 кандидат **deployer (staging-status)** заменён детерминированным `src/staging_runner.py` + (перехват в `launch_job` до `_spawn`, как D1/D2) — A6 переходит из «план» в «реализовано». Карта + `llm-call-sites.md` (A6), `llm-determinization-roadmap.md` (rank 1, инвариант «ровно один + `first_slice`») и анти-дрейф-тесты обновляются **атомарно с кодом** в development (норматив + сопровождения NFR-6). Второй кандидат — `tester`-гибрид (rank 2) — остаётся планом. - ADR: [adr-0047](adr/adr-0047-llm-usage-policy-and-call-site-map.md); детально — `docs/work-items/ORCH-118/06-adr/ADR-001-llm-call-site-map-and-determinization-roadmap.md`. diff --git a/docs/architecture/adr/adr-0048-deterministic-staging-runner.md b/docs/architecture/adr/adr-0048-deterministic-staging-runner.md new file mode 100644 index 0000000..b219fee --- /dev/null +++ b/docs/architecture/adr/adr-0048-deterministic-staging-runner.md @@ -0,0 +1,92 @@ +--- +work_item: ORCH-115 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# adr-0048: Детерминированный staging-раннер — первый реализованный срез determinization-roadmap + +> **Сквозной (cross-cutting) ADR.** Агрегирует решение ORCH-115, влияющее на **весь** +> оркестратор: вводит новый компонент-leaf `src/staging_runner.py`, снимает первую +> avoidable LLM-консультацию (`deployer`/`staging-status`, A6) и переводит rank-1 +> determinization-roadmap из «план» в «реализовано». Локальная детализация (все решения +> D1–D11) — `docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md`. + +## Статус +Proposed + +## Контекст + +ORCH-118 ([adr-0047](adr-0047-llm-usage-policy-and-call-site-map.md)) зафиксировал +нормативную политику и карту LLM-консультаций и назвал **avoidable LLM control paths = +`{tester, deployer}`**, поставив **deployer (staging-status)** первым срезом +(`first_slice = yes`, `replace-deterministic-now`, `hybrid_needed = no`). ORCH-118 раннеры +**не реализовывал** (docs+tests). ORCH-115 — первая фактическая реализация этого среза. + +Вердикт `staging_status:` на стадии `deploy-staging` сейчас эмитит LLM-агент `deployer`, но +он есть **чистый маппинг exit-кода** `scripts/staging_check.py` (infra-tolerance ORCH-061 +уже внутри скрипта), а гейт `check_staging_status` детерминирован. Это удовлетворяет обоим +условиям «avoidable»: C-консультация **и** деривируемый вердикт. Прецедент детерминированной +замены агента (`launch_job`-перехват до `_spawn`, D1/D2 `deploy-finalizer`/`post-deploy-monitor`) +и эталон «детерминированный джоб → `advance_stage`» (`run_deploy_finalizer`) уже работают в +проде — архитектурный риск снят. + +## Решение + +**Новый leaf `src/staging_runner.py` + перехват в `launch_job` до `_spawn`** (рядом с D1/D2). +На `deploy-staging` для in-scope репо джоб `deployer` обрабатывает раннер: исполняет +staging-сюиту через `proc_group` (tree-kill, ORCH-110), маппит exit-код единым контрактом +`self_deploy.map_exit_code_to_status`, пишет `15-staging-log.md` (тот же machine-key +`staging_status:`), вызывает **существующий** `advance_stage(finished_agent="deployer")`. + +Кросс-каттинговые инварианты (сохранены **байт-в-байт**): +- `STAGE_TRANSITIONS` (`src/stages.py`), реестр и имена `QG_CHECKS`/`check_*`/`_parse_*`, + machine-verdict-ключи (`staging_status:`/`deploy_status:`/`verdict:`/`result:`/ + `security_status:`/`coverage_status:`), **схема БД** — не тронуты. Это замена *продюсера* + артефакта, не гейта/стадии. +- Единственный транспорт LLM-консультации (`launcher._spawn`/S0, + [llm-usage-policy.md](../llm-usage-policy.md) §5) — соблюдён: раннер **не зовёт LLM**; + второй транспорт не вводится. +- Сквозной бюджет времени ORCH-065/109/110 (`reaper_max_running_s` > Σ(работ на ребре + `deploy-staging`) + grace) — соблюдён **без** правки `reaper_max_running_s` (раннер-таймаут + 600s ≤ прежнего LLM-окна). +- Граница ORCH-112/ORCH-114: transition-lease берётся **внутри** `advance_stage`; раннер + lease/гигиену не модифицирует. + +Скоуп — **self-hosting only** (`staging_runner_repos=""` → `is_self_hosting_repo`), под +kill-switch `staging_runner_enabled` (off → `_spawn` LLM-deployer'а байт-в-байт). never-raise +во всех публичных функциях; **двухуровневый исход** (verdict при исполнившейся сюите; bounded +defer → fail-closed на tool-error/таймауте) убирает с staging-ребра RCA-класс ORCH-110 (инфра +≠ код-фейл). + +**Эволюция карты LLM (норматив сопровождения, в том же PR — D11 локального ADR):** +`llm-call-sites.md` (A6 → реализовано детерминированно), `llm-determinization-roadmap.md` +(rank 1 deployer → реализован; инвариант «ровно один `first_slice`» цел), `llm-usage-policy.md` +(§5 — транспорт не нарушен), плюс анти-дрейф-тесты (`test_llm_call_site_inventory.py`/ +`test_llm_determinization_docs.py`). Эти правки коуплены к коду → применяются в development +атомарно с реализацией, не в architecture-стадии. + +## Последствия + +- **+** Минус один avoidable LLM control path; первый доказанный раннер-паттерн замены + C-консультации (опора для второго кандидата — `tester`-гибрид, rank 2). +- **+** Дешевле/быстрее/детерминированнее собственный `deploy-staging`; нет токенов/латентности + LLM в точке ветвления. +- **+** Паттерн переиспользуем: leaf + перехват до `_spawn` + `advance_stage` — шаблон для + будущих срезов и для Phase 2 (project deploy contract не-self репо). +- **−** Новый компонент + врезка + defer-механика. Митигейшн: never-raise leaf, kill-switch + (fail-safe к LLM), без схемы БД, структурное покрытие. +- **Откат:** `ORCH_STAGING_RUNNER_ENABLED=false` → прежний LLM-путь на `deploy-staging` + байт-в-байт. + +## Ссылки +- Локальный ADR: `docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md` +- Политика/карта/roadmap: [llm-usage-policy.md](../llm-usage-policy.md), + [llm-call-sites.md](../llm-call-sites.md), [llm-determinization-roadmap.md](../llm-determinization-roadmap.md), + [adr-0047](adr-0047-llm-usage-policy-and-call-site-map.md) +- Прецеденты: D1/D2 (`launcher.py:389/394`), `run_deploy_finalizer` (`stage_engine.py:2010`), + `proc_group` (ORCH-110, [adr-0042](adr-0042-merge-gate-retest-infra-tolerance-and-tree-kill.md)), + transition-lease (ORCH-114, [adr-0045](adr-0045-transition-ownership-lease-and-stage-cas.md)) diff --git a/docs/architecture/internals.md b/docs/architecture/internals.md index daa79f2..781743f 100644 --- a/docs/architecture/internals.md +++ b/docs/architecture/internals.md @@ -96,6 +96,20 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash 3. Стартует **watchdog thread** (per-role wall-clock бюджет → SIGTERM→grace→SIGKILL по pid; ORCH-109: developer 60 мин / reviewer 50 мин / прочие 30 мин дефолт, `_resolve_timeout`) 4. Стартует **monitor thread**: `proc.wait()` (гарантированный reap → реальный exit_code в БД) → закрывает log_fh → git commit/push → auto-advance +**Детерминированные перехваты `launch_job` ДО `_spawn` (no-LLM джобы).** Перед `_spawn` `launch_job` +перехватывает зарезервированные роли и исполняет их детерминированно, сам ведя `jobs`-строку через +`mark_job` (нет `agent_runs`, нет токенов): `deploy-finalizer` (D1, ORCH-036 Phase C) и +`post-deploy-monitor` (D2, ORCH-021). **ORCH-115 ([adr-0048](adr/adr-0048-deterministic-staging-runner.md)):** +тем же паттерном перехватывается джоб `deployer` на стадии `deploy-staging` для in-scope репо +(дискриминатор — **стадия задачи**, не имя роли: роль `deployer` общая для `deploy-staging`/`deploy`; ++`staging_runner.applies(repo)` под kill-switch `staging_runner_enabled`, скоуп `staging_runner_repos`, +пусто → self-hosting only; `should_intercept` never-raise → `False` → штатный `_spawn`, fail-safe к +LLM). Leaf `src/staging_runner.py` (зеркало `run_deploy_finalizer`) исполняет staging-сюиту через +`proc_group` (tree-kill, таймаут `staging_runner_timeout_s`), маппит exit-код +`self_deploy.map_exit_code_to_status`, пишет `15-staging-log.md` (тот же machine-key `staging_status:`) +и вызывает существующий `advance_stage(finished_agent="deployer")` (см. §5). Так LLM-агент `deployer` +на `deploy-staging` исчезает из happy-path; `STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД не тронуты. + ### 5. Auto-advance (`launcher._try_advance_stage`) После успешного завершения агента: diff --git a/docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md b/docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md new file mode 100644 index 0000000..fed0749 --- /dev/null +++ b/docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md @@ -0,0 +1,335 @@ +--- +work_item: ORCH-115 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# ADR-001: Детерминированный staging-раннер вместо LLM-деплойера на `deploy-staging` + +Work Item: **ORCH-115** — заменить LLM-агента `deployer` на стадии `deploy-staging` +(self-hosting `orchestrator`) детерминированным staging-раннером. +Стадия: **architecture** +Сквозная регистрация: **`docs/architecture/adr/adr-0048-deterministic-staging-runner.md`** +(решение кросс-каттинговое — вводит новый компонент-leaf и реализует первый срез +determinization-roadmap; влияет на карту LLM-консультаций всего оркестратора). + +## Статус +Proposed + +## Контекст + +Стадию `deploy-staging` сейчас исполняет **LLM-агент `deployer`** (`src/stages.py`: +`get_agent_for_stage("testing") = "deployer"`; роль в `launcher.AGENTS`). Фактическая +работа агента на этой стадии — **чисто детерминированная** (`.openclaw/agents/deployer.md` +шаги 1–4): + +1. запустить staging-сюиту — `docker exec orchestrator-staging python3 + /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub`; +2. смаппить **exit-код** в вердикт (`0 → SUCCESS`, ≠0 → `FAILED`) — infra-tolerance + ORCH-061 уже **внутри** `staging_check.py` (`src/staging_verdict.py::compute_staging_verdict`), + агент её не пересуживает; +3. записать `15-staging-log.md` с frontmatter `staging_status:`; +4. закоммитить лог. + +Вердикт `staging_status:` потребляется детерминированным гейтом `check_staging_status` +(`src/qg/checks.py:599` → `_parse_staging_status:538`). По нормативной политике +(`docs/architecture/llm-usage-policy.md` §3) это **avoidable LLM control path**: (i) это +C-консультация (LLM-вердикт ветвит гейт) **и** (ii) вердикт **деривируем** из exit-кода +инструмента, который оркестратор уже умеет вычислять сам. Карта call-site'ов +(`docs/architecture/llm-call-sites.md`, строка **A6**) классифицирует deployer как +`replace-deterministic-now`; roadmap (`llm-determinization-roadmap.md`, rank 1, +`first_slice = yes`, `hybrid_needed = no`) ставит его первым срезом. ORCH-115 — реализация +этого среза. + +**Установленные факты (сверено по коду, не изобретать):** +- Детерминированный прецедент замены агента уже работает: `launch_job` перехватывает + зарезервированные роли `deploy-finalizer` (D1, `src/agents/launcher.py:389`) и + `post-deploy-monitor` (D2, `:394`) **до `_spawn`** и исполняет их как no-LLM-джобы, + сами ведущие `jobs`-строку через `mark_job`. +- Эталонный поток «детерминированный джоб → вердикт → существующий контракт»: + `stage_engine.run_deploy_finalizer` (`:2010`) маппит exit-код, пишет `14-deploy-log.md` + и вызывает `advance_stage(..., finished_agent="deployer")`, после чего срабатывают + **существующие** контракты (`SUCCESS → done`/advance, `FAILED → откат на development`). +- Пьюр-маппинг exit-кода уже есть: `self_deploy.map_exit_code_to_status` (`:81`, + `0→SUCCESS`, иначе/None/нечисло→`FAILED`, fail-closed, unit-tested). +- Tree-kill subprocess'а под таймаутом уже есть: `proc_group.run_in_process_group` + (ORCH-110, stdlib-only leaf, never-raise, fallback к `subprocess.run`). +- Прод-ребро `deploy` для self-hosting уже детерминировано (`self_deploy` Phase A/B/C, + ORCH-036) — `deployer` там **не спавнится** (Phase A — `finished_agent is None`-путь). + Срез не трогает критический прод-путь. + +«Как есть» не годится: каждый прогон тратит токены/время opus-агента (по `agent_runs`: +~40–120k / 3–15 мин на прогон) ради действия в три shell-строки, встраивает недетерминизм +LLM в точку ветвления и принадлежит к RCA-классу «LLM принял решение, которое есть +исполнение фиксированных команд + маппинг результата» (ORCH-110/111/112/113/114/117). + +## Решение + +### Сводка + +Ввести **новый leaf `src/staging_runner.py`** (never-raise, по образцу +`self_deploy.py`/`proc_group.py`/`staging_verdict.py`) и **перехват в `launch_job` до +`_spawn`** (рядом с D1/D2). Когда на стадии `deploy-staging` для in-scope репо к запуску +приходит джоб `deployer`, его обрабатывает раннер: исполняет ту же staging-сюиту через +`proc_group`, маппит exit-код в `staging_status:`, пишет `15-staging-log.md`, и вызывает +**существующий** `advance_stage(current_stage="deploy-staging", finished_agent="deployer")` +— ровно как завершившийся LLM-deployer. Контракт артефакта, гейт `check_staging_status`, +`STAGE_TRANSITIONS`, схема БД — **байт-в-байт неизменны** (это замена *продюсера* +артефакта, не гейта). Под kill-switch + скоуп-CSV; fail-safe к прежнему LLM-пути. + +### D1 — Точка диспетчеризации: перехват в `launch_job` **до** `_spawn` (FR-1 / AC-1) + +В `launcher.launch_job`, рядом с существующими врезками D1/D2, **до** `_spawn`: + +```python +if job.get("agent") == "deployer" and staging_runner.should_intercept(job): + return self._run_staging_runner_job(job) +``` + +- **Дискриминатор «staging vs prod» — стадия задачи, НЕ имя роли** (роль `deployer` общая + для `deploy-staging` и `deploy`). `should_intercept(job)` истинно ⇔ `agent=="deployer"` + **И** `tasks.stage` (по `job["task_id"]`) `== "deploy-staging"` **И** + `staging_runner.applies(job["repo"])`. Гард по стадии — защита от перехвата не того джоба + (R-1): для self-hosting прод-ребро `deployer` не запускает; для не-self репо прод-`deploy` + запускает синхронный ssh-deployer — но там `applies==False`, поэтому не перехватывается + (NFR-5; TC-06). +- `should_intercept` — **never-raise**: любая ошибка (DB-lookup упал) → `False` → провал + в `_spawn` (fail-safe к прежнему LLM-пути). +- `_run_staging_runner_job(job)` — тонкая обёртка-зеркало `_run_deploy_finalizer_job` + (`:404`): синхронно зовёт `staging_runner.run_staging_gate(job)`, затем + `mark_job(job["id"], "done")`; любое исключение → `mark_job(..., "failed", error=…)`; + возвращает `None` (нет `agent_runs`-строки, `_spawn` не вызывается). + +### D2 — Размещение логики: чистый leaf `src/staging_runner.py` (зеркало finalizer) + +`run_staging_gate(job)` живёт в leaf'е и владеет полным детерминированным потоком +(зеркало `stage_engine.run_deploy_finalizer`): +1. поднять `work_item_id`/`branch`/`stage` по `task_id`; +2. исполнить staging-сюиту (D3) → `(returncode, timed_out, stdout)`; +3. определить исход (D5); +4. на verdict-исходе: записать `15-staging-log.md` (D6) и вызвать + `advance_stage(finished_agent="deployer")` (D7); +5. на defer-исходе: requeue (D5); +6. учесть счётчики + структурный лог (D10). + +**Чистота leaf'а:** импортирует на уровне модуля только `config`, `logging` (+ `proc_group`); +лениво (внутри функций) — `db`/`git_worktree`/`self_deploy.map_exit_code_to_status`/ +`qg.checks.is_self_hosting_repo`/`stage_engine.advance_stage`/`notifications`. Лениво — +чтобы не тащить тяжёлый `stage_engine` на импорте и не плодить цикл (паттерн +`transition_lease`/`merge_gate`). Все публичные функции — **never-raise** (AC-7). + +### D3 — Исполнение сюиты: `proc_group` + config-арги (FR-2 / NFR-3 / AC-9 / AC-8) + +Команда строится из конфига (ORCH-101, без host-хардкодов — анти-дрейф +`tests/test_no_host_hardcodes.py`): + +``` +docker exec python3 //scripts/staging_check.py \ + --base-url http://localhost: --mode stub +``` +где `STAGING_SERVICE = "orchestrator-staging"` (платформенный сервис-литерал, уже допущен — +ср. `image_freshness._STAGING_SERVICE:68`), `repos_dir`/`staging_port` из `settings`, +`SELF_HOSTING_REPO` из `qg.checks`. Запуск — через +`proc_group.run_in_process_group(argv, cwd=None, timeout=, +tree_kill=settings.subprocess_tree_kill_enabled)` → SIGTERM→grace→SIGKILL всего дерева на +таймауте, без сирот docker/pytest (согласовано с ORCH-110). **Self-hosting safety +(BR-7/AC-8):** в argv нет литералов рестарта 8500 / `docker compose up … orchestrator` / +`--build` / force-push / правок `.env` — раннер только читает и исполняет staging-сюиту +(8501) и пишет лог. Покрывается TC-12 (запрет литералов). + +### D4 — Маппинг exit-кода: переиспользовать единый контракт (FR-3 / AC-3) + +`staging_status` = `self_deploy.map_exit_code_to_status(returncode)` (`0→SUCCESS`, иначе/ +None/нечисло→`FAILED`, fail-closed). **Второй маппинг не вводится** — общий пьюр-контракт, +уже покрытый unit-тестом. infra-tolerance ORCH-061 остаётся внутри `staging_check.py` — +раннер вердикт повторно не судит (BR-4). + +### D5 — Двухуровневый исход: verdict vs tool-error (NFR-2 / AC-7 / R-3 / R-5) — **ключевое решение** + +`AC-7`/`NFR-2`/A1 явно оставляют обработку «инструмент недоступен» архитектору, разрешая +**FAILED (fail-closed) ИЛИ штатный requeue/defer**. Выбран **двухуровневый исход**: + +- **Сюита ИСПОЛНИЛАСЬ (получен реальный exit-код, 0 или ≠0):** доверяем коду. + `0 → SUCCESS → advance`; `≠0 → FAILED → откат deploy-staging → development` через + `advance_stage` (тот же путь и developer-retry-cap, что у FAILED-вердикта LLM — + `stage_engine.py:932`; R-5/AC-4). ORCH-061 уже внутри exit-кода. +- **Сюита НЕ исполнилась (tool-error: spawn-error / таймаут / `returncode is None`):** + это **инфра-сбой, а не код-фейл**. Раннер делает **ограниченный DEFER** — requeue + свежего `deployer`-джоба с задержкой и маркером в `task_content` (restart-safe счётчик + подсчётом маркера — зеркало `merge_gate._merge_infra_retry_count` ORCH-110 и + `_deploy_finalize_defer_count` ORCH-036; **без правки схемы БД**, NFR-1). На + **исчерпании** бюджета (`staging_runner_infra_max_retries`) — **fail-closed**: записать + `staging_status: FAILED` + `advance_stage` (откат) + alert (кликабельный номер). Так + раннер **никогда не делает тихий advance / ложный green** и **никогда не клинит очередь + навсегда**, но **не жжёт developer-retry на транзиентной инфре**. + +**Почему не «tool-error → немедленный FAILED-откат»:** это в точности анти-паттерн ORCH-110 +(инфра-таймаут, ошибочно маршрутизированный как код-фейл → откат на `development` + расход +developer-retry; на следующем retry падает так же → ручное вмешательство). RCA-осведомлённый +reviewer ловит это как регресс. Пьюр-маппинг D4 остаётся fail-closed (None→FAILED) — он +терминальный fallback на исчерпании defer, а не реакция на первый же tool-error. + +### D6 — Артефакт `15-staging-log.md`: зеркало `write_deploy_log` (FR-4 / AC-2 / AC-8) + +Раннер пишет `docs/work-items//15-staging-log.md` в worktree фичеветки +(`git_worktree.get_worktree_path`) с frontmatter: + +```markdown +--- +staging_status: SUCCESS # или FAILED — UPPERCASE, имя/регистр ключа не меняются +work_item: +stage: deploy-staging +author_agent: staging-runner +status: success # или failed — выровнен по staging_status +created_at: +model_used: n/a +timestamp: +base_url: http://localhost: +exit_code: +--- + +# Staging Gate Log (deterministic runner, ORCH-115) + +``` + +- `author_agent: staging-runner` / `model_used: n/a` честно отражают **детерминированного** + продюсера; **machine-key `staging_status:` и его регистр/значения не меняются** (AC-2/AC-5), + читается неизменённым `_parse_staging_status` (TC-04). +- Запись через `frontmatter.render/write_frontmatter` либо литералом — обязательная 52c-схема + присутствует. +- **Best-effort commit+push в ФИЧЕВЕТКУ** (зеркало `write_deploy_log` — git-identity + ORCH-101, `_GIT_TIMEOUT`). Гейт читает worktree **первым** (`check_staging_status` lookup + order, `:627`), поэтому отдельный PR-merge лога в `main` **не выполняется** — это + сознательное упрощение относительно шага-4 LLM-deployer'а: исключает любую прямую работу с + `main` (усиливает AC-8/BR-7). Итоговый мерж фичеветки в `main` идёт штатным + merge-gate/merge-verify-путём позже. + +### D7 — Инициация существующего гейта (FR-5 / AC-4 / R-2 / R-4, граница O1) + +После записи лога раннер вызывает: +```python +advance_stage(task_id, current_stage="deploy-staging", repo, work_item_id, branch, + finished_agent="deployer") +``` +Это запускает `check_staging_status` и — на SUCCESS — существующие под-гейты +security→merge→coverage→image-freshness (ORCH-022/043/027/058) и Phase A (ORCH-036); на +FAILED — существующий откат (`stage_engine.py:932`). **Никакой новой ветви маршрутизации, +никаких новых рёбер/исходов** (AC-4). **Граница O1/R-4:** transition-lease ORCH-114 +берётся **внутри** `advance_stage` на side-effectful ребре — раннер его **не трогает**; +serial-gate ORCH-088 не взаимодействует (гейтит analyst-job claim, не deployer-job). +Код ORCH-112/ORCH-114 не модифицируется. + +### D8 — Kill-switch и скоуп: обратимость (FR-6 / AC-6 / BR-5) + +`config.py` (паттерн `coverage_gate_*`/`self_deploy_*`): +- `staging_runner_enabled: bool = True` (env `ORCH_STAGING_RUNNER_ENABLED`). +- `staging_runner_repos: str = ""` (env `ORCH_STAGING_RUNNER_REPOS`; CSV; **пусто → + self-hosting only** через `is_self_hosting_repo`). +- `staging_runner_timeout_s: int = 600` (env `ORCH_STAGING_RUNNER_TIMEOUT_S`; см. D9). +- `staging_runner_infra_max_retries: int = 2`, `staging_runner_infra_retry_delay_s: int = 30` + (defer-бюджет D5; зеркало `merge_retest_infra_*`). + +`applies(repo)` (локально, без сети, **never-raise → False**): `staging_runner_enabled==False` +→ `False` (откат к LLM-пути); непустой CSV → membership; пустой → `is_self_hosting_repo(repo)`. +Проверяется **первым** в `should_intercept` → при выключенном флаге нулевой оверхед, на +`deploy-staging` штатно вызывается `_spawn` (прежний LLM-deployer **байт-в-байт**). Откат = +`ORCH_STAGING_RUNNER_ENABLED=false`. + +### D9 — Бюджет времени (NFR-4 / AC-9, сквозной инвариант ORCH-065/109/110) + +`staging_runner_timeout_s = 600` (дефолт; малформ/непозитив → дефолт + WARNING, never-break +— зеркало `_resolve_retest_timeout`). Обоснование инварианта **без правки +`reaper_max_running_s` (5400)**: окно «running» одного deployer-джоба = `staging_check` +(≤600s) + те же edge-под-гейты, что и раньше (security + merge re-test 900 + coverage 900 + +image-freshness rebuild). В LLM-пути это окно включало staging-прогон LLM (3–15 мин, до ~900s) ++ те же под-гейты. Раннер заменяет до-900s LLM-окна ограниченными ≤600s → **Σ(работ на ребре) +не растёт** → инвариант `reaper_max_running_s > Σ + grace` сохранён без изменения reaper'а. + +### D10 — Наблюдаемость (FR-7 / AC-10 / BR-6) + +In-process счётчики `_STAGING_RUNNER_COUNTERS` (зеркало `_MERGE_GATE_COUNTERS`, +`merge_gate.py:678`): `runs`/`success`/`failed`/`tool_error`/`deferred`. Read-only блок +`staging_runner` в `GET /queue` (`enabled`/`repos`/счётчики) — `src/main.py`. Один +структурный лог-вердикт на прогон: `work_item`/`repo`/`exit_code`/`status`/`duration_s`/ +`outcome` — различает «код упал» (`FAILED` от сюиты) и «инструмент недоступен» (`tool_error`/ +`deferred`). (Опционально, как ORCH-110: на исчерпании defer записать lesson `transient_retry` +через `lessons.record` — не обязательно для приёмки.) + +### D11 — Норматив сопровождения LLM-карты (NFR-6 / AC-11) — спека для developer + +Карта/политика/roadmap и их анти-дрейф-тесты **связаны с состоянием кода**, поэтому правятся +**в development-стадии атомарно с кодом** (иначе тесты покраснеют на полу-готовой ветке). +Архитектура фиксирует **точную спеку** правок (developer применяет в том же PR): +- `docs/architecture/llm-call-sites.md` — строка **A6** и машинный + `ORCH-118-INVENTORY-BLOCK`: deployer на `deploy-staging` для in-scope репо больше не + консультирует LLM; отразить реализованное детерминированное состояние (раннер-перехват до + `_spawn`, как D1/D2), сохранив парсимый заголовок таблицы; синхронно — `_parse_staging_status` + остаётся потребителем (имя гейта не меняется). +- `docs/architecture/llm-determinization-roadmap.md` — машинный `ORCH-118-ROADMAP-BLOCK`: + rank 1 (deployer) переходит из «план» в «реализовано»; **инвариант «ровно один + `first_slice = yes`»** держать корректным (см. `test_llm_determinization_docs.py`). +- `docs/architecture/llm-usage-policy.md` — §5: единственный транспорт LLM-консультации + (`_spawn`/S0) не нарушен; ввод второго транспорта запрещён (раннер LLM не зовёт). +- Анти-дрейф `tests/test_llm_call_site_inventory.py` / `tests/test_llm_determinization_docs.py` + — обновить ожидания синхронно, держать зелёными (TC-14). +- Прочие docs того же PR (правило агентов №2): `.openclaw/agents/deployer.md` (пометка, что + на `deploy-staging` для in-scope репо стадию ведёт детерминированный код; LLM-ветвь — + fallback под выключенным флагом / не-self репо), `CLAUDE.md`, `CHANGELOG.md`, + `docs/overview/`. + +**Обоснование против `llm-usage-policy.md` §5:** ORCH-115 **снимает** C-консультацию с +деривируемым вердиктом (A6/staging-status) — это разрешённое `replace-deterministic-now`, +не ввод новой LLM-консультации; политика соблюдена. + +## Альтернативы + +- **Новая стадия / новый QG для детерминированного staging** — отвергнуто: нарушает NFR-1 + (`STAGE_TRANSITIONS`/`QG_CHECKS` байт-в-байт). Меняется только *продюсер* артефакта; гейт + и ребро прежние. +- **tool-error → немедленный `FAILED`-откат на `development`** — отвергнуто: анти-паттерн + ORCH-110 (инфра-сбой как код-фейл → расход developer-retry → петля). Выбран двухуровневый + исход D5 (defer на tool-error, fail-closed на исчерпании). +- **Merge лога отдельным PR в `main`** (как шаг-4 LLM-deployer'а) — отвергнуто: гейт читает + worktree первым → достаточно push в фичеветку; исключение прямой работы с `main` усиливает + AC-8/BR-7. +- **Логика раннера прямо в `launcher.py`** — отвергнуто: нарушает разделение + транспорт/решение; leaf тестируем без живого CLI/docker (зеркало + `self_deploy`/`coverage_gate`). +- **Править `llm-call-sites.md`/roadmap/policy в architecture-стадии** — отвергнуто: + анти-дрейф-тесты коуплены к коду; правки идут атомарно с кодом (D11). +- **Свой второй exit-code→verdict маппинг** — отвергнуто: переиспользуем + `self_deploy.map_exit_code_to_status` (BR-4, единый контракт). + +## Последствия + +- **+** На `deploy-staging` для `orchestrator` исчезает LLM-консультация: дешевле/быстрее/ + детерминированнее; минус один avoidable LLM control path (первый срез roadmap). +- **+** Happy-path не вызывает `_spawn` (нет `agent_runs`-строки, нет токенов). +- **+** Полная обратимость одним флагом; артефакт/гейт/ребро/схема БД неизменны → переключение + туда-сюда не оставляет несовместимого состояния. +- **+** Двухуровневый исход (D5) убирает класс ORCH-110 (инфра ≠ код-фейл) с staging-ребра. +- **−** Новый leaf + врезка в `launch_job` + defer-механика — рост поверхности кода. + Митигейшн: leaf never-raise + kill-switch (fail-safe к LLM), тонкая врезка-зеркало D1/D2, + defer-счётчик без схемы БД (маркер в `task_content`), покрытие `tests/test_orch115_*`. +- **−** Раннер программно зависит от доступности `docker exec` в `orchestrator-staging` и от + поднятого staging-контейнера (раньше это делал LLM). Митигейшн: D5 (defer + fail-closed), + предусловие фиксировано в `07-infra-requirements.md`. +- **Откат:** `ORCH_STAGING_RUNNER_ENABLED=false` → `applies()` → `False` → `should_intercept` + → `False` → штатный `_spawn` LLM-deployer'а на `deploy-staging` **байт-в-байт** до ORCH-115. + +## Ссылки +- BRD: `docs/work-items/ORCH-115/01-brd.md` +- TRZ: `docs/work-items/ORCH-115/02-trz.md` +- Acceptance: `docs/work-items/ORCH-115/03-acceptance-criteria.md` +- Инфра: `docs/work-items/ORCH-115/07-infra-requirements.md`; + Данные: `08-data-requirements.md`; Риски: `10-tech-risks.md` +- Сквозной ADR: `docs/architecture/adr/adr-0048-deterministic-staging-runner.md` +- Сверено по коду: `src/agents/launcher.py:389/404/1189`, `src/stage_engine.py:191/932/2010`, + `src/self_deploy.py:81/317`, `src/qg/checks.py:525/538/599`, `src/proc_group.py`, + `src/staging_verdict.py`, `src/merge_gate.py:678`, `src/config.py` (`coverage_gate_*`/ + `reaper_max_running_s`) +- Политика/карта/roadmap: `docs/architecture/llm-usage-policy.md`, + `docs/architecture/llm-call-sites.md` (A6), `docs/architecture/llm-determinization-roadmap.md` diff --git a/docs/work-items/ORCH-115/07-infra-requirements.md b/docs/work-items/ORCH-115/07-infra-requirements.md new file mode 100644 index 0000000..8b5bcaf --- /dev/null +++ b/docs/work-items/ORCH-115/07-infra-requirements.md @@ -0,0 +1,61 @@ +--- +work_item: ORCH-115 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# 07 — Инфра-требования: ORCH-115 — детерминированный staging-раннер + +Work Item: **ORCH-115** · Repo: **orchestrator** · Стадия: architecture + +> When-applicable. Топология **не меняется** (новых контейнеров/портов/томов/compose-правок +> нет). Файл фиксирует **предусловия**, на которые раннер теперь опирается **программно** +> (раньше эти же шаги исполнял LLM-deployer), чтобы предусловие было аудитопригодно (BR-7/ +> AC-8/AC-9). + +## I-1. Топология / окружения +**Без изменений топологии.** Раннер исполняется в прод-контейнере `orchestrator` (8500), в +worker-треде, как `_run_deploy_finalizer_job`. Предусловия (существующие, не вводятся +ORCH-115): +- staging-контейнер `orchestrator-staging` (8501) поднят и доступен на хосте (Допущение А1); +- прод-контейнер имеет возможность `docker exec` в `orchestrator-staging` (та же возможность + использовал LLM-deployer — `.openclaw/agents/deployer.md` шаг 1; уже в проде); +- `scripts/staging_check.py` доступен внутри `orchestrator-staging` по bind-mount + (`/repos/orchestrator/scripts/…`, паттерн B6/ORCH-048) — источник истины набора проверок и + exit-кода (Допущение А2), ORCH-115 его не меняет. + +Недоступность любого из предусловий обрабатывается **детерминированно** (раннер D5: bounded +defer → fail-closed `FAILED` + alert на исчерпании) — никогда тихий advance / ложный green. + +## I-2. Переменные окружения / секреты +**Новые env-ключи (config, дефолты = боевое; добавить в `.env.example`):** +- `ORCH_STAGING_RUNNER_ENABLED` (`staging_runner_enabled`, дефолт `True`) — kill-switch; + `false` → прежний LLM-deployer-путь байт-в-байт. +- `ORCH_STAGING_RUNNER_REPOS` (`staging_runner_repos`, дефолт `""`) — CSV скоупа; пусто → + self-hosting only (`orchestrator`). +- `ORCH_STAGING_RUNNER_TIMEOUT_S` (`staging_runner_timeout_s`, дефолт `600`) — таймаут + subprocess'а; малформ/непозитив → дефолт + WARNING. +- `ORCH_STAGING_RUNNER_INFRA_MAX_RETRIES` (`staging_runner_infra_max_retries`, дефолт `2`) и + `ORCH_STAGING_RUNNER_INFRA_RETRY_DELAY_S` (`staging_runner_infra_retry_delay_s`, дефолт `30`) + — бюджет defer на tool-error (D5). + +**Секретов не вводит.** Команда строится из существующих host-параметров (`repos_dir`/ +`staging_port`/`SELF_HOSTING_REPO`/сервис-литерал `orchestrator-staging`) — без новых +host-хардкодов (анти-дрейф `tests/test_no_host_hardcodes.py`). + +## I-3. Деплой / рестарт +**Self-hosting инвариант соблюдён.** Раннер на `deploy-staging` **никогда** не рестартит +прод-контейнер 8500, не выполняет `docker compose up -d orchestrator`/`--build`, не пушит +force в `main`, не правит `.env`/`.env.staging`/`docker-compose.yml` (BR-7/AC-8; TC-12 — +запрет литералов в argv). Прод-выкат самого ORCH-115 идёт штатно через staging-гейт (8501) +→ `Confirm Deploy` (ORCH-059). Изменение **docs/prompts/код+config**, активируется на +следующем worktree от `main`; включение в проде — флагом (по умолчанию `True`, обратимо). + +## I-4. CI/CD +**Без изменений `.gitea/workflows/`.** Новый `tests/test_orch115_staging_runner.py` исполняется +существующим `pytest tests/ -q` (мокирует subprocess/docker-exec и `advance_stage`; живой +Claude CLI / docker / сеть не требуются). Staging-smoke (`scripts/staging_check.py` на 8501) +— штатный гейт, не меняется. diff --git a/docs/work-items/ORCH-115/08-data-requirements.md b/docs/work-items/ORCH-115/08-data-requirements.md new file mode 100644 index 0000000..cf0f92e --- /dev/null +++ b/docs/work-items/ORCH-115/08-data-requirements.md @@ -0,0 +1,43 @@ +--- +work_item: ORCH-115 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# 08 — Требования к данным: ORCH-115 — детерминированный staging-раннер + +Work Item: **ORCH-115** · Repo: **orchestrator** · Стадия: architecture + +> When-applicable. Создан **намеренно** при `N/A`-результате: «нет изменений схемы БД» — это +> критический инвариант NFR-1/AC-5, поэтому решение фиксируется явно и аудитопригодно. + +## D-1. Схема БД +**Изменений нет.** Ни новых таблиц, ни колонок, ни миграций. Раннер использует существующие +таблицы read/write через существующие хелперы: +- `tasks` — чтение `stage`/`work_item_id`/`branch` по `task_id` (дискриминатор стадии D1, + поля артефакта/гейта); запись стадии — **только внутри `advance_stage`** (его существующий + CAS/lease-контракт ORCH-114, раннер схему не трогает). +- `jobs` — статус джоба ведётся `mark_job(done|failed)` самим раннером (зеркало + `_run_deploy_finalizer_job`); requeue defer — `enqueue_job` свежего `deployer`-джоба + (существующий механизм). + +## D-2. Restart-safe состояние без схемы (defer-счётчик D5) +Счётчик infra-defer (ограничение петли tool-error, D5) — **без колонки БД**: подсчёт +маркера-подстроки в `task_content` нового `deployer`-джоба (зеркало +`merge_gate._merge_infra_retry_count` ORCH-110 и `_deploy_finalize_defer_count` ORCH-036). +Сохраняет restart-safe семантику без миграции (NFR-1). + +## D-3. Артефакт `15-staging-log.md` (контракт неизменен) +Формат/расположение/machine-key прежние: `docs/work-items//15-staging-log.md`, +frontmatter `staging_status: SUCCESS|FAILED` (UPPERCASE) + обязательная 52c-схема. Меняется +лишь *продюсер* (детерминированный код вместо LLM): `author_agent: staging-runner`, +`model_used: n/a` — **имя и регистр ключа `staging_status:` не меняются**; читается +неизменённым `_parse_staging_status` (AC-2/AC-5; TC-04). + +## D-4. Наблюдаемость — in-process, не БД +Счётчики `staging_runner` (`runs`/`success`/`failed`/`tool_error`/`deferred`) — in-process +(`_STAGING_RUNNER_COUNTERS`, паттерн `_MERGE_GATE_COUNTERS` ORCH-110), отдаются read-only в +`GET /queue`. В БД не персистятся. diff --git a/docs/work-items/ORCH-115/10-tech-risks.md b/docs/work-items/ORCH-115/10-tech-risks.md new file mode 100644 index 0000000..be6a75e --- /dev/null +++ b/docs/work-items/ORCH-115/10-tech-risks.md @@ -0,0 +1,44 @@ +--- +work_item: ORCH-115 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-115 — детерминированный staging-раннер + +Work Item: **ORCH-115** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Риски реализации + их митигейшн; нумерация +> наследует R-1…R-5 из BRD §8 и добавляет производные. + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 (R-1) | Перехват «до `_spawn`» перехватит **не тот** джоб (прод-deployer вместо staging) | Низ. | Выс. | Дискриминатор = **стадия задачи** (`tasks.stage=="deploy-staging"`) **И** `applies(repo)`, не только имя роли (ADR D1). Для self-hosting прод-ребро `deployer` не спавнит; для не-self `applies==False`. Покрытие TC-05/TC-06. `should_intercept` never-raise → `False` → штатный `_spawn`. | +| TR-2 (R-2) | После вердикта не инициирован `advance_stage` → задача зависает на `deploy-staging` (нет «финиша агента») | Низ. | Выс. | Раннер сам вызывает `advance_stage(current_stage="deploy-staging", finished_agent="deployer")` (зеркало `run_deploy_finalizer`, ADR D7). На исключении джоб → `mark_job(failed)` → reaper/worker по существующим контрактам; никогда тихий advance. Покрытие TC-07. | +| TR-3 (R-3) | Таймаут/изоляция docker-subprocess; утечка процессов (инцидент ORCH-110) | Сред. | Сред. | `proc_group.run_in_process_group` (tree-kill SIGTERM→grace→SIGKILL всего дерева), `staging_runner_timeout_s`; малформ/непозитив → дефолт + WARNING. Покрытие TC-11; запрет сирот согласован с ORCH-110. | +| TR-4 (R-4) | Конфликт с transition-lease (ORCH-114) / serial-gate (ORCH-088) на side-effectful ребре | Низ. | Выс. | Граница O1: lease берётся **внутри** `advance_stage` — раннер его не трогает (ADR D7). serial-gate гейтит analyst-job claim, не deployer-job. Код ORCH-112/114 не модифицируется. | +| TR-5 (R-5) | Откат FAILED (developer-retry cap) расходится с LLM-путём | Низ. | Сред. | Реальный `≠0` exit → тот же `advance_stage`-откат (`stage_engine.py:932`, тот же cap `MAX_DEVELOPER_RETRIES`), что у FAILED-вердикта LLM. Покрытие TC-07. | +| TR-6 | **Инфра-сбой как код-фейл** (docker down / staging недоступен / таймаут → откат + расход developer-retry → петля) — анти-паттерн ORCH-110 | Сред. | Выс. | **Двухуровневый исход D5:** сюита исполнилась → verdict; tool-error/таймаут → bounded defer (`staging_runner_infra_max_retries`) → fail-closed `FAILED` + alert на исчерпании. Не жжёт developer-retry на инфре. Покрытие TC-10. | +| TR-7 | Скоуп-дрейф: случайная правка `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-key/схемы БД | Низ. | Выс. | NFR-1 — замена только *продюсера*. Анти-дрейф структурный тест TC-09; reviewer ловит ≥P1. Раннер пишет тот же `staging_status:` key, читается неизменённым `_parse_staging_status`. | +| TR-8 | Сквозной бюджет времени (`reaper_max_running_s`) превышен суммой работ на ребре | Низ. | Сред. | Таймаут 600s ≤ прежнего LLM-окна (3–15 мин) → Σ(работ на ребре) не растёт → инвариант ORCH-065/109/110 сохранён **без** правки `reaper_max_running_s` (ADR D9). | +| TR-9 | Рассинхрон карты LLM (`llm-call-sites.md`/roadmap/policy) с реализацией → красные анти-дрейф-тесты | Сред. | Сред. | Норматив сопровождения NFR-6 (ADR D11): точная спека правок + `test_llm_call_site_inventory.py`/`test_llm_determinization_docs.py` обновляются **атомарно с кодом** в development. Инвариант «ровно один `first_slice`» держать корректным. Покрытие TC-14. | +| TR-10 | Self-hosting safety: раннер случайно рестартит 8500 / force-push в `main` / правит инфру | Низ. | Выс. | BR-7/AC-8: argv не содержит запрещённых литералов (TC-12); лог пишется в worktree + push в **фичеветку** (не main PR-merge, ADR D6); только чтение + staging-сюита (8501). | + +## Сводный вывод + +Доминирующий класс — **корректность диспетчеризации и обработки инфра-сбоев** (TR-1/TR-2/TR-6) +на side-effectful ребре общего прод-инстанса (self-hosting). Все сняты опорой на **доказанные +прецеденты** (D1/D2 перехват, `run_deploy_finalizer`, `proc_group`, transition-lease внутри +`advance_stage`) и **двухуровневым исходом D5**, явно адресующим RCA-класс ORCH-110. +Изменение **аддитивное, never-raise, под kill-switch с байт-в-байт откатом**; гейт/ребро/ +схема БД неизменны. Остаточный риск для прод-конвейера — **низкий**. + +Эскалация **не требуется**: это не новая стадия/QG/смена БД (лейбл `arch:major-change` не +ставится), ТЗ удовлетворяется без нарушения принципов (возврат в анализ не нужен). Единственное +**инфра-предусловие** для включения в проде — доступность `docker exec` в `orchestrator-staging` +(уже выполнено LLM-путём); до включения флага поведение байт-в-байт прежнее.