refactor(onboard): make runtime the machine authority

src/lib/onboard/machine/README.md

@@ -41,15 +41,12 @@ A state handler may perform many smaller operations, but it should expose only s
 
 ## Session steps versus machine state
 
-The persisted onboarding session still tracks step-level progress for resumability. Step recording is older than the FSM and is currently used as a compatibility bridge.
+The persisted onboarding session tracks step-level progress for resumability.
 
-Long term:
-
-- `OnboardRuntime` should own machine transitions and machine revision increments.
-- Session step helpers should record only step status (`pending`, `in_progress`, `complete`, `failed`, `skipped`).
-- State handlers should return explicit results instead of implicitly moving the machine by calling step helpers.
-
-Until that migration completes, step helpers may still infer machine snapshots for compatibility with older sessions and tests.
+- `OnboardRuntime` owns normal machine transitions, revision increments, terminal state, and machine events.
+- Session step helpers record only step status (`pending`, `in_progress`, `complete`, `failed`, `skipped`) and safe step updates. They cannot change the machine snapshot.
+- State handlers return explicit results. They do not move the machine through step helpers.
+- Explicit session recovery and the process-exit failure backstop are narrow exceptions.
 
 ## Handler contract
 
@@ -87,15 +84,15 @@ without a state transition so a later process can resume the same non-terminal s
 
 ## Runtime responsibilities
 
-`OnboardRuntime` is the intended authority for:
+`OnboardRuntime` is the authority for:
 
-- validating transitions against `transitions.ts`;
+- validating result source, target, kind, and graph transitions;
 - applying safe session context updates;
 - marking terminal states;
 - emitting redacted lifecycle, state, repair, resume-conflict, and hook events;
 - normalizing older sessions before strict execution.
 
-The runtime should reject invalid transitions before they can be persisted.
+Step helpers record step status and safe step updates. They cannot change the machine snapshot or emit machine events. Explicit session recovery and the process-exit failure backstop are separate recovery boundaries. They validate their snapshot changes and run before or outside handler execution.
 
 ## Event semantics
 

src/lib/onboard/machine/core-flow-phases.test.ts

@@ -46,6 +46,7 @@ function context(
     hermesToolGateways: [],
     preferredInferenceApi: null,
     compatibleEndpointReasoning: null,
+
     compatibleEndpointReasoningEffort: null,
     nimContainer: null,
     webSearchConfig: null,
@@ -136,6 +137,7 @@ function createPhases(
         hermesToolGateways: ["local"],
         preferredInferenceApi: "chat",
         compatibleEndpointReasoning: null,
+
         compatibleEndpointReasoningEffort: null,
         nimContainer: "nim-test",
       })),
@@ -161,8 +163,10 @@ function createPhases(
       recordRepairEvent: vi.fn(async () => createSession()),
       hydrateCredentialEnv: vi.fn(),
       configureCompatibleEndpointReasoning: vi.fn(async () => "false" as const),
-      clearCompatibleEndpointReasoning: vi.fn(() => null),
+
       configureCompatibleEndpointReasoningEffort: vi.fn(async () => null),
+      clearCompatibleEndpointReasoning: vi.fn(() => null),
+
       clearCompatibleEndpointReasoningEffort: vi.fn(() => null),
       repairLocalInferenceSystemdOverrideOrExit: vi.fn(),
       isNonInteractive: () => true,
@@ -204,11 +208,8 @@ function createPhases(
       resolvePath: (value) => value,
       agentSupportsWebSearch: () => true,
       note: vi.fn(),
+
       cliName: () => "nemoclaw",
-      retireReplacedSandboxWorkload: vi.fn(() => ({
-        status: "skipped" as const,
-        reason: "replacement-unproven" as const,
-      })),
       updateSession: vi.fn((mutator) => mutator(createSession()) ?? createSession()),
       getStoredMessagingChannelConfig: () => null,
       hydrateMessagingChannelConfig: (config) => config,
@@ -371,6 +372,7 @@ describe("core onboard flow phases", () => {
       hermesToolGateways: [],
       preferredInferenceApi: "chat",
       compatibleEndpointReasoning: null,
+
       compatibleEndpointReasoningEffort: null,
       nimContainer: null,
     }));
@@ -860,7 +862,7 @@ describe("core onboard flow phases", () => {
         resume: true,
         recordRepairEvent: repairRecorder(),
       }),
-    ).rejects.toThrow("Unexpected onboarding live flow state before slice entry");
+    ).rejects.toThrow("Unexpected onboarding flow state before slice entry");
     expect(providerInference.run).not.toHaveBeenCalled();
     expect(sandbox.run).not.toHaveBeenCalled();
   });

