refactor(onboard): declare resume compatibility states

[cv]

Summary

Make live onboarding flow slices require callers to declare every machine state that may use compatibility execution. This keeps resume replay behavior explicit at each phase boundary while preserving the existing safety backstops.

Changes

• Tighten runLiveOnboardFlowSlice so undeclared resume states fail before phase side effects run.
• Declare resume entry and ahead states in the initial, core, and final onboarding slices.
• Update FSM slice tests to cover the explicit compatibility-state contract.

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

Summary by CodeRabbit

• Tests

  • Added and updated test coverage for onboarding state-machine resume and compatibility behavior across more phases.
  • Added a case to ensure unexpected onboarding states are rejected before any slice actions occur.

• Bug Fixes

  • Strengthened live onboarding state validation so incompatible session states fail consistently (including during resume).
  • Expanded compatibility handling to cover additional onboarding phases/states for smoother session recovery.

[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: fa895975-aac6-47bf-96a1-746c2c181e40

📥 Commits

Reviewing files that changed from the base of the PR and between dc08a1c and 07543b8.

📒 Files selected for processing (1)

• src/lib/onboard/machine/live-flow-slice.test.ts

---

📝 Walkthrough

Walkthrough

runLiveOnboardFlowSlice now throws UnexpectedLiveOnboardFlowSliceStateError when the current machine state is absent from compatibilityWhenState regardless of whether resume is set. The three flow-phase slices expand their compatibilityWhenState arrays (adding init, preflight, provider_selection, openclaw, agent_setup), and their tests seed sessions with explicit machine state metadata to match.

Changes

Compatibility State Validation and Coverage Expansion

Layer / File(s)	Summary
Live flow slice: unconditional compatibility guard and doc update src/lib/onboard/machine/live-flow-slice.ts	JSDoc is updated to remove the resume-specific framing of compatibility behavior. The guard throwing UnexpectedLiveOnboardFlowSliceStateError is changed from !resume && to an unconditional compatibilityWhenState membership check, so invalid states are rejected even when resume is true.
Phase slice compatibilityWhenState expansions src/lib/onboard/machine/initial-flow-phases.ts, src/lib/onboard/machine/core-flow-phases.ts, src/lib/onboard/machine/final-flow-phases.ts	initial-flow-phases adds init and preflight; core-flow-phases adds provider_selection; final-flow-phases adds openclaw and agent_setup to their respective compatibilityWhenState arrays.
Test updates for compatibility validation and expanded states src/lib/onboard/machine/live-flow-slice.test.ts, src/lib/onboard/machine/core-flow-phases.test.ts, src/lib/onboard/machine/final-flow-phases.test.ts	Five live-flow-slice tests now explicitly pass compatibilityWhenState values; a new test verifies that undeclared resume states reject before side effects run. Core-flow-phases and final-flow-phases tests seed createSession with explicit machine metadata (version, state, stateEnteredAt, revision) matching their targeted compatibility states.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐇 Hop through the states without fear,
resume no longer shields the unclear—
compatibilityWhenState guards every lane,
init, preflight, openclaw join the chain.
The machine checks all, fair and bright,
No state slips by in the dead of night! ✨

🚥 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 clearly summarizes the main change: declaring resume compatibility states across the onboarding flow refactor, which aligns with the core objective of enforcing explicit state declarations.
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 refactor/onboard-fsm-compat-states

---

_{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 main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	refactor/onboard-fsm... 07543b8	+/-
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 main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	refactor/onboard-fsm... 07543b8	+/-
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 23, 2026 06:16 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

E2E Advisor Recommendation

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

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 (medium): Directly validates interrupted onboard followed by onboard --resume, the highest-risk path changed by the compatibility-state behavior.
• onboard-repair-e2e (medium): Covers resume/repair backstops that must still execute when persisted machine state has advanced beyond a slice, which is exactly the compatibility behavior changed here.
• cloud-onboard-e2e (medium): Runs a full hosted-inference onboarding flow through initial, core, sandbox, policy, and finalization phases to catch real end-to-end regressions from the phase runner changes.

Optional E2E

• double-onboard-e2e (medium): Useful adjacent coverage for re-running onboarding against an existing completed/ahead-state session, but less targeted than explicit resume and repair E2Es.
• onboard-negative-paths-e2e (medium): Provides confidence that invalid or unexpected onboarding states still fail safely before side effects, matching the stricter undeclared-state behavior in runLiveOnboardFlowSlice.

New E2E recommendations

• onboard state machine compatibility (medium): Existing resume/repair E2Es cover important real flows, but there does not appear to be a narrowly targeted E2E that starts from each persisted slice-entry state such as init, preflight, provider_selection, openclaw, and agent_setup and proves resume-at-entry uses compatibility execution without skipping backstop checks.
  • Suggested test: Add a deterministic onboard state-machine compatibility E2E that seeds session.machine at each slice entry/ahead state, runs nemoclaw onboard --resume, and verifies phase backstops, transition recording, and final completion.

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
Optional Vitest E2E scenarios: onboard-repair-vitest

Dispatch required Vitest E2E scenarios:

• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-resume-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: The PR changes live onboarding flow-slice compatibility behavior for resume and ahead-state sessions across initial, core, and final phases. The wired free-standing onboard-resume Vitest job directly exercises interrupted onboard followed by nemoclaw onboard --resume and is the smallest dispatch that validates this resume contract.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-resume-vitest

Optional Vitest E2E scenarios

• onboard-repair-vitest: Adjacent coverage for resume repair flows that also depend on the onboarding machine compatibility path, especially around re-running sandbox/core-phase checks from saved session state.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-repair-vitest

Relevant changed files

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

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 0 suggestions · 2 test follow-ups
Since last review: 1 prior item resolved · 0 still apply · 0 new items found

Action checklist

• PRA-T1 Add or justify test follow-up: Runtime validation
• PRA-T2 Add or justify test follow-up: Runtime validation

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

• PRA-T1 Runtime validation — Add or identify targeted runtime/integration coverage that a resumed onboarding session whose saved machine state is outside the slice's declared compatibility list rejects before gateway, provider, sandbox, policy, or finalization handlers run.. Unit coverage is targeted and sufficient for the local state-machine contract, including the previously missing undeclared-resume fail-closed path. Because these onboarding slices eventually gate gateway, provider, sandbox, policy, and finalization side effects, a focused runtime-boundary validation would still improve confidence without relying on external E2E status.
• PRA-T2 Runtime validation — Add or identify targeted runtime/integration coverage that resume-at-entry sessions for initial, core, and final slices use the compatibility recorder while fresh non-resume entry sessions still use the strict FSM runner.. Unit coverage is targeted and sufficient for the local state-machine contract, including the previously missing undeclared-resume fail-closed path. Because these onboarding slices eventually gate gateway, provider, sandbox, policy, and finalization side effects, a focused runtime-boundary validation would still improve confidence without relying on external E2E status.

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.

[cv]

PR Review Advisor follow-up:

• PRA-T1: covered at the helper contract level by src/lib/onboard/machine/live-flow-slice.test.ts (rejects undeclared resume states before running side effects). That test exercises a resumed session with an undeclared current machine state and verifies runSlice, phase.run, and applyCompatibleResult are not called. I kept this as unit coverage because the change is the live-slice dispatch guard, not a new runtime dependency path.
• PRA-T2: covered by the wrapper/unit tests updated in this PR plus test/onboard-fsm-live-slices.test.ts, which exercises fresh strict slice entry for initial/core/final flows and resume compatibility execution for the initial slice. Broader runtime E2E coverage also passed in CI; no additional docs or integration surface changed.