fix(onboard): reject the reserved Hermes API port as the dashboard port

[rluo8]

Summary

NemoHermes onboarding accepted NEMOCLAW_DASHBOARD_PORT=8642 (the port reserved for the Hermes OpenAI-compatible API) and built the sandbox instead of failing the security check. This adds a host-side guard that rejects the reserved port before any sandbox is created.

Related Issue

Fixes #4984

Changes

• Reject a dashboard port equal to the Hermes OpenAI-compatible API port (8642) in resolveHermesDashboardOnboardState (src/lib/onboard/hermes-dashboard.ts), emitting [SECURITY] Invalid Hermes dashboard port 8642 - reserved for the Hermes OpenAI-compatible API and exiting non-zero before sandbox creation — the same message as the in-sandbox guard in agents/hermes/start.sh.
• Cover both entry points that can set the dashboard port to 8642: the resolved effectivePort (--control-ui-port, CHAT_UI_URL, or a persisted registry port) and the raw NEMOCLAW_DASHBOARD_PORT env (which the host otherwise silently drops to the agent default, so effectivePort alone would miss it).
• Add unit tests for both entry points plus the no-override and non-hermes cases; update two existing tests that passed 8642 as a placeholder dashboard port (it is the reserved API port, never a valid dashboard port) to the realistic 18789.

Type of Change

• [√] Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• [√] npx prek run --all-files passes
• [√] npm test passes
• [√] Tests added or updated for new or changed behavior
• [√] No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: rluo8 ruluo@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Added validation to prevent dashboard port configuration to the reserved Hermes API port (8642), with explicit security error messaging when this occurs.
  • Validation checks both environment variable overrides and computed port resolution from configuration.

• Tests

  • Updated dashboard onboarding tests to validate reserved port rejection behavior and reflect realistic port configurations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9ad6bb0e-0f93-451b-9d0b-41b44368d04f

📥 Commits

Reviewing files that changed from the base of the PR and between ab983f2 and 81854a4.

📒 Files selected for processing (2)

• src/lib/onboard/hermes-dashboard.test.ts
• src/lib/onboard/hermes-dashboard.ts

---

📝 Walkthrough

Walkthrough

This PR hardens Hermes onboarding against port 8642 (reserved for the OpenAI-compatible API) being used as a dashboard port. It adds a reserved-port constant and pre-sandbox validation that checks both the effective port and environment override, plus comprehensive test coverage including whitespace handling and control UI derivation.

Changes

Reserved Port Validation and Testing

Layer / File(s)	Summary
Reserved port constant and validation logic src/lib/onboard/hermes-dashboard.ts	Introduces HERMES_OPENAI_API_PORT constant (8642) and extends resolveHermesDashboardOnboardState with pre-sandbox validation that rejects configurations where either the effective dashboard port or raw NEMOCLAW_DASHBOARD_PORT environment override equals 8642, producing a [SECURITY] error.
Test coverage for reserved port validation src/lib/onboard/hermes-dashboard.test.ts	Updates existing drift-tracking and rollback tests to use realistic port 18789; adds new test cases verifying rejection of port 8642 from environment variables (including whitespace-padded values), derivation via control UI inputs with empty raw env, acceptance of non-reserved ports, and exclusion of the guard for non-Hermes agents.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4931: Updates resolveHermesDashboardOnboardState to reject dashboard configurations when a port collides with the Hermes API effective port.

Suggested labels

integration: hermes, area: onboarding, bug-fix, v0.0.61

Suggested reviewers

• cv

Poem

🐰 A port in the night, 8642 bright,
Was taken for dash, but it's API's right!
We validate now, with a [SECURITY] cry,
No sandbox for you with that port—goodbye! 🔐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly summarizes the main change: rejecting the reserved Hermes API port (8642) as the dashboard port, which is the primary objective of the PR.
Linked Issues check	✅ Passed	The PR fully addresses issue #4984 by implementing reserved-port validation in resolveHermesDashboardOnboardState, rejecting port 8642 with a [SECURITY] error message and non-zero exit before sandbox creation.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the reserved-port guard: validation logic in hermes-dashboard.ts and comprehensive test coverage in hermes-dashboard.test.ts with no unrelated modifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}