fix(onboard): align Hermes WebUI port

[ogarciarevett]

Summary

Hermes WebUI onboarding now treats the resolved NemoClaw dashboard port as the single public WebUI port, so NEMOCLAW_DASHBOARD_PORT=9119 or --control-ui-port 9119 no longer trips a false Hermes API-port collision. The legacy NEMOCLAW_HERMES_DASHBOARD_PORT value is accepted only when it matches that public OpenShell forward, preventing a host/sandbox port mismatch that cannot serve the WebUI.

Related Issue

Fixes #6277

Changes

• Normalize enabled Hermes dashboard state to the effective NemoClaw dashboard/OpenShell forward port.
• Replace misleading “Hermes API port” collision errors with Hermes WebUI/OpenShell-forward specific validation.
• Add regression coverage for #6277 covering 9119, matching legacy alias, and mismatched alias rejection.

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)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: existing docs already describe NEMOCLAW_DASHBOARD_PORT as the Hermes built-in dashboard/WebUI forward; this fixes implementation drift.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: focused onboarding port-state self-review; the change keeps the existing reserved 8642 API guard, does not touch credentials/policies, and constrains Hermes WebUI public port state to the already validated OpenShell dashboard forward.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: RED npx vitest run --project cli src/lib/onboard/hermes-dashboard.test.ts failed on the false API-port collision and mismatch cases; GREEN npx vitest run --project cli src/lib/onboard/hermes-dashboard.test.ts; neighbor coverage npx vitest run --project cli src/lib/onboard/hermes-dashboard.test.ts src/lib/onboard/sandbox-create-launch.test.ts src/lib/onboard/sandbox-reuse.test.ts src/lib/hermes-dashboard.test.ts src/lib/agent/onboard.test.ts src/lib/onboard/dashboard-preflight-ports.test.ts passed 48 tests.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• 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: ogarciarevett ogarciarevett@gmail.com

Summary by CodeRabbit

• Bug Fixes

  • Improved Hermes dashboard onboarding port handling: the effective WebUI public port is always used, legacy port aliases are validated for exact matches, and clearer guidance is shown when configurations don’t align.
  • Refined port collision/overlap validation and reserved-port checks.
  • Updated dashboard forwarding behavior to prefer recorded sandbox dashboard ports, preserve the correct forwarded URL/port set on refresh, and avoid duplicate “additional port” instructions.

• Tests

  • Expanded onboarding, Hermes UI URL selection, and dashboard-forwarding test coverage to match the new effective-port precedence and output expectations.

