fix(reaper): Tier-2 finalization grace + claim-before-act (no dup advance)

Tier-2 reaped a LIVE, still-finalizing monitor: _monitor_agent writes agent_runs.exit_code FIRST, then does git push / PR / Plane comments before _finalize_job, and the agent pid is already dead in that window — so the old "exit_code recorded -> reap now" had no grace and could race a healthy job. Worse, _reap_known_outcome ran the advance (advance_stage -> enqueue_job) BEFORE the atomic claim, so a reaper that lost the race had already enqueued the next stage (dup advance / dup enqueue), violating ADR-001 Р-1. Fix: - Tier-2 grace: reap only once agent_runs.exit_code has been recorded for >= reaper_finalize_grace_s (new setting, default 300s; > max finalization window). A live finalizing monitor is never reaped (FR-1.3/AC-3). New finished_age_s column computed in get_running_jobs. - claim-before-act for exit0: evaluate the canonical QG READ-ONLY (the reconciler pattern) to choose the terminal status, then atomically claim 'done' FIRST; only the claim winner runs the advance. A loser performs no side effects -> no dup advance / dup enqueue. Docs (golden source) updated in the same change: ADR-001, global adr-0011, README, internals, .env.example, CHANGELOG (also fixes the P3 broken adr-0011 link). New tests cover the grace window, lost-claim no-side-effects, and the already-advanced idempotent path. Refs: ORCH-065 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-07 16:06:27 +00:00
parent c3d9f13870
commit 3e2eb27e7d
10 changed files with 354 additions and 99 deletions
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -207,14 +207,19 @@ ORCH-065 вводит фоновый watchdog, чтобы смерть проц
  работает **без рестарта**. Трёхуровневая liveness: Tier-1 мёртвый `jobs.pid`
  (новая колонка) после `reaper_dead_ticks` подряд тиков (анти-ложноположительность
  — живой долгий агент не реапится); Tier-2 `agent_runs.exit_code` записан, а job
-  ещё `running` (monitor умер между записью exit_code и финализацией); Tier-3
-  backstop по потолку `reaper_max_running_s` (> max agent_timeout+grace). Действие
-  переиспользует контракты: exit0 → **gate-driven idempotent advance**
-  (`_try_advance_stage`+`_finalize_job`, источник истины — канонический QG, не
-  факт «exit0»; нет дубль-перехода); exit≠0/неизвестно → `attempts<max`→`queued`,
-  иначе `failed`+Telegram. Атомарный reap-claim (`UPDATE ... WHERE id=? AND
-  status='running'`) совместим со стартовым `requeue_running_jobs` (restart-safe,
-  без двойной обработки).
+  ещё `running` — но это окно неоднозначно (живой monitor пишет exit_code ПЕРВЫМ,
+  затем git push/PR/Plane-комментарии), поэтому Tier-2 реапит только после
+  finalization-grace `reaper_finalize_grace_s` (живой финализирующий monitor НЕ
+  реапится); Tier-3 backstop по потолку `reaper_max_running_s` (> max
+  agent_timeout+grace). Действие переиспользует контракты по принципу
+  **claim-before-act**: для exit0 канонический QG оценивается read-only ПЕРЕД
+  атомарным claim, затем claim `done` ПЕРВЫМ и только победитель claim делает
+  `_try_advance_stage` (advance+enqueue) — проигравший claim (поздний monitor /
+  стартовый requeue) не выполняет побочных эффектов (нет дубль-advance/-enqueue);
+  источник истины — канонический QG, не факт «exit0»; гейт красный или exit≠0/
+  неизвестно → `attempts<max`→`queued`, иначе `failed`+Telegram. Атомарный
+  reap-claim (`UPDATE ... WHERE id=? AND status='running'`) совместим со стартовым
+  `requeue_running_jobs` (restart-safe, без двойной обработки).
 - **Проактивный реклейм stale/dead lease** (функции в `merge_gate.py`:
  `pid_alive`, `reclaim_stale_lease`) — на старте (рядом с `requeue_running_jobs`)
  и периодически из тика reaper: освобождает lease, чей держатель **мёртв** (pid
@@ -238,7 +243,8 @@ ORCH-065 вводит фоновый watchdog, чтобы смерть проц
  `logger.warning`; reap→`failed` и lease-reclaim → Telegram.
 - **Kill-switch'и:** `ORCH_REAPER_ENABLED`, `ORCH_REAPER_INTERVAL_S`,
  `ORCH_REAPER_DEAD_TICKS`, `ORCH_REAPER_MAX_RUNNING_S`,
-  `ORCH_LEASE_RECLAIM_ENABLED`; `false` → строго прежнее поведение.
+  `ORCH_REAPER_FINALIZE_GRACE_S`, `ORCH_LEASE_RECLAIM_ENABLED`; `false` → строго
+  прежнее поведение.

 Подробнее: [adr-0011](adr/adr-0011-job-reaper-lease-reclaim.md), детально —
 `docs/work-items/ORCH-065/06-adr/ADR-001-job-reaper-and-lease-reclaim.md`.
--- a/docs/architecture/adr/adr-0011-job-reaper-lease-reclaim.md
+++ b/docs/architecture/adr/adr-0011-job-reaper-lease-reclaim.md
@@ -28,13 +28,18 @@ self-restart во время deploy) оставляет строку `jobs` на
   never-raise, `_stop`-Event, старт/стоп в `lifespan`, снимок в `/queue`,
   kill-switch). Работает **без рестарта** процесса. Liveness — трёхуровневая:
   Tier-1 мёртвый `jobs.pid` (новая колонка) после `reaper_dead_ticks` подряд
