add sandbox observability contracts

tasks.md

@@ -227,3 +227,63 @@
 - Файлы: `domain/sandbox.py`, `usecase/interface.py`, `usecase/sandbox.py`, `repository/sandbox_session.py`, `adapter/http/fastapi/*`, `adapter/docker/runtime.py`, `adapter/di/container.py`, `test/*`
 - Решение: HTTP boundary принимает/возвращает UUID, usecase и repository работают с UUID objects, Docker labels продолжают сериализоваться в строки через `str(uuid)`
 - Критерии приемки: внутри sandbox flow `chat_id` и `session_id` больше не строки; `container_id` остается `str`; pydantic корректно сериализует UUID в response; `make pre-commit` проходит
+
+## Follow-up после issue #11 observability
+
+### M19. ADR и observability contracts для sandbox lifecycle
+
+- Исполнитель: `primary-agent`
+- Статус: completed
+- Зависимости: `M18`
+- Commit required: yes
+- Commit message: `add sandbox observability contracts`
+- Scope: зафиксировать sandbox lifecycle observability policy в ADR-lite и подготовить минимальные контракты для traces и current-state metrics без нарушения clean architecture
+- Файлы: `docs/008-sandbox-lifecycle-observability.md`, `usecase/interface.py`, `repository/sandbox_session.py`, `adapter/otel/metrics.py`, `adapter/observability/noop.py`
+- Решение: добавить в `Metrics` порт операцию `set(...)` для gauge-like current-state сигналов; добавить в `SandboxSessionRepository` `count_active()` как источник truth для `sandbox.active.count`
+- Критерии приемки: ADR занимает 10-20 строк; inner layers по-прежнему знают только порты `Logger`/`Metrics`/`Tracer`; current-state метрика активных sandbox выражается без OTel imports во внутреннем слое
+
+### M20. Трейсы и метрики в sandbox usecases
+
+- Субагент: `feature-developer`
+- Статус: pending
+- Зависимости: `M19`
+- Commit required: yes
+- Commit message: `instrument sandbox usecases`
+- Scope: добавить spans и ключевые lifecycle metrics в `CreateSandbox` и `CleanupExpiredSandboxes`
+- Файлы: `usecase/sandbox.py`, `adapter/di/container.py`, при необходимости тесты в `test/*`
+- Решение: usecase получает `Metrics` и `Tracer` через конструктор; `CreateSandbox` и `CleanupExpiredSandboxes` публикуют `sandbox.create.total`, `sandbox.cleanup.total`, `sandbox.cleanup.error.total` и обновляют `sandbox.active.count` после мутаций registry
+- Критерии приемки: есть spans `usecase.create_sandbox` и `usecase.cleanup_expired_sandboxes`; span attrs и metric attrs включают ключевые lifecycle identifiers/result fields; reuse/replace/cleanup paths наблюдаемы без OTel imports в usecase
+
+### M21. Трейсы и runtime metrics в Docker adapter и reconciliation
+
+- Субагент: `feature-developer`
+- Статус: pending
+- Зависимости: `M19`
+- Commit required: yes
+- Commit message: `instrument sandbox docker runtime`
+- Scope: добавить observability в `DockerSandboxRuntime` и reconciliation path для Docker operations и current-state sync
+- Файлы: `adapter/docker/runtime.py`, `adapter/sandbox/reconciliation.py`, `adapter/di/container.py`, при необходимости тесты в `test/*`
+- Решение: `DockerSandboxRuntime` получает `Metrics` и `Tracer`; create/stop/list публикуют duration histograms `sandbox.runtime.create.duration_ms`, `sandbox.runtime.stop.duration_ms`, `sandbox.runtime.list_active.duration_ms`, error counter `sandbox.runtime.error.total` и span attrs по chat/session/container; reconciliation обновляет `sandbox.active.count` по registry snapshot
+- Критерии приемки: Docker adapter остается во внешнем слое; ошибки Docker операций отражаются в spans и metrics; после startup reconciliation current-state метрика активных sandbox синхронизирована с registry
+
+### M22. Тесты на sandbox observability
+
+- Субагент: `test-engineer`
+- Статус: pending
+- Зависимости: `M20`, `M21`
+- Commit required: yes
+- Commit message: `add sandbox observability tests`
+- Scope: покрыть regression tests новую observability policy без реального OTel backend
+- Файлы: `test/test_sandbox_usecase.py`, `test/test_docker_runtime.py`, при необходимости новые focused tests в `test/*`
+- Решение: использовать типизированные fake metrics/tracer implementations и проверить names/attrs ключевых spans и metrics на create/reuse/replace/cleanup/runtime paths
+- Критерии приемки: тесты подтверждают spans и metrics на usecase и adapter paths; constructor wiring обновлен без mypy regressions; `make typecheck` и релевантный `pytest` проходят
+
+### M23. Boundary review для sandbox observability
+
+- Субагент: `code-reviewer`
+- Статус: pending
+- Зависимости: `M22`
+- Commit required: no
+- Scope: проверить, что observability изменения закрывают issue #11 и FR-034 без нарушения clean architecture
+- Файлы: весь измененный код после `M19`-`M22`
+- Критерии приемки: inner layers не импортируют OTel; Docker-specific tracing остается в `adapter/docker/`; current-state и duration metrics достаточно покрывают sandbox lifecycle; замечания сведены к minor или отсутствуют