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

[cv]

Summary

Add a record-only FSM runner adapter for the post-legacy onboarding path. It creates a runtime boundary whose step helpers only update step status while runOnboardMachine() owns all machine transitions.

Changes

• Add createRecordOnlyOnboardRuntimeBoundary() to force updateMachine: false for step recording.
• Add runOnboardMachineWithRecordOnlySteps() to combine lifecycle emission, the record-only boundary, and the FSM runner.
• Add tests proving handlers can record preflight/gateway steps without moving session.machine; the runner applies those transitions explicitly.

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 a comprehensive test suite validating the record-only onboarding runner: step lifecycle recording, deterministic timing, resumed/suppressed lifecycle emission, safe session updates (with sensitive-field redaction), machine transitions, and failure handling.

• New Features

  • Added a record-only onboarding runtime and runner that records step lifecycle events (start/complete/skip/fail) and applies session updates without forcing immediate machine state changes.

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

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: c9df0ffc-3cce-4279-b8cc-e70f323531ea

📥 Commits

Reviewing files that changed from the base of the PR and between 1cfaf79 and 339ff38.

📒 Files selected for processing (1)

• src/lib/onboard/machine/record-only-runner.test.ts

---

📝 Walkthrough

Walkthrough

Adds a record-only runtime boundary and runner wrapper that records step lifecycle events without durable machine transitions, plus a Vitest harness and tests verifying lifecycle emission, record-only mutation semantics, safe-field redaction, resumed/suppressed lifecycle events, and failure isolation.

Changes

Record-only runtime boundary and runner

Layer / File(s)	Summary
Record-only boundary contracts and factory src/lib/onboard/machine/record-only-runner.ts	Introduces RecordOnlyOnboardRuntimeBoundaryOptions, RecordOnlyStepRecorders, and RecordOnlyOnboardRuntimeBoundary and the factory that forces stepMutationOptions.updateMachine = false, exposing getRuntime(), recordOnboardStarted(), and filtered step lifecycle recorders.
Record-only runner wrapper src/lib/onboard/machine/record-only-runner.ts	Adds runOnboardMachineWithRecordOnlySteps() which optionally calls recordOnboardStarted(resumed) and delegates to runOnboardMachine() using runtime: boundary.getRuntime() while passing through other runner options.
Test harness and verification src/lib/onboard/machine/record-only-runner.test.ts	Adds a Vitest harness with in-memory session cloning, deterministic time, event capture, and step mutation wiring. Tests verify lifecycle emission (onboard.started/onboard.resumed), record-only mutation enforcement, safe-field redaction/late-apply semantics, suppression of lifecycle events, and failure isolation semantics.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4373: Related lifecycle emission additions (recordOnboardStarted) that this PR uses and tests.
• NVIDIA/NemoClaw#4453: The wrapper delegates to the FSM runner introduced/modified in that PR.
• NVIDIA/NemoClaw#4457: Related gating for StepMutationOptions.updateMachine which this record-only boundary relies on.

Suggested labels

refactor, feature

Suggested reviewers

• prekshivyas
• cjagwani
• jyaunches

Poem

🐰 I hop through records, quiet and light,
I mark each step without forcing a fight,
Events whispered — started, resumed or not,
Safe secrets hidden until the runner's got,
A tiny rabbit cheers for tests done right.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.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 accurately describes the main change: adding a record-only FSM runner adapter for the onboarding system. It is concise, specific, and directly reflects the primary purpose of the changeset.
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-record-only-runner

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: ubuntu-repo-cloud-openclaw-resume, test/e2e/test-onboard-resume.sh

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. No merge-blocking E2E is recommended because the added runtime helper is currently unreferenced outside its unit test, so existing user-flow E2Es would not exercise the new code path. Unit tests are the primary validation for this PR until the runner is integrated into live onboarding.

Optional E2E

• ubuntu-repo-cloud-openclaw-resume (medium): Closest existing scenario for onboarding machine/session resume semantics. Useful as a confidence check if reviewers suspect the new runner will soon be wired into live onboarding, but this PR does not currently import it from production code.
• test/e2e/test-onboard-resume.sh (medium): Script-level resume coverage validates interrupted onboarding session state, cached step reuse, lifecycle continuation, and completion behavior adjacent to record-only step recording.

New E2E recommendations

• onboarding FSM record-only runner integration (high): No existing E2E appears to exercise createRecordOnlyOnboardRuntimeBoundary or runOnboardMachineWithRecordOnlySteps because the new source file is not referenced by current production onboarding paths. Add coverage when this adapter is wired into live onboarding to verify step helpers no longer mutate session.machine, lifecycle events remain redacted, and resume/failure paths persist correct terminal state.
  • Suggested test: Add an onboarding FSM integration E2E that runs a real non-interactive onboard/resume flow through the record-only runner path and asserts machine revisions, step statuses, terminal state, and redacted lifecycle events.

[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/main
Head: HEAD
Confidence: medium

Required scenario E2E

• None. No scenario E2E is recommended because the changed production file adds a new record-only onboard runner that is not referenced by the current scenario/onboarding execution path, and the other changed file is a unit test outside test/e2e-scenario/. These changes cannot currently be exercised by dispatchable scenario E2E jobs.

Optional scenario E2E

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor

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

Consider writing more tests for

• **Mocked behavioral coverage** — Verify `recordStepSkipped()` marks only the step as skipped, leaves `session.machine` unchanged, and a following handler result is the only transition source.. The changed adapter coordinates stateful onboarding runtime behavior. The PR adds a mocked runtime/session/event harness that covers the main record-only transition invariant and previous suggested behavioral tests.
• **Mocked behavioral coverage** — Verify `startRecordedStep(step, updates)` applies only `toSessionUpdates`-filtered context updates while still forcing `updateMachine: false`.. The changed adapter coordinates stateful onboarding runtime behavior. The PR adds a mocked runtime/session/event harness that covers the main record-only transition invariant and previous suggested behavioral tests.

Workflow run details

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