-   тиков; Tier-2 `agent_runs.exit_code` записан, а job ещё `running`; Tier-3
-   backstop по потолку `reaper_max_running_s`. Действие переиспользует контракты:
-   exit0 → gate-driven idempotent advance (`_try_advance_stage`+`_finalize_job`,
-   источник истины — QG, не «exit0»); exit≠0 / неизвестно → `attempts<max` →
-   `queued`, иначе `failed`+Telegram. Атомарный reap-claim (`UPDATE ... WHERE
-   id=? AND status='running'` + `rowcount`, как `claim_next_job`) исключает
-   двойную обработку (совместимость со стартовым `requeue_running_jobs`).
+   тиков; Tier-2 `agent_runs.exit_code` записан, а job ещё `running` — но только
+   после finalization-grace `reaper_finalize_grace_s` (окно неоднозначно: живой
+   monitor пишет exit_code ПЕРВЫМ, затем git push/PR/Plane-комментарии, поэтому
+   живой финализирующий monitor НЕ реапится); Tier-3 backstop по потолку
+   `reaper_max_running_s`. Действие — **claim-before-act**: для exit0 канонический
+   QG оценивается read-only ПЕРЕД атомарным claim, затем claim `done` ПЕРВЫМ и
+   только победитель claim выполняет `_try_advance_stage` (advance+enqueue) —
+   проигравший не делает побочных эффектов (источник истины — QG, не «exit0»);
+   гейт красный или exit≠0 / неизвестно → `attempts<max` → `queued`, иначе
+   `failed`+Telegram. Атомарный reap-claim (`UPDATE ... WHERE id=? AND
+   status='running'` + `rowcount`, как `claim_next_job`) исключает двойную
+   обработку (совместимость со стартовым `requeue_running_jobs`).
 2. **Проактивный реклейм stale/dead lease** — функции в `merge_gate.py`
   (`pid_alive`, `reclaim_stale_lease`), вызываемые на старте (рядом с
   `requeue_running_jobs`) и периодически из тика reaper. Освобождение, если
@@ -49,9 +54,9 @@ self-restart во время deploy) оставляет строку `jobs` на
   (паттерн live-safe миграции). Больше ничего не меняется.

 Kill-switch'и (`ORCH_*`): `reaper_enabled`, `reaper_interval_s`,
