macOS: guest agent, online templates, virtio-fs shares, persistent home volume

Apple's built-in QEMU guest agent (AppleQEMUGuestAgent, launched by launchd
when a virtio console port org.qemu.guest_agent.0 appears; guest-exec as root)
is attached by vmix run --macos and the NixOS module. AppleVirtIO.kext on x86
Tahoe drives virtio-fs, block, console, input, net — verified in QEMU.

- customizeImage: `bootScript` — online step through the guest agent (driver
  mode qga): boot the image, run the script as root with the VMIX volume, shut
  down through the agent. `as_user` runs commands in the logged-in session.
- templates.software: pkg/app (offline in the PE), script/homebrew (online).
- templates.profile.settings: widgets, wallpaper (pinned desktoppr — Apple
  Events need TCC consent that a headless session cannot give), dock apps,
  autohide, dark mode, hidden files.
- generalize: persistHome (fstab LABEL=vmix-home /Users), hideWidgets offline.
- formatVolume: formats a blank disk image as APFS by booting the PE (~35 s);
  idempotent.
- NixOS module: macos.guestAgent (/run/vmix/qga-<name>.sock), shares via
  virtiofsd + vhost-user-fs (Apple automount tag for the first share, others
  mounted through the agent), macos.homeDisk (created + formatted on first
  start, virtio-blk), SPICE keeps -vga vmware for macOS.
- CLI: vmix run --macos --share DIR --home FILE --qga PATH.
- qemu.nix helpers; README section.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XsESshRCoBoUVWV9qKURUF

lib/images/macos/templates/generalize.nix

@@ -22,6 +22,13 @@
   uuid ? null,
   mac ? null,
   seed ? "${hostname}-${username}",
+  # mount an APFS volume labelled vmix-home (a virtio-blk/AHCI disk the host
+  # provides, formatted by the PE on first start) at /Users: ephemeral OS disk,
+  # persistent home directories
+  persistHome ? false,
+  homeVolumeLabel ? "vmix-home",
+  # no desktop widgets for the created user (Sonoma+)
+  hideWidgets ? true,
   # accepted for CLI parity with Windows, not supported on macOS
   bgColor ? null,
 }:
@@ -92,6 +99,11 @@ in
     pe_plist_set "$P" LastPreLoginTasksPerformedVersion string "$VER"
     pe_plist_set "$P" LastPreLoginTasksPerformedBuild string "$BUILD"
     pe_plist_set "$HOME_DIR/Library/Preferences/.GlobalPreferences.plist" AppleLocale string "${macLocale}"
+    ${lib.optionalString hideWidgets ''
+    WM="$HOME_DIR/Library/Preferences/com.apple.WindowManager.plist"
+    pe_plist_set "$WM" StandardHideWidgets integer 1
+    pe_plist_set "$WM" StageManagerHideWidgets integer 1
+    ''}
     chown -R "$UID_NEW:20" "$HOME_DIR"
     touch "$DATA/private/var/db/.AppleSetupDone"
     ''}
@@ -119,6 +131,14 @@ in
     pe_plist_dict "$KT" keyboardtype
     pe_plist_set "$KT" keyboardtype.1-1575-0 integer 40
 
+    ${lib.optionalString persistHome ''
+    # --- home directories on the host-provided persistent volume (fstab by label;
+    # diskarbitrationd mounts it at /Users when a volume named ${homeVolumeLabel} exists)
+    F="$DATA/private/etc/fstab"
+    grep -q "LABEL=${homeVolumeLabel}" "$F" 2>/dev/null || echo "LABEL=${homeVolumeLabel} /Users apfs rw 0 2" >> "$F"
+    chmod 644 "$F"; chown 0:0 "$F"
+    ''}
+
     # --- use the whole (possibly grown) disk
     STORE=$(diskutil info "$SYS_ID" | sed -n 's/.*APFS Physical Store: *//p' | awk '{print $1}')
     [ -n "$STORE" ] && diskutil apfs resizeContainer "$STORE" 0 || true