refactor(onboard): add initial FSM flow slice

[cv]

Summary

Add a reusable initial onboarding flow slice for preflight and gateway. This slice uses runner stop states to hand off at provider_selection for incremental live-flow migration.

Changes

• Add initialOnboardFlowPhases() for selecting preflight and gateway phases.
• Add runInitialOnboardFlowSequence() to run that prefix and stop at provider selection.
• Thread stop-state support through the sequence runner adapter.
• Add tests for phase selection and stopping at provider_selection.

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: 3eddb3a5-bfba-4e0d-bf6b-07dc78ade655

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-initial-sequence-slice

---

_{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
Optional E2E: ubuntu-repo-cloud-openclaw-resume, ubuntu-repo-cloud-hermes

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-sequence
Head: HEAD
Confidence: high

Required E2E

• ubuntu-repo-cloud-openclaw (high): Primary real-user onboarding path on Ubuntu with Docker and cloud OpenClaw. It validates install/onboard execution through preflight, gateway startup, provider/inference, sandbox readiness, smoke, inference, and credential assertions, making it the best merge-blocking E2E for changes to the onboarding sequence runner.
• ubuntu-no-docker-preflight-negative (medium): Covers the negative preflight boundary and verifies Docker/preflight failures do not start a gateway or create a sandbox. This is directly relevant because the new flow slice begins with preflight and gateway phases.

Optional E2E

• ubuntu-repo-cloud-openclaw-resume (high): Useful adjacent confidence for FSM/session behavior because sequence-runner context updates and stop-state handling can interact with interrupted or resumed onboarding flows.
• ubuntu-repo-cloud-hermes (high): Exercises the same onboarding FSM machinery with the Hermes assistant path, giving additional confidence that sequence-runner changes are not OpenClaw-only.

New E2E recommendations

• initial-onboarding-slice (high): Existing E2E scenarios cover full onboarding or preflight failure, but none appear to invoke an initial-only onboarding flow that runs real preflight and gateway startup, stops at provider_selection, and asserts provider/sandbox/credential side effects have not occurred.
  • Suggested test: Add a typed scenario such as ubuntu-repo-cloud-openclaw-initial-flow that exercises the initial onboarding slice/entrypoint and validates persisted session.machine.state == provider_selection after real preflight+gateway execution.

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-sequence
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, 2 worth checking, 0 nice ideas
Top item: Clarify or enforce the preflight starting-state contract

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Clarify or enforce the preflight starting-state contract (src/lib/onboard/machine/flow-slices.ts:20): `runInitialOnboardFlowSequence()` filters the supplied phases down to only `preflight` and `gateway`, then calls the generic runner. A normal `createSession()` starts the FSM at `init`; with that default state, the filtered phase list has no `init` handler and the runner will fail before reaching preflight. The new test avoids this by manually initializing the session machine to `preflight`, but the exported helper does not document or enforce that precondition.
  • Recommendation: Either include/handle the `init` transition in this slice, or document and assert that callers must invoke it only after the machine has already entered `preflight`. Add a regression test for the chosen contract, especially the default-session behavior.
  • Evidence: `flow-slices.ts` passes `phases: initialOnboardFlowPhases(options.phases)` and `stopStates: ["provider_selection"]`; `initialOnboardFlowPhases()` only keeps `preflight` and `gateway`. `flow-slices.test.ts` constructs the runtime session with `machine.state: "preflight"`, while `createSession()` defaults to `init`.
• Coordinate overlapping onboarding FSM PRs: The patch touches onboarding FSM files that deterministic context reports are also modified by active overlapping PRs. This increases drift risk for the new slice surface and the sequence-runner adapter, especially because this PR is stacked on recent FSM migration work.
  • Recommendation: Before landing or building callers on this helper, reconcile the intended ownership and final shape with the overlapping FSM slice and sequence-runner PRs so duplicate helpers or conflicting contracts do not persist.
  • Evidence: Open PR overlap context lists PR refactor(onboard): add core FSM flow slice #4487 touching `flow-slices.ts` and `flow-slices.test.ts`, and PR refactor(onboard): add sequence runner adapter #4475 touching `sequence-runner.ts`; this PR also changes those files.

🌱 Nice ideas

• None.

Workflow run details

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