refactor(onboard): make finalization return FSM result

src/lib/onboard.ts

@@ -6294,8 +6294,8 @@ const recordStepSkipped = onboardRuntimeBoundary.recordStepSkipped.bind(onboardR
 const recordStepFailed = onboardRuntimeBoundary.recordStepFailed.bind(onboardRuntimeBoundary);
 const recordStateSkipped = onboardRuntimeBoundary.recordStateSkipped.bind(onboardRuntimeBoundary);
 const recordRepairEvent = onboardRuntimeBoundary.recordRepairEvent.bind(onboardRuntimeBoundary);
+const recordStateResult = onboardRuntimeBoundary.recordStateResult.bind(onboardRuntimeBoundary);
 const recordPostVerifyStarted = onboardRuntimeBoundary.recordPostVerifyStarted.bind(onboardRuntimeBoundary);
-const recordSessionComplete = onboardRuntimeBoundary.recordSessionComplete.bind(onboardRuntimeBoundary);
 
 function skippedStepMessage(
   stepName: string,
@@ -7004,7 +7004,7 @@ async function onboard(opts: OnboardOptions = {}): Promise<void> {
     session = policiesResult.session;
     sandboxCancelRollback.disarm(); // #4614: policies confirmed, past the cancellable window
 
-    await handleFinalizationState({
+    const finalizationResult = await handleFinalizationState({
       sandboxName,
       model,
       provider,
@@ -7020,7 +7020,6 @@ async function onboard(opts: OnboardOptions = {}): Promise<void> {
         setDefaultSandbox: registry.setDefault,
         verifyWebSearchInsideSandbox,
         recordPostVerifyStarted,
-        recordSessionComplete,
         toSessionUpdates: (updates) => toSessionUpdates(updates as Parameters<typeof toSessionUpdates>[0]),
         removeLegacyCredentialsFile,
         cleanupStaleHostFiles,
@@ -7058,6 +7057,7 @@ async function onboard(opts: OnboardOptions = {}): Promise<void> {
         log: (message) => console.log(message),
       },
     });
+    await recordStateResult(finalizationResult.stateResult);
     traceCompleted = true;
   } finally {
     releaseOnboardLock();

src/lib/onboard/machine/handlers/finalization.test.ts

@@ -15,7 +15,6 @@ function createDeps(overrides: Partial<FinalizationStateOptions<Agent, VerifyCha
     setDefaultSandbox: vi.fn(),
     ensureAgentDashboard: vi.fn(() => 18789),
     postVerify: vi.fn(async () => createSession({ machine: { version: 1, state: "post_verify", stateEnteredAt: null, revision: 1 } })),
-    complete: vi.fn(async () => createSession({ status: "complete" })),
     removeLegacy: vi.fn(),
     cleanupHost: vi.fn(),
     recoverProcesses: vi.fn(),
@@ -34,7 +33,6 @@ function createDeps(overrides: Partial<FinalizationStateOptions<Agent, VerifyCha
       ensureAgentDashboardForward: calls.ensureAgentDashboard,
       setDefaultSandbox: calls.setDefaultSandbox,
       recordPostVerifyStarted: calls.postVerify,
-      recordSessionComplete: calls.complete,
       toSessionUpdates: (updates: Record<string, unknown>) => updates as SessionUpdates,
       removeLegacyCredentialsFile: calls.removeLegacy,
       cleanupStaleHostFiles: calls.cleanupHost,
@@ -76,10 +74,10 @@ describe("handleFinalizationState", () => {
 
     const result = await handleFinalizationState(baseOptions(deps));
 
-    // Default is set at finalization (deferred from sandbox creation, #4614), before completion.
+    // Default is set at finalization (deferred from sandbox creation, #4614), before post-verify starts.
     expect(calls.setDefaultSandbox).toHaveBeenCalledWith("my-assistant");
     expect(calls.setDefaultSandbox.mock.invocationCallOrder[0]).toBeLessThan(
-      calls.complete.mock.invocationCallOrder[0],
+      calls.postVerify.mock.invocationCallOrder[0],
     );
     expect(calls.cleanupHost).toHaveBeenCalledOnce();
     expect(calls.recoverProcesses).toHaveBeenCalledWith("my-assistant", { quiet: true });
@@ -88,12 +86,16 @@ describe("handleFinalizationState", () => {
     expect(calls.log).toHaveBeenCalledWith("  ✓ verified");
     expect(calls.dashboard).toHaveBeenCalledWith("my-assistant", "model", "provider", null, null);
     expect(calls.postVerify).toHaveBeenCalledOnce();
-    expect(calls.complete).toHaveBeenCalledWith({
-      sandboxName: "my-assistant",
-      provider: "provider",
-      model: "model",
-      hermesAuthMethod: null,
-      hermesToolGateways: [],
+    expect(result.stateResult).toEqual({
+      type: "complete",
+      updates: {
+        sandboxName: "my-assistant",
+        provider: "provider",
+        model: "model",
+        hermesAuthMethod: null,
+        hermesToolGateways: [],
+      },
+      metadata: { state: "finalizing" },
     });
     expect(result.verificationDiagnostics).toEqual(["  ✓ verified"]);
   });
@@ -105,9 +107,8 @@ describe("handleFinalizationState", () => {
     await handleFinalizationState({ ...baseOptions(deps), agent });
 
     expect(calls.ensureAgentDashboard).toHaveBeenCalledWith("my-assistant", agent);
-    expect(calls.complete).toHaveBeenCalled();
     expect(calls.ensureAgentDashboard.mock.invocationCallOrder[0]).toBeLessThan(
-      calls.complete.mock.invocationCallOrder[0],
+      calls.dashboard.mock.invocationCallOrder[0],
     );
     expect(calls.dashboard).toHaveBeenCalledWith("my-assistant", "model", "provider", null, agent);
   });
@@ -122,7 +123,6 @@ describe("handleFinalizationState", () => {
     await expect(handleFinalizationState(baseOptions(deps))).rejects.toThrow("verification failed");
 
     expect(calls.postVerify).toHaveBeenCalledOnce();
-    expect(calls.complete).not.toHaveBeenCalled();
     expect(calls.dashboard).not.toHaveBeenCalled();
     // The sandbox reached finalization (policies confirmed), so it stays the default
     // even when post-policy verification flakes — only a pre-policy cancel rolls back.

src/lib/onboard/machine/handlers/finalization.ts

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import type { Session, SessionUpdates } from "../../../state/onboard-session";
+import type { Session } from "../../../state/onboard-session";
+import { completeOnboardMachine, type OnboardStateCompleteResult } from "../result";
 
 export interface FinalizationStateOptions<Agent, VerifyChain, VerificationResult> {
   sandboxName: string;
@@ -23,8 +24,7 @@ export interface FinalizationStateOptions<Agent, VerifyChain, VerificationResult
      */
     setDefaultSandbox(sandboxName: string): void;
     recordPostVerifyStarted(): Promise<Session>;
-    recordSessionComplete(updates: SessionUpdates): Promise<Session>;
-    toSessionUpdates(updates: Record<string, unknown>): SessionUpdates;
+    toSessionUpdates(updates: Record<string, unknown>): NonNullable<OnboardStateCompleteResult["updates"]>;
     removeLegacyCredentialsFile(): void;
     cleanupStaleHostFiles(): void;
     checkAndRecoverSandboxProcesses(sandboxName: string, options: { quiet: boolean }): void;
@@ -52,7 +52,7 @@ export interface FinalizationStateOptions<Agent, VerifyChain, VerificationResult
 }
 
 export interface FinalizationStateResult {
-  session: Session;
+  stateResult: OnboardStateCompleteResult;
   unmigratedLegacyKeys: string[];
   verificationDiagnostics: string[];
 }
@@ -112,9 +112,10 @@ export async function handleFinalizationState<Agent, VerifyChain, VerificationRe
 
   deps.printDashboard(sandboxName, model, provider, nimContainer, agent);
 
-  const session = await deps.recordSessionComplete(
+  const stateResult = completeOnboardMachine(
     deps.toSessionUpdates({ sandboxName, provider, model, hermesAuthMethod, hermesToolGateways }),
+    { state: "finalizing" },
   );
 
-  return { session, unmigratedLegacyKeys, verificationDiagnostics };
+  return { stateResult, unmigratedLegacyKeys, verificationDiagnostics };
 }

src/lib/onboard/runtime-boundary.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import type { Session, SessionUpdates } from "../state/onboard-session";
+import type { OnboardStateResult } from "./machine/result";
 import { OnboardRuntime } from "./machine/runtime";
 import type { ResumeConfigConflict } from "./resume-config";
 import type { OnboardMachineEventType, OnboardMachineState } from "./machine/types";
@@ -39,6 +40,7 @@ export class OnboardRuntimeBoundary {
       recordStateSkipped: this.recordStateSkipped.bind(this),
       recordRepairEvent: this.recordRepairEvent.bind(this),
       recordResumeConflict: this.recordResumeConflict.bind(this),
+      recordStateResult: this.recordStateResult.bind(this),
       recordStepFailed: this.recordStepFailed.bind(this),
       recordPostVerifyStarted: this.recordPostVerifyStarted.bind(this),
       recordSessionComplete: this.recordSessionComplete.bind(this),
@@ -85,6 +87,10 @@ export class OnboardRuntimeBoundary {
     return this.getRuntime().markSkipped(state, metadata);
   }
 
+  async recordStateResult(result: OnboardStateResult): Promise<Session> {
+    return this.getRuntime().applyResult(result);
+  }
+
   async recordResumeConflict(conflict: ResumeConfigConflict): Promise<Session> {
     return this.getRuntime().emitResumeConflict(conflict);
   }