Summary

• Problem: when the Control UI is mounted at /, the SPA request classifier can still claim /health, /healthz, /ready, and /readyz before the gateway probe handler runs.
• Why it matters: deployment probes can receive Control UI fallback responses instead of the machine probe payload, which keeps [Bug]: /health and /healthz can return Control UI HTML 200 instead of machine health payload #18446 reproducible even after Gateway: add healthz/readyz probe endpoints for container checks #31272 landed.
• What changed: root-mounted Control UI classification now explicitly leaves the four probe routes outside the SPA catch-all, and regression tests cover both probe reachability and plugin precedence on probe paths.
• What did NOT change (scope boundary): no deep readiness semantics, no auth model changes, and no route-order reversal that would shadow plugin-owned probe paths.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: /health and /healthz can return Control UI HTML 200 instead of machine health payload #18446
• Related Gateway: add healthz/readyz probe endpoints for container checks #31272

User-visible / Behavior Changes

• /health, /healthz, /ready, and /readyz stay reachable even when the Control UI is mounted at /.
• Plugin-owned routes mounted on probe paths still keep precedence, matching the compatibility behavior from Gateway: add healthz/readyz probe endpoints for container checks #31272.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22
• Model/provider: N/A
• Integration/channel (if any): gateway HTTP server
• Relevant config (redacted): root-mounted Control UI (gateway.controlUi.basePath = "/" equivalent normalization to empty base path)

Steps

1. Start the gateway with Control UI mounted at /.
2. Request /healthz and /readyz.
3. Mount a plugin handler on /healthz and request it again.

Expected

• Probe paths return the gateway probe JSON when unclaimed.
• Plugin handlers on probe paths still win when explicitly registered.

Actual

• Matches expected.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Root-mounted Control UI no longer swallows /health, /healthz, /ready, or /readyz.
  • Plugin handlers mounted on /healthz still keep precedence.
• Edge cases checked:
  • Existing non-probe root-mounted Control UI fallthrough behavior remains intact.
• What you did not verify:
  • Full end-to-end deploy on Render/Kubernetes in this PR.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert the two commits in this PR.
• Files/config to restore:
  • src/gateway/control-ui-routing.ts
  • src/gateway/server.plugin-http-auth.test.ts
  • CHANGELOG.md
• Known bad symptoms reviewers should watch for:
  • Root-mounted Control UI starts serving probe paths again.
  • Plugin routes mounted on /healthz stop taking precedence.

Risks and Mitigations

• Risk: root-mounted Control UI path classification grows another special-case allowlist.
  • Mitigation: keep the allowlist limited to the four built-in probe paths and cover it with regression tests.