feat(health): add internal HTTP health endpoint for Docker/orchestrators

[iagorobo24-hub]

Description of changes

Adds an internal HTTP health server (src/health/server.ts) exposing three endpoints on configurable port (default 3100, BOT_HEALTH_PORT, 0 to disable):

• GET /health/live — Liveness probe (process alive), always 200, no dependency checks
• GET /health/ready — Readiness probe, 200 if healthy, 503 if degraded (OpenCode down)
• GET /health — Full health payload: {status, version, uptimeSeconds, checks: {process, opencode}}, always 200 with status field (Docker healthcheck convention)

Integrated into app lifecycle (start-bot-app.ts): starts after settings load, stops on shutdown signals. Used by Docker HEALTHCHECK in docker-compose.yml and by hermes-ops via health.type: http.

Docker healthcheck reads BOT_HEALTH_PORT env var:

• Default 3100 → checks http://127.0.0.1:3100/health
• Custom port (e.g. 3200) → checks that port
• 0 → health server disabled, healthcheck exits 0 (container stays healthy)

Motivation

• Docker: Current compose has no native healthcheck; hermes-ops reports UNKNOWN because bot doesn't expose health.
• Observability: Detects process liveness (/live) + OpenCode dependency (/ready, /health) in standard endpoints.
• Orchestrators: Standard /health/live + /health/ready for Kubernetes/Docker Compose/swarm.

Design choices

• Binds only to 127.0.0.1 (loopback) — safe with network_mode: host.
• Uses native fetch (Node 22) — no extra deps (curl/wget not in slim image).
• Returns degraded (not unhealthy) when OpenCode is down — bot process is alive, can recover automatically.
• Version/uptime in payload for debugging.
• checks.process (liveness) + checks.opencode (dependency) — no false "event loop" claim.

How it was tested

• npm run lint ✅
• npm run build ✅
• npm test ✅ (2 pre-existing flaky failures in event-subscription-service.lifecycle unrelated)
• Local Docker build + run:
  • Default 3100 → healthy
  • Custom BOT_HEALTH_PORT=3200 → healthcheck uses 3200, healthy
  • BOT_HEALTH_PORT=0 → server disabled, healthcheck exits 0, container stays healthy
• Simulated OpenCode down → /health returns degraded, /health/ready returns 503

Checklist

• PR title follows Conventional Commits
• This PR contains one logically complete change
• Branch is rebased on the latest main
• I ran npm run lint, npm run build, and npm test
• Behavior/limitations for Linux/macOS/Windows described (binds 127.0.0.1 only)
• Docker healthcheck respects BOT_HEALTH_PORT, 0 disables server and passes
• docker compose config validates (exit 0)

[grinev]

@iagorobo24-hub thanks for the PR, I reviewed it and requesting some changes before merge:

Major — src/config.ts:38-50

BOT_HEALTH_PORT values greater than 65535 are accepted by the configuration parser. For example, BOT_HEALTH_PORT=65536 reaches
startHealthServer(), and server.listen() throws ERR_SOCKET_BAD_PORT, so the whole bot fails during startup.

Please validate the port range as 0..65535. Value 0 should keep its special meaning and disable the server. Please also add a test for
values above 65535.

Minor — README.md:211-253, 480-484

BOT_HEALTH_PORT is documented in .env.example, but it is missing from the README environment variable table and Docker configuration
section. Users following the main documentation will not know about the default port or the value 0 that disables the server.

Please add this variable to the README documentation.

Minor — src/health/server.ts:124-130

If server.listen() fails, the module keeps the created server object in the global server variable. A later startHealthServer() call
then reports that the server is already running and does not retry the startup.

Please reset server and startTimeMs when the listen operation fails, so a retry is possible.