fix(onboard): guard reserved Hermes port 8642 for all agents

[rluo8]

Summary

Extends the #4984 reserved-port guard (PR #5015) to all agents, and adds a fail-fast preflight check. The shipped guard was hermes-gated, so a plain nemoclaw onboard (default OpenClaw agent) still accepted NEMOCLAW_DASHBOARD_PORT=8642 — and, being a single-port agent, actually bound host port 8642. That silently breaks a later nemoclaw onboard --agent hermes, whose OpenAI-compatible API must forward 8642 (it warns "cannot be reallocated" but still exits 0, leaving the API unreachable).

Related Issue

Fixes #4984

Changes

• core/ports.ts: add HERMES_OPENAI_API_PORT (8642) and a shared, agent-neutral rejection message RESERVED_HERMES_DASHBOARD_PORT_MESSAGE as the single source of truth for both guards.
• New onboard/preflight-ports.ts: buildRequiredPreflightPorts() (extracted from the inline onboard.ts array) and assertDashboardPortNotReserved().
• onboard.ts preflight ([1/8]) now rejects an explicit reserved dashboard port fast — before gateway/inference — instead of printing "✓ available" and then hard-failing later. Net change to onboard.ts is negative (no growth).
• resolveHermesDashboardOnboardState ([6/8]) rejection made agent-agnostic
  (catches deferred CHAT_UI_URL / persisted-port paths the preflight can't see).
• Message is now agent-neutral ("Invalid dashboard port 8642 - reserved for the
  Hermes OpenAI-compatible API") since the dashboard belongs to whichever agent is onboarding; the reason still names Hermes.
• Tests: new onboard/preflight-ports tests + flipped the non-Hermes guard test.

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

  • Onboarding now rejects the reserved dashboard port 8642 for all agent types (non-Hermes agents no longer bypass this guard).
  • Explicit dashboard-port preflight checks now fail fast when 8642 is provided.
  • Error message standardized to begin with "[SECURITY] Invalid dashboard port 8642..." when the reserved port is used.

• Tests

  • Added/updated tests to assert the reserved-port rejection and required-port preflight behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: c78d2f57-8904-4ec7-ae45-06fc8ffd9351

📥 Commits

Reviewing files that changed from the base of the PR and between 356714c and d071bd6.

📒 Files selected for processing (1)

• src/lib/onboard.ts

---

📝 Walkthrough

Walkthrough

Adds HERMES_OPENAI_API_PORT constant, new preflight-ports helpers and tests, integrates a fail-fast reserved-dashboard-port assertion into onboarding’s required-ports phase, reorders hermes-dashboard validation to run before non-Hermes early-return, and updates tests to assert the shared security message for port 8642.

Changes

Port 8642 Security Validation

Layer / File(s)	Summary
Export reserved-port constant src/lib/core/ports.ts	Adds HERMES_OPENAI_API_PORT = 8642 used by onboarding and tests.
Preflight ports helpers and tests src/lib/onboard/preflight-ports.ts, src/lib/onboard/dashboard-preflight-ports.test.ts	Adds RESERVED_HERMES_DASHBOARD_PORT_MESSAGE, PreflightPort, buildRequiredPreflightPorts, and assertDashboardPortNotReserved; tests verify port list construction and that 8642 triggers the security failure while normal/null ports pass.
Onboard integration of preflight checks src/lib/onboard.ts	Imports assertDashboardPortNotReserved and buildRequiredPreflightPorts; calls assertDashboardPortNotReserved(dashboardPortToCheck) before building required ports and uses buildRequiredPreflightPorts instead of inline array construction.
Hermes dashboard validation reorder and tests src/lib/onboard/hermes-dashboard.ts, src/lib/onboard/hermes-dashboard.test.ts	Moves reserved-port validation (effective and raw env checks) to run before the agentName !== "hermes" early-return and updates tests to expect the standardized [SECURITY] Invalid dashboard port 8642... message (including non-Hermes agent case).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

area: onboarding

Suggested reviewers

• prekshivyas
• sandl99

Poem

🐰 I found a port that shouldn't be blue,
8642 — reserved, who knew?
I hopped to check each onboarding part,
Guarded the port from the very start.
Now safe, the dashboard plays its part.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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 accurately and concisely summarizes the main change: guarding the reserved Hermes port 8642 for all agents during onboarding.
Linked Issues check	✅ Passed	The PR fully addresses issue #4984 objectives: rejects port 8642 for all agents via preflight fail-fast and deferred resolution, uses centralized constants/messages, exits with non-zero status, and adds comprehensive tests.
Out of Scope Changes check	✅ Passed	All changes are directly related to the linked issue: adding reserved port constant, preflight validation helpers, integration into onboarding flow, and test coverage—no unrelated modifications detected.

_{✏️ 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.}

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[wscurran]

✨
Related open PRs:

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

---

Related open issues:

• #4984 [All Platforms][Security] Hermes: NEMOCLAW_DASHBOARD_PORT=8642 not rejected, onboarding proceeds instead of failing security check