-`reaper_dead_ticks`, `reaper_max_running_s`, `lease_reclaim_enabled`;
-переиспользуются `merge_lock_timeout_s`, `merge_gate_repos`. `false` → строго
-прежнее поведение.
+`reaper_dead_ticks`, `reaper_max_running_s`, `reaper_finalize_grace_s`,
+`lease_reclaim_enabled`; переиспользуются `merge_lock_timeout_s`,
+`merge_gate_repos`. `false` → строго прежнее поведение.

 ## Альтернативы
 - Reaper внутри reconciler — отвергнуто (смешение stage- и jobs-уровней, общий
--- a/docs/architecture/internals.md
+++ b/docs/architecture/internals.md
@@ -354,13 +354,20 @@ daemon-поток `src/job_reaper.py` (каркас `reconciler`) периоди
 - **Tier-1** — `jobs.pid` мёртв (`os.kill(pid,0)`→`ProcessLookupError`) на
  протяжении `reaper_dead_ticks` подряд тиков (анти-ложноположительность);
 - **Tier-2** — у `agent_runs[run_id]` записан `exit_code`, а `jobs.status` ещё
-  `running` (monitor умер между записью exit_code и `_finalize_job`);
+  `running`. Окно неоднозначно: живой monitor пишет `exit_code` ПЕРВЫМ, затем
+  git push/PR/Plane-комментарии (секунды-десятки секунд) и лишь потом
+  `_finalize_job`; pid агента к этому моменту мёртв в обоих случаях. Поэтому
+  Tier-2 реапит только после finalization-grace `reaper_finalize_grace_s`
+  (`finished_age_s >= grace`) — живой финализирующий monitor НЕ реапится;
 - **Tier-3** — backstop: job висит `running` дольше `reaper_max_running_s`.

 Реап атомарен (`UPDATE jobs SET ... WHERE id=? AND status='running'` + `rowcount`,
 как `claim_next_job`) → совместим со стартовым `requeue_running_jobs` без двойной
-обработки. Действие переиспользует контракты: exit0 → gate-driven
-`_try_advance_stage`+`_finalize_job` (источник истины — QG); exit≠0/неизвестно →
+обработки. Действие — **claim-before-act**: для exit0 канонический QG оценивается
+read-only ПЕРЕД атомарным claim, затем claim `done` ПЕРВЫМ и только победитель
+claim делает `_try_advance_stage` (advance+enqueue) — проигравший (поздний monitor
+/ стартовый requeue) не выполняет побочных эффектов (нет дубль-advance/-enqueue);
+источник истины — QG, не «exit0»; гейт красный или exit≠0/неизвестно →
 `attempts<max`→`queued`, иначе `failed`+Telegram. Тот же поток на старте и
 периодически делает проактивный реклейм stale/dead merge-lease (`merge_gate.py`:
 `pid_alive`/`reclaim_stale_lease`). never-raise; kill-switch `ORCH_REAPER_ENABLED`
--- a/docs/work-items/ORCH-065/06-adr/ADR-001-job-reaper-and-lease-reclaim.md
+++ b/docs/work-items/ORCH-065/06-adr/ADR-001-job-reaper-and-lease-reclaim.md
@@ -65,9 +65,18 @@ liveness процесса). Это разные never-raise-домены и ра
   `pid_alive(pid)` = `os.kill(pid, 0)` с обработкой `ProcessLookupError` (мёртв)
   / `PermissionError` (жив, чужой) — единственный сигнал, ловящий «monitor умер
   ДО записи `finished_at`».
-2. **Tier-2 (completion race): exit_code записан, job ещё `running`.** Если у
-   `agent_runs[run_id]` есть `finished_at`/`exit_code`, а `jobs.status='running'`
-   — monitor умер между записью exit_code и `_finalize_job`. Здесь исход **известен**.
+2. **Tier-2 (completion race): exit_code записан, job ещё `running`.** Окно
+   **неоднозначно**: это И «monitor умер между записью exit_code и
+   `_finalize_job`», И «живой monitor ещё финализирует» — `_monitor_agent`
+   пишет `exit_code` ПЕРВЫМ, затем git commit/push (+PR), БАГ-8-проверку и
+   сетевые usage-комментарии в Plane (секунды-десятки секунд), и лишь потом
+   `_try_advance_stage` → `_finalize_job`. pid агента к этому моменту уже мёртв в
+   ОБОИХ случаях, поэтому по pid их не различить. **Анти-ложноположительность
+   Tier-2 (FR-1.3, AC-3): finalization-grace.** Job реапится по Tier-2 только
+   когда `exit_code` записан не меньше `reaper_finalize_grace_s` назад (потолок
+   заведомо > максимального окна финализации). В пределах grace строка не
+   трогается (живой финализирующий monitor НИКОГДА не реапится; нет дубль-advance
+   / дубль-enqueue). После grace monitor заведомо мёртв → исход **известен**.
 3. **Tier-3 (backstop по потолку):** job висит `running` дольше
   `reaper_max_running_s` (заведомо > max `agent_timeout`+grace). Реап даже когда
   liveness определить нельзя (pid переиспользован/неизвестен).
