fix: add native lifecycle-aware health endpoint

[RaviTharuma]

Summary

• add a native unauthenticated GET/HEAD /healthz endpoint
• report 503 during startup and graceful shutdown, and 200 only after initialization
• bypass centralized auth without database or provider dependencies
• add focused lifecycle and auth-matcher regression tests

Validation

• node --import tsx/esm --test tests/unit/healthz-route.test.ts
• npm run typecheck:core
• focused ESLint and git diff --check

Closes #7848

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request introduces a new /healthz endpoint to track and expose the server's lifecycle phases (starting, ready, and stopping) using a global state manager. It integrates lifecycle hooks into the Node.js instrumentation startup and graceful shutdown processes, and adds comprehensive unit tests. The reviewer points out a critical issue where the /healthz route handler might be statically optimized and cached by Next.js at build time, and suggests adding export const dynamic = "force-dynamic"; to ensure it is always executed dynamically at runtime.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[RaviTharuma]

Addressed the static-optimization finding in b5481c9: /healthz now exports dynamic = "force-dynamic", and the lifecycle regression test asserts the route remains dynamic. Focused tests, core typecheck, ESLint, Prettier, and diff checks pass.

[diegosouzapw]

Thanks for this — clean, focused implementation that matches what #7848 asked for closely: unauthenticated /healthz, 503 during start/stop, 200 only once registerNodejs() finishes, zero DB/provider I/O at request time, and a nice regression test that proves the auth-bypass claim against the real Next.js middleware matcher instead of just asserting on a string.

I ran the PR's test in isolation and it's 3/3 green; the CI red on this PR (Fast Quality Gates, ESLint, Unit Tests fast-path, dast-smoke) all trace back to a pre-existing base issue unrelated to this diff — ReferenceError: TICK_MS is not defined in src/lib/tokenHealthCheck.ts:285, reproducible on release/v3.8.49 before your commit — so none of that is on you; we'll land the base fix separately and this should go green on rebase.

A couple of small optional nits, non-blocking:

• src/app/api/health/ping/route.ts (same category of endpoint in this repo) explicitly sets export const dynamic = "force-dynamic";. Next 16 already defaults GET route handlers to dynamic, so this probably isn't a live bug, but matching that convention would be cheap insurance against ever baking the 503-during-startup response into a build-time cache.
• The issue asked for "documented readiness/liveness semantics" — a short docs note on the /healthz contract would close that out fully.
• A changelog.d/features/7848-native-healthz.md fragment per this repo's changelog convention.

None of these block the merge; happy to add them directly if you'd rather not touch the branch again.

[diegosouzapw]

Merged — thanks @RaviTharuma! The lifecycle-aware /healthz endpoint is a clean addition and the test coverage made it an easy call. Validated in the local merge-train (14-PR combined tree, full unit suite + vitest green) on tomni-proxmox-113 @ 0fda37bb4fdb26ba1345fd7b4cac44fbe235cda4, then squash-merged.