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>

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 | как есть |