[RaviTharuma]

Summary

• Document the two HTTP health surfaces: stock GET /healthz (lifecycle) vs GET /api/monitoring/health (deep).
• Add Kubernetes probe recommendations: TCP liveness (or soft HTTP /healthz), HTTP readiness on /healthz, do not point kubelet liveness at /api/monitoring/health.
• Note that both routes share the Node event loop — busy ≠ dead — and link fix(ops): /healthz (and other HTTP) times out while event loop is busy (k8s probes flap) #10052 / fix(api): GET /v1/models pegs event loop — getModelsDevPricing re-reads per model #9685 / fix(models): memoize getModelsDevPricing (event loop / healthz) #10055 / perf(compression): countTextTokens blocks the event loop on large Codex payloads (worker wedge) #10117.
• Cross-link from the Docker guide so operators do not copy Docker HEALTHCHECK into kubelet liveness.

Related Issues

• Related to fix(ops): /healthz (and other HTTP) times out while event loop is busy (k8s probes flap) #10052 (probe timeouts while event loop busy)
• Related to fix(api): GET /v1/models pegs event loop — getModelsDevPricing re-reads per model #9685 / fix(models): memoize getModelsDevPricing (event loop / healthz) #10055 (catalog pricing hog)
• Related to perf(compression): countTextTokens blocks the event loop on large Codex payloads (worker wedge) #10117 (compression token-count hog)
• Related to release(v3.8.51): publish a versioned image containing the /v1/models event-loop fix #10296 (stable channel still on 3.8.49)

Validation

• Docs-only change (no production code)
• npm run lint N/A for markdown-only
• Production-code changes include a new or updated automated test in this PR — N/A (docs only)
• SonarQube PR analysis is green or any remaining issues are explicitly documented below

Tests Added Or Updated

• No production code changed; no automated tests added.

Coverage Notes

• Docs-only; no src/ / open-sse/ / electron/ / bin/ coverage impact.

Reviewer Notes

• Docs only. Does not fix event-loop hogs; gives operators a safer probe layout until SemVer images ship the code fixes.
• English docs updated (docs/ops/MONITORING_GUIDE.md, docs/guides/DOCKER_GUIDE.md). No secrets or private hostnames.

[diegosouzapw]

Thanks for this, @RaviTharuma — really useful writeup. I checked the two routes against the current source and everything you describe matches exactly: /healthz is the lifecycle-only check (no DB touch, ok/starting/stopping), and /api/monitoring/health really is the heavy path the Docker HEALTHCHECK already targets. Tying this back to #10052/#9685/#10055/#10117 makes the "why" clear for anyone hitting flapping liveness probes.

Content-wise this is good to merge as-is — no changes requested there. The only thing blocking it right now is CI: the "Merge integrity (changelog + generated skills)" job is red because the omni-settings skill's generated file drifted on the base branch after this PR was opened, unrelated to your diff (you don't touch anything under skills/). A rebase/merge from the current release/v3.8.50 tip should clear that automatically once CI re-runs.

Nice catch calling out that both routes share the same event loop — that's the detail that actually explains the false-kill reports.

[diegosouzapw]

Babysit summary

• Fix: refresh-merge origin/release/v3.8.50 into the PR head → merged as 8c84462134.
• Gate cleared: Merge integrity (changelog + generated skills) went FAILURE → SUCCESS. The failure was stale — the docs gate re-runs on the current merge-result, and the head was 76 commits behind the (green) release/v3.8.50 tip. A refresh-merge alone cleared it; zero production-code lines changed.
• Docs gate: npm run check:docs-all passes locally on the merged tree (doc-links + fabricated-docs clean). The few stale-version drift hits are upstream-tool version notes at the base tip, rebaselined at release — not hard failures.
• Final checks: Docs Gates, Merge integrity, Change Classification, semgrep, semgrep-cloud-platform all pass; build/unit/vitest/eslint are fast-path-skipped for this docs-only PR.
• Ready for human review & merge.

[diegosouzapw]

Validated in local merge-train .claude/worktrees/merge-train-20260816-002347-suite.log (train7, 8be62df6) / train8 1e5c976f on devbox-vm-06-dev002 (FAST gates green: static + changed tests + vitest; daily full-suite run still required). Merged under batch merge-train protocol (merge-gates §7). ⚠️ base-red inherited: #10523 (ServiceSupervisor order-dependent test, unrelated to this batch).