refactor(onboard): run initial phases through FSM slice

src/lib/onboard.ts

@@ -141,7 +141,6 @@ const crypto = require("node:crypto");
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
-const { spawnSync } = require("child_process");
 const pRetry = require("p-retry");
 
 /** Strip ANSI escape sequences before printing process output to the terminal.
@@ -379,7 +378,6 @@ const {
 const sandboxGpuPreflight: typeof import("./onboard/sandbox-gpu-preflight") = require("./onboard/sandbox-gpu-preflight");
 const {
   exitOnSandboxGpuConfigErrors,
-  formatSandboxGpuPassthroughNote,
   resolveSandboxGpuFlagFromOptions,
   validateSandboxGpuPreflight,
 } = sandboxGpuPreflight;
@@ -459,21 +457,19 @@ const {
 const {
   handleFinalizationState,
 }: typeof import("./onboard/machine/handlers/finalization") = require("./onboard/machine/handlers/finalization");
-const {
-  handleGatewayState,
-}: typeof import("./onboard/machine/handlers/gateway") = require("./onboard/machine/handlers/gateway");
 const {
   handlePoliciesState,
 }: typeof import("./onboard/machine/handlers/policies") = require("./onboard/machine/handlers/policies");
-const {
-  handlePreflightState,
-}: typeof import("./onboard/machine/handlers/preflight") = require("./onboard/machine/handlers/preflight");
 const {
   handleProviderInferenceState,
 }: typeof import("./onboard/machine/handlers/provider-inference") = require("./onboard/machine/handlers/provider-inference");
 const {
   handleSandboxState,
 }: typeof import("./onboard/machine/handlers/sandbox") = require("./onboard/machine/handlers/sandbox");
+const {
+  createInitialOnboardFlowPhases,
+  runInitialOnboardFlowSlice,
+}: typeof import("./onboard/machine/initial-flow-phases") = require("./onboard/machine/initial-flow-phases");
 const {
   advanceTo,
 }: typeof import("./onboard/machine/result") = require("./onboard/machine/result");
@@ -6415,29 +6411,56 @@ async function onboard(opts: OnboardOptions = {}): Promise<void> {
 
     const explicitSandboxGpuFlag = resolveSandboxGpuFlagFromOptions(opts);
     const recordedGpuPassthroughBeforePreflight = session?.gpuPassthrough === true;
-    const preflightResult = await handlePreflightState({
+    type InitialOnboardFlowContext =
+      import("./onboard/machine/initial-flow-phases").InitialOnboardFlowContext<
+        typeof agent,
+        ReturnType<typeof nim.detectGpu>,
+        ReturnType<typeof resolveSandboxGpuConfig>
+      >;
+    const initialFlowContext: InitialOnboardFlowContext = {
       resume,
+      fresh,
       session,
+      agent,
       recordedSandboxName,
       requestedSandboxName,
+      sandboxName: recordedSandboxName || requestedSandboxName || null,
+      fromDockerfile,
+      model: session?.model || null,
+      provider: session?.provider || null,
+      endpointUrl: session?.endpointUrl || null,
+      credentialEnv: session?.credentialEnv || null,
+      hermesAuthMethod: normalizeHermesAuthMethod(session?.hermesAuthMethod),
+      hermesToolGateways: normalizeHermesToolGatewaySelections(session?.hermesToolGateways),
+      preferredInferenceApi: session?.preferredInferenceApi || null,
+      nimContainer: session?.nimContainer || null,
+      webSearchConfig: session?.webSearchConfig || null,
+      webSearchSupported: false,
+      selectedMessagingChannels,
+      gpu: null,
+      sandboxGpuConfig: null,
+      gpuPassthrough: false,
+      resumeHasResolvedGpuIntent: false,
+      requestedGpuPassthrough: opts.gpu === true,
+    };
+
+    const [preflightPhase, gatewayPhase] = createInitialOnboardFlowPhases({
       explicitSandboxGpuFlag,
       sandboxGpuDevice: opts.sandboxGpuDevice ?? null,
       gpuRequested: opts.gpu === true,
       noGpu: opts.noGpu === true,
       env: process.env,
-      deps: {
+      recordedGpuPassthroughBeforePreflight,
+      ensureResumePreflightDashboardPortAvailable: () => {
+        if (_preflightDashboardPort === null) preflightDashboardPortRangeAvailability();
+      },
+      preflightDeps: {
         getSandbox: registry.getSandbox.bind(registry),
         getResumeSandboxGpuOverrides,
         detectGpu: nim.detectGpu,
         runPreflight: (preflightOptions) => preflight({ ...opts, ...preflightOptions }),
         assessHost,
         assertCdiNvidiaGpuSpecPresent,
-        // Resume backstops for #3508/#3630/Podman: the cached preflight
-        // step does not capture host Docker/DNS state, and a session
-        // written by an older NemoClaw may not have run the new bridge/
-        // DNS fatal checks (mirrors the assertCdiNvidiaGpuSpecPresent
-        // resume pattern). Podman rejection runs first so users on
-        // unsupported runtimes don't see Docker-specific diagnostics.
         rejectUnsupportedContainerRuntime,
         assertDockerBridgeAndContainerDnsHealthy,
         resolveSandboxGpuConfig,
@@ -6448,59 +6471,11 @@ async function onboard(opts: OnboardOptions = {}): Promise<void> {
         recordStepComplete,
         updateSession: onboardSession.updateSession,
       },
-    });
-    if (resume && _preflightDashboardPort === null) preflightDashboardPortRangeAvailability(); // #3953 — resume must mirror preflight()'s fail-fast
-    session = (await recordStateResult(preflightResult.stateResult), preflightResult.session);
-    const {
-      sandboxGpuConfig,
-      resumeHasResolvedGpuIntent,
-      requestedGpuPassthrough,
-      gpuPassthrough,
-    } = preflightResult;
-    const gpu = preflightResult.gpu ?? null;
-    if (gpuPassthrough) {
-      note(
-        formatSandboxGpuPassthroughNote({
-          hostGpuPlatform: sandboxGpuConfig.hostGpuPlatform,
-          resumeHasResolvedGpuIntent,
-          recordedGpuPassthroughBeforePreflight,
-          requestedGpuPassthrough,
-          sandboxGpuMode: sandboxGpuConfig.mode,
-        }),
-      );
-    } else if (gpu?.platform === "jetson") {
-      note("  Sandbox GPU disabled by configuration on Jetson/Tegra.");
-    } else if (process.platform === "linux" && !opts.noGpu) {
-      try {
-        const lspci = spawnSync("lspci", { encoding: "utf-8", timeout: 5000 });
-        if (lspci.status === 0 && /nvidia/i.test(lspci.stdout || "")) {
-          const smi = spawnSync(
-            "nvidia-smi",
-            ["--query-gpu=name", "--format=csv,noheader,nounits"],
-            { encoding: "utf-8", timeout: 5000 },
-          );
-          note(
-            smi.status === 0 && smi.stdout?.trim()
-              ? "  NVIDIA GPU detected with working drivers, but GPU passthrough was not enabled.\n  If Docker GPU support is needed, install nvidia-container-toolkit and run:\n  sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker"
-              : "  NVIDIA GPU hardware detected but nvidia-smi is not available.\n  Install NVIDIA drivers and the Container Toolkit for default GPU passthrough.",
-          );
-        }
-      } catch {
-        /* lspci not available — skip hint */
-      }
-    }
-    const gatewaySnapshot = selectNamedGatewayForReuseIfNeeded(getGatewayReuseSnapshot());
-    const gatewayResult = await handleGatewayState({
-      resume,
-      session,
-      initialGatewayReuseState: gatewaySnapshot.gatewayReuseState,
-      gpu,
-      gpuPassthrough,
+      getInitialGatewayReuseState: () =>
+        selectNamedGatewayForReuseIfNeeded(getGatewayReuseSnapshot()).gatewayReuseState,
       gatewayName: GATEWAY_NAME,
-      recordedSandboxName,
-      requestedSandboxName,
-      recreateSandbox: isRecreateSandbox(),
-      deps: {
+      recreateSandbox: isRecreateSandbox,
+      gatewayDeps: {
         refreshDockerDriverGatewayReuseState,
         gatewayCliSupportsLifecycleCommands: () =>
           gatewayCliSupportsLifecycleCommands(runCaptureOpenshell),
@@ -6529,8 +6504,23 @@ async function onboard(opts: OnboardOptions = {}): Promise<void> {
         recordStepComplete,
         exitProcess: (code) => process.exit(code),
       },
+      note,
     });
-    session = (await recordStateResult(gatewayResult.stateResult), gatewayResult.session);
+    const initialFlowResult = await runInitialOnboardFlowSlice({
+      context: initialFlowContext,
+      runtime: onboardRuntimeBoundary.getRuntime(),
+      phases: [preflightPhase, gatewayPhase],
+      resume,
+      recordStateResult,
+    });
+
+    const initialContext = initialFlowResult.context;
+    if (!initialContext.sandboxGpuConfig) {
+      throw new Error("Preflight did not produce a sandbox GPU configuration.");
+    }
+    session = initialFlowResult.session;
+    const sandboxGpuConfig = initialContext.sandboxGpuConfig;
+    const gpu = initialContext.gpu;
 
     // #2753: prefer requestedSandboxName over an unconfirmed session name.
     // A pre-fix session may carry sandboxName even though sandbox creation