refactor(onboard): introduce explicit state result types

[cv]

Summary

Introduce explicit result types and helpers for future onboarding state handlers. This prepares handlers to return transition, completion, and failure decisions without changing live orchestration yet.

Changes

• Add src/lib/onboard/machine/result.ts with transition, complete, and failed state-result types.
• Add helper constructors for advance, retry, branch, complete, and failed results.
• Add tests for the result helper shapes and metadata/update preservation.

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: 17e64365-3f15-4987-8c65-24f0b0244493

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-state-results

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: ubuntu-repo-cloud-openclaw-resume, ubuntu-repo-cloud-openclaw-repair

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

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-resume-conflict-events
Head: HEAD
Confidence: high

Required E2E

• None. No merge-blocking E2E is required for this PR as shown: it adds a new onboarding FSM helper module plus unit tests, and the diff does not wire the helper into the live CLI onboarding runtime, installer, sandbox lifecycle, credentials, network policy, or inference routing paths.

Optional E2E

• ubuntu-repo-cloud-openclaw-resume (high; requires NVIDIA_API_KEY and Docker/OpenShell sandbox lifecycle): Closest existing E2E for onboarding FSM/resume semantics. Useful as a confidence check if reviewers believe these new result helpers may be wired into resume handling by surrounding branch changes.
• ubuntu-repo-cloud-openclaw-repair (high; requires NVIDIA_API_KEY and Docker/OpenShell sandbox lifecycle): Adjacent coverage for resume repair and conflict/invalidation behavior, which is related to onboarding state transitions and failure results but not directly changed by this helper-only diff.

New E2E recommendations

• onboarding-fsm-result-application (medium): There is no dedicated E2E that asserts state handlers returning explicit OnboardStateResult values are applied through OnboardRuntime with expected state events, failure metadata, and secret redaction. Add this when the helpers become wired into live handler execution.
  • Suggested test: Add a focused onboarding FSM events/resume-conflict E2E that forces transition, retry/branch, complete, and failed handler results and validates emitted JSONL events remain redacted.

Dispatch hint

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

[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-resume-conflict-events
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
Top item: No actionable code findings

Workflow run details

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