refactor(onboard): make finalization return FSM result

[cv]

Summary

Make the finalization handler return an explicit terminal FSM result instead of completing the session inside the handler. The live onboard flow now applies that result through OnboardRuntime via the runtime boundary.

Changes

• Change handleFinalizationState() to return completeOnboardMachine(...) metadata and updates.
• Add recordStateResult() to OnboardRuntimeBoundary and use it from src/lib/onboard.ts after finalization completes.
• Update finalization tests to assert the returned FSM completion 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: e718de43-fa8a-45fd-864b-2f21037a8029

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-finalization-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: onboard-repair-e2e, credential-migration-e2e

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

Workflow run

Full advisor summary

E2E Recommendation Advisor

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

Required E2E

• cloud-onboard-e2e (high; live Docker/OpenShell sandbox plus NVIDIA API key): Required fresh-onboard coverage for a real install/onboard flow through finalization: verifies sandbox health, deployment/security checks, and catches regressions where finalization no longer completes after deployment verification.
• onboard-resume-e2e (high; live Docker/OpenShell sandbox plus NVIDIA API key, timeout 60m): Required because the change moves completion to runtime.applyResult(); this E2E interrupts onboarding, resumes, and explicitly asserts ~/.nemoclaw/onboard-session.json reaches status=complete with all expected steps complete.

Optional E2E

• onboard-repair-e2e (high; live Docker/OpenShell sandbox plus NVIDIA API key, timeout 60m): Useful adjacent confidence for the same onboard session/runtime machinery: validates resume repair and conflict handling when recorded sandbox state is stale or requested inputs differ.
• credential-migration-e2e (medium-high; live sandbox plus credential migration checks): Optional adjacent guard because the modified finalization handler still performs legacy credential cleanup. Run if reviewers want extra confidence that the refactor did not disturb final cleanup side effects.

New E2E recommendations

• onboarding-finalization-state (high): Existing fresh onboard E2Es validate sandbox delivery but do not appear to explicitly assert the final onboard session machine/result fields after a successful non-resume run. The resume E2E asserts status=complete, but a direct fresh-finalization assertion would cover the new recordStateResult(applyResult) path without relying on resume setup.
  • Suggested test: Add a fresh onboard finalization assertion that verifies ~/.nemoclaw/onboard-session.json has status=complete and the expected final machine state/result metadata after dashboard/deployment verification succeeds.

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-apply-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
Top item: No actionable findings

Workflow run details

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