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

Auto reviews are disabled on base/target branches other than the default branch.

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: e9ffd032-b923-4aa4-98ec-43aea93ab828

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-repo-cloud-openclaw-resume
Optional E2E: ubuntu-no-docker-preflight-negative, ubuntu-gateway-port-conflict-negative

Dispatch hint: ubuntu-repo-cloud-openclaw,ubuntu-repo-cloud-openclaw-resume

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 live OpenClaw onboarding scenario. It exercises repo checkout onboarding through preflight, gateway, provider/inference setup, sandbox creation, smoke inference, and credentials, covering the user-facing path most likely affected by FSM sequence and stop-state changes.
• ubuntu-repo-cloud-openclaw-resume (high): Validates interrupted/resumed onboarding with persisted session state. This is important because the PR changes onboarding sequence boundaries and introduces a partial initial slice that stops at provider_selection.

Optional E2E

• ubuntu-no-docker-preflight-negative (medium): Useful adjacent confidence for the preflight portion of the new initial slice: verifies a no-Docker preflight failure remains bounded and does not start gateway or create a sandbox.
• ubuntu-gateway-port-conflict-negative (medium): Useful adjacent confidence for the gateway portion of the new initial slice: verifies gateway startup failure classification and no sandbox side effects when the gateway port is unavailable.

New E2E recommendations

• onboarding-initial-slice-handoff (medium): Existing E2E scenarios cover full onboarding and resume, but do not appear to directly assert a standalone initial onboarding slice that pauses at provider_selection with only preflight/gateway side effects recorded.
  • Suggested test: Add a typed E2E scenario or validation assertion for initial onboarding handoff: run the initial preflight/gateway slice, assert session.machine.state is provider_selection, gateway/preflight state is recorded, and provider/sandbox work has not started.

Dispatch hint

• Workflow: .github/workflows/e2e-scenarios.yaml
• jobs input: ubuntu-repo-cloud-openclaw,ubuntu-repo-cloud-openclaw-resume

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw
Optional scenario E2E: ubuntu-repo-cloud-hermes, ubuntu-repo-openai-compatible-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/stack/onboard-fsm-flow-sequence
Head: HEAD
Confidence: medium

Required scenario E2E

• ubuntu-repo-cloud-openclaw: Core onboarding FSM sequence code changed, including the generic sequence runner and initial onboarding flow slice. The standard Ubuntu repo-current cloud OpenClaw scenario is the smallest primary scenario that exercises the real onboarding path through preflight/gateway/provider selection and validates the resulting running sandbox/gateway state.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional scenario E2E

• ubuntu-repo-cloud-hermes: Optional adjacent coverage for the same onboarding sequence machinery with the Hermes agent path, in case the FSM sequencing change interacts with agent-specific onboarding behavior.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes
• ubuntu-repo-openai-compatible-openclaw: Optional adjacent provider coverage for the OpenAI-compatible onboarding profile, since the changed flow slice stops at provider selection and provider-path differences could be relevant.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-openai-compatible-openclaw

Relevant changed files

• src/lib/onboard/machine/flow-slices.test.ts
• src/lib/onboard/machine/flow-slices.ts
• src/lib/onboard/machine/sequence-runner.ts

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 2 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 1 still applies, 1 new item found

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Pin the initial-slice handoff boundary with a negative test (src/lib/onboard/machine/flow-slices.test.ts:100): The new tests verify that the initial slice reaches `provider_selection`, but they do not explicitly prove that a supplied `provider_selection` phase is not invoked once the stop state is reached. Because this onboarding flow eventually gates provider and sandbox setup, an accidental future regression that crosses the handoff boundary could execute later setup phases earlier than intended.
  • Recommendation: Add a targeted test such as `runInitialOnboardFlowSequence does not invoke a supplied provider_selection phase after reaching the handoff state`, using a spy or throwing `provider_selection` phase. A direct adapter test such as `runOnboardSequenceWithRunner forwards stopStates without requiring a handler for the stop state` would also pin the contract at the lower layer.
  • Evidence: `runInitialOnboardFlowSequence()` passes `stopStates: ["provider_selection"]` in `flow-slices.ts`, and the current tests assert the final machine state is `provider_selection`; existing `runner.test.ts` covers runner-level stop states, but the new slice tests do not assert that the supplied later phase remains uncalled.
