orchestrator/docs/work-items/ORCH-065/01-brd.md

BRD — ORCH-065: zombie jobs + залипший merge-lease

Work Item ID: ORCH-065 Тип: BUG (P0) Репозиторий: orchestrator (self-hosting) Эпик: блокер ORCH-54 (полностью автономный self-deploy)

1. Контекст и проблема

Оркестратор — единый инстанс с общей БД и общей очередью (jobs, max_concurrency=1 для self-hosting), обслуживающий несколько проектов. Финальная автономность self-deploy упирается в два связанных класса отказов, оба сводящиеся к «процесс умер/завершился, а состояние осталось захваченным навсегда»:

Проблема A — zombie jobs (строка jobs навсегда running)

Агент (deployer/developer/reviewer) завершается или умирает (краш, OOM, рестарт контейнера в ходе self-deploy, гибель monitor-потока), но строка в таблице jobs остаётся в статусе running. Финализация статуса job выполняется только в _monitor_agent → _finalize_job внутри того же процесса; если этот поток/процесс не доживает до финализации — job «зомбирован».

• Единственная имеющаяся защита — requeue_running_jobs() в main.lifespan, срабатывающая исключительно на старте процесса. Зомби, возникший без рестарта (умер дочерний процесс/monitor-поток, а сервис жив), не реанимируется никогда.
• При max_concurrency=1 одна зомби-строка running блокирует claim всех последующих job (count_running_jobs() >= max_concurrency → claim не происходит) → встаёт конвейер всех проектов.

Проблема B — залипший merge-lease

Merge-gate (ORCH-043) берёт файловый lease <repos_dir>/.merge-lease-<repo>.json ПЕРЕД rebase+re-test и держит его до фактического merge PR в main. Если процесс умирает на финальном merge с зажатым lease:

• Реклейм lease реализован лениво и только по возрасту (age >= merge_lock_timeout_s) и только в момент acquire_merge_lease другой задачей. Проактивного освобождения (на старте / периодически) нет; liveness держателя по pid не проверяется (хотя pid в lease пишется).
• Пострадавшая задача сама re-drive не получает: merge не финализируется → задача висит, lease мешает чужим merge до истечения TTL.

Проблема C — неидемпотентная финализация merge

Если rebase+re-test прошли зелёно (ветка догнана и проверена), но процесс умер до завершения слияния PR — повторного «докатывания» merge нет. Задача застревает в полу-выполненном состоянии, хотя вся дорогая работа (rebase+re-test) уже сделана.

2. Бизнес-последствия

• Это ПОСЛЕДНЯЯ ручная точка автономного деплоя. Без фикса ни одна self-hosting задача не доезжает до прода без оператора (cancel zombie + ручной merge PR + ручной --deploy).
• Прямой блокер эпика ORCH-54.
• Доказанные инциденты (07.06): ORCH-58/60/61/21 — каждый раз после успешного deployer-прохода job оставался running; jobs 236/239/242/254 — зомби, прод-merge/deploy доводились вручную.
• Групповой риск: зомби в общей очереди при concurrency=1 останавливает конвейер enduro-trails и всех прочих проектов.

3. Цель

Сделать так, чтобы смерть процесса/потока на любой стадии (включая self-restart во время deploy) НЕ оставляла навсегда захваченных ресурсов — ни строки jobs в running, ни merge-lease. Конвейер должен самовосстанавливаться без оператора, при этом сохраняя все инварианты self-hosting (не ронять прод-контейнер, не трогать main, fail-closed на реальных ошибках).

4. Объём (Scope)

В объёме

1. Job-reaper — фоновый watchdog (паттерн reconciler/queue_worker), детектирующий «мёртвый» running-job и приводящий его строку в корректный терминальный/повторный статус (done/failed/queued) детерминированно, без LLM. Restart-safe и работающий без рестарта процесса.
2. Проактивный реклейм stale merge-lease — освобождение lease, чей держатель мёртв (pid не жив) ИЛИ возраст превысил TTL — на старте и периодически (reaper/ reconciler), а не только лениво при чужом acquire.
3. Идемпотентная финализация merge — если rebase+re-test зелёные, но merge не состоялся, операция повторяется/докатывается без потери уже сделанной работы.

Вне объёма

• Переход на внешний брокер очередей / смену схемы блокировок merge на БД-lock.
• Полный авто-approve деплоя (ORCH-54) — отдельная задача; здесь только снятие технического блокера.
• Изменение конвейера стадий (STAGE_TRANSITIONS) и реестра гейтов как контрактов.

5. Заинтересованные стороны

• Owner оркестратора (self-hosting автономность).
• Все проекты на общем инстансе (enduro-trails и пр.) — страдают от блокировки общей очереди.

6. Допущения и ограничения

• max_concurrency=1 для self-hosting сохраняется.
• Self-hosting safety (CLAUDE.md): нельзя ронять/рестартить прод-контейнер в рамках задачи; нельзя пушить/форс-пушить main; реклейм lease не должен прерывать легитимно работающий merge.
• Никаких ложных реанимаций: живой, но долгий job не должен помечаться зомби (нужен порог/грейс «N тиков» + проверка реальной смерти, а не просто долготы).
• Контракт never-raise для всей новой фоновой логики (как у reconciler/merge_gate).
• Kill-switch на каждый новый механизм (как reconcile_enabled / merge_gate_enabled).

7. Критерий успеха (бизнес-уровень)

После фикса воспроизводимый сценарий «успешный deployer-проход + смерть процесса/ self-restart» НЕ оставляет зомби-job и зажатого lease: задача либо корректно доезжает до done сама, либо откатывается по штатному контракту — без участия оператора. Регресс-тест на jobs-зомби и stale-lease зелёный.