refactor(onboard): extract preflight and gateway FSM phases

[cv]

Summary

Add reusable FSM phase wrappers for preflight and gateway. These wrappers map existing handler outputs into OnboardFlowContext updates plus explicit FSM results.

Changes

• Add createPreflightPhase() and createGatewayPhase() under onboard machine flow phases.
• Map preflight outputs such as GPU, sandbox GPU config, passthrough, and session into the flow context.
• Add tests for phase state names, context updates, and 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: 7d4b5002-1471-4148-8653-64eb4fc209ad

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-phases

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: ubuntu-repo-cloud-openclaw, ubuntu-no-docker-preflight-negative, gateway-drift-preflight-e2e
Optional E2E: gpu-repo-local-ollama-openclaw, ubuntu-repo-cloud-openclaw-resume

Dispatch hint: ubuntu-repo-cloud-openclaw,ubuntu-no-docker-preflight-negative

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-flow-context
Head: HEAD
Confidence: high

Required E2E

• ubuntu-repo-cloud-openclaw (medium): Canonical happy-path onboarding scenario that exercises repo checkout, Docker preflight, gateway startup, sandbox creation, cloud OpenClaw setup, credentials, and inference after the preflight-to-gateway transition.
• ubuntu-no-docker-preflight-negative (low): Preflight-negative scenario should confirm the new preflight phase still fails closed when Docker is unavailable and does not start the gateway or create a sandbox.
• gateway-drift-preflight-e2e (low): Regression guard for preflight/gateway boundary behavior; validates that stale or incompatible gateway state is detected and handled safely instead of allowing onboarding to advance on bad gateway state.

Optional E2E

• gpu-repo-local-ollama-openclaw (high): Useful confidence for the GPU fields introduced in the preflight phase context mapping, but higher cost because it requires a self-hosted GPU/CDI runner.
• ubuntu-repo-cloud-openclaw-resume (medium): Optional coverage for session propagation across the new flow phase adapters during resumed onboarding.

New E2E recommendations

• None.

Dispatch hint

• Workflow: .github/workflows/e2e-scenarios.yaml
• jobs input: ubuntu-repo-cloud-openclaw,ubuntu-no-docker-preflight-negative

[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-flow-context
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

Workflow run details

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