Walkthrough

Introduces a state machine runner that executes onboarding transitions through non-terminal states with handler dispatch and transition limits, adds runtime-boundary-level compatibility logic to coexist with legacy step helpers, extends event vocabulary for skip events, and integrates compatibility-aware result recording into the main onboarding orchestration.

Changes

Onboarding state machine runner and compatibility bridge

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4446: Updates preflight and gateway handlers to return explicit FSM transition objects that pair directly with this PR's compatibility-aware recording of those results.
• NVIDIA/NemoClaw#4444: Makes handleAgentSetupState return explicit FSM transitions, complementing this PR's compatible recording at the agent-setup handler point.
• NVIDIA/NemoClaw#4445: Updates handlePoliciesState to return explicit FSM transitions to finalizing, aligning with this PR's policy-setup handler recording changes.

Suggested labels

onboarding

Suggested reviewers

• prekshivyas
• cjagwani
• ericksoa

🐰 A runner hops through states so fine,
Each transition marked by a clean design,
When old and new paths both take flight,
We skip and emit—just right! ✨

❌ Failed checks (1 warning)

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• cloud-onboard-e2e (high): Baseline full cloud onboarding is required because the main onboard flow now consumes every major state result through the new compatibility path and could regress sandbox creation, provider setup, policies, or final completion.
• onboard-resume-e2e (high): Direct coverage for interrupted onboard followed by --resume; this PR specifically changes how stale/already-applied state transition results are skipped when legacy step helpers have advanced the session.
• hermes-e2e (high): Required to exercise the non-OpenClaw agent_setup branch after sandbox creation; the changed compatibility logic has explicit branch behavior for agent setup sandboxes.

Optional E2E

• onboard-repair-e2e (high): Useful adjacent confidence for resume repair and conflict behavior because the runtime boundary emits skip diagnostics and resume conflict events, but the direct merge-blocking risk is better covered by onboard-resume-e2e.
• ubuntu-repo-cloud-openclaw-double-provider-switch (high): Useful scenario coverage for provider selection retryStateResults now consumed via recordStateResultsWithStepCompatibility, especially stale retry results followed by successful inference setup.
• double-onboard-e2e (very high): Adjacent lifecycle confidence for repeated onboarding and gateway/sandbox reuse after state result recording changes, but less targeted than resume coverage.

New E2E recommendations

• onboarding-state-machine-observability (medium): Existing resume E2E validates step statuses and completion, but does not appear to assert session.machine.state/revision or state.result.skipped event telemetry after legacy step/result compatibility skips.
  • Suggested test: Extend onboard-resume-e2e or add a focused E2E that inspects onboard-session machine state and emitted trace/events for already_at_target/source_state_mismatch compatibility skips.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: cloud-onboard-e2e,onboard-resume-e2e,hermes-e2e

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• ubuntu-repo-cloud-openclaw: Primary Ubuntu repo-current OpenClaw onboarding path. The PR changes core onboarding FSM/result recording and runtime-boundary compatibility used across preflight, gateway, provider/inference, sandbox, OpenClaw setup, policies, and finalization.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
• ubuntu-repo-cloud-hermes: Exercises the non-OpenClaw agent branch through agent_setup, which is directly relevant to the changed sandbox/agent state-result compatibility behavior.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes
• ubuntu-repo-cloud-openclaw-resume: Targets resume-after-interrupt onboarding, where stale/current FSM state compatibility and skipped state-result diagnostics are most likely to affect scenario behavior.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-resume
• ubuntu-repo-cloud-openclaw-double-provider-switch: Targets provider retry/switch lifecycle behavior, matching the PR's changes around recording retryStateResults and transition compatibility for provider/inference state results.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-double-provider-switch

Optional scenario E2E

• ubuntu-no-docker-preflight-negative: Optional negative coverage for preflight failure behavior, adjacent to the changed preflight state-result recording in src/lib/onboard.ts.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-no-docker-preflight-negative
• ubuntu-repo-cloud-openclaw-repair: Optional lifecycle-adjacent coverage for repair-existing-config flows that also use onboarding runtime diagnostics and state recording.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-repair
• wsl-repo-cloud-openclaw: Optional special-runner platform coverage for the same OpenClaw onboarding state flow under WSL.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=wsl-repo-cloud-openclaw
• gpu-repo-local-ollama-openclaw: Optional special-runner coverage for the local Ollama/GPU onboarding path; useful because core FSM/runtime-boundary changes are provider-agnostic, but the GPU runner is not the primary path.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=gpu-repo-local-ollama-openclaw
• macos-repo-cloud-openclaw: Optional special-runner platform coverage for repo-current onboarding on macOS; Docker-dependent suites are skipped on GitHub-hosted macOS.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=macos-repo-cloud-openclaw

