fix(onboard): persist the bumped dashboard port in the machine handler path (#8214)

[jason-ma-nv]

Summary

When port 18789 is already taken by another sandbox, the onboard machine handler allocates a bumped dashboard port (for example, 18791) and the dashboard starts there—but nemoclaw <sandbox> dashboard-url --quiet returned http://127.0.0.1:18789 (the default), so dashboard HTTP probes failed with ECONNREFUSED.

Root cause: In the machine handler path, src/lib/onboard/machine/handlers/agent-setup.ts called ensureAgentDashboardForward(sandboxName, agent) and discarded its return value—the actual, possibly bumped port—so the sandbox registry dashboardPort field kept the default. The old onboard.ts path persisted the returned port (dashboardPort: actualDashboardPort); the machine handler path regressed it.

Fixes #8214.

Changes

• src/lib/onboard/machine/handlers/agent-setup.ts: capture ensureAgentDashboardForward's returned port and, when the agent manages a dashboard (port > 0), persist it through a new persistDashboardPort dependency.
• src/lib/onboard.ts: wire persistDashboardPort to registry.updateSandbox(name, { dashboardPort: port }).
• src/lib/onboard/machine/handlers/agent-setup.test.ts: add tests that a bumped port is persisted and a no-dashboard agent (port 0) persists nothing.
• src/lib/onboard/machine/handlers/finalization.ts: persist a positive port selected when final recovery reconciles the dashboard forward, using the same registry callback as agent setup.
• test/helpers/onboard-final-flow-phases.ts: provide the new dependency in the shared agent-setup dependency fixture.
• test/onboard-fsm-live-slices.test.ts: cover the production-composed path from collision-selected port allocation through post-recovery reallocation, registry persistence, and dashboard-url output.

Verification

Run on the Ubuntu host (npm ci + plugin build, Node 22), against a clean clone of this branch:

• npm run typecheck:cli → exit 0.
• Affected suites with the fix: agent-setup.test.ts, finalization.test.ts, final-flow-phases.runtime.test.ts → 42 passed; test/credential-migration-reconciliation.test.ts → 2 passed.
• Reverting only the handler source, keeping the tests: the persists the bumped dashboard port (#8214) test fails (persistDashboardPort not called)—the discarded-return regression, reproduced by driving the real handleAgentSetupState handler.
• Advisor regression coverage: the first composed regression and related suites passed 22 tests. The post-recovery follow-up passed 48 targeted tests, including a composed forward change from 18791 to 18792 with the registry and dashboard-url reporting 18792.
• Biome, test-title validation, and git diff --check passed.
• Normal pre-commit and pre-push hooks passed, including repository checks and CLI type-checking.

The revert run confirms the test exercises the real handler path rather than hand-built state; the passing runs confirm the live port is persisted and returned.

Documentation

No user-visible surface change. This restores correct dashboard-url output on multi-sandbox onboarding, matching documented behavior. No documentation update is required.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: No documentation change is needed. Commit 36be2b2f2 restores the documented dashboard-port contract by recording the positive port selected after final onboarding recovery. Existing documentation already explains next-free dashboard-port selection and recorded dashboard URLs for OpenClaw and Hermes. Agent-variant and route checks passed, and 48 focused tests passed.
• Agent: Codex Desktop

Signed-off-by: Jason Ma jama@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Agent dashboard connection details are now retained during setup and finalization when a valid dashboard port is available.
  • Dashboard port information is skipped when no valid port is returned.
  • Dashboard URLs now reflect the retained connection details after onboarding.

[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: 783c9c74-ada1-4fe7-96ef-d2cfca21f23e

📥 Commits

Reviewing files that changed from the base of the PR and between 8ef2511 and 36be2b2.

📒 Files selected for processing (6)

• src/lib/onboard.ts
• src/lib/onboard/machine/final-flow-phases.ts
• src/lib/onboard/machine/handlers/finalization.test.ts
• src/lib/onboard/machine/handlers/finalization.ts
• test/credential-migration-reconciliation.test.ts
• test/onboard-fsm-live-slices.test.ts

💤 Files with no reviewable changes (1)

• src/lib/onboard.ts

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

• test/onboard-fsm-live-slices.test.ts

---

📝 Walkthrough

Walkthrough

The onboarding machine handler now captures the dashboard port returned by ensureAgentDashboardForward and persists it in the sandbox registry. Agent setup stores the port directly. Finalization receives the persistence dependency through object merging and also stores the forwarding result. Unit tests verify persistence behavior. An end-to-end test validates the complete port propagation and dashboard URL generation.

Changes

Dashboard port persistence

Layer / File(s)	Summary
Agent setup port capture src/lib/onboard/machine/handlers/agent-setup.ts, src/lib/onboard.ts	Agent setup receives a persistDashboardPort dependency, captures the dashboard port returned by ensureAgentDashboardForward, and persists positive port values through the sandbox registry wiring.
Agent setup persistence tests src/lib/onboard/machine/handlers/agent-setup.test.ts, test/helpers/onboard-final-flow-phases.ts	Tests mock persistDashboardPort and verify that positive ports are persisted and persistence is skipped when an agent has no managed dashboard.
Finalization port capture and dependency merging src/lib/onboard/machine/final-flow-phases.ts, src/lib/onboard/machine/handlers/finalization.ts	Finalization receives agentSetupDeps.persistDashboardPort through dependency object merging. The finalization handler captures the dashboard port returned by ensureAgentDashboardForward and persists positive values. The finalization options type excludes persistDashboardPort from public dependencies since agent setup provides it internally.
Finalization persistence tests src/lib/onboard/machine/handlers/finalization.test.ts, test/credential-migration-reconciliation.test.ts	Tests mock persistDashboardPort and verify that finalization persists positive forwarding ports and skips persistence when forwarding returns zero.
Dashboard port composition end-to-end test test/onboard-fsm-live-slices.test.ts	A live-slice probe scenario runs agent setup and finalization in sequence. Mocks return deterministic ports on successive calls. The test verifies the final registry port and dashboard URL contain the bumped port expected from the forwarding sequence.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested labels: bug-fix, area: onboarding, area: sandbox, v0.0.101

Suggested reviewers: apurvvkumaria, cv

🚥 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 clearly identifies the onboarding fix that persists the bumped dashboard port.
Linked Issues check	✅ Passed	The changes capture and persist the allocated dashboard port, including tests for bumped ports and agents without dashboards, satisfying #8214.
Out of Scope Changes check	✅ Passed	All production, dependency, fixture, and test changes directly support dashboard-port persistence for #8214.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/8214-dashboard-port

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 36be2b2 in the fix/8214-dashboard-p... branch remains at 96%, unchanged from commit 3a7899f in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 36be2b2 in the fix/8214-dashboard-p... branch remains at 81%, unchanged from commit bef5d0b in the main branch.

Show a code coverage summary of the most impacted files.

File	main bef5d0b	fix/8214-dashboard-p... 36be2b2	+/-
src/lib/onboard...ntime-create.ts	100%	0%	-100%
src/lib/onboard...cker-runtime.ts	52%	2%	-50%
src/lib/onboard...ndbox-create.ts	87%	78%	-9%
src/lib/onboard...shared-state.ts	79%	73%	-6%
src/lib/onboard...shboard-port.ts	96%	90%	-6%
src/lib/policy/...ne-exclusion.ts	96%	92%	-4%
src/lib/shields/index.ts	68%	68%	0%
src/lib/onboard...trap/adapter.ts	68%	69%	+1%
src/lib/onboard...press-resume.ts	76%	78%	+2%
src/lib/actions...andbox/start.ts	73%	86%	+13%

---

_{Updated August 04, 2026 16:04 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections differ; severity counts match.

1 terminology difference from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• dashboard port composition at test/onboard-fsm-live-slices.test.ts:24: selected only by the second-opinion lane as established.

2 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• ubuntu-repo-cloud-openclaw: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• ubuntu-repo-docker-post-reboot-recovery: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

2 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — bumped dashboard port at src/lib/onboard/machine/handlers/agent-setup.test.ts:106: Keep “bumped dashboard port”; the modifier distinguishes collision-selected ports from the default port.
• justified — post-recovery dashboard port at test/onboard-fsm-live-slices.test.ts:547: Keep “post-recovery dashboard port”; the modifier identifies the lifecycle point that determines the persisted port.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, onboard-repair, onboard-resume

1 optional E2E recommendation

• concurrent-gateway-ports

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[cjagwani]

Reviewed exact head 36be2b2f2991aff652b4e474c079fbc89d28f87b against #8214 and the existing dashboard-forward contract.

The machine path now preserves the actual positive port returned by dashboard-forward reconciliation in both agent setup and post-recovery finalization. Wiring the single registry callback through agentSetupDeps keeps both phases consistent, and the tests cover bumped ports, no-dashboard/zero-port behavior, the production composition, the second post-recovery reallocation, and the final dashboard-url output. I found no credential, policy, command-execution, or trust-boundary regression in the changed paths.

Approved. The exact-head selected E2E gate is still in progress and must complete successfully before merge; the old cancelled duplicate commit-lint receipt is not a code failure.