refactor(onboard): apply strict step results directly

[cv]

Summary

Route validated record-only step completion results through the strict state-result path instead of the compatibility bridge. This makes recordStepCompleteWithStateResult() apply a checked transition directly, while keeping legacy/repaired-resume compatibility paths explicitly documented and isolated.

Changes

• Apply validated record-only step completion results directly after the step status write, avoiding state.result.skipped compatibility diagnostics on the strict path.
• Add focused runtime-boundary coverage for a preflight → gateway step completion result that applies directly without compatibility events.
• Clarify initial/core/final flow-slice compatibility comments with the tolerated ahead-state snapshots, their source boundaries, existing regression coverage, and removal condition.

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)

Targeted local checks run:

• npx vitest run --project cli src/lib/onboard/machine/initial-flow-phases.test.ts src/lib/onboard/machine/core-flow-phases.test.ts src/lib/onboard/machine/final-flow-phases.test.ts src/lib/onboard/runtime-boundary-record-only.test.ts src/lib/onboard/runtime-boundary.test.ts
• npm run typecheck:cli

---

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

Summary by CodeRabbit

• Bug Fixes
  • Improved onboarding resume and step-completion handling so validated results follow the direct path, reducing inconsistent “stale” transition behavior.
  • Clarified and reinforced resume behavior for onboarding flows, helping ensure repair and verification steps still run in the correct order.
• Tests
  • Added coverage to verify direct record-only step completion does not use the compatibility path.

[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: 558d7175-e70a-46e4-b8ae-0f58bf926fe1

📥 Commits

Reviewing files that changed from the base of the PR and between decb592 and c0003d3.

📒 Files selected for processing (3)

• src/lib/onboard/machine/core-flow-phases.ts
• src/lib/onboard/machine/final-flow-phases.ts
• src/lib/onboard/machine/initial-flow-phases.ts

✅ Files skipped from review due to trivial changes (3)

• src/lib/onboard/machine/core-flow-phases.ts
• src/lib/onboard/machine/final-flow-phases.ts
• src/lib/onboard/machine/initial-flow-phases.ts

---

📝 Walkthrough

Walkthrough

Updated onboarding step-completion handling to bypass the compatibility bridge for one path, added a test for that behavior, and rewrote related resume-compatibility comments in the onboarding flow slices and runtime boundary.

Changes

Onboard resume path and comment wording

Layer / File(s)	Summary
Record-step completion path src/lib/onboard/runtime-boundary.ts, src/lib/onboard/runtime-boundary-record-only.test.ts	recordStepCompleteWithStateResult now records state results directly, and the record-only test asserts the direct path without recordStateResultWithStepCompatibility.
Resume compatibility comments src/lib/onboard/machine/initial-flow-phases.ts, src/lib/onboard/machine/core-flow-phases.ts, src/lib/onboard/machine/final-flow-phases.ts, src/lib/onboard/runtime-boundary.ts	The inline comments in the onboarding phase slices and runtime boundary were rewritten to describe tolerated resume states and the steps that still re-run before later verification.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5646: Modifies the onboarding runtime boundary’s step/result compatibility flow and related tests.
• NVIDIA/NemoClaw#5648: Changes the compatibility-bridge plumbing around recordStateResultWithStepCompatibility and its interaction with step completion.
• NVIDIA/NemoClaw#5701: Touches the same onboarding step/result compatibility bridge in runtime-boundary.ts.

Suggested reviewers

• jyaunches

Poem

A bunny hopped through resume lanes,
No bridge required for step-complete gains.
The comments gleam, the path runs straight,
And little paws just celebrate. 🐰

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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 clearly captures the main behavior change: applying strict step results directly instead of through the compatibility bridge.
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 test/onboard-record-only-boundary-stale-results

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: onboard-resume-e2e, onboard-repair-e2e, cloud-onboard-e2e
Optional E2E: None

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

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• onboard-resume-e2e: Required by the onboarding resume compatibility rule because the PR touches live onboarding machine slice files and runtime-boundary compatibility behavior that can affect resume state transitions.
• onboard-repair-e2e: Required by the onboarding resume compatibility rule because repaired-resume and ahead-state replay paths rely on the same runtime boundary and flow-slice compatibility behavior changed here.
• cloud-onboard-e2e: Required because the runtime boundary change can affect the full hosted onboarding path where state results are recorded across preflight, gateway, provider selection, sandbox setup, policies, and finalization.

Optional E2E

• None.

New E2E recommendations

• None.

Dispatch hint

• Workflow: 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/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

• onboard-resume-vitest: Changes touch onboarding machine live slice resume compatibility/ahead-state handling and runtime-boundary state-result application, which must be validated by the focused live onboard resume Vitest job.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-resume-vitest
• onboard-repair-vitest: The resume compatibility and runtime-boundary changes can affect repair/backstop execution from persisted sessions, so the focused live onboard repair Vitest job is required alongside resume coverage.
  • 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/core-flow-phases.ts
• src/lib/onboard/machine/final-flow-phases.ts
• src/lib/onboard/machine/initial-flow-phases.ts
• src/lib/onboard/runtime-boundary.ts

[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: 3 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-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the test/onboard-record-... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	test/onboard-record-... c0003d3	+/-
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 test/onboard-record-... branch is 47%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	test/onboard-record-... c0003d3	+/-
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	—	70%	—
src/lib/onboard/preflight.ts	—	64%	—
src/lib/actions...licy-channel.ts	—	58%	—
src/lib/state/sandbox.ts	—	55%	—
src/lib/policy/index.ts	—	49%	—
src/lib/onboard...er-gpu-patch.ts	—	44%	—
src/lib/onboard.ts	—	18%	—

---

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