[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.

[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

📝 Walkthrough

Walkthrough

The Hermes dashboard onboarding flow now propagates the effective dashboard port through preflight, forwarding, and UI printing. Hermes validation and tests were updated to use the effective dashboard port for WebUI checks and error handling.

Changes

Hermes dashboard port propagation

Layer / File(s)	Summary
Preflight port source src/lib/onboard.ts, src/lib/actions/sandbox/forward-recovery.ts, test/process-recovery-primitives.test.ts	sandbox.controlUiPort now uses the preflight dashboard port, and sandbox dashboard-port recovery now prefers recorded sandbox metadata before the active agent port.
Effective dashboard port wiring src/lib/onboard/dashboard.ts, src/lib/agent/onboard.ts, src/lib/agent/dashboard-ui.ts, src/lib/agent/onboard.test.ts, test/onboard-dashboard.test.ts	effectiveDashboardPort is threaded into dashboard URL rendering and optional dashboard UI printing, with updated port selection, duplicate-port skipping, and coverage for the new port handling.
Agent dashboard forwarding src/lib/onboard/agent-dashboard-forward.ts, src/lib/onboard/agent-dashboard-forward.test.ts	Agent dashboard forwarding now accepts chatUiUrl, preserves selected ports, sets CHAT_UI_URL from the forwarded URL, and has updated tests for the new forwarding behavior.
Hermes dashboard validation and tests src/lib/onboard/hermes-dashboard.ts, src/lib/onboard/hermes-dashboard.test.ts	Hermes onboarding validation now aligns the WebUI port with the effective dashboard port, updates reserved-port messaging, and refreshes the corresponding tests.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs: #6277

Suggested labels: bug-fix

Suggested reviewers: ericksoa, jyaunches

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and matches the main Hermes WebUI port alignment change.
Linked Issues check	✅ Passed	The changes address #6277 by using the documented dashboard port for Hermes WebUI, keeping API port separate, and fixing the mismatched alias/error behavior.
Out of Scope Changes check	✅ Passed	The added changes stay focused on Hermes dashboard port handling, onboarding, and related forwarding tests without introducing unrelated functionality.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[cv]

Correctness blocker: runtime uses effectivePort, but final dashboard access output still derives its URL from the legacy alias or default 9119. NEMOCLAW_DASHBOARD_PORT=9120 or --control-ui-port 9120 forwards 9120 while advertising 9119. Failure guidance also points users to a legacy alias now required to match. Carry effectivePort through all output and guidance, and cover nondefault canonical-port cases.

[wscurran]

✨ Thanks for the PR. This fixes the Hermes WebUI onboarding port collision by aligning the resolved NemoClaw dashboard port as the single public WebUI port. Ready for maintainer review.

---

Related open issues:

• #6277 [Hermes] Cannot set port for Web dashboard/TUI

---

Related open issues:

• #6277 [Hermes] Cannot set port for Web dashboard/TUI

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/agent/onboard.ts (1)

404-423: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicate port-validation logic; consider a shared helper.

This inline Number.isInteger(...) && ... >= 1 && ... <= 65535 check re-implements the same rule already expressed as isValidPort in src/lib/agent/dashboard-ui.ts and src/lib/onboard/agent-dashboard-forward.ts. Extracting a single shared isValidPort utility and reusing it here would reduce the risk of the three copies drifting apart.

♻️ Proposed refactor sketch

-  const effectiveDashboardPort =
-    Number.isInteger(deps.effectiveDashboardPort) &&
-    Number(deps.effectiveDashboardPort) >= 1 &&
-    Number(deps.effectiveDashboardPort) <= 65535
-      ? Number(deps.effectiveDashboardPort)
-      : info.port;
+  const effectiveDashboardPort = isValidPort(deps.effectiveDashboardPort)
+    ? deps.effectiveDashboardPort
+    : info.port;

(where isValidPort is imported from a shared module used by dashboard-ui.ts and agent-dashboard-forward.ts.)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/agent/onboard.ts` around lines 404 - 423, The port validation in
printDashboardUi is duplicated and should reuse the shared isValidPort rule
instead of re-implementing the numeric range check inline. Move or import the
common helper used by dashboard-ui.ts and agent-dashboard-forward.ts, then
replace the Number.isInteger/1..65535 logic with that helper for
effectiveDashboardPort. Keep the fallback to info.port unchanged so all
dashboard port validation stays consistent across the agent onboarding flow.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/agent/onboard.ts`:
- Around line 404-423: The port validation in printDashboardUi is duplicated and
should reuse the shared isValidPort rule instead of re-implementing the numeric
range check inline. Move or import the common helper used by dashboard-ui.ts and
agent-dashboard-forward.ts, then replace the Number.isInteger/1..65535 logic
with that helper for effectiveDashboardPort. Keep the fallback to info.port
unchanged so all dashboard port validation stays consistent across the agent
onboarding flow.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bce257d0-59c2-4538-a6f9-9f0bd0ed4d5a

📥 Commits

Reviewing files that changed from the base of the PR and between b4d633b and f28567a.

📒 Files selected for processing (12)

• src/lib/actions/sandbox/forward-recovery.ts
• src/lib/agent/dashboard-ui.ts
• src/lib/agent/onboard.test.ts
• src/lib/agent/onboard.ts
• src/lib/onboard.ts
• src/lib/onboard/agent-dashboard-forward.test.ts
• src/lib/onboard/agent-dashboard-forward.ts
• src/lib/onboard/dashboard.ts
• src/lib/onboard/hermes-dashboard.test.ts
• src/lib/onboard/hermes-dashboard.ts
• test/onboard-dashboard.test.ts
• test/process-recovery-primitives.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

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

[cjagwani]

Approved exact verified head eff896b5d717cab69c847c0b55933a32f9b9b415. The original correctness blocker is resolved: the effective dashboard port is carried through preflight, forward creation, printed access URLs, registry-backed recovery, and optional Hermes WebUI forwarding, while the fixed Hermes API port remains distinct. Matching/mismatched legacy aliases, nondefault canonical ports, forward preservation/reallocation, recovery, and output are covered. All 30 exact-head checks are green; no major advisor findings remain.

[cjagwani]

@cv The exact head remains eff896b5d717cab69c847c0b55933a32f9b9b415, all 30 checks are green, and your original advertised-port blocker is resolved across preflight, forward creation, printed URL, and registry recovery. I approved that exact head after focused verification; GitHub still holds the older change-request review, and auto-merge is now armed by another maintainer. Please re-review or dismiss the stale blocker when you have a moment.