refactor(onboard): allow step recording without machine transitions

[cv]

Summary

Add a record-only mode to onboarding session step helpers. The default behavior remains unchanged, but future runtime-driven paths can update step status without also mutating the durable machine snapshot.

Changes

• Add StepMutationOptions with updateMachine?: boolean to src/lib/state/onboard-session.ts.
• Let markStepStarted, markStepComplete, and markStepFailed skip machine snapshot transitions when updateMachine: false.
• Add session tests proving step status/failure metadata still persists while machine state stays unchanged in record-only mode.

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

  • Step mutation operations (starting, completing, and failing steps) now accept optional configuration parameters for enhanced control over machine state updates.
  • Added new methods to record step results while managing state transitions independently.

• Tests

  • Added comprehensive test coverage for "record-only" step mutation behavior.

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

Warning

Review limit reached

@cv, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 91 minutes and 9 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: af29d917-89cd-44be-a57e-62bc574bf2a7

📥 Commits

Reviewing files that changed from the base of the PR and between f03adbc and 13745bd.

📒 Files selected for processing (10)

• src/lib/onboard/machine/runner.test.ts
• src/lib/onboard/machine/runtime.test.ts
• src/lib/onboard/machine/runtime.ts
• src/lib/onboard/runtime-boundary-record-only.test.ts
• src/lib/onboard/runtime-boundary.test.ts
• src/lib/onboard/runtime-boundary.ts
• src/lib/state/onboard-session.ts
• src/lib/state/onboard-step-mutation.test.ts
• src/lib/state/onboard-step-mutation.ts
• src/lib/state/onboard-step-state.ts

📝 Walkthrough

Walkthrough

The PR introduces an optional StepMutationOptions flag to onboard step mutation methods, enabling record-only mode where machine snapshots are not updated. New runtime boundary methods pair step recording with explicit FSM result application, and comprehensive tests validate that step state persists while machine state remains unchanged.

Changes

Conditional machine snapshot updates via StepMutationOptions

Layer / File(s)	Summary
StepMutationOptions contract and default-true helper src/lib/state/onboard-step-mutation.ts	Introduces StepMutationOptions interface with optional updateMachine boolean and shouldUpdateMachine() helper that defaults to true unless explicitly set to false.
Runtime API extension for options forwarding src/lib/onboard/machine/runtime.ts	OnboardRuntimeDeps interface and OnboardRuntime class methods (markStepStarted, markStepComplete, markStepFailed) updated to accept optional StepMutationOptions and forward to deps.
Session implementation of options-gated mutations src/lib/state/onboard-session.ts	markStepStarted, markStepComplete, and markStepFailed conditionally gate machine snapshot transitions and event emissions based on shouldUpdateMachine(options), with imports adjusted.
Runtime boundary recorder methods for step-and-result pattern src/lib/onboard/runtime-boundary.ts	OnboardRuntimeBoundary adds recordStepCompleteWithStateResult and recordStepFailedWithStateResult that call step mutations with updateMachine: false then apply corresponding FSM results.
Test harness and record-only mutation validation src/lib/onboard/runtime-boundary.test.ts, src/lib/state/onboard-session.test.ts, src/lib/state/onboard-step-mutation.test.ts	Test harness updated to handle options-controlled transitions; new tests verify record-only mutations persist per-step state while keeping machine snapshot unchanged and pair with explicit state results.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant OnboardRuntimeBoundary
  participant OnboardSession
  participant FSMRecorder
  
  Caller->>OnboardRuntimeBoundary: recordStepCompleteWithStateResult(stepName, updates, result)
  OnboardRuntimeBoundary->>OnboardSession: markStepComplete(stepName, updates, {updateMachine: false})
  OnboardSession->>OnboardSession: persist step updates, skip machine snapshot
  OnboardSession-->>OnboardRuntimeBoundary: session
  OnboardRuntimeBoundary->>FSMRecorder: apply explicit FSM result
  FSMRecorder->>FSMRecorder: update machine snapshot with result
  FSMRecorder-->>OnboardRuntimeBoundary: session
  OnboardRuntimeBoundary-->>Caller: session

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4375: The main PR's new runtime-boundary "record*WithStateResult" methods depend on the explicit onboard state result types like OnboardStateFailedResult introduced in that PR.
• NVIDIA/NemoClaw#4443: The main PR extends runtime-boundary.ts with recordStepCompleteWithStateResult/recordStepFailedWithStateResult that reconcile step outcomes via the same recordStateResult FSM result-recording mechanism.

Suggested reviewers

• prekshivyas
• cjagwani
• ericksoa

Poem

🐰 A rabbit hops through the machine state,
Now choosing whether to translate—
Record the step or shift the FSM,
An escape hatch for logic's whim!
With options gated, control is ours,
Step mutations bloom with newfound powers. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor(onboard): allow step recording without machine transitions' directly and clearly describes the main change: introducing a record-only mode for onboarding step helpers that decouples step status recording from FSM snapshot mutations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/onboard-fsm-step-record-only

---

