test(onboard): make gateway TCP readiness refusal deterministic (#7250)

[jason-ma-nv]

Summary

The negative case in gateway-tcp-readiness.test.ts assumed a just-closed
ephemeral loopback port becomes synchronously unreachable, which is not
portable: under WSL2 mirrored networking the mirrored loopback path keeps
accepting connections for a few milliseconds after the Linux listener closes,
so isGatewayTcpReady observes a successful connect and resolves true,
failing the CLI suite. This makes the closed/error path deterministic by
simulating ECONNREFUSED instead of racing listener teardown. Production probe
behavior is unchanged.

Related Issue

Fixes #7250

Changes

• Removed the getLikelyClosedPort() helper, which opened and closed a real
  ephemeral loopback listener and depended on platform-specific teardown timing.
• Rewrote "resolves false when the connection is refused (ECONNREFUSED)" to mock
  net.createConnection (the OS boundary) and emit an ECONNREFUSED error,
  exercising the real socket.once("error") -> settle(false) path in
  isGatewayTcpReadyImpl with no timing sleep and no listener race. This reuses
  the same net.createConnection mocking seam the existing minimum-timeout test
  already uses, and asserts the socket is destroyed on the error path.
• No production source changed; the positive-listener and timeout tests are
  untouched.

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 test fixture; no user-facing 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: Change is test-fixture only under src/lib/onboard/; zero production onboarding/probe code is modified, so the security surface is unchanged. Flagging for maintainer confirmation.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-not-needed
• Evidence: The exact-head diff changes only the gateway TCP readiness test fixture; no user-facing command, output, configuration, or supported behavior changes.
• Agent: Codex Desktop

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 — command/result: npx vitest run --project cli src/lib/onboard/gateway-tcp-readiness.test.ts → 6/6 passed locally and on a fresh clone + npm ci on an ordinary Linux (Ubuntu, x86_64) host (exit 0).
• Applicable broad gate passed — justification: test-only fixture portability fix; not a broad runtime/test-harness change.
• 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: Jason Ma jama@nvidia.com

🤖 Generated with Claude Code

Summary by CodeRabbit

• Tests
  • Improved coverage for gateway TCP readiness checks when a connection is refused.
  • Added deterministic simulation of ECONNREFUSED to confirm the service reports it as unavailable.
  • Verified the connection cleanup behavior via mocked socket destruction.

[coderabbitai]

📝 Walkthrough

Walkthrough

The gateway TCP readiness test replaces platform-dependent closed-port probing with a mocked ECONNREFUSED socket event, asserting that readiness resolves false and the socket is destroyed.

Changes

Gateway readiness tests

Layer / File(s)	Summary
Deterministic connection-refused test src/lib/onboard/gateway-tcp-readiness.test.ts	Removes the ephemeral closed-port helper and simulates ECONNREFUSED through net.createConnection, verifying the false result and socket cleanup.

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

Suggested labels: area: onboarding

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The test change matches #7250 by simulating ECONNREFUSED deterministically and keeping production behavior unchanged.
Out of Scope Changes check	✅ Passed	The PR stays confined to the readiness test and does not introduce unrelated code or production changes.
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 PR’s main change: making the gateway TCP readiness refusal test deterministic.

✨ 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/7250-tcp-readiness-deterministic-refused

---

_{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 633e34d in the fix/7250-tcp-readine... branch remains at 96%, unchanged from commit e84f5ee in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 633e34d in the fix/7250-tcp-readine... branch remains at 80%, unchanged from commit e84f5ee in the main branch.

Show a code coverage summary of the most impacted files.

File	main e84f5ee	fix/7250-tcp-readine... 633e34d	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/state/m...-acquisition.ts	87%	84%	-3%
src/lib/state/g...way-registry.ts	95%	94%	-1%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/securit...ntial-filter.ts	93%	93%	0%
src/lib/state/m...ock-identity.ts	95%	95%	0%
src/lib/state/m...lock-storage.ts	97%	97%	0%
src/lib/trace.ts	94%	94%	0%
src/lib/platform.ts	84%	89%	+5%

---

_{Updated July 23, 2026 23:53 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 E2E selections differ; severity counts match.

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: cloud-onboard

1 optional E2E recommendation

• onboard-negative-paths

Workflow run details

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

[cjagwani]

Reviewed the exact refreshed diff and linked regression scope. The change replaces a timing-dependent refused-port setup with a deterministic ECONNREFUSED socket mock, preserves cleanup assertions, and adds no product surface. All 53 current checks and the repository merge gate pass at 742ebbf.