fix(onboard): emit lifecycle events for onboarding start by cv · Pull Request #4373 · NVIDIA/NemoClaw

cv · 2026-05-28T00:28:42Z

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

Summary by CodeRabbit

New Features
- Onboarding lifecycle events are now recorded when sessions start or resume. The system captures initialization and resumption details, providing enhanced tracking and visibility into whether users are beginning a fresh onboarding or continuing a previous session. This enables improved analytics and monitoring of the overall onboarding experience.

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

copy-pr-bot · 2026-05-28T00:28:45Z

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 · 2026-05-28T00:28:48Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7355b42f-12f5-4efe-bf3a-da8c21f63fc9

📥 Commits

Reviewing files that changed from the base of the PR and between ca410b5 and 4458d8f.

📒 Files selected for processing (4)

src/lib/onboard.ts
src/lib/onboard/runtime-boundary.test.ts
src/lib/onboard/runtime-boundary.ts
test/onboard-lifecycle.test.ts

📝 Walkthrough

Walkthrough

This PR adds lifecycle event recording to the onboarding flow by introducing a factory-injectable recordOnboardStarted() method on OnboardRuntimeBoundary. The boundary is enhanced with dependency injection support, integrated into the main onboard flow, and validated through both unit and end-to-end tests.

Changes

Onboard Runtime Lifecycle Recording

Layer / File(s)	Summary
Runtime Boundary Contract & Factory Pattern `src/lib/onboard/runtime-boundary.ts`	`OnboardRuntimeBoundaryOptions` now accepts an optional `createRuntime()` factory for custom runtime injection. `reset()` and `getRuntime()` use this factory (or fall back to direct instantiation), and a new `recordOnboardStarted(resumed)` method starts the runtime and returns the session.
Unit Test Harness & Boundary Validation `src/lib/onboard/runtime-boundary.test.ts`	New Vitest suite with in-memory runtime dependencies and session utilities. Test verifies `recordOnboardStarted` called twice emits ordered lifecycle events (`onboard.started`, `onboard.resumed`) each with `state: "init"`.
Main Onboard Flow Integration `src/lib/onboard.ts`	The main `onboard()` function now calls `onboardRuntimeBoundary.recordOnboardStarted(resume)` during session initialization to record the boundary lifecycle event.
End-to-End Lifecycle Test `test/onboard-lifecycle.test.ts`	New subprocess-based test that runs the built entrypoint with `fresh` and `resume` modes, spies on `recordOnboardStarted`, validates captured session details, and asserts correct lifecycle event emission and state for each mode.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

ericksoa
jyaunches
prekshivyas

Poem

🐰 A boundary recorder hops in view,
Lifecycle events, both fresh and through,
Factory patterns inject with care,
Unit tests and e2e pair,
Onboarding events hop fair and square! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(onboard): emit lifecycle events for onboarding start' directly and clearly describes the primary change: emitting lifecycle events when onboarding starts, which is the core focus of all changes across the modified and new files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 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 · 2026-05-28T00:30:07Z

E2E Advisor Recommendation

Required E2E: ubuntu-repo-cloud-openclaw-resume, ubuntu-repo-cloud-openclaw
Optional E2E: test/e2e/test-onboard-negative-paths.sh, ubuntu-repo-cloud-openclaw-double-same-provider

Dispatch hint: ubuntu-repo-cloud-openclaw-resume,ubuntu-repo-cloud-openclaw

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

ubuntu-repo-cloud-openclaw-resume (high): Covers the impacted interrupted-onboard then onboard --resume path, including persisted session state, skipped cached steps, sandbox lifecycle, and completion after resume. This is the most direct E2E for the new started/resumed lifecycle event behavior.
ubuntu-repo-cloud-openclaw (high): Validates the normal fresh cloud OpenClaw onboarding path still completes after inserting recordOnboardStarted into the main onboard flow before agent selection/preflight/sandbox creation.

Optional E2E

test/e2e/test-onboard-negative-paths.sh (medium): Useful adjacent confidence for non-interactive onboarding edge cases because the new lifecycle call runs before many validation and preflight failures; not merge-blocking if the resume and fresh scenario E2Es pass.
ubuntu-repo-cloud-openclaw-double-same-provider (high): Optional coverage for repeated fresh onboarding/lifecycle reuse. The touched code runs at the start of each onboard invocation, but the direct risk is lower than fresh and resume basics.