_{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-negative-paths-e2e, double-onboard-e2e

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

Auto-dispatched E2E: cloud-onboard-e2e, onboard-resume-e2e via nightly-e2e.yaml at 13745bdc4675d3d30f0905fcb4b7c23317760cde — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard-e2e (high): Runs a clean non-interactive install and cloud onboarding flow, validating that the changed session mutation and FSM runtime still produce a working sandbox and live inference route.
• onboard-resume-e2e (high): Directly targets interrupted onboarding session persistence and resume. This is the highest-signal E2E for changes to step status, failure recording, lastCompletedStep, machine snapshots, and resumable completion.

Optional E2E

• onboard-negative-paths-e2e (high): Useful confidence for changed failure semantics: invalid provider keys, gateway port conflicts, and non-interactive validation should still fail cleanly without stale session or sandbox side effects.
• double-onboard-e2e (very high): Adjacent lifecycle coverage for repeated onboarding and stale registry reconciliation; helpful because session and machine snapshot behavior can affect repeat onboard reuse and cleanup decisions.

New E2E recommendations

• onboarding FSM/session snapshot audit (medium): Existing E2Es validate successful and resumed onboarding, but do not appear to explicitly assert the persisted machine.state/revision and event sequence across each live onboarding step after the record-only migration.
  • Suggested test: Add an E2E or scenario validation step that inspects ~/.nemoclaw/onboard-session.json after live onboarding and after forced failure/resume, asserting machine.state, revision monotonicity, step statuses, and sanitized failure fields.

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: ubuntu-repo-cloud-openclaw, ubuntu-repo-cloud-hermes, ubuntu-no-docker-preflight-negative
Optional scenario E2E: ubuntu-repo-cloud-openclaw-resume, wsl-repo-cloud-openclaw, macos-repo-cloud-openclaw, gpu-repo-local-ollama-openclaw

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-hermes
• gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-no-docker-preflight-negative

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• ubuntu-repo-cloud-openclaw: Core onboarding runtime/session state changes affect normal repo-current Ubuntu cloud OpenClaw onboarding, including step completion, machine transitions, context updates, and final ready-state validation.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
• ubuntu-repo-cloud-hermes: The changed step-to-machine state logic and runtime boundary paths are shared across agents; Hermes is the primary non-OpenClaw cloud onboarding path in the route table and exercises the alternate agent-specific flow.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes
• ubuntu-no-docker-preflight-negative: The PR changes onboarding failure/session mutation behavior, including record-only failed steps and machine failure transitions; the no-Docker preflight negative scenario is the smallest routed scenario that validates failed onboarding does not create downstream side effects.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-no-docker-preflight-negative

Optional scenario E2E

• ubuntu-repo-cloud-openclaw-resume: Optional adjacent coverage for resume-after-interrupt behavior because the changed code owns persisted onboarding session and machine snapshots.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-resume
• wsl-repo-cloud-openclaw: Optional platform coverage for the same cloud OpenClaw onboarding/session flow under WSL; special-runner/platform scenarios are not the primary target unless platform-specific code changed.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=wsl-repo-cloud-openclaw
• macos-repo-cloud-openclaw: Optional macOS CLI/onboarding-adjacent coverage for the same repo-current code path on a different platform; macOS is not required because the changes are not platform-specific.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=macos-repo-cloud-openclaw
• gpu-repo-local-ollama-openclaw: Optional local Ollama/GPU coverage because the onboarding runtime/session changes are provider-agnostic, but this requires a special GPU runner and is not the primary cloud onboarding target.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=gpu-repo-local-ollama-openclaw

Relevant changed files

• src/lib/onboard/machine/runtime.ts
• src/lib/onboard/runtime-boundary.ts
• src/lib/state/onboard-session.ts
• src/lib/state/onboard-step-mutation.ts
• src/lib/state/onboard-step-state.ts

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 1 worth checking, 0 nice ideas
Top item: PR review advisor unavailable

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• PR review advisor unavailable: The automated advisor could not complete: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt
  • Recommendation: Re-run the PR Review Advisor or perform a manual review.
  • Evidence: Could not parse JSON from PR review advisor output; see /home/runner/work/NemoClaw/NemoClaw/artifacts/pr-review-advisor/pr-review-advisor-raw-output.txt

🌱 Nice ideas

• None.

Consider writing more tests for

• **Mocked behavioral coverage** — Add or confirm behavioral tests with mocked filesystem/network/process boundaries.. Changed code has I/O, state, credentials, provider, or config behavior that should be covered with behavioral mocks: src/lib/onboard/machine/runtime.ts, src/lib/onboard/runtime-boundary.ts, src/lib/state/onboard-session.ts, src/lib/state/onboard-step-mutation.ts, src/lib/state/onboard-step-state.ts.

Workflow run details

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

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26979729422
Target ref: 758367adb601595c071d2d235da8713c0d829d87
Workflow ref: stack/onboard-fsm-consume-results-compat
Requested jobs: onboard-resume-e2e,cloud-onboard-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
onboard-resume-e2e	✅ success

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26989143258
Target ref: f03adbcb6343fef03d598c94fabe868e6968dd90
Workflow ref: main
Requested jobs: cloud-onboard-e2e,onboard-resume-e2e,onboard-negative-paths-e2e
Summary: 3 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
onboard-negative-paths-e2e	✅ success
onboard-resume-e2e	✅ success

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26989919414
Target ref: 13745bdc4675d3d30f0905fcb4b7c23317760cde
Workflow ref: main
Requested jobs: cloud-onboard-e2e,onboard-resume-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
onboard-resume-e2e	✅ success