refactor(onboard): make preflight and gateway return FSM results

[cv]

Summary

Make the preflight and gateway handlers return explicit FSM transition results. These early handlers now report their next states while preserving the existing step-boundary/session behavior.

Changes

• Add stateResult to PreflightStateResult with the preflight -> gateway transition.
• Add stateResult to GatewayStateResult with the gateway -> provider_selection transition.
• Extend preflight and gateway handler tests to assert returned FSM results.

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)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• 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: Carlos Villela cvillela@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 11e6a422-fbf1-41e8-9d54-c69e89f4e2c1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/onboard-fsm-preflight-gateway-results

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: full-e2e, onboard-resume-e2e
Optional E2E: gateway-drift-preflight-e2e, gpu-e2e

Dispatch hint: full-e2e,onboard-resume-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-policies-result
Head: HEAD
Confidence: high

Required E2E

• full-e2e (high; requires Docker and NVIDIA_API_KEY, creates a real sandbox and live inference route): Runs the complete install/onboard/sandbox/inference user journey and will exercise the fresh preflight -> gateway -> provider_selection path that this PR changes.
• onboard-resume-e2e (medium-high; requires Docker, OpenShell, NVIDIA_API_KEY, and a real resumable sandbox): Directly covers resumed onboard behavior where preflight and gateway can be skipped from cached session state; these changed handlers now must still return valid FSM transitions on resume paths.

Optional E2E

• gateway-drift-preflight-e2e (medium; targeted regression on ubuntu-latest): Useful targeted confidence for the gateway/preflight boundary and stale gateway image/metadata handling adjacent to the changed gateway handler, but the PR does not alter drift detection logic directly.
• gpu-e2e (very high; requires ephemeral GPU runner and local Ollama inference): Optional only if maintainers want confidence that gpuPassthrough metadata and GPU gateway startup still work in a real local-inference GPU environment; expensive and not required for this transition-result-only change.

New E2E recommendations

• onboarding-state-machine (medium): Existing E2E flows validate successful onboarding/resume, but they do not appear to assert the durable FSM transition trail or transition metadata for preflight and gateway specifically. A focused regression would catch handlers that complete side effects but fail to advance the onboard machine correctly.
  • Suggested test: Add an E2E or scenario assertion that inspects onboard-session artifacts/events after preflight and gateway and verifies transitions preflight->gateway and gateway->provider_selection, including resume skip paths.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: full-e2e,onboard-resume-e2e

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/stack/onboard-fsm-policies-result
Head: HEAD
Confidence: high

Required scenario E2E

• None. No scenario workflow, scenario metadata, scenario runtime, or validation-suite files changed.

Optional scenario E2E

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Top item: No actionable findings

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.