work_item: ORCH-063
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-09
model_used: claude-opus-4-8
title: "Disk-watchdog mva154: heartbeat-замер + Telegram-алерт при >85%"
framework: pytest
scope: >
  Покрывается: чистая логика решения об алерте (порог/анти-спам/recovery), замер заполнения
  по путям с дедупом/never-raise, формат алерт-сообщения, daemon start/stop/status,
  блок disk_monitor в GET /queue, нулевая регрессия при выключенном kill-switch.
  Вне покрытия: реальная отправка в Telegram (мокается), реальное заполнение диска mva154,
  внешние системы мониторинга, авто-очистка диска (вне объёма ORCH-063).
notes: >
  Время и Telegram-транспорт инъецируются/мокаются: now-провайдер для cooldown,
  monkeypatch send_telegram для перехвата вызовов. shutil.disk_usage мокается для задания
  used_pct без реального диска. Полный регресс tests/ должен оставаться зелёным.
  Имена модулей/функций финализирует архитектор (ADR-001) — module в TC ориентировочны.

tests:
  - id: TC-01
    type: unit
    description: "Решение алертить: used_pct >= threshold и состояние было 'ниже' -> should_alert=True (пересечение порога)."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-02
    type: unit
    description: "Анти-спам: used_pct >= threshold, состояние уже 'выше', с последнего алерта прошло < realert_s -> should_alert=False (не на каждом тике)."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-03
    type: unit
    description: "Повтор по cooldown: 'выше' порога, прошло >= realert_s с последнего алерта -> should_alert=True (повторный алерт)."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-04
    type: unit
    description: "Recovery: переход used_pct < threshold из состояния 'выше' -> сброс состояния + ровно одно recovery-сообщение; ниже порога устойчиво -> recovery не повторяется."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-05
    type: unit
    description: "Граница порога: used_pct ровно == threshold трактуется как превышение (>= порога алертит); used_pct == threshold-1 -> молчит."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-06
    type: unit
    description: "Замер по путям: для каждого пути считается used_pct/free через (мок) shutil.disk_usage; совпадающие по устройству пути дедуплицируются (одно срабатывание)."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-07
    type: unit
    description: "never-raise: недоступный/несуществующий путь и исключение в send_telegram логируются и не пробрасываются; тик завершается, демон жив."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-08
    type: unit
    description: "Формат алерта: сообщение содержит путь/точку монтирования, used_pct, свободно (ГБ или %) и порог; отправляется notifying (disable_notification не True)."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-09
    type: unit
    description: "Kill-switch: при disk_monitor_enabled=False демон не стартует в lifespan (или start() — no-op); замеры/алерты не выполняются."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-10
    type: unit
    description: "status(): возвращает dict с enabled/threshold_pct/interval_s/paths(последний замер)/alerting/last_alert_at; never-raise при отсутствии замеров."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-11
    type: integration
    description: "GET /queue содержит аддитивный блок disk_monitor с ожидаемыми ключами; существующие ключи ответа (counts/reconcile/reaper/serial_gate/...) не изменены."
    module: tests/test_disk_watchdog.py
    expected: PASS

  - id: TC-12
    type: integration
    description: "Тик демона при замоканном высоком заполнении (>=85%) вызывает send_telegram один раз; при выключенном флаге GET /queue отдаёт disk_monitor.enabled=false и алертов нет (нулевая регрессия)."
    module: tests/test_disk_watchdog.py
    expected: PASS