• Coordinate overlapping onboarding FSM slice PRs (src/lib/onboard/machine/flow-slices.ts:11): This PR adds the initial flow-slice surface while active adjacent onboarding FSM PRs also touch the same slice files. The current code is internally consistent, but stacked helpers for initial/core/final flow slices can drift in phase ownership, stop-state contracts, or duplicate test fixtures if landed independently.
  • Recommendation: Before building callers on this helper or landing the stacked series, reconcile the intended ownership and final shape with the overlapping core/final FSM slice PRs so the slice contracts remain consistent.
  • Evidence: Deterministic overlap context lists PR refactor(onboard): add core FSM flow slice #4487 and PR refactor(onboard): add final FSM flow slice #4488 touching `src/lib/onboard/machine/flow-slices.ts` and `src/lib/onboard/machine/flow-slices.test.ts`; this PR also changes those files. The previous advisor overlap warning still applies.

🌱 Nice ideas

• None.

Consider writing more tests for

• **Runtime validation** — runInitialOnboardFlowSequence does not invoke a supplied provider_selection phase after reaching the handoff state. Unit coverage exercises phase selection and the initial slice stopping at `provider_selection`, and existing runner tests cover stop states. Because this code participates in onboarding flow orchestration and handoff boundaries before provider/sandbox setup, more explicit behavioral validation would reduce migration risk.
• **Runtime validation** — runOnboardSequenceWithRunner forwards stopStates without requiring a handler for the stop state. Unit coverage exercises phase selection and the initial slice stopping at `provider_selection`, and existing runner tests cover stop states. Because this code participates in onboarding flow orchestration and handoff boundaries before provider/sandbox setup, more explicit behavioral validation would reduce migration risk.
• **Runtime validation** — runInitialOnboardFlowSequence returns immediately when the persisted machine state is already provider_selection. Unit coverage exercises phase selection and the initial slice stopping at `provider_selection`, and existing runner tests cover stop states. Because this code participates in onboarding flow orchestration and handoff boundaries before provider/sandbox setup, more explicit behavioral validation would reduce migration risk.

Since last review details

Current findings:

• Pin the initial-slice handoff boundary with a negative test (src/lib/onboard/machine/flow-slices.test.ts:100): The new tests verify that the initial slice reaches `provider_selection`, but they do not explicitly prove that a supplied `provider_selection` phase is not invoked once the stop state is reached. Because this onboarding flow eventually gates provider and sandbox setup, an accidental future regression that crosses the handoff boundary could execute later setup phases earlier than intended.
  • Recommendation: Add a targeted test such as `runInitialOnboardFlowSequence does not invoke a supplied provider_selection phase after reaching the handoff state`, using a spy or throwing `provider_selection` phase. A direct adapter test such as `runOnboardSequenceWithRunner forwards stopStates without requiring a handler for the stop state` would also pin the contract at the lower layer.
  • Evidence: `runInitialOnboardFlowSequence()` passes `stopStates: ["provider_selection"]` in `flow-slices.ts`, and the current tests assert the final machine state is `provider_selection`; existing `runner.test.ts` covers runner-level stop states, but the new slice tests do not assert that the supplied later phase remains uncalled.
• Coordinate overlapping onboarding FSM slice PRs (src/lib/onboard/machine/flow-slices.ts:11): This PR adds the initial flow-slice surface while active adjacent onboarding FSM PRs also touch the same slice files. The current code is internally consistent, but stacked helpers for initial/core/final flow slices can drift in phase ownership, stop-state contracts, or duplicate test fixtures if landed independently.
  • Recommendation: Before building callers on this helper or landing the stacked series, reconcile the intended ownership and final shape with the overlapping core/final FSM slice PRs so the slice contracts remain consistent.
  • Evidence: Deterministic overlap context lists PR refactor(onboard): add core FSM flow slice #4487 and PR refactor(onboard): add final FSM flow slice #4488 touching `src/lib/onboard/machine/flow-slices.ts` and `src/lib/onboard/machine/flow-slices.test.ts`; this PR also changes those files. The previous advisor overlap warning still applies.

Workflow run details

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