docs(ORCH-009): staging gate log — SUCCESS (8/10, C9a/C9b infra-waived)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -465,3 +465,48 @@ ORCH_POST_DEPLOY_BASE_URL=http://localhost:8500
 # DB title TEXT is unbounded). Default 200. An invalid/empty value gracefully
 # degrades to 200 (the process never crashes on startup).
 ORCH_QG0_TITLE_MAX=200
+
+# ── ORCH-100 (FND/F1b): sidecar-watchdog (orchestrator-watchdog container) ─────
+# The monitoring brain runs in a SEPARATE container with its OWN config. These
+# keys are read by the watchdog package (watchdog/config.py), NOT by the
+# orchestrator. At runtime they live in `.env.watchdog` (env_file of the
+# orchestrator-watchdog service); this block is the canon. NO real secrets here.
+#   ENABLED        -> kill-switch; false (or not starting the service) -> inert.
+#   INTERVAL_S     -> seconds between ticks.
+#   HTTP_TIMEOUT_S -> per-request timeout (metrics / pings / docker / telegram).
+#   COOLDOWN_S     -> re-alert throttle for a sustained signal (anti-spam).
+#   METRICS_URL    -> orchestrator /metrics (host-network -> 127.0.0.1:8500).
+#   ORCH_DOWN_TICKS-> K consecutive /metrics failures before "орк не отвечает".
+#   MEM_PCT        -> host memory used-% threshold.
+#   DISK_CRIT_*    -> OPT-IN independent disk CEILING (disk_watchdog/ORCH-063 owns
+#                     the 85% alert; this is a higher ceiling on the sidecar's own
+#                     channel, OFF by default -> no double disk-alert, AC-5/D6).
+#   DISK_PATHS     -> host paths measured for the opt-in ceiling.
+#   AGENT_HUNG_MIN -> runtime minutes before an agent with ~0 CPU is "hung".
+#   AGENT_CPU_FLOOR-> CPU fraction below which a long-running agent counts as hung.
+#   STAGE_STUCK_MIN-> minutes a task may sit in one stage before alerting.
+#   QUEUE_DEPTH    -> queued-job depth threshold.
+#   CONTAINERS     -> CSV of container names to watch (status != running/healthy).
+#   DOCKER_SOCK    -> path to the read-only docker.sock inside the container.
+#   DEPS           -> CSV of name=url dependency pings (empty -> no pings).
+#   TG_BOT_TOKEN / TG_CHAT_ID -> the sidecar's OWN Telegram bot/chat (independent
+#                     of the orchestrator's; absent -> logs, does not send).
+WATCHDOG_ENABLED=true
+WATCHDOG_INTERVAL_S=30
+WATCHDOG_HTTP_TIMEOUT_S=5
+WATCHDOG_COOLDOWN_S=1800
+WATCHDOG_METRICS_URL=http://127.0.0.1:8500/metrics
+WATCHDOG_ORCH_DOWN_TICKS=3
+WATCHDOG_MEM_PCT=90
+WATCHDOG_DISK_CRIT_ENABLED=false
+WATCHDOG_DISK_CRIT_PCT=97
+WATCHDOG_DISK_PATHS=/repos,/app/data
+WATCHDOG_AGENT_HUNG_MIN=20
+WATCHDOG_AGENT_CPU_FLOOR=0.01
+WATCHDOG_STAGE_STUCK_MIN=120
+WATCHDOG_QUEUE_DEPTH=20
+WATCHDOG_CONTAINERS=orchestrator
+WATCHDOG_DOCKER_SOCK=/var/run/docker.sock
+WATCHDOG_DEPS=
+WATCHDOG_TG_BOT_TOKEN=
+WATCHDOG_TG_CHAT_ID=

.task-dev.md

@@ -1,4 +1,4 @@
-Work item: ORCH-057
+Work item: ORCH-100
 Repo: orchestrator
-Branch: feature/ORCH-057-bug-follow-up-orch-040-normali
+Branch: feature/ORCH-100-fnd-f1b-sidecar-watchdog
 Stage: development

CHANGELOG.md

@@ -3,6 +3,23 @@
 Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
 
 ## [Unreleased]
+- **Машинный журнал уроков `lessons`** (ORCH-098, `feat`): шаг 1 («Фундамент», F2) эпика саморазвития — формализует свободнотекстовые «уроки» из `memory/` в **машинную структурированную таблицу отклонений конвейера** `lessons`, фундамент для будущих ретроспективщика (E2), приоритизатора RICE (E3) и Стрим. Чистый **observer-leaf** `src/lessons.py` (never-raise, kill-switch, паттерн `serial_gate`/`coverage_gate`/`metrics`): `record()`/`get()`/`update()`/`snapshot()`. **Инвариант:** журнал — наблюдатель, **не** Quality Gate — `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схемы существующих таблиц байт-в-байт не тронуты; enduro не затронут. ADR: `docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md`, сквозной `docs/architecture/adr/adr-0034-lessons-journal.md`.
+  - **Таблица (D1, FR-1):** аддитивная идемпотентная `lessons` (`CREATE TABLE IF NOT EXISTS` в `db.init_db()` + три индекса, restart-safe) — контекст (`work_item_id`/`task_id`/`stage`/`agent`/`repo`), анализ (`root_cause`/`suggestion`), статус (`status`/`related_task`), **колонки атрибуции — сразу и нуллабельно** (`attribution`/`target_repo`/`target_domain`, требование Славы 10.06 / NFR-6, заполняется позже через update; `_ensure_column` форвард-safe на старой таблице) + `source`/`detail`; без `enum`-констрейнтов (слаги forward-compatible). Хелперы `db.record_lesson`/`get_lessons`/`update_lesson`/`lessons_snapshot`/`lessons_recent_dup_exists`.
+  - **НЕ скоупится по репо (D2):** журнал observer-only → единственный регулятор — глобальный kill-switch `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`); **`lessons_repos` НЕ вводится**. Recorder пишет уроки про **любой** репо (включая enduro-trails); репо-разрез — на **выборке** (`get(repo=…)`).
+  - **Автозапись 4 типов (D3, FR-3):** тонкие best-effort врезки (`source="auto"`, never-raise, дедуп) — `gate_failure` (`stage_engine._handle_qg_failure_rollbacks`, откат на `development`), `merge_hold` (`stage_engine._handle_merge_verify` HOLD), `transient_retry` (`launcher._finalize_transient` на исчерпании бюджета ретраев), `deploy_degraded` (post-deploy `DEGRADED → set_repo_freeze`, урок слоя-3 «деплой OK / прод сломан» ET-8).
+  - **Дедуп (D4):** для `auto` — один indexed-SELECT по `idx_lessons_wi_type`: дубль `(work_item_id, lesson_type, stage)` в окне `lessons_dedup_window_s` (env, дефолт 3600с) → no-op; `manual` не дедупится.
+  - **Эндпоинты (D5, FR-4/5):** `GET /lessons` (read-only, фильтры `type`/`status`/`repo`/`work_item`/`limit`), `POST /lessons` (ручная запись), `POST /lessons/{id}` (доклассификация/update); read-only ключ `lessons` в `GET /queue`. Выключенный флаг → `{"enabled": false}`.
+  - **Регресс:** kill-switch `lessons_enabled=False` → полная инертность (no-op без обращения к БД); never-raise на всех публичных функциях/врезках — сбой журнала не роняет конвейер; аддитивно (новая таблица + leaf + эндпоинты + тонкие врезки). Флаги `config.py`: `lessons_enabled`/`lessons_query_limit_default`/`lessons_dedup_window_s`. Тесты `tests/test_lessons.py` (TC-01…TC-12, unit+integration).
+- **FND/F1b: sidecar-watchdog — мозг мониторинга в отдельном контейнере** (ORCH-100, `feat`): новая папка `watchdog/` (тонкий **Python-3.12-stdlib-only** демон) + сервис `orchestrator-watchdog` в `docker-compose.yml` (`network_mode: host`, read-only `docker.sock`, `mem_limit: 128m`). Вторая половина пары наблюдаемости домена 0: F1a (ORCH-099) отдаёт `GET /metrics` (сырьё), F1b — **мозг**, который это сырьё читает, дополняет внешними сигналами (хост/контейнеры/зависимости) и превращает в **алерты** через **собственный** независимый Telegram-канал. **`src/**` НЕ изменён** — F1b потребитель `/metrics`; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД орка — байт-в-байт. Аддитивно, под kill-switch `WATCHDOG_ENABLED`, строго read-only к наблюдаемому (self-hosting-безопасно). ADR: `docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md`, сквозной `docs/architecture/adr/adr-0033-sidecar-watchdog.md`.
+  - **fix(test): изоляция `settings.runs_dir` в conftest** — устранена амбиентная prod-зависимость, валившая `test_queue.py::TestRetry::test_finalize_job_requeue_then_fail` в self-hosting-окружении (TC-14 «full tests/ regression green»). `launcher._finalize_job` классифицирует падение по хвосту `<settings.runs_dir>/<run_id>.log`; `runs_dir` по умолчанию = живой prod-каталог `/app/data/runs`, где на хосте накоплены РЕАЛЬНЫЕ логи агентов (`2.log` содержит `429` → 'transient'), поэтому тест с литеральным `run_id=2` читал чужой prod-лог и получал requeue вместо `failed`. Новый autouse-фикстур `_isolate_runs_dir` в `tests/conftest.py` (по образцу `_no_telegram`/`_disable_merge_verify`) перенаправляет `runs_dir` в пер-тестовый tmp → `_run_log_path()` указывает на несуществующий файл → `classify_log_file()` отдаёт документированный дефолт 'permanent'. Детерминизм всей сюты восстановлен (1617 passed); `src/**` не тронут.
+  - **Стек (D1):** Python 3.12 stdlib-only на `python:3.12-slim` — `urllib` (HTTP `/metrics` + пинги + Telegram POST), сырой HTTP-over-unix-socket для read-only `docker.sock` (БЕЗ pip-пакета `docker`), `shutil.disk_usage`/`/proc/meminfo` для хоста. Нет дерева зависимостей (тонкость, C-3). Отдельный образ `watchdog/Dockerfile` (build-контекст = корень репо; `src/**` НЕ копируется — изоляция C-1).
+  - **Топология (D2):** сервис собирается из `watchdog/Dockerfile`, `restart: unless-stopped` (самовосстановление), `network_mode: host` → `/metrics` достижим как `http://127.0.0.1:8500/metrics`; `docker.sock` смонтирован `:ro` И код GET-only (двойная гарантия read-only); хост-пути bind-mount `:ro`; `mem_limit: 128m`+`mem_reservation: 32m`. `env_file` опционален (`required: false`) → отсутствие `.env.watchdog` НЕ ломает `docker compose up` прод-орка. Деплой watchdog поднимает ТОЛЬКО его — прод `orchestrator` не пересобирается/не рестартится.
+  - **Обобщённая чистая решающая функция (D4):** `watchdog/decision.py::decide(signal_active, prev, now, cooldown_s) -> alert|realert|recovery|none` — строгая генерализация `disk_watchdog.decide_action` (булев `signal_active` вместо `used_pct >= threshold`), per-signal in-memory `AlertState` (анти-спам/recovery, рестарт сбрасывает → корректный повторный алерт стоящей проблемы).
+  - **Реестр сигналов (D5):** `orch_down` (K=3 подряд неудачных `/metrics` — debounce, не флаппит на одиночной икоте), `host_mem` (≥90%), `host_disk_crit` (opt-in потолок 97%, default off — D6), `agent_hung` (per run_id, два опроса: `runtime > N` И доля CPU `< floor`), `stage_stuck` (per work_item), `job_failed` (edge, рост счётчика), `queue_depth` (≥20), `container_down` (per name, статус ∉ {running,healthy}), `dep_down` (per name, пинг Plane/Gitea/Anthropic). Все пороги/интервалы/URL/токены — из env (`WATCHDOG_*`, канон в `.env.example`).
+  - **Анти-дубль диск-алерта (D6, AC-5):** штатные 85% остаются ЕДИНСТВЕННО за `disk_watchdog` (ORCH-063) → **нулевой дубль по построению**; вклад sidecar — `orch_down` (когда орк лёг, in-process стражи мертвы) + **opt-in** независимый потолок `host_disk_crit` (97%, default off) как резерв канала. Один владелец на порог.
+  - **Независимый транспорт (D7):** `watchdog/notify.py` читает **свои** `WATCHDOG_TG_BOT_TOKEN`/`WATCHDOG_TG_CHAT_ID`, **запрещён** импорт `src/notifications.py`/токена орка (падение орка не утянет алерт-канал). Отсутствие токена → fail-safe (логирует, не шлёт, не падает).
+  - **never-raise + kill-switch (D8):** три уровня (per-source: битый коллектор деградирует один сигнал; per-tick: внешний try/except цикла; per-send: обёрнутая отправка). `WATCHDOG_ENABLED=false` → демон инертен (idle-loop с логом, НЕ exit — чтобы restart-policy не крутил петлю). Толерантность к версии `/metrics` (D9): неизвестные поля игнорируются, рост `schema_version` логируется (warning) без крэша.
+  - Тесты: `tests/watchdog/test_*.py` (TC-01…TC-13: решение/orch-down/never-raise/kill-switch/full-tick/docker-readonly/notify-isolation/metrics-parse/compose/disk-dedup + коллекторы host/deps) + полный регресс `tests/ -q` зелёный (TC-14, `src/**` не тронут). **Инфра-предусловие** (07): добавить сервис в compose, создать bot/chat watchdog + `.env.watchdog`, первый запуск на хосте. Откат: не запускать сервис / `WATCHDOG_ENABLED=false`.
 - **Багфикс-трек: упрощённый/дешёвый маршрут конвейера для багов** (ORCH-019, `feat`): задача с меткой Plane `Bug` идёт **укороченным маршрутом** — пропускается стадия `architecture` (отдельный прогон opus-агента `architect` + ADR + exit-гейт `check_architecture_done`), тяжёлая аналитика заменяется облегчённым пакетом (короткий bug-report + обязательный план регресс-теста). **Все Quality Gate'ы исполняются без изменений** (корневой инвариант NFR-1): `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / сигнатуры `check_*` / machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/`coverage_status:`) — байт-в-байт прежние; маршрутизация багфикса — свойство планировщика, **не** гейт. Аддитивно, под kill-switch, с областью репо, never-raise, fail-safe → полный цикл. ADR: `docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md`, сквозной `docs/architecture/adr/adr-0032-bug-fast-track.md`.
   - **Классификация (D1, FR-1):** новый leaf `src/bug_fast_track.py` (never-raise, паттерн `labels`/`serial_gate`). `bug_fast_track_applies(repo)` (локально, без сети) проверяется ПЕРВЫМ → выключенный флаг = нулевой сетевой оверхед; `is_bug_task(work_item_id, project_id)` делегирует в проверенный `labels.has_label` (ORCH-089: `fetch_issue_labels`+`get_project_labels`, нормализация, TTL-кэш). **Источник истины — Plane API**, не payload вебхука. Чтение метки — только в `start_pipeline`, **никогда** в горячем `claim_next_job` (NFR-4).
   - **Хранение типа (D2):** аддитивная идемпотентная колонка `tasks.track TEXT DEFAULT 'full'` (`_ensure_column`, паттерн `tasks.cancelled_at` ORCH-090); значения `'full'` (дефолт, ВСЕ существующие и не-баг задачи) | `'bug'`. Хелперы `db.set_task_track`/`db.get_task_track` (отсутствие/NULL → `'full'`, fail-safe). Сигнатура `create_task_atomic` не меняется.

CLAUDE.md

@@ -235,6 +235,44 @@ kill-switch, never-raise, fail-safe → полный цикл.
   `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md`,
   `docs/architecture/adr/adr-0029-coverage-gate.md`.
 
+## Машинный журнал уроков (ORCH-098)
+Шаг 1 («Фундамент», F2) эпика саморазвития: формализует свободнотекстовые «уроки» из `memory/` в
+**машинную структурированную таблицу отклонений конвейера** `lessons`, фундамент для будущих
+ретроспективщика (E2), приоритизатора RICE (E3) и Стрим. Чистый **observer-leaf** `src/lessons.py`
+(never-raise, kill-switch, паттерн `serial_gate`/`coverage_gate`/`metrics`): `record()`/`get()`/
+`update()`/`snapshot()`. **Инвариант:** журнал — наблюдатель, **не** Quality Gate; запись урока
+никогда не влияет на продвижение по стадиям — `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/
+machine-verdict/схемы существующих таблиц байт-в-байт не тронуты.
+- **Таблица (D1):** аддитивная идемпотентная `lessons` (`CREATE TABLE IF NOT EXISTS` в `init_db()`,
+  три индекса) — контекст (`work_item_id`/`task_id`/`stage`/`agent`/`repo`), анализ (`root_cause`/
+  `suggestion`), статус (`status`/`related_task`), **атрибуция сразу и нуллабельно** (`attribution`/
+  `target_repo`/`target_domain`, требование Славы 10.06 / NFR-6, заполняется позже через update;
+  `_ensure_column` форвард-safe на старой таблице) + `source`/`detail`. Без `enum`-констрейнтов —
+  значения суть forward-compatible слаги. Хелперы `db.record_lesson`/`get_lessons`/`update_lesson`/
+  `lessons_snapshot`/`lessons_recent_dup_exists`.
+- **НЕ скоупится по репо (D2):** в отличие от гейт-leaf'ов (`serial_gate`/`coverage_gate` имеют
+  `*_repos`, т.к. *действуют* на репо), журнал observer-only → единственный регулятор — глобальный
+  kill-switch `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`); **`lessons_repos` НЕ
+  вводится**. Recorder пишет уроки про **любой** репо (включая enduro-trails — урок ценен для петли);
+  репо-разрез — на **выборке** (`get(repo=…)`). enduro не затронут (общая БД, аддитивная таблица).
+- **Автозапись 4 типов (D3):** тонкие best-effort врезки (`source="auto"`, never-raise, дедуп) —
+  `gate_failure` (`stage_engine._handle_qg_failure_rollbacks`, откат на `development`), `merge_hold`
+  (`stage_engine._handle_merge_verify` HOLD-ветка), `transient_retry` (`launcher._finalize_transient`
+  на **исчерпании** бюджета ретраев, а не на каждом backoff), `deploy_degraded` (post-deploy
+  `DEGRADED → set_repo_freeze`, урок слоя-3 «деплой OK / прод сломан» ET-8 — `attribution="unknown"`,
+  классифицируется позже).
+- **Дедуп (D4):** для `source="auto"` — один indexed-SELECT по `idx_lessons_wi_type`: дубль с тем же
+  `(work_item_id, lesson_type, stage)` в окне `lessons_dedup_window_s` (env, дефолт 3600с) → no-op.
+  `source="manual"` дедуп НЕ проходит (оператор/Стрим всегда пишут).
+- **Эндпоинты (D5):** `GET /lessons` (read-only, фильтры `type`/`status`/`repo`/`work_item`/`limit`),
+  `POST /lessons` (ручная запись, `source="manual"`), `POST /lessons/{id}` (доклассификация/update);
+  read-only ключ `lessons` в `GET /queue`. Выключенный флаг → `{"enabled": false}`.
+- **never-raise (NFR-1):** все публичные функции и врезки изолированы (`try/except` → warning +
+  безопасный дефолт) — сбой журнала не роняет конвейер. Self-hosting-безопасно: только читает/пишет
+  свою таблицу, не деплоит/не рестартит прод/не трогает `main`/без процессов/сети. Детали —
+  `docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md`,
+  `docs/architecture/adr/adr-0034-lessons-journal.md`.
+
 ## Конвенции
 - Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`)
 - Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug`

docker-compose.yml

@@ -38,6 +38,39 @@ services:
     group_add:
       - "999"
 
+  # ORCH-100 (FND/F1b): sidecar-watchdog — the monitoring brain in a SEPARATE
+  # container (observer separated from observed, ADR-001 D2). Deploying it builds
+  # ONLY this service — the prod `orchestrator` is NOT rebuilt/restarted.
+  #   * network_mode: host -> /metrics reachable at http://127.0.0.1:8500/metrics
+  #     and host interfaces visible for memory/disk reads.
+  #   * docker.sock mounted :ro AND the code is GET-only (double read-only guard).
+  #   * host disk paths bind-mounted :ro so shutil.disk_usage sees the host FS but
+  #     can never write (opt-in disk ceiling, D6).
+  #   * mem_limit caps the thin stdlib daemon (D2): OOM = early "sidecar grew" signal.
+  #   * WATCHDOG_ENABLED=false (or simply not starting the service) -> inert.
+  orchestrator-watchdog:
+    build:
+      context: .
+      dockerfile: watchdog/Dockerfile
+    container_name: orchestrator-watchdog
+    restart: unless-stopped
+    init: true
+    network_mode: host
+    mem_limit: 128m
+    mem_reservation: 32m
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /home/slin/repos:/repos:ro
+      - ./data:/app/data:ro
+    # Optional env_file (required: false): a missing .env.watchdog must NOT fail
+    # `docker compose up` for the prod orchestrator (self-hosting safety). Absent
+    # file -> WATCHDOG_* defaults, no token -> fail-safe (logs, does not send).
+    env_file:
+      - path: .env.watchdog
+        required: false
+    group_add:
+      - "999"
+
   # ORCH-31: staging instance (port 8501, isolated DB).
   # Starts ONLY with: docker compose --profile staging up -d orchestrator-staging
   # Normal "docker compose up -d" does NOT start this service.

docs/architecture/README.md

@@ -20,6 +20,8 @@
 - **Plane Sync** (`src/plane_sync.py`) — синхронизация статусов/комментариев в Plane. Резолв статусов проекта `get_project_states` (ORCH-10) кэширует `{logical_key→uuid}` per-project; **ORCH-068** добавляет в кэш-запись `{uuid→group}` (для терминал-исключения F-2) и **TTL** `ORCH_PLANE_STATES_TTL_S` (дефолт 300с; `0` → прежний lifetime-кэш) — устаревший набор статусов самозалечивается без рестарта процесса через существующий `reload_project_states()` (баг кэша после появления нового Plane-статуса). Форма возврата `get_project_states` неизменна (обратная совместимость).
 - **FS ownership detect** (`src/fs_normalize.py`, ORCH-057 — [adr-0031](adr/adr-0031-legacy-ownership-normalization.md)) — чистый **never-raise** leaf (паттерн `serial_gate`/`preflight`), закрывает пробел ORCH-040: при миграции на `user: "1000:1000"` legacy `root:root` файлы в `/repos` ломали создание worktree под uid 1000 (`ensure_worktree` → сырой `fatal: … Permission denied`, агент не стартовал). Три слоя: (1) **D1** — `src/git_worktree.py::ensure_worktree` классифицирует класс «нет прав» (`Permission denied`/`could not create leading directories`/`insufficient permission`/`EACCES`/`EPERM`) и поднимает actionable `RuntimeError` с причиной + лечащей командой (не-прав-ошибки сохраняют прежний контракт — меняется только формулировка, не факт сбоя); (2) **D2** — `scan_ownership(roots, target_uid=os.getuid())` обходит `/repos/_wt`, `<repo>/.git/{objects,worktrees}`, `data/runs` с ранним выходом при первом `st_uid != target_uid` + TTL-кэш; (3) **D3** — best-effort вызов на старте `main.lifespan` → WARNING + Telegram при mismatch (claim **НЕ** блокируется — внятный ранний отказ даёт D1 в точке launch, знающей repo; preflight-блок отвергнут как repo-слепой → регресс enduro). Опц. `normalize()` chown'ит только при `CAP_CHOWN` (под uid 1000 — no-op; init-контейнер/root-entrypoint отвергнуты — реинтродукция root-контекста + self-deploy compose). Фактическая нормализация = **операторская процедура** под root на хосте (`INFRA.md` «Миграция uid»). Условность `applies(repo)` first: `fs_normalize_enabled` (kill-switch) + `fs_normalize_repos` (CSV, пусто → self-hosting only). Наблюдаемость — блок `fs_ownership` в `GET /queue`; опц. `POST /fs-normalize/check`. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД — не тронуты. Детали — `docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md`.
 - **Metrics endpoint** (`src/metrics.py` + `GET /metrics`, ORCH-099 — [adr-0030](adr/adr-0030-metrics-endpoint.md)) — лёгкий **read-only** leaf-сборщик (`build_metrics() -> dict`, never-raise по разделам, паттерн `serial_gate.snapshot()`) + тонкий эндпоинт (стиль `GET /queue`). Отдаёт JSON-«сырьё» о самом орке (стадии задач / очередь jobs / agent-liveness / стоимость-токены) как **стабильный машинный контракт для sidecar F1b** (`watchdog/`, отдельная задача — наблюдатель отделён от наблюдаемого). Только чтение существующих `tasks`/`jobs`/`agent_runs` + in-memory-снапшотов (`worker.breaker`); два read-only helper'а в `db.py` (`get_running_agents`/`agent_cost_totals`). Логику мониторинга (пороги/алерты/история/Telegram) НЕ несёт — это F1b. Контракт ниже (§ «Сырьё-эндпоинт `/metrics`»). Kill-switch `metrics_endpoint_enabled` (дефолт `True`). `STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД — не тронуты.
+- **Lessons journal** (`src/lessons.py` + таблица `lessons`, ORCH-098 — реализовано, [adr-0034](adr/adr-0034-lessons-journal.md)) — машинный журнал уроков (структурированная база отклонений конвейера); шаг 1 эпика саморазвития (домен 0 «Фундамент», F2; топливо петли самообучения 8A), фундамент для будущих ретроспективщика (E2)/приоритизатора RICE (E3)/Стрим. Чистый **observer-leaf** (never-raise, паттерн `serial_gate`/`coverage_gate`/`metrics`): `record()`/`get()`/`update()`/`snapshot()`. **Аддитивная идемпотентная таблица `lessons`** (`CREATE TABLE IF NOT EXISTS` в `init_db()`, restart-safe) с полями контекста (`work_item_id`/`task_id`/`stage`/`agent`/`repo`), анализа (`root_cause`/`suggestion`), статуса (`status`/`related_task`) и **атрибуции — сразу и нуллабельно** (`attribution`/`target_repo`/`target_domain`, требование Славы 10.06 / NFR-6, заполняется позже ретроспективщиком/человеком) + `source`/`detail`; без `enum`-констрейнтов (слаги forward-compatible). **Автозапись 4 типов** (`source="auto"`, best-effort, дедуп в окне; `transient_retry` — только на исчерпании бюджета ретраев) тонкими врезками: `gate_failure` (`stage_engine._handle_qg_failure_rollbacks`), `merge_hold` (`merge_gate._handle_merge_verify` HOLD), `transient_retry` (merge-retry/launcher transient budget-exhaustion), `deploy_degraded` (post-deploy `DEGRADED → set_repo_freeze`, урок слоя-3 «деплой OK / прод сломан», ET-8). Эндпоинты `GET /lessons` (read-only, фильтры), `POST /lessons` (ручная запись), `POST /lessons/{id}` (update/доклассификация), + read-only ключ `lessons` в `GET /queue`. **Расхождение с гейт-шаблоном:** журнал observer-only → **НЕ скоупится по репо** (kill-switch `lessons_enabled` only, без `lessons_repos`); репо-разрез — на выборке (`repo`-колонка/фильтр), enduro не затронут (общая БД, аддитивная таблица). `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схемы существующих таблиц — байт-в-байт не тронуты (журнал не участвует в решении гейта). Kill-switch `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`). Детали — `docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md`.
+- **Sidecar-watchdog F1b** (`watchdog/` + сервис `orchestrator-watchdog`, ORCH-100 — [adr-0033](adr/adr-0033-sidecar-watchdog.md)) — **мозг мониторинга в ОТДЕЛЬНОМ контейнере** (наблюдатель отделён от наблюдаемого, C-1): код в репо орка (`watchdog/`), рантайм — свой образ (`watchdog/Dockerfile`, `python:3.12-slim`, **stdlib-only**) + сервис в `docker-compose.yml` (`network_mode: host`, read-only `docker.sock`, `mem_limit: 128m`). На каждом тике собирает 4 источника: `GET /metrics` орка (F1a/ORCH-099), хост (диск/inode/память/CPU, stdlib), статусы контейнеров через read-only `docker.sock` (GET-only, без `docker` SDK), пинг Plane/Gitea/Anthropic. Каждый сигнал → **обобщённая чистая** `decide(signal_active, prev, now, cooldown)` (генерализация `disk_watchdog.decide_action`, per-signal in-memory `AlertState`) → алерт в **собственный** Telegram-канал sidecar (`WATCHDOG_TG_*`, **НЕ** импорт `src/notifications.py`). Особый сигнал `orch_down` — `/metrics` не отвечает (наблюдатель жив, наблюдаемый лёг). Диск: штатные 85% остаются за `disk_watchdog` (ORCH-063, нулевой дубль), sidecar — `orch_down` + opt-in потолок 97% (default off). never-raise, kill-switch `WATCHDOG_ENABLED`, строго read-only к наблюдаемому; `src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД орка — не тронуты. Подробнее ниже (§ «Sidecar-watchdog F1b»). Детали — `docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md`.
 
 ## Сырьё-эндпоинт `/metrics` для sidecar (ORCH-099 — design)
 
@@ -73,6 +75,53 @@ F1b (рамка C-1: наблюдатель отделён от наблюдае
 Подробнее: [adr-0030](adr/adr-0030-metrics-endpoint.md), детально —
 `docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md`.
 
+## Sidecar-watchdog F1b (ORCH-100 — design)
+
+**Вторая половина пары наблюдаемости.** F1a (ORCH-099) отдаёт сырьё через `GET /metrics`; F1b — мозг,
+который это сырьё читает, дополняет внешними сигналами и превращает в алерты. Ключевая рамка
+заказчика — **наблюдатель отделён от наблюдаемого** (C-1): частичные стражи (`disk_watchdog`/`reaper`/
+`reconciler`) живут ВНУТРИ процесса орка и лягут вместе с ним; sidecar в отдельном контейнере
+переживает падение орка и делает наблюдателя **громче** в инцидент.
+
+- **Рантайм:** код в `watchdog/` (репо орка), но **отдельный контейнер** `orchestrator-watchdog`
+  (свой `watchdog/Dockerfile`, `python:3.12-slim`, **stdlib-only** — без сторонних зависимостей,
+  C-3 «тонкий стек, НЕ Grafana/Prometheus»). `network_mode: host` → `/metrics` достижим как
+  `http://127.0.0.1:8500/metrics`; `docker.sock` смонтирован **read-only**; `mem_limit: 128m`;
+  `restart: unless-stopped`.
+- **4 коллектора на тик:** (a) `GET /metrics` орка (толерантный парсинг конверта F1a — неизвестные
+  ключи игнор, рост `schema_version` → warning); (b) хост — диск (`shutil.disk_usage`)/inode/память
+  (`/proc/meminfo`)/CPU; (c) контейнеры через read-only `docker.sock` — **только** GET list/inspect
+  (Up/healthy/restarting/exited/unhealthy), без `docker` SDK; (d) пинг Plane/Gitea/Anthropic.
+- **Решение — обобщённая чистая функция** `decide(signal_active, prev, now, cooldown) -> alert |
+  realert | recovery | none` (строгая генерализация `src/disk_watchdog.py::decide_action`;
+  per-signal in-memory `AlertState`, рестарт → корректный повторный алерт стоящей проблемы). Реестр
+  сигналов: `orch_down` (K подряд неудачных опросов), `host_mem`, `host_disk_crit` (opt-in потолок),
+  `agent_hung` (доля CPU из Δ`cpu_ticks`/`clk_tck`/Δ`generated_at` < floor при растущем `runtime_s` —
+  sidecar stateful-арбитр), `stage_stuck` (`age_in_stage_s`), `job_failed` (edge), `queue_depth`,
+  `container_down` (per name), `dep_down` (per name). Пороги/интервалы/URL — из env (`WATCHDOG_*`).
+- **`orch_down` — главный сигнал:** `/metrics` не отвечает (таймаут/refused/5xx/нечитаемо) → алерт
+  «орк не отвечает» через ту же машину порога/дедупа/recovery. Наблюдатель жив, наблюдаемый лёг.
+- **Независимый Telegram-канал:** свои `WATCHDOG_TG_BOT_TOKEN`/`WATCHDOG_TG_CHAT_ID`; **запрещено**
+  импортировать `src/notifications.py` или использовать токен орка (иначе падение орка утянуло бы и
+  алерт-канал — нарушение C-1).
+- **Владелец диск-алерта (BR-10, ADR-001 D6):** штатные 85% — ЕДИНСТВЕННО за внутренним
+  `disk_watchdog` (ORCH-063, канал орка) ⇒ **нулевой дубль по построению**; sidecar покрывает провал
+  «орк+disk_watchdog мертвы» через `orch_down`, плюс **opt-in** независимый критический потолок
+  `host_disk_crit` (97%, `WATCHDOG_DISK_CRIT_ENABLED=false` по умолчанию) — другое событие/канал.
+- **Гарантии:** never-raise (per-source/per-tick/per-send); kill-switch `WATCHDOG_ENABLED=false` →
+  демон инертен (idle-loop, нулевой эффект на орк); строго read-only к наблюдаемому (нет
+  start/stop/restart/exec/записи в `docker.sock`/БД/`main`) ⇒ self-hosting-безопасно (enduro не
+  затронут). `src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД орка — **не тронуты**
+  (F1b вне процесса орка и вне конвейера QG — как `disk_watchdog`/`reaper`/`reconciler`). Деплой
+  sidecar НЕ рестартит прод-контейнер `orchestrator`; прод-выкат — через staging-гейт (8501).
+- **Инфра-предусловие (разовое, человек):** добавить сервис в compose, создать bot/chat watchdog,
+  смонтировать `docker.sock` `:ro` + хост-пути, первый запуск на хосте —
+  `docs/work-items/ORCH-100/07-infra-requirements.md`.
+
+Подробнее: [adr-0033](adr/adr-0033-sidecar-watchdog.md), детально —
+`docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md`,
+`docs/work-items/ORCH-100/07-infra-requirements.md`.
+
 ## Конвейер и Quality Gates
 
 ```
@@ -1037,6 +1086,7 @@ Monitoring after Deploy → Done
 - `jobs` — очередь задач (ORCH-1); статусы `queued|running|done|failed|cancelled` (ORCH-090: `cancelled` — терминальный исход STOP, нигде не реквью'ится); колонка `pid` (ORCH-065) — pid агентского процесса для liveness-детекции зомби job-reaper'ом
 - `job_deps` — декларативные зависимости задач (ORCH-026, Уровень B): `(task_id, depends_on_task_id)`, аддитивная; источник истины планировщика для гейта «B ждёт A»
 - `repo_freeze` — durable per-repo rollback-freeze (ORCH-088, FR-5): `(id, repo, frozen_at, reason, work_item_id, cleared_at)`, аддитивная append-only; активный freeze ⇔ строка репо с `cleared_at IS NULL`. Выставляется post-deploy `DEGRADED` (`set_repo_freeze`), снимается вручную (`POST /serial-gate/unfreeze` → `cleared_at=now`). Гейтит serial-claim безусловно (деградировавшая задача уже `done`)
+- `lessons` — машинный журнал отклонений конвейера (ORCH-098, FR-1): `(id, created_at, updated_at, lesson_type, work_item_id, task_id, stage, agent, repo, root_cause, suggestion, status, related_task, attribution, target_repo, target_domain, source, detail)`, аддитивная идемпотентная (`CREATE TABLE IF NOT EXISTS` + три индекса); колонки атрибуции (`attribution`/`target_repo`/`target_domain`) — нуллабельны и присутствуют сразу (NFR-6), без `enum`-констрейнтов (слаги forward-compatible). Автозапись 4 типов (`gate_failure`/`merge_hold`/`transient_retry`/`deploy_degraded`, `source="auto"`, дедуп в окне `lessons_dedup_window_s`) + ручная (`source="manual"`); observer-only (не участвует в решении гейта). Leaf `src/lessons.py` never-raise, kill-switch `lessons_enabled` (без `*_repos` — журнал не скоупится по репо, репо-разрез на выборке)
 
 ## Изоляция (git worktree, ORCH-2)
 Каждая задача исполняется в отдельном git worktree, ветки не пересекаются. Репозитории проектов разделены под `/repos/<project>`.
@@ -1046,9 +1096,12 @@ Monitoring after Deploy → Done
 |--------|------|----------|
 | GET | `/health` | health check |
 | GET | `/status` | активные задачи (stage != done) |
-| GET | `/queue` | очередь: counts + max_concurrency + resilience + reconcile (ORCH-053) + reaper (ORCH-065) + post_deploy (ORCH-021) + task_deps (ORCH-026) + serial_gate (ORCH-088) + auto_labels (ORCH-089) + stop (ORCH-090) + последние jobs |
+| GET | `/queue` | очередь: counts + max_concurrency + resilience + reconcile (ORCH-053) + reaper (ORCH-065) + post_deploy (ORCH-021) + task_deps (ORCH-026) + serial_gate (ORCH-088) + auto_labels (ORCH-089) + stop (ORCH-090) + lessons (ORCH-098) + последние jobs |
 | GET | `/metrics` | ORCH-099 (FND/F1a): read-only машинное «сырьё» для sidecar F1b — конверт `schema_version`/`generated_at`/`clk_tck` + разделы `stages`/`queue`/`agents` (liveness: pid/runtime/cpu_ticks)/`cost`. never-raise по разделам; kill-switch `ORCH_METRICS_ENABLED` (дефолт `True`). Контракт — см. раздел «Сырьё-эндпоинт `/metrics`» |
 | POST | `/serial-gate/unfreeze` | ORCH-088 (FR-5): ручное снятие per-repo rollback-freeze (query/body `repo=<repo>`) → `{ok, repo, cleared, frozen}`; идемпотентно. Альтернатива — `UPDATE repo_freeze SET cleared_at=datetime('now') WHERE repo=? AND cleared_at IS NULL` |
+| GET | `/lessons` | ORCH-098 (FR-4): read-only выборка журнала уроков; query-фильтры `type`/`status`/`repo`/`work_item`/`limit` → `{enabled, lessons:[…]}` (всегда `200`, чтение не мутирует). При `lessons_enabled=False` → `{enabled:false, lessons:[]}` |
+| POST | `/lessons` | ORCH-098 (FR-5): ручная запись урока (JSON-тело, `lesson_type` обязателен, `source="manual"` не дедупится) → `{id}`; при выключенном флаге → `{enabled:false}` |
+| POST | `/lessons/{id}` | ORCH-098 (FR-5): доклассификация/обновление урока (`status`/`attribution`/`target_*`/`related_task`/`root_cause`/`suggestion`), стампит `updated_at` → `{ok}` |
 | POST | `/webhook/plane` | Plane webhook |
 | POST | `/webhook/gitea` | Gitea webhook (push, PR, CI status) |
 

docs/architecture/adr/adr-0033-sidecar-watchdog.md

@@ -0,0 +1,85 @@
+---
+work_item: ORCH-100
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# adr-0033: Sidecar-watchdog F1b — мозг мониторинга в отдельном контейнере
+
+- **Статус:** proposed
+- **Дата:** 2026-06-10
+- **Задача:** ORCH-100 (FND/F1b)
+- **Детальный ADR:** `docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md`
+- **Парный ADR:** `adr-0030` (F1a `/metrics` — источник сырья)
+
+## Контекст
+Домен 0 «Фундамент» эпика автономного саморазвития, рамка наблюдаемости заказчика: **наблюдатель
+отделён от наблюдаемого**. F1a (adr-0030) отдаёт read-only `GET /metrics` — **только сырьё**. F1b —
+**мозг**: читает сырьё, дополняет внешними сигналами (хост/контейнеры/зависимости), решает по порогам,
+алертит. Частичные стражи (`disk_watchdog`/`reaper`/`reconciler`) живут ВНУТРИ процесса орка — орк
+завис/упал ⇒ они мертвы, платформа слепа в критический момент. Рамки: C-1 (отдельный контейнер, код в
+`watchdog/`), C-2 (без внешнего плеча — принятый риск), C-3 (тонкий стек, НЕ Grafana/Prometheus; хост
+впритык). Критический инвариант: орк лёг ⇒ `/metrics` недоступен = **сам сигнал тревоги**.
+
+## Решение
+Новая папка `watchdog/` — **тонкий Python-3.12-stdlib демон** (без сторонних зависимостей), отдельный
+образ `watchdog/Dockerfile` + сервис `orchestrator-watchdog` в `docker-compose.yml` (`network_mode:
+host`, read-only `docker.sock`, `mem_limit: 128m`, `restart: unless-stopped`). Тик: (1) `GET /metrics`;
+(2) хост (диск/inode/память/CPU, stdlib); (3) статусы контейнеров через read-only `docker.sock`
+(GET-only — без `docker` SDK); (4) пинг Plane/Gitea/Anthropic. Сигналы проходят через **обобщённую
+чистую** `decide(signal_active, prev, now, cooldown) -> alert|realert|recovery|none` (генерализация
+`disk_watchdog.decide_action`; per-signal in-memory `AlertState`). Алерт — в **собственный** Telegram-
+канал sidecar (свои `WATCHDOG_TG_*`; **НЕ** импорт `src/notifications.py`). Особый сигнал — `/metrics`
+не отвечает → `orch_down`. Всё never-raise (per-source/per-tick/per-send), под kill-switch
+`WATCHDOG_ENABLED`, строго read-only к наблюдаемому. **`src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/
+`check_*`/схема БД орка — не тронуты** (F1b вне процесса орка и вне конвейера QG).
+
+- **Стек** — Python stdlib (`urllib`, `socket`+`http.client` для docker.sock, `shutil.disk_usage`,
+  `/proc/meminfo`); pytest на чистые функции. Отвергнуты Go / `docker` SDK / Prometheus (C-3).
+- **Реестр сигналов** — `orch_down` (K подряд неудачных опросов), `host_mem`/`host_disk_crit`,
+  `agent_hung` (Δ`cpu_ticks`/`clk_tck`/Δ`generated_at` < floor при растущем `runtime_s`; нужно 2
+  опроса — sidecar stateful-арбитр), `stage_stuck` (`age_in_stage_s`), `job_failed` (edge),
+  `queue_depth`, `container_down` (per name), `dep_down` (per name). Пороги/интервалы/URL — из env.
+- **Владелец диск-алерта (BR-10)** — штатные 85% остаются за внутренним `disk_watchdog` (ORCH-063,
+  канал орка) ⇒ **нулевой дубль по построению**; sidecar покрывает провал «орк+disk_watchdog мертвы»
+  через `orch_down`, плюс **opt-in** (default off) независимый критический потолок `host_disk_crit`
+  (97%) — другое событие/канал, не повтор 85%.
+- **Толерантность контракта** — неизвестные ключи `/metrics` игнорируются, отсутствие опционального не
+  ошибка, рост `schema_version` → warning (зеркало аддитивной политики adr-0030).
+- **Kill-switch** `WATCHDOG_ENABLED=false` → демон инертен (idle-loop, не exit) ⇒ нулевой эффект.
+
+## Альтернативы
+- **Go / `docker` SDK / `requests`** — отклонено: вес/вторая цепочка против C-3 и консистентности с
+  `disk_watchdog`.
+- **Prometheus/Grafana/TSDB** — отклонено: прямой запрет C-3.
+- **Sidecar — единственный владелец диска** — отклонено: потеря покрытия, когда сам sidecar/Docker
+  недоступен; выбрана связка primary `disk_watchdog` + opt-in ceiling.
+- **Push из орка в sidecar** — отклонено: зависший орк не пушит; pull падает = сам сигнал `orch_down`.
+- **bridge + `host.docker.internal`** — отклонено: на Linux ненадёжно; `network_mode: host` проще.
+- **Своя БД/файл порогов** — отклонено: C-3; in-memory best-effort достаточно (как `disk_watchdog`).
+
+## Последствия
+- Внешний мозг мониторинга переживает падение орка; `orch_down` делает наблюдателя громче в инцидент.
+- Строго read-only + независимый канал + never-raise ⇒ self-hosting-безопасно (enduro не затронут);
+  падение sidecar не влияет на конвейер.
+- Аддитивно/обратимо: `src/**`/гейты/схема байт-в-байт; kill-switch → нулевая регрессия; дубль диска
+  исключён структурно.
+- Плата: новый контейнер на впритык-хосте (`mem_limit: 128m` + замер RSS на staging обязательны);
+  C-2 (падёт хост → молчит и sidecar); новая поверхность совместимости `/metrics`↔F1b (толерантный
+  парсинг + единый репо контракта); CPU-liveness Linux-специфичен.
+- **Топология** меняется (новый контейнер) → `07-infra-requirements.md`; **схема БД** не меняется →
+  08 = N/A. Новый компонент + контейнер + канал → `arch:major-change`; прод-выкат через staging-гейт
+  (8501), деплой sidecar НЕ рестартит прод-контейнер.
+- **Откат:** не запускать сервис / `WATCHDOG_ENABLED=false` (мгновенный) или удаление `watchdog/` +
+  сервиса + env — без следов в БД/схеме.
+
+## Связи
+adr-0030 (F1a `/metrics` — парный источник сырья; контракт `cpu_ticks`/`clk_tck`/`generated_at`/
+`schema_version`), adr-0024 (`disk_watchdog` — образец решающей функции/never-raise + владелец
+диск-алерта), adr-0025 (build-cache-pruner — паттерн «вторая половина»), adr-0017 (serial_gate —
+leaf `snapshot()`/never-raise), adr-0011 (job-reaper — pid/liveness-семантика). Прямой источник —
+**F1a** (`GET /metrics`); F1b — его потребитель.
+</content>

docs/architecture/adr/adr-0034-lessons-journal.md

@@ -0,0 +1,92 @@
+---
+work_item: ORCH-098
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# adr-0034: Машинный журнал уроков — таблица `lessons` + observer-leaf (ORCH-098)
+
+## Статус
+Proposed
+
+## Контекст
+
+Оркестратор автономно ведёт задачи по конвейеру (ORCH-54), но **развивается** вручную: инциденты →
+уроки → задачи. Уроки живут свободным текстом в `memory/` — не машиночитаемы: нельзя считать
+паттерны, приоритизировать, предлагать улучшения. ORCH-098 — шаг 1 эпика саморазвития (домен 0
+«Фундамент», F2): «топливо» петли самообучения 8A. Нужна **структурированная таблица отклонений
+конвейера**, на которой позже встанут ретроспективщик (E2), приоритизатор RICE (E3) и Стрим.
+
+Нормативное требование Славы (10.06): схема ДОЛЖНА **сразу** нести поля **атрибуции** урока
+(`platform`/`project`/`both`/`unknown` + целевой репо + домен улучшения), иначе позже придётся
+переделывать схему на живой общей прод-БД.
+
+**Кросс-каттинговость** (почему сквозной ADR): новый компонент `src/lessons.py` + аддитивная
+таблица на **общей прод-БД** (self-hosting, разделяемой с enduro-trails) + врезки автозаписи в
+несколько горячих choke-point'ов (`stage_engine`/`merge_gate`/`launcher`) + новый раздел контракта
+`GET /queue`. Фундамент для будущих задач-потребителей → регистрируется глобально.
+
+## Решение
+
+Журнал уроков — **observer (наблюдатель), НЕ Quality Gate**. Аддитивная таблица + чистый leaf,
+по образцу `serial_gate`/`coverage_gate`/`metrics`/`bug_fast_track`.
+
+1. **Таблица `lessons`** (`db.init_db()`, `CREATE TABLE IF NOT EXISTS` + 3 индекса, идемпотентно,
+   restart-safe) — поля контекста (`work_item_id`/`task_id`/`stage`/`agent`/`repo`), анализа
+   (`root_cause`/`suggestion`), статуса (`status`/`related_task`), **атрибуции сразу и нуллабельно**
+   (`attribution`/`target_repo`/`target_domain`) + `source`/`detail`. Без `enum`-констрейнтов
+   (слаги forward-compatible). Будущие колонки — `_ensure_column`.
+
+2. **Leaf `src/lessons.py`** (never-raise, импортирует только `config`+`db`): `record()` / `get()` /
+   `update()` / `snapshot()`. **Расхождение с гейт-шаблоном: журнал НЕ скоупится по репо** — он
+   observer-only и не *действует* ни на один репо; единственный регулятор — глобальный kill-switch
+   `lessons_enabled`. Запись урока про enduro ценна и **не затрагивает** пайплайн enduro (чистая
+   память орка); репо-разрез — на выборке (`repo`-колонка/фильтр).
+
+3. **Автозапись 4 типов** (`source="auto"`, best-effort, дедуп в окне; `transient_retry` — только на
+   исчерпании бюджета ретраев): `gate_failure` (`stage_engine._handle_qg_failure_rollbacks`),
+   `merge_hold` (`merge_gate._handle_merge_verify` HOLD), `transient_retry` (merge-retry/launcher
+   transient budget-exhaustion), `deploy_degraded` (post-deploy `DEGRADED → set_repo_freeze`, урок
+   слоя-3 «деплой OK / прод сломан», ET-8). Каждая врезка — одиночный вызов в защитном `try/except`.
+
+4. **Эндпоинты** `GET /lessons` (read-only, фильтры), `POST /lessons` (ручная запись,
+   `source="manual"`), `POST /lessons/{id}` (update — доклассификация `unknown`), + read-only ключ
+   `"lessons": snapshot()` в `GET /queue`. При выключенном флаге → `{"enabled": false}`.
+
+**Инвариант (нерушимый):** `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи
+(`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`/`coverage_status:`) /
+схемы существующих таблиц — **байт-в-байт не тронуты**. Журнал не влияет на продвижение по стадиям.
+
+## Композиция с существующими механизмами
+- **Self-hosting (общая БД):** аддитивная таблица; enduro не затронут (NFR-3).
+- **serial-gate (ORCH-088) / post-deploy (ORCH-021):** детектор `deploy_degraded` врезан рядом с
+  `set_repo_freeze`, не меняя freeze-логику.
+- **merge-gate (ORCH-043/071/093):** `merge_hold`/`transient_retry` читают исход актора, не меняя
+  классификатор/ретрай.
+- **metrics (ORCH-099):** журнал — историческая память петли (best-effort запись), `/metrics` —
+  realtime-сырьё для sidecar; разные роли, оба observer-only.
+
+## Условность и откат
+- Флаг `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`; kill-switch) +
+  `lessons_dedup_window_s` / `lessons_query_limit_default`. `False` → полная инертность, нулевая
+  регрессия, конвейер байт-в-байт прежний.
+- **never-raise** на всех публичных функциях и врезках (NFR-1) — сбой журнала не роняет конвейер.
+- Откат — флаг в `false` (мгновенно) или revert диффа; таблица не касается существующих.
+
+## Последствия
+- **+** Машиночитаемые уроки — фундамент E2/E3/Стрим; атрибуция forward-proof (без передела живой БД).
+- **+** Нулевая регрессия; проверенный additive-observer-leaf шаблон → низкий риск; enduro изолирован.
+- **−** Рост таблицы (митигейшн: лёгкие строки + дедуп + budget-exhaustion; ретенция — будущее).
+- **−** Дедуп-запрос в `record()` (один indexed-SELECT, только `auto`).
+
+## Ссылки
+- Локальный ADR: `docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md`
+- BRD/TRZ/AC: `docs/work-items/ORCH-098/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`
+- Data/Infra/Risks: `docs/work-items/ORCH-098/08-data-requirements.md`, `07-infra-requirements.md`,
+  `10-tech-risks.md`
+- Эпик: `docs/epics/self-evolution.md` (домен 0 «Фундамент», F2; петля 8A)
+- Сверено по коду: `src/serial_gate.py`, `src/coverage_gate.py`, `src/db.py`, `src/stage_engine.py`,
+  `src/merge_gate.py`, `src/agents/launcher.py`, `src/main.py`, `src/qg/checks.py`.

docs/epics/self-evolution.md

@@ -75,6 +75,16 @@
 - **F1 Наблюдаемость** (ORCH-83 [ЭПИК]): метрики agent-liveness + очередь + стадии + хост (диск/память/CPU) + контейнеры + внешние деп (Plane/Gitea/Anthropic). Эндпоинты /health /status /queue → расширить до /metrics + дашборд.
 - **F2 Журнал уроков** (ORCH-8 шаг 1): машинная структурированная таблица отклонений (тип, контекст, корень, предложение, статус) — формализовать то, что сейчас в memory/. Это «топливо» для вертикали-двигателя.
 
+### 🎯 СКОП НАБЛЮДЕНИЯ — три слоя (решено Славой 10.06)
+
+> Граница «мониторим ПЛАТФОРМУ vs ПРОДУКТЫ на ней». Важно для архитектора и будущих задач — не путать уровни.
+
+- **Слой 1 — проекты как ЗАДАЧИ в конвейере — ✅ В СКОПЕ (F1a/F1b).** ET-задачи в stages/queue/agents `/metrics` — это работа орка (его агенты/очередь/стадии). Sidecar алертит «ET-задача застряла». Здоровье КОНВЕЙЕРА.
+- **Слой 2 — проекты как КОНТЕЙНЕРЫ на хосте — ✅ В СКОПЕ (F1b, жив/мёртв).** `enduro-trails-app-1`, `osrm` и пр. через docker.sock ro — Up/healthy/restarting/exited. Общий хост впритык → текущий ET-контейнер вредит орку. Здоровье контейнера как чёрного ящика.
+- **Слой 3 — ВНУТРЕННЕЕ бизнес-здоровье продукта — ❌ НЕ В ФУНДАМЕНТЕ, НО НУЖНО (см. ниже).** Эндпоинты ET отвечают 200? карта рендерится? latency не деградировала после фичи? Орк не знает внутренностей задеплоенных приложений — это МОНИТОРИНГ ПРОДУКТА, не платформы.
+
+**Слой 3 — это отдельная продуктовая способность (домен D4/D5):** «per-project мониторинг здоровья задеплоенного приложения» — опция для заказчика («слежу, что твой ET-сайт жив»). **НО он НУЖЕН и самой петле** (см. §8A «атрибуция уроков») — без детекции деградации продукта петле нечего ловить. Порядок: фундамент (слои 1-2) сначала, слой 3 — позже как D4/D5-фича.
+
 ---
 
 ## 3. ДОМЕН D1 — 🛡️ Надёжность (Self-Repairing)
@@ -166,6 +176,25 @@
 - **Анализ (гибрид):** машина копит и предлагает черновик → Стрим фильтрует/оформляет → Слава апрувит.
 - **E1** Журнал уроков (=F2). **E2** Агент-ретроспективщик (анализ→предложение).
 
+#### ⚖️ АТРИБУЦИЯ урока — platform-level vs project-level (решено Славой 10.06)
+
+> Ключевой шаг петли. Пример Славы: выпустили фичу в ET → она деградировала ET. Петля поймала сигнал — но ЧЬЯ вина и ГДЕ чинить?
+
+Когда детектирована деградация продукта после выпуска фичи, петля ДОЛЖНА различить два уровня вины и направить урок в правильное русло:
+
+- **А. Platform-level (недоработал ОРК):** конвейер выпустил деградацию, потому что у платформы СЛАБЫЙ ПРОЦЕСС (нет регресс-гейта «фича не ломает соседнее», тест-стадия не ловит деградацию производительности, нет производительностного бенчмарка в приёмке). → улучшаем ПРОЦЕСС орка (домен **D2 Качество** / **D1 Надёжность**). Чинится ОДИН раз — выигрывают ВСЕ проекты.
+- **Б. Project-level (недоработал ПРОЕКТ):** процесс орка нормальный, но в конкретном ET МАЛО тестов/слабая приёмка под этот тип фич. → усиливаем ТЕСТЫ/приёмку В САМОМ ET (задача в бэклог ET). Чинится точечно — выигрывает только ET.
+
+**Механизм (новый шаг петли):**
+```
+ДЕТЕКЦИЯ деградации продукта (слой 3) → урок →
+   АТРИБУЦИЯ: platform-level или project-level?
+   ├─ platform → задача в D1/D2 (улучшить процесс — польза всем)
+   └─ project  → задача в бэклог ET (усилить тесты ET — польза ET)
+   (развилка не всегда бинарна — бывает ОБА: и гейт в орк, и тесты в ET)
+```
+Без атрибуции петля «чинит платформу» там, где надо усилить проект (и наоборот). **Зависит от слоя-3 детекции** (§2): без мониторинга здоровья продукта петле нечего атрибутировать. **E2-ретроспективщик** несёт эту классификацию; спорные случаи → Стрим/Слава решают.
+
 ### 8B. Проактивная турбина 💡 — генератор идей новых возможностей (НОВОЕ — запрос Славы)
 
 > Отдельный источник идей роста функционала — НЕ только требования от Славы. Проактивно предлагает новые фичи/возможности/удобства. Та же воронка: машина/агент генерит черновики → Стрим фильтрует → Слава решает.

docs/work-items/ORCH-009/15-staging-log.md

@@ -0,0 +1,48 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-009
+stage: deploy-staging
+author_agent: deployer
+status: success
+created_at: 2026-06-10
+model_used: claude-fable-5
+timestamp: 2026-06-10T13:07:10Z
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log
+
+Staging test suite completed against the live staging environment
+(`orchestrator-staging`, 8501), run canonically inside the container
+(ORCH-048, ADR-001: `docker exec orchestrator-staging python3
+/repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501
+--mode stub`).
+
+**Verdict: SUCCESS** (exit code 0).
+
+## Results
+
+Result: 8/10 checks PASS. All REAL (pipeline) checks are green:
+
+- **Block A (SMOKE)**: A1 `/health` → 200 status=ok, A2 `/queue` → 200 with
+  counts/max_concurrency/resilience (incl. `serial_gate`, `coverage`,
+  `auto_labels`, `stop`, `bug_fast_track`, `lessons` blocks), A3
+  `ORCH_STAGING=true` — PASS
+- **Block B (ACCESS)**: B4 Plane sandbox accessible, B5 Gitea
+  `orchestrator-sandbox` accessible (push=true), B6 registry isolation
+  (sandbox present, prod ET/ORCH absent) — PASS
+- **Block C (E2E, mode=stub)**: C7 create issue in Plane SANDBOX (HTTP 201),
+  C8 trigger pipeline via `/webhook/plane` (HTTP 200, accepted) — PASS;
+  cleanup completed (Plane issue deleted, HTTP 204)
+
+REAL failed: none.
+
+The two failed checks (C9a/C9b) are known sandbox-infra checks (they depend on
+SANDBOX bot accounts being project members, not on the pipeline) and were
+waived per ORCH-061 (`staging_infra_tolerance_enabled=True`); the script still
+exited 0 fail-closed because every REAL check is green.
+
+```
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+```

docs/work-items/ORCH-019/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-019
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

docs/work-items/ORCH-098/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: FND: машинный журнал уроков — структурированная база отклонений (топливо петли)
+
+Work Item ID: ORCH-098
+
+## Description
+
+TBD

docs/work-items/ORCH-098/01-brd.md

@@ -0,0 +1,143 @@
+---
+work_item: ORCH-098
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD (бизнес-требования): ORCH-098 — FND: машинный журнал уроков (структурированная база отклонений)
+
+Work Item: **ORCH-098** · Repo: **orchestrator** · Стадия: analysis
+
+## 1. Бизнес-контекст и проблема
+
+Оркестратор уже автономно проводит задачи через конвейер (ORCH-54), но **развивает** платформу
+по-прежнему вручную связка Слава+Стрим: ловим инциденты → формулируем уроки → заводим задачи.
+Уроки сегодня живут **свободным текстом** в `memory/` — они не машиночитаемы, по ним нельзя
+считать паттерны, нельзя приоритизировать, нельзя автоматически предлагать улучшения.
+
+ORCH-098 — шаг 1 эпика саморазвития (`docs/epics/self-evolution.md`, **домен 0 «Фундамент», F2**,
+ORCH-8). Это **«топливо» вертикали-двигателя** (петля самообучения 8A): формализовать свободный
+текст в **машинную структурированную таблицу отклонений конвейера**. Каждый урок — запись с
+полями для машинного анализа паттернов. Журнал — фундамент, на котором позже встанут
+ретроспективщик (E2), приоритизатор RICE (E3) и Стрим как потребители.
+
+**Установленные факты-источники сигналов («уроков»)** — из памяти орка (инциденты 06–09.06) и §8A
+эпика:
+- Провал гейта (BLOCKED / FAILED / REQUEST_CHANGES).
+- **Ручное вмешательство человека — самый ценный сигнал** (каждый ручной пинок = дыра автономности).
+- Ретраи, откаты деплоя, таймауты агентов.
+- Ложные срабатывания гейтов (исторический пример: substring `PASS` в `check_tests_passed`).
+- «Деплой SUCCESS, а прод не работает» (урок ET-8); транзиенты (Gitea `405`, Anthropic `Overloaded`).
+
+**Решение Славы 10.06 (ОБЯЗАТЕЛЬНО учесть на этапе схемы):** схема журнала ДОЛЖНА **с самого
+начала** нести поля для будущей **АТРИБУЦИИ** урока (иначе потом переделывать схему на живой
+общей прод-БД). Атрибуция (`platform-level` / `project-level` / `both` / `unknown`), целевой
+проект и целевой домен улучшения — это §8A эпика «platform-level vs project-level». При автозаписи
+поля атрибуции могут быть пустыми/`unknown` (классификацию позже ставит ретроспективщик/Стрим), но
+**колонки в схеме должны существовать сразу** — аддитивные, нуллабельные.
+
+**Связь со слоями наблюдения (§2 эпика):** деградация продукта (слой 3, урок ET-8) — один из типов
+урока; журнал должен уметь его хранить с атрибуцией `platform`/`project`.
+
+## 2. Объём (scope)
+
+### В объёме
+- Аддитивная идемпотентная таблица БД `lessons` для структурированных уроков со всеми полями
+  контекста, анализа, статуса **и атрибуции** (колонки атрибуции — сразу, нуллабельные).
+- Leaf-модуль `src/lessons.py` (never-raise, kill-switch) + helper записи урока.
+- **Автозапись** ≥2–3 типов отклонений из кода через best-effort точки врезки в
+  `stage_engine.py` / `merge_gate.py` / `launcher.py` (провал гейта/откат, HOLD, транзиент-ретрай).
+- **Read-only выборка** уроков (HTTP-эндпоинт + блок в `GET /queue`) — для будущего
+  ретроспективщика и Стрим.
+- **Ручная запись** урока (HTTP-эндпоинт / helper) — Стрим/оператор кладёт урок руками.
+- Доки (CLAUDE.md / architecture README / ADR) + `CHANGELOG.md`.
+
+### Вне объёма
+- **Анализ паттернов / ретроспективщик (E2)** — отдельная задача-потребитель журнала.
+- **Приоритизатор RICE (E3)** — отдельная задача.
+- **Автоматическая классификация атрибуции** — её ставит ретроспективщик/человек позже; здесь —
+  только колонки и возможность проставить значение руками/через update.
+- **Банк идей (D4 / идеатор, E5)** — отдельный реестр, НЕ путать с журналом уроков.
+- **Слой-3 детекция здоровья продукта** (мониторинг задеплоенного приложения) — отдельная
+  D4/D5-способность; журнал лишь умеет **хранить** такой урок, когда детектор появится.
+- Изменение `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключей / любых
+  существующих таблиц.
+- Миграция исторических уроков из `memory/` (ручной разовый импорт — вне объёма).
+
+## 3. Заинтересованные стороны
+- **Заказчик:** Слава (требование атрибуции 10.06 — нормативно).
+- **Прямой потребитель (будущее):** агент-ретроспективщик E2, приоритизатор E3, Стрим (ручной
+  разбор).
+- **Затрагивается:** self-hosting прод-инстанс orchestrator (общая БД и очередь с enduro-trails) —
+  enduro **не должен быть затронут** (аддитивность, never-raise).
+- **Принимает результат:** reviewer/tester конвейера + Слава.
+
+## 4. Бизнес-требования (BR)
+
+- **BR-1 — Структурированная таблица уроков.** Аддитивная, идемпотентная (`CREATE TABLE IF NOT
+  EXISTS`) таблица `lessons` на общей прод-БД с полями: тип отклонения; контекст
+  (work_item/task/стадия/агент/repo); корневая причина (если известна); предложенное улучшение
+  (если есть); статус (`new`/`in_progress`/`closed`/`linked`) + связанная задача; timestamp.
+- **BR-2 — Поля атрибуции с самого начала.** Схема несёт **сразу** нуллабельные колонки:
+  `attribution` (`platform`/`project`/`both`/`unknown`), `target_repo` (кого касается:
+  `orchestrator`/`enduro-trails`/др.), `target_domain` (домен улучшения:
+  `reliability`/`quality`/`economy`/`features`/`scale`). При автозаписи допустимо пусто/`unknown`.
+- **BR-3 — Автозапись ≥2–3 типов отклонений.** Из кода, best-effort, в детерминированных
+  choke-point: (а) провал гейта / откат на `development` (reviewer REQUEST_CHANGES, tester FAIL,
+  staging/deploy FAILED), (б) HOLD merge-актора / regression-guard HOLD, (в) транзиент-ретрай
+  (Gitea-merge `405`/`5xx`, Anthropic `Overloaded`/agent-timeout requeue). Дополнительно желательно
+  (г) post-deploy `DEGRADED` (урок «деплой OK / прод сломан», слой-3, ET-8) с атрибуцией.
+- **BR-4 — Read-only выборка.** HTTP-эндпоинт `GET /lessons` (фильтры: тип/статус/repo/work_item,
+  лимит) + read-only блок `lessons` в `GET /queue` (сводка). Только чтение.
+- **BR-5 — Ручная запись.** HTTP-эндпоинт `POST /lessons` (+ публичный helper) — оператор/Стрим
+  кладёт урок руками, в т.ч. с проставленной атрибуцией.
+- **BR-6 — Обновление урока.** Возможность сменить статус / проставить атрибуцию / привязать
+  задачу после создания (helper/эндпоинт `POST /lessons/{id}` или поля в `POST /lessons`) — чтобы
+  ретроспективщик/человек позже классифицировал автозаписанный `unknown`.
+
+## 5. Нефункциональные требования (NFR)
+
+- **NFR-1 — never-raise (критично, self-hosting).** Сбой записи/чтения урока **никогда** не роняет
+  и не тормозит конвейер. Любая ошибка детектора/записи → лог WARNING + продолжение основного
+  потока. Журнал — наблюдатель, не участник пайплайна.
+- **NFR-2 — Kill-switch.** Флаг `lessons_enabled` (env `ORCH_LESSONS_ENABLED`). `False` →
+  автозапись и эндпоинты инертны (нулевая регрессия, поведение конвейера байт-в-байт прежнее).
+- **NFR-3 — Аддитивность / изоляция enduro.** Только новая таблица + новый leaf + новые эндпоинты +
+  тонкие врезки. `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схема
+  существующих таблиц — **байт-в-байт не тронуты**. Общая БД: enduro-trails не затронут.
+- **NFR-4 — Restart-safe / идемпотентность таблицы.** `CREATE TABLE IF NOT EXISTS` + `_ensure_column`
+  (паттерн `repo_freeze`/`coverage_baseline`) — безопасно на живой БД, повторный старт без эффекта.
+- **NFR-5 — Лёгкость.** Запись — один `INSERT`, чтение — простые `SELECT` (общий хост впритык:
+  RAM 171Mi free, диск 92%). Никаких фоновых потоков/сканов.
+- **NFR-6 — Схема-forward-proof.** Колонки атрибуции добавлены сразу (BR-2), чтобы не
+  переделывать схему на живой БД, когда появится ретроспективщик.
+- **NFR-7 — Self-hosting безопасность.** Модуль только пишет/читает БД и отдаёт JSON — не
+  деплоит, не рестартит прод, не трогает `main`, не порождает процессы/сеть.
+
+## 6. Допущения и ограничения
+- Журнал уроков — **исключение** из правила «наблюдатель отделён от наблюдаемого» (§2 эпика): это
+  историческая память петли, не realtime-мониторинг → допустимо в БД орка; запись best-effort.
+- Точки автозаписи привязаны к существующим choke-point: `stage_engine._handle_qg_failure_rollbacks`
+  (откаты), `merge_gate` (HOLD/transient-классификатор ORCH-093), `launcher` (timeout/requeue
+  транзиентов). Архитектор уточняет точный набор и сигнатуры врезок.
+- Набор значений `lesson_type` / `attribution` / `target_domain` — конвенция (строковые слаги),
+  не enum-констрейнт БД (forward-compatible; новый тип не требует миграции).
+- Общая прод-БД с enduro: любое поле repo-scoped, фильтрация на уровне выборки.
+
+## 7. Критерии успеха
+Таблица `lessons` создаётся идемпотентно на старте; автозаписаны ≥2–3 типа отклонений из реального
+прогона; `GET /lessons` и `POST /lessons` работают; атрибутивные колонки присутствуют и
+проставляемы; kill-switch выключает всё без регрессии; `pytest tests/ -q` зелёный; доки+CHANGELOG
+обновлены. Детальные PASS/FAIL — `03-acceptance-criteria.md`.
+
+## 8. Риски
+- Врезка детектора в горячий путь конвейера → риск регрессии при сбое записи. Митигация: NFR-1
+  never-raise + kill-switch.
+- Рост таблицы со временем (автозапись на каждом откате/ретрае). Митигация: лёгкие строки;
+  будущая ретенция — вне объёма, отметить в `10-tech-risks.md` (архитектор).
+- Недооформленная схема атрибуции → переделка на живой БД. Митигация: BR-2/NFR-6 (колонки сразу).
+- Детали и архитектурные развилки (точные точки врезки, индексы, дедуп автозаписей) — задача
+  архитектора (`06-adr/`, `10-tech-risks.md`).

docs/work-items/ORCH-098/02-trz.md

@@ -0,0 +1,163 @@
+---
+work_item: ORCH-098
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-098 — FND: машинный журнал уроков
+
+Work Item: **ORCH-098** · Repo: **orchestrator** · Стадия: analysis
+
+> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
+> Архитектурное обоснование/решения (точные сигнатуры врезок, индексы, дедуп, ретенция) — задача
+> архитектора (`06-adr`).
+
+## 1. Сводка изменения
+
+Ввести **машинный журнал уроков** — аддитивную таблицу `lessons` + чистый leaf-модуль
+`src/lessons.py` (never-raise, kill-switch) по образцу `serial_gate.py` / `coverage_gate.py` /
+`metrics.py`. Модуль несёт: helper записи урока (`record`), read-only выборку (`get_lessons`),
+обновление (`update_lesson`), `snapshot()` для `GET /queue`. Автозапись ≥2–3 типов отклонений —
+тонкими best-effort врезками в существующие choke-point `stage_engine.py` / `merge_gate.py` /
+`launcher.py`. Два новых HTTP-эндпоинта (`GET /lessons`, `POST /lessons`) в `main.py`. Схема несёт
+**сразу** нуллабельные колонки атрибуции (требование Славы 10.06). Конвейер (`STAGE_TRANSITIONS` /
+`QG_CHECKS` / `check_*` / machine-verdict) — **не тронут**; enduro — не затронут.
+
+## 2. Задействованные модули / пути
+| Путь | Действие |
+|------|----------|
+| `src/db.py` | изменить — `CREATE TABLE IF NOT EXISTS lessons` в `init_db()`; helper'ы `record_lesson` / `get_lessons` / `update_lesson` / `lessons_snapshot` |
+| `src/lessons.py` | **создать** — leaf: `record(...)`, `get(...)`, `update(...)`, `snapshot()`, константы `LessonType`/`Attribution`/`Domain`, `applies()`, never-raise |
+| `src/config.py` | изменить — флаг `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`) + опц. `lessons_query_limit_default` |
+| `src/stage_engine.py` | изменить — best-effort врезка `lessons.record(...)` в `_handle_qg_failure_rollbacks` (откаты gate-fail) и в ветку post-deploy `DEGRADED` → freeze |
+| `src/merge_gate.py` | изменить — best-effort врезка в HOLD/regression-guard HOLD и в транзиент-классификатор (`_classify_merge_response == "transient"` / merge-retry-исчерпан) |
+| `src/agents/launcher.py` | изменить — best-effort врезка при timeout-kill / транзиент-requeue агента |
+| `src/main.py` | изменить — эндпоинты `GET /lessons`, `POST /lessons` (+опц. `POST /lessons/{id}`); блок `lessons` в `GET /queue` |
+| `tests/test_lessons.py` | **создать** — unit + integration (см. `04-test-plan.yaml`) |
+| `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md` | изменить — документация |
+
+## 3. Функциональные требования
+
+### FR-1 — Таблица `lessons` (BR-1, BR-2)
+Аддитивная идемпотентная таблица в `db.init_db()` (паттерн `repo_freeze`/`coverage_baseline`):
+
+```sql
+CREATE TABLE IF NOT EXISTS lessons (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at    TEXT,
+    -- тип отклонения (slug-конвенция, не enum-констрейнт)
+    lesson_type   TEXT NOT NULL,
+    -- контекст
+    work_item_id  TEXT,
+    task_id       INTEGER,
+    stage         TEXT,
+    agent         TEXT,
+    repo          TEXT,
+    -- анализ
+    root_cause    TEXT,
+    suggestion    TEXT,
+    -- статус
+    status        TEXT NOT NULL DEFAULT 'new',   -- new|in_progress|closed|linked
+    related_task  TEXT,
+    -- АТРИБУЦИЯ (BR-2, Слава 10.06) — нуллабельные, заполняются позже
+    attribution   TEXT,                          -- platform|project|both|unknown
+    target_repo   TEXT,                          -- кого касается (orchestrator|enduro-trails|…)
+    target_domain TEXT,                          -- reliability|quality|economy|features|scale
+    -- учёт
+    source        TEXT,                          -- auto|manual
+    detail        TEXT                           -- свободный JSON/текст (payload детектора)
+);
+CREATE INDEX IF NOT EXISTS idx_lessons_type_status ON lessons (lesson_type, status);
+CREATE INDEX IF NOT EXISTS idx_lessons_repo        ON lessons (repo);
+```
+Колонки атрибуции создаются **сразу** и нуллабельны (NFR-6). На уже созданной таблице новые
+колонки добавляются `_ensure_column` (forward-safe). Никакого `enum`-констрейнта — значения суть
+конвенция строковых слагов (forward-compatible).
+
+### FR-2 — Helper записи `lessons.record(...)` (BR-3, BR-5; NFR-1)
+Сигнатура (уточняет архитектор), напр.:
+`record(lesson_type, *, work_item_id=None, task_id=None, stage=None, agent=None, repo=None,
+root_cause=None, suggestion=None, status="new", related_task=None, attribution=None,
+target_repo=None, target_domain=None, source="auto", detail=None) -> int | None`.
+- При `lessons_enabled is False` → немедленный no-op (`None`), без обращения к БД.
+- Оборачивает `db.record_lesson` в `try/except` → при любой ошибке `logger.warning` + `None`
+  (**never-raise**, NFR-1). Возвращает `id` вставленной строки при успехе.
+- `source="auto"` для детекторов, `source="manual"` для ручной записи.
+
+### FR-3 — Автозапись отклонений (BR-3)
+Минимум 2–3 типа, best-effort (каждая врезка обёрнута/делегирует в never-raise `record`):
+- **FR-3a — gate-fail / rollback** — в `stage_engine._handle_qg_failure_rollbacks`: при откате на
+  `development` (reviewer `REQUEST_CHANGES`, tester `check_tests_passed` FAIL, staging FAILED,
+  deploy FAILED) → `record("gate_failure", stage=…, agent=…, work_item_id=…, repo=…,
+  root_cause=reason)`. Тип откатной причины → в `detail`/`root_cause`.
+- **FR-3b — merge HOLD / regression-guard HOLD** — в `merge_gate` (путь HOLD `_handle_merge_verify`
+  / `main_regressed_alerts_total` инкремент) → `record("merge_hold", …, root_cause=…)`.
+- **FR-3c — транзиент-ретрай** — в `merge_gate._classify_merge_response`-ветке `"transient"`
+  (Gitea `405`/`5xx`) и/или `launcher` timeout-kill / транзиент-requeue (Anthropic `Overloaded`) →
+  `record("transient_retry", …, detail=<код/причина>)`.
+- **FR-3d (желательно) — post-deploy DEGRADED** — в ветке `stage_engine`, где post-deploy
+  `DEGRADED`/rollback ведёт к `set_repo_freeze` (ORCH-088/021) → `record("deploy_degraded", …,
+  attribution=None|"unknown", target_repo=repo)` — урок «деплой OK / прод сломан» (слой-3, ET-8),
+  атрибуцию проставит ретроспективщик/человек позже.
+
+Дедуп/частота автозаписи (чтобы не плодить дубли на ретраях) — решение архитектора (например,
+ключ `work_item_id+stage+lesson_type` в окне); если не реализуется в v1 — отметить в `10-tech-risks.md`.
+
+### FR-4 — Read-only выборка (BR-4)
+`db.get_lessons(*, lesson_type=None, status=None, repo=None, work_item_id=None, limit=N) ->
+list[dict]` (параметризованный `SELECT … ORDER BY id DESC LIMIT ?`). `lessons.get(...)` —
+never-raise обёртка → `[]` при ошибке. `lessons.snapshot()` — лёгкая сводка (счётчики по
+типу/статусу, последние N) для `GET /queue`, never-raise → `{}`.
+
+### FR-5 — Ручная запись + обновление (BR-5, BR-6)
+- `POST /lessons` (тело JSON) → `lessons.record(..., source="manual")`. Возвращает `{id}`.
+- `POST /lessons/{id}` (или поля в `POST /lessons`) → `lessons.update(id, status=…,
+  attribution=…, target_repo=…, target_domain=…, related_task=…, root_cause=…, suggestion=…)` →
+  `db.update_lesson` (`UPDATE … SET … updated_at=datetime('now')`). Позволяет ретроспективщику/
+  человеку классифицировать автозаписанный `unknown`. never-raise.
+
+### FR-6 — Kill-switch + изоляция (NFR-2, NFR-3)
+`lessons_enabled=False` → `record`/`get`/`update`/`snapshot` инертны, эндпоинты возвращают
+`{"enabled": false}` (паттерн `metrics_endpoint_enabled`), врезки no-op. Поведение конвейера —
+байт-в-байт прежнее. enduro не затронут (общая БД, аддитивная таблица).
+
+## 4. Изменения API
+Новые эндпоинты в `src/main.py` (стиль `GET /queue` / `POST /coverage/baseline`):
+- **`GET /lessons`** — read-only выборка. Query: `type`, `status`, `repo`, `work_item`, `limit`
+  (дефолт из конфига). Ответ: `{"enabled": bool, "lessons": [ {…строка…} ]}`. Всегда `200`.
+- **`POST /lessons`** — ручная запись. Тело: `lesson_type` (обяз.) + опциональные поля контекста/
+  анализа/атрибуции. Ответ: `{"id": <int>}` или `{"enabled": false}`.
+- **(опц.) `POST /lessons/{id}`** — обновление статуса/атрибуции/привязки задачи. Ответ `{"ok": bool}`.
+- `GET /queue` — добавить read-only ключ `"lessons": lessons.snapshot()` (рядом с `serial_gate`/
+  `coverage`/`bug_fast_track`). Существующие ключи — без изменений.
+
+`GET /health` / `GET /status` / `GET /metrics` / прочие эндпоинты — **байт-в-байт прежние**.
+
+## 5. Изменения схемы БД
+**Новая аддитивная таблица `lessons`** (FR-1) + два индекса, всё `IF NOT EXISTS` / `_ensure_column`.
+Существующие таблицы (`tasks`/`jobs`/`agent_runs`/`events`/`job_deps`/`repo_freeze`/
+`coverage_baseline`/`tracker_messages`) — **не тронуты**. Колонки атрибуции — сразу, нуллабельные
+(BR-2/NFR-6). Restart-safe, идемпотентно, безопасно на живой общей прод-БД (enduro не затронут).
+
+## 6. Требования к новым/изменённым QG checks
+**Нет.** Журнал уроков — наблюдатель, **не** Quality Gate. `QG_CHECKS` / `check_*` /
+machine-verdict-ключи (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`/
+`coverage_status:`) — байт-в-байт не тронуты. Журнал не влияет на продвижение по стадиям.
+
+## 7. Совместимость / регресс
+- **Kill-switch** `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`): `False` → полная
+  инертность, нулевая регрессия.
+- **never-raise** на всех публичных функциях и врезках (NFR-1) — сбой журнала не роняет конвейер.
+- **Аддитивно**: только новая таблица + leaf + эндпоинты + тонкие врезки; ничего существующего не
+  переписывается.
+- **Изоляция enduro**: общая БД, новая таблица; репо-скоуп через поле/фильтр выборки.
+- **Обратимость**: выключение флага возвращает прод к доресурсному поведению мгновенно.
+- **Self-hosting безопасность** (NFR-7): модуль не деплоит/не рестартит прод/не трогает `main`/без
+  процессов/сети.
+- **Артефакты pipeline:** задача создаёт/обновляет стандартный пакет (`01`–`04` + `06-adr` от
+  архитектора, `12`/`13`/`14`/`15`/`17`/`18` по ходу конвейера). Сам журнал — БД-сущность, не
+  номерной артефакт.

docs/work-items/ORCH-098/03-acceptance-criteria.md

@@ -0,0 +1,123 @@
+---
+work_item: ORCH-098
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки (Acceptance Criteria): ORCH-098 — FND: машинный журнал уроков
+
+Work Item: **ORCH-098** · Repo: **orchestrator** · Стадия: analysis
+
+Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
+считается провалом). Reviewer/tester проверяет их буквально по файлам репозитория и тестам.
+
+---
+
+## AC-1 — Аддитивная таблица уроков
+
+**Условие:** `db.init_db()` создаёт таблицу `lessons` идемпотентно.
+- **PASS:** в `src/db.py` есть `CREATE TABLE IF NOT EXISTS lessons (...)` со всеми полями
+  (`lesson_type`, контекст `work_item_id/task_id/stage/agent/repo`, `root_cause`, `suggestion`,
+  `status`+`related_task`, `created_at`); повторный `init_db()` не падает и не дублирует; таблица
+  создаётся на общей прод-БД без изменения существующих таблиц.
+- **FAIL:** таблицы нет / создаётся не идемпотентно / отсутствует любое поле из BR-1 / меняется
+  схема существующей таблицы.
+
+---
+
+## AC-2 — Поля атрибуции присутствуют с самого начала
+
+**Условие:** схема `lessons` несёт нуллабельные колонки атрибуции (требование Славы 10.06).
+- **PASS:** колонки `attribution` (`platform`/`project`/`both`/`unknown`), `target_repo`,
+  `target_domain` существуют сразу, нуллабельны, допускают пустое/`unknown` при автозаписи и
+  проставляются позже через update.
+- **FAIL:** хотя бы одной из трёх колонок нет в исходной схеме / колонка `NOT NULL` без дефолта /
+  атрибуцию нельзя проставить после создания записи.
+
+---
+
+## AC-3 — Автозапись ≥2–3 типов отклонений
+
+**Условие:** из кода автоматически (best-effort, `source="auto"`) пишутся минимум 2–3 типа уроков.
+- **PASS:** есть врезки `lessons.record(...)` минимум в двух-трёх точках из:
+  `stage_engine._handle_qg_failure_rollbacks` (gate-fail/откат), `merge_gate` (HOLD/transient),
+  `launcher` (timeout/transient-requeue); интеграционный тест подтверждает появление строки в
+  `lessons` после смоделированного отклонения.
+- **FAIL:** автозаписи нет / реализован <2 типов / врезка может бросить исключение в горячий путь.
+
+---
+
+## AC-4 — Read-only выборка
+
+**Условие:** уроки можно прочитать через эндпоинт и сводку в `GET /queue`.
+- **PASS:** `GET /lessons` возвращает `200` с массивом уроков, поддерживает фильтры
+  (type/status/repo/work_item/limit); `GET /queue` содержит read-only блок `lessons`; ни один
+  путь чтения не мутирует данные.
+- **FAIL:** эндпоинта нет / не фильтрует / чтение мутирует данные / блока в `/queue` нет.
+
+---
+
+## AC-5 — Ручная запись и обновление
+
+**Условие:** оператор/Стрим кладёт урок руками и может его доклассифицировать.
+- **PASS:** `POST /lessons` создаёт урок (`source="manual"`, можно задать атрибуцию); обновление
+  (`POST /lessons/{id}` или поля) меняет `status`/`attribution`/`target_*`/`related_task` и
+  стампит `updated_at`.
+- **FAIL:** ручной записи нет / нельзя проставить атрибуцию / нельзя обновить автозаписанный урок.
+
+---
+
+## AC-6 — never-raise (сбой журнала не роняет конвейер)
+
+**Условие:** любая ошибка записи/чтения урока изолирована от пайплайна.
+- **PASS:** все публичные функции `src/lessons.py` и все врезки обёрнуты так, что исключение БД/
+  любого источника → `logger.warning` + безопасный дефолт (`None`/`[]`/`{}`); юнит-тест с
+  замоканной падающей БД подтверждает, что вызывающий код (откат/HOLD/retry) не падает.
+- **FAIL:** исключение из журнала пробивается в `stage_engine`/`merge_gate`/`launcher`/эндпоинт.
+
+---
+
+## AC-7 — Kill-switch и нулевая регрессия
+
+**Условие:** `lessons_enabled=False` делает функционал инертным.
+- **PASS:** при `False` `record`/`get`/`update`/`snapshot` — no-op (без обращения к БД), эндпоинты
+  отдают `{"enabled": false}`, врезки не пишут; поведение конвейера и `GET /queue` (помимо нового
+  блока) — байт-в-байт прежнее; enduro-trails не затронут.
+- **FAIL:** при `False` журнал что-то пишет/ломает / меняется поведение конвейера / затронут enduro.
+
+---
+
+## AC-8 — Инварианты конвейера не тронуты
+
+**Условие:** изменение не касается машины стадий и гейтов.
+- **PASS:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, функции `check_*`, machine-verdict-ключи и
+  схема существующих таблиц — **диффом не затронуты**; журнал не влияет на продвижение по стадиям.
+- **FAIL:** изменён любой из перечисленных артефактов / журнал участвует в решении гейта.
+
+---
+
+## AC-9 — Тесты, документация, CHANGELOG
+
+**Условие:** изменение проверено и задокументировано.
+- **PASS:** `pytest tests/ -q` зелёный (включая новый `tests/test_lessons.py` с unit+integration);
+  обновлены `CLAUDE.md` + `docs/architecture/README.md`; в задаче есть `06-adr/` (архитектор);
+  `CHANGELOG.md` дополнен.
+- **FAIL:** тесты падают / нет покрытия новой логики / документация или CHANGELOG не обновлены.
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+| AC | Покрывает |
+|----|-----------|
+| AC-1 | BR-1 / FR-1 |
+| AC-2 | BR-2 / FR-1 / NFR-6 |
+| AC-3 | BR-3 / FR-2 / FR-3 |
+| AC-4 | BR-4 / FR-4 |
+| AC-5 | BR-5 / BR-6 / FR-5 |
+| AC-6 | NFR-1 / FR-2 |
+| AC-7 | NFR-2 / NFR-3 / FR-6 |
+| AC-8 | NFR-3 / FR-6 |
+| AC-9 | NFR-1…NFR-7 (верификация) |

docs/work-items/ORCH-098/04-test-plan.yaml

@@ -0,0 +1,91 @@
+work_item: ORCH-098
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+title: "Журнал уроков: таблица, автозапись отклонений, выборка, ручная запись, never-raise"
+framework: pytest
+scope: >
+  Покрывается: создание аддитивной таблицы lessons (идемпотентность, поля атрибуции),
+  helper записи record(), автозапись из choke-point (gate-fail/HOLD/transient), read-only
+  выборка get_lessons + snapshot, ручная запись/обновление, kill-switch, never-raise.
+  Вне покрытия: ретроспективщик (E2), приоритизатор (E3), автоклассификация атрибуции,
+  слой-3 детекция здоровья продукта.
+notes: >
+  Тесты используют изолированную временную SQLite-БД (фикстура init_db во временном файле).
+  Полный регресс tests/ должен оставаться зелёным. Self-hosting: журнал never-raise — ни один
+  тест не должен показать, что сбой записи урока роняет конвейер.
+
+tests:
+  - id: TC-01
+    type: unit
+    description: "init_db() создаёт таблицу lessons идемпотентно (двойной вызов не падает, нет дублей); присутствуют все поля BR-1."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "Схема lessons несёт нуллабельные колонки атрибуции attribution/target_repo/target_domain; запись без них проходит (NULL/unknown), update проставляет их позже."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-03
+    type: unit
+    description: "lessons.record() вставляет строку с переданными полями (source=auto/manual), возвращает id; created_at заполняется."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-04
+    type: unit
+    description: "never-raise: при замоканной падающей БД record/get/update/snapshot возвращают None/[]/{} и не бросают исключение (logger.warning)."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-05
+    type: unit
+    description: "kill-switch: при lessons_enabled=False record/get/update/snapshot инертны (no-op, без обращения к БД)."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "get_lessons фильтрует по type/status/repo/work_item и соблюдает limit; порядок ORDER BY id DESC."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "update_lesson меняет status/attribution/target_*/related_task и стампит updated_at; несуществующий id безопасен."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-08
+    type: integration
+    description: "Автозапись gate-fail: смоделированный откат на development в _handle_qg_failure_rollbacks создаёт строку lessons type=gate_failure с контекстом (stage/agent/work_item/repo)."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-09
+    type: integration
+    description: "Автозапись transient/HOLD: транзиент-ветка merge_gate (или timeout/requeue launcher) пишет урок type=transient_retry/merge_hold; сбой записи не ломает основной путь (never-raise в горячем пути)."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-10
+    type: integration
+    description: "GET /lessons возвращает 200 с массивом и фильтрами; GET /queue содержит read-only блок lessons; чтение не мутирует данные."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-11
+    type: integration
+    description: "POST /lessons создаёт ручной урок (source=manual, с атрибуцией); POST /lessons/{id} обновляет его; при lessons_enabled=False эндпоинты отдают {enabled:false}."
+    module: tests/test_lessons.py
+    expected: PASS
+
+  - id: TC-12
+    type: unit
+    description: "Инварианты конвейера не тронуты: STAGE_TRANSITIONS/QG_CHECKS/machine-verdict-ключи неизменны (структурный анти-регресс по составу реестра)."
+    module: tests/test_lessons.py
+    expected: PASS

docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md

@@ -0,0 +1,244 @@
+---
+work_item: ORCH-098
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Машинный журнал уроков `lessons` — аддитивная таблица + observer-leaf
+
+Work Item: **ORCH-098** — FND: машинный журнал уроков (структурированная база отклонений конвейера)
+Стадия: **architecture**
+Сквозная регистрация: **`docs/architecture/adr/adr-0034-lessons-journal.md`** (решение
+кросс-каттинговое: новый компонент + новая таблица на общей прод-БД + фундамент эпика
+саморазвития).
+
+## Статус
+Proposed
+
+## Контекст
+
+ORCH-098 — шаг 1 («Фундамент», F2) эпика саморазвития: формализовать свободнотекстовые «уроки»
+из `memory/` в **машинную структурированную таблицу отклонений конвейера**, на которой позже
+встанут ретроспективщик (E2), приоритизатор RICE (E3) и Стрим. BRD/TRZ уже зафиксировали состав
+полей, набор эндпоинтов и структуру leaf-модуля; нормативное требование Славы 10.06 — колонки
+**атрибуции** в схеме **с самого начала** (нуллабельные), чтобы не переделывать схему на живой
+общей прод-БД.
+
+Сверено по коду (recon):
+- **Образец observer-leaf**: `src/serial_gate.py`, `src/coverage_gate.py`, `src/metrics.py` —
+  чистые leaf'ы, импортируют только `config`+`db`, `applies(repo)`-first, never-raise, `snapshot()`
+  для `GET /queue`.
+- **БД-паттерн**: `db.get_db() -> sqlite3.Connection` (`row_factory=sqlite3.Row`, `.close()` в
+  `finally`); `db.init_db()` — `executescript` с `CREATE TABLE IF NOT EXISTS …`; идемпотентные
+  миграции `_ensure_column(conn, table, column, decl)` (`src/db.py:341`). Эталон аддитивной таблицы
+  — `repo_freeze`, `coverage_baseline`; атомарный helper — `ratchet_coverage_baseline` (`db.py:251`).
+- **Choke-point'ы автозаписи** (точные сигнатуры):
+  - `stage_engine._handle_qg_failure_rollbacks(task_id, current_stage, repo, work_item_id, branch,
+    agent, qg_name, reason, result)` (`src/stage_engine.py:728`) — все нужные поля контекста
+    локально доступны.
+  - post-deploy `DEGRADED → set_repo_freeze` (`src/stage_engine.py:~1993`) — доступны `repo`,
+    `work_item_id`, `branch`, локально собранный `reason`.
+  - `merge_gate._handle_merge_verify(task_id, repo, work_item_id, branch, result)`
+    (`src/merge_gate.py:1588`); ветка HOLD ставит `result.note="merge-not-verified-hold"` (~`:1695`).
+  - `merge_gate._classify_merge_response(repo, branch, index, status_code) -> "transient"|"terminal"`
+    (`src/merge_gate.py:811`).
+  - `launcher._watchdog`/`stop_process` (timeout-kill) и `launcher._finalize_transient(job_id, agent,
+    run_id, exit_code, job, retry_after)` (`src/agents/launcher.py:997`) — транзиент-requeue с
+    бюджетом `transient_attempts`.
+- **Конфиг-паттерн**: pydantic `BaseSettings` с авто-биндингом `ORCH_*`; пары `*_enabled` (bool) +
+  `*_repos` (CSV); `is_self_hosting_repo(repo)` (`src/qg/checks.py:520`).
+
+«Как есть» не годится: уроки в `memory/` не машиночитаемы — нельзя считать паттерны, нельзя
+приоритизировать. Нужна структурированная таблица, но врезанная в **горячий путь** конвейера, что
+на self-hosting прод-инстансе с общей БД (enduro-trails) требует жёсткой изоляции.
+
+## Решение
+
+### Сводка
+
+Ввести **аддитивную идемпотентную таблицу `lessons`** + **чистый observer-leaf `src/lessons.py`**
+(never-raise, kill-switch) по образцу `serial_gate`/`coverage_gate`/`metrics`. Leaf несёт
+`record()` / `get()` / `update()` / `snapshot()`. Автозапись 4 типов отклонений — тонкими
+best-effort врезками в существующие choke-point. Два-три HTTP-эндпоинта в `main.py`. Колонки
+атрибуции — в схеме сразу, нуллабельные. **Конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/
+machine-verdict) и схемы существующих таблиц — байт-в-байт не тронуты; enduro не затронут.**
+
+### D1 — Таблица `lessons`: аддитивная, идемпотентная, forward-proof (BR-1, BR-2; AC-1, AC-2)
+
+`CREATE TABLE IF NOT EXISTS lessons (…)` в `db.init_db()` (паттерн `repo_freeze`):
+
+```sql
+CREATE TABLE IF NOT EXISTS lessons (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at    TEXT,
+    lesson_type   TEXT NOT NULL,                 -- slug-конвенция, НЕ enum-констрейнт
+    work_item_id  TEXT,
+    task_id       INTEGER,
+    stage         TEXT,
+    agent         TEXT,
+    repo          TEXT,
+    root_cause    TEXT,
+    suggestion    TEXT,
+    status        TEXT NOT NULL DEFAULT 'new',    -- new|in_progress|closed|linked
+    related_task  TEXT,
+    attribution   TEXT,                           -- platform|project|both|unknown (NULLABLE)
+    target_repo   TEXT,                           -- orchestrator|enduro-trails|… (NULLABLE)
+    target_domain TEXT,                           -- reliability|quality|economy|features|scale (NULLABLE)
+    source        TEXT,                           -- auto|manual
+    detail        TEXT                            -- свободный JSON/текст (payload детектора)
+);
+CREATE INDEX IF NOT EXISTS idx_lessons_type_status ON lessons (lesson_type, status);
+CREATE INDEX IF NOT EXISTS idx_lessons_repo        ON lessons (repo);
+CREATE INDEX IF NOT EXISTS idx_lessons_wi_type     ON lessons (work_item_id, lesson_type);
+```
+
+**Инварианты:**
+- Все три колонки **атрибуции создаются сразу и нуллабельны** (NFR-6, требование Славы 10.06): на
+  живой уже-существующей таблице добавляются через `_ensure_column(conn, "lessons", "<col>",
+  "TEXT")` — forward-safe, restart-safe, без миграции данных.
+- **Нет `enum`/`CHECK`-констрейнта** на `lesson_type`/`attribution`/`target_domain` — значения суть
+  конвенция строковых слагов (новый тип урока не требует миграции схемы; §6 допущений BRD).
+- **Третий индекс `idx_lessons_wi_type`** добавлен сверх двух из TRZ — обслуживает дедуп-запрос
+  автозаписи (D4) одним indexed-lookup'ом (NFR-5).
+
+DDL-хелперы в `db.py` (стиль `coverage_baseline`): `record_lesson(...) -> int|None`,
+`get_lessons(...) -> list[dict]`, `update_lesson(id, **fields) -> bool`, `lessons_snapshot() -> dict`.
+Каждый открывает `get_db()` и закрывает в `finally`.
+
+### D2 — Observer-leaf `src/lessons.py`: scope **kill-switch only**, НЕ repo-gated (BR-3/4/5/6; NFR-1/2/7)
+
+Чистый leaf, импортирует только `config`+`db` (lazy `notifications` при необходимости); **никогда
+не импортирует `stage_engine`/`merge_gate`/`launcher`** (анти-цикл). Публичный контракт:
+
+```python
+def record(lesson_type, *, work_item_id=None, task_id=None, stage=None, agent=None, repo=None,
+           root_cause=None, suggestion=None, status="new", related_task=None, attribution=None,
+           target_repo=None, target_domain=None, source="auto", detail=None) -> int | None
+def get(*, lesson_type=None, status=None, repo=None, work_item_id=None, limit=None) -> list[dict]
+def update(lesson_id, **fields) -> bool
+def snapshot() -> dict
+```
+
+**Ключевое решение D2 — расхождение с шаблоном гейт-leaf'ов: журнал НЕ скоупится по repo.**
+В отличие от `serial_gate`/`coverage_gate`/`bug_fast_track` (которые *действуют* на конкретный репо
+и потому имеют пару `*_repos`), журнал — **observer-only**: запись строки никогда не влияет на
+пайплайн ни одного репо. Поэтому:
+- единственный регулятор — глобальный kill-switch `lessons_enabled` (env `ORCH_LESSONS_ENABLED`,
+  дефолт `True`); **`lessons_repos` НЕ вводится**;
+- recorder пишет уроки про **любой** репо (включая enduro-trails) — урок про деградацию деплоя
+  enduro ценен для петли самообучения; репо-скоуп терял бы этот сигнал;
+- `repo`-разрез — на уровне **выборки** (`get(repo=…)`, фильтр `snapshot()`), как зафиксировано в
+  §6 BRD «репо-скоуп через поле/фильтр выборки».
+- **enduro не затронут (NFR-3):** запись observer-строки про enduro не меняет ни одной стадии/гейта
+  enduro — это чистая память орка.
+
+**never-raise (NFR-1, AC-6):** при `lessons_enabled is False` каждая функция — немедленный no-op
+(`record→None`, `get→[]`, `update→False`, `snapshot→{}`) **без обращения к БД**. При `True` — тело в
+`try/except Exception → logger.warning(...) + безопасный дефолт`. Журнал **не** деплоит, **не**
+рестартит прод, **не** трогает `main`, **не** порождает процессов/сети (NFR-7).
+
+### D3 — Точки автозаписи: 4 детектора, тонкая врезка одним вызовом (BR-3; FR-3; AC-3)
+
+Каждая врезка = локальный импорт + один вызов `lessons.record(...)`, обёрнутый в защитный
+`try/except` (паттерн post-deploy-freeze-врезки `stage_engine.py:~1993`), чтобы даже ошибка импорта
+не пробилась в горячий путь:
+
+| Тип (`lesson_type`) | Choke-point | Контекст врезки |
+|---|---|---|
+| `gate_failure` | `stage_engine._handle_qg_failure_rollbacks` (после решения об откате на `development`) | `work_item_id, task_id, stage=current_stage, agent, repo, root_cause=reason, detail=qg_name` |
+| `merge_hold` | `merge_gate._handle_merge_verify` (ветка HOLD, `result.note="merge-not-verified-hold"`) | `work_item_id, task_id, repo, stage="deploy", root_cause="merge-not-verified-hold"` |
+| `transient_retry` | **budget-exhaustion**: `merge_gate` (merge-retry исчерпан) и/или `launcher._finalize_transient` (исчерпан `transient_attempts`) | `work_item_id?, repo, agent?, stage?, detail=<код/причина>` |
+| `deploy_degraded` | `stage_engine` post-deploy `DEGRADED → set_repo_freeze` | `work_item_id, repo, stage="deploy", root_cause=reason, attribution="unknown", target_repo=repo, target_domain="reliability"` |
+
+Все врезки — `source="auto"`. Это **4 типа > минимума 2–3** (BR-3). `(г) deploy_degraded` (желаемый
+по TRZ) включён как полноценный детектор: это урок слоя-3 «деплой OK / прод сломан» (ET-8),
+ради которого Слава и потребовал атрибуцию.
+
+### D4 — Дедуп автозаписи: один indexed-SELECT в окне (BR-3; FR-3 «решение архитектора»; NFR-5)
+
+Риск: транзиент-ретраи/повторные откаты плодят дубли. Решение — **дешёвый дедуп только для
+`source="auto"`** внутри `record()`: перед `INSERT` — один indexed-lookup
+```sql
+SELECT 1 FROM lessons
+WHERE work_item_id = ? AND lesson_type = ? AND (stage IS ? OR ?)  -- stage-match
+  AND created_at > datetime('now', ?)                            -- '-<window> seconds'
+LIMIT 1;
+```
+по индексу `idx_lessons_wi_type` (D1). Найдено → no-op (`return None`, лог DEBUG). Окно —
+`lessons_dedup_window_s` (env `ORCH_LESSONS_DEDUP_WINDOW_S`, дефолт `3600`). **`source="manual"`
+дедуп НЕ проходит** (оператор/Стрим всегда может записать). Это один лёгкий `SELECT` (NFR-5), без
+фоновых сканов.
+
+**Доп. контроль флуда на самом шумном детекторе:** `transient_retry` пишется **только на исчерпании
+бюджета ретраев** (а не на каждом backoff) — это и есть ценный сигнал «транзиенты исчерпаны», а не
+шум каждой попытки. Так флуд гасится в источнике до дедупа.
+
+### D5 — Эндпоинты `main.py`: read-only выборка + ручная запись/обновление (BR-4/5/6; FR-4/5; AC-4/5)
+
+Стиль `GET /queue` / `POST /coverage/baseline`, все never-raise, при выключенном флаге →
+`{"enabled": false}`:
+- **`GET /lessons`** — query `type/status/repo/work_item/limit` (дефолт `lessons_query_limit_default`,
+  напр. 100) → `{"enabled": bool, "lessons": [...]}`, всегда `200`, только чтение.
+- **`POST /lessons`** — тело JSON, `lesson_type` обязателен → `lessons.record(..., source="manual")`
+  → `{"id": <int>}`.
+- **`POST /lessons/{id}`** — `lessons.update(id, status=…, attribution=…, target_repo=…,
+  target_domain=…, related_task=…, root_cause=…, suggestion=…)` → `{"ok": bool}`; стампит
+  `updated_at=datetime('now')`. Позволяет ретроспективщику/человеку доклассифицировать
+  автозаписанный `unknown`.
+- **`GET /queue`** — добавить read-only ключ `"lessons": lessons.snapshot()` рядом с
+  `serial_gate`/`coverage`. `snapshot()` — лёгкие `GROUP BY`-счётчики (по типу/статусу) + последние
+  N. Существующие ключи `/queue` и эндпоинты `/health|/status|/metrics` — **байт-в-байт прежние**.
+
+### D6 — Изоляция от конвейера и гейтов (NFR-3; AC-8)
+
+`STAGE_TRANSITIONS`, реестр `QG_CHECKS`, функции `check_*`, machine-verdict-ключи
+(`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`/`coverage_status:`) и
+схемы существующих таблиц — **диффом не затрагиваются**. Журнал — наблюдатель, **не** Quality Gate;
+он не участвует в решении о продвижении по стадиям. Никаких новых/изменённых QG-checks (FR-6).
+
+## Альтернативы
+
+- **Repo-скоуп `lessons_repos` (как у гейтов)** — отвергнуто: журнал observer-only, не действует на
+  репо; скоуп терял бы ценные enduro-уроки. Скоуп — на выборке (D2).
+- **Без дедупа в v1 (TRZ это допускает)** — отвергнуто как дефолт: транзиент-ретраи реально
+  флудят таблицу; дешёвый indexed-дедуп (D4) дешевле, чем последующая чистка. Бюджет-exhaustion +
+  окно дают двойную защиту при одном `SELECT`.
+- **Запись `transient_retry` на каждом backoff** — отвергнуто: шум; ценен факт исчерпания бюджета.
+- **Отдельная БД/файл для журнала** — отвергнуто: лишняя зависимость; общая SQLite-БД с аддитивной
+  таблицей соответствует принципу «минимум зависимостей» и паттерну `repo_freeze`/`coverage_baseline`.
+- **Фоновый агрегатор/ретенция-крон в v1** — отвергнуто: NFR-5 (без фоновых потоков/сканов);
+  ретенция — будущая задача (см. `10-tech-risks.md` TR-2).
+- **ORM** — отвергнуто: raw SQL достаточно (принцип «без ORM, если хватает raw SQL»).
+
+## Последствия
+
+- **+** Уроки становятся машиночитаемыми — фундамент для E2/E3/Стрим; атрибуция forward-proof
+  (колонки сразу, переделки живой БД не будет).
+- **+** Нулевая регрессия: kill-switch + never-raise + чистая аддитивность; enduro не затронут;
+  конвейер байт-в-байт прежний.
+- **+** Следует проверенному additive-observer-leaf шаблону (`serial_gate`/`coverage_gate`/`metrics`/
+  `cancel`/`bug_fast_track`) — низкий архитектурный риск, не требует `arch:major-change` (см.
+  `10-tech-risks.md` сводный вывод).
+- **−** Рост таблицы со временем (автозапись на отклонениях). Митигейшн: лёгкие строки + дедуп (D4) +
+  budget-exhaustion-only для транзиентов; ретенция — TR-2 (будущее).
+- **−** Лёгкое усложнение `record()` дедуп-запросом. Митигейшн: один indexed-SELECT, только для
+  `auto`, под окном; для `manual` пропускается.
+- **Откат:** `ORCH_LESSONS_ENABLED=false` → весь функционал инертен мгновенно (no-op, нулевая
+  регрессия). Полный откат — revert диффа; таблица `lessons` остаётся пустой/неиспользуемой,
+  существующих таблиц не касается.
+
+## Ссылки
+- BRD: `docs/work-items/ORCH-098/01-brd.md`
+- TRZ: `docs/work-items/ORCH-098/02-trz.md`
+- Acceptance: `docs/work-items/ORCH-098/03-acceptance-criteria.md`
+- Data: `docs/work-items/ORCH-098/08-data-requirements.md`
+- Infra: `docs/work-items/ORCH-098/07-infra-requirements.md`
+- Risks: `docs/work-items/ORCH-098/10-tech-risks.md`
+- Сквозной ADR: `docs/architecture/adr/adr-0034-lessons-journal.md`
+- Сверено по коду: `src/serial_gate.py`, `src/coverage_gate.py`, `src/metrics.py`, `src/db.py:251,341`,
+  `src/stage_engine.py:728,~1993`, `src/merge_gate.py:811,1588`, `src/agents/launcher.py:997`,
+  `src/main.py` (`GET /queue`, `POST /coverage/baseline`), `src/qg/checks.py:520`.

docs/work-items/ORCH-098/07-infra-requirements.md

@@ -0,0 +1,45 @@
+---
+work_item: ORCH-098
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 07 — Инфра-требования: ORCH-098 — машинный журнал уроков `lessons`
+
+Work Item: **ORCH-098** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable. Топология **не меняется**; файл создан для аудитопригодности (новая env-переменная).
+
+## I-1. Топология / окружения
+**N/A.** Новых контейнеров/портов/сети/томов нет. Таблица `lessons` живёт в существующей общей
+SQLite-БД (тот же том `./data`), эндпоинты обслуживаются текущим процессом `orchestrator` (8500) /
+`orchestrator-staging` (8501). Принцип «всё в Docker на одном сервере mva154» — соблюдён.
+
+## I-2. Переменные окружения / секреты
+Новые env (pydantic `BaseSettings`, авто-биндинг `ORCH_*`), все с безопасными дефолтами:
+
+| Env | Дефолт | Назначение |
+|---|---|---|
+| `ORCH_LESSONS_ENABLED` | `true` | kill-switch журнала (NFR-2); `false` → полная инертность |
+| `ORCH_LESSONS_DEDUP_WINDOW_S` | `3600` | окно дедупа автозаписи (ADR-001 D4) |
+| `ORCH_LESSONS_QUERY_LIMIT_DEFAULT` | `100` | дефолтный `limit` для `GET /lessons` |
+
+**`lessons_repos` СОЗНАТЕЛЬНО не вводится** — журнал observer-only и не скоупится по репо
+(ADR-001 D2). Секретов нет. `.env.example` дополнить тремя ключами для документируемости (значения —
+дефолтные, не секреты).
+
+## I-3. Деплой / рестарт
+- Изменение применяется штатным конвейером: **обязательный staging-гейт (8501) перед прод-деплоем**
+  орка (self-hosting инвариант). Прод-контейнер **не рестартить вне процедуры деплоя стадии**
+  `deploy`/`Confirm Deploy` (ORCH-059) — конвейер всех проектов встанет.
+- Таблица `lessons` создаётся идемпотентно при старте (`init_db()`) — на первом штатном запуске
+  нового образа, **без отдельной ручной миграции** (restart-safe, NFR-4). На живой БД enduro не
+  затронут.
+- Откат — `ORCH_LESSONS_ENABLED=false` (мгновенная инертность) либо revert образа.
+
+## I-4. CI/CD
+**Без изменений** в `.gitea/workflows/`. Новые тесты `tests/test_lessons.py` исполняются штатным
+шагом `pytest tests/ -q`. Новых системных/pip-зависимостей нет (raw SQL на stdlib `sqlite3`).

docs/work-items/ORCH-098/08-data-requirements.md

@@ -0,0 +1,76 @@
+---
+work_item: ORCH-098
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 08 — Требования к данным: ORCH-098 — машинный журнал уроков `lessons`
+
+Work Item: **ORCH-098** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable: задача **добавляет** одну таблицу на общую прод-БД. Схемы существующих таблиц —
+> не затрагиваются.
+
+## Изменения схемы БД
+
+**Новая аддитивная таблица `lessons`** + три индекса, создаются идемпотентно в `db.init_db()`
+(`CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS`), restart-safe (паттерн `repo_freeze`,
+`coverage_baseline`). На уже существующей таблице новые/будущие колонки добавляются через
+`_ensure_column(conn, "lessons", "<col>", "<decl>")` (`src/db.py:341`) — forward-safe, без миграции
+данных. DDL — см. ADR-001 D1.
+
+Существующие таблицы (`tasks`/`jobs`/`agent_runs`/`events`/`job_deps`/`repo_freeze`/
+`coverage_baseline`/`tracker_messages`) — **байт-в-байт не тронуты** (NFR-3, AC-8).
+
+## Новые/изменённые сущности
+
+Сущность **`lesson`** — одна запись структурированного отклонения конвейера. Колонки:
+
+| Колонка | Тип | Null | Назначение |
+|---|---|---|---|
+| `id` | INTEGER PK AUTOINCREMENT | — | суррогатный ключ |
+| `created_at` | TEXT `DEFAULT datetime('now')` | NOT NULL | момент записи |
+| `updated_at` | TEXT | NULL | момент последнего `update` |
+| `lesson_type` | TEXT | NOT NULL | slug-тип (`gate_failure`/`merge_hold`/`transient_retry`/`deploy_degraded`/…) |
+| `work_item_id` | TEXT | NULL | контекст: задача (`ORCH-NNN`/`ET-NNN`) |
+| `task_id` | INTEGER | NULL | контекст: внутренний id задачи |
+| `stage` | TEXT | NULL | контекст: стадия конвейера |
+| `agent` | TEXT | NULL | контекст: агент-роль |
+| `repo` | TEXT | NULL | контекст: репозиторий, **разрез выборки** |
+| `root_cause` | TEXT | NULL | анализ: корневая причина (если известна) |
+| `suggestion` | TEXT | NULL | анализ: предложенное улучшение (если есть) |
+| `status` | TEXT `DEFAULT 'new'` | NOT NULL | `new`/`in_progress`/`closed`/`linked` |
+| `related_task` | TEXT | NULL | связанная заведённая задача |
+| `attribution` | TEXT | **NULL** | **АТРИБУЦИЯ:** `platform`/`project`/`both`/`unknown` |
+| `target_repo` | TEXT | **NULL** | **АТРИБУЦИЯ:** кого касается улучшение |
+| `target_domain` | TEXT | **NULL** | **АТРИБУЦИЯ:** `reliability`/`quality`/`economy`/`features`/`scale` |
+| `source` | TEXT | NULL | `auto` (детектор) / `manual` (оператор/Стрим) |
+| `detail` | TEXT | NULL | свободный JSON/текст — payload детектора |
+
+**Инварианты данных:**
+- Три колонки **атрибуции** (`attribution`/`target_repo`/`target_domain`) присутствуют в исходной
+  схеме, **нуллабельны** (требование Славы 10.06, NFR-6, AC-2) — при автозаписи допустимо
+  пусто/`unknown`; проставляются позже через `update` (AC-5).
+- **Без `enum`/`CHECK`-констрейнтов** — значения `lesson_type`/`attribution`/`target_domain` суть
+  конвенция строковых слагов (forward-compatible: новый тип не требует миграции).
+- Индексы: `idx_lessons_type_status (lesson_type, status)` — выборка/snapshot; `idx_lessons_repo
+  (repo)` — репо-разрез; `idx_lessons_wi_type (work_item_id, lesson_type)` — дедуп автозаписи
+  (ADR-001 D4).
+
+## Совместимость данных / миграции
+
+- **Аддитивно / идемпотентно / restart-safe:** только новая таблица + индексы; повторный `init_db()`
+  не падает и не дублирует (NFR-4).
+- **Общая прод-БД (self-hosting):** таблица создаётся на том же файле БД, что обслуживает
+  orchestrator и enduro-trails. Уроки про любой репо хранятся в одной таблице; **изоляция enduro** —
+  таблица аддитивна и не участвует в пайплайне enduro (NFR-3); репо-разрез — поле `repo` + фильтр
+  выборки (ADR-001 D2).
+- **Объём строки** — короткие текстовые поля; `detail` — компактный payload. Запись — один `INSERT`,
+  чтение — простой параметризованный `SELECT … ORDER BY id DESC LIMIT ?` (NFR-5; общий хост впритык:
+  RAM/диск).
+- **Ретенция / архивация** — вне объёма v1; тренд роста и будущая стратегия — `10-tech-risks.md`
+  (TR-2).
+- **Миграция исторических уроков из `memory/`** — вне объёма (BRD §2).

docs/work-items/ORCH-098/10-tech-risks.md

@@ -0,0 +1,39 @@
+---
+work_item: ORCH-098
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-098 — машинный журнал уроков `lessons`
+
+Work Item: **ORCH-098** · Repo: **orchestrator** · Стадия: architecture
+
+> Информационный (гейтом не парсится). Риски реализации и их митигейшн.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | Врезка детектора в горячий путь конвейера (`stage_engine`/`merge_gate`/`launcher`) бросает исключение → регрессия пайплайна на self-hosting прод-инстансе (встанет конвейер всех проектов, в т.ч. enduro). | Низ. | Выс. | **NFR-1 never-raise**: `lessons.record` полностью self-contained `try/except → None`; каждая врезка дополнительно обёрнута защитным `try/except` (паттерн post-deploy-freeze, `stage_engine.py:~1993`), ловит даже ошибку импорта. **NFR-2 kill-switch** `ORCH_LESSONS_ENABLED=false` → no-op. Юнит-тест с замоканной падающей БД (AC-6). |
+| TR-2 | Неограниченный рост таблицы `lessons` (автозапись на каждом откате/HOLD/деградации) на впритык-хосте (диск 92%). | Сред. | Низ. | Лёгкие строки (короткий текст); **дедуп D4** (один indexed-SELECT в окне) + **`transient_retry` только на budget-exhaustion** гасят флуд в источнике. Ретенция/архивация — отдельная будущая задача (вне объёма v1); тренд наблюдаем через `snapshot()` в `GET /queue`. |
+| TR-3 | Недооформленная схема атрибуции → переделка схемы на живой общей прод-БД, когда появится ретроспировщик (E2). | Низ. | Сред. | **BR-2/NFR-6**: три нуллабельные колонки атрибуции (`attribution`/`target_repo`/`target_domain`) в схеме **сразу**; `update`/`POST /lessons/{id}` позволяет доклассифицировать `unknown` позже без миграции. Слаги без `enum`-констрейнта → новые значения не требуют DDL. |
+| TR-4 | Дубли автозаписи на ретраях/повторных откатах искажают будущий pattern-анализ. | Сред. | Низ. | **Дедуп D4** для `source="auto"`: indexed `SELECT` по `idx_lessons_wi_type` в окне `ORCH_LESSONS_DEDUP_WINDOW_S` перед `INSERT`. `manual` дедуп не проходит. Если в реальном прогоне дедуп окажется слишком строгим/слабым — окно конфигурируемо без передеплоя логики. |
+| TR-5 | Случайное касание инвариантов конвейера (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схемы существующих таблиц) при врезках. | Низ. | Выс. | Врезки — строго аддитивные одиночные вызовы; **AC-8** требует «диффом не затронуты». Reviewer проверяет дифф перечисленных артефактов. Журнал не участвует в решении гейта (FR-6). |
+| TR-6 | Эндпоинт `POST /lessons`/`/lessons/{id}` как непреднамеренный мутатор/вектор (запись в прод-БД без аутентификации). | Низ. | Сред. | Пишет **только** в аддитивную таблицу `lessons` (не трогает `tasks`/`jobs`/гейты); never-raise; `enabled:false` при выключенном флаге. Тот же уровень доступа, что у существующего `POST /coverage/baseline`. Дальнейшее ужесточение доступа — общая инфра-тема, вне объёма ORCH-098. |
+
+## Сводный вывод
+
+Доминирующий класс рисков — **изоляция наблюдателя от горячего пути конвейера на self-hosting
+прод-инстансе** (TR-1, TR-5): высокое влияние при низкой вероятности, полностью покрыто
+проверенной связкой *never-raise + kill-switch + чистая аддитивность*, идентичной уже работающим
+leaf'ам (`serial_gate`/`coverage_gate`/`metrics`/`bug_fast_track`). Вторичный класс — **рост/шум
+данных** (TR-2/TR-4): низкое влияние, смягчён лёгкими строками, дедупом и budget-exhaustion-записью;
+ретенция вынесена в будущее.
+
+**Эскалация не требуется.** Несмотря на формально «новый компонент + новая таблица», изменение
+следует устоявшемуся **additive-observer-leaf** шаблону, **не трогает машину стадий, гейты и схемы
+существующих таблиц**, полностью обратимо флагом → метка `arch:major-change` **не выставляется**,
+возврат в анализ (`back-to:analysis`) не нужен. Остаточный риск для прод-конвейера — **низкий**.

docs/work-items/ORCH-098/12-review.md

@@ -0,0 +1,71 @@
+---
+verdict: APPROVED
+work_item: ORCH-098
+stage: review
+author_agent: reviewer
+status: approved
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-098
+version: 1
+---
+
+# Review ORCH-098 — FND: машинный журнал уроков
+
+## Summary
+
+Реализация полностью соответствует ТЗ (`02-trz.md`), критериям приёмки (`03-acceptance-criteria.md`)
+и ADR-001/adr-0034. Введён чистый observer-leaf `src/lessons.py` (never-raise, единственный
+kill-switch `lessons_enabled`, без repo-скоупа — по решению D2), аддитивная идемпотентная таблица
+`lessons` с нуллабельными колонками атрибуции сразу (NFR-6, требование Славы 10.06), 4 типа
+автозаписи best-effort, дедуп для `auto`, три HTTP-эндпоинта + блок `lessons` в `GET /queue`.
+
+**Инварианты конвейера не тронуты (AC-8):** `src/stages.py` (`STAGE_TRANSITIONS`), `src/qg/checks.py`
+(`QG_CHECKS`/`check_*`), `src/merge_gate.py`, machine-verdict-ключи и схемы существующих таблиц —
+**диффом не затронуты** (подтверждено `git diff --name-only`). `tests/test_lessons.py` (TC-01…TC-12,
+13 тестов) — **зелёный** локально. Документация обновлена в том же PR.
+
+Все findings — P2/P3 (advisory), блокеров нет.
+
+## Findings
+
+### P0 — Blocker
+- Нет.
+
+### P1 — Must fix
+- Нет.
+
+### P2 — Should fix
+- [ ] **Кросс-задачный дедуп `transient_retry` теряет сигнал.** Врезка в
+  `launcher._finalize_transient` (`src/agents/launcher.py:~1024`) передаёт `task_id`, но **не**
+  `work_item_id` и **не** `stage` → ключ дедупа `db.lessons_recent_dup_exists` становится
+  `(work_item_id IS NULL, lesson_type='transient_retry', stage IS NULL)`. В окне
+  `lessons_dedup_window_s` (дефолт 1ч) **разные** задачи, исчерпавшие бюджет ретраев, схлопываются в
+  одну запись — теряется урок про вторую задачу. Поскольку `task_id` локально доступен, дедуп-ключ
+  стоило бы доопределять им при `work_item_id is None` (или включать `task_id` в ключ дедупа).
+  Это observer/best-effort (не влияет на конвейер, AC-3 формально выполнен — 4 типа автозаписи
+  работают), потому не блокер, но ослабляет ценность самого сигнала, ради которого фича вводится.
+  Ссылка: ADR-001 D4 («ключ `work_item_id+stage+lesson_type`»).
+
+### P3 — Nice to have
+- [ ] **Мелкая неточность ADR vs код.** `06-adr/ADR-001` (D3, таблица) и `adr-0034` указывают
+  choke-point `merge_hold` как `merge_gate._handle_merge_verify`, фактически `_handle_merge_verify`
+  живёт в `src/stage_engine.py` (туда и врезан `merge_hold`; `merge_gate.py` диффом не тронут).
+  Функционально корректно; рекомендуется поправить адрес в ADR для трассировки. Также
+  `transient_retry` в `merge_gate` (merge-retry exhausted) не реализован — но ADR формулирует это как
+  «**and/or** launcher», т.е. опционально; реализация через launcher достаточна.
+
+## Документация
+
+**Обновлена полностью в том же PR — ось «документация» PASS:**
+- `CLAUDE.md` — добавлен раздел «Машинный журнал уроков (ORCH-098)» (D1–D5, флаги, инвариант).
+- `docs/architecture/README.md` — компонент «Lessons journal», строка таблицы `lessons` в разделе
+  схемы БД, три новых эндпоинта в таблице API, обновлена строка `GET /queue` (`+ lessons (ORCH-098)`).
+- `docs/architecture/adr/adr-0034-lessons-journal.md` — сквозной ADR (новый).
+- `docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md` — локальный ADR (присутствует).
+- `CHANGELOG.md` — запись `[Unreleased]` с разбивкой D1–D5 + регресс.
+- `README.md` «Известные ограничения» — пунктов, закрываемых этой задачей, нет (ORCH-079 N/A).
+
+Изменение `src/` ⇒ требование «документация = golden source» выполнено; основание для
+`REQUEST_CHANGES` по оси документации отсутствует.

docs/work-items/ORCH-098/13-test-report.md

@@ -0,0 +1,86 @@
+---
+result: PASS   # PASS | FAIL — машинный вердикт, UPPERCASE
+work_item: ORCH-098
+stage: testing
+author_agent: tester
+status: pass
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: test-report
+work_item_id: ORCH-098
+---
+
+# Test Report — ORCH-098 — FND: машинный журнал уроков
+
+## Окружение
+- Python: 3.12.13
+- pytest: 8.3.3 (pytest-cov 5.0.0, anyio 4.13.0, asyncio 0.23.8)
+- Worktree: `/repos/_wt/orchestrator/feature_ORCH-098-fnd/` (ветка `feature/ORCH-098-fnd`)
+- Дата: 2026-06-10
+
+## Предусловия
+- Review-вердикт (`12-review.md`): **APPROVED** (блокеров нет, все findings P2/P3 advisory). ✅
+- Smoke API (read-only, prod 8500):
+  - `GET /health` → `{"status":"ok","service":"orchestrator"}` ✅
+  - `GET /status` → `200`, активные задачи отдаются (ORCH-098 в стадии `testing`). ✅
+  - `GET /queue` → `200`; присутствует блок **`serial_gate`** (ORCH-088) ✅ и **`auto_labels`**
+    (ORCH-089) ✅ в полезной нагрузке — смок-регресса нет.
+  - Примечание: прод-контейнер 8500 несёт ещё не задеплоенный код (без блока `lessons` в `/queue`) —
+    это ожидаемо (ORCH-098 не выкатан в прод), на смок-вердикт не влияет.
+
+## Результаты — покрытие тест-плана (`04-test-plan.yaml`)
+
+Прогон: `cd /repos/_wt/orchestrator/feature_ORCH-098-fnd && pytest tests/ -v --tb=short`.
+Все TC из тест-плана исполнены и сопоставлены с критериями приёмки (`03-acceptance-criteria.md`).
+
+| TC ID | Тип | Описание | AC | Тест (`tests/test_lessons.py`) | Результат |
+|-------|-----|----------|----|--------------------------------|-----------|
+| TC-01 | unit | `init_db()` создаёт `lessons` идемпотентно, все поля BR-1 | AC-1 | `test_tc01_table_idempotent_and_fields` | PASS |
+| TC-02 | unit | Нуллабельные колонки атрибуции `attribution/target_repo/target_domain`, update проставляет позже | AC-2 | `test_tc02_attribution_columns_nullable_and_settable` | PASS |
+| TC-03 | unit | `record()` вставляет строку (source auto/manual), возвращает id, `created_at` заполнен | AC-3/AC-5 | `test_tc03_record_inserts_and_returns_id` | PASS |
+| TC-04 | unit | never-raise при падающей БД: `record/get/update/snapshot` → `None/[]/{}` без исключения | AC-6 | `test_tc04_never_raise_on_db_error` | PASS |
+| TC-05 | unit | kill-switch `lessons_enabled=False` — инертность (no-op, без БД) | AC-7 | `test_tc05_kill_switch_inert` | PASS |
+| TC-06 | unit | `get_lessons` фильтрует type/status/repo/work_item, limit, `ORDER BY id DESC` | AC-4 | `test_tc06_filters_limit_order` | PASS |
+| TC-07 | unit | `update_lesson` меняет status/attribution/target_*/related_task + `updated_at`; неизв. id безопасен | AC-5 | `test_tc07_update_and_unknown_id` | PASS |
+| TC-07b | unit | (доп.) дедуп `source=auto` в окне; `source=manual` всегда проходит | AC-3/AC-5 | `test_tc07b_auto_dedup_and_manual_passthrough` | PASS |
+| TC-08 | integration | Автозапись gate-fail: откат в `_handle_qg_failure_rollbacks` → строка `gate_failure` с контекстом | AC-3 | `test_tc08_gate_failure_autorecord` | PASS |
+| TC-09 | integration | Автозапись transient/HOLD: транзиент-ветка пишет урок; сбой записи не ломает горячий путь | AC-3/AC-6 | `test_tc09_transient_autorecord_and_never_raise` | PASS |
+| TC-10 | integration | `GET /lessons` → 200 с фильтрами; `GET /queue` несёт блок `lessons`; чтение не мутирует | AC-4 | `test_tc10_get_endpoints` | PASS |
+| TC-11 | integration | `POST /lessons` (manual+атрибуция), `POST /lessons/{id}` обновляет; при выключенном флаге `{enabled:false}` | AC-5/AC-7 | `test_tc11_post_endpoints_and_killswitch` | PASS |
+| TC-12 | unit | Инварианты конвейера не тронуты: `STAGE_TRANSITIONS`/`QG_CHECKS`/machine-verdict неизменны | AC-8 | `test_tc12_pipeline_invariants_untouched` | PASS |
+
+**Итог покрытия:** 12/12 TC тест-плана исполнены и сопоставлены с AC-1…AC-9 → PASS.
+AC-9 (полный регресс зелёный + новый `test_lessons.py`) подтверждён прогоном ниже.
+
+## Вывод pytest
+
+Полный регресс (`tests/`):
+```
+================== 1630 passed, 1 warning in 71.78s (0:01:11) ==================
+```
+(единственный warning — PydanticDeprecatedSince20 в `src/config.py`, не связан с ORCH-098,
+предсуществующий.)
+
+Целевой модуль (`tests/test_lessons.py`):
+```
+collected 13 items
+tests/test_lessons.py::test_tc01_table_idempotent_and_fields PASSED      [  7%]
+tests/test_lessons.py::test_tc02_attribution_columns_nullable_and_settable PASSED [ 15%]
+tests/test_lessons.py::test_tc03_record_inserts_and_returns_id PASSED    [ 23%]
+tests/test_lessons.py::test_tc04_never_raise_on_db_error PASSED          [ 30%]
+tests/test_lessons.py::test_tc05_kill_switch_inert PASSED                [ 38%]
+tests/test_lessons.py::test_tc06_filters_limit_order PASSED              [ 46%]
+tests/test_lessons.py::test_tc07_update_and_unknown_id PASSED            [ 53%]
+tests/test_lessons.py::test_tc07b_auto_dedup_and_manual_passthrough PASSED [ 61%]
+tests/test_lessons.py::test_tc08_gate_failure_autorecord PASSED          [ 69%]
+tests/test_lessons.py::test_tc09_transient_autorecord_and_never_raise PASSED [ 76%]
+tests/test_lessons.py::test_tc10_get_endpoints PASSED                    [ 84%]
+tests/test_lessons.py::test_tc11_post_endpoints_and_killswitch PASSED    [ 92%]
+tests/test_lessons.py::test_tc12_pipeline_invariants_untouched PASSED    [100%]
+======================== 13 passed, 1 warning in 1.55s =========================
+```
+
+## Итог
+**PASS** — полный регресс зелёный (1630 passed), все 12 TC тест-плана исполнены и сопоставлены
+с критериями приёмки, smoke API read-only (`/health`/`/status`/`/queue`) в норме (блоки
+`serial_gate` и `auto_labels` присутствуют). Задача готова к переходу на `deploy-staging`.

docs/work-items/ORCH-098/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-098
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

docs/work-items/ORCH-098/15-staging-log.md

@@ -0,0 +1,30 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-098
+stage: deploy-staging
+author_agent: deployer
+status: success
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+timestamp: 2026-06-10T07:55:10Z
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log
+
+Staging test suite completed against the live staging stand (`orchestrator-staging`, port 8501),
+run canonically inside the container via `docker exec` (ORCH-048). **All REAL pipeline checks
+passed** → `staging_status: SUCCESS` (exit code 0).
+
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+
+## Results
+
+- **Block A (SMOKE)**: PASS — A1 `/health` 200 `status=ok`; A2 `/queue` 200 (counts/max_concurrency/resilience present); A3 `ORCH_STAGING=true`.
+- **Block B (ACCESS)**: PASS — B4 Plane sandbox project accessible (sandbox=YES); B5 Gitea `orchestrator-sandbox` accessible, push=true; B6 Registry isolated (sandbox=YES, prod-ET=NO, prod-ORCH=NO).
+- **Block C (E2E)**: C7 Create issue in Plane SANDBOX PASS; C8 Trigger pipeline via `/webhook/plane` PASS; C9a/C9b FAIL but **waived** (sandbox-infra: SANDBOX bot accounts not members of the sandbox Plane project — not a pipeline regression, ORCH-061).
+
+RESULT: 8/10 checks PASS. REAL failed: **none**. SANDBOX_INFRA failed (waived): C9a, C9b.
+
+Cleanup: test Plane issue deleted (HTTP 204); no branch created (nothing to delete).

docs/work-items/ORCH-100/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: FND/F1b: sidecar-watchdog — сбор хост/контейнеры/деп + алертинг (отдельный контейнер, репо орка)
+
+Work Item ID: ORCH-100
+
+## Description
+
+TBD

docs/work-items/ORCH-100/01-brd.md

@@ -0,0 +1,167 @@
+---
+work_item: ORCH-100
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD (бизнес-требования): ORCH-100 — FND/F1b: sidecar-watchdog (мозг мониторинга, отдельный контейнер)
+
+Work Item: **ORCH-100** · Repo: **orchestrator** · Стадия: analysis
+
+## 1. Бизнес-контекст и проблема
+
+Задача — фундаментный кирпич **F1b** домена 0 «Фундамент» эпика автономного саморазвития
+(`docs/epics/self-evolution.md`, §2, §«Архитектурные рамки наблюдаемости»). **F1a (ORCH-099)** уже
+реализовал лёгкий read-only `GET /metrics` в самом орке — он отдаёт **только сырьё** (стадии,
+очередь, agent-liveness, cost), без порогов/алертов/хранения. F1b — **вторая половина пары:** мозг
+мониторинга, который это сырьё читает, дополняет внешними сигналами (хост, контейнеры, внешние
+зависимости) и превращает в **алерты**.
+
+**Боль, которую закрывает F1b.** Сегодня платформа слепа к собственному здоровью в реальном
+времени. Инциденты 06–09.06 (диск хоста молча дорос до 100% и встал весь конвейер — ORCH-063;
+фантом-merge, deploy-петли, флапп-статусы, зомби-jobs) обнаруживались **постфактум, человеком**.
+Частичные стражи существуют, но они **живут ВНУТРИ процесса орка** (`disk_watchdog` ORCH-063,
+`reaper` ORCH-065, `reconciler` ORCH-053): если орк завис/съел память/упал — стражи лягут **вместе
+с ним**, и платформа слепа именно в критический момент.
+
+**Архитектурная рамка — установленный факт заказчика (Слава, 09.06), не предмет переизобретения:**
+- **C-1 / C-1б:** наблюдатель ОТДЕЛЁН от наблюдаемого. Sidecar-контейнер на том же хосте; КОД
+  sidecar — в репо орка (папка `watchdog/`), но рантайм — **ОТДЕЛЬНЫЙ контейнер** (свой Dockerfile +
+  сервис `orchestrator-watchdog` в `docker-compose.yml`). Изоляция — на уровне контейнера, не репо.
+- **C-2:** без внешнего плеча (одна площадка; принятый риск — падёт весь хост → молчит и наблюдатель).
+- **C-3:** тонкий стек — **НЕ Grafana/Prometheus**. Хост впритык: RAM 171Mi free / 7.7Gi, диск 92%.
+- **Разделение ответственности:** орк отдаёт сырьё (`/metrics`), sidecar — мозг (пороги/алерты/свой
+  Telegram-канал, независимый от кода орка). Орк лёг → `/metrics` недоступен = **сам сигнал тревоги**.
+
+**Критический инвариант наблюдаемости:** падение/зависание орка должно делать sidecar **громче**, а
+не тише. Если орк не отвечает на `/metrics` — sidecar жив и обязан зарепортить это как тревогу
+«орк не отвечает».
+
+## 2. Объём (scope)
+
+### В объёме
+- Новая папка `watchdog/` в репо орка: тонкий код sidecar + собственный `Dockerfile`.
+- Сервис `orchestrator-watchdog` в `docker-compose.yml` (отдельный контейнер, свой рестарт/память).
+- **Сбор сигналов** (периодический тик): (a) `GET /metrics` орка по HTTP; (b) хост — диск %/inode,
+  память, CPU; (c) контейнеры — через `docker.sock` **read-only** (статусы Up/healthy/restarting/
+  exited/unhealthy); (d) пинг внешних зависимостей — Plane / Gitea / Anthropic.
+- **Алертинг по порогам:** диск≥порог, память, agent-завис >N мин, job-failed, застрявшая стадия,
+  контейнер-down/unhealthy, внешняя зависимость недоступна, **орк-down (`/metrics` не отвечает)**.
+- **Доставка:** Telegram через **СОБСТВЕННЫЙ канал sidecar** (свой токен/chat в `.env`), НЕ через
+  код/Telegram-функции орка.
+- **Гигиена алертов:** дедупликация + throttle (один алерт на пересечение порога, не флапп) +
+  recovery-сообщение при возврате метрики в норму.
+- **Управляемость:** kill-switch, конфигурируемые пороги, конфигурируемые интервалы.
+- `.env.example`: токен/chat watchdog + пороги/интервалы (канон, без секретов).
+- Документация (`07-infra-requirements.md` — разовое инфра-действие) + `CHANGELOG.md`; pytest зелёный.
+
+### Вне объёма
+- **Любая авто-ремедиация** (рестарт контейнеров, очистка диска, requeue jobs). F1b — **только
+  наблюдение + алерт** (L0 reactive, эпик §9). Авто-фиксы — домен D1 (отдельные задачи).
+- **Grafana / Prometheus / TSDB / дашборд-UI / исторические графики** (C-3 — тонкий стек).
+- **Изменение `/metrics` орка** (контракт F1a/ORCH-099 — данность; sidecar — потребитель). Если
+  обнаружится нехватка поля — это отдельная задача-расширение F1a, не часть F1b.
+- **Изменение `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / схемы БД орка** — sidecar их не
+  касается (он вне процесса орка).
+- **Журнал уроков (F2)** — отдельная задача; F1b не пишет в БД орка.
+- **Второе внешнее плечо мониторинга (L2)** — сознательно отложено (C-2).
+
+## 3. Заинтересованные стороны
+- **Заказчик / приёмка:** Слава (зафиксировал архитектурные рамки 09.06).
+- **Постановщик / ведение:** Стрим.
+- **Затрагивает:** операторов платформы (получатели алертов), все проекты в общем прод-инстансе
+  (enduro-trails и пр.) — sidecar повышает наблюдаемость их общей инфраструктуры, **не вмешиваясь**.
+- **Исполнители конвейера:** architect (стек, формат хранения порогов, владелец диск-алерта),
+  developer, reviewer, tester, deployer.
+
+## 4. Бизнес-требования (BR)
+
+- **BR-1 (отдельный контейнер).** Sidecar собирается в отдельный образ (`watchdog/Dockerfile`) и
+  работает как сервис `orchestrator-watchdog` в `docker-compose.yml` — отдельный процесс/память/
+  рестарт, **НЕ внутри процесса орка**.
+- **BR-2 (сбор сырья орка).** На каждом тике sidecar делает `GET /metrics` орка по HTTP и
+  разбирает версионированный конверт (`schema_version`/`stages`/`queue`/`agents`/`cost`), **толерантно
+  к неизвестным/отсутствующим полям** (контракт F1a — additive, версия не растёт на добавление поля).
+- **BR-3 (сбор хоста).** Sidecar измеряет хост: заполнение диска (% и, где доступно, inode), память,
+  CPU — по смонтированным хост-путям/интерфейсам, доступным контейнеру.
+- **BR-4 (сбор контейнеров).** Sidecar читает состояние контейнеров через `docker.sock`
+  (**read-only mount**): различает Up / healthy / restarting / exited / unhealthy. Минимум — статус
+  ключевых контейнеров платформы (включая сам `orchestrator`).
+- **BR-5 (пинг зависимостей).** Sidecar периодически проверяет доступность внешних зависимостей —
+  Plane, Gitea, Anthropic (лёгкий health/ping, короткий таймаут) — и алертит при недоступности.
+- **BR-6 (пороговый алертинг).** При **пересечении порога** сигналом (диск≥порог, память,
+  agent-завис >N мин, job-failed, застрявшая стадия, контейнер-down/unhealthy, зависимость
+  недоступна) sidecar шлёт **ровно один** Telegram-алерт.
+- **BR-7 (орк-down = тревога).** Если `GET /metrics` орка **не отвечает** (таймаут/connection
+  refused/5xx) — sidecar шлёт алерт «орк не отвечает». Это **главный** сценарий ценности:
+  наблюдатель жив, наблюдаемый лёг.
+- **BR-8 (свой Telegram-канал).** Алерты идут через **независимый** транспорт sidecar — собственные
+  bot-токен и chat-id из `.env`, БЕЗ обращения к коду/функциям/токену орка (иначе падение орка
+  утянуло бы и алерт-канал — нарушение C-1).
+- **BR-9 (дедуп / throttle / recovery).** Повторное нахождение метрики за порогом не флаппит: один
+  алерт на пересечение + анти-спам cooldown между повторами + **recovery-сообщение** при возврате
+  метрики в норму. Поведение — по образцу `disk_watchdog` (ORCH-063): чистая решающая функция
+  `(value, threshold, prev_state, now, cooldown) → alert | realert | recovery | none`.
+- **BR-10 (нет дубля диск-алерта).** Диск уже алертит `disk_watchdog` ORCH-063 (порог 85%, через
+  Telegram орка). F1b **НЕ должен** порождать второй диск-алерт на то же событие. **Владельца
+  диск-алерта (sidecar vs внутренний `disk_watchdog`) выбирает архитектор** — BRD лишь фиксирует
+  требование «один диск-алерт на событие, без дублирования».
+
+## 5. Нефункциональные требования (NFR)
+
+- **NFR-1 (изоляция / резилентность).** Падение/зависание/рестарт орка **НЕ роняет** sidecar
+  (доказывается: орк down → sidecar продолжает тикать и шлёт алерт). Обратное тоже: sidecar — чисто
+  наблюдатель, его падение не влияет на конвейер.
+- **NFR-2 (тонкость).** Контейнер лёгкий: предсказуемо малое потребление памяти (хост впритык —
+  171Mi free). Конкретный бюджет памяти и `mem_limit` — решение архитектора; BRD требует «в разумных
+  пределах, измеримо». **НЕ Grafana/Prometheus.**
+- **NFR-3 (never-raise).** Любая ошибка сбора/парсинга/сети/отправки — best-effort: один битый
+  источник деградирует один сигнал, не роняет тик; ошибка тика не роняет демон. По образцу
+  `disk_watchdog` / `metrics` (три уровня never-raise: per-source, per-tick, per-send).
+- **NFR-4 (безопасность self-hosting).** Sidecar **только читает и шлёт Telegram** — НИКОГДА не
+  трогает диск/контейнеры/прод, не рестартит, не пишет в `docker.sock` (mount **read-only**), не
+  пишет в БД орка, не пушит в `main`. Безопасен для общего инстанса (enduro-trails не затронут).
+- **NFR-5 (управляемость / обратимость).** Kill-switch (выключить → sidecar инертен/не стартует,
+  нулевой эффект на орк). Пороги и интервалы конфигурируемы через `.env` (не хардкод).
+- **NFR-6 (изоляция контракта).** Sidecar толерантен к версии `/metrics`: неизвестное поле
+  игнорируется, отсутствие опционального — не падение; рост `schema_version` логируется (предупреждение),
+  не крэшит.
+- **NFR-7 (наблюдаемость самого sidecar).** Стартап/тик/решения логируются достаточно, чтобы по логам
+  контейнера понять, что sidecar жив и почему (не)сработал алерт.
+
+## 6. Допущения и ограничения
+
+- **Зависимость:** F1b **зависит от F1a (ORCH-099)** — читает `GET /metrics`. Контракт `/metrics`
+  (envelope `schema_version`/`generated_at`/`clk_tck`/`stages`/`queue`/`agents`/`cost`/`enabled`) —
+  установленный факт, sidecar его потребитель.
+- **Сеть:** орк работает `network_mode: host` (порт 8500) → из host-network sidecar `/metrics`
+  достижим как `http://127.0.0.1:8500/metrics`. Точный сетевой режим sidecar — решение архитектора.
+- **`docker.sock`** доступен на хосте `/var/run/docker.sock`; монтируется в sidecar **read-only**.
+- **Разовое инфра-действие** (добавить сервис в compose + первый запуск + создать bot/chat watchdog)
+  выполняется человеком (Слава/Стрим) на хосте — фиксируется в `07-infra-requirements.md`. Дальше код
+  watchdog катится через конвейер (self-hosting).
+- **Стек (Python/Go), формат хранения порогов, владелец диск-алерта** — **зона архитектора** в рамках
+  C-1…C-3; BRD их не предрешает.
+- **Известный принятый риск (C-2):** падёт весь хост/Docker → молчит и sidecar (нет внешнего плеча).
+- **Telegram 48ч** и прочие лимиты транспорта — как у орка (best-effort доставка).
+
+## 7. Критерии успеха
+
+Sidecar стартует отдельным контейнером, на каждом тике собирает сырьё орка + хост + контейнеры +
+зависимости, при пересечении порога шлёт ровно один Telegram-алерт со своего канала (throttle +
+recovery), при недоступности орка шлёт «орк не отвечает», и переживает падение орка не падая сам.
+Тонкий, с kill-switch и конфигурируемыми порогами. Разовое инфра-действие задокументировано, pytest
+зелёный, доки + CHANGELOG обновлены. Детальные PASS/FAIL — `03-acceptance-criteria.md`.
+
+## 8. Риски
+
+- **Дубль диск-алерта** с `disk_watchdog` ORCH-063 (BR-10) — нужно явное решение владельца (архитектор).
+- **Шум алертов** (флапп на границе порога) при недостаточном throttle/recovery — закрывается BR-9.
+- **Зависимость от `/metrics`:** ложный «орк-down» при сетевой икоте — нужен разумный таймаут/ретрай в
+  пороге, чтобы единичный transient не флаппил (детали — архитектор/developer).
+- **Ресурсы хоста впритык** — sidecar обязан быть лёгким (NFR-2), иначе сам станет частью проблемы.
+- **`docker.sock` доступ** — строго read-only; риск привилегий минимизируется mount-режимом (NFR-4).
+- Детальный реестр и митигации — `10-tech-risks.md` (заполняет архитектор).

docs/work-items/ORCH-100/02-trz.md

@@ -0,0 +1,155 @@
+---
+work_item: ORCH-100
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-100 — FND/F1b: sidecar-watchdog (мозг мониторинга, отдельный контейнер)
+
+Work Item: **ORCH-100** · Repo: **orchestrator** · Стадия: analysis
+
+> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD (`01-brd.md`) и фактического
+> кода. Архитектурное обоснование/решения (выбор стека Python/Go, формат хранения порогов, владелец
+> диск-алерта, точная топология сети sidecar, бюджет памяти/`mem_limit`) — **зона архитектора**
+> (`06-adr/`). ТЗ фиксирует ТРЕБОВАНИЯ и ограничения, не способ реализации.
+
+## 1. Сводка изменения
+
+Добавить **отдельный sidecar-контейнер** `orchestrator-watchdog`, код которого лежит в новой папке
+`watchdog/` репозитория орка, а рантайм — изолированный контейнер (свой `watchdog/Dockerfile` + сервис
+в `docker-compose.yml`). Sidecar периодически (тик): (1) тянет `GET /metrics` орка; (2) меряет хост
+(диск/inode/память/CPU); (3) читает статусы контейнеров через read-only `docker.sock`; (4) пингует
+Plane/Gitea/Anthropic. По набору **конфигурируемых порогов** через **чистую решающую функцию**
+(образец `disk_watchdog.decide`) принимает решение `alert | realert | recovery | none` с дедупом/
+throttle, и шлёт алерт в **собственный** Telegram-канал (свой токен/chat, независимо от кода орка).
+Особый сигнал: `/metrics` не отвечает → алерт «орк не отвечает». Всё — never-raise, под kill-switch,
+строго read-only к наблюдаемому (self-hosting-безопасно).
+
+**Орк-сторона (`src/**`) не меняется**: F1b — потребитель уже существующего `GET /metrics` (F1a,
+ORCH-099). `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / схема БД орка — **не тронуты**.
+
+## 2. Задействованные модули / пути
+
+| Путь | Действие |
+|------|----------|
+| `watchdog/` | **создать** — корень кода sidecar (новая папка в репо орка) |
+| `watchdog/Dockerfile` | **создать** — отдельный тонкий образ sidecar (стек — выбор архитектора) |
+| `watchdog/<entrypoint>` | **создать** — демон/цикл сбора+решения+отправки (имя/структура — архитектор) |
+| `watchdog/<collectors>` | **создать** — сбор: `/metrics` орка (HTTP), хост (диск/inode/память/CPU), контейнеры (`docker.sock` ro), пинг Plane/Gitea/Anthropic |
+| `watchdog/<decision>` | **создать** — **чистая** решающая функция порога `(value, threshold, prev_state, now, cooldown) → alert\|realert\|recovery\|none` (образец `src/disk_watchdog.py::decide`) |
+| `watchdog/<notify>` | **создать** — независимый Telegram-транспорт sidecar (свой токен/chat; НЕ импорт `src/notifications.py`) |
+| `watchdog/<config>` | **создать** — чтение порогов/интервалов/токенов/kill-switch из env |
+| `watchdog/tests/` (или `tests/watchdog/`) | **создать** — pytest на чистые функции (решение/парсинг/детект орк-down); размещение — архитектор |
+| `docker-compose.yml` | **изменить** — добавить сервис `orchestrator-watchdog` (build `watchdog/`, restart-policy, read-only `docker.sock`, `mem_limit`, env, kill-switch) |
+| `.env.example` | **изменить** — канон: токен/chat watchdog + пороги + интервалы + kill-switch (без секретов) |
+| `CHANGELOG.md` | **изменить** — запись о F1b |
+| `docs/work-items/ORCH-100/07-infra-requirements.md` | **создать (architect)** — разовое инфра-действие: добавить сервис в compose, создать bot/chat watchdog, первый запуск на хосте |
+
+> **`src/**` НЕ редактируется.** Если в ходе разработки выяснится нехватка поля в `/metrics` — это
+> отдельная задача-расширение F1a (ORCH-099), а не правка в рамках F1b (см. BRD §«Вне объёма»).
+
+## 3. Функциональные требования
+
+### FR-1 — Отдельный контейнер sidecar (BR-1, NFR-1)
+Sidecar собирается из `watchdog/Dockerfile` в отдельный образ и поднимается сервисом
+`orchestrator-watchdog` в `docker-compose.yml`: отдельный процесс/память/рестарт-политика, **НЕ**
+внутри процесса орка. `restart: unless-stopped` (или эквивалент) — sidecar самовосстанавливается.
+
+### FR-2 — Сбор сырья орка (BR-2, NFR-6)
+На каждом тике `GET <orch-metrics-url>` (дефолт-достижимость `http://127.0.0.1:8500/metrics` при
+host-network; URL конфигурируем). Тело — версионированный конверт F1a:
+`{schema_version, generated_at, clk_tck, stages[], queue, agents[], cost, enabled}`. Парсинг
+**толерантен**: неизвестные поля игнорируются, отсутствие опционального — не ошибка, рост
+`schema_version` логируется (warning), не крэшит. Из конверта извлекаются сигналы для порогов:
+agent-liveness (cpu_ticks/runtime → «завис»), застрявшая стадия, job-failed, длина очереди.
+
+### FR-3 — Детект «орк не отвечает» (BR-7) — главный сигнал
+Если `GET /metrics` завершается таймаутом / connection refused / 5xx / нечитаемым телом — это
+**отдельный сигнал тревоги** `orchestrator_down`. Проходит через ту же машину порога/дедупа/recovery
+(BR-9): один алерт «орк не отвечает», recovery при восстановлении. Единичный transient не должен
+немедленно флаппить — порог/таймаут/ретрай подбираются так, чтобы алерт был осмысленным (детали —
+архитектор/developer; требование: «не флаппить на одиночной сетевой икоте»).
+
+### FR-4 — Сбор хоста (BR-3)
+Измерять заполнение диска (% и, где доступно, inode), память, CPU по доступным контейнеру
+хост-путям/интерфейсам (стдлиб-средствами выбранного стека; **без** тяжёлых агентов). Пути/пороги —
+конфигурируемы. **Диск:** см. FR-9 (анти-дубль с ORCH-063).
+
+### FR-5 — Сбор контейнеров (BR-4, NFR-4)
+Через `docker.sock`, смонтированный **read-only**, читать состояния контейнеров платформы:
+различать Up / healthy / restarting / exited / unhealthy. Минимум — статус `orchestrator` (и других
+ключевых сервисов). **Только чтение** Docker API (list/inspect) — никаких start/stop/restart/exec.
+
+### FR-6 — Пинг внешних зависимостей (BR-5)
+Периодически проверять доступность Plane / Gitea / Anthropic лёгким запросом (health/ping, короткий
+таймаут, never-raise). Недоступность → сигнал для порога. Эндпоинты/таймауты — конфигурируемы.
+
+### FR-7 — Пороговый алертинг (BR-6, BR-9)
+Каждый сигнал проходит через **чистую решающую функцию** (образец `disk_watchdog.decide`):
+вход `(value/state, threshold, prev_state, now, cooldown)`, выход `alert | realert | recovery | none`.
+Семантика:
+- не-alerting & за порогом → **ALERT** (один на пересечение);
+- alerting & за порогом & cooldown истёк → **REALERT**;
+- alerting & за порогом & в cooldown → **NONE** (анти-спам);
+- alerting & вернулось в норму → **RECOVERY**;
+- не-alerting & в норме → **NONE**.
+Состояние порога (alerting/last_alert_at) — per-signal, in-memory (best-effort; рестарт sidecar
+сбрасывает → корректно повторно алертит ещё стоящую проблему, как `disk_watchdog`). Хранилище
+состояния/порогов (in-memory vs файл/иное) — **решение архитектора**.
+
+### FR-8 — Независимый Telegram-транспорт (BR-8, NFR-4)
+Отправка через собственный код sidecar (свой `<notify>`), читающий **свои** `bot_token`/`chat_id`
+из env. **Запрещено** импортировать/вызывать `src/notifications.py` или использовать токен/функции
+орка (иначе падение орка утянет алерт-канал). `disable_web_page_preview`/`parse_mode` — по
+усмотрению; сообщение содержит суть алерта (сигнал, значение, порог, хост/контейнер).
+
+### FR-9 — Анти-дубль диск-алерта (BR-10)
+Диск уже алертит `disk_watchdog` (ORCH-063, порог 85%, Telegram орка). F1b **не должен** слать
+второй диск-алерт на то же событие. **Владельца диск-алерта выбирает архитектор** (варианты:
+sidecar становится единственным владельцем и внутренний `disk_watchdog` остаётся как fallback на
+случай down-канала орка; ИЛИ sidecar не дублирует диск, оставляя его за ORCH-063). ТЗ фиксирует
+инвариант: **на одно событие переполнения диска — не более одного алерта**, решение и его обоснование —
+в `06-adr/`.
+
+### FR-10 — Управляемость (NFR-5)
+Kill-switch (env): выключен → sidecar не стартует / инертен, нулевой эффект на орк и конвейер.
+Пороги (диск, память, agent-завис N мин, длина очереди, и т.п.), интервал тика, таймауты, cooldown —
+из env (`.env.example` — канон).
+
+### FR-11 — never-raise (NFR-3)
+Три уровня: per-source (битый источник деградирует один сигнал, прочие собираются), per-tick (внешний
+try/except цикла), per-send (обёрнутая отправка). Демон не падает от ошибки сбора/сети/парсинга.
+
+## 4. Изменения API
+
+**Нет** изменений API орка. Sidecar — **клиент** существующего `GET /metrics` (F1a, ORCH-099). Орк
+новых эндпоинтов не получает. Sidecar собственного входящего HTTP-API не обязан иметь (опциональный
+liveness-эндпоинт самого sidecar — на усмотрение архитектора, вне обязательного объёма).
+
+## 5. Изменения схемы БД
+
+**Нет.** Sidecar **не пишет** в БД орка (NFR-4) и не имеет своей БД (тонкий стек, C-3). Состояние
+порогов — in-memory best-effort (FR-7). Журнал уроков (F2, БД орка) — отдельная задача, не F1b.
+
+## 6. Требования к новым/изменённым QG checks
+
+**Нет.** F1b живёт **вне** процесса орка и **вне** конвейера Quality Gate. `QG_CHECKS` / `check_*` /
+`STAGE_TRANSITIONS` — **не тронуты** (по образцу operational-демонов `disk_watchdog`/`reaper`/
+`reconciler`, которые тоже не являются Quality Gate). Sidecar — операционный наблюдатель, не гейт.
+
+## 7. Совместимость / регресс
+
+- **Обратная совместимость:** изменения **аддитивны** — новая папка `watchdog/`, новый сервис в
+  compose, новые ключи в `.env.example`. Существующий орк-контейнер и его поведение — без изменений.
+- **Kill-switch:** выключенный sidecar = нулевой эффект (не стартует), полная обратимость (NFR-5).
+- **Область раската:** только инфраструктура наблюдения; конвейер всех проектов не затронут
+  (self-hosting-безопасно, NFR-4).
+- **Регресс:** существующий `pytest tests/` остаётся зелёным; новые тесты sidecar добавляются
+  изолированно (FR — чистые функции тестируемы без контейнера/таймера, образец
+  `tests/` для `disk_watchdog.decide`).
+- **Разовое инфра-предусловие** (не код): добавить сервис в compose + создать bot/chat watchdog +
+  первый запуск на хосте (Слава/Стрим). Зафиксировать в `07-infra-requirements.md`. Отсутствие
+  bot/chat watchdog = sidecar не шлёт (fail-safe, логирует), но не падает.

docs/work-items/ORCH-100/03-acceptance-criteria.md

@@ -0,0 +1,114 @@
+---
+work_item: ORCH-100
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки (Acceptance Criteria): ORCH-100 — FND/F1b: sidecar-watchdog
+
+Work Item: **ORCH-100** · Repo: **orchestrator** · Стадия: analysis
+
+Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
+считается провалом). Reviewer/tester проверяет их буквально по файлам репозитория и поведению.
+
+---
+
+## AC-1 — Sidecar стартует отдельным контейнером и собирает все источники
+
+**Условие:** есть папка `watchdog/` с кодом + `watchdog/Dockerfile`; в `docker-compose.yml` есть
+сервис `orchestrator-watchdog`, собираемый из `watchdog/`; запущенный sidecar на тике собирает
+сырьё орка (`GET /metrics`) + хост (диск/память/CPU) + контейнеры (`docker.sock`) + пинг зависимостей.
+- **PASS:** `watchdog/Dockerfile` существует; сервис `orchestrator-watchdog` объявлен отдельным
+  сервисом в `docker-compose.yml` (свой build/restart/`mem_limit`, read-only `docker.sock`); код
+  sidecar реализует все 4 коллектора (метрики орка, хост, контейнеры, зависимости); тик опрашивает
+  все 4 (подтверждается тестами/логами).
+- **FAIL:** мониторинг встроен в процесс орка (`src/**`) / нет отдельного сервиса в compose / отсутствует
+  любой из 4 коллекторов / `docker.sock` смонтирован НЕ read-only.
+
+---
+
+## AC-2 — Пороговый алерт: один на пересечение + throttle + recovery + орк-down
+
+**Условие:** при пересечении порога — ровно один Telegram-алерт со **своего** канала sidecar; повтор
+в cooldown молчит; возврат в норму шлёт recovery; недоступность `/metrics` орка → алерт «орк не
+отвечает».
+- **PASS:** чистая решающая функция возвращает `alert | realert | recovery | none` по семантике FR-7
+  (тесты TC-01…TC-04 зелёные); алерт идёт через независимый транспорт sidecar (свой токен/chat, БЕЗ
+  импорта `src/notifications.py`); сценарий `orchestrator_down` (таймаут/refused/5xx) даёт алерт
+  «орк не отвечает» (TC-05) и recovery при восстановлении.
+- **FAIL:** флапп (>1 алерта на одно пересечение без cooldown) / нет recovery / алерт шлётся через
+  код/токен орка / `orchestrator_down` не детектируется или не алертит.
+
+---
+
+## AC-3 — Изоляция: падение орка не роняет sidecar
+
+**Условие:** орк недоступен/упал → sidecar продолжает работать и репортит проблему.
+- **PASS:** при недоступном `/metrics` (мок таймаута/refused) тик sidecar не падает, проходит до конца,
+  формирует алерт `orchestrator_down` (TC-05, TC-08); демон never-raise на трёх уровнях (per-source/
+  per-tick/per-send) — ошибка одного источника не валит тик, ошибка тика не валит демон (TC-06).
+- **FAIL:** исключение в коллекторе/отправке роняет тик или демон / недоступность орка приводит к
+  падению/остановке sidecar.
+
+---
+
+## AC-4 — Тонкость, kill-switch, конфигурируемые пороги
+
+**Условие:** контейнер лёгкий; есть kill-switch; пороги/интервалы конфигурируемы через env.
+- **PASS:** `docker-compose.yml` задаёт ограничение памяти sidecar (`mem_limit`/эквивалент) в разумных
+  пределах (НЕ Grafana/Prometheus-стек); kill-switch (env) при выключении → sidecar не стартует/инертен,
+  нулевой эффект на орк (TC-07); пороги (диск/память/agent-завис N мин/очередь и т.п.), интервал,
+  таймауты, cooldown читаются из env; `.env.example` содержит токен/chat watchdog + все пороги/интервалы
+  (канон, без реальных секретов).
+- **FAIL:** нет `mem_limit` / тянется Grafana/Prometheus / нет kill-switch или он не отключает sidecar /
+  пороги захардкожены / `.env.example` не обновлён или содержит реальный секрет.
+
+---
+
+## AC-5 — Анти-дубль диск-алерта (согласовано с ORCH-063)
+
+**Условие:** на одно событие переполнения диска — не более одного алерта; владелец зафиксирован в ADR.
+- **PASS:** в `06-adr/` зафиксировано решение о владельце диск-алерта (sidecar vs внутренний
+  `disk_watchdog` ORCH-063); реализация не порождает два алерта на то же событие переполнения; выбор
+  обоснован.
+- **FAIL:** диск алертится дважды (и sidecar, и `disk_watchdog`) на одно событие / решение о владельце
+  не задокументировано.
+
+---
+
+## AC-6 — Безопасность self-hosting (только чтение/алерт)
+
+**Условие:** sidecar ничего не мутирует в наблюдаемой системе.
+- **PASS:** код sidecar не содержит вызовов записи/управления — нет start/stop/restart/exec контейнеров,
+  нет записи в `docker.sock` (mount read-only), нет записи в БД орка, нет операций с диском хоста
+  (кроме чтения заполнения), нет push в `main`. Подтверждается ревью кода + статической проверкой
+  (TC-09: docker-клиент используется только для list/inspect).
+- **FAIL:** sidecar выполняет любое мутирующее действие над контейнерами/диском/БД/прод-инстансом.
+
+---
+
+## AC-7 — Разовое инфра-действие задокументировано; pytest зелёный; доки+CHANGELOG
+
+**Условие:** инфра-предусловие описано; тесты проходят; документация обновлена.
+- **PASS:** `07-infra-requirements.md` описывает разовое действие (добавить сервис в compose, создать
+  bot/chat watchdog, первый запуск на хосте); `pytest` (полный `tests/` + тесты sidecar) зелёный;
+  `CHANGELOG.md` содержит запись F1b; релевантные доки (CLAUDE.md/README при необходимости) обновлены.
+- **FAIL:** нет `07-infra-requirements.md` / падают тесты / нет записи в CHANGELOG / функционал добавлен
+  без обновления документации.
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+
+| AC | Покрывает |
+|----|-----------|
+| AC-1 | BR-1/2/3/4/5 · FR-1/2/4/5/6 · NFR-4 |
+| AC-2 | BR-6/7/8/9 · FR-3/7/8 |
+| AC-3 | NFR-1/3 · FR-3/11 |
+| AC-4 | NFR-2/5 · FR-10 |
+| AC-5 | BR-10 · FR-9 |
+| AC-6 | NFR-4 · FR-5/8 |
+| AC-7 | BR (доки) · NFR-7 · процессные правила агентов |

docs/work-items/ORCH-100/04-test-plan.yaml

@@ -0,0 +1,108 @@
+work_item: ORCH-100
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+title: "FND/F1b sidecar-watchdog — пороговый алертинг, орк-down, изоляция, self-hosting safety"
+framework: pytest
+scope: >
+  Покрывает чистую логику sidecar (решающая функция порога, парсинг конверта /metrics,
+  детект orchestrator-down, never-raise) и структурно-инфраструктурные инварианты (отдельный
+  сервис в compose, read-only docker.sock, независимый Telegram-транспорт, kill-switch,
+  анти-дубль диск-алерта). ВНЕ покрытия: реальный Telegram-API, живой docker.sock, живой
+  хост-хост-стек (мокаются); сетевые коллекторы тестируются на моках, не на боевых Plane/Gitea/
+  Anthropic. Стек sidecar (Python/Go) и точное размещение тестов выбирает архитектор — при Python
+  тесты идут в общий pytest; если архитектор выберет Go, набор тест-кейсов переносится на go test
+  1:1 по смыслу (решение/парсинг/детект/never-raise остаются обязательными).
+notes: >
+  Образец чистой решающей функции и её тестов — src/disk_watchdog.py::decide и его тесты в tests/.
+  Все коллекторы/транспорт мокаются (никаких боевых сетевых/docker-вызовов в CI). Полный регресс
+  tests/ орка должен оставаться зелёным (src/** не меняется). Тесты sidecar изолированы и не требуют
+  поднятого контейнера/таймера. Пути модулей watchdog/* — ориентировочные; финальные имена задаёт
+  архитектор/developer, id и смысл тест-кейсов сохраняются.
+
+tests:
+  - id: TC-01
+    type: unit
+    description: "Решающая функция: not-alerting & value>=threshold -> ALERT (один на пересечение порога)"
+    module: watchdog/tests/test_decision.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "Решающая функция: alerting & still>=threshold & cooldown НЕ истёк -> NONE (анти-спам throttle)"
+    module: watchdog/tests/test_decision.py
+    expected: PASS
+
+  - id: TC-03
+    type: unit
+    description: "Решающая функция: alerting & still>=threshold & cooldown истёк -> REALERT (повторный алерт)"
+    module: watchdog/tests/test_decision.py
+    expected: PASS
+
+  - id: TC-04
+    type: unit
+    description: "Решающая функция: alerting & value вернулось ниже порога -> RECOVERY (recovery-сообщение)"
+    module: watchdog/tests/test_decision.py
+    expected: PASS
+
+  - id: TC-05
+    type: unit
+    description: "Детект orchestrator-down: /metrics таймаут/connection-refused/5xx -> сигнал orchestrator_down -> ALERT «орк не отвечает»"
+    module: watchdog/tests/test_orch_down.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "never-raise: исключение в одном коллекторе (хост/контейнеры/деп) деградирует один сигнал, тик доходит до конца и собирает остальные"
+    module: watchdog/tests/test_never_raise.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "Kill-switch: при выключенном флаге sidecar инертен/не стартует тик; пороги/интервалы/таймауты читаются из env (не хардкод)"
+    module: watchdog/tests/test_config_killswitch.py
+    expected: PASS
+
+  - id: TC-08
+    type: integration
+    description: "Полный тик при недоступном орке (мок /metrics down): тик не падает, собирает хост/контейнеры/деп, формирует ровно один алерт orchestrator_down, recovery при восстановлении"
+    module: watchdog/tests/test_tick_orch_down_integration.py
+    expected: PASS
+
+  - id: TC-09
+    type: unit
+    description: "Self-hosting safety: docker-клиент используется только для чтения (list/inspect); нет вызовов start/stop/restart/exec/записи (статическая/мок-проверка)"
+    module: watchdog/tests/test_docker_readonly.py
+    expected: PASS
+
+  - id: TC-10
+    type: unit
+    description: "Независимый транспорт: алерт-отправка использует СВОИ токен/chat sidecar из env и НЕ импортирует src/notifications.py / код орка"
+    module: watchdog/tests/test_notify_isolation.py
+    expected: PASS
+
+  - id: TC-11
+    type: unit
+    description: "Толерантность к контракту /metrics: неизвестное поле игнорируется, отсутствие опционального не падает, рост schema_version логируется (warning) без крэша"
+    module: watchdog/tests/test_metrics_parse.py
+    expected: PASS
+
+  - id: TC-12
+    type: integration
+    description: "Compose-инвариант: orchestrator-watchdog объявлен отдельным сервисом (свой build watchdog/, restart, mem_limit) с docker.sock в режиме :ro"
+    module: watchdog/tests/test_compose_service.py
+    expected: PASS
+
+  - id: TC-13
+    type: unit
+    description: "Анти-дубль диск-алерта: согласно решению ADR владельца — sidecar не порождает второй диск-алерт на то же событие переполнения (по образцу взаимодействия с ORCH-063)"
+    module: watchdog/tests/test_disk_alert_dedup.py
+    expected: PASS
+
+  - id: TC-14
+    type: unit
+    description: "Регресс орка: полный pytest tests/ зелёный — src/** не изменён, /metrics-контракт (ORCH-099) не сломан"
+    module: tests/
+    expected: PASS

docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md

@@ -0,0 +1,304 @@
+---
+work_item: ORCH-100
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Sidecar-watchdog F1b — мозг мониторинга в отдельном контейнере
+
+Work Item: **ORCH-100** — FND/F1b: sidecar-watchdog (мозг мониторинга, отдельный контейнер)
+Стадия: **architecture**
+Сквозная регистрация: **`docs/architecture/adr/adr-0033-sidecar-watchdog.md`** (решение
+кросс-каттинговое — новый компонент наблюдаемости + новый рантайм-контейнер + новый независимый
+алерт-канал; парный к adr-0030 F1a).
+
+## Статус
+Proposed
+
+## Контекст
+
+F1b — вторая половина пары наблюдаемости домена 0 «Фундамент» эпика автономного саморазвития. **F1a
+(ORCH-099, adr-0030)** уже отдаёт лёгкий read-only `GET /metrics` — **только сырьё** (стадии,
+очередь, agent-liveness, cost) в версионированном конверте. F1b — **мозг**, который это сырьё читает,
+дополняет внешними сигналами (хост, контейнеры, зависимости) и превращает в **алерты**.
+
+Рамка заказчика (Слава, 09.06) — **установленный факт, не предмет переизобретения** (BRD §1):
+- **C-1 / C-1б:** наблюдатель ОТДЕЛЁН от наблюдаемого. Код sidecar — в репо орка (`watchdog/`),
+  рантайм — **ОТДЕЛЬНЫЙ контейнер** (`orchestrator-watchdog`). Изоляция на уровне контейнера.
+- **C-2:** без внешнего плеча (один хост; принятый риск — падёт весь хост → молчит и наблюдатель).
+- **C-3:** тонкий стек — **НЕ Grafana/Prometheus/TSDB**. Хост впритык (RAM 171Mi free / 7.7Gi, диск 92%).
+- **Критический инвариант:** падение/зависание орка делает sidecar **громче**, а не тише — орк лёг ⇒
+  `/metrics` недоступен = **сам сигнал тревоги** «орк не отвечает».
+
+Факты, сверенные с кодом:
+- Орк работает `network_mode: host`, порт 8500 (`docker-compose.yml:14`) ⇒ из host-network sidecar
+  `/metrics` достижим как `http://127.0.0.1:8500/metrics`.
+- `docker.sock` на хосте `/var/run/docker.sock`, уже монтируется в орк (`docker-compose.yml:18`).
+- `src/disk_watchdog.py::decide_action(used_pct, threshold, prev, now, realert_s)` — эталонная
+  чистая решающая функция `alert | realert | recovery | none` + `PathAlertState` (in-memory
+  анти-спам) + трёхуровневый never-raise (per-path / per-tick / per-send). BRD §BR-9 прямо предписывает
+  её как образец.
+- Диск уже алертит `disk_watchdog` (ORCH-063) на 85% **через Telegram орка** — потенциальный дубль
+  (BR-10), требует явного выбора владельца.
+- `/metrics`-конверт (adr-0030 D2): `schema_version`/`generated_at`/`clk_tck`/`stages`/`queue`/
+  `agents`/`cost`/`enabled`; CPU-сырьё — `cpu_ticks` (utime+stime из `/proc`), орк **дельту не считает**
+  (stateless) — арбитр «жив/завис» это **F1b** (sidecar считает долю CPU по двум опросам).
+
+«Как есть» не годится: частичные стражи (`disk_watchdog`/`reaper`/`reconciler`) живут **ВНУТРИ
+процесса орка** — зависнет/упадёт орк, лягут и они, и платформа слепа именно в критический момент.
+
+## Решение
+
+### Сводка
+
+Новая папка `watchdog/` в репо орка — **тонкий Python-3.12-stdlib демон** (никаких сторонних
+зависимостей), собираемый в отдельный образ (`watchdog/Dockerfile`) и поднимаемый сервисом
+`orchestrator-watchdog` в `docker-compose.yml` (свой процесс/память/рестарт, `network_mode: host`,
+read-only `docker.sock`). На каждом тике: (1) `GET /metrics` орка; (2) хост (диск/inode/память/CPU);
+(3) статусы контейнеров через read-only `docker.sock`; (4) пинг Plane/Gitea/Anthropic. Каждый сигнал
+проходит через **обобщённую чистую решающую функцию** (генерализация `disk_watchdog.decide_action`) с
+per-signal in-memory дедупом/throttle/recovery и шлёт алерт в **собственный** Telegram-канал sidecar.
+Особый сигнал — `/metrics` не отвечает → `orchestrator_down`. Всё never-raise, под kill-switch,
+строго read-only к наблюдаемому. **`src/**` не меняется** — F1b потребитель `/metrics`;
+`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД орка — **не тронуты**.
+
+### D1 — Стек: Python 3.12 stdlib-only, отдельный тонкий образ (BR-1, NFR-2, C-3)
+
+**Решение: Python 3.12 + только стандартная библиотека** на базе `python:3.12-slim`.
+- `urllib.request` — HTTP к `/metrics` и пинги зависимостей (короткие таймауты).
+- `docker.sock` — **сырой HTTP-over-unix-socket** через stdlib (`socket.AF_UNIX` +
+  `http.client.HTTPConnection`-подкласс), БЕЗ pip-пакета `docker`. Только `GET /containers/json` и
+  `GET /containers/<name>/json` ⇒ read-only **по построению** (нет ни одного мутирующего вызова).
+- Хост-метрики — `shutil.disk_usage` (как `disk_watchdog`), `/proc/meminfo`, `/proc/loadavg` /
+  `os.getloadavg` — stdlib, без тяжёлых агентов.
+- Telegram — `urllib` POST на `api.telegram.org`.
+- Тесты — `pytest` на чистые функции (решение/парсинг конверта/детект down), как `disk_watchdog.decide`.
+
+Обоснование: BRD §BR-9 фиксирует `disk_watchdog.decide` как образец — Python даёт почти дословный
+перенос паттерна, переиспользует экспертизу команды и pytest, держит образ тонким (stdlib-only ⇒ нет
+дерева зависимостей). **Отвергнуто:** Go (вторая цепочка инструментов/языка ради ~десятков МБ RSS —
+не оправдано на фоне C-1-консистентности с `disk_watchdog`); `docker` SDK / `requests` / `httpx`
+(вес и поверхность зависимостей против C-3); Prometheus/Grafana/TSDB (прямой запрет C-3).
+
+Привязка: BR-1, NFR-2, FR-1, AC-1, AC-4.
+
+### D2 — Топология контейнера: `network_mode: host` + read-only docker.sock + `mem_limit` (BR-1/3/4, NFR-2/4)
+
+Сервис `orchestrator-watchdog` (`docker-compose.yml`):
+- `build: ./watchdog`, `container_name: orchestrator-watchdog`, `restart: unless-stopped`
+  (самовосстановление, FR-1).
+- **`network_mode: host`** — как орк ⇒ `/metrics` достижим как `http://127.0.0.1:8500/metrics`
+  (дефолт, конфигурируем), и доступны хост-интерфейсы. Отвергнут bridge + `host.docker.internal`
+  (на Linux ненадёжно, лишняя сложность).
+- **`/var/run/docker.sock:/var/run/docker.sock:ro`** — read-only mount (NFR-4, AC-6); даже при
+  read-only mount код делает **только** GET-запросы (двойная гарантия).
+- **Хост-пути для дисковых метрик** — read-only bind тех же путей, что меряет `disk_watchdog`
+  (`/repos`, `/app/data`/`./data`), `:ro` ⇒ `shutil.disk_usage` видит хост-ФС, но не может писать.
+- **`mem_limit: 128m`** (+ `mem_reservation: 32m`) — тонкость измерима и принудительна (NFR-2).
+  Ожидаемый базовый RSS однопоточного stdlib-демона ~40–60 МБ; 128 МБ — потолок с запасом, но далеко
+  от Grafana-класса. OOM при превышении = ранний сигнал «sidecar растолстел» (см. 10-tech-risks TR-4).
+- `env_file: .env.watchdog` (или общий `.env` с префиксом `WATCHDOG_`; точный файл — деталь
+  инфра-предусловия 07). Свои токен/chat — **только** у sidecar.
+- **Self-hosting:** добавление нового сервиса и `docker compose up -d orchestrator-watchdog`
+  поднимает ТОЛЬКО watchdog — прод-контейнер `orchestrator` НЕ пересобирается и НЕ рестартится
+  (отдельный сервис). Это снимает риск «деплой наблюдателя уронил наблюдаемого».
+
+Привязка: BR-1, BR-3, BR-4, NFR-2, NFR-4, FR-1, FR-4, FR-5, AC-1, AC-4, AC-6.
+
+### D3 — Структура кода `watchdog/` (NFR-3, NFR-7)
+
+```
+watchdog/
+  Dockerfile          # python:3.12-slim, COPY watchdog/, ENTRYPOINT демон
+  __main__.py         # цикл: tick loop, kill-switch, per-tick never-raise, лог старта/тика
+  config.py           # чтение WATCHDOG_* env (пороги/интервалы/токены/URL/kill-switch), дефолты
+  collectors/
+    orch.py           # GET /metrics -> распарсенный конверт | сигнал orchestrator_down
+    host.py           # диск (shutil.disk_usage) / inode / память (/proc/meminfo) / CPU (loadavg)
+    containers.py     # docker.sock (ro) GET list/inspect -> статусы Up/healthy/restarting/exited/unhealthy
+    deps.py           # пинг Plane/Gitea/Anthropic (urllib, короткий таймаут)
+  decision.py         # ЧИСТАЯ decide(...) + AlertState (генерализация disk_watchdog)
+  notify.py           # независимый Telegram-транспорт (свой токен/chat; НЕ импорт src/notifications)
+  tests/              # pytest на чистые функции (или tests/watchdog/ — на усмотрение developer)
+```
+
+Никакого импорта из `src/**` (иначе падение/рефактор орка утянул бы sidecar — нарушение C-1).
+Логирование старта/тика/каждого вердикта в stdout контейнера (NFR-7) — по логам видно, что sidecar
+жив и почему (не)сработал алерт.
+
+Привязка: BR-8, NFR-1, NFR-3, NFR-7, FR-8, FR-11, AC-3.
+
+### D4 — Обобщённая чистая решающая функция (BR-6, BR-9, FR-7) — образец `disk_watchdog.decide_action`
+
+`disk_watchdog.decide_action` зашит на `used_pct >= threshold`. Для F1b сигналов много и они
+разнотипны (булевы — «орк down», «контейнер unhealthy»; счётчики — «job-failed delta»; пороговые —
+«память %», «agent завис N мин»). Поэтому **сравнение выносится наружу**, а функция работает с уже
+вычисленным булевым `signal_active`:
+
+```
+def decide(signal_active: bool, prev: AlertState, now: float, cooldown_s: float) -> str:
+    # not alerting & active           -> ALERT     (пересечение порога)
+    # alerting & active & cooldown ок -> REALERT   (повтор)
+    # alerting & active & в cooldown  -> NONE       (анти-спам)
+    # alerting & не active            -> RECOVERY   (возврат в норму)
+    # not alerting & не active        -> NONE       (норма)
+
+@dataclass
+class AlertState:            # 1:1 семантика PathAlertState
+    alerting: bool = False
+    last_alert_at: float | None = None
+```
+
+Это **строгая генерализация** disk-варианта (тот же набор исходов, та же cooldown/recovery-семантика,
+тот же in-memory best-effort, инъецируемые `now`/`cooldown` для детерминированных тестов). Состояние —
+карта `{signal_key -> AlertState}`, где `signal_key` идентифицирует сигнал: скаляр (`"orch_down"`,
+`"host_mem"`) или кортеж для пер-сущностных (`("agent_hung", run_id)`, `("container_down", name)`,
+`("stage_stuck", work_item)`, `("dep_down", dep_name)`). Рестарт sidecar сбрасывает карту →
+корректно повторно алертит ещё стоящую проблему (как `disk_watchdog`; FR-7).
+
+Привязка: BR-6, BR-9, FR-7, AC-2, TC-01…TC-04.
+
+### D5 — Реестр сигналов и их пороги (BR-2/3/4/5/6/7, FR-2…FR-7)
+
+| signal_key | Источник | `signal_active` когда | Порог (env, дефолт) |
+|------------|----------|------------------------|----------------------|
+| `orch_down` | collectors/orch | K подряд неудачных `/metrics` (таймаут/refused/5xx/нечитаемо) | `WATCHDOG_ORCH_DOWN_TICKS=3` |
+| `host_mem` | host | `mem_used_pct >= порог` | `WATCHDOG_MEM_PCT=90` |
+| `host_disk_crit` | host | `disk_used_pct >= ceiling` (**opt-in, см. D6**) | `WATCHDOG_DISK_CRIT_PCT=97`, `WATCHDOG_DISK_CRIT_ENABLED=false` |
+| `agent_hung` (per run_id) | orch.agents | `runtime_s > N` И доля CPU (Δ`cpu_ticks`/`clk_tck`/Δ`generated_at`) `< floor` | `WATCHDOG_AGENT_HUNG_MIN=20`, `WATCHDOG_AGENT_CPU_FLOOR=0.01` |
+| `stage_stuck` (per work_item) | orch.stages | `age_in_stage_s > порог` | `WATCHDOG_STAGE_STUCK_MIN=120` |
+| `job_failed` | orch.queue | `counts.failed` вырос с прошлого тика (edge) | — (дельта; алерт на рост) |
+| `queue_depth` | orch.queue | `depth >= порог` | `WATCHDOG_QUEUE_DEPTH=20` |
+| `container_down` (per name) | containers | статус ∉ {running, healthy} (restarting/exited/unhealthy) | список `WATCHDOG_CONTAINERS=orchestrator` |
+| `dep_down` (per name) | deps | пинг неуспешен/таймаут | URL'ы/таймаут из env |
+
+- **`agent_hung`** требует **двух** опросов (stateful у sidecar) — sidecar хранит предыдущие
+  `(cpu_ticks, generated_at)` per run_id и считает долю CPU; `cpu_ticks: null` (pid мёртв/не-Linux —
+  adr-0030 D5) ⇒ сигнал не вычисляется (none), не ложная тревога.
+- **`job_failed`** — edge-сигнал (рост счётчика), а не sustained-порог: при росте `failed` → ALERT
+  один раз; recovery как такового нет (это событие), поэтому состояние сбрасывается сразу после
+  отправки (alerting=False), чтобы следующий новый фейл снова алертил.
+- Все пороги/интервалы/URL/таймауты/cooldown — из env (FR-10), канон в `.env.example`.
+
+Привязка: BR-2…BR-7, FR-2…FR-7, AC-1, AC-2.
+
+### D6 — Владелец диск-алерта: disk_watchdog остаётся основным; sidecar — opt-in критический потолок (BR-10, FR-9) — **ключевое решение**
+
+BRD §BR-10 / FR-9 / AC-5 явно делегируют выбор владельца архитектору. **Решение:**
+
+1. **Штатный диск-алерт на 85% остаётся ЕДИНСТВЕННО за внутренним `disk_watchdog` (ORCH-063), через
+   Telegram орка.** Sidecar **НЕ** запускает независимый диск-алерт на том же пороге ⇒ **нулевой дубль
+   по построению** (AC-5 удовлетворён структурно, а не throttle-эвристикой).
+2. **Вклад sidecar в дисковую безопасность — покрытие именно того провала, который F1b и создаётся
+   закрывать:** когда орк (а с ним и in-process `disk_watchdog`) **завис/упал**, штатный диск-алерт
+   физически невозможен. Тогда срабатывает **`orch_down`** — мастер-сигнал sidecar с независимого
+   канала; его текст явно подсказывает «in-process стражи (диск/reaper/reconciler) тоже мертвы →
+   проверьте хост, включая диск».
+3. **Крайний edge — орк жив, но его Telegram сломан** (диск растёт, `disk_watchdog` не может
+   доставить): sidecar несёт **opt-in** независимый алерт `host_disk_crit` на **более высоком**
+   пороге-потолке (дефолт 97%, **выключен по умолчанию** `WATCHDOG_DISK_CRIT_ENABLED=false`). Это
+   **другое событие** (критический потолок, независимый канал), а не повтор 85%-события ⇒ инвариант
+   «не более одного алерта на одно событие переполнения» сохранён. Включается оператором осознанно,
+   когда нужна избыточность канала.
+
+Итог: из коробки — ровно один владелец диска (`disk_watchdog`); резервирование канала — обратимый
+opt-in. Решение и обоснование зафиксированы здесь (AC-5).
+
+Привязка: BR-10, FR-9, AC-5.
+
+### D7 — Независимый Telegram-транспорт (BR-8, NFR-4, FR-8)
+
+`watchdog/notify.py` читает **свои** `WATCHDOG_TG_BOT_TOKEN` / `WATCHDOG_TG_CHAT_ID` из env и шлёт
+через `urllib` POST на `api.telegram.org`. **Запрещено** импортировать `src/notifications.py` или
+использовать токен/функции/чат орка — иначе падение/рефактор орка утянул бы алерт-канал (нарушение
+C-1, прямой смысл BR-8). Отсутствие токена/chat → sidecar логирует и не шлёт (fail-safe), но **не
+падает** (NFR-3). Сообщение несёт суть: сигнал, значение, порог, хост/контейнер.
+
+Привязка: BR-8, NFR-4, FR-8, AC-2, AC-6.
+
+### D8 — Three-level never-raise + kill-switch (NFR-3, NFR-5, FR-10, FR-11)
+
+- **per-source:** битый коллектор (орк down / docker.sock недоступен / пинг таймаут) деградирует
+  ОДИН сигнал, прочие собираются (`orch_down` сам по себе — нормальный сигнал, а не крах тика).
+- **per-tick:** внешний `try/except` цикла — ошибка тика логируется, не валит демон.
+- **per-send:** обёрнутый `notify` — сбой Telegram логируется и проглатывается (best-effort).
+- **Kill-switch** `WATCHDOG_ENABLED` (env): `false` → демон **инертен** (idle-loop с логом «disabled»,
+  НЕ `exit`, чтобы `restart: unless-stopped` не крутил рестарт-петлю) ⇒ нулевой эффект на орк и
+  конвейер. Полная обратимость: не запускать сервис вовсе / `WATCHDOG_ENABLED=false`.
+
+Привязка: NFR-1, NFR-3, NFR-5, FR-10, FR-11, AC-3, AC-4.
+
+### D9 — Толерантность к версии `/metrics` (NFR-6, FR-2)
+
+`collectors/orch.py` парсит конверт защитно: неизвестные ключи игнорируются, отсутствие
+опционального — не ошибка (дефолт `None`/`[]`/`{}`), `enabled:false` трактуется явно (орк сам
+выключил `/metrics` — не `orch_down`). Рост `schema_version` выше известного → `logger.warning`
+(«новая версия контракта, читаю совместимое подмножество»), **не** крэш. Это зеркалит аддитивно-
+толерантную политику F1a (adr-0030 D2): sidecar обязан пережить расширение `/metrics` без правок.
+
+Привязка: NFR-6, FR-2, AC-1.
+
+## Альтернативы
+
+- **Go-стек / `docker` SDK / `requests`** — отвергнуто: вес/вторая цепочка инструментов против C-3 и
+  C-1-консистентности с `disk_watchdog` (D1).
+- **Prometheus/Grafana/TSDB/дашборд** — отвергнуто: прямой запрет C-3 (тонкий стек, хост впритык).
+- **Sidecar — единственный владелец диска (внутренний `disk_watchdog` выключить)** — отвергнуто:
+  потеря покрытия диска, когда сам sidecar/хост-Docker недоступен; `disk_watchdog` дешёв и уже в
+  проде. Выбрана связка «disk_watchdog primary + sidecar opt-in ceiling» (D6).
+- **Sidecar дублирует диск на 85% с дедупом по времени** — отвергнуто: хрупкая координация двух
+  каналов на одном событии; структурное «один владелец на порог» надёжнее (D6).
+- **Push метрик из орка в sidecar** — отвергнуто: при зависшем орке push не уходит; pull-опрос
+  падает = **сам сигнал** `orch_down` (C-1).
+- **bridge-сеть + `host.docker.internal`** — отвергнуто: на Linux ненадёжно; `network_mode: host`
+  проще и достигает и `/metrics`, и хост-интерфейсов (D2).
+- **Своя БД/файл состояния порогов** — отвергнуто: тонкий стек (C-3); in-memory best-effort
+  достаточно (рестарт → корректный повторный алерт стоящей проблемы), как `disk_watchdog` (D4).
+
+## Последствия
+
+- **+** Появляется внешний мозг мониторинга, переживающий падение орка — закрыт корневой пробел
+  «in-process стражи лягут вместе с орком»; `orch_down` делает наблюдателя **громче** в инцидент.
+- **+** Строго read-only к наблюдаемому (docker.sock `:ro` + GET-only, нет записи в БД/диск/`main`,
+  нет start/stop/restart/exec) + независимый канал ⇒ self-hosting-безопасно (enduro-trails не
+  затронут); падение sidecar не влияет на конвейер (NFR-1/4, AC-6).
+- **+** Аддитивно и обратимо: новая папка `watchdog/`, новый сервис compose, новые `WATCHDOG_*` env.
+  `src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД орка — байт-в-байт. Kill-switch →
+  нулевая регрессия.
+- **+** Дубль диск-алерта исключён структурно (D6): один владелец на порог; резерв канала — opt-in.
+- **−** Новый рантайм-контейнер на впритык-хосте: бюджет памяти `mem_limit: 128m` (D2) + измерение
+  фактического RSS на staging — обязательны (10-tech-risks TR-4).
+- **−** C-2: падёт весь хост/Docker → молчит и sidecar (принятый заказчиком риск; внешнее плечо L2
+  отложено).
+- **−** Новая поверхность совместимости `/metrics`↔F1b — митигируется толерантным парсингом (D9) +
+  единым репо контракта (adr-0030). CPU-liveness Linux-специфичен (`/proc`); не-Linux → сигнал
+  `agent_hung` деградирует в none, не ошибка.
+- **Топология:** меняется (новый контейнер) → см. `07-infra-requirements.md` (разовое действие:
+  добавить сервис в compose, создать bot/chat watchdog, смонтировать docker.sock `:ro` + хост-пути,
+  первый запуск). **Схема БД:** не меняется → `08-data-requirements.md` = N/A.
+- **Эскалация:** новый компонент наблюдаемости + новый рантайм-контейнер + новый алерт-канал → лейбл
+  **`arch:major-change`** (консервативно, хоть изменение аддитивно/read-only/обратимо). Прод-выкат —
+  строго через staging-гейт (8501); деплой sidecar НЕ рестартит прод-контейнер `orchestrator`.
+- **Откат:** не запускать сервис / `WATCHDOG_ENABLED=false` (мгновенный); удаление папки `watchdog/`
+  + сервиса из compose + `WATCHDOG_*` env — полный откат без следов (нет БД/схемы/изменений `src`).
+
+## Ссылки
+- BRD: `docs/work-items/ORCH-100/01-brd.md`
+- TRZ: `docs/work-items/ORCH-100/02-trz.md`
+- Acceptance: `docs/work-items/ORCH-100/03-acceptance-criteria.md`
+- Инфра-требования: `docs/work-items/ORCH-100/07-infra-requirements.md`
+- Данные: `docs/work-items/ORCH-100/08-data-requirements.md` (N/A)
+- Тех-риски: `docs/work-items/ORCH-100/10-tech-risks.md`
+- Сквозной ADR: `docs/architecture/adr/adr-0033-sidecar-watchdog.md`
+- Сверено по коду: `src/disk_watchdog.py` (`decide_action`/`PathAlertState`/трёхуровневый never-raise
+  — эталон D4/D8), `docker-compose.yml` (`network_mode: host`, `docker.sock` mount — база D2),
+  `src/metrics.py`/adr-0030 (контракт `/metrics`, `cpu_ticks`/`clk_tck`/`generated_at` — D5/D9).
+- Связанные ADR: adr-0030 (F1a `/metrics` — источник сырья, парный контракт), adr-0024
+  (`disk_watchdog` — образец решающей функции/never-raise/владелец диск-алерта), adr-0025
+  (build-cache-pruner — «вторая половина» паттерн), adr-0017 (serial_gate — leaf never-raise),
+  adr-0011 (job-reaper — pid/liveness-семантика).
+</content>
+</invoke>

docs/work-items/ORCH-100/07-infra-requirements.md

@@ -0,0 +1,93 @@
+---
+work_item: ORCH-100
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 07 — Инфра-требования: ORCH-100 — FND/F1b: sidecar-watchdog
+
+Work Item: **ORCH-100** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable: топология **меняется** (новый рантайм-контейнер). Разовое инфра-действие выполняет
+> человек (Слава/Стрим) на хосте mva154; дальше код `watchdog/` катится через конвейер (self-hosting).
+
+## I-1. Топология / окружения
+
+Новый сервис `orchestrator-watchdog` в `docker-compose.yml` — **отдельный контейнер** рядом с
+`orchestrator` (8500) и `orchestrator-staging` (8501, profile staging).
+- **Образ:** `build: ./watchdog` (`watchdog/Dockerfile`, `python:3.12-slim`, stdlib-only).
+- **Сеть:** `network_mode: host` — достаёт `/metrics` орка как `http://127.0.0.1:8500/metrics` и
+  хост-интерфейсы (ADR-001 D2).
+- **Тома (все read-only к наблюдаемому, NFR-4):**
+  - `/var/run/docker.sock:/var/run/docker.sock:ro` — статусы контейнеров (GET-only).
+  - `/home/slin/repos:/repos:ro` и `./data:/app/data:ro` (или эквивалент) — дисковые метрики хоста
+    через `shutil.disk_usage` (те же пути, что у `disk_watchdog`).
+- **Лимиты:** `mem_limit: 128m` + `mem_reservation: 32m` (тонкость измерима/принудительна, NFR-2);
+  `restart: unless-stopped` (самовосстановление, FR-1).
+- **Kill-switch:** `WATCHDOG_ENABLED` (env). `false` → демон инертен (idle-loop, не exit — чтобы
+  `restart` не крутил петлю), нулевой эффект на орк.
+- **Контейнеры под наблюдением (BR-4):** минимум `orchestrator`; список `WATCHDOG_CONTAINERS` (CSV).
+- **Образец сервиса (ориентир для developer; точные пути сверить с актуальным `docker-compose.yml`):**
+  ```yaml
+  orchestrator-watchdog:
+    build: ./watchdog
+    container_name: orchestrator-watchdog
+    restart: unless-stopped
+    network_mode: host
+    mem_limit: 128m
+    mem_reservation: 32m
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /home/slin/repos:/repos:ro
+      - ./data:/app/data:ro
+    env_file: .env.watchdog        # ЛИБО общий .env с префиксом WATCHDOG_ (деталь — developer/оператор)
+    group_add: ["999"]             # docker-группа для чтения docker.sock (как у орка)
+  ```
+
+## I-2. Переменные окружения / секреты
+
+Канон (без секретов) — в `.env.example` (TRZ §2). Префикс `WATCHDOG_` (изоляция от `ORCH_`):
+- **Секреты (только на хосте, в гит НЕ коммитятся):** `WATCHDOG_TG_BOT_TOKEN`, `WATCHDOG_TG_CHAT_ID`
+  — **собственные** bot/chat sidecar, независимые от Telegram орка (BR-8). Отсутствие → sidecar
+  логирует и не шлёт (fail-safe), но не падает.
+- **Управление:** `WATCHDOG_ENABLED` (kill-switch), `WATCHDOG_INTERVAL_S` (дефолт 60),
+  `WATCHDOG_ORCH_METRICS_URL` (дефолт `http://127.0.0.1:8500/metrics`).
+- **Пороги/таймауты (дефолты — ADR-001 D5):** `WATCHDOG_ORCH_DOWN_TICKS=3`, `WATCHDOG_MEM_PCT=90`,
+  `WATCHDOG_DISK_CRIT_ENABLED=false`, `WATCHDOG_DISK_CRIT_PCT=97`, `WATCHDOG_AGENT_HUNG_MIN=20`,
+  `WATCHDOG_AGENT_CPU_FLOOR=0.01`, `WATCHDOG_STAGE_STUCK_MIN=120`, `WATCHDOG_QUEUE_DEPTH=20`,
+  `WATCHDOG_COOLDOWN_S` (анти-спам realert), `WATCHDOG_HTTP_TIMEOUT_S`.
+- **Цели:** `WATCHDOG_CONTAINERS` (CSV, дефолт `orchestrator`), `WATCHDOG_DEP_PLANE_URL`/
+  `WATCHDOG_DEP_GITEA_URL`/`WATCHDOG_DEP_ANTHROPIC_URL` (health/ping).
+
+> Анти-дубль диск-алерта (ADR-001 D6): штатный 85%-алерт остаётся за внутренним `disk_watchdog`
+> (ORCH-063). `WATCHDOG_DISK_CRIT_ENABLED` по умолчанию `false` — sidecar НЕ дублирует диск, пока
+> оператор осознанно не включит независимый критический потолок.
+
+## I-3. Деплой / рестарт
+
+- **Разовое действие человеком на хосте (Слава/Стрим):**
+  1. Создать **отдельного** Telegram-бота watchdog + получить chat-id; положить `WATCHDOG_TG_*` в
+     `.env.watchdog` (или `.env`) на хосте.
+  2. Заполнить пороги/интервалы (дефолты годятся), включить `WATCHDOG_ENABLED=true`.
+  3. Добавить сервис в `docker-compose.yml` (приходит с PR) и поднять **только его:**
+     `docker compose up -d --build orchestrator-watchdog`.
+- **Self-hosting инвариант (критично):** поднятие/пересборка `orchestrator-watchdog` **НЕ** трогает
+  прод-контейнер `orchestrator` (отдельный сервис) — конвейер всех проектов не прерывается. **НЕ**
+  выполнять `docker compose up -d` без явного имени сервиса, если это спровоцирует рекреейт орка.
+- **Прод-выкат кода watchdog** — через штатный self-hosting-конвейер и **обязательный staging-гейт
+  (8501)** перед прод-деплоем; деплой sidecar не рестартит прод-контейнер орка.
+- **Проверка после старта (NFR-7):** `docker logs orchestrator-watchdog` показывает старт + тики;
+  тестовый алерт приходит в канал watchdog; остановка орка (на staging) → приходит `orch_down`.
+
+## I-4. CI/CD
+
+- Без изменений `.gitea/workflows/` по существу: новые тесты sidecar (`watchdog/tests/` или
+  `tests/watchdog/`) подхватываются существующим `pytest tests/`/прогоном (изолированы, чистые
+  функции — без контейнера/таймера). Если выбран отдельный путь `watchdog/tests/`, developer
+  обеспечивает его включение в существующий тест-ран (без нового workflow-файла).
+- Docker-сборка нового образа — стандартным `docker compose build` (отдельный `watchdog/Dockerfile`),
+  без правок пайплайна CI.
+</content>

docs/work-items/ORCH-100/08-data-requirements.md

@@ -0,0 +1,40 @@
+---
+work_item: ORCH-100
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 08 — Требования к данным: ORCH-100 — FND/F1b: sidecar-watchdog
+
+Work Item: **ORCH-100** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable. Создан для аудитопригодности: фиксирует, что схема БД **не меняется** — это
+> архитектурное утверждение (sidecar вне процесса орка, без своей БД), а не пропуск.
+
+## Изменения схемы БД орка
+
+**N/A.** Sidecar **не пишет** в БД орка (NFR-4: строго read-only к наблюдаемому — нет
+`INSERT/UPDATE/DELETE/CREATE/ALTER`) и **не читает** её напрямую: всё орк-сырьё идёт через
+`GET /metrics` (F1a, adr-0030). `tasks`/`jobs`/`agent_runs`/`STAGE_TRANSITIONS`/`QG_CHECKS` —
+не тронуты.
+
+## Собственное хранилище sidecar
+
+**Нет (по решению C-3 / ADR-001 D4).** Состояние порогов (`AlertState`: `alerting`/`last_alert_at`
+per signal_key) — **in-memory best-effort** в процессе демона: ни таблицы, ни файла, ни миграции.
+Рестарт sidecar сбрасывает карту состояний → ещё стоящая проблема корректно повторно алертится один
+раз (ранний сигнал, не SLA) — 1:1 семантика `disk_watchdog.PathAlertState` (ORCH-063).
+
+## Журнал уроков (F2)
+
+**Вне объёма.** Долговременное хранение инцидентов/уроков (потенциально БД орка) — отдельная задача
+домена F2; F1b ничего не персистит (BRD §«Вне объёма»).
+
+## Вывод
+
+Изменений данных/схемы нет. Контракт данных F1b — **потребление** версионированного JSON `/metrics`
+(adr-0030) + эфемерное in-memory состояние порогов. Откат не оставляет следов в БД.
+</content>

docs/work-items/ORCH-100/10-tech-risks.md

@@ -0,0 +1,44 @@
+---
+work_item: ORCH-100
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-100 — FND/F1b: sidecar-watchdog
+
+Work Item: **ORCH-100** · Repo: **orchestrator** · Стадия: architecture
+
+> Информационный (гейтом не парсится). Реестр рисков реализации F1b и митигейшн.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | **Дубль диск-алерта** с `disk_watchdog` (ORCH-063) на одно событие переполнения. | Сред. | Низ. | ADR-001 D6: 85% остаётся ЕДИНСТВЕННО за `disk_watchdog` (канал орка); sidecar НЕ дублирует порог — `host_disk_crit` opt-in (default off) и на другом пороге-потолке (97%, другой канал = другое событие). Структурно один владелец на порог. |
+| TR-2 | **Ложный `orch_down`** на одиночной сетевой икоте `/metrics` (флапп). | Сред. | Сред. | Порог `WATCHDOG_ORCH_DOWN_TICKS` (K подряд неудачных опросов, дефолт 3) + cooldown/recovery decide() (FR-3). Единичный transient → none. |
+| TR-3 | **Sidecar толстеет** (память на впритык-хосте, 171Mi free) и сам становится проблемой. | Низ. | Сред. | Stdlib-only Python, один поток (D1); `mem_limit: 128m` + `mem_reservation: 32m` принудительно (D2); **обязательный замер фактического RSS на staging** перед прод-выкатом; OOM = ранний сигнал, не тихий рост. |
+| TR-4 | **Привилегии docker.sock** — доступ к Docker API = потенциально мощно. | Низ. | Выс. | Mount `:ro` (NFR-4) + код делает ТОЛЬКО GET (list/inspect), без `docker` SDK — мутаций нет по построению; ревью + статпроверка (AC-6/TC-09). |
+| TR-5 | **Дрейф контракта `/metrics`** (F1a расширили/сломали) роняет/искажает sidecar. | Низ. | Сред. | Толерантный парсинг (D9): неизвестные ключи игнор, отсутствие опционального не ошибка, рост `schema_version` → warning не крэш; единый репо контракта (adr-0030); ломающее изменение `/metrics` — отдельная задача-расширение F1a, не F1b. |
+| TR-6 | **Шум алертов** (флапп на границе порога agent_hung/stage_stuck/mem). | Сред. | Низ. | Чистая decide() с cooldown/realert/recovery (D4, образец disk_watchdog); пороги/cooldown из env (тюнинг без релиза); `agent_hung` требует 2 опросов + CPU-floor (не дёргается на коротких паузах). |
+| TR-7 | **Self-hosting: деплой sidecar задел прод-контейнер** `orchestrator`. | Низ. | Выс. | Отдельный сервис; `docker compose up -d orchestrator-watchdog` поднимает только его (07 I-3); прод-выкат через staging-гейт (8501); деплой sidecar не рестартит орк. |
+| TR-8 | **`network_mode: host`** у sidecar — разделяет сетевой namespace хоста. | Низ. | Низ. | Sidecar read-only, не слушает входящих портов (опц. liveness вне обязательного объёма); host-network нужен для достижимости `/metrics` и хост-интерфейсов (D2); поверхность минимальна. |
+| TR-9 | **Утечка/отсутствие** `WATCHDOG_TG_*` (свой бот) → алерты не доходят/секрет в гит. | Низ. | Сред. | Секреты только в `.env*` на хосте, канон без значений в `.env.example` (правило 8); отсутствие токена → fail-safe (лог, не падение, не шлёт); префикс `WATCHDOG_` изолирует от `ORCH_`. |
+| TR-10 | **C-2: падёт весь хост/Docker** → молчит и sidecar (нет внешнего плеча). | Низ. | Выс. | Принятый заказчиком риск (одна площадка); внешнее плечо L2 сознательно отложено (BRD §«Вне объёма»). Документируется, не закрывается в F1b. |
+
+## Сводный вывод
+
+Доминирующий класс — **операционно-инфраструктурный** (привилегии docker.sock, память впритык,
+self-hosting-безопасность), а не алгоритмический: ядро (decide/парсинг) — чистые тестируемые функции,
+перенос зрелого паттерна `disk_watchdog`. Все мутирующие пути закрыты по построению (read-only mount +
+GET-only, нет записи в БД/`main`), независимый алерт-канал и kill-switch дают полную обратимость.
+Остаточный риск для прод-конвейера (enduro-trails и пр.) — **near-zero**: F1b физически вне процесса
+орка и вне конвейера QG, при выключенном флаге — нулевой эффект.
+
+**Эскалация:** новый компонент наблюдаемости + новый рантайм-контейнер + новый алерт-канал → лейбл
+**`arch:major-change`** (консервативно). Возврат в анализ **не требуется** — ТЗ выполнимо в рамках
+принципов (всё в Docker на одном сервере, тонкий стек, минимум зависимостей). Обязательное
+предусловие приёмки developer/tester: **замер фактического RSS sidecar на staging** (TR-3).
+</content>

docs/work-items/ORCH-100/12-review.md

@@ -0,0 +1,138 @@
+---
+verdict: APPROVED
+work_item: ORCH-100
+stage: review
+author_agent: reviewer
+status: approved
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-100
+version: 2
+---
+
+# Review ORCH-100 — FND/F1b: sidecar-watchdog (re-review)
+
+## Summary
+
+Аддитивная реализация sidecar-наблюдателя в отдельном контейнере `orchestrator-watchdog`
+(папка `watchdog/`, тонкий Python-3.12-stdlib-only демон). Это **повторное ревью** после цикла
+`testing → development`: предыдущий прогон тестера дал `result: FAIL` из-за единственного красного
+теста `tests/test_queue.py::TestRetry::test_finalize_job_requeue_then_fail`; развработчик закрыл
+причину тест-only фиксом (коммит `2040de3` — autouse-фикстура `_isolate_runs_dir` в
+`tests/conftest.py`, **без правок `src/**`**).
+
+Проверено по 4 осям. Реализация **точно** соответствует ТЗ (FR-1…FR-11) и ADR-001 (D1…D9):
+отдельный контейнер, толерантный парсинг `/metrics` (D9), debounce `orch_down` (FR-3, порог
+`orch_down_ticks`), read-only `docker.sock` (`_get` хардкодит `GET` — read-only **по построению** +
+mount `:ro`), обобщённая чистая `decide` (D4, 1:1 семантика `disk_watchdog`), независимый
+Telegram-канал (свои токены, ноль импортов `src/**`), структурный анти-дубль диск-алерта (D6,
+opt-in потолок), трёхуровневый never-raise (per-source/per-tick/per-send), kill-switch (idle-loop,
+не exit).
+
+**Корневой инвариант соблюдён:** PR не трогает `src/**` ни одной строкой за всю ветку, включая
+fix-коммит (`git diff origin/main...HEAD --stat -- 'src/**'` → пусто) ⇒ `STAGE_TRANSITIONS` /
+`QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД орка — байт-в-байт прежние.
+
+**Блокер тестирования снят.** Полный регресс `pytest tests/` теперь **зелёный (1617 passed)`**,
+профильная сюита `tests/watchdog/` — **66/66 PASS**. Документация обновлена исчерпывающе.
+
+**Вердикт: APPROVED.** P0/P1 нет. Ниже — анализ снятого блокера и P2/P3-замечания (не блокируют).
+
+## Findings
+
+### P0 — Blocker
+- (нет)
+
+### P1 — Must fix
+- (нет)
+
+### P2 — Should fix
+- [ ] **ADR-001 D3: docstring-блок структуры `host.py` упоминает «CPU (loadavg)», которого в
+  реализации нет.** ADR D3 (строка с `host.py # ... / CPU (loadavg)`) перечисляет CPU/inode среди
+  host-метрик, но реестр сигналов D5 сознательно сузил host до `host_mem` + opt-in `host_disk_crit`,
+  а host-CPU/«завис» покрыт через `agent_hung` из `/metrics`. Сам `watchdog/collectors/host.py`
+  внутренне консистентен (его docstring явно пишет «CPU ... computed from the /metrics envelope, not
+  here»), inode FR-4 оговорён как «где доступно» — это документированное сужение на стадии
+  архитектуры, **не нарушение ТЗ**. Замечание косметическое: привести строку D3 в соответствие с D5
+  (снять «CPU (loadavg)»/inode из блока структуры). Источник: `ADR-001` D3/D5, `02-trz.md` FR-4.
+
+### P3 — Nice-to-have
+- [ ] **CLAUDE.md не обновлён.** Паспорт проекта не получил TL;DR-запись о F1b. Прецедент: парная
+  задача F1a (ORCH-099) также отсутствует в CLAUDE.md (`grep` → 0) — семейство наблюдаемости в
+  паспорте не трекается, а золотой архитектурный док (`docs/architecture/README.md`) покрывает F1b
+  исчерпывающе. Опционально для единообразия с операционными демонами (`disk_watchdog`/`reaper`).
+- [ ] **`DockerSockReader.list_containers` не вызывается** в `core.tick` (используется только
+  `inspect(name)` по `cfg.containers`). Публичный read-метод оставлен для полноты API/тестов
+  (`test_docker_readonly.py`) — безвреден; при желании пометить как explicit-API.
+
+## Анализ снятого блокера (testing FAIL → development fix)
+
+- **Причина прежнего FAIL:** `test_finalize_job_requeue_then_fail` (run_id=1/2) читал хвост
+  `<settings.runs_dir>/<run_id>.log`. Дефолтный `runs_dir` указывал на прод-каталог
+  `/app/data/runs`, где на self-hosting-хосте лежат реальные накопленные `*.log`; реальный `2.log`
+  с токеном «429» переключал классификацию `permanent → transient` (requeue вместо `failed`). Это
+  **ambient prod-pollution окружения, не дефект кода** — сам тест байт-в-байт идентичен
+  `origin/main`, а `src/**` ORCH-100 не трогает.
+- **Фикс (коммит `2040de3`):** autouse-фикстура `_isolate_runs_dir` редиректит `settings.runs_dir`
+  на per-test `tmp_path` ⇒ `_run_log_path()` резолвится в несуществующий файл ⇒
+  `classify_log_file()` возвращает документированный дефолт `permanent` ⇒ детерминированный,
+  не зависящий от окружения результат для всей сюиты. Зеркалит существующие autouse-фикстуры
+  `_no_telegram`/`_disable_merge_verify`/`_reset_webhook_secrets`.
+- **Это НЕ «подгонка теста под код»:** тело теста не изменено; добавлена только изоляция окружения
+  (test-infra). Фикс улучшает гигиену всей сюиты и устраняет скрытую env-зависимость. Прежний
+  диагноз тестера («реальное красное, ловящее расхождение requeue→finalize в launcher») оказался
+  ошибочным — корень был в загрязнении прод-логами; артефакт тестера (`13-test-report.md`) не правлю
+  (чужая стадия), фиксирую факт здесь.
+- **Верификация (независимо):** `git diff origin/main...HEAD --stat -- 'src/**'` → пусто (включая
+  fix-коммит); изолированный прогон `test_finalize_job_requeue_then_fail` → **1 passed**; полный
+  `pytest tests/` → **1617 passed**; `tests/watchdog/` → **66 passed**.
+- **Багфикс-трек (ORCH-019 BR-4):** задача — `feat`/FND (не `Bug`) ⇒ требование
+  регресс-теста-фиксатора не применяется. Фикс окружения, тем не менее, детерминирует поведение
+  всей сюиты.
+
+## Документация
+
+**Обновлена исчерпывающе — golden source синхронизирован с кодом:**
+- ✅ `docs/architecture/README.md` — новая компонентная строка (Sidecar-watchdog F1b) + полная
+  секция дизайна F1b + перекрёстная ссылка из секции F1a.
+- ✅ `CHANGELOG.md` — детальная запись F1b (стек D1 / топология D2 / decide D4 / реестр сигналов D5 /
+  анти-дубль D6 / транспорт D7 / never-raise D8) **+** отдельная строка fix-коммита `2040de3`
+  (`_isolate_runs_dir`).
+- ✅ `docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md` + сквозной
+  `docs/architecture/adr/adr-0033-sidecar-watchdog.md` (оба с корректным frontmatter).
+- ✅ `docs/work-items/ORCH-100/07-infra-requirements.md` — разовое инфра-предусловие (сервис в
+  compose, bot/chat watchdog, `.env.watchdog`, первый запуск).
+- ✅ `.env.example` — канон всех `WATCHDOG_*` ключей, **без реальных секретов** (`TG_BOT_TOKEN`/
+  `TG_CHAT_ID` пустые).
+- ⚠️ **CLAUDE.md** — не обновлён (P3, прецедент F1a — допустимо).
+- ✅ **README «Известные ограничения» (ось ORCH-079):** F1b — новая способность (внешний
+  наблюдатель); **ни один** из 3 открытых пунктов витрины (Telegram-48h / intra-repo task-deps /
+  пакетный автоном Этап 1) не закрывается этим PR ⇒ обновления обзорной витрины не требуется.
+
+**`src/**` НЕ изменён ⇒ P0 «src изменён, документация не обновлена» не активируется**; документация
+при этом обновлена сверх минимума.
+
+## Проверки инвариантов (явно)
+
+- `git diff origin/main...HEAD --stat -- 'src/**'` → **пусто** за всю ветку, включая fix-коммит
+  (STAGE_TRANSITIONS / QG_CHECKS / check_* / схема БД — байт-в-байт).
+- `docker.sock` смонтирован `:ro` (compose) И код GET-only по построению (`_get` хардкодит `GET`,
+  ни одного мутирующего метода/`POST`/start/stop/restart/exec) — двойная гарантия read-only (AC-6).
+- Нет импорта `src/**` из `watchdog/**` (`grep` → пусто; C-1 / BR-8) — независимый Telegram-транспорт
+  со своими токенами; падение орка не утянет алерт-канал.
+- never-raise: per-source (коллекторы `_collect_*`), per-tick (`__main__.run` + `core._dispatch`),
+  per-send (`notify`/`_send`) — все три уровня присутствуют (TC-06).
+- kill-switch `WATCHDOG_ENABLED=false` → idle-loop (НЕ exit) — restart-policy не крутит петлю (TC-07).
+- `mem_limit: 128m` + `mem_reservation: 32m`; stdlib-only (нет requirements/pip-дерева) — тонкость
+  C-3 соблюдена; compose-сервис изолирован (деплой watchdog НЕ пересобирает/рестартит `orchestrator`).
+- Анти-дубль диска (D6/AC-5): `host_disk_crit` opt-in (`disk_crit_enabled=False` по умолчанию) на
+  более высоком потолке (97%) — структурно один владелец 85%-события (`disk_watchdog`/ORCH-063).
+
+## Escalation
+
+- Нет открытых эскалаций. Прежняя эскалация ревью v1 / тест-репорта (pre-existing красный тест) —
+  **закрыта** fix-коммитом `2040de3` (test-only изоляция окружения, `src/**` не тронут). Полный
+  регресс `pytest tests/` зелёный (1617 passed) ⇒ downstream merge-gate re-test (ORCH-043) по этой
+  причине более не упрётся. Отдельная баг-задача на `test_finalize_job_requeue_then_fail` **не
+  требуется**: корнем было загрязнение прод-логами, а не дефект `src/**`.

docs/work-items/ORCH-100/13-test-report.md

@@ -0,0 +1,107 @@
+---
+result: PASS   # PASS | FAIL — машинный вердикт, UPPERCASE
+work_item: ORCH-100
+stage: testing
+author_agent: tester
+status: pass
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: test-report
+work_item_id: ORCH-100
+---
+
+# Test Report — ORCH-100 — FND/F1b: sidecar-watchdog (re-test)
+
+> Повторный прогон после цикла `testing → development → review`. Прежний блокер прошлого прогона
+> (`tests/test_queue.py::TestRetry::test_finalize_job_requeue_then_fail`) снят fix-коммитом
+> `2040de3` (test-only autouse-фикстура `_isolate_runs_dir` в `tests/conftest.py`, изолирующая
+> `settings.runs_dir` от ambient prod-log pollution; `src/**` не тронут). Полный регресс снова зелёный.
+
+## Окружение
+- Python: 3.12.13
+- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8)
+- Дата: 2026-06-10
+- Worktree: `/repos/_wt/orchestrator/feature_ORCH-100-fnd-f1b-sidecar-watchdog`
+  (ветка `feature/ORCH-100-fnd-f1b-sidecar-watchdog`, HEAD `a153c8e`, fix `2040de3` в истории) —
+  тесты прогнаны из рабочего дерева именно этой задачи, НЕ из общего `/repos/orchestrator`.
+
+## Smoke API (read-only)
+| Эндпоинт | Результат |
+|----------|-----------|
+| `GET /health` | OK — `{"status":"ok","service":"orchestrator"}` |
+| `GET /status` | OK — валидный JSON, активный набор задач отдан |
+| `GET /queue` | OK — блоки `serial_gate` (ORCH-088) **И** `auto_labels` (ORCH-089) присутствуют в полезной нагрузке (анти-регресс смока соблюдён) |
+
+Smoke зелёный, прод-контейнер не трогался (только чтение).
+
+## Результаты
+
+### Профильная сюита F1b — `tests/watchdog/`
+**66 passed** (0 failed) — собственно поставка F1b: решающая функция, парсинг `/metrics`, детект
+orchestrator-down, never-raise, read-only docker, изолированный транспорт, kill-switch,
+compose-инвариант, анти-дубль диск-алерта.
+
+### Полный регресс орка — `pytest tests/`
+**1617 passed** (0 failed, 1 warning — pre-existing Pydantic V2 deprecation в `src/config.py:8`,
+не относится к ORCH-100). `src/**` не изменён за всю ветку (`git diff origin/main...HEAD -- 'src/**'`
+→ пусто) ⇒ контракт `/metrics` (ORCH-099), `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД — целы.
+
+## Сопоставление с тест-планом (`04-test-plan.yaml`)
+
+| TC ID | Описание | Тест-функция / модуль | Покрытый AC | Результат |
+|-------|----------|------------------------|-------------|-----------|
+| TC-01 | not-alerting & ≥threshold → ALERT (один на пересечение) | `test_decision.py::test_tc01_*` (active + inactive→none) | AC-2 | PASS |
+| TC-02 | alerting & cooldown НЕ истёк → NONE (throttle) | `test_decision.py::test_tc02_alerting_active_in_cooldown_is_none` | AC-2 | PASS |
+| TC-03 | alerting & cooldown истёк → REALERT | `test_decision.py::test_tc03_*` (elapsed + no_last_alert) | AC-2 | PASS |
+| TC-04 | alerting & вернулось ниже порога → RECOVERY | `test_decision.py::test_tc04_alerting_recovers_when_inactive` | AC-2 | PASS |
+| TC-05 | детект orchestrator-down (timeout/refused/5xx/нечит. тело) → ALERT + debounce | `test_orch_down.py` (7 тестов) | AC-2/AC-3 | PASS |
+| TC-06 | never-raise per-source/per-tick/per-send | `test_never_raise.py` (3 теста) | AC-3 | PASS |
+| TC-07 | kill-switch инертен; пороги/интервалы/таймауты из env (не хардкод) | `test_config_killswitch.py` (4 теста) | AC-4 | PASS |
+| TC-08 | интеграция: полный тик при down орке (1 алерт + throttle + recovery; всё ломается — тик не падает) | `test_tick_orch_down_integration.py` (2 теста) | AC-2/AC-3 | PASS |
+| TC-09 | self-hosting safety: docker GET-only, без start/stop/restart/exec | `test_docker_readonly.py` (5 тестов) | AC-6 | PASS |
+| TC-10 | независимый транспорт: свои токен/chat, без импорта `src/notifications.py`/`src` | `test_notify_isolation.py` (6 тестов) | AC-2/AC-6 | PASS |
+| TC-11 | толерантность `/metrics`: неизвестное поле игнор, опц. отсутствие ок, рост schema_version → warning | `test_metrics_parse.py` (10 тестов) | AC-1 | PASS |
+| TC-12 | compose-инвариант: отдельный сервис `orchestrator-watchdog`, build `watchdog/`, restart, mem_limit, docker.sock `:ro` | `test_compose_service.py` (7 тестов) | AC-1/AC-4/AC-6 | PASS |
+| TC-13 | анти-дубль диск-алерта (согласовано с ORCH-063) | `test_disk_alert_dedup.py` (3 теста) | AC-5 | PASS |
+| TC-14 | регресс орка: полный `pytest tests/` зелёный; `src/**` не изменён; `/metrics`-контракт цел | `tests/` (1617 passed) | AC-7 | PASS |
+
+**Покрытие:** все 14 TC из `04-test-plan.yaml` выполнены, сопоставлены с AC-1…AC-7
+(`03-acceptance-criteria.md`) и зелёные.
+
+## Сопоставление с критериями приёмки (`03-acceptance-criteria.md`)
+
+| AC | Покрытие | Результат |
+|----|----------|-----------|
+| AC-1 — sidecar отдельным контейнером собирает 4 источника | TC-11/12 + коллекторы host/deps/docker/metrics | PASS |
+| AC-2 — пороговый алерт: один на пересечение + throttle + recovery + орк-down | TC-01…TC-05/08/10 | PASS |
+| AC-3 — изоляция: падение орка не роняет sidecar | TC-05/06/08 | PASS |
+| AC-4 — тонкость, kill-switch, конфиг-пороги | TC-07/12 | PASS |
+| AC-5 — анти-дубль диск-алерта (ORCH-063) | TC-13 | PASS |
+| AC-6 — self-hosting safety (только чтение/алерт) | TC-09/10/12 | PASS |
+| AC-7 — инфра-доки + `pytest` зелёный + docs/CHANGELOG | `07-infra-requirements.md` ✅, CHANGELOG ✅, доки ✅, полный `pytest tests/` 1617 passed ✅ | PASS |
+
+## Вывод pytest
+
+### Полный регресс (`pytest tests/ -q`)
+```
+........................................................................ [100%]
+1617 passed, 1 warning in 65.33s (0:01:05)
+```
+
+### Профильная сюита (`pytest tests/watchdog/ -v`)
+```
+collected 66 items
+... (все 66 PASSED) ...
+======================== 66 passed, 1 warning in 0.57s =========================
+```
+
+## Эскалация
+Нет открытых эскалаций. Прежний pre-existing красный тест (`test_finalize_job_requeue_then_fail`)
+снят fix-коммитом `2040de3` (изоляция `settings.runs_dir`, test-only, `src/**` не тронут) и
+независимо подтверждён зелёным в этом прогоне. Отдельная баг-задача более не требуется.
+
+## Итог
+**PASS** — полный регресс `pytest tests/` зелёный (1617 passed), профильная сюита sidecar-watchdog
+66/66 PASS, smoke API (`/health`/`/status`/`/queue` с блоками `serial_gate` + `auto_labels`) read-only
+прошёл без регресса. Каждый TC (TC-01…TC-14) выполнен и сопоставлен с AC-1…AC-7. Блокеров нет.
+Задача готова к переходу на `deploy-staging`.

docs/work-items/ORCH-100/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-100
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

docs/work-items/ORCH-100/15-staging-log.md

@@ -0,0 +1,36 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-100
+stage: deploy-staging
+author_agent: deployer
+status: success
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+timestamp: 2026-06-10T06:33:59Z
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log
+
+Staging test suite completed against the live `orchestrator-staging` stand (8501). Canonical
+run **inside** the container (process-env `.env.staging`, so B6 registry-isolation is authoritative).
+Exit code **0** → advance.
+
+All REAL pipeline checks passed; the two sandbox-infra checks (C9a/C9b) failed and were waived
+per ORCH-061 (SANDBOX bot accounts are not members of the sandbox Plane project — not a pipeline
+regression). Trusting the exit code; not re-judging waived checks.
+
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+
+## Results (8/10 PASS; 2 SANDBOX_INFRA waived)
+- **Block A (SMOKE)**: A1 `/health` 200 ok · A2 `/queue` 200 (counts/max_concurrency/resilience) · A3 `ORCH_STAGING=true`. All PASS.
+- **Block B (ACCESS)**: B4 Plane sandbox accessible (sandbox=YES) · B5 Gitea orchestrator-sandbox push=true · B6 registry isolation (sandbox=YES, prod-ET=NO, prod-ORCH=NO). All PASS.
+- **Block C (E2E, mode=stub)**: C7 create issue in Plane SANDBOX PASS · C8 trigger pipeline `/webhook/plane` PASS · C9a branch-in-sandbox FAIL (waived) · C9b analyst-job-enqueued FAIL (waived). CLEANUP: Plane issue deleted (HTTP 204); no branch to delete.
+
+REAL failed: none.
+
+> Note: docker CLI is not installed on the host PATH; the canonical container run was performed via
+> the Docker Engine API over `/var/run/docker.sock` (exec inside `orchestrator-staging`), which is
+> functionally identical to `docker exec` — the script still ran with the container's `.env.staging`
+> process-env, keeping B6 authoritative.

src/agents/launcher.py

@@ -1016,6 +1016,20 @@ class AgentLauncher:
             )
             self._notify_failed(job_id, agent, job, run_id,
                                 f"transient (rate-limit) after {tattempts} attempts")
+            # ORCH-098 (FR-3c / D3): auto-record a `transient_retry` lesson ONLY on
+            # budget EXHAUSTION (not on each backoff — that would be noise; the
+            # valuable signal is "transients exhausted"). best-effort, never-raise,
+            # deduped; can't escape into the queue-worker path.
+            try:
+                from ..lessons import record as record_lesson, LessonType
+                record_lesson(
+                    LessonType.TRANSIENT_RETRY,
+                    task_id=job.get("task_id"), repo=job.get("repo"), agent=agent,
+                    root_cause=f"transient retry budget exhausted ({tattempts}/{tmax})",
+                    detail=err, source="auto",
+                )
+            except Exception as e:  # noqa: BLE001 - never break the queue worker
+                logger.warning(f"Job {job_id}: lessons transient_retry record failed: {e}")
 
     def _finalize_permanent(self, job_id, agent, run_id, exit_code, job):
         """Permanent (code-fault) failure -> normal attempts<max requeue, then fail."""

src/config.py

@@ -291,6 +291,27 @@ class Settings(BaseSettings):
     coverage_tool_fail_closed: bool = False
     coverage_run_timeout_s: int = 900
 
+    # ORCH-098 (FND/F2): machine lessons-journal — additive `lessons` table + leaf
+    # src/lessons.py (never-raise observer, by образцу serial_gate/coverage_gate/
+    # metrics). The journal is an OBSERVER, never a Quality Gate: writing a lesson
+    # never influences any repo's pipeline, so — UNLIKE the gate leaves — it has NO
+    # `*_repos` scope (it records lessons about ANY repo, incl. enduro-trails; the
+    # repo cut lives on the READ side, get(repo=...)). The only regulator is a single
+    # global kill-switch (ADR-001 D2). See ADR-001-lessons-journal.md / adr-0033.
+    #   lessons_enabled            -> SINGLE kill-switch (env ORCH_LESSONS_ENABLED).
+    #                                 False -> record/get/update/snapshot inert (no DB
+    #                                 access), endpoints return {"enabled": false},
+    #                                 auto-record injections no-op. Default True.
+    #   lessons_query_limit_default-> default LIMIT for GET /lessons / get() when the
+    #                                 caller passes none.
+    #   lessons_dedup_window_s     -> auto-record dedup window (s): a second auto lesson
+    #                                 with the same (work_item_id, lesson_type, stage)
+    #                                 inside this window is suppressed (D4). manual
+    #                                 records are never deduped. Default 3600 (1h).
+    lessons_enabled: bool = True
+    lessons_query_limit_default: int = 100
+    lessons_dedup_window_s: int = 3600
+
     # ORCH-057: legacy root-owned file ownership detect + actionable worktree error
     # (follow-up ORCH-040). Three additive, kill-switch-reversible layers: (1) an
     # actionable RuntimeError in git_worktree.ensure_worktree when a worktree fails

src/db.py

@@ -220,10 +220,195 @@ def init_db():
             updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
         );
     """)
+    # ORCH-098 (FR-1, ADR-001 D1): additive machine lessons-journal — a structured
+    # table of pipeline deviations (gate-fail / merge-hold / transient-retry /
+    # post-deploy-degraded), the foundation of the self-improvement epic (E2
+    # retrospective / E3 RICE prioritiser). Purely ADDITIVE (CREATE TABLE/INDEX IF NOT
+    # EXISTS, pattern repo_freeze/coverage_baseline) -> idempotent, restart-safe on
+    # the shared prod DB; existing tables untouched (NFR-3, enduro-trails not
+    # affected). The attribution columns (attribution/target_repo/target_domain) are
+    # NULLABLE and present FROM THE START (Слава 10.06, NFR-6) so the live shared DB
+    # never needs a schema rework — an auto-recorded `unknown` lesson is classified
+    # later via update. lesson_type / attribution / target_domain carry NO enum/CHECK
+    # constraint: the values are a forward-compatible slug convention (a new lesson
+    # type never needs a migration). See docs/work-items/ORCH-098/08-data-requirements.md.
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS lessons (
+            id            INTEGER PRIMARY KEY AUTOINCREMENT,
+            created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+            updated_at    TEXT,
+            lesson_type   TEXT NOT NULL,
+            work_item_id  TEXT,
+            task_id       INTEGER,
+            stage         TEXT,
+            agent         TEXT,
+            repo          TEXT,
+            root_cause    TEXT,
+            suggestion    TEXT,
+            status        TEXT NOT NULL DEFAULT 'new',
+            related_task  TEXT,
+            attribution   TEXT,
+            target_repo   TEXT,
+            target_domain TEXT,
+            source        TEXT,
+            detail        TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_lessons_type_status ON lessons (lesson_type, status);
+        CREATE INDEX IF NOT EXISTS idx_lessons_repo        ON lessons (repo);
+        CREATE INDEX IF NOT EXISTS idx_lessons_wi_type     ON lessons (work_item_id, lesson_type);
+    """)
+    # Forward-safe: on an already-created `lessons` table the attribution columns are
+    # added idempotently (_ensure_column is a no-op once present) so an old prod DB
+    # picks them up without a data migration (NFR-6, AC-2).
+    _ensure_column(conn, "lessons", "attribution", "TEXT")
+    _ensure_column(conn, "lessons", "target_repo", "TEXT")
+    _ensure_column(conn, "lessons", "target_domain", "TEXT")
     conn.commit()
     conn.close()
 
 
+# ---------------------------------------------------------------------------
+# ORCH-098 (FR-1..FR-5, ADR-001 D1): lessons-journal DDL helpers. Each opens its
+# own connection and closes it in `finally` (pattern coverage_baseline). The leaf
+# src/lessons.py wraps these in its never-raise contract — these may raise on a
+# real DB fault (the leaf swallows it).
+# ---------------------------------------------------------------------------
+# The full column set, in INSERT order. Single source of truth so record/get stay
+# in lockstep with the schema.
+_LESSON_COLUMNS = (
+    "lesson_type", "work_item_id", "task_id", "stage", "agent", "repo",
+    "root_cause", "suggestion", "status", "related_task",
+    "attribution", "target_repo", "target_domain", "source", "detail",
+)
+# Fields an update() may set (everything mutable; never id/created_at/lesson_type).
+_LESSON_UPDATABLE = (
+    "status", "attribution", "target_repo", "target_domain", "related_task",
+    "root_cause", "suggestion", "stage", "agent", "repo", "detail",
+)
+
+
+def record_lesson(**fields) -> int:
+    """Insert one lessons row; return the new id. Raises only on a real DB fault.
+
+    Only the known columns in ``_LESSON_COLUMNS`` are written; unknown keys are
+    ignored (forward-safe). ``created_at`` is stamped by the table default.
+    """
+    cols = [c for c in _LESSON_COLUMNS if c in fields]
+    if "lesson_type" not in cols:
+        raise ValueError("record_lesson requires lesson_type")
+    placeholders = ", ".join("?" for _ in cols)
+    sql = f"INSERT INTO lessons ({', '.join(cols)}) VALUES ({placeholders})"
+    conn = get_db()
+    try:
+        cur = conn.execute(sql, tuple(fields[c] for c in cols))
+        conn.commit()
+        return int(cur.lastrowid)
+    finally:
+        conn.close()
+
+
+def lessons_recent_dup_exists(work_item_id, lesson_type, stage, window_s: int) -> bool:
+    """ORCH-098 (D4): is there an auto-lesson with the same (work_item_id,
+    lesson_type, stage) within the last ``window_s`` seconds? One indexed lookup on
+    ``idx_lessons_wi_type``. Used to suppress duplicate auto-records on retries.
+    """
+    conn = get_db()
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM lessons "
+            "WHERE work_item_id IS ? AND lesson_type = ? AND stage IS ? "
+            "AND source = 'auto' "
+            "AND created_at > datetime('now', ?) LIMIT 1",
+            (work_item_id, lesson_type, stage, f"-{int(window_s)} seconds"),
+        ).fetchone()
+    finally:
+        conn.close()
+    return row is not None
+
+
+def get_lessons(*, lesson_type=None, status=None, repo=None, work_item_id=None,
+                limit: int = 100) -> list[dict]:
+    """Read-only parametrised SELECT of lessons (ORDER BY id DESC LIMIT ?)."""
+    where = []
+    params: list = []
+    if lesson_type:
+        where.append("lesson_type = ?")
+        params.append(lesson_type)
+    if status:
+        where.append("status = ?")
+        params.append(status)
+    if repo:
+        where.append("repo = ?")
+        params.append(repo)
+    if work_item_id:
+        where.append("work_item_id = ?")
+        params.append(work_item_id)
+    sql = "SELECT * FROM lessons"
+    if where:
+        sql += " WHERE " + " AND ".join(where)
+    sql += " ORDER BY id DESC LIMIT ?"
+    try:
+        lim = int(limit)
+    except (TypeError, ValueError):
+        lim = 100
+    params.append(max(1, lim))
+    conn = get_db()
+    try:
+        rows = conn.execute(sql, tuple(params)).fetchall()
+    finally:
+        conn.close()
+    return [dict(r) for r in rows]
+
+
+def update_lesson(lesson_id: int, **fields) -> bool:
+    """Update mutable fields of a lesson + stamp updated_at. Returns True iff a row
+    changed. Unknown / non-updatable keys are ignored (forward-safe).
+    """
+    sets = [c for c in _LESSON_UPDATABLE if c in fields]
+    if not sets:
+        return False
+    assignments = ", ".join(f"{c} = ?" for c in sets)
+    sql = f"UPDATE lessons SET {assignments}, updated_at = datetime('now') WHERE id = ?"
+    conn = get_db()
+    try:
+        cur = conn.execute(sql, tuple(fields[c] for c in sets) + (int(lesson_id),))
+        conn.commit()
+        return (cur.rowcount or 0) > 0
+    finally:
+        conn.close()
+
+
+def lessons_snapshot(recent: int = 10) -> dict:
+    """Light GROUP BY summary (counts by type/status) + the last N lessons, for the
+    GET /queue observability block."""
+    conn = get_db()
+    try:
+        total = conn.execute("SELECT COUNT(*) FROM lessons").fetchone()[0]
+        by_type = {
+            r["lesson_type"]: r["n"]
+            for r in conn.execute(
+                "SELECT lesson_type, COUNT(*) AS n FROM lessons GROUP BY lesson_type"
+            ).fetchall()
+        }
+        by_status = {
+            r["status"]: r["n"]
+            for r in conn.execute(
+                "SELECT status, COUNT(*) AS n FROM lessons GROUP BY status"
+            ).fetchall()
+        }
+        rows = conn.execute(
+            "SELECT * FROM lessons ORDER BY id DESC LIMIT ?", (max(1, int(recent)),)
+        ).fetchall()
+    finally:
+        conn.close()
+    return {
+        "total": total,
+        "by_type": by_type,
+        "by_status": by_status,
+        "recent": [dict(r) for r in rows],
+    }
+
+
 def get_coverage_baseline(repo: str) -> float | None:
     """ORCH-027: read the per-repo coverage baseline (%, line coverage).
 

src/lessons.py

@@ -0,0 +1,191 @@
+"""ORCH-098 (FND/F2): machine lessons-journal — a never-raise observer leaf.
+
+Background
+----------
+The orchestrator runs an autonomous pipeline; when it deviates (a quality gate
+rolls a task back, a merge is held, a transient burst exhausts the retry budget,
+a post-deploy verdict comes back DEGRADED) the only trace today is free-text in
+``memory/`` — not machine-readable, so nothing can count the patterns or
+prioritise the fixes. ORCH-098 is step 1 («Фундамент», F2) of the
+self-improvement epic: it formalises those deviations into a structured
+``lessons`` table on which the future retrospective agent (E2), the RICE
+prioritiser (E3) and Стрим will stand.
+
+Design (ADR-001, by образцу ``serial_gate`` / ``coverage_gate`` / ``metrics``)
+------------------------------------------------------------------------------
+This is a **leaf**: it imports only ``config`` + ``db`` (lazily). It NEVER imports
+``stage_engine`` / ``merge_gate`` / ``launcher`` (anti-cycle) — those choke-points
+call INTO this module, never the reverse.
+
+Two contract invariants, both load-bearing on the shared self-hosting prod DB:
+
+  * **kill-switch** (FR-6 / AC-7): ``lessons_enabled=False`` -> every public
+    function is an immediate no-op (``record→None``, ``get→[]``, ``update→False``,
+    ``snapshot→{}``) WITHOUT touching the DB; the auto-record injections become
+    no-ops; pipeline behaviour is byte-for-byte the pre-ORCH-098 behaviour.
+  * **never-raise** (NFR-1 / AC-6): with the switch on, every body runs under
+    ``try/except Exception -> logger.warning + safe default``. A journal fault
+    (a failing DB, a bad row) can NEVER propagate into the hot path that called it
+    (a rollback / HOLD / retry must complete regardless).
+
+**No repo scope (D2).** Unlike the gate leaves (``serial_gate`` / ``coverage_gate``
+/ ``bug_fast_track`` carry a ``*_repos`` CSV because they *act* on a repo), the
+journal is observer-only: writing a row never influences any repo's pipeline.
+So it records lessons about ANY repo — including enduro-trails (a degraded enduro
+deploy is a valuable self-learning signal; a repo scope would drop it). The
+repo cut lives on the READ side (``get(repo=...)`` / ``snapshot``). enduro is not
+affected (NFR-3): an observer row about enduro changes no enduro stage/gate.
+
+Self-hosting safety (NFR-7): the journal only reads/writes its own table. It never
+deploys, never restarts prod, never touches ``main``, spawns no process, opens no
+socket.
+"""
+from __future__ import annotations
+
+import logging
+
+from .config import settings
+
+logger = logging.getLogger("orchestrator.lessons")
+
+
+# ---------------------------------------------------------------------------
+# Slug conventions (NOT enum constraints — forward-compatible string slugs, D1).
+# Exposed as constants so the choke-point injections and tests share one spelling.
+# ---------------------------------------------------------------------------
+class LessonType:
+    """Canonical ``lesson_type`` slugs written by the auto-detectors (D3)."""
+    GATE_FAILURE = "gate_failure"        # QG rollback to development
+    MERGE_HOLD = "merge_hold"            # merge not verified -> task held on deploy
+    TRANSIENT_RETRY = "transient_retry"  # transient retry budget exhausted
+    DEPLOY_DEGRADED = "deploy_degraded"  # post-deploy DEGRADED -> repo freeze
+
+
+class Attribution:
+    """``attribution`` slugs (who a lesson is about — filled in later by a human /
+    the retrospective agent; auto-records leave it NULL or ``unknown``)."""
+    PLATFORM = "platform"
+    PROJECT = "project"
+    BOTH = "both"
+    UNKNOWN = "unknown"
+
+
+class Domain:
+    """``target_domain`` slugs (which improvement axis a lesson touches)."""
+    RELIABILITY = "reliability"
+    QUALITY = "quality"
+    ECONOMY = "economy"
+    FEATURES = "features"
+    SCALE = "scale"
+
+
+class Status:
+    """``status`` lifecycle slugs."""
+    NEW = "new"
+    IN_PROGRESS = "in_progress"
+    CLOSED = "closed"
+    LINKED = "linked"
+
+
+def _enabled() -> bool:
+    """Read the kill-switch; never raises (a config read fault -> treated as off)."""
+    try:
+        return bool(settings.lessons_enabled)
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.warning("lessons: kill-switch read error: %s", e)
+        return False
+
+
+def record(lesson_type, *, work_item_id=None, task_id=None, stage=None, agent=None,
+           repo=None, root_cause=None, suggestion=None, status="new", related_task=None,
+           attribution=None, target_repo=None, target_domain=None, source="auto",
+           detail=None) -> int | None:
+    """Record one lesson; return its new id, or ``None`` (no-op / error / deduped).
+
+    * Kill-switch off -> immediate ``None`` WITHOUT a DB access (FR-6 / AC-7).
+    * ``source="auto"`` records are DEDUPED (D4): a prior auto-lesson with the same
+      ``(work_item_id, lesson_type, stage)`` within ``lessons_dedup_window_s`` ->
+      ``None`` (so transient retry-storms / repeated rollbacks don't flood the
+      table). ``source="manual"`` is NEVER deduped (the operator / Стрим can always
+      write).
+    * never-raise (NFR-1 / AC-6): any DB / internal error -> ``logger.warning`` +
+      ``None``; the caller (a hot-path rollback / HOLD / retry) is untouched.
+    """
+    if not _enabled():
+        return None
+    if not lesson_type:
+        return None
+    try:
+        from . import db
+        if source == "auto":
+            try:
+                window = int(getattr(settings, "lessons_dedup_window_s", 3600) or 0)
+            except (TypeError, ValueError):
+                window = 3600
+            if window > 0 and db.lessons_recent_dup_exists(
+                work_item_id, lesson_type, stage, window
+            ):
+                logger.debug(
+                    "lessons: deduped auto %s for %s/%s (within %ss window)",
+                    lesson_type, work_item_id, stage, window,
+                )
+                return None
+        return db.record_lesson(
+            lesson_type=lesson_type, work_item_id=work_item_id, task_id=task_id,
+            stage=stage, agent=agent, repo=repo, root_cause=root_cause,
+            suggestion=suggestion, status=status, related_task=related_task,
+            attribution=attribution, target_repo=target_repo,
+            target_domain=target_domain, source=source, detail=detail,
+        )
+    except Exception as e:  # noqa: BLE001 - never-raise contract (NFR-1 / AC-6)
+        logger.warning("lessons.record(%s) error: %s", lesson_type, e)
+        return None
+
+
+def get(*, lesson_type=None, status=None, repo=None, work_item_id=None,
+        limit=None) -> list[dict]:
+    """Read-only fetch of lessons (newest first). never-raise -> ``[]`` on error /
+    when the kill-switch is off."""
+    if not _enabled():
+        return []
+    try:
+        if limit is None:
+            limit = getattr(settings, "lessons_query_limit_default", 100)
+        from . import db
+        return db.get_lessons(
+            lesson_type=lesson_type, status=status, repo=repo,
+            work_item_id=work_item_id, limit=limit,
+        )
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.warning("lessons.get error: %s", e)
+        return []
+
+
+def update(lesson_id, **fields) -> bool:
+    """Re-classify / re-status an existing lesson (status / attribution / target_* /
+    related_task / root_cause / suggestion). Stamps ``updated_at``. never-raise ->
+    ``False`` on error / kill-switch off."""
+    if not _enabled():
+        return False
+    try:
+        from . import db
+        return db.update_lesson(lesson_id, **fields)
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.warning("lessons.update(%s) error: %s", lesson_id, e)
+        return False
+
+
+def snapshot() -> dict:
+    """Light read-only summary for the GET /queue ``lessons`` block. never-raise ->
+    a minimal dict (``{"enabled": False}`` when off / ``{"enabled": True}`` on
+    error)."""
+    if not _enabled():
+        return {"enabled": False}
+    try:
+        from . import db
+        out = {"enabled": True}
+        out.update(db.lessons_snapshot())
+        return out
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.warning("lessons.snapshot error: %s", e)
+        return {"enabled": True}

src/main.py

@@ -1,4 +1,4 @@
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from contextlib import asynccontextmanager
 import logging
 from .db import init_db
@@ -213,6 +213,7 @@ async def queue():
     from . import labels
     from . import cancel
     from . import bug_fast_track
+    from . import lessons
     from .disk_watchdog import disk_watchdog
     from .build_cache_pruner import build_cache_pruner
     return {
@@ -248,6 +249,10 @@ async def queue():
         # kill-switch, label, scope, bug-task counts + the structural savings metric
         # (architecture stages skipped). Additive block; never-raise.
         "bug_fast_track": bug_fast_track.snapshot(),
+        # ORCH-098 (FR-4 / AC-4): lessons-journal observability (read-only) —
+        # kill-switch + counts by type/status + last N lessons. Additive block;
+        # never-raise (snapshot() returns {"enabled": ...} minimum on error).
+        "lessons": lessons.snapshot(),
         # ORCH-063 (FR-6 / AC-7): disk-watchdog observability (read-only) —
         # enabled, threshold, interval, last measurement per host-path. Additive
         # block; never-raise (status() returns {"enabled": ...} minimum on error).
@@ -390,3 +395,82 @@ async def bug_fast_track_escalate(work_item: str = ""):
         except Exception:
             pass
     return {"ok": True, "work_item": work_item, "track": "full", "was": prev_track}
+
+
+# ---------------------------------------------------------------------------
+# ORCH-098 (FR-4 / FR-5, ADR-001 D5): machine lessons-journal endpoints.
+# Read-only fetch + manual record + re-classify. All never-raise; with the
+# kill-switch off they return {"enabled": false} (style of /metrics, AC-7).
+# ---------------------------------------------------------------------------
+@app.get("/lessons")
+async def lessons_list(
+    type: str = "", status: str = "", repo: str = "", work_item: str = "",
+    limit: int | None = None,
+):
+    """ORCH-098: read-only lessons fetch with optional filters (type / status / repo
+    / work_item / limit). Always 200; reading never mutates. ``lessons_enabled=False``
+    -> ``{"enabled": false}``."""
+    from . import lessons
+    from .config import settings
+    if not getattr(settings, "lessons_enabled", True):
+        return {"enabled": False, "lessons": []}
+    rows = lessons.get(
+        lesson_type=(type or None), status=(status or None), repo=(repo or None),
+        work_item_id=(work_item or None), limit=limit,
+    )
+    return {"enabled": True, "lessons": rows}
+
+
+@app.post("/lessons")
+async def lessons_create(request: Request):
+    """ORCH-098: manually record a lesson (``source="manual"``, never deduped). JSON
+    body: ``lesson_type`` (required) + optional context / analysis / attribution
+    fields. Returns ``{"id": <int>}`` or ``{"enabled": false}`` /
+    ``{"error": ...}``."""
+    from . import lessons
+    from .config import settings
+    if not getattr(settings, "lessons_enabled", True):
+        return {"enabled": False}
+    try:
+        body = await request.json()
+    except Exception:  # noqa: BLE001 - malformed body
+        body = {}
+    if not isinstance(body, dict):
+        body = {}
+    lesson_type = body.get("lesson_type")
+    if not lesson_type:
+        return {"ok": False, "error": "missing 'lesson_type'"}
+    # Only forward known fields; source is forced to "manual" (operator/Стрим).
+    allowed = (
+        "work_item_id", "task_id", "stage", "agent", "repo", "root_cause",
+        "suggestion", "status", "related_task", "attribution", "target_repo",
+        "target_domain", "detail",
+    )
+    kwargs = {k: body[k] for k in allowed if k in body}
+    new_id = lessons.record(lesson_type, source="manual", **kwargs)
+    return {"id": new_id}
+
+
+@app.post("/lessons/{lesson_id}")
+async def lessons_update(lesson_id: int, request: Request):
+    """ORCH-098: re-classify / re-status an existing lesson (status / attribution /
+    target_* / related_task / root_cause / suggestion). Lets a human / the
+    retrospective agent classify an auto-recorded ``unknown``. Returns
+    ``{"ok": bool}`` or ``{"enabled": false}``."""
+    from . import lessons
+    from .config import settings
+    if not getattr(settings, "lessons_enabled", True):
+        return {"enabled": False}
+    try:
+        body = await request.json()
+    except Exception:  # noqa: BLE001 - malformed body
+        body = {}
+    if not isinstance(body, dict):
+        body = {}
+    allowed = (
+        "status", "attribution", "target_repo", "target_domain", "related_task",
+        "root_cause", "suggestion", "stage", "agent", "repo", "detail",
+    )
+    kwargs = {k: body[k] for k in allowed if k in body}
+    ok = lessons.update(lesson_id, **kwargs)
+    return {"ok": ok}

src/stage_engine.py

@@ -927,6 +927,24 @@ def _handle_qg_failure_rollbacks(
             f"development ({reason})"
         )
 
+    # ORCH-098 (FR-3a / D3): machine lessons-journal — auto-record a `gate_failure`
+    # lesson whenever a quality gate rolled this task back to `development`
+    # (reviewer REQUEST_CHANGES / tester FAIL / staging FAILED / deploy FAILED — all
+    # four branches above set result.rolled_back_to="development"). One best-effort
+    # call covers every rollback branch; lessons.record is never-raise + deduped, and
+    # this guard ensures even an import fault can't escape into the hot rollback path.
+    if result.rolled_back_to == "development":
+        try:
+            from . import lessons
+            lessons.record(
+                lessons.LessonType.GATE_FAILURE,
+                work_item_id=work_item_id, task_id=task_id, stage=current_stage,
+                agent=agent, repo=repo, root_cause=reason, detail=qg_name,
+                source="auto",
+            )
+        except Exception as e:  # noqa: BLE001 - never break the rollback path
+            logger.warning(f"Task {task_id}: lessons gate_failure record failed: {e}")
+
 
 # ---------------------------------------------------------------------------
 # ORCH-043: merge-gate sub-gate on the deploy-staging -> deploy edge
@@ -1726,6 +1744,19 @@ def _handle_merge_verify(task_id, repo, work_item_id, branch, result: AdvanceRes
         result.alerted = True
         result.note = "merge-not-verified-hold"
         result.advanced = False
+        # ORCH-098 (FR-3b / D3): auto-record a `merge_hold` lesson — deploy succeeded
+        # but `main` never got the commit, so the task is held on `deploy` (not done).
+        # best-effort, never-raise, deduped; can't escape into the HOLD path.
+        try:
+            from . import lessons
+            lessons.record(
+                lessons.LessonType.MERGE_HOLD,
+                work_item_id=work_item_id, task_id=task_id, stage="deploy",
+                repo=repo, root_cause="merge-not-verified-hold", detail=merge_msg,
+                source="auto",
+            )
+        except Exception as e:  # noqa: BLE001 - never break the HOLD
+            logger.warning(f"Task {task_id}: lessons merge_hold record failed: {e}")
         return True
     except Exception as e:  # noqa: BLE001 - never-raise contract (INV-1/AC-7)
         # Any internal error -> treat as "not confirmed" -> HOLD + alert, never crash.
@@ -2009,6 +2040,24 @@ def run_post_deploy_monitor(job: dict):
     except Exception as e:  # noqa: BLE001 - never break the tick
         logger.warning(f"post-deploy: set_repo_freeze failed for {repo}: {e}")
 
+    # ORCH-098 (FR-3d / D3): auto-record a `deploy_degraded` lesson — "deploy OK /
+    # prod broken" (layer-3, ET-8). attribution left "unknown" + target_domain
+    # "reliability" for a human / the retrospective agent to classify later (this is
+    # exactly the signal Слава required the attribution columns for). best-effort,
+    # never-raise; can't escape into the monitor tick.
+    try:
+        from . import lessons
+        reason = f"post-deploy DEGRADED ({checks_failed}/{checks_total})"
+        lessons.record(
+            lessons.LessonType.DEPLOY_DEGRADED,
+            work_item_id=work_item_id, repo=repo, stage="deploy",
+            root_cause=reason, attribution=lessons.Attribution.UNKNOWN,
+            target_repo=repo, target_domain=lessons.Domain.RELIABILITY,
+            source="auto",
+        )
+    except Exception as e:  # noqa: BLE001 - never break the tick
+        logger.warning(f"post-deploy: lessons deploy_degraded record failed for {repo}: {e}")
+
     post_deploy.write_post_deploy_log(
         repo, work_item_id, branch, post_deploy.DEGRADED, action_taken,
         settings.post_deploy_window_s, checks_total, checks_failed,

tests/conftest.py

@@ -77,6 +77,34 @@ def _reset_webhook_secrets(monkeypatch):
     yield
 
 
+@pytest.fixture(autouse=True)
+def _isolate_runs_dir(monkeypatch, tmp_path):
+    """ORCH-100: point settings.runs_dir at a per-test tmp dir in ALL tests.
+
+    Background: ``launcher._run_log_path(run_id)`` resolves to
+    ``<settings.runs_dir>/<run_id>.log`` and, on a non-zero exit,
+    ``_finalize_job`` classifies the failure by reading the *tail of that log*
+    (transient 429/overload/timeout -> backoff-requeue; permanent -> attempts
+    requeue then 'failed'). settings.runs_dir defaults to the live prod dir
+    ``/app/data/runs``, which on the self-hosting host holds REAL accumulated
+    agent logs (1.log, 2.log, ...). Tests that exercise the finalize path with a
+    small literal run_id (e.g. test_finalize_job_requeue_then_fail uses run_id=1/2)
+    therefore read whatever a real prod run happened to log — and a real 2.log that
+    contains "429" silently flips an expected 'permanent' classification to
+    'transient', requeueing instead of failing. That is ambient prod pollution, not
+    a code fault.
+
+    Redirecting runs_dir to an empty tmp dir makes _run_log_path() resolve to a
+    non-existent file -> classify_log_file() returns the documented 'permanent'
+    default, restoring deterministic, environment-independent behaviour for the
+    whole suite. settings is a process-wide singleton shared by launcher
+    (``launcher.settings is config.settings``), so patching the source covers it.
+    """
+    from src import config as _cfg
+    monkeypatch.setattr(_cfg.settings, "runs_dir", str(tmp_path), raising=False)
+    yield
+
+
 @pytest.fixture(autouse=True)
 def _disable_merge_verify(monkeypatch):
     """ORCH-071: disable the merge-verify under-gate by default in ALL tests.

tests/test_lessons.py

@@ -0,0 +1,396 @@
+"""ORCH-098 / TC-01..TC-12: the machine lessons-journal (src/lessons.py + db + wiring).
+
+Contract under test (ADR-001 §7 / acceptance-criteria):
+  * the `lessons` table is additive + idempotent and carries the NULLABLE
+    attribution columns (attribution / target_repo / target_domain) from the start;
+  * record() inserts a row (auto/manual) and returns its id; auto records are
+    deduped in a window, manual records are never deduped;
+  * never-raise: a failing DB -> None/[]/{}/False, never an exception into the caller;
+  * kill-switch off -> record/get/update/snapshot inert (no DB access);
+  * get_lessons filters by type/status/repo/work_item + LIMIT + ORDER BY id DESC;
+  * update_lesson mutates fields + stamps updated_at; unknown id is safe;
+  * auto-record wiring: a QG rollback to development writes a `gate_failure` lesson;
+    a launcher transient-budget-exhaustion writes a `transient_retry` lesson; a
+    failing journal never breaks the hot path;
+  * the HTTP endpoints (GET /lessons, POST /lessons, POST /lessons/{id}) and the
+    GET /queue `lessons` block behave + honour the kill-switch;
+  * pipeline invariants (STAGE_TRANSITIONS / QG_CHECKS) are structurally untouched.
+"""
+import os
+import tempfile
+
+os.environ["ORCH_DB_PATH"] = os.path.join(tempfile.gettempdir(), "test_lessons.db")
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+
+import pytest  # noqa: E402
+
+import src.db as db  # noqa: E402
+from src import config as cfg  # noqa: E402
+from src import lessons  # noqa: E402
+
+_REPO = "orchestrator"
+_WI = "ORCH-098"
+
+
+@pytest.fixture(autouse=True)
+def fresh_db(tmp_path, monkeypatch):
+    """Isolated tmp SQLite DB + journal ON by default."""
+    dbfile = tmp_path / "lessons.db"
+    monkeypatch.setattr(db.settings, "db_path", str(dbfile))
+    monkeypatch.setattr(cfg.settings, "lessons_enabled", True, raising=False)
+    monkeypatch.setattr(cfg.settings, "lessons_query_limit_default", 100, raising=False)
+    monkeypatch.setattr(cfg.settings, "lessons_dedup_window_s", 3600, raising=False)
+    db.init_db()
+    yield
+
+
+def _columns():
+    conn = db.get_db()
+    try:
+        return {r[1] for r in conn.execute("PRAGMA table_info(lessons)").fetchall()}
+    finally:
+        conn.close()
+
+
+# ===========================================================================
+# TC-01 — additive + idempotent table with all BR-1 fields
+# ===========================================================================
+def test_tc01_table_idempotent_and_fields():
+    # Double init must not raise nor duplicate.
+    db.init_db()
+    db.init_db()
+    cols = _columns()
+    for f in (
+        "id", "created_at", "updated_at", "lesson_type", "work_item_id", "task_id",
+        "stage", "agent", "repo", "root_cause", "suggestion", "status", "related_task",
+    ):
+        assert f in cols, f"missing column {f}"
+    # No existing table mutated: tasks/jobs still present and unchanged in shape.
+    conn = db.get_db()
+    try:
+        tabs = {
+            r[0] for r in conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table'"
+            ).fetchall()
+        }
+    finally:
+        conn.close()
+    assert {"tasks", "jobs", "agent_runs", "lessons"} <= tabs
+
+
+# ===========================================================================
+# TC-02 — attribution columns present from the start, nullable, set later
+# ===========================================================================
+def test_tc02_attribution_columns_nullable_and_settable():
+    cols = _columns()
+    assert {"attribution", "target_repo", "target_domain"} <= cols
+    # A record WITHOUT attribution is accepted (NULL).
+    lid = lessons.record(lessons.LessonType.DEPLOY_DEGRADED, work_item_id=_WI, repo=_REPO)
+    assert lid is not None
+    rows = lessons.get(work_item_id=_WI)
+    assert rows[0]["attribution"] is None
+    # Attribution can be filled in later via update.
+    assert lessons.update(
+        lid, attribution=lessons.Attribution.PLATFORM,
+        target_repo=_REPO, target_domain=lessons.Domain.RELIABILITY,
+    ) is True
+    rows = lessons.get(work_item_id=_WI)
+    assert rows[0]["attribution"] == "platform"
+    assert rows[0]["target_domain"] == "reliability"
+
+
+# ===========================================================================
+# TC-03 — record() inserts and returns id, created_at filled, source honoured
+# ===========================================================================
+def test_tc03_record_inserts_and_returns_id():
+    lid = lessons.record(
+        lessons.LessonType.GATE_FAILURE, work_item_id=_WI, task_id=7, stage="review",
+        agent="reviewer", repo=_REPO, root_cause="REQUEST_CHANGES", source="auto",
+    )
+    assert isinstance(lid, int) and lid > 0
+    rows = lessons.get(work_item_id=_WI)
+    assert len(rows) == 1
+    r = rows[0]
+    assert r["lesson_type"] == "gate_failure"
+    assert r["task_id"] == 7
+    assert r["agent"] == "reviewer"
+    assert r["source"] == "auto"
+    assert r["status"] == "new"
+    assert r["created_at"]
+    # A manual record with a different (work_item, type) -> distinct row.
+    lid2 = lessons.record("custom_manual", work_item_id="ORCH-1", source="manual")
+    assert lid2 is not None and lid2 != lid
+
+
+# ===========================================================================
+# TC-04 — never-raise: a failing DB -> safe defaults, no exception
+# ===========================================================================
+def test_tc04_never_raise_on_db_error(monkeypatch):
+    def boom(*a, **k):
+        raise RuntimeError("db down")
+
+    monkeypatch.setattr(db, "record_lesson", boom)
+    monkeypatch.setattr(db, "lessons_recent_dup_exists", lambda *a, **k: False)
+    monkeypatch.setattr(db, "get_lessons", boom)
+    monkeypatch.setattr(db, "update_lesson", boom)
+    monkeypatch.setattr(db, "lessons_snapshot", boom)
+
+    assert lessons.record("gate_failure", work_item_id=_WI) is None
+    assert lessons.get(work_item_id=_WI) == []
+    assert lessons.update(1, status="closed") is False
+    snap = lessons.snapshot()
+    assert snap == {"enabled": True}  # never-raise -> minimal dict, no exception
+
+
+# ===========================================================================
+# TC-05 — kill-switch: lessons_enabled=False -> inert, no DB access
+# ===========================================================================
+def test_tc05_kill_switch_inert(monkeypatch):
+    monkeypatch.setattr(cfg.settings, "lessons_enabled", False, raising=False)
+
+    def fail(*a, **k):
+        raise AssertionError("DB must NOT be touched when kill-switch is off")
+
+    monkeypatch.setattr(db, "record_lesson", fail)
+    monkeypatch.setattr(db, "get_lessons", fail)
+    monkeypatch.setattr(db, "update_lesson", fail)
+    monkeypatch.setattr(db, "lessons_snapshot", fail)
+
+    assert lessons.record("gate_failure", work_item_id=_WI) is None
+    assert lessons.get(work_item_id=_WI) == []
+    assert lessons.update(1, status="closed") is False
+    assert lessons.snapshot() == {"enabled": False}
+
+
+# ===========================================================================
+# TC-06 — get_lessons filters + limit + ORDER BY id DESC
+# ===========================================================================
+def test_tc06_filters_limit_order():
+    # Seed rows directly via the DB helper (bypasses the leaf's auto-dedup).
+    for i in range(5):
+        db.record_lesson(
+            lesson_type="gate_failure", work_item_id=f"ORCH-{i}", repo=_REPO,
+            status="new", source="auto",
+        )
+    db.record_lesson(lesson_type="merge_hold", work_item_id="ORCH-X", repo="enduro-trails",
+                     status="closed", source="auto")
+
+    # Filter by type.
+    gf = db.get_lessons(lesson_type="gate_failure")
+    assert len(gf) == 5 and all(r["lesson_type"] == "gate_failure" for r in gf)
+    # Filter by status.
+    assert len(db.get_lessons(status="closed")) == 1
+    # Filter by repo.
+    assert len(db.get_lessons(repo="enduro-trails")) == 1
+    # Filter by work_item.
+    assert len(db.get_lessons(work_item_id="ORCH-3")) == 1
+    # LIMIT.
+    assert len(db.get_lessons(lesson_type="gate_failure", limit=2)) == 2
+    # ORDER BY id DESC (newest first).
+    allr = db.get_lessons(limit=100)
+    got_ids = [r["id"] for r in allr]
+    assert got_ids == sorted(got_ids, reverse=True)
+
+
+# ===========================================================================
+# TC-07 — update_lesson mutates + stamps updated_at; unknown id safe
+# ===========================================================================
+def test_tc07_update_and_unknown_id():
+    lid = db.record_lesson(lesson_type="deploy_degraded", work_item_id=_WI, repo=_REPO,
+                           status="new", source="auto")
+    before = db.get_lessons(work_item_id=_WI)[0]
+    assert before["updated_at"] is None
+    ok = db.update_lesson(
+        lid, status="in_progress", attribution="both", target_repo=_REPO,
+        target_domain="reliability", related_task="ORCH-200",
+    )
+    assert ok is True
+    after = db.get_lessons(work_item_id=_WI)[0]
+    assert after["status"] == "in_progress"
+    assert after["attribution"] == "both"
+    assert after["related_task"] == "ORCH-200"
+    assert after["updated_at"] is not None
+    # Unknown id -> no row changed, no raise.
+    assert db.update_lesson(999999, status="closed") is False
+    # Empty update (no recognised fields) -> False, safe.
+    assert db.update_lesson(lid) is False
+
+
+# ===========================================================================
+# TC-07b — auto dedup vs manual always-writes (D4)
+# ===========================================================================
+def test_tc07b_auto_dedup_and_manual_passthrough():
+    a = lessons.record("transient_retry", work_item_id=_WI, stage="deploy", source="auto")
+    b = lessons.record("transient_retry", work_item_id=_WI, stage="deploy", source="auto")
+    assert a is not None and b is None  # second auto deduped in-window
+    # Manual is never deduped.
+    m1 = lessons.record("transient_retry", work_item_id=_WI, stage="deploy", source="manual")
+    m2 = lessons.record("transient_retry", work_item_id=_WI, stage="deploy", source="manual")
+    assert m1 is not None and m2 is not None and m1 != m2
+    # Window=0 disables dedup.
+    import src.config as c
+    c.settings.lessons_dedup_window_s = 0
+    c2 = lessons.record("transient_retry", work_item_id=_WI, stage="deploy", source="auto")
+    assert c2 is not None
+    c.settings.lessons_dedup_window_s = 3600
+
+
+# ===========================================================================
+# TC-08 — wiring: QG rollback to development writes a gate_failure lesson
+# ===========================================================================
+def test_tc08_gate_failure_autorecord(monkeypatch):
+    from src import stage_engine as se
+
+    # All side-effecting DB / notifier / plane ops on the rollback path are patched
+    # to no-ops; only the lessons block reaches the (real tmp) DB — so we assert the
+    # WIRING (rolled_back_to -> gate_failure lesson) without standing up a full task.
+    for name in ("notify_stage_change", "plane_notify_stage", "send_telegram",
+                 "set_issue_in_progress", "plane_add_comment", "update_task_stage"):
+        monkeypatch.setattr(se, name, lambda *a, **k: None, raising=False)
+    monkeypatch.setattr(se, "extract_test_failures", lambda *a, **k: "", raising=False)
+    monkeypatch.setattr(se, "_developer_retry_count", lambda *a, **k: 0, raising=False)
+    monkeypatch.setattr(se, "enqueue_job", lambda *a, **k: 123, raising=False)
+
+    result = se.AdvanceResult()
+    se._handle_qg_failure_rollbacks(
+        99, "testing", _REPO, "ORCH-098", "feature/ORCH-098-fnd",
+        agent="tester", qg_name="check_tests_passed", reason="2 failed", result=result,
+    )
+    assert result.rolled_back_to == "development"
+    rows = db.get_lessons(lesson_type="gate_failure", work_item_id="ORCH-098")
+    assert len(rows) == 1
+    r = rows[0]
+    assert r["stage"] == "testing"
+    assert r["agent"] == "tester"
+    assert r["repo"] == _REPO
+    assert r["source"] == "auto"
+    assert r["detail"] == "check_tests_passed"
+
+
+# ===========================================================================
+# TC-09 — wiring: launcher transient-budget-exhaustion writes a lesson;
+#          a failing journal never breaks the hot path
+# ===========================================================================
+def test_tc09_transient_autorecord_and_never_raise(monkeypatch):
+    from src.agents import launcher as lmod
+
+    launcher = lmod.AgentLauncher()
+    monkeypatch.setattr(launcher, "_notify_failed", lambda *a, **k: None)
+    monkeypatch.setattr(launcher, "_record_outcome", lambda *a, **k: None)
+    monkeypatch.setattr(cfg.settings, "transient_max_attempts", 3, raising=False)
+
+    job_id = db.enqueue_job("developer", _REPO, "task", task_id=42)
+    job = {"transient_attempts": 3, "task_id": 42, "repo": _REPO}
+    # Budget exhausted (tattempts >= tmax) -> the failed branch records the lesson.
+    launcher._finalize_transient(job_id, "developer", 1, 99, job, retry_after=None)
+
+    rows = db.get_lessons(lesson_type="transient_retry")
+    assert len(rows) == 1
+    assert rows[0]["repo"] == _REPO
+    assert rows[0]["agent"] == "developer"
+    assert rows[0]["source"] == "auto"
+
+    # never-raise in the hot path: a failing record must not break finalisation.
+    def boom(*a, **k):
+        raise RuntimeError("journal down")
+
+    monkeypatch.setattr(db, "record_lesson", boom)
+    monkeypatch.setattr(db, "lessons_recent_dup_exists", lambda *a, **k: False)
+    job_id2 = db.enqueue_job("developer", _REPO, "task2", task_id=43)
+    job2 = {"transient_attempts": 3, "task_id": 43, "repo": _REPO}
+    # Must NOT raise even though the journal insert blows up.
+    launcher._finalize_transient(job_id2, "developer", 1, 99, job2, retry_after=None)
+
+
+# ===========================================================================
+# TC-10 — GET /lessons + GET /queue block; reads do not mutate
+# ===========================================================================
+def test_tc10_get_endpoints(monkeypatch):
+    from fastapi.testclient import TestClient
+    import src.main as main
+
+    db.record_lesson(lesson_type="gate_failure", work_item_id=_WI, repo=_REPO,
+                     status="new", source="auto")
+    db.record_lesson(lesson_type="merge_hold", work_item_id="ORCH-2", repo="enduro-trails",
+                     status="closed", source="auto")
+
+    client = TestClient(main.app)
+
+    r = client.get("/lessons")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["enabled"] is True
+    assert len(body["lessons"]) == 2
+
+    # Filters.
+    r = client.get("/lessons", params={"type": "gate_failure"})
+    assert len(r.json()["lessons"]) == 1
+    r = client.get("/lessons", params={"repo": "enduro-trails"})
+    assert len(r.json()["lessons"]) == 1
+    r = client.get("/lessons", params={"limit": 1})
+    assert len(r.json()["lessons"]) == 1
+
+    # Reads do not mutate.
+    assert db.lessons_snapshot()["total"] == 2
+
+    # GET /queue carries the read-only lessons block.
+    q = client.get("/queue")
+    assert q.status_code == 200
+    assert "lessons" in q.json()
+    assert q.json()["lessons"]["enabled"] is True
+    assert q.json()["lessons"]["total"] == 2
+
+
+# ===========================================================================
+# TC-11 — POST /lessons (manual) + POST /lessons/{id} (update); kill-switch
+# ===========================================================================
+def test_tc11_post_endpoints_and_killswitch(monkeypatch):
+    from fastapi.testclient import TestClient
+    import src.main as main
+
+    client = TestClient(main.app)
+
+    # Manual create with attribution.
+    r = client.post("/lessons", json={
+        "lesson_type": "process_gap", "work_item_id": _WI, "repo": _REPO,
+        "attribution": "platform", "target_domain": "quality", "root_cause": "manual note",
+    })
+    assert r.status_code == 200
+    lid = r.json()["id"]
+    assert isinstance(lid, int)
+    rows = db.get_lessons(work_item_id=_WI)
+    assert rows[0]["source"] == "manual"
+    assert rows[0]["attribution"] == "platform"
+
+    # Missing lesson_type -> error, no row.
+    r = client.post("/lessons", json={"work_item_id": "X"})
+    assert r.json()["ok"] is False
+
+    # Update via POST /lessons/{id}.
+    r = client.post(f"/lessons/{lid}", json={"status": "closed", "related_task": "ORCH-300"})
+    assert r.json()["ok"] is True
+    assert db.get_lessons(work_item_id=_WI)[0]["status"] == "closed"
+
+    # Kill-switch off -> endpoints report {"enabled": false}.
+    monkeypatch.setattr(cfg.settings, "lessons_enabled", False, raising=False)
+    assert client.get("/lessons").json() == {"enabled": False, "lessons": []}
+    assert client.post("/lessons", json={"lesson_type": "x"}).json() == {"enabled": False}
+    assert client.post(f"/lessons/{lid}", json={"status": "new"}).json() == {"enabled": False}
+
+
+# ===========================================================================
+# TC-12 — pipeline invariants structurally untouched
+# ===========================================================================
+def test_tc12_pipeline_invariants_untouched():
+    from src.stages import STAGE_TRANSITIONS
+    from src.qg.checks import QG_CHECKS
+
+    # The journal must not have added/removed a stage edge or a QG check.
+    assert "development" in STAGE_TRANSITIONS
+    assert "deploy" in STAGE_TRANSITIONS
+    # machine-verdict QG checks still registered (sample of the canon set).
+    for name in ("check_ci_green", "check_tests_passed", "check_coverage_gate"):
+        assert name in QG_CHECKS
+    # The journal is NOT a quality gate — no check named after it.
+    assert not any("lesson" in k.lower() for k in QG_CHECKS)

tests/watchdog/conftest.py

@@ -0,0 +1,46 @@
+"""Shared helpers/fixtures for the watchdog (ORCH-100, F1b) test suite.
+
+A tiny urllib-style fake opener so HTTP collectors / Telegram transport never
+touch the network (test plan §scope: all collectors/transport are mocked).
+"""
+from __future__ import annotations
+
+import io
+import urllib.error
+
+
+class FakeResponse:
+    """Context-manager response mimicking ``urllib`` ``addinfourl``."""
+
+    def __init__(self, status: int = 200, body: bytes = b"{}"):
+        self.status = status
+        self._body = body
+
+    def getcode(self):
+        return self.status
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def make_opener(*, status=200, body=b"{}", exc=None):
+    """Build a fake ``urlopen`` that returns a body or raises ``exc``."""
+
+    def _opener(req, timeout=None):
+        if exc is not None:
+            raise exc
+        return FakeResponse(status=status, body=body)
+
+    return _opener
+
+
+def http_error(code: int) -> urllib.error.HTTPError:
+    return urllib.error.HTTPError(
+        url="http://x", code=code, msg="err", hdrs=None, fp=io.BytesIO(b"")
+    )

tests/watchdog/test_compose_service.py

@@ -0,0 +1,66 @@
+"""TC-12: compose invariant — orchestrator-watchdog is a separate service.
+
+It declares its own build (watchdog/Dockerfile), restart policy, mem_limit, and
+mounts docker.sock read-only (:ro). Parses the real docker-compose.yml.
+"""
+import pathlib
+
+import yaml
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
+
+
+def _compose():
+    with open(REPO_ROOT / "docker-compose.yml") as f:
+        return yaml.safe_load(f)
+
+
+def test_watchdog_service_declared():
+    svc = _compose()["services"]
+    assert "orchestrator-watchdog" in svc
+
+
+def test_watchdog_builds_from_watchdog_dockerfile():
+    wd = _compose()["services"]["orchestrator-watchdog"]
+    build = wd["build"]
+    assert isinstance(build, dict)
+    assert build["dockerfile"] == "watchdog/Dockerfile"
+    assert build["context"] == "."
+
+
+def test_watchdog_has_restart_and_mem_limit():
+    wd = _compose()["services"]["orchestrator-watchdog"]
+    assert wd["restart"] == "unless-stopped"
+    assert wd["mem_limit"] == "128m"  # thin stack, not Grafana/Prometheus
+
+
+def test_docker_sock_mounted_read_only():
+    wd = _compose()["services"]["orchestrator-watchdog"]
+    sock = [v for v in wd["volumes"] if "docker.sock" in v]
+    assert sock, "docker.sock must be mounted"
+    assert all(v.endswith(":ro") for v in sock), "docker.sock must be :ro"
+
+
+def test_host_paths_mounted_read_only():
+    wd = _compose()["services"]["orchestrator-watchdog"]
+    # Every bind mount the watchdog uses is read-only (it only reads).
+    for v in wd["volumes"]:
+        assert v.endswith(":ro"), f"watchdog mount must be :ro: {v}"
+
+
+def test_env_file_is_optional():
+    # A missing .env.watchdog must not break `docker compose up` (self-hosting).
+    wd = _compose()["services"]["orchestrator-watchdog"]
+    env_file = wd["env_file"]
+    assert isinstance(env_file, list)
+    assert env_file[0]["required"] is False
+
+
+def test_watchdog_dockerfile_exists_and_is_stdlib_only():
+    df = REPO_ROOT / "watchdog" / "Dockerfile"
+    assert df.exists()
+    text = df.read_text()
+    # No pip install of third-party deps (stdlib-only, D1).
+    assert "pip install" not in text
+    assert "COPY requirements" not in text
+    assert "requirements.txt" not in text

tests/watchdog/test_config_killswitch.py

@@ -0,0 +1,69 @@
+"""TC-07: kill-switch + env-driven config (no hardcoded thresholds).
+
+``WATCHDOG_ENABLED=false`` -> the daemon is inert (idle, no ticks). Thresholds /
+intervals / timeouts come from env, not constants.
+"""
+from watchdog.config import Config
+
+
+def test_killswitch_off_is_inert(monkeypatch):
+    from watchdog import __main__ as entry
+
+    cfg = Config.from_env({"WATCHDOG_ENABLED": "false", "WATCHDOG_INTERVAL_S": "0"})
+    assert cfg.enabled is False
+
+    built = {"n": 0}
+
+    class _Dog:
+        def tick(self):
+            built["n"] += 1
+
+    # If run() ever constructed a Watchdog / ticked while disabled, this would fire.
+    monkeypatch.setattr(entry, "Watchdog", lambda c: _Dog())
+    monkeypatch.setattr(entry.time, "sleep", lambda *_: None)
+    entry.run(cfg=cfg, max_ticks=3)
+    assert built["n"] == 0  # inert: never ticked
+
+
+def test_thresholds_read_from_env():
+    cfg = Config.from_env(
+        {
+            "WATCHDOG_INTERVAL_S": "7",
+            "WATCHDOG_MEM_PCT": "77",
+            "WATCHDOG_QUEUE_DEPTH": "9",
+            "WATCHDOG_AGENT_HUNG_MIN": "5",
+            "WATCHDOG_STAGE_STUCK_MIN": "11",
+            "WATCHDOG_ORCH_DOWN_TICKS": "4",
+            "WATCHDOG_COOLDOWN_S": "60",
+            "WATCHDOG_HTTP_TIMEOUT_S": "2",
+            "WATCHDOG_CONTAINERS": "orchestrator,plane-app",
+            "WATCHDOG_DEPS": "gitea=http://g/healthz,plane=http://p/",
+        }
+    )
+    assert cfg.interval_s == 7.0
+    assert cfg.mem_pct == 77.0
+    assert cfg.queue_depth == 9
+    assert cfg.agent_hung_s == 5 * 60.0
+    assert cfg.stage_stuck_s == 11 * 60.0
+    assert cfg.orch_down_ticks == 4
+    assert cfg.cooldown_s == 60.0
+    assert cfg.http_timeout_s == 2.0
+    assert cfg.containers == ["orchestrator", "plane-app"]
+    assert cfg.deps == {"gitea": "http://g/healthz", "plane": "http://p/"}
+
+
+def test_defaults_when_env_absent():
+    cfg = Config.from_env({})
+    assert cfg.enabled is True
+    assert cfg.interval_s == 30.0
+    assert cfg.metrics_url.endswith(":8500/metrics")
+    assert cfg.disk_crit_enabled is False
+    assert cfg.containers == ["orchestrator"]
+    assert cfg.deps == {}
+
+
+def test_malformed_env_degrades_to_default():
+    # A garbage numeric value must not crash config; it degrades to the default.
+    cfg = Config.from_env({"WATCHDOG_INTERVAL_S": "abc", "WATCHDOG_MEM_PCT": ""})
+    assert cfg.interval_s == 30.0
+    assert cfg.mem_pct == 90.0

tests/watchdog/test_decision.py

@@ -0,0 +1,56 @@
+"""TC-01…TC-04: the pure decision function (alert/throttle/realert/recovery).
+
+Mirrors the disk_watchdog.decide_action tests — the generalised ``decide`` is a
+strict superset (boolean ``signal_active`` instead of ``used_pct >= threshold``).
+"""
+from watchdog.decision import (
+    ACTION_ALERT,
+    ACTION_NONE,
+    ACTION_REALERT,
+    ACTION_RECOVERY,
+    AlertState,
+    decide,
+)
+
+COOLDOWN = 1800.0
+
+
+def test_tc01_not_alerting_active_alerts():
+    # TC-01: not-alerting & signal active -> ALERT (one per crossing).
+    prev = AlertState(alerting=False)
+    assert decide(True, prev, now=100.0, cooldown_s=COOLDOWN) == ACTION_ALERT
+
+
+def test_tc01_not_alerting_inactive_is_none():
+    prev = AlertState(alerting=False)
+    assert decide(False, prev, now=100.0, cooldown_s=COOLDOWN) == ACTION_NONE
+
+
+def test_tc02_alerting_active_in_cooldown_is_none():
+    # TC-02: alerting & still active & cooldown NOT elapsed -> NONE (anti-spam).
+    prev = AlertState(alerting=True, last_alert_at=1000.0)
+    assert decide(True, prev, now=1000.0 + 10.0, cooldown_s=COOLDOWN) == ACTION_NONE
+
+
+def test_tc03_alerting_active_cooldown_elapsed_realerts():
+    # TC-03: alerting & still active & cooldown elapsed -> REALERT.
+    prev = AlertState(alerting=True, last_alert_at=1000.0)
+    assert decide(True, prev, now=1000.0 + COOLDOWN, cooldown_s=COOLDOWN) == ACTION_REALERT
+
+
+def test_tc03_alerting_active_no_last_alert_realerts():
+    # Defensive: alerting but last_alert_at missing -> treat cooldown as elapsed.
+    prev = AlertState(alerting=True, last_alert_at=None)
+    assert decide(True, prev, now=5.0, cooldown_s=COOLDOWN) == ACTION_REALERT
+
+
+def test_tc04_alerting_recovers_when_inactive():
+    # TC-04: alerting & signal back to normal -> RECOVERY.
+    prev = AlertState(alerting=True, last_alert_at=1000.0)
+    assert decide(False, prev, now=1200.0, cooldown_s=COOLDOWN) == ACTION_RECOVERY
+
+
+def test_cooldown_boundary_is_inclusive():
+    # Exactly at cooldown boundary -> REALERT (>= semantics, like disk_watchdog).
+    prev = AlertState(alerting=True, last_alert_at=0.0)
+    assert decide(True, prev, now=COOLDOWN, cooldown_s=COOLDOWN) == ACTION_REALERT

tests/watchdog/test_deps_collector.py

@@ -0,0 +1,39 @@
+"""Dependency ping collector: reachable / unreachable / 5xx (never-raise)."""
+from watchdog.collectors import deps as deps_mod
+
+from .conftest import http_error, make_opener
+
+
+def test_ping_reachable():
+    assert deps_mod.ping("http://x", 1.0, opener=make_opener(status=200)) is True
+
+
+def test_ping_4xx_still_reachable():
+    # A 4xx proves the host is up (we ping for liveness, not auth).
+    assert deps_mod.ping("http://x", 1.0, opener=make_opener(exc=http_error(404))) is True
+
+
+def test_ping_5xx_is_down():
+    assert deps_mod.ping("http://x", 1.0, opener=make_opener(exc=http_error(503))) is False
+
+
+def test_ping_timeout_is_down():
+    assert deps_mod.ping(
+        "http://x", 1.0, opener=make_opener(exc=TimeoutError())
+    ) is False
+
+
+def test_ping_all_mixed():
+    def opener_factory(url):
+        return make_opener(status=200) if "good" in url else make_opener(
+            exc=ConnectionError()
+        )
+
+    def opener(req, timeout=None):
+        url = req.full_url if hasattr(req, "full_url") else req
+        return opener_factory(url)(req, timeout)
+
+    res = deps_mod.ping_all(
+        {"good": "http://good", "bad": "http://bad"}, 1.0, opener=opener
+    )
+    assert res == {"good": True, "bad": False}

tests/watchdog/test_disk_alert_dedup.py

@@ -0,0 +1,42 @@
+"""TC-13: anti-duplicate disk alert (coordinated with ORCH-063 / disk_watchdog).
+
+ADR-001 D6: disk_watchdog (ORCH-063) is the SOLE owner of the 85% disk alert via
+the orchestrator's Telegram. The sidecar carries NO disk alert by default
+(``WATCHDOG_DISK_CRIT_ENABLED=false``) -> structurally zero double-alert. The
+sidecar's contribution is an OPT-IN independent ceiling at a HIGHER threshold
+(a different event, separate channel).
+"""
+from watchdog.config import Config
+from watchdog.signals import host_signals
+
+
+def _cfg(**kw):
+    return Config.from_env(kw)
+
+
+def test_disk_signal_absent_by_default():
+    # Disk full at 90% -> sidecar produces NO disk signal (disk_watchdog owns it).
+    cfg = _cfg()
+    assert cfg.disk_crit_enabled is False
+    sigs = host_signals(cfg, mem_pct=None, disk=("/repos", 90.0))
+    assert [s for s in sigs if s.key == "host_disk_crit"] == []
+
+
+def test_opt_in_ceiling_is_separate_higher_event():
+    cfg = _cfg(WATCHDOG_DISK_CRIT_ENABLED="true", WATCHDOG_DISK_CRIT_PCT="97")
+    # Below the ceiling (90% < 97%) -> not active even when opted in (no 85% dup).
+    below = host_signals(cfg, mem_pct=None, disk=("/repos", 90.0))
+    crit_below = [s for s in below if s.key == "host_disk_crit"]
+    assert len(crit_below) == 1 and crit_below[0].active is False
+
+    # At/over the high ceiling -> active (a DIFFERENT event from disk_watchdog 85%).
+    over = host_signals(cfg, mem_pct=None, disk=("/repos", 98.0))
+    crit_over = [s for s in over if s.key == "host_disk_crit"]
+    assert len(crit_over) == 1 and crit_over[0].active is True
+
+
+def test_mem_signal_independent_of_disk():
+    cfg = _cfg(WATCHDOG_MEM_PCT="90")
+    sigs = host_signals(cfg, mem_pct=95.0, disk=None)
+    mem = [s for s in sigs if s.key == "host_mem"]
+    assert len(mem) == 1 and mem[0].active is True

tests/watchdog/test_docker_readonly.py

@@ -0,0 +1,79 @@
+"""TC-09: self-hosting safety — the Docker client is read-only by construction.
+
+The client exposes ONLY read methods (list/inspect), its single request
+primitive hard-codes the ``GET`` HTTP method, and the source carries no
+mutating Docker verb (start/stop/restart/kill/exec/POST). ``classify_container``
+is a pure status mapper.
+"""
+import inspect as _inspect
+
+from watchdog.collectors import containers as cmod
+
+
+def test_request_primitive_is_get_only(monkeypatch):
+    captured = {}
+
+    class _FakeConn:
+        def __init__(self, *a, **k):
+            pass
+
+        def request(self, method, path):
+            captured["method"] = method
+            captured["path"] = path
+
+        def getresponse(self):
+            class _R:
+                status = 200
+
+                def read(self_inner):
+                    return b"[]"
+
+            return _R()
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(cmod, "_UnixHTTPConnection", _FakeConn)
+    reader = cmod.DockerSockReader("/var/run/docker.sock")
+    reader.list_containers()
+    assert captured["method"] == "GET"
+    reader.inspect("orchestrator")
+    assert captured["method"] == "GET"
+
+
+def test_no_mutating_verbs_in_source():
+    src = _inspect.getsource(cmod)
+    lowered = src.lower()
+    # No write/control verbs should appear as Docker actions in this module.
+    for verb in ("/start", "/stop", "/restart", "/kill", "/exec", "\"post\"", "'post'"):
+        assert verb not in lowered, f"mutating verb leaked into containers.py: {verb}"
+
+
+def test_reader_exposes_only_read_methods():
+    public = [
+        n for n in dir(cmod.DockerSockReader)
+        if not n.startswith("_")
+    ]
+    assert set(public) == {"list_containers", "inspect"}
+
+
+def test_classify_container_pure_mapping():
+    assert cmod.classify_container({"State": {"Status": "running"}}) == "running"
+    assert cmod.classify_container({"State": {"Status": "exited"}}) == "exited"
+    assert cmod.classify_container(
+        {"State": {"Status": "running", "Health": {"Status": "unhealthy"}}}
+    ) == "unhealthy"
+    assert cmod.classify_container(
+        {"State": {"Status": "running", "Health": {"Status": "healthy"}}}
+    ) == "healthy"
+    assert cmod.classify_container(None) == "unknown"
+    assert cmod.classify_container({}) == "unknown"
+
+
+def test_container_alarm_semantics():
+    assert cmod.container_alarm("running") is False
+    assert cmod.container_alarm("healthy") is False
+    assert cmod.container_alarm("exited") is True
+    assert cmod.container_alarm("restarting") is True
+    assert cmod.container_alarm("unhealthy") is True
+    assert cmod.container_alarm("unknown") is True

tests/watchdog/test_host_collector.py

@@ -0,0 +1,54 @@
+"""Host collector: /proc/meminfo parsing + disk reads (never-raise)."""
+import os
+import tempfile
+
+from watchdog.collectors import host as host_mod
+
+
+def test_mem_used_pct_from_meminfo():
+    content = "MemTotal:       1000 kB\nMemFree:  100 kB\nMemAvailable:  250 kB\n"
+    with tempfile.NamedTemporaryFile("w", suffix=".meminfo", delete=False) as f:
+        f.write(content)
+        path = f.name
+    try:
+        pct = host_mod.read_mem_used_pct(path)
+        # used = (1 - 250/1000) * 100 = 75.0
+        assert pct == 75.0
+    finally:
+        os.unlink(path)
+
+
+def test_mem_used_pct_missing_file_is_none():
+    assert host_mod.read_mem_used_pct("/no/such/meminfo") is None
+
+
+def test_mem_used_pct_garbage_is_none():
+    with tempfile.NamedTemporaryFile("w", delete=False) as f:
+        f.write("totally not meminfo\n")
+        path = f.name
+    try:
+        assert host_mod.read_mem_used_pct(path) is None
+    finally:
+        os.unlink(path)
+
+
+def test_disk_used_pct_real_path():
+    pct = host_mod.read_disk_used_pct("/")
+    assert pct is None or (0.0 <= pct <= 100.0)
+
+
+def test_disk_used_pct_missing_path_is_none():
+    assert host_mod.read_disk_used_pct("/no/such/path/xyz") is None
+
+
+def test_max_disk_used_pct_picks_worst(monkeypatch):
+    monkeypatch.setattr(
+        host_mod, "read_disk_used_pct",
+        lambda p: {"/a": 10.0, "/b": 80.0, "/c": None}.get(p),
+    )
+    assert host_mod.max_disk_used_pct(["/a", "/b", "/c"]) == ("/b", 80.0)
+
+
+def test_max_disk_used_pct_all_unreadable(monkeypatch):
+    monkeypatch.setattr(host_mod, "read_disk_used_pct", lambda p: None)
+    assert host_mod.max_disk_used_pct(["/a", "/b"]) is None

tests/watchdog/test_metrics_parse.py

@@ -0,0 +1,118 @@
+"""TC-11: tolerance to the /metrics contract.
+
+Unknown fields are ignored, a missing optional does not crash, and a
+schema_version above the known one logs a warning (no crash). Also covers the
+envelope-derived signal evaluation (agent_hung / stage_stuck / job_failed /
+queue_depth).
+"""
+import logging
+
+from watchdog.collectors import orch as orch_mod
+from watchdog.config import Config
+from watchdog.signals import AgentSample, eval_envelope
+
+
+def _cfg(**kw):
+    return Config.from_env(kw)
+
+
+def test_unknown_field_ignored():
+    body = '{"schema_version":1,"stages":[],"brand_new_field":42}'
+    env = orch_mod.parse_envelope(body)
+    assert env["brand_new_field"] == 42  # tolerated, not a crash
+
+
+def test_missing_optional_not_an_error():
+    env = orch_mod.parse_envelope('{"schema_version":1}')
+    ev = eval_envelope(env, _cfg(), prev_agents={}, prev_failed=None)
+    assert ev.signals == []  # no stages/agents/queue -> no signals, no crash
+
+
+def test_non_object_body_raises_valueerror():
+    import pytest
+
+    with pytest.raises(ValueError):
+        orch_mod.parse_envelope("[1,2,3]")
+
+
+def test_schema_version_bump_warns(caplog):
+    env = {"schema_version": 999}
+    with caplog.at_level(logging.WARNING):
+        orch_mod.check_schema_version(env)
+    assert any("schema_version" in r.message for r in caplog.records)
+
+
+def test_parse_generated_at_roundtrip_and_tolerant():
+    assert orch_mod.parse_generated_at({"generated_at": "2026-06-10T00:00:00Z"})
+    assert orch_mod.parse_generated_at({"generated_at": "garbage"}) is None
+    assert orch_mod.parse_generated_at({}) is None
+
+
+def test_queue_depth_and_job_failed_signals():
+    env = {
+        "schema_version": 1,
+        "queue": {"depth": 25, "counts": {"failed": 5}},
+    }
+    cfg = _cfg(WATCHDOG_QUEUE_DEPTH="20")
+    # First tick: failed baseline established, depth over threshold fires.
+    ev = eval_envelope(env, cfg, prev_agents={}, prev_failed=None)
+    keys = {s.key for s in ev.signals}
+    assert "queue_depth" in keys
+    assert "job_failed" not in keys  # no prior baseline -> no edge yet
+    assert ev.failed_count == 5
+
+    # Next tick: failed grew 5 -> 7 -> edge job_failed alert.
+    env2 = {"queue": {"depth": 0, "counts": {"failed": 7}}}
+    ev2 = eval_envelope(env2, cfg, prev_agents={}, prev_failed=ev.failed_count)
+    jf = [s for s in ev2.signals if s.key == "job_failed"]
+    assert len(jf) == 1 and jf[0].edge is True and jf[0].active is True
+
+
+def test_stage_stuck_signal():
+    env = {"stages": [{"work_item": "ORCH-1", "stage": "review", "age_in_stage_s": 9999}]}
+    cfg = _cfg(WATCHDOG_STAGE_STUCK_MIN="1")  # 60s threshold
+    ev = eval_envelope(env, cfg, prev_agents={}, prev_failed=None)
+    stuck = [s for s in ev.signals if s.key == ("stage_stuck", "ORCH-1")]
+    assert len(stuck) == 1 and stuck[0].active is True
+
+
+def test_agent_hung_needs_two_polls_and_low_cpu():
+    cfg = _cfg(WATCHDOG_AGENT_HUNG_MIN="1", WATCHDOG_AGENT_CPU_FLOOR="0.01")
+    env = {
+        "schema_version": 1,
+        "generated_at": "2026-06-10T00:01:40Z",  # +100s vs prev sample below
+        "clk_tck": 100,
+        "agents": [{"run_id": 7, "agent": "developer", "runtime_s": 999, "cpu_ticks": 50}],
+    }
+    prev_t = orch_mod.parse_generated_at({"generated_at": "2026-06-10T00:00:00Z"})
+    prev = {7: AgentSample(cpu_ticks=40, generated_at=prev_t)}
+    # Δticks=10 over clk_tck=100 -> 0.1 CPU-seconds over 100s -> frac 0.001 < floor.
+    ev = eval_envelope(env, cfg, prev_agents=prev, prev_failed=None)
+    hung = [s for s in ev.signals if s.key == ("agent_hung", 7)]
+    assert len(hung) == 1 and hung[0].active is True
+
+
+def test_agent_hung_skipped_when_cpu_ticks_null():
+    cfg = _cfg(WATCHDOG_AGENT_HUNG_MIN="1")
+    env = {
+        "generated_at": "2026-06-10T00:01:40Z",
+        "clk_tck": 100,
+        "agents": [{"run_id": 8, "runtime_s": 999, "cpu_ticks": None}],
+    }
+    prev = {8: AgentSample(cpu_ticks=10, generated_at=0.0)}
+    ev = eval_envelope(env, cfg, prev_agents=prev, prev_failed=None)
+    assert [s for s in ev.signals if s.key == ("agent_hung", 8)] == []
+
+
+def test_agent_busy_not_hung():
+    cfg = _cfg(WATCHDOG_AGENT_HUNG_MIN="1", WATCHDOG_AGENT_CPU_FLOOR="0.01")
+    env = {
+        "generated_at": "2026-06-10T00:01:40Z",
+        "clk_tck": 100,
+        "agents": [{"run_id": 9, "runtime_s": 999, "cpu_ticks": 5000}],
+    }
+    prev_t = orch_mod.parse_generated_at({"generated_at": "2026-06-10T00:00:00Z"})
+    prev = {9: AgentSample(cpu_ticks=40, generated_at=prev_t)}
+    # Big Δticks -> high CPU fraction -> not hung.
+    ev = eval_envelope(env, cfg, prev_agents=prev, prev_failed=None)
+    assert [s for s in ev.signals if s.key == ("agent_hung", 9)] == []

tests/watchdog/test_never_raise.py

@@ -0,0 +1,88 @@
+"""TC-06: three-level never-raise.
+
+A raising collector (host / containers / deps) degrades ONE signal and the tick
+reaches the end collecting the rest; a raising send is swallowed; the daemon
+loop survives a raising tick.
+"""
+from watchdog.config import Config
+from watchdog.core import Watchdog
+
+
+class _BoomDocker:
+    def inspect(self, name):
+        raise RuntimeError("docker socket blew up")
+
+
+class _Notifier:
+    def __init__(self):
+        self.sent = []
+
+    def send(self, text):
+        self.sent.append(text)
+        return True
+
+
+class _BoomNotifier:
+    def send(self, text):
+        raise RuntimeError("telegram blew up")
+
+
+def _cfg(**kw):
+    base = {
+        "WATCHDOG_TG_BOT_TOKEN": "t",
+        "WATCHDOG_TG_CHAT_ID": "c",
+        "WATCHDOG_CONTAINERS": "orchestrator",
+    }
+    return Config.from_env({**base, **kw})
+
+
+def _good_fetch_patch(dog, monkeypatch):
+    from watchdog.collectors import orch as orch_mod
+
+    env = {"schema_version": 1, "generated_at": "2026-06-10T00:00:00Z",
+           "clk_tck": 100, "agents": [], "stages": [],
+           "queue": {"depth": 0, "counts": {"failed": 0}}}
+    monkeypatch.setattr(
+        orch_mod, "fetch_metrics",
+        lambda *a, **k: orch_mod.FetchResult(ok=True, envelope=env),
+    )
+
+
+def test_per_source_broken_container_degrades_one_signal(monkeypatch):
+    notifier = _Notifier()
+    dog = Watchdog(_cfg(), notifier=notifier, docker=_BoomDocker())
+    _good_fetch_patch(dog, monkeypatch)
+    # Should not raise; tick completes and produces results for other sources.
+    results = dog.tick()
+    keys = [getattr(s, "key", None) for _, s in results]
+    # orch_down evaluated (orch was up -> not active) and container evaluated.
+    assert "orch_down" in keys
+    assert ("container_down", "orchestrator") in keys
+
+
+def test_per_send_failure_is_swallowed(monkeypatch):
+    # A raising notifier must not break the tick (per-send never-raise).
+    cfg = _cfg(WATCHDOG_MEM_PCT="0")  # mem >= 0 always -> force an alert send
+    dog = Watchdog(cfg, notifier=_BoomNotifier(), docker=_BoomDocker())
+    _good_fetch_patch(dog, monkeypatch)
+    monkeypatch.setattr(
+        "watchdog.collectors.host.read_mem_used_pct", lambda *a, **k: 50.0
+    )
+    # Must not raise despite the notifier exploding on a triggered alert.
+    dog.tick()
+
+
+def test_per_tick_loop_survives_raising_tick(monkeypatch):
+    # The __main__ run loop must survive a tick that raises (outer never-raise).
+    from watchdog import __main__ as entry
+
+    cfg = _cfg(WATCHDOG_INTERVAL_S="0")
+
+    class _BoomDog:
+        def tick(self):
+            raise RuntimeError("tick blew up")
+
+    monkeypatch.setattr(entry, "Watchdog", lambda c: _BoomDog())
+    monkeypatch.setattr(entry.time, "sleep", lambda *_: None)
+    # max_ticks bounds the loop; it must return cleanly, not propagate.
+    entry.run(cfg=cfg, max_ticks=3)

tests/watchdog/test_notify_isolation.py

@@ -0,0 +1,84 @@
+"""TC-10: independent Telegram transport.
+
+The sidecar sends through its OWN bot_token/chat_id from env and must NOT import
+``src.notifications`` or the orchestrator's code (C-1 / BR-8).
+"""
+import pathlib
+
+from watchdog import notify as notify_mod
+from watchdog.notify import Notifier, send_telegram
+
+
+def test_notify_uses_own_token_and_chat(monkeypatch):
+    captured = {}
+
+    def _fake_opener(req, timeout=None):
+        captured["url"] = req.full_url
+        captured["data"] = req.data
+
+        class _R:
+            status = 200
+
+            def getcode(self):
+                return 200
+
+            def __enter__(self_inner):
+                return self_inner
+
+            def __exit__(self_inner, *a):
+                return False
+
+        return _R()
+
+    ok = send_telegram(
+        "MYTOKEN", "MYCHAT", "hello", opener=_fake_opener, api_base="https://tg.test"
+    )
+    assert ok is True
+    assert "botMYTOKEN" in captured["url"]
+    assert b"MYCHAT" in captured["data"]
+
+
+def test_missing_credentials_is_failsafe_no_send():
+    # Absent token/chat -> logs and returns False, never raises (fail-safe).
+    assert send_telegram("", "chat", "x") is False
+    assert send_telegram("tok", "", "x") is False
+
+
+def test_send_failure_is_swallowed():
+    def _boom(req, timeout=None):
+        raise OSError("network down")
+
+    assert send_telegram("t", "c", "x", opener=_boom) is False
+
+
+def test_notifier_wraps_credentials(monkeypatch):
+    sent = {}
+    monkeypatch.setattr(
+        notify_mod, "send_telegram",
+        lambda tok, chat, text, timeout: sent.update(tok=tok, chat=chat, text=text) or True,
+    )
+    Notifier("TOK", "CHAT").send("body")
+    assert sent == {"tok": "TOK", "chat": "CHAT", "text": "body"}
+
+
+def test_watchdog_package_does_not_import_src():
+    # No watchdog/*.py file may reference the orchestrator's src package (C-1).
+    # (Source scan, not sys.modules: the global test conftest imports src.* for
+    # every test, so a runtime check would be polluted.)
+    pkg_root = pathlib.Path(notify_mod.__file__).resolve().parent
+    offenders = []
+    for py in pkg_root.rglob("*.py"):
+        text = py.read_text(encoding="utf-8")
+        for needle in ("import src", "from src", "src.notifications"):
+            if needle in text:
+                offenders.append(f"{py.name}: {needle}")
+    assert offenders == [], f"watchdog references the orchestrator src: {offenders}"
+
+
+def test_notify_source_has_no_src_notifications_import():
+    import inspect
+
+    src = inspect.getsource(notify_mod)
+    assert "src.notifications" not in src
+    assert "from src" not in src
+    assert "import src" not in src

tests/watchdog/test_orch_down.py

@@ -0,0 +1,67 @@
+"""TC-05: orchestrator-down detection.
+
+A ``/metrics`` timeout / connection-refused / 5xx / unreadable body -> the
+``orchestrator_down`` signal -> ALERT "орк не отвечает" once the debounce
+threshold of consecutive failures is reached (FR-3).
+"""
+from watchdog.collectors import orch as orch_mod
+from watchdog.config import Config
+from watchdog.signals import orch_down_signal
+
+from .conftest import http_error, make_opener
+
+
+def _cfg(**kw):
+    return Config.from_env({**{"WATCHDOG_ORCH_DOWN_TICKS": "3"}, **kw})
+
+
+def test_fetch_timeout_is_not_ok():
+    opener = make_opener(exc=TimeoutError("timed out"))
+    res = orch_mod.fetch_metrics("http://x/metrics", 1.0, opener=opener)
+    assert res.ok is False
+    assert res.envelope is None
+    assert res.error
+
+
+def test_fetch_connection_refused_is_not_ok():
+    opener = make_opener(exc=ConnectionRefusedError("refused"))
+    res = orch_mod.fetch_metrics("http://x/metrics", 1.0, opener=opener)
+    assert res.ok is False
+
+
+def test_fetch_5xx_is_not_ok():
+    opener = make_opener(status=503, body=b"oops")
+    res = orch_mod.fetch_metrics("http://x/metrics", 1.0, opener=opener)
+    assert res.ok is False
+    assert "503" in (res.error or "")
+
+
+def test_fetch_httperror_5xx_is_not_ok():
+    opener = make_opener(exc=http_error(502))
+    res = orch_mod.fetch_metrics("http://x/metrics", 1.0, opener=opener)
+    assert res.ok is False
+
+
+def test_fetch_unreadable_body_is_not_ok():
+    opener = make_opener(status=200, body=b"not-json{{{")
+    res = orch_mod.fetch_metrics("http://x/metrics", 1.0, opener=opener)
+    assert res.ok is False
+
+
+def test_fetch_good_body_is_ok():
+    opener = make_opener(status=200, body=b'{"schema_version":1,"stages":[]}')
+    res = orch_mod.fetch_metrics("http://x/metrics", 1.0, opener=opener)
+    assert res.ok is True
+    assert res.envelope["schema_version"] == 1
+
+
+def test_orch_down_signal_debounce_then_alert():
+    cfg = _cfg()
+    # Single transient failure -> NOT active (does not flap).
+    assert orch_down_signal(1, cfg, "timeout").active is False
+    assert orch_down_signal(2, cfg, "timeout").active is False
+    # K-th consecutive failure -> active alarm.
+    sig = orch_down_signal(3, cfg, "timeout")
+    assert sig.active is True
+    assert sig.key == "orch_down"
+    assert "не отвечает" in sig.detail

tests/watchdog/test_tick_orch_down_integration.py

@@ -0,0 +1,106 @@
+"""TC-08: full tick with the orchestrator down (integration).
+
+With ``/metrics`` failing, the tick must not crash, must still collect host /
+containers / deps, must produce EXACTLY ONE ``orchestrator_down`` alert (after
+the debounce), suppress within cooldown, and emit recovery on restoration.
+"""
+from watchdog.collectors import orch as orch_mod
+from watchdog.config import Config
+from watchdog.core import Watchdog
+
+
+class _Notifier:
+    def __init__(self):
+        self.sent = []
+
+    def send(self, text):
+        self.sent.append(text)
+        return True
+
+
+class _StubDocker:
+    def inspect(self, name):
+        return {"State": {"Status": "running"}}
+
+
+def _cfg(**kw):
+    base = {
+        "WATCHDOG_TG_BOT_TOKEN": "t",
+        "WATCHDOG_TG_CHAT_ID": "c",
+        "WATCHDOG_ORCH_DOWN_TICKS": "2",
+        "WATCHDOG_COOLDOWN_S": "1000",
+        "WATCHDOG_CONTAINERS": "orchestrator",
+    }
+    return Config.from_env({**base, **kw})
+
+
+def _clock():
+    t = {"v": 0.0}
+
+    def now():
+        return t["v"]
+
+    return t, now
+
+
+def _down(monkeypatch):
+    monkeypatch.setattr(
+        orch_mod, "fetch_metrics",
+        lambda *a, **k: orch_mod.FetchResult(ok=False, error="timeout"),
+    )
+
+
+def _up(monkeypatch):
+    env = {"schema_version": 1, "generated_at": "2026-06-10T00:00:00Z",
+           "clk_tck": 100, "agents": [], "stages": [],
+           "queue": {"depth": 0, "counts": {"failed": 0}}}
+    monkeypatch.setattr(
+        orch_mod, "fetch_metrics",
+        lambda *a, **k: orch_mod.FetchResult(ok=True, envelope=env),
+    )
+
+
+def _orch_down_alerts(notifier):
+    return [m for m in notifier.sent if "не отвечает" in m]
+
+
+def test_tick_orch_down_one_alert_then_throttle_then_recovery(monkeypatch):
+    notifier = _Notifier()
+    t, now = _clock()
+    dog = Watchdog(_cfg(), notifier=notifier, docker=_StubDocker(), now_provider=now)
+
+    _down(monkeypatch)
+    # tick 1: first failure -> debounced, NOT yet active -> no alert.
+    dog.tick()
+    assert _orch_down_alerts(notifier) == []
+
+    # tick 2: second consecutive failure -> active -> EXACTLY ONE alert.
+    t["v"] = 30.0
+    dog.tick()
+    assert len(_orch_down_alerts(notifier)) == 1
+
+    # tick 3: still down, within cooldown -> throttled (no new alert).
+    t["v"] = 60.0
+    dog.tick()
+    assert len(_orch_down_alerts(notifier)) == 1
+
+    # restore: orchestrator answers again -> recovery message.
+    _up(monkeypatch)
+    t["v"] = 90.0
+    dog.tick()
+    recoveries = [m for m in notifier.sent if "восстановление" in m and "Орк" in m]
+    assert len(recoveries) == 1
+
+
+def test_tick_does_not_crash_when_everything_breaks(monkeypatch):
+    # orch down + docker raising + no deps: tick still completes.
+    class _BoomDocker:
+        def inspect(self, name):
+            raise RuntimeError("boom")
+
+    notifier = _Notifier()
+    dog = Watchdog(_cfg(), notifier=notifier, docker=_BoomDocker())
+    _down(monkeypatch)
+    dog.tick()  # must not raise
+    dog.tick()
+    assert len(_orch_down_alerts(notifier)) == 1

watchdog/Dockerfile

@@ -0,0 +1,28 @@
+# ORCH-100 (FND/F1b): sidecar-watchdog — thin stdlib-only monitoring brain.
+#
+# A separate, deliberately tiny image (NO pip dependencies — Python 3.12 stdlib
+# only, ADR-001 D1): urllib for HTTP/Telegram, a raw HTTP-over-unix-socket client
+# for the read-only docker.sock, shutil/proc for host metrics. Kept thin on a
+# tight host (C-3); mem_limit is enforced in docker-compose.yml (D2).
+#
+# The build context is the REPO ROOT (see docker-compose.yml `build:
+# context: . / dockerfile: watchdog/Dockerfile`) so we can COPY the watchdog/
+# package. src/** is intentionally NOT copied — the sidecar must not import the
+# orchestrator (C-1).
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Run as a non-root user; the sidecar only READS (docker.sock :ro, host paths :ro).
+RUN useradd -u 1000 -m -d /home/watchdog -s /bin/bash watchdog
+
+# Copy ONLY the sidecar package (no src/, no requirements — stdlib only).
+COPY watchdog/ ./watchdog/
+
+ENV PYTHONPATH=/app
+ENV PYTHONUNBUFFERED=1
+
+USER watchdog
+
+# `python -m watchdog` runs watchdog/__main__.py (the tick loop).
+ENTRYPOINT ["python", "-m", "watchdog"]

watchdog/__init__.py

@@ -0,0 +1,31 @@
+"""ORCH-100 (FND/F1b): sidecar-watchdog — the monitoring brain in a separate container.
+
+This package is the *brain* half of the domain-0 observability pair. F1a
+(ORCH-099, ``src/metrics.py``) exposes a lightweight read-only ``GET /metrics``
+envelope — raw signal only. F1b (this package) is the stateful observer that
+reads that envelope, augments it with host / container / dependency probes, runs
+every signal through a generalised pure decision function (modelled 1:1 on
+``src/disk_watchdog.py::decide_action``) with per-signal in-memory
+dedup / throttle / recovery, and emits alerts over its OWN independent Telegram
+channel.
+
+Hard invariants (ADR-001, ``docs/work-items/ORCH-100/06-adr/``):
+  * The observer is separated from the observed: the runtime is a separate
+    container (``orchestrator-watchdog``). A hang/crash of the orchestrator makes
+    the sidecar *louder* (``orchestrator_down``), never silent.
+  * Strictly read-only to the observed system: ``docker.sock`` is GET-only (and
+    mounted ``:ro``), no DB writes, no disk writes, no process control
+    (start/stop/restart/exec) — self-hosting-safe on the shared prod host.
+  * never-raise on three levels (per-source / per-tick / per-send) + a
+    ``WATCHDOG_ENABLED`` kill-switch.
+  * NO import from ``src/**`` — the sidecar must survive a refactor/crash of the
+    orchestrator process (C-1).
+
+The highest known ``/metrics`` schema_version this build understands. A higher
+value from the orchestrator is tolerated (warning, read the compatible subset),
+never a crash (D9).
+"""
+
+KNOWN_SCHEMA_VERSION = 1
+
+__all__ = ["KNOWN_SCHEMA_VERSION"]

watchdog/__main__.py

@@ -0,0 +1,75 @@
+"""Sidecar entrypoint: the tick loop with kill-switch + per-tick never-raise (D8).
+
+Run as ``python -m watchdog`` (the container ``ENTRYPOINT``). The loop:
+  * honours ``WATCHDOG_ENABLED=false`` -> stays INERT (idle-loops with a log line,
+    does NOT ``exit``, so ``restart: unless-stopped`` does not spin a restart loop);
+  * wraps every tick in an outer ``try/except`` so a tick error logs and the daemon
+    survives (per-tick never-raise);
+  * logs start / each tick so the container logs prove the sidecar is alive and why
+    an alert did (not) fire (NFR-7).
+"""
+from __future__ import annotations
+
+import logging
+import time
+
+from .config import Config
+from .core import Watchdog
+
+logger = logging.getLogger("watchdog")
+
+
+def _setup_logging() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+
+def run(cfg: Config | None = None, max_ticks: int | None = None) -> None:
+    """Run the tick loop. ``max_ticks`` bounds the loop for tests (``None`` = forever)."""
+    cfg = cfg or Config.from_env()
+
+    if not cfg.enabled:
+        logger.info("watchdog: WATCHDOG_ENABLED=false -> inert (idle, no ticks)")
+        # Idle, not exit: keep the container up so restart-policy does not flap.
+        ticks = 0
+        while max_ticks is None or ticks < max_ticks:
+            time.sleep(cfg.interval_s)
+            ticks += 1
+        return
+
+    logger.info(
+        "watchdog started (interval=%ss, metrics=%s, containers=%s, deps=%s, "
+        "mem_pct=%s, disk_crit=%s)",
+        cfg.interval_s,
+        cfg.metrics_url,
+        cfg.containers,
+        list(cfg.deps),
+        cfg.mem_pct,
+        cfg.disk_crit_enabled,
+    )
+    dog = Watchdog(cfg)
+    ticks = 0
+    while max_ticks is None or ticks < max_ticks:
+        try:
+            dispatched = dog.tick()
+            fired = [
+                (a, getattr(s, "key", None)) for a, s in dispatched if a != "none"
+            ]
+            logger.info("watchdog tick ok (fired=%s)", fired)
+        except Exception as e:  # noqa: BLE001 - per-tick outer never-raise (D8)
+            logger.error("watchdog tick error: %s", e)
+        ticks += 1
+        if max_ticks is not None and ticks >= max_ticks:
+            break
+        time.sleep(cfg.interval_s)
+
+
+def main() -> None:
+    _setup_logging()
+    run()
+
+
+if __name__ == "__main__":
+    main()

watchdog/collectors/__init__.py

@@ -0,0 +1,5 @@
+"""Sidecar collectors: orchestrator ``/metrics``, host, containers, dependencies.
+
+Each collector is never-raise at the source level (per-source degradation, D8):
+a broken source degrades ONE signal and the tick keeps collecting the rest.
+"""

watchdog/collectors/containers.py

@@ -0,0 +1,119 @@
+"""Collector: container statuses over a READ-ONLY ``docker.sock`` (D1, D2, FR-5).
+
+Raw HTTP-over-unix-socket via stdlib (``socket.AF_UNIX`` +
+``http.client.HTTPConnection`` subclass) — NO ``docker`` pip package. The client
+issues ``GET`` requests ONLY (``GET /containers/json``,
+``GET /containers/<name>/json``) — it is read-only **by construction**: there is
+no method that POSTs / starts / stops / restarts / execs (AC-6, TC-09). The
+mount is additionally ``:ro``, a second guarantee.
+
+``classify_container`` is a pure function (Up / healthy / restarting / exited /
+unhealthy) and ``container_alarm`` decides whether the status is alerting — both
+testable without a live Docker.
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import logging
+import socket
+
+logger = logging.getLogger("watchdog.collectors.containers")
+
+# A container is "healthy" (no alarm) only in these states.
+_OK_STATES = frozenset({"running", "healthy"})
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    """``HTTPConnection`` over an ``AF_UNIX`` socket (stdlib only, GET-only use)."""
+
+    def __init__(self, sock_path: str, timeout: float):
+        super().__init__("localhost", timeout=timeout)
+        self._sock_path = sock_path
+
+    def connect(self) -> None:  # noqa: D401 - override
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(self.timeout)
+        sock.connect(self._sock_path)
+        self.sock = sock
+
+
+class DockerSockReader:
+    """Read-only Docker API client over the unix socket.
+
+    EXPOSES READ METHODS ONLY (``list_containers`` / ``inspect``); the single
+    private primitive ``_get`` hard-codes the ``GET`` HTTP method, so no caller
+    can ever mutate the Docker state (AC-6 / TC-09). never-raise: any socket /
+    HTTP / parse error degrades to ``None`` / ``[]``.
+    """
+
+    def __init__(self, sock_path: str = "/var/run/docker.sock", timeout_s: float = 3.0):
+        self._sock_path = sock_path
+        self._timeout = timeout_s
+
+    def _get(self, path: str) -> object | None:
+        """Issue a single ``GET <path>`` over the socket. never-raise.
+
+        This is the ONLY request primitive and it is GET-only — the read-only
+        guarantee is structural, not policy.
+        """
+        conn = None
+        try:
+            conn = _UnixHTTPConnection(self._sock_path, self._timeout)
+            conn.request("GET", path)
+            resp = conn.getresponse()
+            body = resp.read()
+            if resp.status >= 400:
+                logger.warning("watchdog: docker GET %s -> %s", path, resp.status)
+                return None
+            return json.loads(body.decode("utf-8", errors="replace"))
+        except Exception as e:  # noqa: BLE001 - docker unreachable -> degrade
+            logger.warning("watchdog: docker GET %s failed: %s", path, e)
+            return None
+        finally:
+            if conn is not None:
+                try:
+                    conn.close()
+                except Exception:  # noqa: BLE001
+                    pass
+
+    def list_containers(self) -> list:
+        """``GET /containers/json?all=1`` — every container (read-only)."""
+        data = self._get("/containers/json?all=1")
+        return data if isinstance(data, list) else []
+
+    def inspect(self, name: str) -> dict | None:
+        """``GET /containers/<name>/json`` — one container's detail (read-only)."""
+        data = self._get(f"/containers/{name}/json")
+        return data if isinstance(data, dict) else None
+
+
+def classify_container(inspect: dict | None) -> str:
+    """Pure classifier: inspect-JSON -> a coarse status token (D5).
+
+    Returns one of ``running`` / ``healthy`` / ``unhealthy`` / ``restarting`` /
+    ``exited`` / ``created`` / ``paused`` / ``dead`` / ``unknown``. When a
+    healthcheck is present its verdict (``healthy`` / ``unhealthy``) takes
+    precedence over the bare ``running`` state. Never raises.
+    """
+    try:
+        if not inspect:
+            return "unknown"
+        state = inspect.get("State")
+        if not isinstance(state, dict):
+            return "unknown"
+        status = (state.get("Status") or "").strip().lower()
+        health = state.get("Health")
+        if isinstance(health, dict):
+            hstatus = (health.get("Status") or "").strip().lower()
+            if hstatus in ("healthy", "unhealthy"):
+                return hstatus
+        return status or "unknown"
+    except Exception as e:  # noqa: BLE001 - classification must never crash
+        logger.warning("watchdog: classify_container error: %s", e)
+        return "unknown"
+
+
+def container_alarm(status: str) -> bool:
+    """True when ``status`` is NOT a healthy state (restarting/exited/unhealthy/...)."""
+    return (status or "").strip().lower() not in _OK_STATES

watchdog/collectors/deps.py

@@ -0,0 +1,51 @@
+"""Collector: external dependency pings — Plane / Gitea / Anthropic (FR-6).
+
+A light ``GET`` with a short timeout per configured dependency. never-raise: an
+unreachable dependency returns ``False`` (a signal for the threshold), never an
+exception (D8). Endpoints / timeouts are configured via ``WATCHDOG_DEPS`` (D5);
+an empty config means no pings (fail-safe).
+"""
+from __future__ import annotations
+
+import logging
+import urllib.error
+import urllib.request
+
+logger = logging.getLogger("watchdog.collectors.deps")
+
+
+def ping(url: str, timeout_s: float, *, opener=urllib.request.urlopen) -> bool:
+    """True when ``url`` answers with a non-5xx HTTP status. never-raise.
+
+    A 4xx still counts as "reachable" (the host is up and responding) — we ping
+    for liveness, not for auth. ``opener`` is injected so tests never hit the
+    network.
+    """
+    try:
+        req = urllib.request.Request(url, method="GET")
+        with opener(req, timeout=timeout_s) as resp:
+            status = int(getattr(resp, "status", None) or resp.getcode())
+            return status < 500
+    except urllib.error.HTTPError as e:
+        # An HTTP error response still proves the host is reachable, unless 5xx.
+        return int(getattr(e, "code", 500)) < 500
+    except Exception as e:  # noqa: BLE001 - unreachable -> down signal, not a crash
+        logger.warning("watchdog: dep ping %s failed: %s", url, e)
+        return False
+
+
+def ping_all(
+    deps: dict[str, str],
+    timeout_s: float,
+    *,
+    opener=urllib.request.urlopen,
+) -> dict[str, bool]:
+    """Ping every configured dependency -> ``{name: reachable}``. never-raise."""
+    out: dict[str, bool] = {}
+    for name, url in deps.items():
+        try:
+            out[name] = ping(url, timeout_s, opener=opener)
+        except Exception as e:  # noqa: BLE001 - one dep degrades, others continue
+            logger.warning("watchdog: dep %s ping error: %s", name, e)
+            out[name] = False
+    return out

watchdog/collectors/host.py

@@ -0,0 +1,75 @@
+"""Collector: host metrics — memory (/proc/meminfo), disk (shutil.disk_usage).
+
+stdlib-only, the same primitives ``disk_watchdog`` uses (D1). Every reader is
+never-raise: a missing path / unreadable proc-file degrades to ``None`` (one
+signal skipped), never a tick crash (D8). CPU "hung agent" liveness is computed
+from the ``/metrics`` envelope (cpu_ticks), not here.
+"""
+from __future__ import annotations
+
+import logging
+import shutil
+
+logger = logging.getLogger("watchdog.collectors.host")
+
+
+def read_mem_used_pct(meminfo_path: str = "/proc/meminfo") -> float | None:
+    """Host memory used-% from ``/proc/meminfo`` (``MemTotal`` / ``MemAvailable``).
+
+    ``used_pct = (1 - MemAvailable/MemTotal) * 100``. Returns ``None`` on a
+    missing file / unparseable content / non-Linux (never raises).
+    """
+    try:
+        fields: dict[str, int] = {}
+        with open(meminfo_path, "r") as f:
+            for line in f:
+                parts = line.split(":")
+                if len(parts) != 2:
+                    continue
+                key = parts[0].strip()
+                val = parts[1].strip().split()
+                if val:
+                    try:
+                        fields[key] = int(val[0])  # value is in kB
+                    except ValueError:
+                        continue
+        total = fields.get("MemTotal")
+        avail = fields.get("MemAvailable")
+        if not total or avail is None:
+            return None
+        used_pct = (1.0 - (avail / total)) * 100.0
+        return round(used_pct, 1)
+    except Exception as e:  # noqa: BLE001 - degrade one signal, keep the tick
+        logger.warning("watchdog: cannot read memory: %s", e)
+        return None
+
+
+def read_disk_used_pct(path: str) -> float | None:
+    """Disk used-% for one path via ``shutil.disk_usage`` (1:1 with disk_watchdog).
+
+    Returns ``None`` if the path is missing / unreadable (never raises).
+    """
+    try:
+        usage = shutil.disk_usage(path)
+        total = int(usage.total)
+        if total <= 0:
+            return None
+        return round(int(usage.used) / total * 100.0, 1)
+    except Exception as e:  # noqa: BLE001 - skip this path, keep the tick
+        logger.warning("watchdog: cannot measure disk %s: %s", path, e)
+        return None
+
+
+def max_disk_used_pct(paths: list[str]) -> tuple[str, float] | None:
+    """The fullest of ``paths`` as ``(path, used_pct)`` — the worst-case ceiling.
+
+    A path that cannot be measured is skipped; ``None`` if none could be read.
+    """
+    worst: tuple[str, float] | None = None
+    for p in paths:
+        pct = read_disk_used_pct(p)
+        if pct is None:
+            continue
+        if worst is None or pct > worst[1]:
+            worst = (p, pct)
+    return worst

watchdog/collectors/orch.py

@@ -0,0 +1,118 @@
+"""Collector: orchestrator ``GET /metrics`` -> parsed envelope | orchestrator_down.
+
+The orchestrator runs ``network_mode: host`` on port 8500, so from the
+host-network sidecar ``/metrics`` is reachable at ``http://127.0.0.1:8500/metrics``
+(configurable). The body is the F1a versioned envelope
+``{schema_version, generated_at, clk_tck, stages[], queue, agents[], cost,
+enabled}`` (adr-0030 D2). Parsing is DEFENSIVE (D9): unknown keys are ignored,
+a missing optional is not an error, a ``schema_version`` higher than known is
+logged (warning) but read as the compatible subset — never a crash.
+
+A timeout / connection-refused / 5xx / unreadable body is itself the master
+alarm signal ``orchestrator_down`` (FR-3), surfaced by ``FetchResult.ok ==
+False`` — NOT an exception (never-raise per-source, D8).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .. import KNOWN_SCHEMA_VERSION
+
+logger = logging.getLogger("watchdog.collectors.orch")
+
+
+@dataclass
+class FetchResult:
+    """Outcome of one ``/metrics`` probe.
+
+    ``ok`` is ``True`` only when a 2xx response carried a parseable JSON object.
+    Any other outcome (timeout / refused / 5xx / unreadable) -> ``ok == False``
+    with a human ``error`` -> the ``orchestrator_down`` signal source.
+    """
+
+    ok: bool
+    envelope: dict | None = None
+    error: str | None = None
+
+
+def parse_envelope(body: str | bytes) -> dict:
+    """Parse the ``/metrics`` body into a dict — tolerant (D9, TC-11).
+
+    Raises ``ValueError`` only when the body is not a JSON object (that is the
+    "unreadable body" case the caller maps to ``orchestrator_down``). A valid
+    object with unknown / missing keys parses cleanly; downstream readers use
+    ``.get(...)`` with defaults.
+    """
+    if isinstance(body, bytes):
+        body = body.decode("utf-8", errors="replace")
+    data = json.loads(body)
+    if not isinstance(data, dict):
+        raise ValueError("metrics body is not a JSON object")
+    return data
+
+
+def check_schema_version(envelope: dict) -> None:
+    """Warn (never crash) when the orchestrator advertises a newer contract (D9)."""
+    try:
+        sv = envelope.get("schema_version")
+        if isinstance(sv, int) and sv > KNOWN_SCHEMA_VERSION:
+            logger.warning(
+                "watchdog: /metrics schema_version=%s > known=%s; reading the "
+                "compatible subset",
+                sv,
+                KNOWN_SCHEMA_VERSION,
+            )
+    except Exception as e:  # noqa: BLE001 - tolerance must never crash
+        logger.warning("watchdog: schema_version check error: %s", e)
+
+
+def fetch_metrics(
+    url: str,
+    timeout_s: float,
+    *,
+    opener=urllib.request.urlopen,
+) -> FetchResult:
+    """Probe ``GET <url>`` and return a :class:`FetchResult`. never-raise (D8).
+
+    ``opener`` is injected so tests drive timeout / refused / 5xx / good-body
+    without the network. A 5xx (or any ``HTTPError`` >= 500) is treated as
+    down; a parseable 2xx object is ``ok``.
+    """
+    try:
+        with opener(url, timeout=timeout_s) as resp:
+            status = int(getattr(resp, "status", None) or resp.getcode())
+            raw = resp.read()
+        if status >= 500:
+            return FetchResult(ok=False, error=f"http {status}")
+        if status >= 400:
+            # 4xx is "reachable but refusing" — still not a usable envelope.
+            return FetchResult(ok=False, error=f"http {status}")
+        env = parse_envelope(raw)
+        check_schema_version(env)
+        return FetchResult(ok=True, envelope=env)
+    except urllib.error.HTTPError as e:  # noqa: PERF203
+        return FetchResult(ok=False, error=f"http {getattr(e, 'code', '?')}")
+    except Exception as e:  # noqa: BLE001 - timeout / refused / unreadable -> down
+        return FetchResult(ok=False, error=str(e) or e.__class__.__name__)
+
+
+def parse_generated_at(envelope: dict) -> float | None:
+    """Convert the envelope ``generated_at`` ISO-8601 (``...Z``) to epoch seconds.
+
+    Returns ``None`` on a missing / malformed timestamp (never raises) — the
+    caller then skips the CPU-fraction computation for that tick.
+    """
+    try:
+        raw = envelope.get("generated_at")
+        if not raw or not isinstance(raw, str):
+            return None
+        dt = datetime.strptime(raw, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    except Exception as e:  # noqa: BLE001 - tolerant parsing
+        logger.warning("watchdog: cannot parse generated_at: %s", e)
+        return None

watchdog/config.py

@@ -0,0 +1,159 @@
+"""Read ``WATCHDOG_*`` env into a frozen config (thresholds / intervals / tokens /
+URLs / kill-switch), with safe defaults (D1/D8, FR-10).
+
+Every parser is never-raise: a missing / malformed value degrades to its
+documented default, the process never crashes on a bad env (the same spirit as
+``disk_watchdog.parse_paths``). ``.env.example`` is the canon of the keys.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _str(env: dict, key: str, default: str) -> str:
+    try:
+        v = env.get(key)
+        if v is None or not str(v).strip():
+            return default
+        return str(v).strip()
+    except Exception:  # noqa: BLE001 - never break config on a bad env
+        return default
+
+
+def _int(env: dict, key: str, default: int) -> int:
+    try:
+        v = env.get(key)
+        if v is None or not str(v).strip():
+            return default
+        return int(str(v).strip())
+    except Exception:  # noqa: BLE001
+        return default
+
+
+def _float(env: dict, key: str, default: float) -> float:
+    try:
+        v = env.get(key)
+        if v is None or not str(v).strip():
+            return default
+        return float(str(v).strip())
+    except Exception:  # noqa: BLE001
+        return default
+
+
+def _bool(env: dict, key: str, default: bool) -> bool:
+    try:
+        v = env.get(key)
+        if v is None or not str(v).strip():
+            return default
+        return str(v).strip().lower() in ("1", "true", "yes", "on")
+    except Exception:  # noqa: BLE001
+        return default
+
+
+def _csv(env: dict, key: str, default: list[str]) -> list[str]:
+    try:
+        v = env.get(key)
+        if v is None or not str(v).strip():
+            return list(default)
+        out = [p.strip() for p in str(v).split(",") if p.strip()]
+        return out or list(default)
+    except Exception:  # noqa: BLE001
+        return list(default)
+
+
+def _deps(env: dict, key: str) -> dict[str, str]:
+    """Parse ``name=url,name=url`` dependency pings (FR-6). Empty -> no pings.
+
+    Default is empty (fail-safe: no hardcoded network), the canonical example
+    URLs live in ``.env.example`` so the operator opts in explicitly.
+    """
+    out: dict[str, str] = {}
+    try:
+        raw = env.get(key)
+        if not raw or not str(raw).strip():
+            return out
+        for pair in str(raw).split(","):
+            pair = pair.strip()
+            if not pair or "=" not in pair:
+                continue
+            name, _, url = pair.partition("=")
+            name, url = name.strip(), url.strip()
+            if name and url:
+                out[name] = url
+    except Exception:  # noqa: BLE001
+        return {}
+    return out
+
+
+@dataclass(frozen=True)
+class Config:
+    """Immutable sidecar config built from the environment (FR-10)."""
+
+    # -- lifecycle / loop -------------------------------------------------
+    enabled: bool = True
+    interval_s: float = 30.0
+    http_timeout_s: float = 5.0
+    cooldown_s: float = 1800.0  # re-alert throttle for sustained signals
+
+    # -- orchestrator /metrics -------------------------------------------
+    metrics_url: str = "http://127.0.0.1:8500/metrics"
+    orch_down_ticks: int = 3  # K consecutive failures before orch_down fires
+
+    # -- host -------------------------------------------------------------
+    mem_pct: float = 90.0
+    disk_paths: list[str] = field(default_factory=lambda: ["/repos", "/app/data"])
+    disk_crit_enabled: bool = False  # opt-in independent disk ceiling (D6)
+    disk_crit_pct: float = 97.0
+
+    # -- agents / queue / stages (derived from the /metrics envelope) -----
+    agent_hung_min: float = 20.0  # minutes of runtime before "hung" is considered
+    agent_cpu_floor: float = 0.01  # CPU fraction below which a long agent is "hung"
+    stage_stuck_min: float = 120.0  # minutes a task may sit in one stage
+    queue_depth: int = 20
+
+    # -- containers (docker.sock, read-only) ------------------------------
+    containers: list[str] = field(default_factory=lambda: ["orchestrator"])
+    docker_sock: str = "/var/run/docker.sock"
+
+    # -- external dependencies -------------------------------------------
+    deps: dict[str, str] = field(default_factory=dict)
+
+    # -- independent Telegram transport ----------------------------------
+    tg_bot_token: str = ""
+    tg_chat_id: str = ""
+
+    # -- derived helpers --------------------------------------------------
+    @property
+    def agent_hung_s(self) -> float:
+        return self.agent_hung_min * 60.0
+
+    @property
+    def stage_stuck_s(self) -> float:
+        return self.stage_stuck_min * 60.0
+
+    @classmethod
+    def from_env(cls, env: dict | None = None) -> "Config":
+        """Build a Config from ``env`` (defaults to ``os.environ``). never-raise."""
+        e = dict(os.environ if env is None else env)
+        return cls(
+            enabled=_bool(e, "WATCHDOG_ENABLED", True),
+            interval_s=_float(e, "WATCHDOG_INTERVAL_S", 30.0),
+            http_timeout_s=_float(e, "WATCHDOG_HTTP_TIMEOUT_S", 5.0),
+            cooldown_s=_float(e, "WATCHDOG_COOLDOWN_S", 1800.0),
+            metrics_url=_str(e, "WATCHDOG_METRICS_URL", "http://127.0.0.1:8500/metrics"),
+            orch_down_ticks=_int(e, "WATCHDOG_ORCH_DOWN_TICKS", 3),
+            mem_pct=_float(e, "WATCHDOG_MEM_PCT", 90.0),
+            disk_paths=_csv(e, "WATCHDOG_DISK_PATHS", ["/repos", "/app/data"]),
+            disk_crit_enabled=_bool(e, "WATCHDOG_DISK_CRIT_ENABLED", False),
+            disk_crit_pct=_float(e, "WATCHDOG_DISK_CRIT_PCT", 97.0),
+            agent_hung_min=_float(e, "WATCHDOG_AGENT_HUNG_MIN", 20.0),
+            agent_cpu_floor=_float(e, "WATCHDOG_AGENT_CPU_FLOOR", 0.01),
+            stage_stuck_min=_float(e, "WATCHDOG_STAGE_STUCK_MIN", 120.0),
+            queue_depth=_int(e, "WATCHDOG_QUEUE_DEPTH", 20),
+            containers=_csv(e, "WATCHDOG_CONTAINERS", ["orchestrator"]),
+            docker_sock=_str(e, "WATCHDOG_DOCKER_SOCK", "/var/run/docker.sock"),
+            deps=_deps(e, "WATCHDOG_DEPS"),
+            tg_bot_token=_str(e, "WATCHDOG_TG_BOT_TOKEN", ""),
+            tg_chat_id=_str(e, "WATCHDOG_TG_CHAT_ID", ""),
+        )

watchdog/core.py

@@ -0,0 +1,183 @@
+"""The sidecar tick orchestration: collect -> evaluate -> decide -> dispatch (D3).
+
+The ``Watchdog`` owns the cross-tick state the sidecar is responsible for:
+  * ``_states``    — per signal_key :class:`AlertState` (anti-spam / recovery);
+  * ``_agents``    — per run_id :class:`AgentSample` (cpu_ticks, generated_at);
+  * ``_failed``    — last seen ``queue.counts.failed`` (job_failed edge);
+  * ``_orch_fail`` — consecutive ``/metrics`` failures (orch_down debounce).
+
+All collection is wrapped per-source and the whole ``tick`` is wrapped per-tick
+(never-raise, D8). ``now_provider`` is injectable for deterministic tests.
+"""
+from __future__ import annotations
+
+import logging
+import time
+
+from . import decision
+from .collectors import containers as containers_mod
+from .collectors import deps as deps_mod
+from .collectors import host as host_mod
+from .collectors import orch as orch_mod
+from .config import Config
+from .notify import Notifier
+from . import signals as signals_mod
+
+logger = logging.getLogger("watchdog.core")
+
+
+class Watchdog:
+    """Stateful observer: one ``tick`` collects every source and dispatches alerts."""
+
+    def __init__(
+        self,
+        cfg: Config,
+        notifier: Notifier | None = None,
+        docker: containers_mod.DockerSockReader | None = None,
+        now_provider=None,
+    ):
+        self.cfg = cfg
+        self._now = now_provider or time.time
+        self._notifier = notifier or Notifier(
+            cfg.tg_bot_token, cfg.tg_chat_id, cfg.http_timeout_s
+        )
+        self._docker = docker or containers_mod.DockerSockReader(
+            cfg.docker_sock, cfg.http_timeout_s
+        )
+        # cross-tick state owned by the sidecar
+        self._states: dict[object, decision.AlertState] = {}
+        self._agents: dict[object, signals_mod.AgentSample] = {}
+        self._failed: int | None = None
+        self._orch_fail: int = 0
+        self.last_run_ts: float | None = None
+
+    # -- collection (each source guarded; per-source never-raise) ---------
+    def _collect_orch(self) -> orch_mod.FetchResult:
+        try:
+            return orch_mod.fetch_metrics(self.cfg.metrics_url, self.cfg.http_timeout_s)
+        except Exception as e:  # noqa: BLE001 - treat as down, never crash the tick
+            logger.warning("watchdog: orch collect error: %s", e)
+            return orch_mod.FetchResult(ok=False, error=str(e))
+
+    def _collect_host_mem(self) -> float | None:
+        try:
+            return host_mod.read_mem_used_pct()
+        except Exception as e:  # noqa: BLE001
+            logger.warning("watchdog: host mem collect error: %s", e)
+            return None
+
+    def _collect_disk(self) -> tuple | None:
+        if not self.cfg.disk_crit_enabled:
+            return None
+        try:
+            return host_mod.max_disk_used_pct(self.cfg.disk_paths)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("watchdog: disk collect error: %s", e)
+            return None
+
+    def _collect_containers(self) -> dict:
+        out: dict[str, str] = {}
+        for name in self.cfg.containers:
+            try:
+                inspect = self._docker.inspect(name)
+                out[name] = containers_mod.classify_container(inspect)
+            except Exception as e:  # noqa: BLE001 - one container degrades, others continue
+                logger.warning("watchdog: container %s collect error: %s", name, e)
+                out[name] = "unknown"
+        return out
+
+    def _collect_deps(self) -> dict:
+        try:
+            return deps_mod.ping_all(self.cfg.deps, self.cfg.http_timeout_s)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("watchdog: deps collect error: %s", e)
+            return {}
+
+    # -- one tick ---------------------------------------------------------
+    def tick(self) -> list:
+        """Run one full pass; returns the dispatched ``(action, Signal)`` list.
+
+        Per-source collection is independently guarded so a broken source (ork
+        down / docker unreachable / dep timeout) degrades ONE signal and the rest
+        of the tick still runs (D8). The orchestrator being down is itself the
+        ``orchestrator_down`` signal, not a failed tick (FR-3).
+        """
+        now = self._now()
+        built: list[signals_mod.Signal] = []
+
+        # 1) orchestrator /metrics (+ orch_down debounce)
+        fetch = self._collect_orch()
+        if fetch.ok and fetch.envelope is not None:
+            self._orch_fail = 0
+            ev = signals_mod.eval_envelope(
+                fetch.envelope, self.cfg, self._agents, self._failed
+            )
+            self._agents = ev.agent_samples
+            self._failed = ev.failed_count
+            built.extend(ev.signals)
+        else:
+            self._orch_fail += 1
+        built.append(
+            signals_mod.orch_down_signal(self._orch_fail, self.cfg, fetch.error)
+        )
+
+        # 2) host memory + opt-in disk ceiling
+        built.extend(
+            signals_mod.host_signals(
+                self.cfg, self._collect_host_mem(), self._collect_disk()
+            )
+        )
+
+        # 3) containers (read-only docker.sock)
+        built.extend(signals_mod.container_signals(self.cfg, self._collect_containers()))
+
+        # 4) external dependency pings
+        built.extend(signals_mod.dep_signals(self._collect_deps()))
+
+        dispatched = self._dispatch(built, now)
+        self.last_run_ts = now
+        return dispatched
+
+    # -- decision + dispatch ----------------------------------------------
+    def _dispatch(self, built: list, now: float) -> list:
+        """Run each signal through ``decide`` and send alert/realert/recovery."""
+        results: list = []
+        for sig in built:
+            try:
+                cooldown = sig.cooldown_s if sig.cooldown_s is not None else self.cfg.cooldown_s
+                if sig.edge:
+                    # Edge signals (job_failed) fire on each new occurrence and
+                    # keep no sustained state: a fresh empty prev -> ALERT iff active.
+                    prev = decision.AlertState()
+                else:
+                    prev = self._states.get(sig.key) or decision.AlertState()
+                action = decision.decide(sig.active, prev, now, cooldown)
+                if action in (decision.ACTION_ALERT, decision.ACTION_REALERT):
+                    self._send(self._format(sig, action))
+                    if not sig.edge:
+                        self._states[sig.key] = decision.AlertState(
+                            alerting=True, last_alert_at=now
+                        )
+                elif action == decision.ACTION_RECOVERY:
+                    self._send(self._format(sig, action))
+                    self._states[sig.key] = decision.AlertState(
+                        alerting=False, last_alert_at=None
+                    )
+                results.append((action, sig))
+            except Exception as e:  # noqa: BLE001 - one signal degrades, others dispatch
+                logger.warning("watchdog: dispatch error for %s: %s", sig.key, e)
+        return results
+
+    @staticmethod
+    def _format(sig: signals_mod.Signal, action: str) -> str:
+        if action == decision.ACTION_RECOVERY:
+            return f"\U0001f7e2 {sig.title}: восстановление. {sig.detail}"
+        prefix = "\U0001f534" if action == decision.ACTION_ALERT else "\U0001f501"
+        return f"{prefix} {sig.title}: {sig.detail}"
+
+    def _send(self, text: str) -> None:
+        """Best-effort dispatch through the sidecar's own channel. never-raise."""
+        try:
+            self._notifier.send(text)
+        except Exception as e:  # noqa: BLE001 - per-send never-raise (D8)
+            logger.warning("watchdog: send failed: %s", e)

watchdog/decision.py

@@ -0,0 +1,63 @@
+"""Generalised pure alert-decision function + in-memory anti-spam state (D4).
+
+``src/disk_watchdog.py::decide_action`` is hard-wired to ``used_pct >= threshold``.
+F1b has many heterogeneous signals (booleans — "orch down", "container
+unhealthy"; counters — "job-failed delta"; thresholds — "memory %", "agent hung N
+min"), so the *comparison is lifted out* and this function works on an
+already-computed boolean ``signal_active``. The set of outcomes, the cooldown /
+recovery semantics and the in-memory best-effort state are a strict
+generalisation of the disk variant (BRD §BR-9 names it the template).
+
+``now`` and ``cooldown_s`` are injected so the cooldown / recovery logic is
+testable deterministically without a real timer (TC-01…TC-04).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Decision outcomes — same vocabulary as ``disk_watchdog`` (1:1 semantics).
+ACTION_NONE = "none"
+ACTION_ALERT = "alert"
+ACTION_REALERT = "realert"
+ACTION_RECOVERY = "recovery"
+
+
+@dataclass
+class AlertState:
+    """In-memory anti-spam state for one signal key (1:1 with ``PathAlertState``).
+
+    Best-effort: lives only in the daemon (no DB row, no migration). After a
+    process restart ``alerting`` resets to ``False`` -> a still-standing problem
+    re-alerts once, which is safe (an early signal, not an SLA; FR-7).
+    """
+
+    alerting: bool = False
+    last_alert_at: float | None = None
+
+
+def decide(
+    signal_active: bool,
+    prev: AlertState,
+    now: float,
+    cooldown_s: float,
+) -> str:
+    """Pure alert decision — testable without a thread or a real timer (D4).
+
+    Returns one of ``ACTION_{NONE,ALERT,REALERT,RECOVERY}`` as a function of the
+    current boolean signal, the previous per-key state and the injected clock:
+
+      * not alerting & active                 -> ALERT     (threshold crossed)
+      * alerting & active & cooldown elapsed  -> REALERT   (re-alert)
+      * alerting & active & in cooldown       -> NONE      (anti-spam)
+      * alerting & not active                 -> RECOVERY  (back to normal)
+      * not alerting & not active             -> NONE      (normal)
+    """
+    if not prev.alerting:
+        return ACTION_ALERT if signal_active else ACTION_NONE
+    # prev.alerting is True
+    if not signal_active:
+        return ACTION_RECOVERY
+    last = prev.last_alert_at
+    if last is None or (now - last) >= cooldown_s:
+        return ACTION_REALERT
+    return ACTION_NONE

watchdog/notify.py

@@ -0,0 +1,68 @@
+"""Independent Telegram transport for the sidecar (D7, FR-8, BR-8).
+
+Reads its OWN ``WATCHDOG_TG_BOT_TOKEN`` / ``WATCHDOG_TG_CHAT_ID`` and POSTs via
+``urllib`` to ``api.telegram.org``. It is FORBIDDEN to import
+``src/notifications.py`` or to use the orchestrator's token / chat / functions —
+otherwise a crash or refactor of the orchestrator would drag down the alert
+channel (a direct violation of C-1 / BR-8). Missing token/chat -> log and skip
+(fail-safe), never raise (NFR-3).
+"""
+from __future__ import annotations
+
+import logging
+import urllib.parse
+import urllib.request
+
+logger = logging.getLogger("watchdog.notify")
+
+_TELEGRAM_API = "https://api.telegram.org"
+
+
+def send_telegram(
+    bot_token: str,
+    chat_id: str,
+    text: str,
+    timeout_s: float = 5.0,
+    *,
+    api_base: str = _TELEGRAM_API,
+    opener=urllib.request.urlopen,
+) -> bool:
+    """Send one Telegram message over the sidecar's own bot. never-raise (D8).
+
+    Returns ``True`` on a delivered message, ``False`` on any failure (missing
+    credentials, network error, non-2xx). ``opener`` / ``api_base`` are injected
+    so tests never touch the real network.
+    """
+    if not bot_token or not chat_id:
+        logger.warning("watchdog: telegram token/chat not configured -> skip send")
+        return False
+    try:
+        url = f"{api_base}/bot{bot_token}/sendMessage"
+        payload = urllib.parse.urlencode(
+            {
+                "chat_id": chat_id,
+                "text": text,
+                "parse_mode": "HTML",
+                "disable_web_page_preview": "true",
+            }
+        ).encode("utf-8")
+        req = urllib.request.Request(url, data=payload, method="POST")
+        with opener(req, timeout=timeout_s) as resp:
+            status = getattr(resp, "status", None) or resp.getcode()
+            return 200 <= int(status) < 300
+    except Exception as e:  # noqa: BLE001 - delivery is best-effort
+        logger.warning("watchdog: telegram send failed: %s", e)
+        return False
+
+
+class Notifier:
+    """Thin stateful wrapper binding the sidecar credentials for the tick loop."""
+
+    def __init__(self, bot_token: str, chat_id: str, timeout_s: float = 5.0):
+        self._token = bot_token
+        self._chat = chat_id
+        self._timeout = timeout_s
+
+    def send(self, text: str) -> bool:
+        """Best-effort send through the sidecar's own channel (never raises)."""
+        return send_telegram(self._token, self._chat, text, self._timeout)

watchdog/signals.py

@@ -0,0 +1,283 @@
+"""Pure signal builders: turn collected raw inputs into ``Signal`` objects (D5).
+
+A ``Signal`` is ``(key, active, title, detail, edge)``. ``key`` identifies the
+signal for per-key anti-spam state: a scalar (``"orch_down"``, ``"host_mem"``)
+or a tuple for per-entity signals (``("agent_hung", run_id)``,
+``("container_down", name)``, ``("stage_stuck", work_item)``,
+``("dep_down", name)``).
+
+These builders are PURE — given the envelope / host readings / prev-sample state
+they return signals + the next sample state, with no I/O — so the whole decision
+surface is unit-testable without a container, a socket or a timer (TC-01…TC-11).
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from .collectors import containers as containers_mod
+from .collectors import orch as orch_mod
+from .config import Config
+
+logger = logging.getLogger("watchdog.signals")
+
+
+@dataclass
+class Signal:
+    """One evaluated signal heading into the decision function.
+
+    ``edge`` marks event-style signals (e.g. ``job_failed``) that fire on each
+    new occurrence and have no sustained "recovery": the dispatcher does not
+    persist alerting state for them.
+    """
+
+    key: object
+    active: bool
+    title: str
+    detail: str
+    edge: bool = False
+    cooldown_s: float | None = None  # per-signal override of the global cooldown
+
+
+@dataclass
+class AgentSample:
+    """Previous ``(cpu_ticks, generated_at_epoch)`` for one running agent (D5)."""
+
+    cpu_ticks: int
+    generated_at: float
+
+
+@dataclass
+class EnvelopeEval:
+    """Result of evaluating the ``/metrics`` envelope: signals + carried state."""
+
+    signals: list = field(default_factory=list)
+    agent_samples: dict = field(default_factory=dict)  # run_id -> AgentSample
+    failed_count: int | None = None
+
+
+def _cpu_fraction(
+    cur_ticks: int,
+    cur_gen: float,
+    prev: AgentSample,
+    clk_tck: int,
+) -> float | None:
+    """CPU fraction of one agent across two ``/metrics`` polls (D5).
+
+    ``frac = (Δticks / clk_tck) / Δseconds``. Returns ``None`` if the deltas are
+    not usable (no wall-time elapsed, non-positive clk_tck) so a degenerate
+    sample never produces a false "hung" verdict.
+    """
+    try:
+        dt = cur_gen - prev.generated_at
+        if dt <= 0 or not clk_tck or clk_tck <= 0:
+            return None
+        cpu_seconds = (cur_ticks - prev.cpu_ticks) / clk_tck
+        if cpu_seconds < 0:
+            return None
+        return cpu_seconds / dt
+    except Exception as e:  # noqa: BLE001 - degenerate sample, no verdict
+        logger.warning("watchdog: cpu_fraction error: %s", e)
+        return None
+
+
+def eval_envelope(
+    envelope: dict,
+    cfg: Config,
+    prev_agents: dict,
+    prev_failed: int | None,
+) -> EnvelopeEval:
+    """Derive agent_hung / stage_stuck / job_failed / queue_depth signals (D5).
+
+    Pure: no I/O. ``prev_agents`` (run_id -> :class:`AgentSample`) and
+    ``prev_failed`` carry the cross-tick state the sidecar owns; the returned
+    :class:`EnvelopeEval` includes the NEXT state to persist. never-raise: a bad
+    sub-section degrades that family of signals, the rest still evaluate.
+    """
+    out = EnvelopeEval()
+    if not isinstance(envelope, dict):
+        out.agent_samples = dict(prev_agents)
+        out.failed_count = prev_failed
+        return out
+
+    clk_tck = envelope.get("clk_tck")
+    gen_at = orch_mod.parse_generated_at(envelope)
+
+    # -- agent_hung (needs two polls; per run_id) -------------------------
+    new_samples: dict = {}
+    try:
+        for a in envelope.get("agents") or []:
+            run_id = a.get("run_id")
+            cpu_ticks = a.get("cpu_ticks")
+            runtime_s = a.get("runtime_s")
+            if run_id is None:
+                continue
+            if cpu_ticks is None or gen_at is None:
+                # pid dead / non-Linux / no timestamp -> cannot judge; skip.
+                continue
+            new_samples[run_id] = AgentSample(int(cpu_ticks), gen_at)
+            prev = prev_agents.get(run_id)
+            if prev is None or not isinstance(clk_tck, int):
+                continue
+            frac = _cpu_fraction(int(cpu_ticks), gen_at, prev, clk_tck)
+            if frac is None or runtime_s is None:
+                continue
+            hung = (runtime_s > cfg.agent_hung_s) and (frac < cfg.agent_cpu_floor)
+            if hung:
+                out.signals.append(
+                    Signal(
+                        key=("agent_hung", run_id),
+                        active=True,
+                        title="Агент завис",
+                        detail=(
+                            f"agent={a.get('agent')} run_id={run_id} "
+                            f"runtime={int(runtime_s)}s cpu={frac:.4f} "
+                            f"(< {cfg.agent_cpu_floor})"
+                        ),
+                    )
+                )
+    except Exception as e:  # noqa: BLE001 - degrade agent family only
+        logger.warning("watchdog: eval agents error: %s", e)
+    out.agent_samples = new_samples
+
+    # -- stage_stuck (per work_item) -------------------------------------
+    try:
+        for s in envelope.get("stages") or []:
+            age = s.get("age_in_stage_s")
+            wi = s.get("work_item")
+            if age is None or wi is None:
+                continue
+            if age > cfg.stage_stuck_s:
+                out.signals.append(
+                    Signal(
+                        key=("stage_stuck", wi),
+                        active=True,
+                        title="Стадия застряла",
+                        detail=(
+                            f"{wi} в стадии {s.get('stage')} уже {int(age)}s "
+                            f"(порог {int(cfg.stage_stuck_s)}s)"
+                        ),
+                    )
+                )
+    except Exception as e:  # noqa: BLE001
+        logger.warning("watchdog: eval stages error: %s", e)
+
+    # -- queue depth + job_failed (edge) ---------------------------------
+    failed_now: int | None = prev_failed
+    try:
+        queue = envelope.get("queue") or {}
+        depth = queue.get("depth")
+        if isinstance(depth, int) and depth >= cfg.queue_depth:
+            out.signals.append(
+                Signal(
+                    key="queue_depth",
+                    active=True,
+                    title="Очередь растёт",
+                    detail=f"глубина очереди {depth} (порог {cfg.queue_depth})",
+                )
+            )
+        counts = queue.get("counts") or {}
+        failed = counts.get("failed")
+        if isinstance(failed, int):
+            failed_now = failed
+            if prev_failed is not None and failed > prev_failed:
+                out.signals.append(
+                    Signal(
+                        key="job_failed",
+                        active=True,
+                        title="Job упал",
+                        detail=(
+                            f"failed-джобов стало {failed} "
+                            f"(было {prev_failed}, +{failed - prev_failed})"
+                        ),
+                        edge=True,
+                    )
+                )
+    except Exception as e:  # noqa: BLE001
+        logger.warning("watchdog: eval queue error: %s", e)
+    out.failed_count = failed_now
+
+    return out
+
+
+def host_signals(cfg: Config, mem_pct: float | None, disk: tuple | None) -> list:
+    """Build host memory + opt-in disk-ceiling signals (D5/D6). Pure."""
+    sigs: list = []
+    if mem_pct is not None:
+        sigs.append(
+            Signal(
+                key="host_mem",
+                active=mem_pct >= cfg.mem_pct,
+                title="Память хоста",
+                detail=f"память хоста {mem_pct}% (порог {cfg.mem_pct}%)",
+            )
+        )
+    # Disk ceiling is OPT-IN (D6): disk_watchdog (ORCH-063) owns the 85% alert;
+    # the sidecar only carries an independent HIGHER ceiling when explicitly
+    # enabled, so there is no double-alert on the same fill event (FR-9/AC-5).
+    if cfg.disk_crit_enabled and disk is not None:
+        path, pct = disk
+        sigs.append(
+            Signal(
+                key="host_disk_crit",
+                active=pct >= cfg.disk_crit_pct,
+                title="Диск (критический потолок)",
+                detail=(
+                    f"диск {path} {pct}% (критический потолок {cfg.disk_crit_pct}%, "
+                    f"независимый канал sidecar)"
+                ),
+            )
+        )
+    return sigs
+
+
+def container_signals(cfg: Config, statuses: dict) -> list:
+    """Build per-container down signals from ``{name: status}``. Pure."""
+    sigs: list = []
+    for name, status in statuses.items():
+        sigs.append(
+            Signal(
+                key=("container_down", name),
+                active=containers_mod.container_alarm(status),
+                title="Контейнер не в норме",
+                detail=f"контейнер {name}: статус '{status}'",
+            )
+        )
+    return sigs
+
+
+def dep_signals(reachability: dict) -> list:
+    """Build per-dependency down signals from ``{name: reachable}``. Pure."""
+    sigs: list = []
+    for name, reachable in reachability.items():
+        sigs.append(
+            Signal(
+                key=("dep_down", name),
+                active=not reachable,
+                title="Зависимость недоступна",
+                detail=f"зависимость {name} не отвечает",
+            )
+        )
+    return sigs
+
+
+def orch_down_signal(consecutive_failures: int, cfg: Config, error: str | None) -> Signal:
+    """The master ``orchestrator_down`` signal (FR-3).
+
+    Active once ``/metrics`` has failed ``orch_down_ticks`` times in a row — a
+    single transient hiccup does not flap. The text explicitly notes that the
+    in-process guards (disk / reaper / reconciler) are dead too, so the operator
+    knows to check the host directly (D6).
+    """
+    active = consecutive_failures >= cfg.orch_down_ticks
+    return Signal(
+        key="orch_down",
+        active=active,
+        title="Орк не отвечает",
+        detail=(
+            f"GET /metrics не отвечает {consecutive_failures} тик(ов) подряд "
+            f"(порог {cfg.orch_down_ticks}): {error or 'недоступен'}. "
+            f"In-process стражи (disk/reaper/reconciler) тоже мертвы — проверьте "
+            f"хост (вкл. диск) и контейнер orchestrator."
+        ),
+    )