refactor(onboard): make policy setup return FSM result

[cv]

Summary

Make the policy setup handler return its explicit FSM transition result. The handler now reports the policies -> finalizing transition and carries applied policy preset metadata for future machine-driven orchestration.

Changes

• Add stateResult to PoliciesStateResult.
• Return advanceTo("finalizing") with policy preset metadata.
• Extend policy handler tests for the returned FSM result.

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: da1c82de-7e9f-4958-af90-a358bf3af6b5

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-policies-result

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: cloud-onboard-e2e, onboard-resume-e2e
Optional E2E: network-policy-e2e, ubuntu-repo-cloud-openclaw-resume

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

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-agent-setup-result
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard-e2e (medium): Covers real cloud onboarding with custom policy mode and policy presets, exercising policy setup, session completion, finalization, and deployment verification after the policies handler runs.
• onboard-resume-e2e (medium): Covers an interrupted onboarding run that fails at the policies step, then resumes and verifies the policies step and overall session complete successfully. This is the highest-signal existing E2E for the changed resume-related policy handler path.

Optional E2E

• network-policy-e2e (medium): Optional adjacent coverage for the actual sandbox network-policy/security boundary managed by policy presets. Useful if maintainers want extra confidence beyond onboarding flow coverage.
• ubuntu-repo-cloud-openclaw-resume (medium): Typed scenario coverage for cloud OpenClaw resume behavior; overlaps with onboard-resume-e2e but validates the scenario-runner path.

New E2E recommendations

• onboarding-fsm-transition-recording (medium): Existing E2E flows validate that onboarding completes, but there does not appear to be an E2E assertion that the policies handler's machine transition result is recorded or consumed before finalization. A future regression could leave the coarse FSM state inconsistent while the legacy direct flow still completes.
  • Suggested test: Add an E2E or scenario assertion that an onboard run records the policies -> finalizing transition/result in the onboard trace or machine state artifact before final completion.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: cloud-onboard-e2e,onboard-resume-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-setup-result
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.