refactor(onboard): assemble FSM phase sequence

[cv]

Summary

Add an ordered onboarding FSM phase sequence builder. The builder composes the extracted phase wrappers into the canonical onboarding order while delegating actual phase behavior to supplied handlers.

Changes

• Add buildOnboardFlowPhaseSequence() and OnboardFlowPhaseHandlers.
• Assemble preflight, gateway, provider/inference, sandbox, OpenClaw, agent setup, policies, finalization, and post-verify phases.
• Add tests for phase ordering and delegated handler execution.

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: e19299e1-09e9-4bdf-b4b8-2df8032bcd0c

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-flow-sequence

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: cloud-onboard-e2e, hermes-e2e
Optional E2E: onboard-resume-e2e, onboard-repair-e2e, onboard-negative-paths-e2e

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

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-agent-policy-finalization-phases
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard-e2e (high): Validates the main OpenClaw cloud onboarding path end-to-end, including install, preflight/gateway, provider/model setup, sandbox health, custom policy presets, security checks, and inference.local. This is the highest-signal existing E2E for a change to onboard phase ordering/finalization.
• hermes-e2e (high): Covers the non-OpenClaw agent setup branch of onboarding. The new sequence maps both openclaw and agent_setup phases, so Hermes onboarding should be validated to catch branch-specific phase sequencing or context propagation regressions.

Optional E2E

• onboard-resume-e2e (high): Useful adjacent coverage because the onboard FSM context/session flow can affect interrupted onboarding and resume behavior, but it is less directly targeted than the fresh OpenClaw/Hermes onboarding paths.
• onboard-repair-e2e (high): Useful confidence check for repair/resume invalidation behavior if reviewers are concerned the new phase sequence will be used by recovery paths.
• onboard-negative-paths-e2e (high): Optional guard for failure-state handling around onboarding; helpful if the FSM sequence changes affect error propagation or terminal-state handling.

New E2E recommendations

• None.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: cloud-onboard-e2e,hermes-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-agent-policy-finalization-phases
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, 1 worth checking, 0 nice ideas
Top item: Add runtime validation coverage for provider/inference sequencing

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Add runtime validation coverage for provider/inference sequencing (src/lib/onboard/machine/flow-sequence.test.ts:50): The assembled sequence has a provider/inference phase at state `provider_selection` but no separate `inference` phase. That is valid only if the supplied handler returns the multi-result path `provider_selection -> inference -> sandbox`. The current tests use direct `advanceTo("sandbox")` fixtures from the provider handler and only assert phase ordering or preflight delegation, so they would not catch an invalid `provider_selection -> sandbox` transition when the sequence is run through `OnboardRuntime`.
  • Recommendation: Add a sequence-runner/runtime test for `buildOnboardFlowPhaseSequence()` where `providerInference` returns `[advanceTo("inference"), advanceTo("sandbox")]` and the assembled phases are applied through runtime transition validation. Avoid direct `provider_selection -> sandbox` fixtures unless the test is explicitly asserting runtime rejection.
  • Evidence: `flow-sequence.ts` builds `createProviderInferencePhase((context) => handlers.providerInference(context))` at state `provider_selection` and does not add an `inference` phase. `transitions.ts` only allows `provider_selection -> inference` and then `inference -> sandbox`. The test fixtures at `flow-sequence.test.ts` use `result(..., "sandbox")` for `providerInference` but never run that phase through the runtime.

🌱 Nice ideas

• None.

Workflow run details

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