architect(ET): auto-commit from architect run_id=733

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 <STAGING_SERVICE> python3 <repos_dir>/<SELF_HOSTING_REPO>/scripts/staging_check.py \
+    --base-url http://localhost:<staging_port> --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=<staging_runner_timeout_s>,
+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/<work_item_id>/15-staging-log.md` в worktree фичеветки
+(`git_worktree.get_worktree_path`) с frontmatter:
+
+```markdown
+---
+staging_status: SUCCESS        # или FAILED — UPPERCASE, имя/регистр ключа не меняются
+work_item: <work_item_id>
+stage: deploy-staging
+author_agent: staging-runner
+status: success                # или failed — выровнен по staging_status
+created_at: <YYYY-MM-DD>
+model_used: n/a
+timestamp: <ISO>
+base_url: http://localhost:<staging_port>
+exit_code: <returncode>
+---
+
+# Staging Gate Log (deterministic runner, ORCH-115)
+<exit-код, краткий хвост stdout; строку `INFRA-WAIVED:` из stdout скопировать в тело для observability>
+```
+
+- `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`

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)
+— штатный гейт, не меняется.

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/<work_item_id>/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`. В БД не персистятся.

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-путём); до включения флага поведение байт-в-байт прежнее.