E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• onboard-resume-e2e (high; real Docker/OpenShell sandbox and NVIDIA_API_KEY required): Most directly covers the changed session and machine snapshot behavior: it forces an interrupted onboard run, verifies persisted failure/step state, then resumes and validates completion.
• cloud-onboard-e2e (high; public install path, real Docker/OpenShell sandbox, NVIDIA_API_KEY, and cloud inference required): Validates the primary real user install/onboard happy path after changes to onboard runtime/session step recording and machine state persistence.

Optional E2E

• onboard-negative-paths-e2e (high; real Docker/OpenShell sandbox and NVIDIA_API_KEY required): Useful adjacent coverage for failure and edge-case onboarding behavior, including friendly validation failures and gateway-port conflict handling, but the PR already has direct unit coverage for record-only failure mutation.
• double-onboard-e2e (very high; multiple sequential sandbox creations): Optional confidence that repeated onboarding and sandbox lifecycle recovery still work with the changed session step/machine transition plumbing.

New E2E recommendations

• onboarding-runtime-state-machine (medium): Existing E2E coverage validates default legacy step mutation and resume behavior, but does not directly assert a live record-only step path where step status is recorded while the FSM result is the only machine snapshot writer.
  • Suggested test: Add an onboarding state-machine E2E that runs a controlled onboard flow with record-only step mutation enabled and asserts machine revision/state advance only from FSM transition results while step statuses and context updates persist.

Dispatch hint

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

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• ubuntu-repo-cloud-openclaw: Core onboarding runtime/session mutation code changed. The baseline Ubuntu repo OpenClaw scenario exercises the live non-interactive onboarding path, step start/complete/failure defaults, session persistence, expected onboarding state, and post-onboarding smoke/credential checks on the standard runner.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional scenario E2E

• ubuntu-repo-cloud-openclaw-resume: Optional adjacent lifecycle coverage for session/machine snapshot persistence across interrupted/resumed onboarding, which is related to the changed onboard session and runtime-boundary code but not the primary default onboarding path.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-resume
• ubuntu-repo-cloud-hermes: Optional alternate-agent coverage to confirm the same onboarding runtime/session changes do not regress the Hermes path.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes

Relevant changed files

• src/lib/onboard/machine/runtime.ts
• src/lib/onboard/runtime-boundary.ts
• src/lib/state/onboard-session.ts

🛠️ Needs attention

• Offset large test-file growth: This PR adds another 20+ lines to two existing large test files. The changed tests are useful, but the repository drift signal marks these as current large-file hotspots where new coverage should be extracted or offset rather than growing the monolith further.
  • Recommendation: Move the new cases into focused test modules or extract shared harness helpers so `src/lib/onboard/runtime-boundary.test.ts` and `src/lib/state/onboard-session.test.ts` do not continue to grow as hotspots.
  • Evidence: Deterministic monolith deltas: `src/lib/onboard/runtime-boundary.test.ts` grew from 404 to 434 lines (+30); `src/lib/state/onboard-session.test.ts` grew from 1171 to 1197 lines (+26).

🔎 Worth checking

• Source-of-truth review needed: Step mutation options exposed through `OnboardRuntimeBoundaryOptions.stepMutationOptions`: 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: `src/lib/state/onboard-step-mutation.ts` labels `updateMachine` as a transitional escape hatch; this PR adds `stepMutationOptions?: StepMutationOptions` to `OnboardRuntimeBoundaryOptions` and forwards it to generic step recorders.
• Record-only boundary option needs explicit source-of-truth guardrails (src/lib/onboard/runtime-boundary.ts:26): `OnboardRuntimeBoundaryOptions.stepMutationOptions` exposes the transitional `{ updateMachine:false }` escape hatch through the generic boundary recorders. If a future caller configures this option and then uses `startRecordedStep`, `recordStepComplete`, or `recordStepFailed` without an explicit FSM result, the step status can diverge from the durable machine/status/failure source of truth. Current production construction does not pass the option, so this is a guardrail/future-footgun concern rather than an active production bypass.
  • Recommendation: Document this option directly on `OnboardRuntimeBoundaryOptions` and/or constrain its use to paired state-result adapters so record-only writes are always followed by an explicit `OnboardStateResult`. Add a boundary contract test that demonstrates the required pairing.
  • Evidence: `runtime-boundary.ts` adds `stepMutationOptions?: StepMutationOptions` and forwards it to `runtime.markStepStarted`, `runtime.markStepComplete`, and `runtime.markStepFailed`; `onboard-session.ts` suppresses machine/status/failure mutation when `shouldUpdateMachine(options)` is false.

