# Healthcheck — Phase 6

Проверенная готовность доступна через `scripts/server.sh` с теми же абсолютными
MC_ROOT/MC_RELEASE_DIR и host settings, что описаны в [runtime.md](runtime.md).

```bash
export MC_ROOT=/absolute/server-root
export MC_RELEASE_DIR=/absolute/full-release
scripts/server.sh up -d --wait --wait-timeout 120
# Проверить уже созданный контейнер без запуска/перезапуска:
scripts/server.sh health --wait-timeout 120
# Первый запуск с загрузкой dependencies может требовать больше времени:
scripts/server.sh up --wait --wait-timeout 600
```

`up/start/restart --wait` и `health` возвращают 0 только после штатного Docker
healthcheck `mc-health` и свежих успешных Minecraft status queries. Running
container и TCP connect сами по себе не подтверждают готовность.

По умолчанию окно стабильности — 10 секунд. На всём окне должны проходить
queries, контейнер не должен меняться или перезапускаться. Неудачный query
или health status, отличный от healthy, сбрасывает окно; проверки повторяются
до deadline. Пример с явно выбранным окном:

```bash
scripts/server.sh health --wait-timeout 30 --stable-seconds 3
scripts/server.sh restart --wait --wait-timeout 120 --stable-seconds 10
```

Timeout — целое положительное число секунд; он должен быть больше окна
стабильности. Если флаг не задан, берётся `deploy.healthcheck_timeout` из
`platform/config.yaml` (сейчас 120). Timeout учитывает Compose launch и
ожидание readiness; проверка входных данных и сбор диагностических логов
выполняются отдельно. Docker queries ограничены оставшимся временем, отдельный
status query — также максимум 10 секундами. Опрос выполняется примерно раз
в секунду. `up --wait` запускается detached; сочетание с attach/abort options
отклоняется. Флаги поддерживают и `--wait-timeout=120`.

Обычный `up -d` без `--wait` по-прежнему означает только запуск Compose и
не гарантирует готовность. Backup resume из Phase 5 использует `up --wait`
и теперь проходит новую проверку перед возвращением success.

## Ошибки и сохранённые свидетельства

Non-zero возвращается для timeout, crash/exited, paused, restart loop,
замены контейнера, отсутствующего container/healthcheck, ошибки Docker query
и ошибки Compose launch. Наблюдаемый restart или изменение StartedAt/RestartCount
во время ожидания считается нестабильным запуском и завершается ошибкой;
количество перезапусков до начала проверки используется как baseline.

На неудачном запуске выводятся пути:

```text
MC_ROOT/diagnostics/health-TIMESTAMP-UUID.json
MC_ROOT/diagnostics/health-TIMESTAMP-UUID.log
```

Report содержит причину, elapsed/timeout/stability, последнее Docker state
(включая exit code/OOM/restart count), результат последнего status query,
project и SHA256 release manifest. При отказе самого Compose сохраняются
его exit/error/signal; readiness ещё не проверена. Log содержит последние
100 строк Compose logs. Если получение логов тоже не удалось, это записывается
в log. Диагностика имеет mode 600, каталог создаётся с mode 700.

Recovery state сообщает, что runtime и binding сохранены, active release
не переключался, automatic rollback не выполнялся. Поле backup_snapshot
ссылается на snapshot последней записанной backup operation, если он есть;
null не означает, что других snapshots нет. Их можно найти в MC_ROOT/backups.
Healthcheck не удаляет runtime, не распаковывает backup и не переключает релиз.
После timeout контейнер может продолжать startup; исправить причину/увеличить
timeout и повторить `health`. После crash можно запустить тот же релиз через
`up --wait`. При restart loop сначала изучить report/log и остановить сервер
через `scripts/server.sh stop`. Восстановление — [backups.md](backups.md).

Startup и отдельный `health` удерживают общую lifecycle lock до завершения
проверки. Другой wrapper не сможет одновременно выполнить backup/restart/down.
Контейнер другого runtime root отклоняется до запроса игрового протокола.
Прямые Docker/Compose команды и ручное изменение данных обходят эту блокировку.

Это ограниченная проверка готовности после запуска, не постоянно работающий
watchdog. Ручное подключение клиента и состав модов проверяются отдельно;
SSH deployment и переключение active-release используют эту проверку
в Phase 7: [deploy.md](deploy.md).

Реальные проверки crash/restart loop/timeout — [phase6-results.md](phase6-results.md).