refactor(onboard): default runtime steps to record-only

[cv]

Summary

Default OnboardRuntime step recording methods to record-only machine mutations. This moves the runtime closer to being the single source of machine transitions while preserving an explicit override for legacy tests and compatibility paths.

Changes

• Export shared RECORD_ONLY_STEP_MUTATION_OPTIONS from onboard-step-mutation.
• Use the shared record-only default in OnboardRuntime and OnboardRuntimeBoundary.
• Add runtime tests proving default step recording forwards record-only options while explicit overrides still work.

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

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• 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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: af4f6120-ee8f-46be-831f-2973a8bfb4ad

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 refactor/onboard-fsm-runtime-record-only

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the refactor/onboard-fsm... branch is 96%. Coverage data for the refactor/onboard-fsm... branch is not yet available.

Show a code coverage summary of the most covered files.

File	refactor/onboard-fsm...	refactor/onboard-fsm... ebd7ed9	+/-
nemoclaw/src/se...cret-scanner.ts	—	100%	—
nemoclaw/src/commands/slash.ts	—	100%	—
nemoclaw/src/li...bprocess-env.ts	—	100%	—
nemoclaw/src/bl...eprint/state.ts	—	98%	—
nemoclaw/src/onboard/config.ts	—	98%	—
nemoclaw/src/bl...int/snapshot.ts	—	97%	—
nemoclaw/src/bl...print/runner.ts	—	95%	—
nemoclaw/src/co...ration-state.ts	—	94%	—
nemoclaw/src/bl...ate-networks.ts	—	94%	—
nemoclaw/src/index.ts	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the refactor/onboard-fsm... branch is 46%. Coverage data for the refactor/onboard-fsm... branch is not yet available.

Show a code coverage summary of the most covered files.

File	refactor/onboard-fsm...	refactor/onboard-fsm... ebd7ed9	+/-
src/lib/state/o...oard-session.ts	—	91%	—
src/lib/inference/local.ts	—	76%	—
src/lib/sandbox/config.ts	—	72%	—
src/lib/actions...dbox/rebuild.ts	—	67%	—
src/lib/onboard/preflight.ts	—	64%	—
src/lib/actions...licy-channel.ts	—	56%	—
src/lib/state/sandbox.ts	—	55%	—
src/lib/onboard...er-gpu-patch.ts	—	50%	—
src/lib/policy/index.ts	—	49%	—
src/lib/onboard.ts	—	18%	—

---

_{Updated June 24, 2026 04:11 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[github-actions]

E2E Advisor Recommendation

Required E2E: onboard-resume-e2e, onboard-repair-e2e, cloud-onboard-e2e
Optional E2E: onboard-negative-paths-e2e, double-onboard-e2e

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

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/refactor/onboard-fsm-record-only-boundary
Head: HEAD
Confidence: high

Required E2E

• onboard-resume-e2e (medium): Required by the onboarding resume compatibility rule because this PR changes onboarding runtime machine/step mutation behavior that can affect persisted resume states and resumed state transitions.
• onboard-repair-e2e (medium): Required by the onboarding resume compatibility rule because repair flows depend on the same persisted machine state and record-only step mutation semantics changed by this PR.
• cloud-onboard-e2e (high): Required because the runtime default step mutation behavior can affect the full hosted onboarding flow where explicit state results must remain the durable machine source of truth.

Optional E2E

• onboard-negative-paths-e2e (medium): Useful adjacent confidence for failure/skip/error paths because markStepFailed default behavior changed from machine-updating to record-only unless explicitly overridden.
• double-onboard-e2e (medium): Optional confidence that repeated onboarding still observes the intended persisted session and machine state after changing default runtime step recording semantics.

New E2E recommendations

• None.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: onboard-resume-e2e,onboard-repair-e2e,cloud-onboard-e2e

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: onboard-resume-vitest, onboard-repair-vitest
Optional Vitest E2E scenarios: None

Dispatch required Vitest E2E scenarios:

• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-resume-vitest
• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-repair-vitest

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/refactor/onboard-fsm-record-only-boundary
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

• onboard-resume-vitest: Changes alter OnboardRuntime and OnboardRuntimeBoundary step mutation defaults for record-only machine updates. This is onboarding state-machine live slice orchestration and can affect persisted session state used by --resume, so the onboarding resume compatibility rule requires the focused live resume job.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-resume-vitest
• onboard-repair-vitest: The same record-only step mutation and runtime-boundary changes can affect repair/backstop behavior from persisted resumable sessions, including recreating missing sandbox state during resume. The onboarding resume compatibility rule makes repair required for these state-machine resume paths.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-repair-vitest

Optional Vitest E2E scenarios

• None.

Relevant changed files

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