@@ -87,18 +96,23 @@ liveness процесса). Это разные never-raise-домены и ра
  flip несёт guard `WHERE id=? AND status='running'` и проверяет `rowcount`. При
  гонке (поздно доехавший monitor, стартовый `requeue_running_jobs`) проигравший
  видит `rowcount==0` и НЕ обрабатывает строку повторно (AC-5).
- **Исход известен (Tier-2, exit_code в `agent_runs`):** маршрутизируем через
-  существующий `launcher._finalize_job(job_id, agent, run_id, exit_code,
-  output_path)`:
-  - `exit==0`: **gate-driven idempotent advance.** Сначала проверяем, не
-    продвинулась ли уже стадия (текущая `tasks.stage` ≠ исходная стадия агента
-    или активного job нет и гейт уже пройден) → если да, просто `mark_job(done)`
-    (идемпотентная уборка, без дубль-перехода). Если нет — `_try_advance_stage`
-    (он сам гоняет канонический QG: артефакт/PR есть → зелёный гейт → advance;
-    нет → красный гейт → НЕ advance), затем `_finalize_job`. **Источник истины —
-    гейт, не «exit0»** — это исключает ложный `done` без реально выполненной
-    работы (если monitor умер ДО git-push, артефакта нет → гейт красный →
-    переходим к ветке «исход неуспешен» ниже).
+- **Исход известен (Tier-2, exit_code в `agent_runs`, grace прошёл):**
+  - `exit==0`: **claim-BEFORE-act, gate-driven idempotent advance.** Порядок
+    критичен (см. «Атомарный reap-claim» выше): атомарный claim ОБЯЗАН
+    предшествовать любому `advance_stage`/`enqueue_job`. Поскольку claim
+    переводит строку ИЗ `running`, прогнать advance ДО claim, чтобы узнать цвет
+    гейта, нельзя — поэтому канонический QG оценивается **read-only, без
+    побочных эффектов** (тот же `_run_qg`, что у reconciler) ПЕРЕД claim:
+    - стадия уже продвинута мимо этого агента → атомарный `done` без advance
+      (идемпотентная уборка);
+    - гейт зелёный → атомарный claim `done` ПЕРВЫМ, и только победитель claim
+      выполняет `_try_advance_stage` (advance + `enqueue_job` следующей стадии)
+      РОВНО один раз; проигравший claim (поздний monitor / стартовый
+      `requeue_running_jobs`) НЕ делает побочных эффектов (нет дубль-advance /
+      дубль-enqueue);
+    - гейт красный (monitor умер ДО git-push, артефакта нет) → НЕ выдумываем
+      `done`, уходим в ветку «исход неуспешен» ниже.
+    **Источник истины — гейт, не «exit0».**
  - `exit!=0`: ровно существующий контракт `_finalize_job` (классификация
    transient/permanent, `attempts<max` → `queued`, иначе `failed`+Telegram).
 - **Исход неизвестен (Tier-1 мёртвый pid без exit_code, или Tier-3 backstop):**
@@ -177,6 +191,7 @@ logic».
 | `reaper_interval_s` | период сканирования | `60` |
 | `reaper_dead_ticks` | подряд тиков мёртвого pid перед реапом (Tier-1) | `2` |
 | `reaper_max_running_s` | потолок `running` (Tier-3 backstop), > max agent_timeout+grace | `3600` |
+| `reaper_finalize_grace_s` | Tier-2 grace: сколько `exit_code` должен быть записан до реапа (> max окна финализации) | `300` |
 | `lease_reclaim_enabled` | kill-switch проактивного реклейма lease | `True` |
 | (reuse) `merge_lock_timeout_s` | TTL lease | `300` |
 | (reuse) `merge_gate_repos` | область применения lease-reclaim | как есть |