From 3865b14a1c91baf54166f9fd0b364c45a593fd1b Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 07:55:43 +0300 Subject: [PATCH 1/8] analyst(ET): auto-commit from analyst run_id=747 --- docs/work-items/ORCH-123/01-brd.md | 201 ++++++++++++++++++ docs/work-items/ORCH-123/02-trz.md | 136 ++++++++++++ .../ORCH-123/03-acceptance-criteria.md | 169 +++++++++++++++ docs/work-items/ORCH-123/04-test-plan.yaml | 108 ++++++++++ 4 files changed, 614 insertions(+) create mode 100644 docs/work-items/ORCH-123/01-brd.md create mode 100644 docs/work-items/ORCH-123/02-trz.md create mode 100644 docs/work-items/ORCH-123/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-123/04-test-plan.yaml diff --git a/docs/work-items/ORCH-123/01-brd.md b/docs/work-items/ORCH-123/01-brd.md new file mode 100644 index 0000000..739c767 --- /dev/null +++ b/docs/work-items/ORCH-123/01-brd.md @@ -0,0 +1,201 @@ +--- +work_item: ORCH-123 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-16 +model_used: claude-opus-4-8 +escalate: full-cycle +--- + +# 01 — BRD / Bug-report: ORCH-123 — staging-runner assumes Docker CLI inside the orchestrator container and false-fails deploy-staging + +Work Item: **ORCH-123** · Repo: **orchestrator** · Стадия: analysis · Трек: **Bug → эскалация в full-cycle** + +> ⚠️ **`escalate: full-cycle` (ADR-001 D5 ORCH-019).** Метка задачи — `Bug`, но по сути это +> **архитектурный + safety-critical (self-hosting)** дефект: требуется **решение о стратегии +> исполнения** staging-сюиты из прод-окружения (host-side ssh / Docker SDK поверх смонтированного +> сокета / docker CLI в образе / выделенный hook-режим), и любой вариант с доступом к +> `docker.sock`/CLI из контейнера требует **явного security-review** (доступ к сокету = root-эквивалент +> на хосте). Это не «однострочная» правка кода — нужен ADR. Поэтому выпускается **полный** +> analysis-пакет (а не облегчённый bug-пакет). Оператор снимает багфикс-трек: +> `POST /bug-fast-track/escalate?work_item=ORCH-123` → задача пойдёт через стадию `architecture` +> (architect выпустит ADR для стратегии исполнения staging-runner). + +--- + +## 1. Бизнес-контекст и проблема + +### Симптом (наблюдаемое — установленный факт из прод-логов) +Задача **ORCH-116** (поверх раската ORCH-115) дошла до стадии `deploy-staging` с **зелёными +reviewer и tester**, но **детерминированный staging-runner упал ещё до запуска staging-сюиты**. +Запись из прод-логов: +``` +proc_group: spawn error for [docker, exec, orchestrator-staging, python3, +/repos/orchestrator/scripts/staging_check.py, ...]: [Errno 2] No such file or directory: docker +``` +Далее runner отработал свой инфра-DEFER **дважды**, исчерпал `staging_runner_infra_max_retries=2`, +записал `15-staging-log.md` с `staging_status: FAILED` и `stage_engine` **откатил ORCH-116 на +`development`** — как будто это дефект кода/тестов задачи, чем оно не является. + +### Причина симптома (установленный факт — верифицировано по коду и инфраструктуре) +ORCH-115 (`src/staging_runner.py`) исполняет staging-сюиту командой +`docker exec orchestrator-staging python3 .../staging_check.py …` **изнутри прод-контейнера +`orchestrator`** через `proc_group.run_in_process_group`. Прод-контейнер **не содержит docker CLI**: +- **`Dockerfile:11`** ставит `openssh-client git curl ca-certificates` — **бинаря `docker` нет**; + `python:3.12-slim` его тоже не содержит. Поэтому `subprocess.Popen(["docker", …])` падает + `FileNotFoundError: [Errno 2] No such file or directory: docker`. +- **`docker-compose.yml:40`** монтирует `/var/run/docker.sock` (rw) в сервис `orchestrator` и + добавляет `group_add: ${ORCH_DOCKER_GID}`. То есть **сокет в контейнере есть, а CLI-бинаря, который + бы им воспользовался, — нет**. (Это важное уточнение корня: проблема не в доступе к Docker, а в + **отсутствии исполняемого клиента** в образе.) + +Цепочка отказа в коде: +`build_staging_command()` (`staging_runner.py:154`) → `["docker","exec",…]` → `run_staging_suite()` → +`proc_group.run_in_process_group` → `Popen` ⇒ `OSError` ⇒ `ProcResult(returncode=None, timed_out=False)` +⇒ в `run_staging_gate` (`staging_runner.py:528`) `suite_ran = (returncode is not None) and (not +timed_out)` = **False** ⇒ ветка **tool-error** ⇒ `_handle_tool_error` (`staging_runner.py:415`): +инфра-DEFER ×2 → бюджет исчерпан → `write_staging_log(..., "FAILED", tool_error=True)` + +`_advance(...)` ⇒ существующий откат `deploy-staging → development`. + +### Корневая классификационная ошибка +Двухуровневый исход ORCH-115 (D5) различает только **«сюита исполнилась» vs «сюита не исполнилась +(транзиентная инфра)»**. Отсутствие docker CLI — это **детерминированный, постоянный дефект +окружения**, а не транзиентная икота: ретраи бессмысленны (каждая попытка падает идентично), а +**терминальный исход — откат на `development` с расходом developer-retry** — вводит в заблуждение +(винит код/разработчика задачи за environment-проблему раннера). Так до фикса **любая** self-hosting +задача, доходящая до `deploy-staging`, обречена на ложный откат. + +### Локализация (анализ — куда смотреть архитектору/разработчику) + +**Установленный факт о топологии исполнения (CLAUDE.md / `docs/operations/INFRA.md` / код):** +прод-деплой (ORCH-036, `src/self_deploy.py`) **уже решил ровно эту проблему** и НЕ запускает docker +изнутри контейнера. Он исполняет хост-хук **на хосте** через `ssh + setsid` (detached): +`build_deploy_command` (`self_deploy.py:220`) формирует `ssh @ 'setsid bash -c "… bash + --deploy …"'`, где `deploy_ssh_host=127.0.0.1`, ssh-ключ смонтирован, `openssh-client` стоит в +образе (`Dockerfile:11`). Хост-хук `scripts/orchestrator-deploy-hook.sh` уже выполняет `docker +compose …` / `docker tag` / **`docker exec "$STAGING_CONTAINER" python3 staging_check.py`** +(`--build-staging`, строки 197/261) — **на хосте**, где docker CLI есть. + +**Вывод:** ORCH-115 при замене LLM-деплойера детерминированным раннером **отклонился** от уже +установленного паттерна «docker-операции исполняются host-side, не внутри app-контейнера». Дефект — +в **стратегии исполнения** `staging_runner` (где/как запускается staging-сюита), а не в гейте +`check_staging_status` и не в контракте `15-staging-log.md`. Поэтому фикс должен **восстановить +работоспособную стратегию исполнения** staging-сюиты в проде, не завися от недоступного внутри +контейнера docker CLI, и **перестать классифицировать постоянный environment-дефект как код-фейл**. + +> 🔎 **Точка для проверки на стадии architecture (не факт, требует верификации):** как +> staging-сюита исполнялась **до** ORCH-115 LLM-деплойером — действительно через `docker exec` из +> контейнера (тогда путь всегда был сломан и LLM-гейт был «бумажным»), или иным механизмом. Это +> определяет, «сломал ли ORCH-115 рабочий путь» или «сделал давний дефект детерминированным и +> видимым». На фикс выбор стратегии это не меняет, но влияет на формулировку регресса. + +## 2. Объём (scope) + +### В объёме +- Исправить **стратегию исполнения staging-runner** так, чтобы `deploy-staging` для self-hosting + `orchestrator` **проходил в проде**, не завися от недоступного внутри прод-контейнера docker CLI. +- Гарантировать, что **tool-error / environment-дефект** (в частности отсутствие исполняемого + `docker`/невозможность запустить сюиту по причине окружения) **НЕ приводит к вводящему в + заблуждение откату `deploy-staging → development`** как код-фейлу и **не жжёт** developer-retry; + постоянный environment-дефект должен быть отличим от транзиентной инфры и от настоящего код-фейла. +- Добавить **prod-like регресс/preflight**, который ловит «нет исполняемого/стратегия неработоспособна» + **до раската** (а не постфактум, ложным откатом реальной задачи). +- Задокументировать **границу исполнения** (`docs/operations/INFRA.md` + `docs/architecture/README.md`): + где и как staging-сюита исполняется относительно прод-контейнера, какие исполняемые/сокеты доступны. + +### Вне объёма +- ❌ Изменение гейта `check_staging_status` / `_parse_staging_status`, контракта `15-staging-log.md` + (`staging_status:`), `STAGE_TRANSITIONS`, machine-verdict ключей, схемы БД — **байт-в-байт прежние** + (ORCH-115 NFR-1: меняется **продюсер/стратегия исполнения** артефакта, не гейт). +- ❌ Изменение содержимого/логики самой `scripts/staging_check.py` (тулинг сюиты корректен; меняется + лишь **как/откуда** её запускают). +- ❌ Откат ORCH-115 (детерминизация staging корректна по замыслу; чиним способ исполнения). +- ❌ Выбор конкретного механизма (ssh host-side / Docker SDK поверх сокета / docker CLI в образе / + выделенный hook-режим) — это **зона архитектора** (`06-adr/`), здесь — только требования и ограничения. +- ❌ Изменение прод-деплой-пути (ORCH-036 self_deploy) сверх возможного переиспользования его + ssh-механизма; happy-path прод-деплоя не трогается. + +## 3. Заинтересованные стороны +- **Заказчик/оператор (Слава)** — страдает от ложных откатов и ручного разруливания залипших задач; + принимает результат. +- **Self-hosting конвейер `orchestrator`** — прямой потребитель: без фикса **ни одна** self-hosting + задача не проходит `deploy-staging`. +- **Все проекты на общем инстансе (enduro-trails)** — косвенно: застрявшие/откатываемые self-hosting + задачи занимают слоты и внимание оператора на общей очереди. + +## 4. Бизнес-требования (BR) +- **BR-1** — Для self-hosting `orchestrator` стадия `deploy-staging` (детерминированный staging-runner) + **исполняет staging-сюиту и проходит в проде** без зависимости от docker CLI, отсутствующего внутри + прод-контейнера. Задача уровня ORCH-116 (reviewer/tester зелёные, код корректен) **доходит до + `deploy`**, а не откатывается. +- **BR-2** — **Tool-error / environment-дефект ≠ код-фейл.** Невозможность исполнить сюиту по причине + окружения (нет исполняемого, недоступна стратегия) **не должна** завершаться откатом + `deploy-staging → development` как кодовой ошибкой и **не должна** инкрементировать developer-retry; + такой исход должен быть **отдельным, отличимым** (хольд/алерт оператору об инфра/environment-сбое). +- **BR-3** — **Настоящий код-фейл сохраняется (анти-over-tolerance).** Если сюита **реально + исполнилась** и упала (exit≠0), поведение — **прежний** откат `deploy-staging → development` + + developer-retry (BR-2 не должно маскировать настоящие провалы; ср. ORCH-110 BR-6). +- **BR-4** — **Prod-like preflight/регресс.** Должен существовать механизм, ловящий «исполняемое + отсутствует / стратегия неработоспособна» **до раската** (preflight на старте/в smoke-проверке) и + **тест**, воспроизводящий «docker CLI отсутствует в контейнере» (красный до фикса, зелёный после). +- **BR-5** — **Граница исполнения задокументирована.** `docs/operations/INFRA.md` (и + `docs/architecture/README.md`) явно описывают, где/как исполняется staging-сюита относительно + прод-контейнера, какие исполняемые/сокеты доступны, и почему docker-операции идут так, а не «изнутри + app-контейнера». +- **BR-6** — **Наблюдаемость.** Различие «environment/tool-error» vs «код-фейл» видно в логе + (структурная запись), Telegram-алерте (кликабельный номер) и read-only блоке `staging_runner` в + `GET /queue`. + +## 5. Нефункциональные требования (NFR) +- **NFR-1 (нулевая регрессия конвейера)** — `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / имена и + семантика `check_*` (в т.ч. `check_staging_status`/`_parse_staging_status`) / machine-verdict ключи + (`staging_status:`/`deploy_status:`/…) / схема БД — **байт-в-байт не тронуты** (фикс — стратегия + исполнения продюсера, не гейт и не стадия). +- **NFR-2 (self-hosting safety)** — путь исполнения staging-runner **никогда**: не рестартит прод + `orchestrator` (8500), не делает `docker compose up orchestrator`/`--build` прода, не force-push, не + пишет в `main`, не редактирует `.env`. Только запускает staging-сюиту (8501) и пишет лог + (инвариант ORCH-115 BR-7/AC-8 сохраняется). +- **NFR-3 (security — если выбран socket/CLI-в-контейнере)** — любой вариант с прямым использованием + `docker.sock`/CLI из контейнера = root-эквивалент на хосте → **обязателен явный security-review** в + ADR (поверхность атаки, ограничение прав, :ro где возможно). Вариант host-side ssh должен + переиспользовать уже существующий доверенный механизм (ORCH-036) без расширения привилегий. +- **NFR-4 (обратимость / kill-switch)** — поведение под существующим `staging_runner_enabled` + (+ при необходимости — новым флагом выбора стратегии); выключенный kill-switch → прежний LLM-деплойер + через `_spawn` **байт-в-байт** (ORCH-115 fail-safe сохраняется). +- **NFR-5 (надёжность)** — never-raise / fail-safe / restart-safe (по образцу leaf'ов + `staging_runner`/`self_deploy`/`proc_group`); очередь репо **никогда не клинится**; тайм-аут сюиты не + растёт сверх бюджета, держащего сквозной инвариант reaper (ORCH-065/109/110). +- **NFR-6 (область)** — изменение скоупится на self-hosting (`orchestrator`, единственный с staging + 8501); поведение для прочих репо/синхронного LLM-деплоя — не ухудшается (`applies(repo)` первым). + +## 6. Допущения и ограничения +- Прод и staging контейнеры запущены на **одном хосте**; `/var/run/docker.sock` доступен на хосте, + где docker CLI установлен; ssh на `127.0.0.1` под смонтированным ключом — рабочий канал (его уже + использует ORCH-036 self-deploy). +- `staging_check.py` исполняется **внутри контейнера `orchestrator-staging`** (там есть python3 и + приложение 8501) — это контракт сюиты; меняется только то, **кто инициирует** `docker exec` (хост + vs прод-контейнер) или **как** (CLI vs SDK поверх сокета). +- Источник истины «применять ли детерминированный runner» — `staging_runner.applies(repo)` (ORCH-115); + фикс не меняет его семантику. +- Конкретный механизм исполнения (host-side ssh / Docker SDK поверх сокета / docker CLI в образе / + выделенный режим хука) — **открытый вопрос для архитектуры**, решается в `06-adr/` с security-review. + +## 7. Критерии успеха +Self-hosting задача уровня ORCH-116 проходит `deploy-staging` в проде (staging-сюита реально +исполняется, вердикт маппится из exit-кода); environment/tool-error **не** даёт ложного код-фейл-отката +и не жжёт developer-retry; настоящий код-фейл по-прежнему откатывает на `development`; существует +prod-like preflight + обязательный регресс-тест «нет docker CLI в контейнере» (**красный до фикса, +зелёный после**); граница исполнения задокументирована; гейт/контракт/`STAGE_TRANSITIONS`/схема БД — без +регресса; полный `pytest tests/ -q` зелёный. Детальные PASS/FAIL — `03-acceptance-criteria.md`. + +## 8. Риски +- **Security (socket/CLI в контейнере):** прямой доступ к `docker.sock` из app-контейнера = эскалация + до root на хосте → ADR обязан взвесить поверхность атаки против host-side ssh-варианта. +- **Over-tolerance:** слишком широкая трактовка «environment-дефекта» может замаскировать настоящие + код-фейлы/реальные сбои staging-стенда (митигация — BR-3; ср. инцидент ORCH-110). +- **Кросс-каттинг:** ORCH-115 (staging-runner, прямой объект), ORCH-036 (self_deploy ssh-механизм — + потенциально переиспользуемый), ORCH-110 (proc_group tree-kill + infra-tolerance паттерн), ORCH-058 + (`--build-staging` host-side docker exec — прецедент), ORCH-101 (host-параметризация). Правки + маркированных блоков сверять с их `06-adr/` (CLAUDE.md §9). Детали/митигации — `10-tech-risks.md` + (заполняет архитектор). diff --git a/docs/work-items/ORCH-123/02-trz.md b/docs/work-items/ORCH-123/02-trz.md new file mode 100644 index 0000000..a78a7c8 --- /dev/null +++ b/docs/work-items/ORCH-123/02-trz.md @@ -0,0 +1,136 @@ +--- +work_item: ORCH-123 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# 02 — ТЗ (TRZ): ORCH-123 — staging-runner execution strategy must not depend on Docker CLI inside the app container + +Work Item: **ORCH-123** · Repo: **orchestrator** · Стадия: analysis + +> ТЗ описывает **требования и ограничения к реализации**, выведенные из BRD и фактического кода. +> Архитектурное **решение** (какую стратегию исполнения выбрать: host-side ssh / Docker SDK поверх +> сокета / docker CLI в образе / выделенный hook-режим, + security-review) — задача архитектора +> (`06-adr/`), т.к. задача эскалирована в full-cycle (`01-brd.md` → `escalate: full-cycle`). + +## 1. Сводка изменения +Восстановить работоспособную стратегию исполнения staging-сюиты для self-hosting `orchestrator` на +стадии `deploy-staging`, не завися от docker CLI, **отсутствующего внутри прод-контейнера** +(`Dockerfile:11` ставит `openssh-client git curl ca-certificates`, не docker; `docker.sock` +смонтирован — `docker-compose.yml:40` — но клиента нет). Сегодня `staging_runner.build_staging_command` +(`src/staging_runner.py:154`) формирует `["docker","exec","orchestrator-staging",…]` и запускает её +**изнутри** прод-контейнера через `proc_group` → `Popen` падает `FileNotFoundError` → ветка tool-error +→ инфра-DEFER×2 → fail-closed `FAILED` → откат `deploy-staging → development`. Требуется: (а) исполнять +сюиту так, чтобы она реально запускалась в проде (паттерн host-side, уже применённый прод-деплоем +ORCH-036 / `--build-staging`); (б) **различать** постоянный environment/tool-error от настоящего +код-фейла и не делать вводящего в заблуждение код-фейл-отката; (в) prod-like preflight + регресс; +(г) документировать границу исполнения. + +## 2. Задействованные модули / пути +| Путь | Действие | Примечание | +|------|----------|-----------| +| `src/staging_runner.py` | **изменить** | `build_staging_command`/`run_staging_suite` — точка, где сюита запускается «изнутри контейнера» (корень дефекта, FR-1); классификация tool-error vs environment-дефект в `run_staging_gate`/`_handle_tool_error` (FR-2) | +| `src/self_deploy.py` | возможно переиспользовать | `build_deploy_command`/`initiate_deploy` — рабочий host-side ssh+setsid механизм (ORCH-036); кандидат на общий ssh-хелпер исполнения host-side команды (решает архитектор) | +| `scripts/orchestrator-deploy-hook.sh` | возможно изменить | `--build-staging` уже делает host-side `docker exec "$STAGING_CONTAINER" python3 staging_check.py` (строки 197/261) — прецедент/возможная точка выделенного staging-режима | +| `Dockerfile` | возможно изменить | строка 11 — если выбран вариант «docker CLI в образе» (тогда + security-обоснование) | +| `docker-compose.yml` | возможно изменить | строка 40 — `docker.sock` уже смонтирован; если выбран socket/SDK-вариант, зафиксировать права (`:ro` где возможно) | +| `src/proc_group.py` | возможно изменить | `run_in_process_group` уже корректно деградирует spawn-error в `ProcResult(returncode=None)` — кандидат на preflight «исполняемое существует» (FR-4) | +| `src/config.py` | возможно изменить | существующие `staging_runner_*`; при необходимости — флаг выбора/режима стратегии (FR-5), дефолт = боевое | +| `docs/operations/INFRA.md` | **изменить** | граница исполнения staging-сюиты относительно прод-контейнера (FR-6 / BR-5) | +| `docs/architecture/README.md` | **изменить** | описать стратегию исполнения staging-runner (FR-6 / BR-5) | +| `CHANGELOG.md`, `CLAUDE.md` | изменить | docs = golden source (CLAUDE.md §2); раздел ORCH-115 дополнить фиксом исполнения | +| `tests/test_orch115_staging_runner.py` / `tests/test_orch123_staging_runner_exec.py` | **создать/расширить** | регресс «docker CLI отсутствует» + классификация + preflight (`04-test-plan.yaml`) | + +## 3. Функциональные требования + +### FR-1 — Работоспособная стратегия исполнения staging-сюиты в проде (BR-1) +- На стадии `deploy-staging` для self-hosting `orchestrator` staging-сюита (`staging_check.py` внутри + `orchestrator-staging`) **должна реально исполняться** в боевом окружении, **не завися** от наличия + бинаря `docker` внутри прод-контейнера `orchestrator`. +- Стратегия исполнения — **выбор архитектора** (ADR), из перечня BRD §2: host-side через + существующий ssh+setsid механизм (ORCH-036, `deploy_ssh_host=127.0.0.1`, ssh-ключ смонтирован, + `openssh-client` в образе) **либо** Docker SDK/`docker.sock` (уже смонтирован, + security-review) + **либо** docker CLI в образе **либо** выделенный режим хука. ТЗ **не** прескриптивно — фиксирует + лишь требуемый инвариант «сюита исполняется». +- Команда/контракт сюиты (`python3 staging_check.py --base-url http://localhost: + --mode stub`, host-specifics из config — ORCH-101) сохраняются; меняется **инициатор/канал** + запуска, не сама сюита. + +### FR-2 — Environment/tool-error ≠ код-фейл (BR-2, BR-3) +- Невозможность исполнить сюиту по причине **окружения** (нет исполняемого `docker`/SDK недоступен/ + стратегия неработоспособна) **не должна** завершаться откатом `deploy-staging → development` как + кодовой ошибкой и **не должна** инкрементировать developer-retry. Текущий терминальный путь + `_handle_tool_error` → `write_staging_log("FAILED") + _advance` (= откат) для **постоянного** + environment-дефекта вводит в заблуждение (см. BRD §1) и должен быть заменён на **отличимый + инфра/environment-исход** (хольд на `deploy-staging` + алерт оператору, по образцу + `merge_gate` infra-tolerance ORCH-110: задача остаётся на стадии, без developer-retry). +- **Анти-over-tolerance (BR-3):** если сюита **реально исполнилась** (получен exit-код) и упала + (exit≠0), исход — **прежний** откат `deploy-staging → development` + developer-retry (контракт + `staging_runner` D5 для «сюита исполнилась» сохраняется байт-в-байт). +- Различение «сюита исполнилась / постоянный environment-дефект / транзиентная инфра» — + детерминированная классификация (по образцу `merge_gate.classify_retest_failure`, ORCH-110 D2); + никаких догадок — постоянный environment-дефект (spawn-error «исполняемое не найдено») трактуется + как НЕ-транзиентный и НЕ как код-фейл. + +### FR-3 — Анти-бессмысленный-ретрай (BR-2) +- При постоянном environment-дефекте бессмысленно крутить инфра-DEFER ×N (каждая попытка падает + идентично, жжёт время/слот) и затем ложно откатывать. Допустимо: немедленный отличимый + инфра-хольд+алерт (без отката, без developer-retry) **или** preflight, не дающий задаче войти в + ложный путь. Конкретику решает архитектор; инвариант — **не** оканчиваться код-фейл-откатом. + +### FR-4 — Prod-like preflight (BR-4) +- Должен существовать механизм, ловящий «стратегия исполнения неработоспособна (нет исполняемого/ + канал недоступен)» **до раската** — preflight на старте сервиса и/или в `scripts/staging_check.py`/ + smoke (`scripts/staging_check.py` Block …) / в `should_intercept`/`applies`. Условие, проявившееся + в инциденте (нет бинаря `docker` там, где runner его зовёт), должно детектироваться **до** того, + как реальная задача ложно откатится. +- Реализационно preflight никак не должен трогать гейты/стадии; never-raise; область — self-hosting. + +### FR-5 — Условность / kill-switch (BR-1, NFR-4, NFR-6) +- Поведение под существующим `staging_runner_enabled` (выключен → прежний LLM-деплойер через `_spawn` + байт-в-байт) + `staging_runner_repos` (область). При необходимости нового флага выбора/режима + стратегии — env `ORCH_*`, **дефолт = боевое** (паттерн ORCH-101); откат = выставить флаг(и) → + поведение до ORCH-123. `applies(repo)` (локально, без сети) проверяется первым. + +### FR-6 — Документирование границы исполнения (BR-5) +- `docs/operations/INFRA.md` + `docs/architecture/README.md`: явно зафиксировать, что docker-операции + для self-hosting исполняются **host-side** (а не из app-контейнера, где нет docker CLI), какие + исполняемые/сокеты доступны прод-контейнеру (`openssh-client`/`git`/`curl`; `docker.sock` смонтирован, + CLI — нет), и как именно staging-runner запускает сюиту после фикса. + +## 4. Изменения API +**Нет** обязательных. Существующий read-only блок `staging_runner` в `GET /queue` (ORCH-115) +**дополняется** различием environment/tool-error vs код-фейл и (опц.) статусом preflight; новых +управляющих эндпоинтов не требуется (на усмотрение архитектора — опц. read-only preflight-поле). + +## 5. Изменения схемы БД +**Нет.** Restart-safe состояние (счётчик инфра-ретраев) уже ведётся маркером в `task_content` +(`_INFRA_RETRY_MARKER`, ORCH-115) — без миграции. Новой таблицы/колонки не требуется. + +## 6. Требования к новым/изменённым QG checks +**Нет.** Это **не** Quality Gate и **не** стадия — это стратегия исполнения продюсера артефакта +`15-staging-log.md`. `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / имена и семантика `check_*` +(`check_staging_status`/`_parse_staging_status`) / machine-verdict ключи (`staging_status:`/ +`deploy_status:`/…) / схема БД — **байт-в-байт не тронуты** (NFR-1; зеркало инварианта ORCH-115 NFR-1). + +## 7. Совместимость / регресс +- **Обратная совместимость:** `staging_runner_enabled=False` → стадию `deploy-staging` снова ведёт + LLM-`deployer` через `_spawn` **байт-в-байт**; для прочих репо `applies==False` → no-op (нулевая + регрессия enduro). +- **Контракт артефакта:** `15-staging-log.md` (`staging_status:` + 52c-схема, `author_agent: + staging-runner`/`model_used: n/a`) сохраняется; вердикт по-прежнему читается ТОЛЬКО из frontmatter. +- **Self-hosting инварианты (NFR-2):** не рестартить прод 8500, не `docker compose up orchestrator`/ + `--build` прода, не force-push, не писать в `main`, не править `.env` — сохраняются (ORCH-115 BR-7). +- **Security (NFR-3):** любой socket/CLI-в-контейнере вариант проходит security-review в ADR; host-side + ssh-вариант переиспользует доверенный ORCH-036 механизм без расширения привилегий. +- **Бюджеты/инварианты:** тайм-аут сюиты не растёт сверх `staging_runner_timeout_s` (держит сквозной + reaper-инвариант ORCH-065/109/110); proc_group tree-kill (ORCH-110) сохраняется. +- **Артефакты pipeline:** обычные docs work item (`01..04` этой задачи; `06-adr/` на стадии + architecture после эскалации; `15-staging-log.md` при прогоне). Новых pipeline-артефактов задача не + вводит. +- **Трассировка (CLAUDE.md §9 / ORCH-078):** правки маркированных блоков — ORCH-115 (staging-runner, + прямой объект), ORCH-036 (self_deploy ssh), ORCH-110 (proc_group/infra-tolerance), ORCH-058 + (`--build-staging`) — сверять с их `06-adr/` перед изменением; инварианты не ломать. diff --git a/docs/work-items/ORCH-123/03-acceptance-criteria.md b/docs/work-items/ORCH-123/03-acceptance-criteria.md new file mode 100644 index 0000000..e88f649 --- /dev/null +++ b/docs/work-items/ORCH-123/03-acceptance-criteria.md @@ -0,0 +1,169 @@ +--- +work_item: ORCH-123 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-123 — staging-runner execution strategy fix + +Work Item: **ORCH-123** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что +считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам репозитория. +Критерии **механизм-агностичны** (конкретную стратегию выбирает архитектор), проверяют **требуемый +инвариант**, а не способ реализации. + +--- + +## AC-1 — staging-сюита реально исполняется в проде (без docker CLI в контейнере) + +**Условие:** Для self-hosting `orchestrator` на `deploy-staging` staging-runner запускает +`staging_check.py` так, что сюита **исполняется** в боевом окружении, не завися от бинаря `docker` +внутри прод-контейнера. +- **PASS:** Стратегия исполнения staging-сюиты не требует наличия `docker` CLI **внутри** + прод-контейнера `orchestrator` (исполняется host-side через существующий доверенный канал, либо + через смонтированный сокет/SDK с security-обоснованием, либо CLI добавлен в образ — на выбор ADR); + тест воспроизводит окружение «нет `docker` в контейнере» и подтверждает, что сюита **исполняется** + (а не падает spawn-error'ом). +- **FAIL:** staging-runner по-прежнему вызывает `docker exec` напрямую из прод-контейнера без + доступного исполняемого/канала → `proc_group` spawn-error → tool-error. + +--- + +## AC-2 — ORCH-116-подобная задача проходит `deploy-staging` + +**Условие:** Задача с зелёными reviewer/tester и корректным кодом доходит до `deploy`, а не +откатывается на `development` из-за раннера. +- **PASS:** При успешной staging-сюите (exit 0) → `staging_status: SUCCESS` → штатное продвижение по + под-гейтам ребра `deploy-staging → deploy` (контракт не тронут); ORCH-116-подобный сценарий в + тесте/симуляции достигает `deploy`. +- **FAIL:** Корректная задача откатывается на `development` по причине раннера/окружения. + +--- + +## AC-3 — environment/tool-error НЕ даёт вводящего в заблуждение код-фейл-отката + +**Условие:** Невозможность исполнить сюиту по причине окружения (нет исполняемого/канал недоступен) не +трактуется как код-фейл. +- **PASS:** environment/tool-error → **отличимый** инфра/environment-исход (задача **не** откатывается + на `development` как код-фейл; developer-retry **не** инкрементируется; оператору идёт алерт «инфра/ + окружение, НЕ дефект кода»). Подтверждено тестом: при недоступном исполняемом задача **не** уходит в + `development` и счётчик developer-retry не растёт. +- **FAIL:** environment-дефект завершается `write_staging_log("FAILED") + advance` (откат на + `development`) и/или жжёт developer-retry. + +--- + +## AC-4 — настоящий код-фейл по-прежнему откатывает (анти-over-tolerance) + +**Условие:** Если сюита **реально исполнилась** и упала (exit≠0), поведение не ослаблено. +- **PASS:** exit≠0 при исполнившейся сюите → `staging_status: FAILED` → **прежний** откат + `deploy-staging → development` + developer-retry (байт-в-байт контракт ORCH-115 для «сюита + исполнилась»). Тест подтверждает, что реальный фейл сюиты НЕ маскируется как «инфра». +- **FAIL:** Настоящий код-фейл сюиты трактуется как environment/инфра и не откатывает на `development`. + +--- + +## AC-5 — prod-like preflight ловит «исполняемое/стратегия неработоспособна» до раската + +**Условие:** Условие инцидента детектируется заранее, а не ложным откатом реальной задачи. +- **PASS:** Существует preflight (на старте сервиса и/или в smoke/`staging_check.py`/`applies`/ + `should_intercept`), который при неработоспособной стратегии исполнения сигнализирует (лог/алерт/ + отметка) **до** того, как задача дойдёт до ложного отката; есть тест, симулирующий «нет `docker` в + контейнере», и он проверяет именно это. +- **FAIL:** Нет механизма раннего детекта; «исполняемое отсутствует» обнаруживается только постфактум + откатом реальной задачи. + +--- + +## AC-6 — обязательный регресс-тест (red → green) + +**Условие:** Инцидент ORCH-116 воспроизводится тестом. +- **PASS:** Есть тест, моделирующий исполнение staging-сюиты в окружении **без `docker` CLI в + контейнере**; он **красный на коде до фикса** (воспроизводит spawn-error → tool-error → ложный + откат/false-FAILED) и **зелёный после фикса** (сюита исполняется / environment-дефект не даёт + код-фейл-отката). +- **FAIL:** Регресс-теста нет, либо он зелёный и до фикса (значит, не воспроизводит дефект). + +--- + +## AC-7 — гейт/контракт/стадии — без регресса (NFR-1) + +**Условие:** Меняется продюсер/стратегия исполнения, не гейт. +- **PASS:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, имена и семантика `check_staging_status`/ + `_parse_staging_status`, machine-verdict ключи (`staging_status:`/`deploy_status:`/…), схема БД — + **байт-в-байт прежние** (структурный анти-регресс-тест зелёный); `15-staging-log.md` сохраняет + `staging_status:`-frontmatter + 52c-схему (`author_agent: staging-runner`/`model_used: n/a`). +- **FAIL:** Любое из перечисленного изменено (имя/регистр/семантика/значение) либо введена миграция БД. + +--- + +## AC-8 — self-hosting safety (NFR-2) + +**Условие:** Путь исполнения staging-runner безопасен для общего прод-инстанса. +- **PASS:** Путь **никогда** не рестартит прод `orchestrator` (8500), не делает `docker compose up + orchestrator`/`--build` прода, не force-push, не пишет в `main`, не правит `.env`; оперирует только + запуском staging-сюиты (8501) и записью лога (статический/поведенческий ассерт зелёный). +- **FAIL:** Путь способен затронуть прод-контейнер/`main`/`.env`/сделать force-push. + +--- + +## AC-9 — security-review для socket/CLI-вариантов (NFR-3) + +**Условие:** Если выбран вариант с прямым `docker.sock`/CLI из контейнера. +- **PASS:** ADR (`06-adr/`) содержит явный security-разбор (поверхность атаки `docker.sock` = + root-эквивалент, ограничение прав, `:ro` где возможно) **либо** выбран host-side ssh-вариант, + переиспользующий доверенный ORCH-036 механизм без расширения привилегий — и это зафиксировано. +- **FAIL:** Введён доступ к `docker.sock`/CLI из контейнера без security-обоснования в ADR. + +--- + +## AC-10 — kill-switch / область (NFR-4, NFR-6) + +**Условие:** Обратимость и скоуп сохранены. +- **PASS:** `staging_runner_enabled=False` → `deploy-staging` снова через LLM-`deployer` (`_spawn`) + байт-в-байт; `applies(repo)`: self-hosting `orchestrator` — real, прочие репо — no-op; любой новый + флаг стратегии имеет дефолт = боевое (откат флагом → поведение до ORCH-123). Подтверждено тестом. +- **FAIL:** Выключение kill-switch не возвращает прежний путь, либо затронуты прочие репо. + +--- + +## AC-11 — never-raise / очередь не клинится (NFR-5) + +**Условие:** Сбой стратегии исполнения не роняет worker и не клинит очередь. +- **PASS:** Любая ошибка исполнения/классификации изолирована (never-raise); задача либо штатно + продвигается, либо остаётся на `deploy-staging` для reconciler/reaper без вечного залипания; полный + `pytest tests/ -q` зелёный. +- **FAIL:** Ошибка исполнения роняет worker / задача залипает на `deploy-staging` навсегда / тесты + красные. + +--- + +## AC-12 — документация границы исполнения (BR-5) + +**Условие:** Граница исполнения staging-сюиты задокументирована. +- **PASS:** `docs/operations/INFRA.md` и `docs/architecture/README.md` содержат явное описание: где/как + исполняется staging-сюита относительно прод-контейнера, какие исполняемые/сокеты доступны, почему + docker-операции идут host-side (структурная сверка зелёная); `CHANGELOG.md`/`CLAUDE.md` обновлены. +- **FAIL:** Граница исполнения нигде не описана, или docs противоречат фактическому коду. + +--- + +## Сводная матрица AC ↔ FR/BR +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1 / FR-1 | +| AC-2 | BR-1 / FR-1 | +| AC-3 | BR-2 / FR-2, FR-3 | +| AC-4 | BR-3 / FR-2 | +| AC-5 | BR-4 / FR-4 | +| AC-6 | BR-4 / FR-1, FR-2 | +| AC-7 | NFR-1 / FR-(6) | +| AC-8 | NFR-2 | +| AC-9 | NFR-3 | +| AC-10 | NFR-4, NFR-6 / FR-5 | +| AC-11 | NFR-5 | +| AC-12 | BR-5 / FR-6 | diff --git a/docs/work-items/ORCH-123/04-test-plan.yaml b/docs/work-items/ORCH-123/04-test-plan.yaml new file mode 100644 index 0000000..2212820 --- /dev/null +++ b/docs/work-items/ORCH-123/04-test-plan.yaml @@ -0,0 +1,108 @@ +work_item: ORCH-123 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-16 +model_used: claude-opus-4-8 +title: "Staging-runner execution strategy: docker CLI absent in container must not false-fail deploy-staging" +framework: pytest +scope: > + Покрывается: исполнение staging-сюиты для self-hosting orchestrator на deploy-staging без + зависимости от docker CLI внутри прод-контейнера; различение environment/tool-error vs настоящего + код-фейла; анти-over-tolerance (реальный фейл сюиты по-прежнему откатывает); prod-like preflight; + сохранность контракта гейта/артефакта/STAGE_TRANSITIONS/схемы БД; self-hosting safety; kill-switch/ + область; never-raise. Вне покрытия: логика самой staging_check.py (не трогается), выбор конкретного + механизма исполнения (host-side ssh / docker.sock+SDK / CLI в образе / hook-режим — решает архитектор), + изменения STAGE_TRANSITIONS/QG_CHECKS/схемы БД (их нет). +notes: > + TC-01 — ОБЯЗАТЕЛЬНЫЙ регресс-тест воспроизведения инцидента ORCH-116/ORCH-115: КРАСНЫЙ до фикса, + ЗЕЛЁНЫЙ после. Тесты механизм-агностичны: проверяют ТРЕБУЕМЫЙ ИНВАРИАНТ (сюита исполняется; + environment-дефект не даёт код-фейл-отката; настоящий фейл откатывает), а не конкретную стратегию. + Окружение «нет docker CLI» моделировать без сети/прода/ssh (монки-патч PATH/spawn-функции + proc_group, либо изоляция argv staging_runner). Точные имена тест-функций уточнит разработчик после + выбора механизма архитектором. Полный регресс `pytest tests/ -q` обязан оставаться зелёным (NFR-1). + +tests: + - id: TC-01 + type: integration + description: "РЕГРЕСС (обязательный, red→green): исполнение staging-сюиты в окружении БЕЗ docker CLI в прод-контейнере. До фикса воспроизводит proc_group spawn-error '[Errno 2] No such file or directory: docker' → tool-error → инфра-DEFER×2 → ложный FAILED-откат на development. После фикса сюита ИСПОЛНЯЕТСЯ (или environment-дефект не даёт код-фейл-отката). Красный до фикса." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-02 + type: unit + description: "Стратегия исполнения не зависит от docker CLI внутри прод-контейнера: argv/канал, формируемый staging-runner, не требует наличия бинаря `docker` на PATH контейнера (host-side / socket-SDK / CLI-в-образе — в зависимости от выбора ADR; ассерт проверяет инвариант, а не конкретный механизм)." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-03 + type: integration + description: "environment/tool-error НЕ даёт код-фейл-отката (AC-3): при неработоспособной стратегии (исполняемое отсутствует) задача НЕ переходит deploy-staging → development, developer-retry НЕ инкрементируется, идёт отличимый инфра/environment-алерт ('НЕ дефект кода')." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-04 + type: unit + description: "Анти-over-tolerance (AC-4): сюита РЕАЛЬНО исполнилась (получен exit-код) и упала (exit≠0) → staging_status: FAILED → ПРЕЖНИЙ откат deploy-staging → development + developer-retry. Настоящий фейл сюиты НЕ маскируется как 'инфра'." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-05 + type: unit + description: "Happy-path: сюита исполнилась, exit 0 → staging_status: SUCCESS → штатная инициация advance_stage(deploy-staging, deployer) без новых рёбер/исходов (контракт ORCH-115 D7 сохранён)." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-06 + type: unit + description: "Классификация (по образцу merge_gate.classify_retest_failure): постоянный environment-дефект (spawn-error 'исполняемое не найдено') отличается от транзиентной инфры и от настоящего код-фейла; постоянный дефект НЕ трактуется как транзиент (бессмысленный ретрай) и НЕ как код-фейл." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-07 + type: integration + description: "Prod-like preflight (AC-5): механизм раннего детекта 'стратегия исполнения неработоспособна (нет исполняемого/канал недоступен)' сигнализирует ДО ложного отката реальной задачи (старт сервиса / smoke / applies / should_intercept — в зависимости от выбора ADR)." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-08 + type: unit + description: "Self-hosting safety (AC-8): путь исполнения никогда не рестартит прод 8500, не делает docker compose up orchestrator/--build прода, не force-push, не пишет в main, не правит .env (статический/поведенческий ассерт; инвариант ORCH-115 BR-7 сохранён)." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-09 + type: unit + description: "Kill-switch/область (AC-10): staging_runner_enabled=False → should_intercept False → прежний LLM-deployer через _spawn байт-в-байт; applies(repo): self-hosting orchestrator real, прочие репо — no-op; новый флаг стратегии (если есть) имеет дефолт = боевое." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-10 + type: unit + description: "Контракт артефакта (AC-7): 15-staging-log.md сохраняет staging_status:-frontmatter (UPPERCASE значение) + 52c-схему (author_agent: staging-runner / model_used: n/a); вердикт читается только из frontmatter через src/frontmatter.py." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-11 + type: unit + description: "Анти-регресс конвейера (AC-7): STAGE_TRANSITIONS / реестр QG_CHECKS / имена и семантика check_staging_status / _parse_staging_status / machine-verdict ключи (staging_status:/deploy_status:) — не изменены; миграции БД нет (структурная сверка)." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-12 + type: unit + description: "never-raise / очередь не клинится (AC-11): любая ошибка исполнения/классификации изолирована, worker не падает, задача не залипает на deploy-staging навсегда; снапшот staging_runner в GET /queue различает environment/tool-error vs код-фейл." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-13 + type: unit + description: "Документация-инвариант (AC-12): docs/operations/INFRA.md и docs/architecture/README.md содержат описание границы исполнения staging-сюиты (host-side vs in-container, доступные исполняемые/сокеты) — структурная сверка наличия раздела." + module: tests/test_orch123_staging_runner_exec.py + expected: PASS + + - id: TC-14 + type: unit + description: "Анти-дрейф ORCH-115: существующие структурные тесты staging-runner (tests/test_orch115_staging_runner.py) и LLM-determinization анти-дрейф остаются ЗЕЛЁНЫМИ после фикса (фикс не ломает инварианты ORCH-115)." + module: tests/test_orch115_staging_runner.py + expected: PASS From 2a47744c9da2a6b106a71d0d34324f3bb8d68d3f Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 08:07:55 +0300 Subject: [PATCH 2/8] architect(ET): auto-commit from architect run_id=748 --- ...049-host-side-docker-execution-boundary.md | 105 ++++++ ...taging-execution-and-env-classification.md | 333 ++++++++++++++++++ .../ORCH-123/07-infra-requirements.md | 85 +++++ docs/work-items/ORCH-123/10-tech-risks.md | 93 +++++ 4 files changed, 616 insertions(+) create mode 100644 docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md create mode 100644 docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md create mode 100644 docs/work-items/ORCH-123/07-infra-requirements.md create mode 100644 docs/work-items/ORCH-123/10-tech-risks.md diff --git a/docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md b/docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md new file mode 100644 index 0000000..81e448c --- /dev/null +++ b/docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md @@ -0,0 +1,105 @@ +--- +work_item: ORCH-123 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# adr-0049: Граница исполнения docker — все docker-операции host-side, не изнутри app-контейнера + +> **Сквозной (cross-cutting) ADR.** Кодифицирует инвариант **«docker-операции оркестратора +> исполняются host-side через доверенный ssh-канал, никогда изнутри прод-контейнера»**, охватывающий +> компоненты ORCH-036/058/115/123/101, и **амендит** execution-strategy-решение +> [adr-0048](adr-0048-deterministic-staging-runner.md) (D3/D5). Поводом стала задача ORCH-123 (баг: +> staging-runner отклонился от инварианта). Локальная детализация (D1–D9) — +> `docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md`. + +## Статус +Proposed + +## Контекст + +Прод-контейнер `orchestrator` (8500) **не содержит docker CLI** (`Dockerfile:11`: +`openssh-client git curl ca-certificates` + pinned gitleaks; `python:3.12-slim` docker не несёт). +`/var/run/docker.sock` смонтирован rw + `group_add 999` (ORCH-040 «МИНА 1»), но **клиента, который +бы им воспользовался, нет** — сознательно: добавление CLI/SDK активировало бы root-эквивалентный путь +исполнения для всего, что бежит в контейнере (вкл. LLM-агентов). Поэтому в оркестраторе сложился +**инвариант исполнения**, ранее не выделенный в отдельный ADR: + +- **ORCH-036** (`self_deploy.build_deploy_command`, [adr-0007](adr-0007-executable-self-deploy.md)) — + прод-деплой исполняется host-side через `ssh + setsid bash --deploy` на `127.0.0.1`. +- **ORCH-058** (`image_freshness`, [adr-0008](adr-0008-staging-image-provenance.md)) — ребилд + staging-образа (`ssh … bash --build-staging`) и инспекция revision + (`image_revision(ssh_target=…)`) — host-side; модуль прямо документирует: + *«docker lives on the HOST (the container ships only openssh-client git)»*. +- **ORCH-101** ([adr-0036](adr-0036-replication-foundation-host-parametrization.md)) — host-параметры + канала (`deploy_ssh_*`, `deploy_host_repo_path`, `repos_dir`/`host_repos_dir`) расхардкожены. + +**ORCH-115** ([adr-0048](adr-0048-deterministic-staging-runner.md)), заменяя LLM-деплойера +детерминированным `staging_runner`, **отклонился** от инварианта: зашил `docker exec` **изнутри** +прод-контейнера через `proc_group → Popen` → `FileNotFoundError: docker` → постоянный +environment-дефект, ложно маршрутизированный как транзиентная инфра → DEFER → fail-closed FAILED → +**откат `deploy-staging → development`** (винит код задачи за дефект окружения раннера). Инцидент +ORCH-116/ORCH-123. + +## Решение + +**Кодифицировать инвариант (нормативно):** docker-операции оркестратора (`docker`/`docker compose`/ +`docker exec`/`docker inspect`/`docker tag`) исполняются **host-side** через доверенный ssh-канал +(`deploy_ssh_host=127.0.0.1`, ключ смонтирован, `openssh-client` в образе) — **никогда** изнутри +прод-контейнера, который docker CLI не несёт. `/var/run/docker.sock` **не используется** изнутри +контейнера; docker CLI/SDK в образ **не добавляется** (любое исключение — отдельный явный +security-review: socket-из-контейнера = root-эквивалент на хосте, обслуживающем все проекты). + +**ORCH-123 приводит `staging_runner` в соответствие** (амендит adr-0048 D3/D5): +- **D3 (амендмент adr-0048):** `staging_runner.build_staging_command` теперь обёртывает + `docker exec orchestrator-staging python3 staging_check.py …` в `ssh @ '<…>'` (зеркало + `image_freshness.image_revision(ssh_target=…)`). Внутренняя команда сюиты и exit-код-контракт — те + же; меняется лишь **инициатор/канал**. +- **D5 (амендмент adr-0048 двухуровневого исхода):** введён **третий** класс исхода `permanent-env` + (зеркало `merge_gate.classify_retest_failure`, ORCH-110); корневой инвариант — **«сюита не + исполнилась» (environment ИЛИ транзиентная инфра) НИКОГДА не оканчивается код-фейл-откатом и не жжёт + developer-retry**; откат — только для реально исполнившейся сюиты с `exit≠0`. Терминал исчерпания + DEFER изменён с fail-closed-FAILED+advance на **infra-HOLD + alert** (как ORCH-110 D3). + +Кросс-каттинговые инварианты (сохранены **байт-в-байт**, как adr-0048): +- `STAGE_TRANSITIONS` / реестр и имена `QG_CHECKS`/`check_staging_status`/`_parse_staging_status` / + machine-verdict-ключи (`staging_status:`/`deploy_status:`/…) / **схема БД** — не тронуты (замена + *стратегии исполнения продюсера*, не гейта/стадии). +- Единственный транспорт LLM-консультации (`launcher._spawn`/S0, [adr-0047](adr-0047-llm-usage-policy-and-call-site-map.md)) + — соблюдён (раннер LLM не зовёт). +- Сквозной бюджет времени ORCH-065/109/110 (`reaper_max_running_s` > Σ(работ на ребре) + grace) — не + растёт (host-side ssh заменяет in-container call, окно ≤ `staging_runner_timeout_s`). +- Граница transition-lease ORCH-114 — берётся внутри `advance_stage`; раннер не трогает. + +Скоуп — **self-hosting only** (`staging_runner_repos=""` → `is_self_hosting_repo`); под флагами +`staging_runner_enabled` (→ LLM-путь) и **новым** `staging_runner_exec_host_side` (дефолт `True` → +фикс; `False` → прежний in-container call). never-raise во всех публичных функциях. + +## Последствия + +- **+** Инвариант «docker host-side» выделен и задокументирован → будущие компоненты не повторят + отклонение ORCH-115; reviewer ловит in-container docker как регресс инварианта. +- **+** staging-сюита реально исполняется в проде; инфра/environment ≠ код-фейл на staging-ребре + (закрыт RCA-класс ORCH-110 на этом ребре полностью); анти-over-tolerance цел. +- **+** Без расширения привилегий (нет docker CLI/SDK в контейнере, сокет не используется); согласовано + с ORCH-036/058. +- **−** Remote tree-kill ограничен локальным ssh-клиентом (как `image_freshness.rebuild_staging_image`); + backstop — bounded таймаут внутри `staging_check.py`. +- **−** Permanent-env/исчерпавшая-DEFER задача держится на `deploy-staging` (блокирует serial-gate репо + до починки оператором) — принятый tradeoff (зеркало ORCH-110), self-hosting only. +- **Откат:** `ORCH_STAGING_RUNNER_ENABLED=false` (→ LLM) или `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=false` + (→ in-container call). + +## Ссылки +- Локальный ADR: `docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md` +- Амендит: [adr-0048](adr-0048-deterministic-staging-runner.md) (D3/D5 ORCH-115) +- Опирается на: [adr-0007](adr-0007-executable-self-deploy.md) (ORCH-036 self-deploy ssh), + [adr-0008](adr-0008-staging-image-provenance.md) (ORCH-058 image-freshness host-side docker), + [adr-0042](adr-0042-merge-gate-retest-infra-tolerance-and-tree-kill.md) (ORCH-110 proc_group + + classify + infra-tolerance), [adr-0036](adr-0036-replication-foundation-host-parametrization.md) + (ORCH-101 host-параметризация) +- Сверено по коду: `src/staging_runner.py`, `src/self_deploy.py:220`, `src/image_freshness.py:185/246`, + `scripts/orchestrator-deploy-hook.sh:166/197`, `Dockerfile:11`, `docker-compose.yml` diff --git a/docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md b/docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md new file mode 100644 index 0000000..c91f278 --- /dev/null +++ b/docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md @@ -0,0 +1,333 @@ +--- +work_item: ORCH-123 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# ADR-001: Стратегия исполнения staging-раннера — host-side ssh + классификация environment-дефекта + +Work Item: **ORCH-123** — staging-runner (ORCH-115) исполняет `docker exec` **изнутри** +прод-контейнера, где нет docker CLI → постоянный environment-дефект ложно маршрутизируется как +код-фейл (откат `deploy-staging → development`). Стадия: **architecture** (задача-`Bug`, +эскалирована `escalate: full-cycle` — `01-brd.md`, D5 ORCH-019). +Сквозная регистрация: **`docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md`** +(решение кросс-каттинговое — кодифицирует инвариант «docker-операции исполняются host-side», +охватывающий ORCH-036/058/115/123/101, и амендит execution-strategy-решение adr-0048). + +## Статус +Proposed + +## Контекст + +**Установленный факт (сверено по коду и инфраструктуре, BRD §1):** ORCH-115 +(`src/staging_runner.py:154`, `build_staging_command`) исполняет staging-сюиту командой +`["docker", "exec", "orchestrator-staging", "python3", ".../staging_check.py", …]` **изнутри +прод-контейнера `orchestrator`** через `proc_group.run_in_process_group` → `subprocess.Popen`. +Прод-контейнер docker CLI **не содержит**: + +- `Dockerfile:11` ставит `openssh-client git curl ca-certificates` (+ pinned gitleaks) — бинаря + `docker` нет; `python:3.12-slim` его тоже не несёт → `Popen(["docker", …])` падает + `FileNotFoundError: [Errno 2] No such file or directory: docker`. +- `docker-compose.yml:40` монтирует `/var/run/docker.sock` (rw) в сервис `orchestrator` и + добавляет `group_add 999` (ORCH-040 «МИНА 1»). **Сокет в контейнере есть, а CLI-клиента, + который бы им воспользовался, — нет.** Проблема не в доступе к Docker, а в **отсутствии + исполняемого клиента** в образе. + +Цепочка отказа в проде (job ORCH-116): `Popen` → `OSError` → `proc_group` деградирует в +`ProcResult(returncode=None, timed_out=False)` → в `run_staging_gate` (`:528`) +`suite_ran = (returncode is not None) and (not timed_out)` = **False** → ветка tool-error → +`_handle_tool_error` (`:415`) → инфра-DEFER ×2 → бюджет исчерпан → +`write_staging_log(..., "FAILED", tool_error=True)` + `_advance` → **существующий откат +`deploy-staging → development`** (как код-фейл задачи). Так до фикса **любая** self-hosting задача, +доходящая до `deploy-staging`, обречена на ложный откат. + +**Корневая классификационная ошибка (BRD §1):** двухуровневый исход ORCH-115 (D5) различает только +«сюита исполнилась» vs «сюита не исполнилась (транзиентная инфра → DEFER → fail-closed FAILED)». +Отсутствие docker CLI — **детерминированный, постоянный environment-дефект**, а не транзиентная +икота: ретраи бессмысленны (каждая попытка падает идентично), а терминальный +fail-closed-FAILED-откат винит код/разработчика за дефект окружения раннера. + +**Установленный паттерн, от которого ORCH-115 отклонился (сверено по коду):** прод-деплой ORCH-036 +(`src/self_deploy.py:220`, `build_deploy_command`) и image-freshness ORCH-058 +(`src/image_freshness.py`) **уже** исполняют все docker-операции **host-side** через +`ssh + setsid`/`ssh` на `deploy_ssh_host=127.0.0.1` (ssh-ключ смонтирован, `openssh-client` в +образе). `image_freshness.image_revision` (`:185`) прямо документирует инвариант: +> *«`docker` lives on the HOST (the container ships only `openssh-client git`)»* +и при `ssh_target` обёртывает `docker image inspect` в ssh. Хост-хук +`scripts/orchestrator-deploy-hook.sh --build-staging` (`:197`) уже делает host-side +`docker exec "$STAGING_CONTAINER" python3 staging_check.py` — на хосте, где docker CLI есть. + +**Вывод:** ORCH-115 при замене LLM-деплойера детерминированным раннером **отклонился** от уже +установленного инварианта «docker-операции — host-side, не изнутри app-контейнера». Дефект — в +**стратегии исполнения** раннера, **не** в гейте `check_staging_status` и **не** в контракте +`15-staging-log.md` (BRD §«Вне объёма»; NFR-1). + +> 🔎 **Проверка точки BRD (как сюита исполнялась до ORCH-115 LLM-деплойером):** до ORCH-115 +> staging-сюиту исполнял LLM-агент `deployer` (`.openclaw/agents/deployer.md` шаг 1), которому +> формулировка шага позволяла исполнить шаги на хосте/в нужном контексте; ORCH-115 жёстко зашил +> `docker exec` именно **изнутри** прод-контейнера через `proc_group`. То есть ORCH-115 сделал +> ранее-гибкий путь жёстко-неработоспособным в проде. На выбор стратегии фикса это не влияет +> (host-side восстанавливает рабочий инвариант независимо от истории). + +## Решение + +Восстановить **host-side стратегию исполнения** staging-сюиты через уже доверенный ssh-канал +(ORCH-036/058) и ввести **трёхстороннюю классификацию исхода**, чтобы постоянный +environment-дефект и транзиентная инфра **никогда** не оканчивались код-фейл-откатом, а только +реально исполнившаяся упавшая сюита — откатывала (анти-over-tolerance). Гейт / контракт артефакта / +`STAGE_TRANSITIONS` / схема БД — **байт-в-байт неизменны** (замена *стратегии исполнения продюсера*, +не гейта). Аддитивно, под флагами, never-raise, скоуп self-hosting. + +### D1 — Стратегия исполнения: host-side ssh, обёртывающий `docker exec` (BR-1 / FR-1 / AC-1, AC-2) + +`staging_runner.build_staging_command()` теперь строит **ssh-обёрнутую** команду (зеркало +`self_deploy.build_deploy_command` / `image_freshness.image_revision(ssh_target=…)`): + +``` +ssh -o StrictHostKeyChecking=no @ \ + 'docker exec python3 //scripts/staging_check.py \ + --base-url http://localhost: --mode stub' +``` + +- Внутренняя команда (`docker exec … staging_check.py … --mode stub`) — **та же**, что прежде + (контракт сюиты и exit-кода не меняется, BRD §«Вне объёма»); собирается из config (ORCH-101, без + host-хардкодов), `shlex.quote`-ится в inner-строку ssh. +- Канал — существующий: `deploy_ssh_user`/`deploy_ssh_host` (compose: + `ORCH_DEPLOY_SSH_HOST=127.0.0.1`, `ORCH_DEPLOY_SSH_USER=slin`); ssh-ключ смонтирован + (`${ORCH_HOST_SSH_DIR}:…/.ssh:ro`), `openssh-client` в образе (`Dockerfile:11`). **Новых + секретов/привилегий не вводится** (NFR-3). +- Запуск по-прежнему через `proc_group.run_in_process_group` (bounded local timeout + tree-kill + локального ssh-клиента, ORCH-110). **Ограничение (документируется, D-Последствия):** tree-kill + убивает локальный ssh-клиент, но не гарантирует убийство удалённого `docker exec`-дерева на + хосте; backstop — bounded таймаут самой `staging_check.py` внутри сюиты. Это **то же** допущение, + что у уже принятого `image_freshness.rebuild_staging_image` (синхронный ssh без remote tree-kill). +- **Self-hosting safety (NFR-2 / AC-8):** argv содержит **только** `docker exec + python3 staging_check.py … --mode stub` — **никаких** литералов рестарта прод-8500, + `docker compose up orchestrator`/`--build` прода, force-push, записи в `main`, правки `.env`. + Структурный анти-литерал-тест (ORCH-115 TC-12, расширяется TC-08 ORCH-123) держит инвариант на + ssh-обёрнутой команде. + +### D2 — Почему host-side ssh, а НЕ socket/CLI-в-контейнере — security-review (NFR-3 / AC-9) — **ключевое решение безопасности** + +BRD/TRZ перечисляют четыре кандидата (host-side ssh / Docker SDK поверх `docker.sock` / docker CLI +в образе / выделенный hook-режим). Любой вариант с **прямым использованием `docker.sock`/CLI +изнутри контейнера** = **root-эквивалент на хосте** и требует явного security-обоснования. + +**Разбор поверхности атаки:** +- `/var/run/docker.sock` смонтирован rw + `group_add 999` **уже** (ORCH-040, «МИНА 1»). Это + **дремлющая** возможность: контейнер может *достучаться* до сокета, но **не имеет клиента**, чтобы + им воспользоваться. Добавление docker CLI в образ **или** Docker SDK (`pip install docker`) + превратило бы дремлющую возможность в **активный root-эквивалентный путь исполнения**, доступный + не только worker-коду, но и **любому subprocess'у в том же контейнере — включая LLM-агентов**, + которых оркестратор спавнит (`launcher._spawn`). Это **расширение поверхности атаки** (компрометация + агента/зависимости → полный контроль docker → root на хосте, обслуживающем ВСЕ проекты). +- Host-side ssh держит docker-операции **на хосте** под **существующим** доверенным key-gated + каналом (ORCH-036/058), **не наделяя** in-container код docker-возможностями. Это **строго + безопаснее** и согласуется с задокументированным инвариантом `image_freshness`. + +**Решение:** выбран **host-side ssh** (D1). Docker CLI/SDK в контейнер **не добавляется**; +использование `docker.sock` **не расширяется**. ORCH-123 поверхность ORCH-040 (смонтированный сокет) +**не трогает и не расширяет** (правка compose вне объёма — BRD §«Вне объёма», happy-path +прод-деплоя/ORCH-040 не трогаем). Если будущая задача потребует socket/CLI-в-контейнере — это +**отдельный** явный security-review; этот ADR его не выдаёт (AC-9 удовлетворён выбором ssh-варианта, +переиспользующего доверенный ORCH-036 механизм без расширения привилегий). + +### D3 — Трёхсторонняя классификация исхода (FR-2 / FR-3 / AC-3, AC-4, AC-6) — **ключевое решение** + +Чистая функция `classify_staging_outcome(result, ssh_configured) -> str` (зеркало +`merge_gate.classify_retest_failure`, ORCH-110 D2; pure, never-raise) различает **три** класса: + +| Класс | Детерминированный сигнал | Семантика | +|-------|--------------------------|-----------| +| `permanent-env` | `returncode is None and not timed_out` (spawn-error локального бинаря) **ИЛИ** ssh-target не сконфигурирован **ИЛИ** `returncode in (126, 127)` **ИЛИ** stderr содержит маркеры `command not found` / `executable file not found` / `No such container` / `is not running` / `Cannot connect to the Docker daemon` / `Is the docker daemon running` | Постоянный дефект окружения (нет docker/ssh, контейнер не поднят, демон недоступен). Ретрай бессмыслен. | +| `transient-infra` | `timed_out` **ИЛИ** `returncode == 255` (ssh transport/connection) | Транзиентная инфра (сеть/handshake/стенд на миг недоступен). Ретрай осмыслен. | +| `suite-ran` | распознанный исполнительный exit-код (любой иной int) **и НЕТ** env-маркера в stderr | Сюита **реально исполнилась** — доверяем коду (`0→SUCCESS`, `≠0→FAILED`). | + +- **Дизамбигуация «сюита exit=1 vs `docker exec` No such container exit=1»** — по **скану stderr на + env-маркеры** (а не по голому exit-коду): env-маркер → `permanent-env`; нет маркера → `suite-ran` + (`staging_check.py` пишет PASS/FAIL в stdout, её коды — 0/≠0 без 126/127/255). Маркер-сет + финализирует разработчик; набор выше — стартовый, по образцу scope-guard `merge_gate`. +- **Анти-over-tolerance (BR-3 / AC-4, зеркало ORCH-110 BR-6):** распознанный `suite-ran` exit-код + **никогда** не реклассифицируется в инфру → реальный фейл сюиты (`exit≠0`) идёт прежним путём. +- **Fail-safe при неоднозначности:** неизвестный сигнал по умолчанию → `transient-infra` (DEFER), а + **не** `suite-ran` — mis-route environment→код-фейл есть именно тот дефект, что чиним; но + распознанный suite-exit без env-маркера всегда `suite-ran` (BR-3 не ослаблен). + +### D4 — Маршрутизация исходов (BR-2 / BR-3 / FR-2 / FR-3 / AC-3, AC-4) — **инвариант: инфра ≠ код-фейл** + +| Класс | Действие | +|-------|----------| +| `suite-ran` | **Без изменений** (ORCH-115): `write_staging_log` + `_advance` → `SUCCESS`→под-гейты+Phase A; `FAILED`→**прежний** откат `deploy-staging → development` + developer-retry (`stage_engine.py:932`). BR-3 байт-в-байт. | +| `permanent-env` | **Немедленный отличимый infra-исход:** DEFER-цикл **пропускается** (ретрай постоянного дефекта бессмыслен — FR-3); записывается структурный `permanent-env`-лог + операторский алерт («инфра/окружение, **НЕ дефект кода**», кликабельный номер); **НЕ** `_advance`, **НЕ** откат, **НЕ** developer-retry. Задача **остаётся на `deploy-staging`** (infra-HOLD). Счётчик `permanent_env`++. | +| `transient-infra` | **Существующий** bounded DEFER (re-queue `deployer`-джоба + delay + restart-safe маркер `_INFRA_RETRY_MARKER`, cap `staging_runner_infra_max_retries`). | + +**Изменение терминала исчерпания DEFER (супершид ORCH-115 ADR D5):** при исчерпании бюджета DEFER +исход — **infra-HOLD + алерт** (как `permanent-env`), а **НЕ** прежний fail-closed +`write_staging_log("FAILED") + _advance` (= откат). Прежний терминал нарушал BR-2 (транзиентная инфра, +которая не прояснилась, всё равно ложно откатывалась как код-фейл). Новый терминал выравнивает +staging-раннер с моделью `merge_gate` infra-tolerance (ORCH-110 D3: исчерпание инфра → алерт «НЕ +дефект кода», задача **не** уходит в `development`). + +**Корневой инвариант (нормативно):** «сюита **не исполнилась**» (environment ИЛИ транзиентная инфра) +**никогда** не оканчивается код-фейл-откатом `deploy-staging → development` и **никогда** не жжёт +developer-retry. Откат — **только** для реально исполнившейся сюиты с `exit≠0` (`suite-ran`/`FAILED`). +Это закрывает RCA-класс ORCH-110/111…117 на staging-ребре. + +**Re-drive / отсутствие вечного залипания (NFR-5 / AC-11):** infra-HOLD оставляет задачу на +`deploy-staging` в восстановимом состоянии (worker не падает, тугого ретрай-цикла нет, исход виден в +алерте + `GET /queue` + структурном логе). После починки окружения оператором задача переоткатывается +**существующим** механизмом (оператор / reconciler ORCH-053), без нового движка. **Граница (риск +R-2):** reconciler/reaper **должен** трактовать infra-held `deploy-staging`-задачу как удержанную +(пере-выдать `deployer`-джоб), **не** откатывать её в `development` — иначе реинтродукция дефекта; +developer верифицирует (`10-tech-risks.md`). + +### D5 — Prod-like preflight (BR-4 / FR-4 / AC-5) + +`staging_runner.preflight() -> tuple[bool, str]` (bounded, never-raise, self-hosting-скоуп — +`applies(repo)` первым): +- Пробит **канал исполнения** host-side коротким bounded ssh-зондом: + `ssh 'command -v docker >/dev/null && docker inspect -f "{{.State.Running}}" + '` → распознаёт «нет docker на хосте» / «staging-контейнер не поднят» / «ssh + недоступен» **до** того, как реальная задача дойдёт до ложного исхода. +- Вызывается на **старте сервиса** в `main.lifespan` (best-effort, после + `requeue_running_jobs`/`recover_on_startup`, **никогда не блокирует старт**) → условие инцидента + всплывает на рестарте/деплое самого орка, а не постфактум на реальной задаче. Эмитит структурный + лог + Telegram-алерт при неудаче + поле в `snapshot()`. +- **Чисто наблюдательный:** preflight **не** гейтит/блокирует конвейер, **не** трогает стадии/QG, + never-raise (FR-4). Регресс-тест TC-01 моделирует «нет docker CLI в контейнере» (монки-патч + argv/spawn) — **красный до фикса** (in-container `docker exec` → spawn-error → tool-error → ложный + откат), **зелёный после** (host-side стратегия + `permanent-env`-классификация → нет код-фейл-отката). + +### D6 — Условность / kill-switch / обратимость (FR-5 / NFR-4 / NFR-6 / AC-10) + +`config.py` (паттерн `staging_runner_*` / ORCH-101 «дефолт = боевое»): +- **Новый:** `staging_runner_exec_host_side: bool = True` (env `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE`). + `True` (дефолт) → host-side ssh-стратегия (D1, фикс). `False` → прежний in-container `docker exec` + (валиден **только** там, где docker CLI запечён в образ; в текущем проде — нет). Добавить в + `.env.example`. +- **Переиспользуются:** `staging_runner_enabled` (kill-switch; `False` → прежний LLM-`deployer` через + `_spawn` **байт-в-байт**, ORCH-115 fail-safe), `staging_runner_repos` (CSV; пусто → self-hosting + only через `is_self_hosting_repo`), `staging_runner_timeout_s`, `staging_runner_infra_max_retries`/ + `_retry_delay_s` (DEFER-бюджет транзиентной инфры), `deploy_ssh_user`/`deploy_ssh_host`/ + `deploy_host_repo_path` (ssh-канал). +- `applies(repo)` (локально, без сети) — **первым** в `should_intercept`: выключенный флаг = нулевой + оверхед, на `deploy-staging` штатно `_spawn`. **Откат:** `ORCH_STAGING_RUNNER_ENABLED=false` + (→ LLM-путь) **или** `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=false` (→ прежний in-container call). + Для прочих репо `applies==False` → no-op (нулевая регрессия enduro). NFR-6. + +### D7 — Сохранность контракта (NFR-1 / AC-7) — границы O1 + +**Байт-в-байт неизменны:** `STAGE_TRANSITIONS` (`src/stages.py`), реестр и имена `QG_CHECKS`/ +`check_staging_status`/`_parse_staging_status`, machine-verdict-ключи (`staging_status:`/ +`deploy_status:`/…), **схема БД** (restart-safe счётчик DEFER — маркер в `task_content`, без +миграции). `15-staging-log.md` сохраняет `staging_status:`-frontmatter (UPPERCASE) + 52c-схему +(`author_agent: staging-runner` / `model_used: n/a`); вердикт читается ТОЛЬКО из frontmatter через +`src/frontmatter.py`. Это замена *стратегии исполнения продюсера*, не гейта/стадии (зеркало +инварианта ORCH-115 NFR-1). transition-lease ORCH-114 берётся **внутри** `advance_stage` — раннер +его не трогает (граница O1, как ORCH-115 D7). + +### D8 — Наблюдаемость (BR-6 / AC-12-набл.) + +`_STAGING_RUNNER_COUNTERS` расширяется ключом `permanent_env` (+ существующие +`runs`/`success`/`failed`/`tool_error`/`deferred`). `snapshot()` / read-only блок `staging_runner` в +`GET /queue` различает **три** не-успешных класса: `code-fail` (исполнившаяся сюита `FAILED`) vs +`transient-infra` (`deferred`) vs `permanent-env` (новый). Один структурный лог-вердикт на прогон +(`work_item`/`repo`/`exit_code`/`status`/`duration_s`/`outcome` ∈ {`code-pass`,`code-fail`, +`transient-infra`,`permanent-env`}) + Telegram-алерт на `permanent-env`/infra-исчерпание с +кликабельным номером и явной формулировкой «инфра/окружение, НЕ дефект кода». + +### D9 — Норматив сопровождения docs (BR-5 / FR-6 / AC-12) — спека для development + +Документация границы исполнения и витрина **коуплены к состоянию кода** (описывают post-fix +поведение; структурный анти-дрейф TC-13 проверяет наличие разделов). По прецеденту **ORCH-115 D11 / +adr-0048** (и маршрутизации analyst'а — `02-trz.md` §2) эти правки применяет **developer атомарно с +кодом** в том же PR, **не** architecture-стадия (иначе доки/тесты описывают не-существующий ещё код). +Точная спека (developer применяет дословно): + +- **`docs/operations/INFRA.md`** — в раздел `## ⚠️ Self-hosting` (или новый под-раздел «Граница + исполнения docker-операций») зафиксировать: контейнер `orchestrator` несёт **только** + `openssh-client git curl` (docker CLI **нет**); `/var/run/docker.sock` смонтирован, но **не + используется изнутри** (нет клиента, сознательно — см. D2); **все** docker-операции + (прод-деплой ORCH-036, image-freshness ORCH-058, **staging-runner ORCH-123**) исполняются + **host-side** через ssh на `127.0.0.1` под смонтированным ключом; staging-сюита (`staging_check.py`) + по-прежнему исполняется **внутри** `orchestrator-staging` (8501) — меняется лишь **кто инициирует** + `docker exec` (host vs прод-контейнер). +- **`docs/architecture/README.md`** — в секции про staging-гейт/ORCH-115 (или соседней) описать + host-side стратегию исполнения staging-раннера и трёхстороннюю классификацию (env ≠ код-фейл), + сослаться на `adr-0049`. +- **`CLAUDE.md`** — раздел ORCH-115 дополнить фиксом ORCH-123 (host-side exec + классификация + environment-дефекта); **`CHANGELOG.md`** — запись `fix:`; **`docs/overview/`** — если затронут + машинно-проверяемый факт (`tests/test_system_docs.py`). +- **Анти-дрейф ORCH-115 (TC-14):** существующие `tests/test_orch115_staging_runner.py` и + LLM-determinization-тесты остаются зелёными (фикс не ломает инварианты ORCH-115: контракт/гейт/ + один транспорт LLM `_spawn`/«ровно один first_slice» целы). + +## Альтернативы + +- **Docker CLI в образ (`Dockerfile`) + `docker exec` через смонтированный сокет** — отвергнуто + (D2): активирует дремлющий root-эквивалентный путь для всего, что исполняется в контейнере (вкл. + LLM-агентов) — расширение поверхности атаки. Требовало бы отдельного security-review; host-side ssh + достигает цели без расширения привилегий. +- **Docker SDK (`pip install docker`) поверх `docker.sock`** — отвергнуто: та же security-проблема, + что выше, + новая зависимость + не переиспользует доказанный канал. +- **Выделенный режим хука (`--run-staging-check`) через ssh** — отвергнуто как избыточное: прецедент + `image_freshness.image_revision(ssh_target=…)` уже исполняет docker-команду через **прямой** ssh + (без хука); `--build-staging` хука перегружен ребилдом образа (это работа ORCH-058, не раннера) — + переиспользовать его нельзя, а заводить новый hook-режим тяжелее прямого ssh-wrap. Прямой + ssh-обёртки (D1) достаточно. +- **tool-error → немедленный `FAILED`-откат на `development`** (исходный путь до ORCH-115 D5) — + отвергнуто: это в точности дефект ORCH-123 (и анти-паттерн ORCH-110). +- **Сохранить ORCH-115 D5 терминал (исчерпание DEFER → fail-closed `FAILED` + `_advance`)** — + отвергнуто: нарушает BR-2 (транзиентная инфра, не прояснившаяся за N попыток, всё равно ложно + откатывается как код-фейл). Заменён на infra-HOLD + алерт (D4), как ORCH-110 D3. +- **Двухсторонняя классификация (как ORCH-115)** — отвергнуто: не отличает постоянный + environment-дефект (ретрай бессмыслен, нужен немедленный HOLD) от транзиентной инфры (ретрай + осмыслен). Трёхсторонняя (D3) различает (FR-3). + +## Последствия + +- **+** На `deploy-staging` для `orchestrator` staging-сюита **реально исполняется в проде** + (host-side через доверенный ssh-канал); задача уровня ORCH-116 доходит до `deploy`, а не + откатывается (BR-1 / AC-2). +- **+** **Инфра/environment ≠ код-фейл** на staging-ребре: ни environment-дефект, ни транзиентная + инфра не дают ложного отката `→ development` и не жгут developer-retry (BR-2). Закрыт RCA-класс + ORCH-110 на staging-ребре полностью (не только частично, как ORCH-115 D5). +- **+** Анти-over-tolerance цел: реально исполнившаяся упавшая сюита по-прежнему откатывает (BR-3). +- **+** Переиспользует существующий доверенный ssh-канал (ORCH-036/058) — **без** расширения + привилегий, **без** docker CLI/SDK в контейнере (NFR-3); согласовано с задокументированным + инвариантом `image_freshness`. +- **+** Полная обратимость двумя флагами (`staging_runner_enabled` → LLM; + `staging_runner_exec_host_side` → in-container); контракт/гейт/ребро/схема БД неизменны. +- **−** Remote tree-kill ограничен локальным ssh-клиентом (удалённое `docker exec`-дерево не + гарантированно убивается tree-kill'ом) — **то же** допущение, что у принятого + `image_freshness.rebuild_staging_image`; backstop — bounded таймаут внутри `staging_check.py`. +- **−** Permanent-env / исчерпавшая-DEFER задача **держится** на `deploy-staging` до починки + окружения оператором → блокирует serial-gate репо (ORCH-088) для **более поздних** задач. + Принятый tradeoff (зеркало ORCH-110 infra-HOLD): environment-проблема, требующая оператора, + **должна** остановить репо, а не молча ложно-откатывать; скоуп self-hosting only. +- **−** Классификация по stderr-маркерам имеет остаточную неоднозначность. Митигейшн: fail-safe + default → `transient-infra` (не `suite-ran`); распознанный suite-exit без env-маркера всегда + доверяется (BR-3); набор маркеров — по образцу `merge_gate` scope-guard, под покрытием TC-06. +- **Откат:** `ORCH_STAGING_RUNNER_ENABLED=false` → прежний LLM-`deployer` на `deploy-staging` + байт-в-байт; либо `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=false` → прежний in-container `docker exec`. + +## Ссылки +- BRD: `docs/work-items/ORCH-123/01-brd.md`; ТЗ: `02-trz.md`; Acceptance: `03-acceptance-criteria.md`; + Test-plan: `04-test-plan.yaml` +- Инфра: `docs/work-items/ORCH-123/07-infra-requirements.md`; Риски: `10-tech-risks.md` + (данные — `08` N/A: схема БД не меняется, TRZ §5) +- Сквозной ADR: `docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md` +- Амендит / опирается на: ORCH-115 (`docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md`, + `adr-0048`) — стратегия исполнения D3 и терминал D5; ORCH-036 (`adr-0007-executable-self-deploy.md` / + `self_deploy` ssh-механизм), ORCH-058 (`adr-0008-staging-image-provenance.md` / `image_freshness` + host-side docker), ORCH-110 (`adr-0042-merge-gate-retest-infra-tolerance-and-tree-kill.md` / proc_group + + infra-tolerance + classify), ORCH-101 (`adr-0036-replication-foundation-host-parametrization.md` / + host-параметризация) +- Сверено по коду: `src/staging_runner.py:154/415/487/528`, `src/self_deploy.py:220/287`, + `src/image_freshness.py:185/246`, `scripts/orchestrator-deploy-hook.sh:166/197`, + `src/proc_group.py`, `src/merge_gate.py:229`, `src/agents/launcher.py:406/438`, + `src/main.py:16/58/73`, `Dockerfile:11`, `docker-compose.yml` (docker.sock + ssh mounts), + `src/config.py:301-304/455-459` diff --git a/docs/work-items/ORCH-123/07-infra-requirements.md b/docs/work-items/ORCH-123/07-infra-requirements.md new file mode 100644 index 0000000..080857d --- /dev/null +++ b/docs/work-items/ORCH-123/07-infra-requirements.md @@ -0,0 +1,85 @@ +--- +work_item: ORCH-123 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# 07 — Инфра-требования: ORCH-123 — host-side исполнение staging-раннера + +Work Item: **ORCH-123** · Repo: **orchestrator** · Стадия: architecture + +> When-applicable. **Топология не меняется** (новых контейнеров/портов/томов/compose-правок нет). +> Файл фиксирует **границу исполнения** (BR-5/FR-6/AC-12) и **предусловия канала**, на которые +> раннер теперь опирается программно после фикса (раньше тот же `docker exec` исполнялся изнутри +> контейнера — и поэтому всегда падал в проде). + +## I-1. Граница исполнения docker-операций (нормативно — BR-5 / FR-6) + +**Прод-контейнер `orchestrator` (8500) НЕ содержит docker CLI.** `Dockerfile:11` ставит +`openssh-client git curl ca-certificates` (+ pinned gitleaks); `python:3.12-slim` docker не несёт. +`/var/run/docker.sock` **смонтирован** (`docker-compose.yml`, rw + `group_add 999`, ORCH-040 «МИНА 1»), +но **изнутри контейнера не используется** (нет клиента — сознательно, см. ADR-001 D2: добавление +клиента/SDK = активация root-эквивалентного пути для всего, что исполняется в контейнере). + +**Все docker-операции исполняются host-side через ssh на `127.0.0.1`** (доверенный канал, ключ +смонтирован `${ORCH_HOST_SSH_DIR}:…/.ssh:ro`, `openssh-client` в образе): + +| Операция | Компонент | Канал (host-side) | +|----------|-----------|-------------------| +| Прод-деплой (рестарт 8500) | `self_deploy.build_deploy_command` (ORCH-036) | `ssh + setsid bash --deploy` | +| Ребилд staging-образа из validated commit | `image_freshness.rebuild_staging_image` (ORCH-058) | `ssh … bash --build-staging` | +| Инспекция revision-label образа | `image_freshness.image_revision(ssh_target=…)` (ORCH-058) | `ssh … docker image inspect …` | +| **Staging-сюита на `deploy-staging`** | **`staging_runner.build_staging_command` (ORCH-123)** | **`ssh … docker exec orchestrator-staging python3 staging_check.py …`** | + +`scripts/staging_check.py` по-прежнему исполняется **внутри** `orchestrator-staging` (8501) — это +контракт сюиты (там python3 + приложение 8501, bind-mount `/repos/orchestrator/scripts/…`, ORCH-048). +**Меняется только инициатор `docker exec`** (host-side ssh вместо изнутри прод-контейнера), не сама +сюита и не её exit-код-контракт. + +## I-2. Предусловия канала исполнения + +Раннер после фикса программно опирается на (preflight их пробит на старте сервиса — ADR-001 D5): +- ssh-доступность `deploy_ssh_host` (`127.0.0.1`) под смонтированным ключом (та же, что использует + прод-деплой ORCH-036 / image-freshness ORCH-058 — уже в проде); +- наличие `docker` CLI **на хосте** (есть; контейнер его не несёт); +- поднятый и доступный staging-контейнер `orchestrator-staging` (8501) (Допущение А1 ORCH-115). + +Недоступность любого предусловия классифицируется **детерминированно** (ADR-001 D3): постоянный +дефект (`docker`/контейнер/ssh недоступны как класс) → `permanent-env` → **infra-HOLD + алерт** +(никогда тихий advance / ложный green / откат как код-фейл); транзиентная икота (timeout/ssh-255) → +bounded DEFER. + +## I-3. Переменные окружения / секреты + +**Новый env-ключ** (config, дефолт = боевое; добавить в `.env.example`): +- `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE` (`staging_runner_exec_host_side`, дефолт `True`) — выбор + стратегии исполнения. `True` → host-side ssh (фикс). `False` → прежний in-container `docker exec` + (валиден только там, где docker CLI запечён в образ). Откат фикса — без LLM-пути. + +**Переиспользуются (без изменений):** `ORCH_STAGING_RUNNER_ENABLED`/`_REPOS`/`_TIMEOUT_S`/ +`_INFRA_MAX_RETRIES`/`_INFRA_RETRY_DELAY_S` (ORCH-115); `ORCH_DEPLOY_SSH_USER`/`ORCH_DEPLOY_SSH_HOST`/ +`ORCH_DEPLOY_HOST_REPO_PATH` (ssh-канал ORCH-036); `ORCH_STAGING_PORT`/`ORCH_REPOS_DIR` (ORCH-101). +**Секретов не вводит** — переиспользует существующий смонтированный ssh-ключ; команда строится из +существующих host-параметров (анти-дрейф `tests/test_no_host_hardcodes.py`). + +## I-4. Деплой / рестарт (self-hosting инвариант, NFR-2 / AC-8) + +Раннер на `deploy-staging` **никогда** не рестартит прод-8500, не выполняет +`docker compose up orchestrator`/`--build` прода, не пушит force в `main`, не правит `.env`/ +`docker-compose.yml`/`Dockerfile` (BR-7 ORCH-115 / AC-8; структурный анти-литерал-тест на +ssh-обёрнутой команде — TC-08). Argv содержит только `ssh … docker exec orchestrator-staging python3 +staging_check.py … --mode stub`. ORCH-040 (смонтированный сокет) **не трогается и не расширяется**. +Прод-выкат самого ORCH-123 — штатно через staging-гейт (8501) → `Confirm Deploy` (ORCH-059); это +**docs/код+config**-изменение, активируется на следующем worktree от `main`, включается флагом +(дефолт `True`, обратимо двумя флагами — ADR-001 D6). + +## I-5. CI/CD + +**Без изменений `.gitea/workflows/`.** Новый/расширенный `tests/test_orch123_staging_runner_exec.py` +исполняется существующим `pytest tests/ -q` (моки subprocess/ssh-spawn и `advance_stage`; живой +Claude CLI / docker / ssh / сеть не требуются — окружение «нет docker CLI» моделируется монки-патчем +argv/spawn, `04-test-plan.yaml` notes). Существующие `tests/test_orch115_staging_runner.py` остаются +зелёными (TC-14). diff --git a/docs/work-items/ORCH-123/10-tech-risks.md b/docs/work-items/ORCH-123/10-tech-risks.md new file mode 100644 index 0000000..aab8556 --- /dev/null +++ b/docs/work-items/ORCH-123/10-tech-risks.md @@ -0,0 +1,93 @@ +--- +work_item: ORCH-123 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-16 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-123 — host-side исполнение staging-раннера + +Work Item: **ORCH-123** · Repo: **orchestrator** · Стадия: architecture + +Формат: риск → вероятность/влияние → митигация (привязка к решению ADR-001 / AC). + +--- + +## R-1 — Security: расширение поверхности атаки docker (NFR-3 / AC-9) +**Влияние:** критичное (root-эквивалент на общем хосте). **Вероятность (при выбранной стратегии):** +низкая. +Любой вариант с docker CLI/SDK **в контейнере** поверх смонтированного `docker.sock` (rw + group_add +999, ORCH-040) превращает дремлющую возможность в активный root-эквивалентный путь, доступный +worker-коду **и любому subprocess'у** (вкл. LLM-агентов). +**Митигация:** выбран **host-side ssh** (ADR-001 D1/D2) — docker-операции на хосте под существующим +доверенным key-gated каналом (ORCH-036/058), **без** docker CLI/SDK в контейнере и **без** расширения +использования сокета. ORCH-123 поверхность ORCH-040 не трогает. Любой будущий socket/CLI-в-контейнере +вариант — отдельный явный security-review. + +## R-2 — Реконсилятор/reaper откатывает infra-held задачу как код-фейл (FR-2 / AC-3 / AC-11) +**Влияние:** высокое (реинтродукция дефекта ORCH-123). **Вероятность:** средняя (зависит от +поведения reconciler ORCH-053 на застрявшем `deploy-staging`). +`permanent-env` / исчерпавшая-DEFER задача держится на `deploy-staging` (ADR-001 D4). Если reconciler/ +reaper трактует «застрял на deploy-staging без running-job» как повод откатить на `development` — +дефект вернётся. +**Митигация:** developer **обязан** верифицировать, что reconciler/reaper трактует infra-held +deploy-staging-задачу как **удержанную** (пере-выдать `deployer`-джоб для re-drive после починки +окружения), а **не** откатывает в `development`. Регресс-покрытие — поведенческий тест на «held не +становится rollback». Наблюдаемость (D8) делает held видимым (alert + `GET /queue` + лог). + +## R-3 — Over-tolerance: реальный код-фейл сюиты замаскирован как «инфра» (BR-3 / AC-4) +**Влияние:** высокое (сломанный код проходит staging-гейт). **Вероятность:** низкая. +Трёхсторонняя классификация (D3) может ошибочно отнести реальный `exit≠0` сюиты к +`permanent-env`/`transient-infra` (→ нет отката) при коллизии exit-кодов +(`docker exec` No such container = 1, и `staging_check` fail = 1). +**Митигация (D3):** дизамбигуация по **скану stderr на env-маркеры**, не по голому exit-коду: +распознанный suite-exit **без** env-маркера всегда `suite-ran` (никогда не реклассифицируется в +инфру — зеркало ORCH-110 BR-6). Fail-safe default при неоднозначности → `transient-infra` (DEFER), не +тихий проход. Маркер-сет покрыт TC-06; reviewer проверяет анти-over-tolerance (≥P1, как ORCH-110). + +## R-4 — Remote tree-kill: удалённое `docker exec`-дерево переживает таймаут (NFR-5) +**Влияние:** среднее (осиротевший pytest на хосте — класс ORCH-109/110). **Вероятность:** низкая. +`proc_group` tree-kill убивает **локальный** ssh-клиент при таймауте, но не гарантирует убийство +удалённого `docker exec`-дерева на хосте (процессы — дети docker-демона, не ssh-сессии). +**Митигация:** backstop — bounded таймаут внутри самой `staging_check.py`; это **то же** принятое +допущение, что у `image_freshness.rebuild_staging_image` (синхронный ssh без remote tree-kill). +Документируется как known-limitation (ADR-001 D-Последствия); не блокер. + +## R-5 — Held-задача клинит serial-gate репо (NFR-5 / AC-11) +**Влияние:** среднее (более поздние задачи репо ждут). **Вероятность:** средняя (при реальном +environment-сбое). +infra-HOLD держит задачу на `deploy-staging` → ORCH-088 serial-gate блокирует **более поздние** задачи +того же репо до снятия. +**Митигация:** принятый tradeoff (зеркало ORCH-110 infra-HOLD): environment-проблема, требующая +оператора, **должна** остановить репо, а не молча ложно-откатывать (что было бы хуже — порча +done-критериев + расход developer-retry). Скоуп **self-hosting only** (enduro не затронут). Громкий +alert «инфра, НЕ дефект кода» (D8) → быстрая операторская реакция; `GET /queue` показывает held. + +## R-6 — ssh-target не сконфигурирован / пустой `deploy_ssh_host` (FR-1 / D6) +**Влияние:** среднее. **Вероятность:** низкая (в проде `ORCH_DEPLOY_SSH_HOST=127.0.0.1` задан compose). +Config-дефолт `deploy_ssh_host=""`; на нестандартном хосте host-side стратегия без ssh-target +неработоспособна. +**Митигация:** пустой ssh-target → классификация `permanent-env` (D3) → infra-HOLD + alert (никогда +ложный откат); preflight на старте (D5) ловит это до реальной задачи. `applies(repo)` self-hosting-only +→ прочие репо не затронуты. + +## R-7 — Кросс-каттинг: правка маркированных блоков (CLAUDE.md §9 / ORCH-078) +**Влияние:** среднее. **Вероятность:** низкая. +Затрагиваются блоки с маркерами ORCH-115 (staging_runner, прямой объект), ORCH-036 (`self_deploy` +ssh), ORCH-058 (`image_freshness` host-side docker), ORCH-110 (`proc_group`/infra-tolerance/classify), +ORCH-101 (host-параметризация), ORCH-040 (docker.sock mount), ORCH-114 (transition-lease граница). +**Митигация:** developer **перед** изменением сверяет инварианты с их `06-adr/` (CLAUDE.md §9). Блок с +≥3 маркерами агрегируется **сводным сквозным ADR** `adr-0049` (ADR-001 Сквозная регистрация). Не +ломать: один транспорт LLM `_spawn` (`llm-usage-policy.md` §5), `STAGE_TRANSITIONS`/`QG_CHECKS`/ +machine-verdict (NFR-1), transition-lease берётся внутри `advance_stage` (граница O1), INV-4 (мерж +только через PR-merge, никогда push в `main`). + +## R-8 — Регрессия конвейера / гейта (NFR-1 / AC-7) +**Влияние:** критичное. **Вероятность:** очень низкая. +Случайное изменение `check_staging_status`/`_parse_staging_status`/`staging_status:`/`STAGE_TRANSITIONS`/ +схемы БД. +**Митигация:** фикс — замена **стратегии исполнения продюсера**, не гейта (зеркало ORCH-115 NFR-1). +Структурный анти-регресс-тест (TC-11) держит имена/семантику/ключи байт-в-байт; миграции БД нет +(restart-safe DEFER-счётчик — маркер в `task_content`, TRZ §5). Анти-дрейф ORCH-115 (TC-14) зелёный. From e1872e3d94e5527ab3876c673dcbe9a2c8d1177a Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 08:17:25 +0300 Subject: [PATCH 3/8] developer(ET): auto-commit from developer run_id=749 --- src/config.py | 17 +++++++++++++++++ src/staging_runner.py | 31 +++++++++++++++++++++++++++++-- 2 files changed, 46 insertions(+), 2 deletions(-) diff --git a/src/config.py b/src/config.py index 3db293d..5c7d9f8 100644 --- a/src/config.py +++ b/src/config.py @@ -452,11 +452,28 @@ class Settings(BaseSettings): # until the budget is exhausted (D5, anti ORCH-110). # staging_runner_infra_retry_delay_s-> delay before the re-queued deployer job # (env ORCH_STAGING_RUNNER_INFRA_RETRY_DELAY_S). + # ORCH-123 (D6, adr-0049): the staging suite (`docker exec orchestrator-staging + # ... staging_check.py`) MUST run host-side over the existing trusted ssh channel + # (ORCH-036/058), because the prod container ships only `openssh-client git curl` + # — NOT a `docker` CLI (Dockerfile:11) — so `docker exec` spawned FROM INSIDE the + # prod container hit FileNotFoundError -> a permanent environment defect that + # ORCH-115 mis-routed as a code-fail rollback (incident ORCH-116). The execution + # CHANNEL changes (host-side ssh wrap), the suite COMMAND/contract does not. + # staging_runner_exec_host_side -> True (default = boevoe) wraps the docker-exec + # in `ssh @ + # ''` (mirror self_deploy / + # image_freshness host-side docker). False -> + # the prior in-container `docker exec` (valid + # ONLY where a docker CLI is baked into the + # image; the current prod image has none). env + # ORCH_STAGING_RUNNER_EXEC_HOST_SIDE. Rollback: + # set False -> the prior in-container call 1:1. staging_runner_enabled: bool = True staging_runner_repos: str = "" staging_runner_timeout_s: int = 600 staging_runner_infra_max_retries: int = 2 staging_runner_infra_retry_delay_s: int = 30 + staging_runner_exec_host_side: bool = True # ORCH-098 (FND/F2): machine lessons-journal — additive `lessons` table + leaf # src/lessons.py (never-raise observer, by образцу serial_gate/coverage_gate/ diff --git a/src/staging_runner.py b/src/staging_runner.py index 296bc75..2b9f011 100644 --- a/src/staging_runner.py +++ b/src/staging_runner.py @@ -41,6 +41,8 @@ Two-level outcome (D5 — the key safety decision, anti ORCH-110): """ import logging +import shlex +import subprocess import time from .config import settings @@ -53,6 +55,25 @@ logger = logging.getLogger("orchestrator.staging_runner") # NOT a host hardcode (test_no_host_hardcodes forbids host IP/home/hostname only). STAGING_SERVICE = "orchestrator-staging" +# ORCH-123 (D3): deterministic stderr markers that prove a PERMANENT environment +# defect (no docker / container down / daemon unreachable) — NOT a transient infra +# hiccup and NEVER a code-fail. Scanned lower-cased; mirror of merge_gate's +# scope-guard marker approach. Recognised suite exit-codes WITHOUT any of these +# markers are always trusted as `suite-ran` (anti-over-tolerance, BR-3). +_ENV_MARKERS = ( + "command not found", + "executable file not found", + "no such container", + "is not running", + "cannot connect to the docker daemon", + "is the docker daemon running", +) + +# ORCH-123 (D5): last prod-like preflight verdict of the host-side staging channel +# (observed at startup; surfaced in snapshot()). `ok=None` -> not probed / n/a. +_PREFLIGHT_STATE: dict = {"ok": None, "reason": "not-probed"} +_PREFLIGHT_TIMEOUT_S = 20 + # Default wall-clock budget for the docker-exec staging suite (D9). Kept <= the LLM # staging window it replaces so Σ(work on the deploy-staging edge) does not grow and # the cross-cutting reaper invariant (ORCH-065/109/110) holds WITHOUT touching @@ -67,12 +88,18 @@ _GIT_TIMEOUT = 60 _INFRA_RETRY_MARKER = "staging-runner infra-retry" # In-process observability counters (mirror merge_gate._MERGE_GATE_COUNTERS, ORCH-110). +# ORCH-123 (D8): `failed` now counts ONLY a real code-fail (suite ran, exit != 0); +# `permanent_env` counts infra-HOLD events (a permanent environment defect, OR a +# transient-infra DEFER budget exhausted) so /queue distinguishes the THREE +# non-success classes: code-fail (`failed`) vs transient-infra (`deferred`) vs +# permanent-env / infra-HOLD (`permanent_env`). _STAGING_RUNNER_COUNTERS: dict = { "runs": 0, # run_staging_gate entered "success": 0, # suite ran, exit 0 -> SUCCESS - "failed": 0, # suite ran non-zero, OR infra budget exhausted -> FAILED + "failed": 0, # suite ran non-zero -> FAILED (a real code-fail) "tool_error": 0, # suite did NOT execute (spawn-error / timeout / None) - "deferred": 0, # bounded infra DEFER (re-queued) + "deferred": 0, # bounded transient-infra DEFER (re-queued) + "permanent_env": 0, # infra-HOLD: permanent env defect OR transient budget exhausted } From cc41dd849c37b8a8aae646e83e01ce438ca936bb Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 08:42:36 +0300 Subject: [PATCH 4/8] fix(staging): host-side ssh execution + env classification for staging-runner (ORCH-123) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ORCH-115 deterministic staging-runner ran `docker exec` FROM INSIDE the prod `orchestrator` container, which ships only `openssh-client git curl` — no `docker` CLI (Dockerfile:11). `Popen(["docker", ...])` hit FileNotFoundError -> a PERMANENT environment defect that was mis-routed as a code-fail rollback `deploy-staging -> development` (burning developer-retries). Incident ORCH-116: every self-hosting task reaching deploy-staging was doomed to a false rollback. Fix (adr-0049, additive, flag-gated, never-raise, self-hosting scope; the gate / artifact contract / STAGE_TRANSITIONS / DB schema are byte-for-byte unchanged): - D1: build_staging_command() wraps the SAME `docker exec ... staging_check.py ... --mode stub` in `ssh '<...>'` so it runs HOST-SIDE over the existing trusted ssh channel (mirror self_deploy / image_freshness). New flag staging_runner_exec_host_side (default True). No docker CLI/SDK added to the image, docker.sock not used in-container (D2 security). - D3: three-way classify_staging_outcome (suite-ran / permanent-env / transient-infra), disambiguating the exit=1 collision by scanning stderr. - D4: invariant "infra != code-fail" — permanent-env / exhausted transient-infra end in an infra-HOLD (no rollback, no developer-retry), NOT a false FAILED rollback (supersedes ORCH-115 D5). A really-executed failing suite still rolls back (anti-over-tolerance). R-2 verified: a held deploy-staging task is not rolled back by the reconciler. - D5: prod-like preflight() of the host-side channel at startup (main.lifespan, best-effort, never blocks). - D8: snapshot adds permanent_env / exec_host_side / preflight. Docs (golden source, same PR): INFRA.md execution-boundary section, architecture/README.md, CLAUDE.md, CHANGELOG.md, .env.example. Tests: tests/test_orch123_staging_runner_exec.py (TC-01 mandatory regression red->green; TC-02..TC-14 + R-2). ORCH-115 anti-drift green (3 tests updated for the D1/D4/D8 supersession). Full suite: 2131 passed. Refs: ORCH-123 Co-Authored-By: Claude Opus 4.8 --- .env.example | 11 +- CHANGELOG.md | 7 + CLAUDE.md | 36 ++ docs/architecture/README.md | 2 +- docs/operations/INFRA.md | 29 ++ src/main.py | 15 + src/staging_runner.py | 341 +++++++++++++-- tests/test_orch115_staging_runner.py | 25 +- tests/test_orch123_staging_runner_exec.py | 503 ++++++++++++++++++++++ 9 files changed, 917 insertions(+), 52 deletions(-) create mode 100644 tests/test_orch123_staging_runner_exec.py diff --git a/.env.example b/.env.example index b27f915..a4d4bb1 100644 --- a/.env.example +++ b/.env.example @@ -569,14 +569,21 @@ ORCH_COVERAGE_RUN_TIMEOUT_S=900 # STAGING_RUNNER_REPOS -> CSV scope; empty -> self-hosting only. # STAGING_RUNNER_TIMEOUT_S -> wall-clock budget for the docker-exec suite # (malformed/non-positive -> default 600 + WARNING). -# STAGING_RUNNER_INFRA_MAX_RETRIES -> tool-error (suite did NOT execute) bounded DEFER -# budget before a fail-closed FAILED (anti ORCH-110). +# STAGING_RUNNER_INFRA_MAX_RETRIES -> transient-infra (timeout/ssh) bounded DEFER +# budget before an infra-HOLD (anti ORCH-110). # STAGING_RUNNER_INFRA_RETRY_DELAY_S-> delay before the re-queued deployer job. +# STAGING_RUNNER_EXEC_HOST_SIDE -> ORCH-123 (adr-0049): true (default = prod) wraps +# the `docker exec` in `ssh '<...>'` so +# the suite runs HOST-SIDE (the prod container ships +# no docker CLI; incident ORCH-116). false -> the +# prior in-container `docker exec` (valid only where +# a docker CLI is baked into the image). Rollback knob. ORCH_STAGING_RUNNER_ENABLED=true ORCH_STAGING_RUNNER_REPOS= ORCH_STAGING_RUNNER_TIMEOUT_S=600 ORCH_STAGING_RUNNER_INFRA_MAX_RETRIES=2 ORCH_STAGING_RUNNER_INFRA_RETRY_DELAY_S=30 +ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=true # ORCH-057 (follow-up ORCH-040): legacy root-owned ownership detect + actionable # worktree error. After the uid migration (user: "1000:1000") legacy root:root files diff --git a/CHANGELOG.md b/CHANGELOG.md index 2902751..b64b721 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,13 @@ Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу. ## [Unreleased] +- **Host-side исполнение staging-раннера + классификация environment-дефекта** (ORCH-123, `fix`, bug→escalate full-cycle): устранён инцидент **ORCH-116** — детерминированный staging-раннер (ORCH-115) вызывал `docker exec` **изнутри** прод-контейнера `orchestrator`, где **нет бинаря `docker`** (образ несёт только `openssh-client git curl`, `Dockerfile:11`; `/var/run/docker.sock` смонтирован, но клиента нет) → `Popen(["docker", …])` падал `FileNotFoundError` → ветка tool-error → инфра-DEFER×2 → fail-closed `FAILED` → **ложный** откат `deploy-staging → development` (как код-фейл, с расходом developer-retry). Так до фикса **любая** self-hosting задача, дойдя до `deploy-staging`, была обречена на ложный откат. Аддитивно, под флагами, never-raise, скоуп self-hosting; `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / семантика и имена `check_staging_status`/`_parse_staging_status` / machine-verdict-ключи (`staging_status:`/`deploy_status:`) / схема БД — **байт-в-байт не тронуты** (замена *стратегии исполнения продюсера* `15-staging-log.md`, **не** гейта/стадии; зеркало инварианта ORCH-115 NFR-1). ADR: `docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md`, сквозной `docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md`. + - **Host-side ssh-стратегия (D1):** `staging_runner.build_staging_command()` теперь обёртывает ту же `docker exec orchestrator-staging python3 … staging_check.py … --mode stub` в `ssh -o StrictHostKeyChecking=no @ ''` (зеркало `self_deploy.build_deploy_command` / `image_freshness.image_revision(ssh_target=…)`); канал — существующий доверенный (`ORCH_DEPLOY_SSH_HOST=127.0.0.1`, ssh-ключ смонтирован `:ro`, `openssh-client` в образе) → **новых секретов/привилегий не вводится** (NFR-3). Меняется **инициатор/канал** запуска, **не** сама сюита (она по-прежнему бежит **внутри** `orchestrator-staging` 8501). **Security (D2):** docker CLI/SDK в контейнер **не добавляется**, `docker.sock` **не используется изнутри** — это было бы root-эквивалентным расширением поверхности атаки (доступным и LLM-агентам); host-side ssh достигает цели без расширения привилегий. + - **Трёхсторонняя классификация исхода (D3, чистая `classify_staging_outcome`, зеркало `merge_gate.classify_retest_failure`):** `suite-ran` (распознанный exit-код, кроме 255, **без** env-маркера в stderr → доверяем коду: `0→SUCCESS`/`≠0→FAILED`; анти-over-tolerance BR-3 — реальный фейл сюиты **никогда** не реклассифицируется в инфру), `permanent-env` (spawn-error `rc=None` без таймаута / нет ssh-target / `rc∈{126,127}` / env-маркер `No such container`/`Cannot connect to the Docker daemon`/`command not found` → ретрай бессмыслен), `transient-infra` (timeout / ssh transport `rc=255` / неизвестный сигнал → ретрай осмыслен). Дизамбигуация коллизии `exit=1` (`docker exec` «No such container»=1 vs суита fail=1) — **скан stderr на env-маркеры**, не голый exit-код; fail-safe при неоднозначности → `transient-infra` (DEFER), никогда тихий `suite-ran`. + - **Маршрутизация исходов (D4) — инвариант «инфра ≠ код-фейл»:** `suite-ran` → **без изменений** (ORCH-115): write `15-staging-log.md` + `advance_stage` (FAILED → прежний откат `deploy-staging → development` + developer-retry, байт-в-байт). `permanent-env` → **немедленный infra-HOLD**: DEFER пропускается (FR-3), `15-staging-log.md` **не** пишется (нет ложного FAILED), `advance` **не** зовётся, developer-retry **не** жжётся; структурный ERROR + операторский alert «инфра/окружение, НЕ дефект кода». `transient-infra` → существующий bounded DEFER, **но на исчерпании бюджета** — тоже **infra-HOLD + alert** (СУПЕРСЕД ORCH-115 D5: прежний fail-closed `write_staging_log("FAILED") + advance` ложно откатывал не-прояснившуюся инфру как код-фейл, нарушая BR-2). Корневой инвариант: «сюита **не** исполнилась» (environment ИЛИ инфра) **никогда** не оканчивается код-фейл-откатом `→ development` и **никогда** не жжёт developer-retry — закрывает RCA-класс ORCH-110 на staging-ребре. Задача **держится** на `deploy-staging`; reconciler `advance_if_gate_passed` на red-гейте возвращает `None` (без отката, R-2 верифицирован) → оператор re-drive после починки окружения. + - **Prod-like preflight (D5):** `staging_runner.preflight()` (bounded, never-raise, self-hosting-скоуп — `applies()` первым) пробит host-side канал на **старте сервиса** в `main.lifespan` (best-effort, после `requeue_running_jobs`/`recover_on_startup`, **никогда не блокирует старт**): ssh-зонд `command -v docker && docker inspect -f '{{.State.Running}}' orchestrator-staging` распознаёт «нет docker на хосте» / «staging-контейнер не поднят» / «ssh недоступен» / «нет ssh-target» **до** того, как реальная задача дойдёт до ложного исхода. Чисто наблюдательный — не гейтит конвейер; лог + Telegram-алерт + поле в `snapshot()`. + - **Условность / обратимость (D6):** новый флаг `staging_runner_exec_host_side: bool = True` (env `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE`, дефолт = боевое) — `True` → host-side ssh; `False` → прежний in-container `docker exec` (валиден лишь там, где docker CLI запечён в образ). Переиспользуются `staging_runner_enabled`/`_repos`/`_timeout_s`/`_infra_max_retries`/`_retry_delay_s` + `deploy_ssh_user`/`deploy_ssh_host`. Откат — `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=false` (in-container 1:1) или `ORCH_STAGING_RUNNER_ENABLED=false` (LLM-deployer 1:1). Наблюдаемость (D8): счётчик `permanent_env` (infra-HOLD; отличён от `failed`=код-фейл и `deferred`=транзиент) + `exec_host_side` + `preflight` в блоке `staging_runner` `GET /queue`; один структурный лог-вердикт на прогон (`outcome ∈ {code-pass,code-fail,transient-infra,permanent-env}`). + - **Документация границы исполнения (D9):** `docs/operations/INFRA.md` (новый под-раздел «Граница исполнения docker-операций — host-side») + `docs/architecture/README.md` (host-side стратегия + трёхсторонняя классификация) — зафиксировано, что **все** docker-операции self-hosting (прод-деплой ORCH-036, image-freshness ORCH-058, staging-runner ORCH-123) исполняются host-side через ssh, docker CLI в контейнере нет, `docker.sock` сознательно не используется изнутри. Покрытие — `tests/test_orch123_staging_runner_exec.py` (TC-01 — обязательный регресс ORCH-116: КРАСНЫЙ до фикса / ЗЕЛЁНЫЙ после; TC-02…TC-14 + регресс R-2 «held не становится rollback») + зелёный анти-дрейф `tests/test_orch115_staging_runner.py` (TC-14: инварианты ORCH-115 целы; 3 теста обновлены под суперсед D4/D8/D1). - **Детерминированный staging-раннер вместо LLM-деплойера на `deploy-staging`** (ORCH-115, `feat`): первый реализованный срез determinization-roadmap (ORCH-118 A6, `replace-deterministic-now`) — на стадии `deploy-staging` для self-hosting `orchestrator` **LLM-агент `deployer` заменён детерминированным кодом** (`src/staging_runner.py`). Работа агента на этой стадии была чисто механической (запуск staging-сюиты + маппинг exit-кода `staging_check.py` → `staging_status:`); каждый прогон жёг токены/время opus-агента (~40–120k / 3–15 мин) и встраивал недетерминизм LLM в точку ветвления гейта. **Инвариант (NFR-1):** это замена *продюсера* артефакта, **не** гейта — контракт `15-staging-log.md`, гейт `check_staging_status`/`_parse_staging_status`, `STAGE_TRANSITIONS`, machine-verdict `staging_status:`, схема БД — **байт-в-байт не тронуты**. Аддитивно, под kill-switch, never-raise, fail-closed, скоуп self-hosting. ADR: `docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md`, сквозной `docs/architecture/adr/adr-0048-deterministic-staging-runner.md`. - **Перехват в `launch_job` до `_spawn` (D1):** `if job.agent=="deployer" and staging_runner.should_intercept(job)` → `_run_staging_runner_job` (зеркало `_run_deploy_finalizer_job`, прецедент `deploy-finalizer`/`post-deploy-monitor` `launcher.py:389/394`): синхронно ведёт `jobs`-строку через `mark_job`, возвращает `None` (нет `agent_runs`-строки, нет токенов). Дискриминатор «staging vs prod» — **стадия задачи** `deploy-staging` (роль `deployer` общая для `deploy-staging`/`deploy`), не имя роли; `should_intercept` never-raise → `False` → штатный `_spawn` (fail-safe к LLM-пути). Для не-self репо `applies==False` → прод-`deployer` никогда не перехватывается. - **Leaf `src/staging_runner.py` (новый, чистый never-raise):** по образцу `self_deploy`/`proc_group`/`staging_verdict` (на импорте только `config`/`proc_group`; `db`/`git_worktree`/`stage_engine`/`qg.checks`/`notifications` — лениво). Исполняет ту же сюиту (`docker exec orchestrator-staging python3 //scripts/staging_check.py --base-url http://localhost: --mode stub`, арги из config — ORCH-101, без host-хардкодов) через `proc_group.run_in_process_group` (tree-kill, таймаут `staging_runner_timeout_s=600`, малформ/непозитив → дефолт + WARNING); маппит exit-код **единым** контрактом `self_deploy.map_exit_code_to_status` (`0→SUCCESS`/иначе/None→`FAILED`, fail-closed; ORCH-061 infra-tolerance остаётся внутри `staging_check.py`, раннер не пересуживает — BR-4); пишет `15-staging-log.md` (тот же machine-key `staging_status:` UPPERCASE + 52c-схема, `author_agent: staging-runner`/`model_used: n/a`) + best-effort commit/push в **фичеветку** (не в `main` — гейт читает worktree первым, усиливает AC-8/BR-7); вызывает **существующий** `advance_stage(current_stage="deploy-staging", finished_agent="deployer")` — без новых рёбер/исходов (transition-lease ORCH-114 берётся внутри `advance_stage`, раннер не трогает — граница O1). diff --git a/CLAUDE.md b/CLAUDE.md index 2d5ac85..62b1fde 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -456,6 +456,42 @@ Plane, **не** Quality Gate и **не** стадия). `tests/test_orch115_staging_runner.py` (TC-01…TC-13) + зелёные LLM-анти-дрейф тесты (TC-14). Детали — `docs/work-items/ORCH-115/06-adr/ADR-001-deterministic-staging-runner.md`, сквозной `docs/architecture/adr/adr-0048-deterministic-staging-runner.md`. +- **ORCH-123 (host-side исполнение + классификация environment-дефекта, bug→escalate full-cycle, + adr-0049):** фикс инцидента **ORCH-116** — раннер ORCH-115 вызывал `docker exec` **изнутри** + прод-контейнера, где **нет docker CLI** (`Dockerfile:11` несёт только `openssh-client git curl`; + `docker.sock` смонтирован, клиента нет) → `FileNotFoundError` → постоянный environment-дефект + ложно маршрутизировался как код-фейл-откат `deploy-staging → development` (с расходом + developer-retry); любая self-hosting задача на `deploy-staging` была обречена. Аддитивно, под + флагами, never-raise, скоуп self-hosting; `STAGE_TRANSITIONS`/реестр `QG_CHECKS`/семантика и имена + `check_staging_status`/`_parse_staging_status`/machine-verdict-ключи/схема БД — **байт-в-байт не + тронуты** (замена *стратегии исполнения продюсера*, **не** гейта; зеркало ORCH-115 NFR-1). + **(D1)** `build_staging_command` обёртывает ту же `docker exec orchestrator-staging … staging_check.py + … --mode stub` в `ssh -o StrictHostKeyChecking=no @ '<…>'` + (зеркало `self_deploy`/`image_freshness`; канал доверенный `ORCH_DEPLOY_SSH_HOST=127.0.0.1`, + ssh-ключ `:ro`, `openssh-client` в образе — новых секретов/привилегий нет; сюита по-прежнему бежит + **внутри** `orchestrator-staging` 8501, меняется лишь инициатор `docker exec`). **(D2 security)** + docker CLI/SDK в контейнер **не** добавляется, `docker.sock` **не** используется изнутри (это + root-эквивалентное расширение поверхности атаки, доступное и LLM-агентам). **(D3)** двухуровневый + исход ORCH-115 заменён **трёхсторонней** чистой `classify_staging_outcome` (зеркало + `merge_gate.classify_retest_failure`): `suite-ran` (распознанный exit-код ≠255 **без** env-маркера в + stderr → доверяем коду `0→SUCCESS`/`≠0→FAILED`; анти-over-tolerance BR-3), `permanent-env` + (spawn-error `rc=None`/нет ssh-target/`rc∈{126,127}`/env-маркер `No such container`/`Cannot connect + to the Docker daemon` → ретрай бессмыслен), `transient-infra` (timeout/ssh `rc=255`/неизвестно → + ретрай осмыслен); дизамбигуация `exit=1`-коллизии — скан stderr на env-маркеры, не голый код; + fail-safe → `transient-infra`. **(D4 инвариант «инфра ≠ код-фейл»)** `permanent-env` → немедленный + **infra-HOLD** (DEFER пропускается, `15-staging-log.md` НЕ пишется, advance НЕ зовётся, developer-retry + НЕ жжётся, alert «НЕ дефект кода»); `transient-infra` → bounded DEFER, на исчерпании — тоже + infra-HOLD+alert (**супершид ORCH-115 D5** fail-closed-FAILED-отката). «Сюита **не** исполнилась» + (env ИЛИ инфра) **никогда** не оканчивается код-фейл-откатом — закрывает RCA-класс ORCH-110 на + staging-ребре; задача держится на `deploy-staging` (reconciler `advance_if_gate_passed` на red-гейте + → `None`, без отката, R-2). **(D5)** `preflight()` пробит host-side канал на старте `main.lifespan` + (best-effort, never-blocks). **(D6)** новый флаг `staging_runner_exec_host_side=True` + (env `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE`); откат — `=false` (in-container 1:1) или + `ORCH_STAGING_RUNNER_ENABLED=false` (LLM-deployer 1:1). **(D8)** счётчик `permanent_env` + `exec_host_side` + + `preflight` в блоке `staging_runner` `GET /queue`. Покрытие — `tests/test_orch123_staging_runner_exec.py` + (TC-01 обязательный регресс ORCH-116 red→green; TC-02…TC-14 + R-2) + зелёный анти-дрейф ORCH-115. + Детали — `docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.md`, + сквозной `docs/architecture/adr/adr-0049-host-side-docker-execution-boundary.md`. ## Машинный журнал уроков (ORCH-098) Шаг 1 («Фундамент», F2) эпика саморазвития: формализует свободнотекстовые «уроки» из `memory/` в diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 32e54ba..d52f5b9 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -10,7 +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`. +- **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`. **ORCH-123 (фикс стратегии исполнения — [adr-0049](adr/adr-0049-host-side-docker-execution-boundary.md)):** раннер ORCH-115 вызывал `docker exec` **изнутри** прод-контейнера, где **нет docker CLI** (образ несёт только `openssh-client git curl`, `Dockerfile:11`) → `FileNotFoundError` → постоянный environment-дефект ложно откатывался как код-фейл `deploy-staging → development` (инцидент ORCH-116). Фикс: `build_staging_command` теперь исполняет ту же `docker exec … staging_check.py … --mode stub` **host-side** через доверенный ssh-канал `ssh ''` (зеркало `self_deploy`/`image_freshness`, флаг `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=true`, дефолт; меняется **инициатор/канал**, не сама сюита — она по-прежнему бежит внутри `orchestrator-staging` 8501). Двухуровневый исход ORCH-115 заменён **трёхсторонней классификацией** (`classify_staging_outcome`): `suite-ran` (распознанный exit-код без env-маркера в stderr → доверяем коду: `0→SUCCESS`/`≠0→FAILED`+прежний откат, анти-over-tolerance), `permanent-env` (spawn-error/нет ssh-target/126-127/env-маркер `No such container`/`Cannot connect to the Docker daemon` → **немедленный infra-HOLD**: без отката, без developer-retry, DEFER пропускается), `transient-infra` (timeout/ssh 255 → bounded DEFER, на исчерпании → infra-HOLD, **не** прежний fail-closed FAILED+откат). Корневой инвариант: «сюита **не** исполнилась» (environment ИЛИ инфра) **никогда** не оканчивается код-фейл-откатом — закрывает RCA-класс ORCH-110 на staging-ребре. Plus prod-like preflight host-side канала в `main.lifespan` (best-effort, never-blocks). `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_staging_status`/machine-verdict/схема БД — байт-в-байт не тронуты. Детали — `docs/work-items/ORCH-123/06-adr/ADR-001-host-side-staging-execution-and-env-classification.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`. diff --git a/docs/operations/INFRA.md b/docs/operations/INFRA.md index c0efd19..eed9c3d 100644 --- a/docs/operations/INFRA.md +++ b/docs/operations/INFRA.md @@ -244,10 +244,39 @@ watchdog'а: **watchdog сигналит, pruner убирает**. - **Свежесть staging-образа (ORCH-058):** на ребре `deploy-staging → deploy` (ПОСЛЕ merge-gate, ДО Phase A) QG-под-чек `check_staging_image_fresh` пересобирает staging-образ из валидированного коммита и пересоздаёт 8501 (Strategy A), а хук перед build-once retag fail-closed сверяет OCI-лейбл `revision` с `EXPECTED_REVISION` (Strategy B). Гарантирует: в прод промоутится РОВНО провалидированный артефакт (инцидент LESSONS_ORCH-036 п.4 — тихий промоут устаревшего образа). Сборки/recreate — ТОЛЬКО staging (8501); FAIL → откат на `development`. Условный: реален только для self-hosting. - **Гигиена shared deploy-базы (ORCH-112):** self-deploy `git pull origin main` устойчив к грязному рабочему дереву deploy-базы (модифицированные tracked + untracked-остатки failed/cancelled/брошенных задач). Хук `--deploy` перед pull приводит базу к чистому `origin/main` (resilient-pull: `git fetch` + `git reset --hard origin/main` + `git clean -fd`), **строго сохраняя** rollback-снимки `.deploy-prev-image-*`, `deploy-hook.log`, gitignored `.env`/`data/`/`*.db` (НИКОГДА `-x`!), sibling `.deploy-state-*`/`.merge-lease-*.json`, `.git/worktrees/*`. Гейт — kill-switch `ORCH_CHECKOUT_HYGIENE_ENABLED` (дефолт `True`; off → голый pull 1:1); скоуп `ORCH_CHECKOUT_HYGIENE_REPOS` (пусто → self-hosting only). Грязь базы детектируется → лог + Telegram-алерт (Phase-C finalizer). Решает инцидент ORCH-111 (грязь ORCH-104 заблокировала `git pull`). Детально — `docs/work-items/ORCH-112/06-adr/ADR-001`, сквозной adr-0044. +### Граница исполнения docker-операций — host-side, НЕ изнутри прод-контейнера (ORCH-123) + +**Инвариант (нормативно, adr-0049):** прод-контейнер `orchestrator` несёт **только** +`openssh-client git curl` (+ pinned gitleaks) — **бинаря `docker` в образе НЕТ** (`Dockerfile:11`, +`python:3.12-slim` его не несёт). `/var/run/docker.sock` **смонтирован** (`docker-compose.yml`, +rw + `group_add 999`, «МИНА 1» ORCH-040), но **сознательно НЕ используется изнутри** контейнера: нет +docker-клиента, и добавлять его (CLI/SDK) **нельзя** — это активировало бы дремлющий +root-эквивалентный путь для всего, что бежит в контейнере, включая LLM-агентов (security-разбор — +ADR-001 D2 / adr-0049 / R-1). + +Поэтому **все** docker-операции self-hosting исполняются **host-side** через **ssh на `127.0.0.1`** +(`ORCH_DEPLOY_SSH_HOST`/`ORCH_DEPLOY_SSH_USER`, ssh-ключ смонтирован `:ro`), где docker CLI есть: +- **прод-деплой** (ORCH-036, `self_deploy.build_deploy_command`) — `ssh … setsid bash hook --deploy`; +- **image-freshness** (ORCH-058, `image_freshness.image_revision`/`rebuild_staging_image`) — `ssh … docker …`; +- **staging-runner** (ORCH-123, `staging_runner.build_staging_command`) — `ssh … docker exec orchestrator-staging python3 … staging_check.py … --mode stub`. + +Сама staging-сюита (`scripts/staging_check.py`) **по-прежнему** исполняется **внутри** контейнера +`orchestrator-staging` (8501) — меняется лишь **кто инициирует** `docker exec` (хост через ssh, а не +прод-контейнер). До ORCH-123 staging-runner (ORCH-115) вызывал `docker exec` **изнутри** +прод-контейнера → `FileNotFoundError` (нет `docker`) → постоянный environment-дефект ложно +маршрутизировался как код-фейл-откат `deploy-staging → development` (инцидент ORCH-116). Фикс: +host-side ssh-обёртка (флаг `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=true`, дефолт) + трёхсторонняя +классификация (suite-ran / permanent-env / transient-infra), где environment/инфра **никогда** не +оканчивается код-фейл-откатом (infra-HOLD + алерт «инфра, НЕ дефект кода»), и prod-like preflight +канала на старте сервиса. Откат — `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=false` (прежний in-container +вызов — валиден лишь там, где docker CLI запечён в образ) или `ORCH_STAGING_RUNNER_ENABLED=false` +(LLM-deployer 1:1). Детали — `docs/work-items/ORCH-123/06-adr/ADR-001`, сквозной adr-0049. + **Правила для агентов при задачах ORCH:** 1. НЕ перезапускать / не ронять прод-контейнер `orchestrator` в рамках задачи. 2. Все проверки деплоя — на staging (8501), боевой 8500 не трогать. 3. Деплой self — только через хук с health-check + авто-rollback (`DEPLOY_HOOK.md`). +4. docker-операции исполняются **host-side через ssh** — в контейнере `docker` CLI нет (ORCH-123). ## Эксплуатация (быстрые команды) ```bash diff --git a/src/main.py b/src/main.py index 3877bbd..9655e91 100644 --- a/src/main.py +++ b/src/main.py @@ -79,6 +79,21 @@ async def lifespan(app: FastAPI): except Exception as e: log.warning(f"Transition-lease recovery skipped: {e}") + # ORCH-123 (adr-0049 / D5 / FR-4): prod-like preflight of the host-side staging + # execution channel. The deploy-staging staging-runner (ORCH-115) runs the suite + # HOST-SIDE over ssh because the prod container ships no docker CLI (Dockerfile:11); + # probe the channel at startup so a broken environment (no docker on host / staging + # down / ssh unreachable / no ssh target) surfaces HERE — not postfactum as a false + # rollback of a real task (incident ORCH-116). Purely observational: it never blocks + # the start / gates the pipeline. never raises (runs after requeue + lease-recovery). + try: + from . import staging_runner + ok, reason = staging_runner.preflight() + if not ok: + log.warning(f"Staging-runner preflight: {reason}") + except Exception as e: + log.warning(f"Staging-runner preflight skipped: {e}") + # ORCH-065: proactive startup reclaim of dead/stale merge-leases, next to the # queue-recovery above. A lease held by the previous (now dead) process pid is # released at once instead of waiting for the TTL / a foreign acquire so the diff --git a/src/staging_runner.py b/src/staging_runner.py index 2b9f011..a4c1fce 100644 --- a/src/staging_runner.py +++ b/src/staging_runner.py @@ -178,26 +178,74 @@ def should_intercept(job: dict) -> bool: # --------------------------------------------------------------------------- # Suite execution (D3 / FR-2 / NFR-3 / AC-8 / AC-9) # --------------------------------------------------------------------------- -def build_staging_command() -> list[str]: - """Build the canonical staging-suite argv (same command the LLM-deployer ran). +def _ssh_target() -> str: + """ssh ``user@host`` for host-side execution, or ``""`` when no host is + configured (mirror ``self_deploy``/``image_freshness._ssh_target``). On the prod + host ``ORCH_DEPLOY_SSH_HOST=127.0.0.1`` is set by compose; the config default is + empty so tests / non-self contexts fall back to the in-container command.""" + host = (settings.deploy_ssh_host or "").strip() + if not host: + return "" + user = (settings.deploy_ssh_user or "").strip() + return f"{user}@{host}" if user else host - ``docker exec python3 //scripts/staging_check.py - --base-url http://localhost: --mode stub``. Host-specifics come from - config (ORCH-101, no host hardcodes). Self-hosting safety (BR-7 / AC-8 / TC-12): - NO restart of 8500, NO ``docker compose up orchestrator`` / ``--build``, NO - force-push, NO ``.env`` edit — the runner only reads/executes the staging suite - (8501) and writes a log. + +def _channel_ssh_configured() -> bool: + """Whether the execution channel is viable w.r.t. ssh config (fed to + ``classify_staging_outcome``). In-container mode (host-side disabled) is always + 'configured' — its viability is decided purely by the result signals; host-side + mode needs a non-empty ssh target (R-6: an empty target -> ``permanent-env``). + never-raise -> assume configured (rely on the result signals).""" + try: + if not bool(getattr(settings, "staging_runner_exec_host_side", True)): + return True + return bool(_ssh_target()) + except Exception: # noqa: BLE001 - never-raise + return True + + +def build_staging_command() -> list[str]: + """Build the staging-suite argv (same suite command the LLM-deployer ran). + + The INNER command is unchanged: ``docker exec python3 + //scripts/staging_check.py --base-url + http://localhost: --mode stub``. Host-specifics come from config + (ORCH-101, no host hardcodes). + + ORCH-123 (D1, adr-0049): ``docker`` lives on the HOST — the prod container ships + only ``openssh-client git curl`` (``Dockerfile:11``), so a ``docker exec`` spawned + FROM INSIDE the prod container hit ``FileNotFoundError`` (incident ORCH-116). When + ``staging_runner_exec_host_side`` (default True) is set AND an ssh target is + configured, the inner command is wrapped in ``ssh ''`` + so it runs host-side over the existing trusted ssh channel (mirror + ``self_deploy.build_deploy_command`` / ``image_freshness.image_revision``). With + the flag off OR no ssh target configured (tests / non-self contexts) it falls back + to the prior in-container ``docker exec`` (valid only where a docker CLI is baked + into the image). + + Self-hosting safety (BR-7 / AC-8 / TC-08): the argv carries ONLY ``docker exec + python3 staging_check.py ... --mode stub`` — NO restart of 8500, + NO ``docker compose up orchestrator`` / ``--build``, NO force-push, NO ``.env`` + edit. The runner only reads/executes the staging suite (8501) and writes a log. """ from .qg.checks import SELF_HOSTING_REPO repos_dir = (settings.repos_dir or "/repos").rstrip("/") script = f"{repos_dir}/{SELF_HOSTING_REPO}/scripts/staging_check.py" base_url = f"http://localhost:{int(settings.staging_port)}" - return [ + inner_argv = [ "docker", "exec", STAGING_SERVICE, "python3", script, "--base-url", base_url, "--mode", "stub", ] + # ORCH-123 (D1): host-side ssh-wrap when enabled AND a target is configured. + if bool(getattr(settings, "staging_runner_exec_host_side", True)): + target = _ssh_target() + if target: + remote = " ".join(shlex.quote(a) for a in inner_argv) + return ["ssh", "-o", "StrictHostKeyChecking=no", target, remote] + # Fallback: prior in-container docker exec (no ssh target / flag off). + return inner_argv def _resolve_timeout() -> int: @@ -255,6 +303,71 @@ def map_exit_code_to_status(exit_code) -> str: return _map(exit_code) +# --------------------------------------------------------------------------- +# Three-way outcome classification (D3 / FR-2 / FR-3 / AC-3, AC-4, AC-6) +# --------------------------------------------------------------------------- +def classify_staging_outcome(result, ssh_configured: bool) -> str: + """Classify a staging-suite ProcResult into one of three classes (D3). Pure, + never-raise (mirror of ``merge_gate.classify_retest_failure``, ORCH-110 D2): + + * ``"suite-ran"`` — a recognised executor exit-code (any int except the + ssh transport code 255) AND no environment marker in + stderr: the suite DEMONSTRABLY executed -> trust the + code (``0->SUCCESS``, ``!=0->FAILED``). Anti-over- + tolerance (BR-3): a real suite fail is NEVER + reclassified as infra/env. + * ``"permanent-env"`` — a deterministic PERMANENT environment defect: an + stderr env-marker (no docker / no such container / + daemon unreachable), a shell "command not found / + cannot execute" code (126/127), no host-side ssh + target configured, or a bare local spawn-error + (``returncode is None`` and not a timeout). Retrying is + pointless (FR-3) -> immediate distinguishable + infra-HOLD (no rollback, no developer-retry). + * ``"transient-infra"`` — a timeout OR an ssh transport/connection failure (255) + OR any unknown signal: a retry is meaningful -> the + bounded DEFER. + + The exit=1 collision (``docker exec`` "No such container"=1 vs a real suite fail=1) + is disambiguated by SCANNING stderr for env-markers, NEVER by the bare exit-code. + Fail-safe on doubt -> ``"transient-infra"`` (DEFER), never a silent ``"suite-ran"`` + (a mis-routed environment->code-fail is exactly the defect this fixes; an over- + tolerated code-fail is guarded by trusting recognised suite exit-codes first). + """ + try: + rc = getattr(result, "returncode", None) + timed_out = bool(getattr(result, "timed_out", False)) + stderr = (getattr(result, "stderr", "") or "").lower() + + # 1. env-marker in stderr -> permanent, REGARDLESS of the exit-code (this is + # what disambiguates a `docker exec` "No such container" exit=1 from a real + # suite fail=1 — R-3). + if any(m in stderr for m in _ENV_MARKERS): + return "permanent-env" + # 2. shell "command not found" (127) / "cannot execute" (126) -> permanent. + if rc in (126, 127): + return "permanent-env" + # 3. a recognised executor exit-code (any int except the ssh transport code + # 255) WITHOUT an env-marker -> the suite executed; trust it (BR-3). This is + # checked BEFORE the channel guards so a real suite fail is never masked. + if isinstance(rc, int) and rc != 255: + return "suite-ran" + # --- below this line the suite did NOT produce a trustworthy exit-code --- + # 4. timeout / ssh transport failure (255) -> transient: a retry is meaningful. + if timed_out or rc == 255: + return "transient-infra" + # 5. host-side ssh target missing (R-6) OR a bare local spawn-error (proc_group + # degraded an OSError to rc None without a timeout) -> permanent env defect. + if not ssh_configured: + return "permanent-env" + if rc is None: + return "permanent-env" + # 6. unknown signal -> fail-safe DEFER (never a silent suite-ran). + return "transient-infra" + except Exception: # noqa: BLE001 - never-raise; unknown -> transient (no false rollback) + return "transient-infra" + + # --------------------------------------------------------------------------- # Artifact 15-staging-log.md (D6 / FR-4 / AC-2 / AC-8) — mirror write_deploy_log # --------------------------------------------------------------------------- @@ -439,17 +552,21 @@ def _infra_retry_count(task_id) -> int: return 0 -def _handle_tool_error( +def _handle_transient_infra( task_id, repo: str, work_item_id: str, branch: str, result: proc_group.ProcResult ) -> None: - """Suite did NOT execute (tool-error) -> bounded DEFER, then fail-closed (D5). + """Transient infra (timeout / ssh transport) — the suite did not execute but a + retry is meaningful (D4). Bounded DEFER: re-queue a fresh ``deployer`` job (which + re-enters this runner) with a delay + a restart-safe marker, instead of an + immediate rollback that would burn a developer-retry. - Anti ORCH-110: an infra fault is NOT a code fault, so we re-queue a fresh - ``deployer`` job (which re-enters this runner) with a delay instead of an - immediate FAILED-rollback that would burn a developer-retry. On budget exhaustion - -> write ``staging_status: FAILED`` + advance (the existing rollback) + an - INFRA-specific alert (explicitly "not a code defect"). Never a silent advance / - false green; never wedges the queue. never-raise.""" + On budget exhaustion -> **infra-HOLD + alert** (D4, SUPERSEDES ORCH-115 D5): NOT + the prior fail-closed ``write_staging_log("FAILED") + advance``, which falsely + rolled an unresolved infra hiccup back to ``development`` as a code-fail (BR-2, + anti-pattern ORCH-110). The task is HELD on ``deploy-staging`` (a red/missing gate + keeps the reconciler's ``advance_if_gate_passed`` from rolling it back — R-2); the + operator re-drives it after fixing the stand. Never a silent advance / false green; + never wedges the queue. never-raise.""" retries = _infra_retry_count(task_id) try: max_retries = int(settings.staging_runner_infra_max_retries) @@ -462,7 +579,7 @@ def _handle_tool_error( if retries < max_retries: _bump("deferred") - reason = "timeout" if result.timed_out else "suite did not execute (tool-error)" + reason = "timeout" if result.timed_out else "ssh transport/connection error" task_desc = ( f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n" f"Stage: deploy-staging\nNote: {_INFRA_RETRY_MARKER} " @@ -474,40 +591,77 @@ def _handle_tool_error( "deployer", repo, task_desc, task_id=task_id, available_at_delay_s=delay, ) logger.warning( - "Task %s (%s): staging suite did not execute (%s) -> infra-DEFER " - "(job_id=%s, attempt %d/%d)", + "Task %s (%s): staging suite did not execute (%s) -> transient-infra " + "DEFER (job_id=%s, attempt %d/%d)", task_id, work_item_id, reason, new_job, retries + 1, max_retries, ) except Exception as e: # noqa: BLE001 - never-raise logger.error("staging_runner: infra-DEFER enqueue failed for %s: %s", task_id, e) return - # Budget exhausted -> fail-closed FAILED (terminal, never a false green). - _bump("failed") + # Budget exhausted -> infra-HOLD (D4): NO write_staging_log("FAILED"), NO advance, + # NO developer-retry. The task is held on deploy-staging for the operator. + _bump("permanent_env") logger.error( - "Task %s (%s): staging tool-error DEFER budget exhausted (%d) -> fail-closed FAILED", + "Task %s (%s): staging transient-infra DEFER budget exhausted (%d) -> " + "infra-HOLD on deploy-staging (NOT a code defect, no rollback)", task_id, work_item_id, max_retries, ) - write_staging_log(repo, work_item_id, branch, result.returncode, "FAILED", - result.stdout, tool_error=True) _alert_infra_exhausted(work_item_id, max_retries) - _advance(task_id, repo, work_item_id, branch) + + +def _handle_permanent_env( + task_id, repo: str, work_item_id: str, branch: str, result: proc_group.ProcResult +) -> None: + """Permanent environment defect (D4): an immediate, distinguishable infra-HOLD. + + The DEFER cycle is SKIPPED — retrying a permanent defect (no docker / no ssh + target / container down) is pointless (FR-3). We do NOT write a FAILED staging-log, + do NOT advance, do NOT burn a developer-retry — the task is HELD on + ``deploy-staging``: a red/missing ``check_staging_status`` keeps the reconciler's + ``advance_if_gate_passed`` from rolling it back to ``development`` (R-2), and the + rollback-to-development path (``advance_stage(finished_agent="deployer")``) is never + taken. A structured error log + an operator alert ("infra/environment, NOT a code + defect") make the hold visible; the operator re-drives after fixing the + environment. never-raise.""" + detail = (getattr(result, "stderr", "") or "").strip()[:300] + logger.error( + "Task %s (%s): PERMANENT staging environment defect -> infra-HOLD on " + "deploy-staging (NOT a code defect, no rollback, no developer-retry): %s", + task_id, work_item_id, detail or "", + ) + _alert_permanent_env(work_item_id, detail) def _alert_infra_exhausted(work_item_id: str, max_retries: int) -> None: """Best-effort Telegram alert that the staging suite never executed (infra, NOT a - code defect) after the retry budget. never-raise.""" + code defect) after the retry budget -> infra-HOLD (no rollback). never-raise.""" try: from .notifications import send_telegram, link_for send_telegram( - f"\U0001f6a8 {link_for(work_item_id)}: staging suite не запустилась " - f"(инфра, НЕ дефект кода) после {max_retries} попыток — fail-closed FAILED, " - f"откат на development. Нужно проверить staging-стенд." + f"\U0001f6a8 {link_for(work_item_id)}: staging-сюита не запустилась " + f"(инфра, НЕ дефект кода) после {max_retries} попыток — задача удержана на " + f"deploy-staging (без отката на development). Нужно проверить staging-стенд." ) except Exception as e: # noqa: BLE001 - never-raise logger.warning("staging_runner: infra-exhausted alert failed for %s: %s", work_item_id, e) +def _alert_permanent_env(work_item_id: str, detail: str) -> None: + """Best-effort Telegram alert that the staging suite could not execute due to a + permanent environment defect (NOT a code defect) -> infra-HOLD. never-raise.""" + try: + from .notifications import send_telegram, link_for + tail = f": {detail}" if detail else "" + send_telegram( + f"\U0001f6a8 {link_for(work_item_id)}: staging-сюита не смогла исполниться — " + f"постоянный дефект окружения (инфра, НЕ дефект кода){tail}. Задача удержана " + f"на deploy-staging до починки окружения (без отката на development)." + ) + except Exception as e: # noqa: BLE001 - never-raise + logger.warning("staging_runner: permanent-env alert failed for %s: %s", work_item_id, e) + + # --------------------------------------------------------------------------- # Entry point (D2) — owns the full deterministic flow, mirror run_deploy_finalizer # --------------------------------------------------------------------------- @@ -517,10 +671,12 @@ def run_staging_gate(job: dict) -> None: Flow (mirror of ``stage_engine.run_deploy_finalizer``): 1. resolve ``work_item_id`` / ``branch`` by ``task_id``; 2. execute the staging suite (D3) -> ProcResult; - 3. suite EXECUTED -> map exit-code -> ``staging_status:``, write - ``15-staging-log.md``, initiate the existing gate via ``advance_stage`` (D7); - 4. suite did NOT execute (tool-error) -> bounded DEFER / fail-closed (D5); - 5. observability counters + one structured verdict log (D10). + 3. classify the outcome three ways (D3): ``suite-ran`` -> map exit-code -> + ``staging_status:``, write ``15-staging-log.md``, initiate the existing gate + via ``advance_stage`` (D7); + 4. ``permanent-env`` -> immediate infra-HOLD (no rollback, no developer-retry); + ``transient-infra`` -> bounded DEFER, then infra-HOLD on exhaustion (D4); + 5. observability counters + one structured verdict log (D8). Never raises into the caller (the launcher marks the job done/failed).""" started = time.time() _bump("runs") @@ -552,9 +708,10 @@ def run_staging_gate(job: dict) -> None: try: result = run_staging_suite() duration_s = round(time.time() - started, 1) - suite_ran = (result.returncode is not None) and (not result.timed_out) + # ORCH-123 (D3): three-way classification (env != transient infra != code-fail). + outcome = classify_staging_outcome(result, _channel_ssh_configured()) - if suite_ran: + if outcome == "suite-ran": # 3. trust the exit-code (ORCH-061 already inside staging_check.py). status = map_exit_code_to_status(result.returncode) _bump("success" if status == "SUCCESS" else "failed") @@ -568,14 +725,27 @@ def run_staging_gate(job: dict) -> None: _advance(task_id, repo, work_item_id, branch) return - # 4. tool-error (suite did not execute) -> DEFER / fail-closed (D5). + # The suite did NOT execute. Count it as a tool-error, then route by class + # (D4): permanent-env -> immediate infra-HOLD; transient-infra -> bounded DEFER. + # NEITHER rolls back to development or burns a developer-retry (BR-2 invariant). _bump("tool_error") + if outcome == "permanent-env": + _bump("permanent_env") + logger.warning( + "staging_runner verdict: work_item=%s repo=%s exit_code=%s " + "duration_s=%s outcome=permanent-env (ssh_configured=%s)", + work_item_id, repo, result.returncode, duration_s, _channel_ssh_configured(), + ) + _handle_permanent_env(task_id, repo, work_item_id, branch, result) + return + + # transient-infra (timeout / ssh transport / unknown) -> bounded DEFER. logger.warning( - "staging_runner verdict: work_item=%s repo=%s exit_code=%s status=%s " - "duration_s=%s outcome=tool-error (timed_out=%s)", - work_item_id, repo, result.returncode, "TOOL-ERROR", duration_s, result.timed_out, + "staging_runner verdict: work_item=%s repo=%s exit_code=%s " + "duration_s=%s outcome=transient-infra (timed_out=%s)", + work_item_id, repo, result.returncode, duration_s, result.timed_out, ) - _handle_tool_error(task_id, repo, work_item_id, branch, result) + _handle_transient_infra(task_id, repo, work_item_id, branch, result) except Exception as e: # noqa: BLE001 - never-raise into the worker (AC-7) logger.error( "staging_runner.run_staging_gate: unexpected error for task %s (%s): %s", @@ -584,24 +754,107 @@ def run_staging_gate(job: dict) -> None: # --------------------------------------------------------------------------- -# Observability (D10 / FR-7 / AC-10) +# Prod-like preflight of the host-side execution channel (D5 / FR-4 / AC-5) +# --------------------------------------------------------------------------- +def _alert_preflight(reason: str) -> None: + """Best-effort Telegram alert that the host-side staging channel is unworkable at + startup (so a real task never silently false-routes later). never-raise.""" + try: + from .notifications import send_telegram + send_telegram( + f"⚠️ staging-runner preflight: {reason}. Хост-сторона исполнения " + f"staging-сюиты неработоспособна — задачи на deploy-staging будут удержаны " + f"(инфра, НЕ дефект кода). Проверьте ssh/docker/staging-стенд." + ) + except Exception as e: # noqa: BLE001 - never-raise + logger.warning("staging_runner: preflight alert failed: %s", e) + + +def preflight() -> tuple[bool, str]: + """Prod-like preflight of the host-side staging execution channel (D5 / AC-5). + + Probes the channel with a short bounded ssh probe (``command -v docker`` + + ``docker inspect -f '{{.State.Running}}' ``) so a broken + environment (no docker on the host / staging container down / ssh unreachable / no + ssh target configured) surfaces at SERVICE START — NOT postfactum as a false + rollback of a real task. Records ``_PREFLIGHT_STATE`` + alerts on failure. + + Purely observational (FR-4): it NEVER gates/blocks the pipeline, touches stages / + QG, or raises — called best-effort from ``main.lifespan``. Self-hosting scope: + ``applies()`` first (a disabled runner / out-of-scope repo -> n/a). Returns + ``(ok, reason)`` (``ok=True`` for n/a / in-container mode / a healthy channel). + """ + try: + from .qg.checks import SELF_HOSTING_REPO + if not applies(SELF_HOSTING_REPO): + _PREFLIGHT_STATE.update(ok=None, reason="n/a (runner disabled / out of scope)") + return True, "n/a" + # In-container mode (host-side disabled): nothing to probe host-side. + if not bool(getattr(settings, "staging_runner_exec_host_side", True)): + _PREFLIGHT_STATE.update(ok=True, reason="in-container mode (host-side disabled)") + return True, "in-container mode" + target = _ssh_target() + if not target: + reason = "no ssh target configured (deploy_ssh_host empty) — host-side staging unworkable" + _PREFLIGHT_STATE.update(ok=False, reason=reason) + _alert_preflight(reason) + return False, reason + probe = ( + "command -v docker >/dev/null 2>&1 && " + f"docker inspect -f '{{{{.State.Running}}}}' {shlex.quote(STAGING_SERVICE)}" + ) + cmd = ["ssh", "-o", "StrictHostKeyChecking=no", target, probe] + try: + r = subprocess.run(cmd, capture_output=True, text=True, timeout=_PREFLIGHT_TIMEOUT_S) + except subprocess.TimeoutExpired: + reason = "preflight ssh probe timed out" + _PREFLIGHT_STATE.update(ok=False, reason=reason) + _alert_preflight(reason) + return False, reason + except (subprocess.SubprocessError, OSError) as e: + reason = f"preflight ssh probe error: {e}" + _PREFLIGHT_STATE.update(ok=False, reason=reason) + _alert_preflight(reason) + return False, reason + out = (r.stdout or "").strip().lower() + if r.returncode == 0 and out == "true": + _PREFLIGHT_STATE.update(ok=True, reason="host-side channel ok (docker present, staging running)") + return True, "ok" + reason = f"host-side staging channel not ready (rc={r.returncode}, running={out!r})" + _PREFLIGHT_STATE.update(ok=False, reason=reason) + _alert_preflight(reason) + return False, reason + except Exception as e: # noqa: BLE001 - never-raise; preflight must never block start + logger.warning("staging_runner.preflight error: %s", e) + _PREFLIGHT_STATE.update(ok=None, reason=f"preflight error: {e}") + return True, "preflight skipped (error)" + + +# --------------------------------------------------------------------------- +# Observability (D8 / FR-7 / AC-10) # --------------------------------------------------------------------------- def snapshot() -> dict: """Read-only staging-runner summary for ``GET /queue`` (FR-7 / AC-10). - Additive block; existing ``/queue`` keys are untouched. never-raise: any error -> - a minimal dict with the kill-switch state.""" + Additive block; existing ``/queue`` keys are untouched. ORCH-123 adds + ``exec_host_side`` (the strategy flag), ``permanent_env`` (the infra-HOLD counter, + distinct from ``failed``=code-fail and ``deferred``=transient-infra) and the last + ``preflight`` verdict. never-raise: any error -> a minimal dict with the + kill-switch state.""" try: return { "enabled": bool(settings.staging_runner_enabled), "repos": getattr(settings, "staging_runner_repos", "") or "", "timeout_s": getattr(settings, "staging_runner_timeout_s", _DEFAULT_TIMEOUT_S), "infra_max_retries": getattr(settings, "staging_runner_infra_max_retries", 2), + "exec_host_side": bool(getattr(settings, "staging_runner_exec_host_side", True)), "runs": _STAGING_RUNNER_COUNTERS["runs"], "success": _STAGING_RUNNER_COUNTERS["success"], "failed": _STAGING_RUNNER_COUNTERS["failed"], "tool_error": _STAGING_RUNNER_COUNTERS["tool_error"], "deferred": _STAGING_RUNNER_COUNTERS["deferred"], + "permanent_env": _STAGING_RUNNER_COUNTERS["permanent_env"], + "preflight": dict(_PREFLIGHT_STATE), } except Exception as e: # noqa: BLE001 - never-raise -> minimal dict logger.warning("staging_runner.snapshot error: %s", e) diff --git a/tests/test_orch115_staging_runner.py b/tests/test_orch115_staging_runner.py index da8c415..719d21f 100644 --- a/tests/test_orch115_staging_runner.py +++ b/tests/test_orch115_staging_runner.py @@ -308,7 +308,11 @@ def test_tc10_timeout_defers_without_advance(monkeypatch): assert staging_runner._STAGING_RUNNER_COUNTERS["tool_error"] == 1 -def test_tc10_tool_error_budget_exhausted_fails_closed(monkeypatch, tmp_path): +def test_tc10_tool_error_budget_exhausted_infra_holds(monkeypatch, tmp_path): + # ORCH-123 (D4) SUPERSEDES ORCH-115 D5: a transient-infra DEFER budget that is + # exhausted no longer writes a fail-closed FAILED log + advances (a false rollback + # to development of an unresolved infra hiccup — BR-2). The task is now HELD on + # deploy-staging (infra-HOLD): NO advance, NO FAILED log, an operator alert instead. tid = _make_task("deploy-staging") monkeypatch.setattr(cfg.settings, "staging_runner_infra_max_retries", 0) # exhausted immediately monkeypatch.setattr(staging_runner, "run_staging_suite", @@ -318,8 +322,13 @@ def test_tc10_tool_error_budget_exhausted_fails_closed(monkeypatch, tmp_path): staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) - advance.assert_called_once() # fail-closed: write FAILED + advance (existing rollback) - assert "staging_status: FAILED" in _read_log(tmp_path, "orchestrator", "feature/ORCH-115-x", "ORCH-115") + advance.assert_not_called() # infra-HOLD: NO rollback to development + # No staging-log was written (a FAILED log would mislabel infra as a code-fail). + from src.git_worktree import get_worktree_path + log_path = os.path.join(get_worktree_path("orchestrator", "feature/ORCH-115-x"), + "docs/work-items/ORCH-115/15-staging-log.md") + assert not os.path.exists(log_path) + assert staging_runner._STAGING_RUNNER_COUNTERS["permanent_env"] == 1 def test_tc10_run_gate_never_raises(monkeypatch): @@ -369,6 +378,11 @@ def test_tc11_timeout_passed_to_proc_group(monkeypatch): return ProcResult(returncode=0, stdout="", stderr="", timed_out=False) monkeypatch.setattr(staging_runner.proc_group, "run_in_process_group", fake_run) + # ORCH-123 (D1): with no ssh target the command falls back to the in-container + # `docker exec` shape (the host-side ssh-wrap is covered in test_orch123_*). The + # invariant this test guards — timeout + tree_kill propagate to proc_group — is + # unchanged. + monkeypatch.setattr(cfg.settings, "deploy_ssh_host", "") staging_runner.run_staging_suite() assert captured["timeout"] == 321 assert captured["tree_kill"] is True @@ -420,13 +434,14 @@ def test_tc13_structured_verdict_log_distinguishes_outcomes(monkeypatch, caplog, assert any("outcome=code-pass" in r.message for r in caplog.records) caplog.clear() - # tool-error + # ORCH-123 (D8): a timeout is now classified `transient-infra` (the outcome + # taxonomy is code-pass/code-fail/transient-infra/permanent-env, not "tool-error"). monkeypatch.setattr(cfg.settings, "staging_runner_infra_max_retries", 2) monkeypatch.setattr(staging_runner, "run_staging_suite", lambda: ProcResult(returncode=None, stdout="", stderr="", timed_out=True)) with caplog.at_level("WARNING", logger="orchestrator.staging_runner"): staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) - assert any("outcome=tool-error" in r.message for r in caplog.records) + assert any("outcome=transient-infra" in r.message for r in caplog.records) def test_tc13_snapshot_never_raises(monkeypatch): diff --git a/tests/test_orch123_staging_runner_exec.py b/tests/test_orch123_staging_runner_exec.py new file mode 100644 index 0000000..9950184 --- /dev/null +++ b/tests/test_orch123_staging_runner_exec.py @@ -0,0 +1,503 @@ +"""ORCH-123 — staging-runner execution strategy must not depend on a docker CLI +inside the prod app-container (host-side ssh + three-way env classification). + +Background (incident ORCH-116): the ORCH-115 deterministic staging-runner ran the +staging suite via ``docker exec`` FROM INSIDE the prod ``orchestrator`` container, +which ships only ``openssh-client git curl`` — NOT a ``docker`` CLI (Dockerfile:11). +``Popen(["docker", ...])`` hit ``FileNotFoundError`` -> a PERMANENT environment defect +that ORCH-115 mis-routed as a code-fail rollback ``deploy-staging -> development`` +(burning developer-retries). The fix (ADR-001 / adr-0049): + + * D1 — execute the suite HOST-SIDE over the existing trusted ssh channel + (ORCH-036/058), wrapping the SAME ``docker exec ...`` command; + * D3 — three-way classification ``suite-ran`` / ``permanent-env`` / ``transient-infra``; + * D4 — environment/transient-infra NEVER ends in a code-fail rollback (infra-HOLD); + a really-executed failing suite STILL rolls back (anti-over-tolerance); + * D5 — a prod-like preflight of the host-side channel at startup. + +The pipeline gate / artifact contract / STAGE_TRANSITIONS / DB schema are byte-for-byte +unchanged (NFR-1). No live ssh / docker / network: the suite subprocess, advance_stage +and notifications are mocked; spawn-errors are reproduced with a non-existent binary. +""" +import os +import tempfile + +import pytest + +_test_db = os.path.join(tempfile.gettempdir(), "test_orch123_staging_runner_exec.db") +os.environ["ORCH_DB_PATH"] = _test_db +os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir() +os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token") +os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token") + +from unittest.mock import MagicMock # noqa: E402 + +import src.db as _db # noqa: E402 +from src.db import init_db, get_db # noqa: E402 +from src import staging_runner # noqa: E402 +from src import stage_engine # noqa: E402 +from src import config as cfg # noqa: E402 +from src.proc_group import ProcResult # noqa: E402 + + +# --------------------------------------------------------------------------- +# Fixtures (mirror tests/test_orch115_staging_runner.py) +# --------------------------------------------------------------------------- +@pytest.fixture(autouse=True) +def fresh_db(monkeypatch, tmp_path): + monkeypatch.setattr(_db.settings, "db_path", _test_db) + if os.path.exists(_test_db): + os.unlink(_test_db) + init_db() + monkeypatch.setattr("src.git_worktree.settings.worktrees_dir", str(tmp_path), raising=False) + # Runner ON, self-hosting scope, host-side strategy ON (defaults). + monkeypatch.setattr(cfg.settings, "staging_runner_enabled", True, raising=False) + monkeypatch.setattr(cfg.settings, "staging_runner_repos", "", raising=False) + monkeypatch.setattr(cfg.settings, "staging_runner_infra_max_retries", 2, raising=False) + monkeypatch.setattr(cfg.settings, "staging_runner_exec_host_side", True, raising=False) + # A configured ssh target (prod compose sets ORCH_DEPLOY_SSH_HOST=127.0.0.1). + monkeypatch.setattr(cfg.settings, "deploy_ssh_host", "127.0.0.1", raising=False) + monkeypatch.setattr(cfg.settings, "deploy_ssh_user", "slin", raising=False) + for k in staging_runner._STAGING_RUNNER_COUNTERS: + staging_runner._STAGING_RUNNER_COUNTERS[k] = 0 + staging_runner._PREFLIGHT_STATE.update(ok=None, reason="not-probed") + yield + + +def _make_task(stage, repo="orchestrator", wi="ORCH-123", branch="feature/ORCH-123-x"): + conn = get_db() + cur = conn.execute( + "INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage) VALUES (?, ?, ?, ?, ?)", + (f"plane-{wi}", wi, repo, branch, stage), + ) + tid = cur.lastrowid + conn.commit() + conn.close() + return tid + + +def _job_dict(job_id, agent, repo, task_id): + return {"id": job_id, "agent": agent, "repo": repo, "task_id": task_id, "task_content": "x"} + + +def _infra_jobs(task_id): + conn = get_db() + n = conn.execute( + "SELECT COUNT(*) FROM jobs WHERE task_id=? AND task_content LIKE ?", + (task_id, f"%{staging_runner._INFRA_RETRY_MARKER}%"), + ).fetchone()[0] + conn.close() + return n + + +def _read_log(repo, branch, wi): + from src.git_worktree import get_worktree_path + p = os.path.join(get_worktree_path(repo, branch), f"docs/work-items/{wi}/15-staging-log.md") + with open(p, "r", encoding="utf-8") as f: + return f.read() + + +def _log_exists(repo, branch, wi): + from src.git_worktree import get_worktree_path + return os.path.exists( + os.path.join(get_worktree_path(repo, branch), f"docs/work-items/{wi}/15-staging-log.md") + ) + + +# --------------------------------------------------------------------------- +# TC-01 — MANDATORY regression (red->green): no docker CLI in the container +# --------------------------------------------------------------------------- +def test_tc01_regression_no_docker_cli_in_container(monkeypatch): + """Reproduces incident ORCH-116. PRE-FIX: an in-container ``docker exec`` where the + container has no docker CLI -> proc_group spawn-error -> tool-error -> infra-DEFER x2 + -> false FAILED rollback to development. POST-FIX: classified ``permanent-env`` -> + infra-HOLD: NO advance, NO re-queue, NO developer-retry. (Red on pre-fix code — + there is no permanent-env class / counter there and the path advances.)""" + tid = _make_task("deploy-staging") + # Force the pre-fix in-container shape, then make the spawn fail exactly as if + # `docker` were absent — no network / ssh / docker needed. + monkeypatch.setattr(cfg.settings, "staging_runner_exec_host_side", False) + monkeypatch.setattr(staging_runner, "build_staging_command", + lambda: ["orch123-no-such-binary", "exec", "orchestrator-staging"]) + advance = MagicMock() + monkeypatch.setattr(stage_engine, "advance_stage", advance) + + staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) + + advance.assert_not_called() # NO false rollback to development + assert _infra_jobs(tid) == 0 # DEFER cycle skipped (FR-3) + assert not _log_exists("orchestrator", "feature/ORCH-123-x", "ORCH-123") # no FAILED log + assert staging_runner._STAGING_RUNNER_COUNTERS["permanent_env"] == 1 + assert staging_runner._STAGING_RUNNER_COUNTERS["tool_error"] == 1 + assert stage_engine.developer_retry_count(tid) == 0 # developer-retry not burned + + +# --------------------------------------------------------------------------- +# TC-02 — strategy does not require a docker CLI on the container PATH +# --------------------------------------------------------------------------- +def test_tc02_host_side_command_does_not_assume_in_container_docker(): + # With host-side ON + an ssh target, the suite is dispatched via ssh — the prod + # container's own PATH is never asked for a `docker` binary. + cmd = staging_runner.build_staging_command() + assert cmd[0] == "ssh" # dispatched over the trusted channel + assert "slin@127.0.0.1" in cmd + # The INNER command is the SAME staging suite (contract unchanged). + remote = cmd[-1] + assert "docker exec orchestrator-staging" in remote + assert "staging_check.py" in remote + assert "--mode stub" in remote + # The local executable invoked is `ssh` (in the container image), NOT `docker`. + assert cmd[0] != "docker" + + +# --------------------------------------------------------------------------- +# TC-03 — environment/tool-error does NOT cause a misleading code-fail rollback +# --------------------------------------------------------------------------- +def test_tc03_env_defect_no_code_fail_rollback_and_alerts(monkeypatch): + tid = _make_task("deploy-staging") + monkeypatch.setattr( + staging_runner, "run_staging_suite", + lambda: ProcResult(returncode=None, stdout="", + stderr="[Errno 2] No such file or directory: 'docker'", timed_out=False), + ) + advance = MagicMock() + monkeypatch.setattr(stage_engine, "advance_stage", advance) + sent = [] + monkeypatch.setattr("src.notifications.send_telegram", lambda msg, **kw: sent.append(msg)) + + staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) + + advance.assert_not_called() # not a code-fail -> no rollback + assert _infra_jobs(tid) == 0 # permanent defect -> no pointless retry + assert stage_engine.developer_retry_count(tid) == 0 + # A distinguishable infra/environment alert ("NOT a code defect") was sent. + assert sent and any("НЕ дефект кода" in m for m in sent) + + +# --------------------------------------------------------------------------- +# TC-04 — anti-over-tolerance: a really-executed failing suite STILL rolls back +# --------------------------------------------------------------------------- +def test_tc04_real_suite_failure_still_rolls_back(monkeypatch): + tid = _make_task("deploy-staging") + # The suite executed (a real exit-code) and failed; clean stderr (no env-marker). + monkeypatch.setattr( + staging_runner, "run_staging_suite", + lambda: ProcResult(returncode=1, stdout="B7 FAIL: assertion", stderr="", timed_out=False), + ) + advance = MagicMock() + monkeypatch.setattr(stage_engine, "advance_stage", advance) + + staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) + + advance.assert_called_once() # same rollback path as ORCH-115 + kwargs = advance.call_args.kwargs + assert kwargs["current_stage"] == "deploy-staging" + assert kwargs["finished_agent"] == "deployer" + assert "staging_status: FAILED" in _read_log("orchestrator", "feature/ORCH-123-x", "ORCH-123") + assert staging_runner._STAGING_RUNNER_COUNTERS["failed"] == 1 + assert staging_runner._STAGING_RUNNER_COUNTERS["permanent_env"] == 0 + + +def test_tc04_exit1_with_env_marker_is_not_a_code_fail(monkeypatch): + # The exit=1 collision: `docker exec` "No such container"=1 must NOT be read as a + # suite fail=1. The stderr env-marker disambiguates it -> permanent-env (no rollback). + tid = _make_task("deploy-staging") + monkeypatch.setattr( + staging_runner, "run_staging_suite", + lambda: ProcResult(returncode=1, stdout="", + stderr="Error: No such container: orchestrator-staging", timed_out=False), + ) + advance = MagicMock() + monkeypatch.setattr(stage_engine, "advance_stage", advance) + monkeypatch.setattr("src.notifications.send_telegram", lambda *a, **kw: None) + + staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) + + advance.assert_not_called() + assert staging_runner._STAGING_RUNNER_COUNTERS["permanent_env"] == 1 + + +# --------------------------------------------------------------------------- +# TC-05 — happy-path: suite ran, exit 0 -> SUCCESS -> advance +# --------------------------------------------------------------------------- +def test_tc05_happy_path_success_advances(monkeypatch): + tid = _make_task("deploy-staging") + monkeypatch.setattr( + staging_runner, "run_staging_suite", + lambda: ProcResult(returncode=0, stdout="ALL OK", stderr="", timed_out=False), + ) + advance = MagicMock() + monkeypatch.setattr(stage_engine, "advance_stage", advance) + + staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) + + advance.assert_called_once() + assert advance.call_args.kwargs["finished_agent"] == "deployer" + assert "staging_status: SUCCESS" in _read_log("orchestrator", "feature/ORCH-123-x", "ORCH-123") + assert staging_runner._STAGING_RUNNER_COUNTERS["success"] == 1 + + +# --------------------------------------------------------------------------- +# TC-06 — three-way classification (D3) +# --------------------------------------------------------------------------- +def _pr(rc=None, stderr="", timed_out=False): + return ProcResult(returncode=rc, stdout="", stderr=stderr, timed_out=timed_out) + + +def test_tc06_classification_three_way(): + C = staging_runner.classify_staging_outcome + # suite-ran: any recognised int (except 255) with no env-marker -> trust it. + assert C(_pr(rc=0), True) == "suite-ran" + assert C(_pr(rc=1), True) == "suite-ran" # anti-over-tolerance (BR-3) + assert C(_pr(rc=2, stderr="B7 FAIL"), True) == "suite-ran" + # permanent-env: spawn-error (rc None, not a timeout). + assert C(_pr(rc=None), True) == "permanent-env" + # permanent-env: shell command-not-found / cannot-execute codes. + assert C(_pr(rc=127), True) == "permanent-env" + assert C(_pr(rc=126), True) == "permanent-env" + # permanent-env: env-marker regardless of the exit-code. + assert C(_pr(rc=1, stderr="Cannot connect to the Docker daemon"), True) == "permanent-env" + assert C(_pr(rc=1, stderr="docker: command not found"), True) == "permanent-env" + # permanent-env: host-side ssh target not configured (R-6). + assert C(_pr(rc=None), False) == "permanent-env" + # transient-infra: timeout / ssh transport (255) -> retry is meaningful. + assert C(_pr(timed_out=True), True) == "transient-infra" + assert C(_pr(rc=255), True) == "transient-infra" + + +def test_tc06_classification_never_raises(): + class Boom: + @property + def returncode(self): + raise RuntimeError("boom") + # An exploding result -> fail-safe transient-infra (DEFER, never a silent suite-ran). + assert staging_runner.classify_staging_outcome(Boom(), True) == "transient-infra" + + +def test_tc06_transient_infra_defers_not_rolls_back(monkeypatch): + tid = _make_task("deploy-staging") + monkeypatch.setattr(staging_runner, "run_staging_suite", + lambda: _pr(rc=255, stderr="ssh: connect: Connection refused")) + advance = MagicMock() + monkeypatch.setattr(stage_engine, "advance_stage", advance) + + staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) + + advance.assert_not_called() # transient -> DEFER, never rollback + assert _infra_jobs(tid) == 1 # a fresh deployer job re-queued + assert staging_runner._STAGING_RUNNER_COUNTERS["deferred"] == 1 + + +# --------------------------------------------------------------------------- +# TC-07 — prod-like preflight (D5 / AC-5) +# --------------------------------------------------------------------------- +def test_tc07_preflight_no_ssh_target_signals_before_a_real_task(monkeypatch): + monkeypatch.setattr(cfg.settings, "deploy_ssh_host", "") # host-side, but no target + sent = [] + monkeypatch.setattr("src.notifications.send_telegram", lambda msg, **kw: sent.append(msg)) + + ok, reason = staging_runner.preflight() + + assert ok is False + assert "no ssh target" in reason + assert staging_runner._PREFLIGHT_STATE["ok"] is False + assert sent # operator alerted at startup + + +def test_tc07_preflight_probe_success(monkeypatch): + class _R: + returncode = 0 + stdout = "true\n" + stderr = "" + monkeypatch.setattr(staging_runner.subprocess, "run", lambda *a, **kw: _R()) + ok, reason = staging_runner.preflight() + assert ok is True + assert staging_runner._PREFLIGHT_STATE["ok"] is True + + +def test_tc07_preflight_probe_failure_alerts(monkeypatch): + class _R: + returncode = 1 + stdout = "" # docker missing on host / container down + stderr = "command not found" + monkeypatch.setattr(staging_runner.subprocess, "run", lambda *a, **kw: _R()) + sent = [] + monkeypatch.setattr("src.notifications.send_telegram", lambda msg, **kw: sent.append(msg)) + ok, _reason = staging_runner.preflight() + assert ok is False + assert sent + + +def test_tc07_preflight_noop_when_disabled(monkeypatch): + monkeypatch.setattr(cfg.settings, "staging_runner_enabled", False) + ok, reason = staging_runner.preflight() # out of scope -> n/a, never blocks + assert ok is True + assert reason == "n/a" + + +def test_tc07_preflight_in_container_mode_noop(monkeypatch): + monkeypatch.setattr(cfg.settings, "staging_runner_exec_host_side", False) + ok, reason = staging_runner.preflight() + assert ok is True + assert "in-container" in reason + + +# --------------------------------------------------------------------------- +# TC-08 — self-hosting safety: no dangerous literals in the host-side command +# --------------------------------------------------------------------------- +def test_tc08_host_side_command_has_no_dangerous_literals(): + cmd = " ".join(staging_runner.build_staging_command()) + forbidden = ("compose", "up -d", "--build", "8500", "force", "push", ".env", + "rm ", "restart") + for token in forbidden: + assert token not in cmd, f"forbidden literal {token!r} in host-side command: {cmd}" + assert "ssh" in cmd and "docker exec" in cmd and "staging_check.py" in cmd + assert "8501" in cmd and "--mode stub" in cmd + + +# --------------------------------------------------------------------------- +# TC-09 — kill-switch / scope / strategy flag default (AC-10) +# --------------------------------------------------------------------------- +def test_tc09_killswitch_scope_and_flag_default(monkeypatch): + # kill-switch off -> should_intercept False -> the prior LLM deployer via _spawn. + monkeypatch.setattr(cfg.settings, "staging_runner_enabled", False) + tid = _make_task("deploy-staging") + assert staging_runner.should_intercept(_job_dict(1, "deployer", "orchestrator", tid)) is False + # enabled, empty CSV -> self-hosting only. + monkeypatch.setattr(cfg.settings, "staging_runner_enabled", True) + assert staging_runner.applies("orchestrator") is True + assert staging_runner.applies("enduro-trails") is False + # the strategy flag defaults to host-side (prod). + assert cfg.settings.staging_runner_exec_host_side is True + + +def test_tc09_host_side_off_falls_back_to_in_container(monkeypatch): + monkeypatch.setattr(cfg.settings, "staging_runner_exec_host_side", False) + cmd = staging_runner.build_staging_command() + assert cmd[:2] == ["docker", "exec"] # rollback knob -> prior 1:1 shape + + +def test_tc09_host_side_on_but_no_target_falls_back(monkeypatch): + monkeypatch.setattr(cfg.settings, "deploy_ssh_host", "") + cmd = staging_runner.build_staging_command() + assert cmd[:2] == ["docker", "exec"] # no target -> in-container fallback + + +# --------------------------------------------------------------------------- +# TC-10 — artifact contract: staging_status frontmatter + 52c schema (AC-7) +# --------------------------------------------------------------------------- +def test_tc10_artifact_contract_unchanged(): + body = staging_runner.build_staging_log("ORCH-123", 0, "SUCCESS", "ok") + assert "staging_status: SUCCESS" in body # UPPERCASE machine key, unchanged + for field in ("work_item: ORCH-123", "stage: deploy-staging", + "author_agent: staging-runner", "model_used: n/a"): + assert field in body + # The UNCHANGED gate parser reads the runner's frontmatter. + from src.qg.checks import _parse_staging_status + ok, _r = _parse_staging_status(body) + assert ok is True + bad, _r2 = _parse_staging_status(staging_runner.build_staging_log("ORCH-123", 1, "FAILED")) + assert bad is False + + +# --------------------------------------------------------------------------- +# TC-11 — pipeline anti-regress: gate / transitions / schema untouched (AC-7) +# --------------------------------------------------------------------------- +def test_tc11_pipeline_contract_unchanged(): + from src.stages import STAGE_TRANSITIONS + from src.qg.checks import QG_CHECKS + assert STAGE_TRANSITIONS["deploy-staging"] == { + "next": "deploy", "agent": "deployer", "qg": "check_staging_status" + } + assert "check_staging_status" in QG_CHECKS + conn = get_db() + tables = {r[0] for r in conn.execute( + "SELECT name FROM sqlite_master WHERE type='table'").fetchall()} + conn.close() + assert not any("staging_runner" in t for t in tables) # no DB migration + + +# --------------------------------------------------------------------------- +# TC-12 — never-raise / queue not wedged + observability distinguishes classes +# --------------------------------------------------------------------------- +def test_tc12_run_gate_never_raises(monkeypatch): + tid = _make_task("deploy-staging") + + def boom(): + raise RuntimeError("ssh exploded") + monkeypatch.setattr(staging_runner, "run_staging_suite", boom) + staging_runner.run_staging_gate(_job_dict(1, "deployer", "orchestrator", tid)) # must NOT raise + + +def test_tc12_snapshot_distinguishes_classes(): + snap = staging_runner.snapshot() + for k in ("enabled", "exec_host_side", "failed", "deferred", "permanent_env", "preflight"): + assert k in snap, f"snapshot missing key {k}" + # The three non-success classes are distinct keys (code-fail vs transient vs env). + assert {"failed", "deferred", "permanent_env"} <= set(snap) + + +def test_tc12_snapshot_never_raises(monkeypatch): + class Boom: + def __getattr__(self, name): + raise RuntimeError("boom") + monkeypatch.setattr(staging_runner, "settings", Boom()) + assert staging_runner.snapshot()["enabled"] is False + + +# --------------------------------------------------------------------------- +# R-2 — a held deploy-staging task is NOT rolled back to development by the +# reconciler (the defect would re-appear if it were). AC-3 / AC-11. +# --------------------------------------------------------------------------- +def test_r2_held_deploy_staging_not_rolled_back(monkeypatch): + tid = _make_task("deploy-staging") + # No 15-staging-log.md was written (infra-HOLD) -> check_staging_status is red. + advance = MagicMock() + monkeypatch.setattr(stage_engine, "advance_stage", advance) + + result = stage_engine.advance_if_gate_passed( + tid, "deploy-staging", "orchestrator", "ORCH-123", "feature/ORCH-123-x" + ) + + assert result is None # red gate -> stay, no advance call + advance.assert_not_called() # NEVER rolled back to development + conn = get_db() + stage = conn.execute("SELECT stage FROM tasks WHERE id=?", (tid,)).fetchone()[0] + conn.close() + assert stage == "deploy-staging" # held in place + + +# --------------------------------------------------------------------------- +# TC-13 — documentation of the execution boundary (AC-12) +# --------------------------------------------------------------------------- +def _repo_root(): + return os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + + +def test_tc13_docs_describe_execution_boundary(): + root = _repo_root() + with open(os.path.join(root, "docs/operations/INFRA.md"), encoding="utf-8") as f: + infra = f.read().lower() + with open(os.path.join(root, "docs/architecture/README.md"), encoding="utf-8") as f: + readme = f.read().lower() + # INFRA.md fixes the boundary: no docker CLI in the container; docker ops host-side. + assert "host-side" in infra + assert "docker" in infra and "ssh" in infra + assert "orch-123" in infra + # README describes the host-side staging-runner strategy. + assert "orch-123" in readme + assert "host-side" in readme + + +# --------------------------------------------------------------------------- +# TC-14 — anti-drift ORCH-115: invariants intact (kill-switch -> LLM, shared map) +# --------------------------------------------------------------------------- +def test_tc14_orch115_invariants_intact(monkeypatch): + # Kill-switch off -> the single LLM transport path is restored (no intercept). + monkeypatch.setattr(cfg.settings, "staging_runner_enabled", False) + tid = _make_task("deploy-staging") + assert staging_runner.should_intercept(_job_dict(1, "deployer", "orchestrator", tid)) is False + # The exit-code mapping is still the SAME shared self_deploy contract (no drift). + from src import self_deploy + for v in (0, 1, None, "x"): + assert staging_runner.map_exit_code_to_status(v) == self_deploy.map_exit_code_to_status(v) From 820e534e7712acf310de4c551b29b265a849619a Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 08:52:22 +0300 Subject: [PATCH 5/8] reviewer(ET): auto-commit from reviewer run_id=751 --- docs/work-items/ORCH-123/12-review.md | 153 ++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 docs/work-items/ORCH-123/12-review.md diff --git a/docs/work-items/ORCH-123/12-review.md b/docs/work-items/ORCH-123/12-review.md new file mode 100644 index 0000000..21beee4 --- /dev/null +++ b/docs/work-items/ORCH-123/12-review.md @@ -0,0 +1,153 @@ +--- +verdict: APPROVED +work_item: ORCH-123 +stage: review +author_agent: reviewer +status: approved +created_at: 2026-06-16 +model_used: claude-opus-4-8 +type: review +work_item_id: ORCH-123 +version: 1 +--- + +# Review ORCH-123 + +## Summary + +Фикс инцидента **ORCH-116**: детерминированный staging-runner (ORCH-115) исполнял `docker exec` +**изнутри** прод-контейнера `orchestrator`, где нет docker CLI (`Dockerfile:11` — только +`openssh-client git curl`) → `FileNotFoundError` → постоянный environment-дефект ложно +маршрутизировался как код-фейл-откат `deploy-staging → development` (с расходом developer-retry). +Задача — `Bug`, эскалирована `escalate: full-cycle` (полный пакет analysis+architecture+ADR). + +Изменение точное и минимальное: 9 файлов в реальном скоупе (`65c17d8..HEAD`) — +`src/staging_runner.py` (+343), `src/config.py` (новый флаг), `src/main.py` (preflight), +`.env.example`, `CHANGELOG.md`, `CLAUDE.md`, `docs/architecture/README.md`, +`docs/operations/INFRA.md`, + тесты `tests/test_orch123_staging_runner_exec.py` (503), +`tests/test_orch115_staging_runner.py` (anti-drift). + +Реализация байт-в-байт соответствует ADR-001 / adr-0049 (D1 host-side ssh-wrap, D3 трёхсторонняя +`classify_staging_outcome`, D4 инвариант «инфра ≠ код-фейл» = infra-HOLD, D5 preflight, D6 флаг, +D7 сохранность контракта, D8 наблюдаемость). Все четыре оси проверки пройдены; P0/P1 findings нет. + +**Проверено фактически:** +- Полный прогон `pytest tests/ -q` → **2131 passed** (AC-11). +- Целевой набор `test_orch123_staging_runner_exec.py` + `test_orch115_staging_runner.py` + + `test_llm_determinization_docs.py` → **53 passed**. +- Структурный анти-регресс `test_system_docs.py` + `test_no_host_hardcodes.py` + + `test_config.py` → **61 passed**. + +## Соответствие ТЗ (02-trz.md / 03-acceptance-criteria.md) + +Все функциональные требования и критерии приёмки реализованы и покрыты тестами: + +| AC | FR/BR | Статус | Где проверено | +|----|-------|--------|---------------| +| AC-1, AC-2 — сюита реально исполняется host-side | FR-1 | ✅ | `build_staging_command` ssh-wrap; TC-02, TC-05 | +| AC-3 — env/tool-error ≠ код-фейл-откат | FR-2/FR-3 | ✅ | `classify_staging_outcome` + `_handle_permanent_env`/`_handle_transient_infra`; TC-01, TC-03 | +| AC-4 — анти-over-tolerance (исполнившаяся упавшая сюита → откат) | FR-2/BR-3 | ✅ | check 3 «trust recognised exit-code first»; TC-04, TC-04-exit1-marker | +| AC-5 — prod-like preflight | FR-4 | ✅ | `preflight()` в `main.lifespan` (best-effort, never-blocks); TC-07 | +| AC-6 — обязательный регресс red→green | FR-1/FR-2 | ✅ | TC-01 (in-container shape + spawn-error → permanent-env, без advance/defer/retry) | +| AC-7 — гейт/контракт/стадии/схема без регресса | NFR-1 | ✅ | TC-10, TC-11 (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_staging_status`/схема БД целы) | +| AC-8 — self-hosting safety | NFR-2 | ✅ | TC-08 (нет `compose`/`--build`/`8500`/`force`/`push`/`.env`/`restart` в argv) | +| AC-9 — security-review socket/CLI | NFR-3 | ✅ | ADR D2: выбран host-side ssh, docker CLI/SDK НЕ добавлен, `docker.sock` не используется изнутри | +| AC-10 — kill-switch/область | NFR-4/NFR-6 | ✅ | TC-09 (`staging_runner_exec_host_side` default True; enduro no-op) | +| AC-11 — never-raise / очередь не клинится | NFR-5 | ✅ | TC-12; полный suite зелёный | +| AC-12 — документация границы исполнения | BR-5/FR-6 | ✅ | TC-13 (INFRA.md + README.md содержат host-side/ssh/ORCH-123) | + +Регресс R-2 (held `deploy-staging`-задача не откатывается reconciler'ом) — отдельный тест +`test_r2_held_deploy_staging_not_rolled_back`: при отсутствии `15-staging-log.md` (infra-HOLD) +`advance_if_gate_passed` отдаёт `None`, задача держится на `deploy-staging`, `advance_stage` не +зовётся. Закрывает риск реинтродукции дефекта (10-tech-risks R-2). + +## Соответствие ADR (06-adr/ADR-001 + сквозной adr-0049) + +- **D1** — `build_staging_command` оборачивает ту же `docker exec … staging_check.py … --mode stub` + в `ssh -o StrictHostKeyChecking=no ''` (зеркало `self_deploy.build_deploy_command`/ + `image_freshness.image_revision`); inner-команда `shlex.quote`-ится; fallback на in-container при + выключенном флаге ИЛИ пустом ssh-target. ✅ +- **D3** — `classify_staging_outcome` различает три класса с корректным порядком проверок: + env-маркер в stderr → `permanent-env` (дизамбигуация `exit=1` коллизии «No such container» vs + реальный фейл, R-3); 126/127 → `permanent-env`; распознанный int≠255 без маркера → `suite-ran` + (проверяется **до** channel-guards → реальный фейл не маскируется, BR-3); timeout/255 → + `transient-infra`; нет ssh-target/`rc=None` → `permanent-env`; неизвестно → fail-safe + `transient-infra`. Pure, never-raise. ✅ +- **D4** — инвариант «инфра ≠ код-фейл»: `permanent-env` → немедленный infra-HOLD (без `_advance`, + без FAILED-лога, без developer-retry); `transient-infra` → bounded DEFER, на исчерпании — тоже + infra-HOLD (суперсед терминала ORCH-115 D5 fail-closed-FAILED+rollback). ✅ +- **D5** — `preflight()` зондирует host-side канал коротким bounded ssh-probe, пишет + `_PREFLIGHT_STATE`, алертит; вызван best-effort из `main.lifespan` после lease-recovery, + никогда не блокирует старт. ✅ +- **D6** — `staging_runner_exec_host_side: bool = True` (env `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE`), + дефолт = боевое; откат двумя флагами. ✅ +- **D7** — `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_staging_status`/`_parse_staging_status`/ + machine-verdict `staging_status:`/схема БД — байт-в-байт (TC-10/TC-11). ✅ +- **D8** — `snapshot()` различает три не-успешных класса (`failed`=code-fail / `deferred`=transient / + `permanent_env`=infra-HOLD) + `exec_host_side` + `preflight`. ✅ + +**Трассировка маркеров (CLAUDE.md §9 / TRACEABILITY.md):** ORCH-123 правит блоки ORCH-115 +(staging-runner, прямой объект), ORCH-036 (self_deploy ssh-паттерн), ORCH-110 (proc_group/classify +/infra-tolerance), ORCH-058 (host-side docker). ADR явно сверяется с их инвариантами и не ломает +их; анти-дрейф ORCH-115 — TC-14 (`should_intercept`/`map_exit_code_to_status` shared-контракт, +kill-switch → LLM) зелёный. + +## Качество кода + +- Чистый leaf-стиль по образцу `merge_gate`/`self_deploy`/`image_freshness`; на импорте только + `config`/`shlex`/`subprocess`, тяжёлое — лениво. Все публичные функции с docstrings. +- `never-raise` соблюдён на всех путях (classify, preflight, snapshot, run_staging_gate, alert'ы). +- Старое имя `_handle_tool_error` чисто переименовано в `_handle_transient_infra` — висячих ссылок + нет (grep пуст). +- Тесты содержательные (поведенческие, не тривиальные): мокается subprocess/advance/notifications, + spawn-error воспроизводится несуществующим бинарём — без живого ssh/docker/сети. +- **Багфикс-трек (ORCH-019 BR-4):** обязательный регресс-тест-фиксатор дефекта присутствует — + TC-01 красный на коде до фикса (нет класса/счётчика `permanent_env`, путь advance'ит + DEFER), + зелёный после. Требование выполнено. + +## Документация + +`src/` изменён → документация обновлена **в том же PR** (golden source): +- `docs/operations/INFRA.md` — новый раздел «Граница исполнения docker-операций — host-side» + + правило 4 для агентов (FR-6 / AC-12). ✅ +- `docs/architecture/README.md` — секция Staging-runner дополнена host-side стратегией + + трёхсторонней классификацией + ссылкой на adr-0049. ✅ +- `CLAUDE.md` — раздел ORCH-123 (host-side exec + классификация environment-дефекта). ✅ +- `CHANGELOG.md` — запись `fix(staging)`. ✅ +- `.env.example` — новый ключ `ORCH_STAGING_RUNNER_EXEC_HOST_SIDE=true` + описание. ✅ +- ADR: `06-adr/ADR-001-…` + сквозной `docs/architecture/adr/adr-0049-…`. ✅ + +**Витрина системы `docs/overview/` (ORCH-011)** — обновление НЕ требуется: канал исполнения +(host-side vs in-container) — внутренняя деталь реализации; машинно-проверяемые факты витрины +(детерминированный раннер заменил LLM-`deployer`, kill-switch, скоуп) ORCH-123 не меняет; +`test_system_docs.py` зелёный. + +**Обзорные доки `README.md` «Известные ограничения» (ORCH-079)** — обновление НЕ требуется: +ORCH-123 закрывает внутренний регресс ORCH-116, а не задокументированное ограничение; релевантного +пункта в списке нет. + +## Findings + +### P0 — Blocker +- Нет. + +### P1 — Must fix +- Нет. + +### P2 — Should fix +- Нет. + +### P3 — Nice-to-have (не блокирует) +- `preflight()` использует прямой `subprocess.run(timeout=20)` вместо `proc_group` — для короткого + read-only ssh-зонда приемлемо (тот же паттерн, что у host-side probe'ов `image_freshness`); + при таймауте локальный ssh-клиент завершается subprocess'ом без tree-kill, что для 20-секундного + inspect незначимо. Можно унифицировать в будущем, не обязательно. +- `_channel_ssh_configured()` вызывается дважды в `run_staging_gate` (для classify и для лог-строки + `permanent-env`) — микро-избыточность, never-raise, влияния нет. + +## Вердикт + +**APPROVED.** Реализация полно и точно покрывает ТЗ/AC, соответствует ADR-001/adr-0049, не трогает +гейты/стадии/контракт/схему БД, безопасна для self-hosting, документация (включая витрину-проверку +и обзорные доки) в порядке, обязательный багфикс-регресс присутствует и зелёный, полный suite +(2131) зелёный. P0/P1 отсутствуют. From 2b71f3887fa3b7768e562899279a508fd2c6a964 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 08:55:07 +0300 Subject: [PATCH 6/8] tester(ET): auto-commit from tester run_id=752 --- docs/work-items/ORCH-123/13-test-report.md | 81 ++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/work-items/ORCH-123/13-test-report.md diff --git a/docs/work-items/ORCH-123/13-test-report.md b/docs/work-items/ORCH-123/13-test-report.md new file mode 100644 index 0000000..76c45bf --- /dev/null +++ b/docs/work-items/ORCH-123/13-test-report.md @@ -0,0 +1,81 @@ +--- +result: PASS +work_item: ORCH-123 +stage: testing +author_agent: tester +status: pass +created_at: 2026-06-16 +model_used: claude-opus-4-8 +type: test-report +work_item_id: ORCH-123 +--- + +# Test Report — ORCH-123 + +Bugfix инцидента **ORCH-116**: детерминированный staging-runner (ORCH-115) вызывал `docker exec` +**изнутри** прод-контейнера `orchestrator`, где нет docker CLI → `FileNotFoundError` → постоянный +environment-дефект ложно маршрутизировался как код-фейл-откат `deploy-staging → development`. +Фикс — host-side ssh-исполнение + трёхсторонняя классификация (`suite-ran` / `permanent-env` / +`transient-infra`). Review-вердикт: **APPROVED**. + +## Окружение +- Python: 3.12.13 +- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.14.0, asyncio-0.23.8) +- Worktree: `/repos/_wt/orchestrator/feature_ORCH-123-bug-staging-runner-assumes-doc` +- Branch: `feature/ORCH-123-bug-staging-runner-assumes-doc` (HEAD `820e534`) +- Дата: 2026-06-16 + +## Smoke API (read-only) +| Endpoint | Результат | +|----------|-----------| +| `GET /health` | PASS — `{"status":"ok","service":"orchestrator"}` | +| `GET /status` | PASS — задача ORCH-123 (id=110) на стадии `testing` | +| `GET /queue` | PASS — блоки `serial_gate` (ORCH-088), `auto_labels` (ORCH-089), `staging_runner` (ORCH-115/123) присутствуют в полезной нагрузке | + +## Результаты (покрытие test-plan `04-test-plan.yaml` ↔ AC) + +| TC ID | Описание | AC | Тест | Результат | +|-------|----------|----|------|-----------| +| TC-01 | РЕГРЕСС red→green: исполнение сюиты без docker CLI в контейнере; spawn-error → `permanent-env`, без advance/defer/retry | AC-6/AC-1 | `test_tc01_regression_no_docker_cli_in_container` | PASS | +| TC-02 | Стратегия исполнения не зависит от docker CLI внутри контейнера (host-side argv/канал) | AC-1 | `test_tc02_host_side_command_does_not_assume_in_container_docker` | PASS | +| TC-03 | environment/tool-error НЕ даёт код-фейл-отката; нет developer-retry; инфра-алерт | AC-3 | `test_tc03_env_defect_no_code_fail_rollback_and_alerts` | PASS | +| TC-04 | Анти-over-tolerance: сюита исполнилась + exit≠0 → FAILED → прежний откат + developer-retry; `exit=1` с env-маркером ≠ код-фейл | AC-4 | `test_tc04_real_suite_failure_still_rolls_back`, `test_tc04_exit1_with_env_marker_is_not_a_code_fail` | PASS | +| TC-05 | Happy-path: exit 0 → `staging_status: SUCCESS` → штатный advance (контракт ORCH-115 D7) | AC-2 | `test_tc05_happy_path_success_advances` | PASS | +| TC-06 | Классификация три-way; постоянный env-дефект ≠ транзиент ≠ код-фейл; never-raise; transient → DEFER не откат | AC-3 | `test_tc06_classification_three_way`, `..._never_raises`, `..._transient_infra_defers_not_rolls_back` | PASS | +| TC-07 | Prod-like preflight сигнализирует ДО ложного отката (success/failure/no-target/disabled/in-container) | AC-5 | `test_tc07_preflight_*` (5 тестов) | PASS | +| TC-08 | Self-hosting safety: нет `compose`/`--build`/`8500`/force-push/`main`/`.env` в argv | AC-8 | `test_tc08_host_side_command_has_no_dangerous_literals` | PASS | +| TC-09 | Kill-switch/область: `staging_runner_enabled=False` → `_spawn`; flag default = боевое; host-side off / no-target → in-container fallback | AC-10 | `test_tc09_killswitch_scope_and_flag_default`, `..._host_side_off_falls_back_to_in_container`, `..._host_side_on_but_no_target_falls_back` | PASS | +| TC-10 | Контракт артефакта `15-staging-log.md` (`staging_status:` UPPERCASE + 52c, `author_agent: staging-runner`/`model_used: n/a`) | AC-7 | `test_tc10_artifact_contract_unchanged` | PASS | +| TC-11 | Анти-регресс конвейера: `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_staging_status`/`_parse_staging_status`/machine-keys/схема БД — не тронуты | AC-7 | `test_tc11_pipeline_contract_unchanged` | PASS | +| TC-12 | never-raise / очередь не клинится; snapshot различает классы (`failed`/`deferred`/`permanent_env`) | AC-11 | `test_tc12_run_gate_never_raises`, `..._snapshot_distinguishes_classes`, `..._snapshot_never_raises` | PASS | +| TC-13 | Документация-инвариант: INFRA.md + README.md описывают границу исполнения (host-side vs in-container) | AC-12 | `test_tc13_docs_describe_execution_boundary` | PASS | +| TC-14 | Анти-дрейф ORCH-115: структурные тесты staging-runner остаются зелёными | AC-7 | `test_tc14_orch115_invariants_intact` + полный `test_orch115_staging_runner.py` (24 теста) | PASS | +| R-2 | Held `deploy-staging`-задача не откатывается reconciler'ом при infra-HOLD | AC-3 | `test_r2_held_deploy_staging_not_rolled_back` | PASS | + +Все 14 TC из `04-test-plan.yaml` выполнены и сопоставлены с критериями приёмки +`03-acceptance-criteria.md`. Обязательный регресс-фиксатор дефекта (TC-01, ORCH-019 BR-4) присутствует +и зелёный. + +## Вывод pytest + +Целевой набор: +``` +tests/test_orch123_staging_runner_exec.py ... (26 tests) +tests/test_orch115_staging_runner.py ... (24 tests) +======================== 50 passed, 1 warning in 3.17s ========================= +``` + +Полный регресс (NFR-1, AC-11): +``` +python -m pytest tests/ -q --tb=short +........................................................................ [100%] +2131 passed, 1 warning in 91.73s (0:01:31) +``` + +(Единственное warning — `PydanticDeprecatedSince20` в `src/config.py:8`, унаследованное, +не относится к задаче.) + +## Итог +**PASS** — полный регресс `2131 passed`, целевой набор `50 passed`, smoke `/health` `/status` +`/queue` (с блоками `serial_gate`/`auto_labels`/`staging_runner`) OK, каждый TC из test-plan выполнен +и сопоставлен с AC. Задача готова к переходу на `deploy-staging`. From 12e3a9e4f396c06bdfa8873cd31e3ea20b600392 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 16 Jun 2026 08:57:48 +0300 Subject: [PATCH 7/8] =?UTF-8?q?docs(ORCH-123):=20staging=20gate=20log=20?= =?UTF-8?q?=E2=80=94=20staging=5Fstatus=20SUCCESS=20(8/10,=20C9a/C9b=20inf?= =?UTF-8?q?ra-waived)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- docs/work-items/ORCH-123/15-staging-log.md | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/work-items/ORCH-123/15-staging-log.md diff --git a/docs/work-items/ORCH-123/15-staging-log.md b/docs/work-items/ORCH-123/15-staging-log.md new file mode 100644 index 0000000..b050ffc --- /dev/null +++ b/docs/work-items/ORCH-123/15-staging-log.md @@ -0,0 +1,35 @@ +--- +staging_status: SUCCESS +work_item: ORCH-123 +stage: deploy-staging +author_agent: deployer +status: success +created_at: 2026-06-16 +model_used: claude-opus-4-8 +timestamp: 2026-06-16T05:57:12Z +base_url: http://localhost:8501 +--- + +# Staging Gate Log + +Staging test suite completed against the live staging instance (`orchestrator-staging`, port 8501). + +**Execution strategy (ORCH-123):** the canonical `docker exec orchestrator-staging … staging_check.py +--base-url http://localhost:8501 --mode stub` was initiated **host-side via ssh** +(`slin@127.0.0.1`), because the prod container carries no docker CLI (`Dockerfile` ships only +`openssh-client git curl`). The suite itself runs INSIDE `orchestrator-staging`. + +**Result:** `8/10 checks PASS`, exit code `0` → `staging_status: SUCCESS`. + +- REAL failed: none — every real check (Block A smoke, Block B access incl. B6 registry isolation + `sandbox=YES, prod-ET=NO, prod-ORCH=NO`, Block C create/trigger) is green. +- Waived (ORCH-061 infra tolerance, `staging_infra_tolerance_enabled=True`): + +``` +INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green) +VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green +``` + +C9a/C9b depend on SANDBOX bot accounts being project members (sandbox-infra, not the pipeline) and +are tolerated when every REAL check is green. The exit-code → verdict mapping is unchanged: trust the +exit code (0 → SUCCESS); waived checks are not re-judged. From 031130c7f03e618937c653c6a5fcc8549d4d4a07 Mon Sep 17 00:00:00 2001 From: deploy-finalizer Date: Tue, 16 Jun 2026 09:03:29 +0300 Subject: [PATCH 8/8] deploy(ORCH-036): finalize SUCCESS for ORCH-123 --- docs/work-items/ORCH-123/14-deploy-log.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/work-items/ORCH-123/14-deploy-log.md diff --git a/docs/work-items/ORCH-123/14-deploy-log.md b/docs/work-items/ORCH-123/14-deploy-log.md new file mode 100644 index 0000000..692a9c9 --- /dev/null +++ b/docs/work-items/ORCH-123/14-deploy-log.md @@ -0,0 +1,12 @@ +--- +deploy_status: SUCCESS +work_item: ORCH-123 +hook_exit_code: 0 +deployed_by: deploy-finalizer +--- + +# Deploy log — ORCH-036 executable self-deploy + +Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`. + +Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.