fix(onboard): emit lifecycle events for onboarding start

[cv]

Summary

Emit the existing onboarding lifecycle machine events from the live onboard entrypoint. Fresh sessions now emit onboard.started, and resumed sessions emit onboard.resumed, through the runtime boundary after the session is available.

Changes

• Add recordOnboardStarted() to src/lib/onboard/runtime-boundary.ts.
• Call the runtime boundary from src/lib/onboard.ts once fresh/resume session setup completes.
• Add src/lib/onboard/runtime-boundary.test.ts coverage for lifecycle event dispatch.

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: 8edd4196-f5a2-4e03-8123-a5ae80f6f732

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-lifecycle-events

---

_{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: ubuntu-repo-cloud-openclaw-resume, cloud-e2e

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

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/stack/onboard-fsm-progress-metadata
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard-e2e (medium): Exercises the real fresh non-interactive cloud onboarding path after the new recordOnboardStarted(false) call is inserted into onboard(). This should catch regressions where lifecycle event recording prevents or corrupts normal onboarding/session progress.
• onboard-resume-e2e (medium): Directly validates interrupted onboard followed by nemoclaw onboard --resume; this PR changes the live resume lifecycle event path via recordOnboardStarted(true), so resume must be merge-blocking.

Optional E2E

• ubuntu-repo-cloud-openclaw-resume (medium): Typed scenario coverage for cloud OpenClaw resume-after-interrupt. Useful as a second harness around the same user flow and scenario metadata, but overlaps with onboard-resume-e2e.
• cloud-e2e (medium): Full install → onboard → sandbox verify → live inference confidence for the general user journey. Optional because cloud-onboard-e2e already targets the changed onboarding entry path more directly.

New E2E recommendations

• onboarding lifecycle event persistence (medium): Existing resume/onboard E2E validates session completion and skip behavior, but does not appear to assert that the live session machine/event history contains onboard.started on fresh runs and onboard.resumed on resume runs. Add assertions to the resume E2E or typed resume scenario to verify these persisted events after each phase.
  • Suggested test: Extend test/e2e/test-onboard-resume.sh or the ubuntu-repo-cloud-openclaw-resume scenario with session machine event assertions for onboard.started/onboard.resumed.

Dispatch hint

• Workflow: 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-progress-metadata
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, 1 worth checking, 0 nice ideas
Top item: Add live onboard-entrypoint lifecycle event coverage

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Live onboard lifecycle emission is not directly tested (src/lib/onboard.ts:6679): The new test verifies that OnboardRuntimeBoundary.recordOnboardStarted delegates to the runtime and emits started/resumed events, but it does not exercise the changed live onboard entrypoint. A future refactor could remove or reorder the call in onboard() while the boundary test still passes.
  • Recommendation: Add a mocked behavioral test around the onboard entry flow, or an extracted orchestration seam, asserting fresh sessions emit onboard.started and resumed sessions emit onboard.resumed after session setup and before the first recorded step.
  • Evidence: src/lib/onboard.ts now calls await recordOnboardStarted(resume) at line 6679; src/lib/onboard/runtime-boundary.test.ts only calls boundary.recordOnboardStarted(false/true) directly and does not invoke onboard().

🌱 Nice ideas

• None.

Workflow run details

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