Relevant changed files

• src/lib/onboard.ts
• src/lib/onboard/machine/runner.ts
• src/lib/onboard/machine/runtime.ts
• src/lib/onboard/machine/types.ts
• src/lib/onboard/runtime-boundary.ts

🛠️ Needs attention

• source_state_mismatch still skips transitions when the runtime is behind (src/lib/onboard/runtime-boundary.ts:134): The compatibility bridge skips any transition result whose metadata source state differs from the current machine state. That covers the documented legacy-step-helper case where the machine is already at or ahead of the result, but it also covers the opposite case where the runtime is behind the result source. In that case, the result may be evidence that the live sequence or legacy mutation missed a required transition, yet the bridge emits a skipped diagnostic and leaves the persisted machine state stale.
  • Recommendation: Only treat source mismatches as compatible no-ops when the current state is demonstrably already at the result target or otherwise known to be ahead due to legacy step-helper mutation. For behind or unknown mismatches, throw/fail loudly or add a separate, fully justified path with regression coverage proving why stale persisted state is safe.
  • Evidence: runtime-boundary.ts skips on `sourceState && current.machine.state !== sourceState`. runtime-boundary.test.ts:191-207 expects an initial `init` session receiving `advanceTo("gateway", { metadata: { state: "preflight" } })` to emit `state.result.skipped` and remain at `init`.
• runtime-boundary.test.ts grew into a larger monolith (src/lib/onboard/runtime-boundary.test.ts:1): The changed runtime-boundary test file grew from 115 to 402 lines, a +287 line increase in a hot onboarding FSM surface. The added scenarios are valuable, but keeping all harness logic and compatibility cases in one file makes future FSM migration review harder.
  • Recommendation: Extract shared runtime harness helpers or split compatibility scenarios into focused test modules so the new coverage does not create a larger monolith hotspot.
  • Evidence: Deterministic monolith analysis reported `src/lib/onboard/runtime-boundary.test.ts` baseLines=115, headLines=402, delta=287, severity=blocker.

🔎 Worth checking

• Source-of-truth review needed: src/lib/onboard/runtime-boundary.ts compatibility bridge for handler FSM results: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: The source-of-truth explanation is mostly present in `runtime-boundary.ts`, but the implementation and tests also treat a behind current state (`init`) with source `preflight` and target `gateway` as skippable. That case is broader than the documented legacy-advanced workaround.
• Tolerant FSM result skipping weakens security confidence in onboarding phase ordering (src/lib/onboard/runtime-boundary.ts:134): No direct sandbox escape, SSRF bypass, credential leak, policy bypass, blueprint tampering, installer-trust issue, or workflow trusted-code-boundary regression was found. However, onboarding host glue is security-sensitive, and the broad source-mismatch skip can conceal ordering defects around sandbox, policy, and finalization phases.
  • Recommendation: Constrain the compatibility bridge to known legacy-advanced states and add behavioral validation that sandbox/policy/finalization state remains aligned when handler FSM results are consumed.
  • Evidence: The new compatibility path emits `state.result.skipped` instead of enforcing the transition when `current.machine.state !== sourceState`; this is also covered by the behind-state test in runtime-boundary.test.ts.

🌱 Nice ideas

• None.

