fix(cli): fail fast on gateway port conflicts

[sandl99]

Summary

nemoclaw onboard now checks for a clearly foreign process on the OpenShell gateway port before running gateway reuse probes. That prevents a silent listener on port 8080 from stalling onboarding and reports the conflict with the shared terminal error styling.

Related Issue

Fixes #6752

Changes

• Add an early gateway-port conflict check after OpenShell availability is confirmed and before openshell status / gateway info probes run.
• Preserve NemoClaw/OpenShell/Docker gateway candidates on the existing reuse path while failing fast for identifiable foreign listeners.
• Extract gateway-port conflict classification into a focused src/lib/onboard/ helper so the top-level onboard entrypoint stays net smaller.
• Share the port-conflict report formatting so both early and required-port failures include the styled heading, PID/process details, remediation hints, and alternate NEMOCLAW_GATEWAY_PORT guidance.
• Bound gateway reuse status/info probes with the existing OpenShell probe timeout.
• Add unit and integration regression coverage for styled diagnostics, probe timeouts, candidate listener classification, and the silent foreign-listener fast-fail path.

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 troubleshooting and command docs already cover gateway port conflicts and NEMOCLAW_GATEWAY_PORT; no new option or workflow was added.
• 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: self-review; the change only reorders a local port ownership check ahead of gateway probes, keeps NemoClaw/OpenShell/Docker candidate listeners on the existing reuse path, adds bounded probe timeouts, and is covered by focused regression tests.
• 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: npm run build:cli passed; npx vitest run --project cli src/lib/onboard/gateway-port-conflict.test.ts src/lib/onboard/gateway-stale-port-reuse.test.ts src/lib/onboard/port-conflict-report.test.ts src/lib/onboard/gateway-reuse.test.ts passed; npx vitest run --project integration test/onboard-gateway-port-conflict-fast-fail.test.ts passed; npm run typecheck:cli passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: not applicable; focused CLI onboarding fix covered by targeted tests and npm run check:diff.
• 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: San Dang sdang@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Onboarding now detects gateway-port conflicts earlier and exits promptly when an unrelated process is using the configured port.
  • Port conflict messages are now consistently formatted, include blocking-process details when available, and provide clearer guidance for resolving the issue or choosing another port.
  • Gateway inspection probes now share consistent timeout handling to help prevent hangs.

• Tests

  • Added automated coverage for port conflict reporting, gateway reuse snapshots, and fast-fail onboarding behavior under port-blocked scenarios.

[coderabbitai]

📝 Walkthrough

Walkthrough

Onboarding now detects foreign listeners on the configured gateway port before gateway inspection, prints a shared port-conflict report, and exits promptly. Gateway reuse probes use a bounded timeout, with unit, formatting, and integration tests covering the updated behavior.

Changes

Gateway port conflict handling

Layer / File(s)	Summary
Standardized port conflict reporting src/lib/onboard/port-conflict-report.ts, src/lib/onboard/port-conflict-report.test.ts, src/lib/onboard.ts	Adds shared port-conflict formatting and printing, tests colored and plain output, and replaces manual error output.
Bounded gateway reuse probes src/lib/onboard/gateway-reuse.ts, src/lib/onboard/gateway-reuse.test.ts	Applies OPENSHELL_PROBE_TIMEOUT_MS to status and gateway-info probes and verifies the command options.
Foreign listener preflight fast-fail src/lib/onboard/gateway-port-conflict.ts, src/lib/onboard/gateway-port-conflict.test.ts, src/lib/onboard.ts, test/onboard-gateway-port-conflict-fast-fail.test.ts	Classifies gateway port owners, reports foreign conflicts immediately after OpenShell setup, exits nonzero, and verifies gateway inspection is skipped.

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

Sequence Diagram(s)

sequenceDiagram
  participant Onboard
  participant PortProbe
  participant GatewayPortConflict
  participant PortConflictReport
  Onboard->>GatewayPortConflict: inspect configured gateway port
  GatewayPortConflict->>PortProbe: check gateway port
  PortProbe-->>GatewayPortConflict: foreign listener details
  GatewayPortConflict->>PortConflictReport: print conflict report
  GatewayPortConflict-->>Onboard: exit nonzero before gateway inspection

Loading

Possibly related PRs

• NVIDIA/NemoClaw#4598: Both modify onboarding preflight port-conflict handling and the path that reaches standardized port-unavailable reporting.

Suggested labels: NV QA, bug-fix, area: cli, area: onboarding

Suggested reviewers: cv, prekshivyas, ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR addresses #6752 by adding fast-fail conflict detection, bounded gateway probes, shared styling, and regression tests.
Out of Scope Changes check	✅ Passed	The code changes stay focused on onboarding port-conflict handling, diagnostics, timeouts, and related tests.
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 and concisely summarizes the main change: failing fast when the CLI finds gateway port conflicts.

✨ 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/6752-onboard-port-conflict

---

