fix(state): accept dashboardPort 0 as no dashboard

[laitingsheng]

Summary

The gateway registry parser rejected a persisted dashboardPort of 0 — the value a no-dashboard (dcode) sandbox records — and threw for the entire registry read, so one such row blocked every registry operation (list, onboard, rebuild) and could leave a rebuilt sandbox destroyed and unrecreatable until the file was hand-edited. Registry reads now treat 0 as "no dashboard" (equivalent to null), and registry writes canonicalize either form to null, so one legacy row can no longer fail host-wide parsing and future writes converge on the canonical representation.

Related Issue

Fixes #7020

Changes

• src/lib/state/gateway-registry.ts: parseRegistry accepts a dashboardPort of 0, rejecting only negative, non-integer, or out-of-range values, and normalizes a stored 0 to null in memory so every consumer treats it as no dashboard.
• src/lib/state/registry.ts: registry serialization canonicalizes dashboardPort: 0 to null. An existing on-disk 0 is safe immediately on read and is persisted as null the next time the registry is written.
• src/lib/state/gateway-registry.test.ts: adds a regression test asserting a persisted 0 parses and is surfaced as no dashboard instead of throwing.
• src/lib/onboard/sandbox-registry-metadata.test.ts: verifies a reused dcode sandbox is persisted and listed with dashboardPort: null, and that a later sandbox allocation still sees the dashboard port as available.

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: internal registry-parser and persistence normalization; no user-facing flag, output, or configurable behavior changes.
• 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: parsing and serialization are limited to dashboardPort; path-safety (O_NOFOLLOW, symlink rejection), size-limit, and gateway-identity guards are untouched — maintainer review requested.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes a Signed-off-by: line 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 — contributor validation: npx vitest run src/lib/state/gateway-registry.test.ts → 5/5 passed; adjacent dashboard-port + registry-normalization → 42/42 passed. Current-head remote CLI shards, static checks, type checks, security checks, and installer/plugin suites are green.
• 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Corrected handling of persisted sandboxes configured with dashboardPort: 0, treating them as having no dashboard.
  • Updated validation to allow dashboardPort values from 0 to 65535, while still rejecting out-of-range inputs.
  • Prevented registry listing/allocation from being blocked by a dashboardPort value of 0.
• Tests
  • Added coverage for reused terminal sandboxes and gateway registry behavior when dashboardPort is 0.
• Documentation
  • Documented the persistence normalization of dashboardPort: 0 to “no dashboard” (null).

[coderabbitai]

📝 Walkthrough

Walkthrough

The gateway registry and sandbox persistence now treat dashboardPort: 0 as no dashboard by normalizing it to null, with regression coverage for registry loading, reused sandbox metadata, and port allocation.

Changes

Dashboard port normalization

Layer / File(s)	Summary
Persistence normalization and reused sandbox coverage src/lib/state/registry.ts, src/lib/onboard/sandbox-registry-metadata.test.ts	Persisted dashboard port zero values are converted to null; reused sandbox metadata tests verify registry output and subsequent port allocation.
Registry parser and regression coverage src/lib/state/gateway-registry.ts, src/lib/state/gateway-registry.test.ts	Validation permits ports from 0 through 65535, converts zero to null, preserves non-zero ports, and tests loading a registry containing dashboardPort: 0.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#6711: Touches gateway registry parsing and dashboard port allocation behavior.

Suggested labels: area: sandbox

Suggested reviewers: cv, yimoj

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The parser now accepts 0, normalizes it to null, and the added tests cover the behavior required by #7020.
Out of Scope Changes check	✅ Passed	Changes are limited to the registry fix, regression tests, and matching docs; no unrelated scope is apparent.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: treating dashboardPort 0 as no dashboard in state handling.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

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

---

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

[coderabbitai]

Actionable comments posted: 1

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

Inline comments:
In `@src/lib/state/gateway-registry.test.ts`:
- Line 72: Update the test title in the zero persisted dashboard port case to
end with the issue reference suffix "(`#7020`)", preserving the existing title
text and behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 025b97ef-f55a-482d-9632-aaf598629539

📥 Commits

Reviewing files that changed from the base of the PR and between b528371 and 1b010a7.

📒 Files selected for processing (2)

• src/lib/state/gateway-registry.test.ts
• src/lib/state/gateway-registry.ts

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/registry-dashboa... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main d034b7f	fix/registry-dashboa... 13f2af5	+/-
src/lib/core/pr...mpt-activity.ts	92%	67%	-25%
src/lib/inferen...er-lifecycle.ts	71%	65%	-6%
src/lib/credentials/store.ts	64%	59%	-5%
src/lib/onboard...host-anchors.ts	94%	90%	-4%
src/lib/actions...eway-restart.ts	93%	90%	-3%
src/lib/onboard...u-patch-mode.ts	93%	90%	-3%
src/lib/messagi...flow-planner.ts	93%	93%	0%
src/lib/state/registry.ts	83%	86%	+3%
src/lib/state/g...way-registry.ts	90%	94%	+4%
src/lib/onboard...box-prebuild.ts	69%	88%	+19%

---

_{Updated July 16, 2026 17:22 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

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

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

2 optional E2E recommendations

• sandbox-rebuild
• ubuntu-repo-cloud-langchain-deepagents-code

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover legacy zero-dashboard state during lifecycle recovery

• Location: test/e2e/live/onboard-resume.test.ts:156
• Category: tests
• Problem: The changed unit tests establish parsing and allocation behavior for an unrelated persisted `dashboardPort: 0` entry, but the lifecycle recovery suites do not seed that legacy state before resuming or repairing a dashboard-bearing sandbox. The affected path can fail after destructive rebuild/recreate work, so unit coverage alone does not demonstrate that a retry converges with no stale allocation.
• Impact: A regression in the integration between registry parsing, host-wide port allocation, and recovery could again leave a target sandbox unrecreated or allocate a stale port when an unrelated terminal/dcode row contains the legacy zero sentinel.
• Recommendation: Add one focused recovery regression that seeds an unrelated no-dashboard registry row with `dashboardPort: 0`, runs resume or repair for a dashboard-bearing sandbox, and asserts successful completion and a non-conflicting allocated dashboard port.
• Verification: Inspect `test/e2e/live/onboard-resume.test.ts` and `test/e2e/live/onboard-repair.test.ts` for a setup that writes an unrelated zero-dashboard registry row before recovery; none is present in the reviewed evidence.
• Test coverage: A live `onboard-resume` or `onboard-repair` case that seeds an unrelated `dashboardPort: 0` entry, triggers target recovery, and verifies target recreation succeeds without treating the zero entry as occupied.
• Evidence: `src/lib/state/gateway-registry.ts` now changes parser behavior for persisted zero dashboard ports used by host-wide allocation. The added unit tests cover parsing/canonicalization and an allocator result, not a resume or repair operation. Risk plan lists lifecycle-state invariant: partial failure and retry converge without ghost resources or stale ports, with `onboard-resume` and `onboard-repair` as required jobs.

Workflow run details

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

[cv]

Approved at exact head 13f2af5 against current base d034b7f. The refresh commit is merge-only and preserves the reviewed patch; parser, persistence, and allocation tests cover the dashboardPort 0 sentinel. All 54 current checks and exact-diff E2E are green, CodeRabbit is clear, DCO is present, and all commits are Verified.