New E2E recommendations

onboarding lifecycle event assertions (medium): Existing live E2Es validate onboarding outcomes, but this PR adds lifecycle started/resumed event emission. Add an E2E assertion that the emitted machine events or persisted lifecycle trace contains onboard.started for fresh runs and onboard.resumed for resume runs at the expected point after session load/create.
- Suggested test: Extend the ubuntu-repo-cloud-openclaw-resume scenario or test/e2e/test-onboard-resume.sh to assert onboard.started/onboard.resumed lifecycle events are emitted/persisted in live CLI execution.

Dispatch hint

Workflow: .github/workflows/e2e-scenarios.yaml
jobs input: ubuntu-repo-cloud-openclaw-resume,ubuntu-repo-cloud-openclaw

github-actions · 2026-05-28T00:30:08Z

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw, ubuntu-repo-cloud-openclaw-resume
Optional scenario E2E: ubuntu-repo-cloud-hermes

Dispatch required scenario E2E:

gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-resume

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

ubuntu-repo-cloud-openclaw: Production onboarding entrypoint/runtime-boundary changes add lifecycle recording during fresh onboarding; the primary Ubuntu repo cloud OpenClaw scenario exercises the normal fresh onboarding path and baseline post-onboarding behavior.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
ubuntu-repo-cloud-openclaw-resume: The change explicitly differentiates fresh versus resumed onboarding lifecycle events; this scenario is the routed resume-after-interrupt OpenClaw path and is the smallest direct coverage for resume behavior.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-resume

Optional scenario E2E

ubuntu-repo-cloud-hermes: Optional adjacent coverage for the same onboarding lifecycle boundary with the Hermes agent, in case agent-specific onboarding sequencing is a concern.
- Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes

Relevant changed files

src/lib/onboard.ts
src/lib/onboard/runtime-boundary.ts

github-actions · 2026-05-28T00:31:16Z

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 0 still apply, 0 new items found

Workflow run details

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

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

cv added 5 commits May 27, 2026 15:18

docs(onboard): document FSM migration target

6b753bf

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

refactor(onboard): centralize machine state metadata

fb1b32d

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

refactor(onboard): derive session step mapping from FSM metadata

c3e4ad6

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

refactor(onboard): derive progress labels from FSM metadata

603832c

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

fix(onboard): emit lifecycle events for onboarding start

4fad8e7

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

cv self-assigned this May 28, 2026

wscurran added enhancement: feature labels May 28, 2026

cv added the onboarding label May 29, 2026

cv mentioned this pull request May 29, 2026

Track onboard FSM migration stack and resume compatibility #4533

Closed

Base automatically changed from stack/onboard-fsm-progress-metadata to main June 1, 2026 19:20

cv added 4 commits June 1, 2026 12:42

merge(main): sync onboard lifecycle branch

bf88fc7

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

test(onboard): cover entrypoint lifecycle events

f98631d

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

fix(onboard): keep lifecycle hook budget neutral

8be4acd

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

Merge branch 'main' into stack/onboard-fsm-lifecycle-events

4458d8f

cv marked this pull request as ready for review June 1, 2026 20:23

cv requested review from cjagwani, ericksoa, jyaunches and prekshivyas June 1, 2026 20:23

cv merged commit 480e82e into main Jun 1, 2026
37 checks passed

cv deleted the stack/onboard-fsm-lifecycle-events branch June 1, 2026 22:35

wscurran added area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow bug-fix PR fixes a bug or regression feature PR adds or expands user-visible functionality labels Jun 3, 2026

wscurran removed enhancement: feature labels Jun 3, 2026

This was referenced Jun 5, 2026

refactor(onboard): add record-only FSM runner adapter #4461

Merged

fix(onboard): ignore policy tier env in interactive mode #4864

Merged

wscurran removed the feature PR adds or expands user-visible functionality label Jun 9, 2026

Conversation

cv commented May 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

copy-pr-bot Bot commented May 28, 2026

Uh oh!

coderabbitai Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

github-actions Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Scenario Advisor Recommendation

E2E Scenario Advisor

Required scenario E2E

Optional scenario E2E

Relevant changed files

Uh oh!

github-actions Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cv commented May 28, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented May 28, 2026 •

edited

Loading