Track onboard FSM migration stack and resume compatibility

[cv]

Summary

This issue tracks the stacked onboarding finite-state-machine (FSM) migration work and explains the current intended end-state for reviewers and maintainers.

The stack moves onboarding from a large manual sequence in src/lib/onboard.ts toward explicit FSM state results, a strict runtime/runner, and phase slices. Fresh onboarding is now being migrated onto FSM slices. Resume/ahead-state flows intentionally remain compatibility-driven for now so historical repair and backstop checks still execute even when the saved machine state is already ahead.

Stack overview

1. FSM target, metadata, and mappings

• docs(onboard): document FSM migration target #4361 — docs(onboard): document FSM migration target
• refactor(onboard): centralize machine state metadata #4362 — refactor(onboard): centralize machine state metadata
• refactor(onboard): derive session step mapping from FSM metadata #4363 — refactor(onboard): derive session step mapping from FSM metadata
• refactor(onboard): derive progress labels from FSM metadata #4364 — refactor(onboard): derive progress labels from FSM metadata

2. Runtime lifecycle/events/result primitives

• fix(onboard): emit lifecycle events for onboarding start #4373 — fix(onboard): emit lifecycle events for onboarding start
• fix(onboard): emit machine events for resume conflicts #4374 — fix(onboard): emit machine events for resume conflicts
• refactor(onboard): introduce explicit state result types #4375 — refactor(onboard): introduce explicit state result types
• refactor(onboard): apply explicit state results through runtime #4376 — refactor(onboard): apply explicit state results through runtime

3. Existing handlers return FSM results

• refactor(onboard): make finalization return FSM result #4443 — refactor(onboard): make finalization return FSM result
• refactor(onboard): make agent setup return FSM result #4444 — refactor(onboard): make agent setup return FSM result
• refactor(onboard): make policy setup return FSM result #4445 — refactor(onboard): make policy setup return FSM result
• refactor(onboard): make preflight and gateway return FSM results #4446 — refactor(onboard): make preflight and gateway return FSM results
• refactor(onboard): make sandbox return branch FSM result #4447 — refactor(onboard): make sandbox return branch FSM result
• refactor(onboard): return FSM results from provider inference #4452 — refactor(onboard): return FSM results from provider inference

4. Runner, record-only steps, and compatibility bridge

• refactor(onboard): add FSM runner shell #4453 — refactor(onboard): add FSM runner shell
• refactor(onboard): consume handler FSM results compatibly #4454 — refactor(onboard): consume handler FSM results compatibly
• refactor(onboard): allow step recording without machine transitions #4457 — refactor(onboard): allow step recording without machine transitions
• refactor(onboard): plumb step mutation options through runtime #4458 — refactor(onboard): plumb step mutation options through runtime
• refactor(onboard): add record-only FSM runner adapter #4461 — refactor(onboard): add record-only FSM runner adapter

5. Ordered results and sequence adapter

• refactor(onboard): return ordered provider FSM results #4471 — refactor(onboard): return ordered provider FSM results
• refactor(onboard): run live sequence with record-only steps #4472 — refactor(onboard): run live sequence with record-only steps
• refactor(onboard): let FSM handlers return result sequences #4473 — refactor(onboard): let FSM handlers return result sequences
• refactor(onboard): add sequence runner adapter #4475 — refactor(onboard): add sequence runner adapter

6. Flow context, phase adapters, and slice helpers

• refactor(onboard): support FSM runner stop states #4480 — refactor(onboard): support FSM runner stop states
• refactor(onboard): define FSM flow context #4481 — refactor(onboard): define FSM flow context
• refactor(onboard): extract preflight and gateway FSM phases #4482 — refactor(onboard): extract preflight and gateway FSM phases
• refactor(onboard): extract provider and sandbox FSM phases #4483 — refactor(onboard): extract provider and sandbox FSM phases
• refactor(onboard): extract agent policy finalization FSM phases #4484 — refactor(onboard): extract agent policy finalization FSM phases
• refactor(onboard): assemble FSM phase sequence #4485 — refactor(onboard): assemble FSM phase sequence
• refactor(onboard): add initial FSM flow slice #4486 — refactor(onboard): add initial FSM flow slice
• refactor(onboard): add core FSM flow slice #4487 — refactor(onboard): add core FSM flow slice
• refactor(onboard): add final FSM flow slice #4488 — refactor(onboard): add final FSM flow slice

7. Live fresh-flow migration and boundary tests

• refactor(onboard): run initial phases through FSM slice #4499 — refactor(onboard): run initial phases through FSM slice
• refactor(onboard): run core phases through FSM slice #4500 — refactor(onboard): run core phases through FSM slice
• refactor(onboard): run final phases through FSM slice #4507 — refactor(onboard): run final phases through FSM slice
• refactor(onboard): extract live FSM slice runner helper #4530 — refactor(onboard): extract live FSM slice runner helper
• test(onboard): cover live FSM slice boundaries #4531 — test(onboard): cover live FSM slice boundaries

