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

Summary by CodeRabbit

• Tests

  • Added comprehensive test coverage for onboarding workflow phases, including phase transitions, state management, and completion validation across multiple scenarios.

• Refactor

  • Introduced helper utilities for onboarding phase construction to ensure consistency and improve maintainability of the workflow system.

[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]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/machine/flow-phases/agent-policy-finalization.test.ts`:
- Around line 60-62: The updateSession helper currently discards in-place
mutations because it uses `mutator(cloneSession(session)) ?? session`; change it
to keep the mutated draft when the mutator returns void by capturing the draft
result and falling back to that draft instead of the original session. In other
words, call the mutator with a cloned draft, store the draft after the mutator
runs, and use the mutator's return value if present or the mutated draft
otherwise before assigning/returning the cloned session; update references to
`updateSession`, `mutator`, `cloneSession`, `Session`, and the
`OnboardRuntimeDeps.updateSession` contract accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 95e00996-91cf-4f8f-84a9-c3858e851c9c

📥 Commits

Reviewing files that changed from the base of the PR and between 4a02d04 and e55a6d4.

📒 Files selected for processing (2)

• src/lib/onboard/machine/flow-phases/agent-policy-finalization.test.ts
• src/lib/onboard/machine/flow-phases/agent-policy-finalization.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Preserve in-place session mutations when mutator returns void.

At Line 61, mutator(...) ?? session drops mutations if the mutator uses the allowed void return path. Use the mutated draft as fallback to honor the OnboardRuntimeDeps.updateSession contract.

Suggested patch

 const updateSession = (mutator: (value: Session) => Session | void): Session => {
-  session = cloneSession(mutator(cloneSession(session)) ?? session);
+  const draft = cloneSession(session);
+  session = cloneSession(mutator(draft) ?? draft);
   return cloneSession(session);
 };

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const updateSession = (mutator: (value: Session) => Session | void): Session => {
	session = cloneSession(mutator(cloneSession(session)) ?? session);
	return cloneSession(session);
	const updateSession = (mutator: (value: Session) => Session | void): Session => {
	const draft = cloneSession(session);
	session = cloneSession(mutator(draft) ?? draft);
	return cloneSession(session);
	};

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/machine/flow-phases/agent-policy-finalization.test.ts` around
lines 60 - 62, The updateSession helper currently discards in-place mutations
because it uses `mutator(cloneSession(session)) ?? session`; change it to keep
the mutated draft when the mutator returns void by capturing the draft result
and falling back to that draft instead of the original session. In other words,
call the mutator with a cloned draft, store the draft after the mutator runs,
and use the mutator's return value if present or the mutated draft otherwise
before assigning/returning the cloned session; update references to
`updateSession`, `mutator`, `cloneSession`, `Session`, and the
`OnboardRuntimeDeps.updateSession` contract accordingly.

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 27229119067
Target ref: e55a6d485e0d80a6d3b9d75e0b8ac2330d9dc1b6
Workflow ref: main
Requested jobs: cloud-onboard-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success