_{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 remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/6752-onboard-por... branch remains at 79%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 3de1de6	fix/6752-onboard-por... 86bb9aa	+/-
src/lib/core/pr...mpt-activity.ts	92%	67%	-25%
src/lib/onboard.ts	29%	28%	-1%
src/lib/messagi.../persistence.ts	90%	89%	-1%
src/lib/state/m...-acquisition.ts	77%	80%	+3%
src/lib/state/gateway.ts	88%	93%	+5%
src/lib/actions...ge-preflight.ts	74%	89%	+15%
src/lib/onboard...ateway-reuse.ts	0%	45%	+45%
src/lib/onboard...ort-conflict.ts	0%	92%	+92%
src/lib/onboard...flict-report.ts	0%	100%	+100%

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: onboard-repair, onboard-resume, cloud-onboard
Optional E2E: concurrent-gateway-ports

Dispatch hint: onboard-repair,onboard-resume,cloud-onboard

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• onboard-repair: Required deterministic lifecycle-state floor: verify repair still reconciles missing or stale gateway/sandbox state after changed preflight gateway-port classification and reuse behavior.
• onboard-resume: Required deterministic lifecycle-state floor: verify interrupted onboarding can resume with the revised gateway preflight and bounded reuse probes.
• cloud-onboard: The shared onboarding preflight runs for hosted onboarding too; validate a complete hosted-inference onboarding flow still creates and uses its gateway successfully.

Optional E2E

• concurrent-gateway-ports: Adjacent live coverage for two onboarded gateways on distinct ports; it provides confidence that the revised port ownership/reuse logic preserves multi-gateway lifecycle behavior.

New E2E recommendations

• onboarding (medium): The new CLI integration test proves a mocked foreign listener fails before a mocked OpenShell inspection can hang, but there is no identified dedicated live E2E job that holds a real foreign listener on the configured gateway port and asserts no gateway or sandbox side effects.
  • Suggested test: Add a live onboarding negative-path scenario that occupies NEMOCLAW_GATEWAY_PORT with an unrelated listener, asserts the conflict report and non-zero exit, and verifies gateway and sandbox remain absent.

Dispatch hint

• Workflow: .github/workflows/e2e.yaml
• jobs input: onboard-repair,onboard-resume,cloud-onboard

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Findings: 0 required · 0 warnings · 0 optional suggestions
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard.ts (1)

1506-1521: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider threading an injectable exit function for consistency/testability.

failFastOnForeignGatewayPortConflict calls process.exit(1) directly, while the neighboring reconcilePreflightGatewayReuseState call a few lines below uses an injected exitProcess: (code) => process.exit(code). Following the same pattern here would let this new fail-fast/classification logic be covered by a fast unit test instead of relying solely on the CLI-spawning integration test.

♻️ Sketch of DI-friendly signature

-async function failFastOnForeignGatewayPortConflict(): Promise<void> {
-  const portCheck = await checkPortAvailable(
+async function failFastOnForeignGatewayPortConflict(
+  exitProcess: (code: number) => void = (code) => process.exit(code),
+): Promise<void> {
+  const portCheck = await checkPortAvailable(
     GATEWAY_PORT,
     dockerDriverGatewayEnv.getGatewayPortCheckOptions(),
   );
   if (portCheck.ok || couldBeNemoClawGatewayPortListener(portCheck)) return;

   printPortConflictReport({
     port: GATEWAY_PORT,
     label: "OpenShell gateway",
     envVar: "NEMOCLAW_GATEWAY_PORT",
     portCheck,
     serviceHints: getPortConflictServiceHints(),
   });
-  process.exit(1);
+  exitProcess(1);
 }

🤖 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/onboard.ts` around lines 1506 - 1521, Update
failFastOnForeignGatewayPortConflict to accept an injectable exitProcess
callback, defaulting to the existing process.exit behavior, and invoke it with
status 1 instead of calling process.exit directly. Thread the callback from its
callers, matching the exitProcess pattern used by
reconcilePreflightGatewayReuseState, so unit tests can provide a stub without
changing the conflict handling behavior.

🤖 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/onboard.ts`:
- Around line 1506-1521: Update failFastOnForeignGatewayPortConflict to accept
an injectable exitProcess callback, defaulting to the existing process.exit
behavior, and invoke it with status 1 instead of calling process.exit directly.
Thread the callback from its callers, matching the exitProcess pattern used by
reconcilePreflightGatewayReuseState, so unit tests can provide a stub without
changing the conflict handling behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ab21527d-30c1-412b-966c-8b22170962b5

📥 Commits

Reviewing files that changed from the base of the PR and between 3de1de6 and 80eb8be.

📒 Files selected for processing (6)

• src/lib/onboard.ts
• src/lib/onboard/gateway-reuse.test.ts
• src/lib/onboard/gateway-reuse.ts
• src/lib/onboard/port-conflict-report.test.ts
• src/lib/onboard/port-conflict-report.ts
• test/onboard-gateway-port-conflict-fast-fail.test.ts

[github-actions]

E2E Target Results — ✅ All selected tests passed

Run: 29246234383
Workflow ref: fix/6752-onboard-port-conflict
Requested targets: onboard-repair,onboard-resume,cloud-onboard
Requested test IDs: (default — all default-enabled tests; explicit-only tests openshell-gateway-auth-contract, mcp-bridge-dev, hermes-gpu-startup, sandbox-rlimits-connect, and jetson-nvmap-gpu are skipped unless selected)
Summary: 3 passed, 0 failed, 0 cancelled, 0 skipped, 0 unknown

Test	Result
cloud-onboard	✅ success
onboard-repair	✅ success
onboard-resume	✅ success

[prekshivyas]

Reviewed current head. Required CI, both PR advisors, CodeRabbit, and all requested onboarding E2E targets are clean. LGTM.