🌱 Nice ideas

• None.

• **Mocked behavioral coverage** — Boundary configured with `{ updateMachine:false }` leaves `session.machine` unchanged after `recordStepComplete` until `recordStateResult` applies the explicit transition.. The changed surfaces mutate persisted onboarding session state and runtime FSM behavior. Existing mocked runtime/boundary harnesses and temp-session tests cover the main forwarding/default behavior, but the newly exposed boundary-level escape hatch would benefit from explicit contract tests around source-of-truth pairing.
• **Mocked behavioral coverage** — Boundary configured with `{ updateMachine:false }` does not mark the session failed after `recordStepFailed` until `recordStepFailedWithStateResult` or an explicit failure result applies.. The changed surfaces mutate persisted onboarding session state and runtime FSM behavior. Existing mocked runtime/boundary harnesses and temp-session tests cover the main forwarding/default behavior, but the newly exposed boundary-level escape hatch would benefit from explicit contract tests around source-of-truth pairing.
• **Mocked behavioral coverage** — Production/default `OnboardRuntimeBoundary` behavior preserves legacy machine advancement when no `stepMutationOptions` are provided.. The changed surfaces mutate persisted onboarding session state and runtime FSM behavior. Existing mocked runtime/boundary harnesses and temp-session tests cover the main forwarding/default behavior, but the newly exposed boundary-level escape hatch would benefit from explicit contract tests around source-of-truth pairing.
• **Offset large test-file growth** — Move the new cases into focused test modules or extract shared harness helpers so `src/lib/onboard/runtime-boundary.test.ts` and `src/lib/state/onboard-session.test.ts` do not continue to grow as hotspots.
• **Step mutation options exposed through `OnboardRuntimeBoundaryOptions.stepMutationOptions`** — Existing tests cover option forwarding, session-level no-machine-mutation behavior, and paired record-only step/result adapters. Missing follow-up: a boundary contract test that a configured record-only generic recorder must be paired with an explicit state result before the machine source of truth advances.. `src/lib/state/onboard-step-mutation.ts` labels `updateMachine` as a transitional escape hatch; this PR adds `stepMutationOptions?: StepMutationOptions` to `OnboardRuntimeBoundaryOptions` and forwards it to generic step recorders.

Current findings:

• Source-of-truth review needed: Step mutation options exposed through `OnboardRuntimeBoundaryOptions.stepMutationOptions`: 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: `src/lib/state/onboard-step-mutation.ts` labels `updateMachine` as a transitional escape hatch; this PR adds `stepMutationOptions?: StepMutationOptions` to `OnboardRuntimeBoundaryOptions` and forwards it to generic step recorders.
• Offset large test-file growth: This PR adds another 20+ lines to two existing large test files. The changed tests are useful, but the repository drift signal marks these as current large-file hotspots where new coverage should be extracted or offset rather than growing the monolith further.
  • Recommendation: Move the new cases into focused test modules or extract shared harness helpers so `src/lib/onboard/runtime-boundary.test.ts` and `src/lib/state/onboard-session.test.ts` do not continue to grow as hotspots.
  • Evidence: Deterministic monolith deltas: `src/lib/onboard/runtime-boundary.test.ts` grew from 404 to 434 lines (+30); `src/lib/state/onboard-session.test.ts` grew from 1171 to 1197 lines (+26).
• Record-only boundary option needs explicit source-of-truth guardrails (src/lib/onboard/runtime-boundary.ts:26): `OnboardRuntimeBoundaryOptions.stepMutationOptions` exposes the transitional `{ updateMachine:false }` escape hatch through the generic boundary recorders. If a future caller configures this option and then uses `startRecordedStep`, `recordStepComplete`, or `recordStepFailed` without an explicit FSM result, the step status can diverge from the durable machine/status/failure source of truth. Current production construction does not pass the option, so this is a guardrail/future-footgun concern rather than an active production bypass.
  • Recommendation: Document this option directly on `OnboardRuntimeBoundaryOptions` and/or constrain its use to paired state-result adapters so record-only writes are always followed by an explicit `OnboardStateResult`. Add a boundary contract test that demonstrates the required pairing.
  • Evidence: `runtime-boundary.ts` adds `stepMutationOptions?: StepMutationOptions` and forwards it to `runtime.markStepStarted`, `runtime.markStepComplete`, and `runtime.markStepFailed`; `onboard-session.ts` suppresses machine/status/failure mutation when `shouldUpdateMachine(options)` is false.