fix(onboard): recover custom endpoint DNS failures

[HwangJohn]

Summary

Custom OpenAI-compatible endpoint DNS preflight failures now use the existing transport recovery path instead of falling back to provider selection. The SSRF preflight still fails closed and skips credentialed probes, but interactive users get retry/back/exit recovery for unreachable hostnames.

Related Issue

Fixes #6854

Changes

• Classify DNS-backed endpoint preflight resolution failures as transport failures.
• Reuse the existing DNS/VPN/endpoint URL recovery guidance for resolver-style failures.
• Add regression coverage that proves a DNS preflight failure does not probe the endpoint and calls transport recovery.

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: no command syntax, option, configuration, or documented workflow changes; this only routes an existing validation failure into the existing recovery prompt.
• 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 of the preflight/inference boundary; the change only classifies failed DNS preflight results for recovery, preserves fail-closed behavior, and keeps credentialed probes disabled on preflight failure.
• 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 — command/result or justification: DGX Spark/Linux: npx vitest run --project cli src/lib/validation-recovery.test.ts passed; npx vitest run --project cli src/lib/onboard/inference-selection-validation.test.ts -t '#6854' passed; npm run check:diff passed.
• 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: HwangJohn angelic805@gmail.com

Summary by CodeRabbit

• Bug Fixes
  • Improved validation failure classification for DNS/endpoint-host resolution issues (e.g., ENOTFOUND/EAI_AGAIN and related messages), ensuring they are handled as transport problems with retry behavior.
  • Enhanced the user-facing recovery guidance for cases where the endpoint host cannot be resolved.
• Tests
  • Expanded test coverage for DNS-check messaging and for routing DNS-backed preflight failures through transport recovery.
  • Updated tests to confirm probe endpoints are not called when endpoint resolution fails.

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

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: d078d04b-529b-4464-8f78-9390930d57ef

📥 Commits

Reviewing files that changed from the base of the PR and between 5d00dad and b2d237c.

📒 Files selected for processing (1)

• src/lib/onboard/inference-selection-validation.test.ts

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

• src/lib/onboard/inference-selection-validation.test.ts

---

📝 Walkthrough

Walkthrough

DNS and hostname-resolution failures are now classified as transport failures with retry recovery. Transport guidance recognizes additional DNS error messages, and tests cover preflight recovery plus custom OpenAI-compatible endpoint onboarding behavior.

Changes

DNS endpoint recovery

Layer / File(s)	Summary
DNS failure classification and guidance src/lib/validation.ts, src/lib/validation-recovery.ts, src/lib/validation-recovery.test.ts	Validation recognizes additional DNS and endpoint-resolution errors as transport retries, while transport recovery provides DNS and endpoint URL guidance.
Preflight recovery routing and onboarding coverage src/lib/validation-recovery.test.ts, src/lib/onboard/inference-selection-validation.test.ts	DNS-backed preflight failures return transport recovery results, and custom endpoint validation verifies the transport recovery call, retry result, and skipped probe.

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

🚥 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 clearly summarizes the main change: recovering DNS failures for custom endpoints during onboard.
Linked Issues check	✅ Passed	DNS-unreachable endpoint and SSRF preflight failures are now classified as transport failures and routed into the existing recovery flow, matching #6854.
Out of Scope Changes check	✅ Passed	The changes stay focused on onboard validation/recovery and related tests, with no unrelated scope added.
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.}

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

[wscurran]

✨ Thanks for the fix, @HwangJohn. Classifying DNS preflight failures as transport failures and reusing the existing recovery path should give users proper retry/back/exit guidance. Ready for maintainer review.

---

Related open issues:

• #6854 [DGX Spark][Onboard] Unreachable custom OpenAI-compatible endpoint loops back to provider menu with no recovery guidance or exit option

---

Related open issues:

• #6854 [DGX Spark][Onboard] Unreachable custom OpenAI-compatible endpoint loops back to provider menu with no recovery guidance or exit option

[prekshivyas]

Reviewed the validation classification and recovery flow. DNS/preflight failures now consistently enter transport retry without weakening credential/TLS handling, with focused tests. No blocking findings.