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

Summary by CodeRabbit

• Tests

  • Updated state transition assertions for onboarding workflow validation.

• Refactor

  • Enhanced internal state transition structure in the onboarding flow to explicitly track and return state progression information.

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

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: afe8fba7-fec7-40aa-a5cc-6e1406027521

📥 Commits

Reviewing files that changed from the base of the PR and between 79972bb and 02d1c7a.

📒 Files selected for processing (4)

• src/lib/onboard/machine/handlers/gateway.test.ts
• src/lib/onboard/machine/handlers/gateway.ts
• src/lib/onboard/machine/handlers/preflight.test.ts
• src/lib/onboard/machine/handlers/preflight.ts

---

📝 Walkthrough

Walkthrough

The onboarding FSM handlers for preflight and gateway now explicitly return state transition results. Both handlePreflightState and handleGatewayState import advanceTo, extend their result interfaces to include stateResult, and wire their completion states with metadata into explicit OnboardStateTransitionResult objects targeting their respective next states.

Changes

Onboarding FSM state transitions

Layer / File(s)	Summary
Preflight state transition src/lib/onboard/machine/handlers/preflight.ts, src/lib/onboard/machine/handlers/preflight.test.ts	PreflightStateResult now includes stateResult field. handlePreflightState computes a transition to gateway via advanceTo(...) with metadata capturing preflight state and GPU passthrough, and test validates the transition structure and metadata payload.
Gateway state transition src/lib/onboard/machine/handlers/gateway.ts, src/lib/onboard/machine/handlers/gateway.test.ts	GatewayStateResult now includes stateResult field. handleGatewayState computes a transition to provider_selection via advanceTo(...) with metadata capturing gateway state and reuse state, and test validates the transition structure and metadata payload.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4375: This PR updates handleGatewayState and handlePreflightState to return transitions built with advanceTo/OnboardStateTransitionResult, which directly relies on the result.ts transition/advance helper types introduced in PR #4375.
• NVIDIA/NemoClaw#4376: Both PRs introduce and rely on explicit stateResult/advanceTo(...) transition objects with transitionKind and metadata—this PR adds those stateResult returns in preflight/gateway handlers, while the retrieved PR updates OnboardRuntime.applyResult/complete to consume and validate them.
• NVIDIA/NemoClaw#4444: Both PRs update onboarding FSM handlers to return an explicit stateResult transition via advanceTo(...) and extend the corresponding tests to assert that transition shape and metadata.

Suggested labels

onboarding

Suggested reviewers

• prekshivyas
• cjagwani

Poem

🐰 Transitions flow like meadow streams,
Each state now marks its exit dreams,
From preflight vales to gateway heights,
The FSM glows with clearer lights!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: making preflight and gateway handlers return FSM transition results.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 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: cloud-onboard-e2e, onboard-resume-e2e
Optional E2E: gpu-e2e, ubuntu-no-docker-preflight-negative

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

Auto-dispatched E2E: cloud-onboard-e2e, onboard-resume-e2e via nightly-e2e.yaml at 02d1c7a3dd68c36eb708aafa80edd6e423792296 — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard-e2e (high; requires Docker, NVIDIA_API_KEY, and full sandbox onboarding): Runs a fresh non-interactive cloud onboard through preflight, gateway start/reuse, provider selection, sandbox health, security checks, and inference.local. This is the primary merge-blocking confidence check that the new handler transition results do not break the real onboarding flow.
• onboard-resume-e2e (high; requires Docker, NVIDIA_API_KEY, and interrupted/resumed sandbox onboarding): Directly exercises resume behavior that skips cached preflight/gateway work and then completes onboarding. Because both touched handlers have resume paths and now return transition results, this should block merge.

Optional E2E

• gpu-e2e (very high; requires NVIDIA GPU runner, Docker CDI, Ollama setup, and model pull): Useful adjacent confidence for the preflight/gateway GPU passthrough path because preflight transition metadata includes gpuPassthrough and gateway start is parameterized by GPU intent. Not merge-blocking for this PR because the diff only adds transition result plumbing and existing unit tests cover GPU config shape.
• ubuntu-no-docker-preflight-negative (medium; scenario dry/runtime orchestration on ubuntu-latest without Docker daemon expectation): Optional typed scenario to verify preflight still fails safely before gateway/sandbox side effects when Docker is unavailable. The changed success transition path should not affect this negative path, so it is not merge-blocking.

New E2E recommendations

• onboarding-state-machine (medium): Existing E2E jobs validate final onboard success/resume behavior but do not appear to assert the durable machine transition events/metadata for preflight -> gateway and gateway -> provider_selection. A focused assertion would catch regressions where onboarding completes only because legacy control flow advances while the machine state/event log is wrong.
  • Suggested test: Add an E2E or scenario assertion that inspects the onboard session/state event log after fresh onboard and resume, verifying preflight advances to gateway with gpuPassthrough metadata and gateway advances to provider_selection with gatewayReuseState metadata.

Dispatch hint

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

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw
Optional scenario E2E: ubuntu-no-docker-preflight-negative, gpu-repo-local-ollama-openclaw

Dispatch required scenario E2E:

• gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• ubuntu-repo-cloud-openclaw: Core onboarding preflight and gateway state handlers changed. The standard Ubuntu repo cloud OpenClaw scenario is the smallest regular-runner scenario that exercises successful preflight, gateway startup/reuse path integration, sandbox readiness, and baseline onboarding behavior.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional scenario E2E

• ubuntu-no-docker-preflight-negative: Optional adjacent coverage for preflight behavior on a missing-Docker host, useful because preflight handler code changed, but not the primary success path touched by the new transition result plumbing.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-no-docker-preflight-negative
• gpu-repo-local-ollama-openclaw: Optional special-runner coverage for GPU passthrough/local onboarding because the preflight result metadata includes gpuPassthrough and gateway reconciliation depends on GPU intent.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=gpu-repo-local-ollama-openclaw

Relevant changed files

• src/lib/onboard/machine/handlers/gateway.ts
• src/lib/onboard/machine/handlers/preflight.ts

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 1 worth checking, 0 nice ideas
Top item: PR review advisor unavailable

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• PR review advisor unavailable: The automated advisor could not complete: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt
  • Recommendation: Re-run the PR Review Advisor or perform a manual review.
  • Evidence: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt

🌱 Nice ideas

• None.

Consider writing more tests for

• **Runtime validation** — Add or identify targeted runtime/integration validation for the changed behavior; do not report external E2E job pass/fail here.. Runtime/sandbox/infrastructure paths need behavioral runtime validation: src/lib/onboard/machine/handlers/gateway.ts, src/lib/onboard/machine/handlers/preflight.ts.

Workflow run details

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

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26977149057
Target ref: 02d1c7a3dd68c36eb708aafa80edd6e423792296
Workflow ref: main
Requested jobs: cloud-onboard-e2e,onboard-resume-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
onboard-resume-e2e	✅ success