Vassal has multiple toolbars. There is one module toolbar and each map has it’s own toolbar. Toolbar button defined within a map (e.g. Layer control buttons) only appear in the toolbar belonging to that map and so can only be added to toolbar menus belonging to the toolbar belonging to that map.
In this case, if you copy the toolbar menu you created under the module and paste it into your map, you will find that it works.
Similiarly, toolbar buttons created at the module level can only appear in menus created at the module level.
Ok, a little follow up on this. Putting the menu under the appropriate window section worked. I added a Hide Pieces Button without an icon in the window as well. I then put it into the Toolbar Menu, and it got pulled in to the menu like I thought it would.
However, when I click on the All Pieces choice (the text I chose to put in the Hide Pieces Button button text), it pops out back on to the main toolbar. None of the other Layer Control Buttons does this. I figure it has something to do with having an icon attached (even though I tried to set it up without one) or maybe the name changes with some null character that I can’t see. I modified the test mod and reposted it here if you want to see this in action.