src/lib/onboard/machine/core-flow-phases.ts

@@ -23,7 +23,7 @@ import {
   type ProviderInferenceStateOptions,
 } from "./handlers/provider-inference";
 import { handleSandboxState, type SandboxStateOptions } from "./handlers/sandbox";
-import { UnexpectedLiveOnboardFlowSliceStateError } from "./live-flow-slice";
+import { UnexpectedOnboardFlowSliceStateError } from "./flow-slice-error";
 import {
   type OnboardPrerequisiteRepairEventRecorder,
   runOnboardPrerequisiteRepair,
@@ -67,6 +67,7 @@ export interface SandboxOnboardFlowPhaseOptions<
   gatewayName: string;
   authoritativeResumeConfig?: boolean;
   authoritativePolicyTier?: string | null;
+
   recreateJournalTargetIntentFingerprint?: string | null;
   resumeAgentChanged: boolean;
   requestedObservabilityEnabled?: boolean | null;
@@ -159,6 +160,7 @@ export function createProviderInferenceOnboardFlowPhase<
         hermesToolGateways: context.hermesToolGateways,
         preferredInferenceApi: context.preferredInferenceApi,
         compatibleEndpointReasoning: context.compatibleEndpointReasoning,
+
         compatibleEndpointReasoningEffort: context.compatibleEndpointReasoningEffort,
         nimContainer: context.nimContainer,
         webSearchConfig: context.webSearchConfig,
@@ -183,6 +185,7 @@ export function createProviderInferenceOnboardFlowPhase<
         hermesToolGateways: providerInferenceResult.hermesToolGateways,
         preferredInferenceApi: providerInferenceResult.preferredInferenceApi,
         compatibleEndpointReasoning: providerInferenceResult.compatibleEndpointReasoning,
+
         compatibleEndpointReasoningEffort:
           providerInferenceResult.compatibleEndpointReasoningEffort,
         nimContainer: providerInferenceResult.nimContainer,
@@ -214,6 +217,7 @@ export function createSandboxOnboardFlowPhase<
       gatewayName: options.gatewayName,
       authoritativeResumeConfig: options.authoritativeResumeConfig,
       authoritativePolicyTier: options.authoritativePolicyTier,
+
       recreateJournalTargetIntentFingerprint: options.recreateJournalTargetIntentFingerprint,
       endpointSource: endpointProvenance.endpointSource,
       resumeAgentChanged: options.resumeAgentChanged,
@@ -279,7 +283,7 @@ export async function runCoreOnboardFlowSlice<Context extends OnboardFlowContext
       ]
     : ["provider_selection", "inference", "sandbox", "openclaw", "agent_setup"];
   if (!allowedStates.includes(state)) {
-    throw new UnexpectedLiveOnboardFlowSliceStateError(
+    throw new UnexpectedOnboardFlowSliceStateError(
       state,
       ["provider_selection", "inference", "sandbox"],
       allowedStates.filter(

src/lib/onboard/machine/final-flow-phases.runtime.test.ts

@@ -11,7 +11,7 @@ import {
 import { createSession } from "../../state/onboard-session";
 import type { VerifyDeploymentResult } from "../../verify-deployment";
 import { runFinalOnboardFlowSlice } from "./final-flow-phases";
-import { UnexpectedLiveOnboardFlowSliceStateError } from "./live-flow-slice";
+import { UnexpectedOnboardFlowSliceStateError } from "./flow-slice-error";
 
 function deploymentResult(healthy: boolean): VerifyDeploymentResult {
   return {
@@ -186,7 +186,7 @@ describe("final onboard flow runtime boundary", () => {
         phases: createPhases(branchState, order),
         recordRepairEvent,
       }),
-    ).rejects.toBeInstanceOf(UnexpectedLiveOnboardFlowSliceStateError);
+    ).rejects.toBeInstanceOf(UnexpectedOnboardFlowSliceStateError);
 
     expect(order).toEqual([]);
     expect(recordRepairEvent).not.toHaveBeenCalled();

src/lib/onboard/machine/final-flow-phases.ts

@@ -18,7 +18,7 @@ import {
   handlePostVerifyState,
 } from "./handlers/finalization";
 import { handlePoliciesState, type PoliciesStateOptions } from "./handlers/policies";
-import { UnexpectedLiveOnboardFlowSliceStateError } from "./live-flow-slice";
+import { UnexpectedOnboardFlowSliceStateError } from "./flow-slice-error";
 import { createPhaseProgressReporter } from "./phase-progress";
 import type { OnboardStateResult } from "./result";
 import type { OnboardMachineRunnerRuntime, OnboardStateHandlerResult } from "./runner";
@@ -336,7 +336,7 @@ export async function runFinalOnboardFlowSlice<Context extends OnboardFlowContex
   const durableEntry = await options.runtime.session();
   const allowedStates = [branchState, ...FINAL_FLOW_DOWNSTREAM_STATES] as const;
   if (!allowedStates.includes(durableEntry.machine.state as (typeof allowedStates)[number])) {
-    throw new UnexpectedLiveOnboardFlowSliceStateError(
+    throw new UnexpectedOnboardFlowSliceStateError(
       durableEntry.machine.state,
       [branchState],
       FINAL_FLOW_DOWNSTREAM_STATES,

src/lib/onboard/machine/flow-slice-error.ts

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { OnboardMachineState } from "./types";
+
+export class UnexpectedOnboardFlowSliceStateError extends Error {
+  constructor(
+    readonly state: OnboardMachineState,
+    readonly runStates: readonly OnboardMachineState[],
+    readonly repairStates: readonly OnboardMachineState[],
+  ) {
+    super(`Unexpected onboarding flow state before slice entry: ${state}`);
+    this.name = "UnexpectedOnboardFlowSliceStateError";
+  }
+}

src/lib/onboard/machine/initial-flow-phases.test.ts

@@ -43,6 +43,7 @@ function context(overrides: Partial<Context> = {}): Context {
     hermesToolGateways: [],
     preferredInferenceApi: null,
     compatibleEndpointReasoning: null,
+
     compatibleEndpointReasoningEffort: null,
     nimContainer: null,
     webSearchConfig: null,
@@ -593,7 +594,7 @@ describe("initial onboard flow phases", () => {
         resume: true,
         recordRepairEvent: repairRecorder(),
       }),
-    ).rejects.toThrow("Unexpected onboarding live flow state before slice entry");
+    ).rejects.toThrow("Unexpected onboarding flow state before slice entry");
     expect(phase.run).not.toHaveBeenCalled();
   });
 

src/lib/onboard/machine/initial-flow-phases.ts

@@ -13,7 +13,7 @@ import {
   type PreflightSandboxGpuFlag,
   type PreflightStateOptions,
 } from "./handlers/preflight";
-import { UnexpectedLiveOnboardFlowSliceStateError } from "./live-flow-slice";
+import { UnexpectedOnboardFlowSliceStateError } from "./flow-slice-error";
 import {
   type OnboardPrerequisiteRepairEventRecorder,
   runOnboardPrerequisiteRepair,
@@ -211,7 +211,7 @@ export async function runInitialOnboardFlowSlice<Context extends OnboardFlowCont
     ? ["init", "preflight", ...resumeAheadStates]
     : ["init", "preflight", "gateway", "provider_selection"];
   if (!allowedStates.includes(state)) {
-    throw new UnexpectedLiveOnboardFlowSliceStateError(
+    throw new UnexpectedOnboardFlowSliceStateError(
       state,
       ["init", "preflight"],
       allowedStates.filter((candidate) => candidate !== "init" && candidate !== "preflight"),