# ORCH-83 — ЭПИК: Наблюдаемость орка (мониторинг + алертинг + дашборд + агент сопровождения)

**Автор:** Стрим · **Дата:** 2026-06-08 · **Заказчик:** Слава
**Стратегический кирпич:** НАБЛЮДАЕМОСТЬ (5-й в стратегии автономности: целостность ✅ → координация ✅ → … → наблюдаемость 🔜)

---

## 0. Зачем (триггер)

Сегодня всплыли три «слепые зоны», которые система мониторинга поймала бы сама:
1. **Agent liveness:** analyst (ORCH-81) «завис» на 22+ мин — пришлось вручную лезть в `/proc/PID/stat`, считать CPU-тики, чтобы понять «думает или мёртв». **Нет индикации что агент работает.**
2. **Диск хоста 93%** (8 ГБ из 118) — обнаружено случайно при scan. Никто не алертит. Риск для орка/Plane/Gitea/Postgres.
3. **Merge-баг (074/081)** — задачи молча застревали на HOLD; узнавали только когда Слава спрашивал «что там».

**Вывод:** орк уже автономен в исполнении (целостность+координация в проде), но **слеп** — оператор (Слава/Стрим) узнаёт о проблемах реактивно, вручную, через ssh+docker+sqlite. Нужна **проактивная наблюдаемость**.

## 1. Что мониторить (полная карта инфры — собрана 08.06)

### Сам орк (приложение)
- Стадии задач: какой stage, как давно (детект застреваний типа merge-HOLD).
- Очередь jobs: queued/running/failed, глубина, ретраи, breaker (429).
- **Agent liveness:** какой агент запущен, run_id, pid, сколько работает, ЖИВ ли (CPU/heartbeat), не превысил ли разумный таймаут. ← прямой ответ на сегодняшнюю боль.
- Стоимость/токены (agent_runs: cost_usd, tokens) — экономика.
- Эндпоинты уже есть: `/health`, `/status`, `/queue` (src/main.py) — фундамент.

### Инфраструктура хоста (82.22.50.71)
- **Диск** (сейчас 93%! критично), inode, рост `/var/lib/docker`.
- **Память** (7.7Gi всего, 442Mi free — впритык).
- CPU/load.

### Контейнеры (docker ps — 21 контейнер)
- orchestrator, orchestrator-staging, gitea, plane-app-* (14 контейнеров!), claude-cli-proxy, xray, enduro-trails, osrm, openclaw-gateway.
- Статус Up/healthy/restarting/exited, рестарты, потребление.
- **Зависимости орка:** gitea (merge/PR), plane (задачи), claude-cli-proxy (LLM — `Up 3 weeks`, кандидат на деградацию → могла быть причина «зависа» analyst!), postgres плейна.

### Внешние зависимости
- Plane API доступность, Gitea API, claude-cli-proxy латентность (← подозрение по ORCH-81 зависанию).

## 2. Четыре слоя эпика (декомпозиция)

| Под-задача | Слой | Суть | Приоритет |
|---|---|---|---|
| **ORCH-83a** | СБОР | Метрики: agent-liveness (pid/CPU/runtime/таймаут), очередь, стадии, диск/память/контейнеры/деп-сервисы. Расширить `/status`/`/metrics`. | HIGH |
| **ORCH-83b** | АЛЕРТИНГ | Правила + пороги (диск>85%, агент>N мин без прогресса, job failed, контейнер down, dep-сервис недоступен) → уведомление в Telegram (как уже шлёт орк). Дедуп/throttle. | HIGH |
| **ORCH-83c** | ДАШБОРД | Веб-дэш: задачи/очередь/агенты/инфра в одном месте (live). Behind nginx как noisemap/snowbike. | MEDIUM |
| **ORCH-83d** | АГЕНТ СОПРОВОЖДЕНИЯ | Агент-SRE: отслеживает → реагирует → исправляет (рестарт зависшего агента, чистка диска, пере-пуш PR) → развивает. Над системой мониторинга. | MEDIUM→HIGH |

## 3. Ключевые принципы (стратегия)

- **Наблюдаемость:** «не лезть в ssh+sqlite вручную» — состояние орка видно сразу.
- **Проактивность:** алерт ДО того как Слава спросит «что там».
- **Не мешать автономности:** мониторинг read-only по умолчанию; агент сопровождения действует осторожно (как Стрим — штатными механизмами, не ручным reset).
- **Экономно:** лёгкие проверки (не жечь токены/CPU); агент сопровождения — дешёвая модель где можно (но это не G3-routing орка, отдельный агент).
- **Self-hosting safety:** мониторинг орка не должен ронять орк.

## 4. Связь с существующим
- Орк УЖЕ шлёт в Telegram (notifications.py) — переиспользовать транспорт для алертов.
- Есть JobReaper (max_running_s=3600) — расширить/сделать видимым (агент-liveness).
- Heartbeat Стрим (HEARTBEAT.md) уже частично watchdog'ит — формализовать в систему.
- ORCH-21 post-deploy-monitor — точечный мониторинг деплоя, частный случай.

## 5. Открытые вопросы к Славе
- Стек дашборда: свой Flask (как noisemap) ИЛИ готовое (Grafana+Prometheus)? Готовое мощнее, но +контейнеры на и так забитый хост (диск 93%!).
- Агент сопровождения: новый агент орка (analyst-стиль) ИЛИ отдельный сервис ИЛИ роль Стрим?
- Приоритет внутри эпика: что первым — liveness-индикация (горит) или диск-алерт (тоже горит)?