Current behavior after the stack

Fresh onboarding is migrated to FSM slices:

1. Initial slice: preflight/gateway → stops at provider_selection
2. Core slice: provider/inference + sandbox → stops at openclaw or agent_setup
3. Final slice: branch setup + policies + finalization → completion

Step helpers can now record status without mutating the durable machine state. Fresh flows use record-only step mutation so OnboardRuntime owns machine transitions.

Resume compatibility is intentional

Resume/ahead-state flows still use the compatibility execution path. This is intentional because many historical fixes are repair/backstop checks inside phase bodies. Those checks must still run even if a saved session has already advanced beyond the phase's nominal FSM state.

Examples of this pattern include preflight/gateway backstops, provider repair, sandbox reuse/repair decisions, policy reconciliation, and final verification/recovery checks.

A future project can model resume repairs as first-class FSM behavior, but this stack keeps resume conservative to avoid regressions.

Suggested review order

1. Review and merge the foundation PRs first (docs(onboard): document FSM migration target #4361 onward).
2. Keep later PRs draft until their bases are merged/restacked.
3. Review handler-result PRs independently; most are small behavior-preserving changes.
4. Review live-slice PRs (refactor(onboard): run initial phases through FSM slice #4499, refactor(onboard): run core phases through FSM slice #4500, refactor(onboard): run final phases through FSM slice #4507, refactor(onboard): extract live FSM slice runner helper #4530, test(onboard): cover live FSM slice boundaries #4531) more carefully because they affect the live onboard.ts execution path for fresh runs.

Follow-up work after this stack

• Move large inline live phase wiring out of src/lib/onboard.ts into a dedicated module.
• Clarify/rename the resume compatibility result application helper.
• Audit high-level smoke coverage for fresh, retry, branch, and resume paths after the stack lands.
• Decide later whether resume repair/backstop behavior should become explicit FSM policy.

[Iamkewl]

Might be outside the scope of this, wondering if I should open a seperate issue with the same, found post revieiwng the PRs:

Summary

OnboardRuntimeBoundary.recordStateResultWithStepCompatibility (runtime-boundary.ts:95–107) silently discards transition results in two cases:

1. Idempotency guard (line 100) — machine is already at the target state → return current
2. Provenance guard (line 104) — result's source state doesn't match current machine state → return current

Neither case emits an event, log, or trace. When debugging resume flows, there's no way to tell if a result was applied, discarded by idempotency, or discarded by provenance mismatch without stepping through with a debugger.

Proposal

Introduce a new type-safe event "state.result.skipped" to the FSM runtime and emit it when a result is skipped during transition recording.

1. Add "state.result.skipped" to ONBOARD_MACHINE_EVENT_TYPES in src/lib/onboard/machine/types.ts:

export const ONBOARD_MACHINE_EVENT_TYPES = [
  ...
  "state.repair.started",
  "state.repair.completed",
  "state.repair.failed",
  "state.result.skipped", // Add here
  "context.updated",
  ...
] as const;

2. Define emitResultSkipped on OnboardRuntime in src/lib/onboard/machine/runtime.ts:

  async emitResultSkipped(options: {
    reason: "already_at_target" | "source_state_mismatch";
    currentState: OnboardMachineState;
    targetState: OnboardMachineState;
    metadata?: Record<string, unknown> | null;
  }): Promise<Session> {
    const session = this.ensureSession();
    this.emit("state.result.skipped", session, {
      state: session.machine.state,
      metadata: {
        ...eventMetadata(options.metadata),
        reason: options.reason,
        currentState: options.currentState,
        targetState: options.targetState,
      },
    });
    return session;
  }

3. Update recordStateResultWithStepCompatibility in src/lib/onboard/runtime-boundary.ts to emit the events:

  async recordStateResultWithStepCompatibility(result: OnboardStateResult): Promise<Session> {
    const runtime = this.getRuntime();
    const current = await runtime.session();
    if (result.type !== "transition") return runtime.applyResult(result);

    if (current.machine.state === result.next) {
      await runtime.emitResultSkipped({
        reason: "already_at_target",
        currentState: current.machine.state,
        targetState: result.next,
      });
      return current;
    }

    const sourceState =
      result.metadata && typeof result.metadata.state === "string" ? result.metadata.state : null;
    if (sourceState && current.machine.state !== sourceState) {
      await runtime.emitResultSkipped({
        reason: "source_state_mismatch",
        currentState: current.machine.state,
        targetState: result.next,
        metadata: { sourceState },
      });
      return current;
    }

    return runtime.applyResult(result);
  }

[wscurran]

✨
Related open PRs:

• #4458 refactor(onboard): plumb step mutation options through runtime
• #4457 refactor(onboard): allow step recording without machine transitions
• #4454 refactor(onboard): consume handler FSM results compatibly