refactor(onboard): extract agent policy finalization FSM phases

[cv]

Summary

Add reusable FSM phase wrappers for agent setup, policy setup, finalization, and post-verification. These wrappers cover the branch-to-completion half of onboarding.

Changes

• Add agent setup and OpenClaw setup phase wrappers.
• Add policies, finalization, and post-verify phase wrappers.
• Add tests for branch-specific phase state names, context updates, finalizing transitions, and terminal completion results.

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: 6deefb8c-4fc2-47fe-b64d-85664127f879

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-agent-policy-finalization-phases

---

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

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 1 worth checking, 0 nice ideas
Top item: Add runtime/sequence-runner coverage for the new FSM phase wrappers

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• New branch-to-completion phase wrappers are not validated through the real FSM runner (src/lib/onboard/machine/flow-phases/agent-policy-finalization.ts:31): The PR adds exported wrappers for `agent_setup`, `openclaw`, `policies`, `finalizing`, and `post_verify`, but repository search shows these helpers are currently imported only by `agent-policy-finalization.test.ts`. The tests cover direct wrapper state/result behavior, but they do not prove these new wrappers compose with `runOnboardSequenceWithRunner`, duplicate-phase detection, or transition validation in the production FSM path.
  • Recommendation: Add a focused integration smoke test that builds these wrappers into a `runOnboardSequenceWithRunner` phase list and verifies the branch-to-completion path through the strict FSM, or wire the wrappers into the onboarding sequence in this PR if this is intended to be a complete extraction.
  • Evidence: `agent-policy-finalization.ts` exports the new factories; `grep` found no production imports of `createAgentSetupPhase`/related helpers outside `agent-policy-finalization.test.ts`. Existing sequence-runner integration exists in `sequence-runner.ts`, but this diff does not exercise these wrappers through it.

🌱 Nice ideas

• None.

Workflow run details

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: ubuntu-repo-cloud-openclaw, ubuntu-repo-cloud-hermes, onboard-resume-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-provider-sandbox-phases
Head: HEAD
Confidence: high

Required E2E

• None. No merge-blocking E2E is recommended: the PR adds an unused onboarding phase-helper module plus unit tests, and inspection found no production imports/call sites that would change installer, onboarding, sandbox lifecycle, credentials, policy enforcement, inference routing, or assistant runtime behavior.

Optional E2E

• ubuntu-repo-cloud-openclaw (medium): Optional confidence check for the normal OpenClaw onboarding path through openclaw -> policies -> finalizing/post_verify if maintainers want live validation of the adjacent FSM phases.
• ubuntu-repo-cloud-hermes (medium): Optional confidence check for the alternate agent_setup branch represented by the new helper's createAgentSetupPhase path.
• onboard-resume-e2e (medium): Optional targeted check because the existing resume E2E forces interruption at policies and resumes through finalization; useful if this helper is wired into runtime before merge.

New E2E recommendations

• None.

[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-provider-sandbox-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.