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

docs/architecture/internals.md

@@ -326,6 +326,7 @@ webhook (plane/gitea)                 background thread (queue_worker)
 | `status` | `queued` → `running` → `done` \| `failed` |
 | `attempts` / `max_attempts` | счётчик попыток (инкремент при claim) / лимит ретраев (default 2) |
 | `run_id` | FK на `agent_runs.id` после старта |
+| `pid` | (ORCH-065) pid агентского процесса (`proc.pid` из `_spawn`); liveness-сигнал для job-reaper. Добавляется `_ensure_column` (idempotent) |
 | `task_content` | ТЗ, которое пишется в task-файл агента |
 | `error` | последняя ошибка |
 
@@ -343,6 +344,29 @@ status='queued'` и проверяет `rowcount`. При гонке двух т
 jobs со статусом `running` (воркер умёр на рестарте) → возвращаются в `queued`.
 Потом стартует воркер; на shutdown — `worker.stop()` (Event.set + join).
 
+### Job-reaper (ORCH-065, рестарт НЕ требуется)
+
+`requeue_running_jobs()` спасает ТОЛЬКО на старте процесса. Зомби-job, возникший
+**без** рестарта (умер monitor-поток/дочерний процесс, а сервис жив), оставался
+`running` навсегда и при `max_concurrency=1` блокировал всю очередь. Фоновый
+daemon-поток `src/job_reaper.py` (каркас `reconciler`) периодически
+(`reaper_interval_s`) сканирует `running`-jobs и реапит «мёртвые»:
+- **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`);
+- **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/неизвестно →
+`attempts<max`→`queued`, иначе `failed`+Telegram. Тот же поток на старте и
+периодически делает проактивный реклейм stale/dead merge-lease (`merge_gate.py`:
+`pid_alive`/`reclaim_stale_lease`). never-raise; kill-switch `ORCH_REAPER_ENABLED`
+/ `ORCH_LEASE_RECLAIM_ENABLED`; снимок в `GET /queue` (блок `reaper`). Подробнее —
+adr-0011.
+
 ### Конфиг
 
 - `ORCH_MAX_CONCURRENCY` (default 1) — лимит параллельных jobs.