• **Runtime validation** — Runtime boundary rejects or loudly reports a transition result when current machine state is behind the result metadata source state. Unit coverage is strong for bridge mechanics and runner transition-limit behavior, but the changed live `onboard.ts` host glue depends on interactions among handler-returned results, legacy step-helper session mutation, and persisted machine snapshots in security-sensitive onboarding phases.
• **Runtime validation** — Live onboarding sequence keeps persisted `session.machine.state` aligned after each compatibility-consumed handler result. Unit coverage is strong for bridge mechanics and runner transition-limit behavior, but the changed live `onboard.ts` host glue depends on interactions among handler-returned results, legacy step-helper session mutation, and persisted machine snapshots in security-sensitive onboarding phases.
• **Runtime validation** — Provider retry compatibility records retry diagnostics without preventing the final inference-to-sandbox transition in the live host-glue sequence. Unit coverage is strong for bridge mechanics and runner transition-limit behavior, but the changed live `onboard.ts` host glue depends on interactions among handler-returned results, legacy step-helper session mutation, and persisted machine snapshots in security-sensitive onboarding phases.
• **Runtime validation** — Finalization completes from `post_verify` after `recordPostVerifyStarted()` when consumed through the compatibility alias. Unit coverage is strong for bridge mechanics and runner transition-limit behavior, but the changed live `onboard.ts` host glue depends on interactions among handler-returned results, legacy step-helper session mutation, and persisted machine snapshots in security-sensitive onboarding phases.
• **Runtime validation** — Skipped compatibility results never apply provider, model, credential, sandbox, or policy context updates. Unit coverage is strong for bridge mechanics and runner transition-limit behavior, but the changed live `onboard.ts` host glue depends on interactions among handler-returned results, legacy step-helper session mutation, and persisted machine snapshots in security-sensitive onboarding phases.
• **Acceptance clause:** `npx prek run --all-files` passes — add test evidence or identify existing coverage. Claim appears in the PR body, but this advisory review did not execute package-manager or test commands and does not report external CI status.
• **Acceptance clause:** `npm test` passes — add test evidence or identify existing coverage. Claim appears in the PR body, but this advisory review did not execute package-manager or test commands and does not report external CI status.
• **Acceptance clause:** Docs updated for user-facing behavior changes — add test evidence or identify existing coverage. No docs changed. The patch appears primarily internal to onboarding FSM/runtime diagnostics, though it does add a new machine event type.

Current findings:

• Source-of-truth review needed: src/lib/onboard/runtime-boundary.ts compatibility bridge for handler FSM results: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: The source-of-truth explanation is mostly present in `runtime-boundary.ts`, but the implementation and tests also treat a behind current state (`init`) with source `preflight` and target `gateway` as skippable. That case is broader than the documented legacy-advanced workaround.
• source_state_mismatch still skips transitions when the runtime is behind (src/lib/onboard/runtime-boundary.ts:134): The compatibility bridge skips any transition result whose metadata source state differs from the current machine state. That covers the documented legacy-step-helper case where the machine is already at or ahead of the result, but it also covers the opposite case where the runtime is behind the result source. In that case, the result may be evidence that the live sequence or legacy mutation missed a required transition, yet the bridge emits a skipped diagnostic and leaves the persisted machine state stale.
  • Recommendation: Only treat source mismatches as compatible no-ops when the current state is demonstrably already at the result target or otherwise known to be ahead due to legacy step-helper mutation. For behind or unknown mismatches, throw/fail loudly or add a separate, fully justified path with regression coverage proving why stale persisted state is safe.
  • Evidence: runtime-boundary.ts skips on `sourceState && current.machine.state !== sourceState`. runtime-boundary.test.ts:191-207 expects an initial `init` session receiving `advanceTo("gateway", { metadata: { state: "preflight" } })` to emit `state.result.skipped` and remain at `init`.
• Tolerant FSM result skipping weakens security confidence in onboarding phase ordering (src/lib/onboard/runtime-boundary.ts:134): No direct sandbox escape, SSRF bypass, credential leak, policy bypass, blueprint tampering, installer-trust issue, or workflow trusted-code-boundary regression was found. However, onboarding host glue is security-sensitive, and the broad source-mismatch skip can conceal ordering defects around sandbox, policy, and finalization phases.
  • Recommendation: Constrain the compatibility bridge to known legacy-advanced states and add behavioral validation that sandbox/policy/finalization state remains aligned when handler FSM results are consumed.
  • Evidence: The new compatibility path emits `state.result.skipped` instead of enforcing the transition when `current.machine.state !== sourceState`; this is also covered by the behind-state test in runtime-boundary.test.ts.
• runtime-boundary.test.ts grew into a larger monolith (src/lib/onboard/runtime-boundary.test.ts:1): The changed runtime-boundary test file grew from 115 to 402 lines, a +287 line increase in a hot onboarding FSM surface. The added scenarios are valuable, but keeping all harness logic and compatibility cases in one file makes future FSM migration review harder.
  • Recommendation: Extract shared runtime harness helpers or split compatibility scenarios into focused test modules so the new coverage does not create a larger monolith hotspot.
  • Evidence: Deterministic monolith analysis reported `src/lib/onboard/runtime-boundary.test.ts` baseLines=115, headLines=402, delta=287, severity=blocker.