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/README.md

@@ -122,3 +122,46 @@ makes VirtualSMC step aside ("multiple devices present"); VirtualSMC carries
 the OSK itself. Images built before this change still need the stub:
 `vmix run --macos --applesmc`. RestrictEvents (`revpatch=memtab`) silences
 MacPro7,1's "Memory Modules Misconfigured" at login.
+
+## Guest agent, shares, persistent home, online templates
+
+macOS 13+ ships **Apple's own QEMU guest agent** (`/usr/libexec/AppleQEMUGuestAgent`,
+started by launchd when a virtio console port named `org.qemu.guest_agent.0`
+appears). It is Apple-signed, needs no approval, and offers `guest-exec` as
+root plus `guest-file-*`. vmix uses it everywhere an in-guest agent is needed:
+
+* `vmix run --macos` and the NixOS module attach it by default
+  (`/tmp/vmix-qga-<pid>.sock`, `/run/vmix/qga-<name>.sock`); talk to it with any
+  QGA client, e.g. `printf '{"execute":"guest-exec","arguments":{"path":"/usr/bin/id","capture-output":true}}\n' | socat - UNIX-CONNECT:<sock>`.
+* **online templates** (`bootScript`): `customizeImage` boots the image with the
+  agent, runs the script as root (network available, `as_user <cmd>` runs inside
+  the logged-in user's session), then shuts down through the agent.
+  `templates.software.script { name; script; }`,
+  `templates.software.homebrew { formulae; casks; }`,
+  `templates.profile.settings { hideWidgets; wallpaper; dockApps; dockAutohide;
+  darkMode; showHiddenFiles; }` (wallpaper via the pinned `desktoppr`; Apple
+  Events / `osascript` do not work headless — TCC automation consent).
+* **offline software templates** run in the PE: `templates.software.pkg { name;
+  src; }` (`installer -target`), `templates.software.app { name; src; }`.
+
+`AppleVirtIO.kext` (x86 Tahoe) drives virtio-fs, 9p, block, console, input,
+net, sound, balloon, vsock — QEMU's modern virtio-pci devices work as-is:
+
+* **shared folders**: virtio-fs (`virtiofsd` + `vhost-user-fs-pci`, shared
+  memory backend). The tag `com.apple.virtio-fs.automount` is mounted by macOS
+  itself at `/Volumes/My Shared Files`; further tags are mounted with
+  `mount -t virtiofs <tag> <dir>` — the module does that through the guest agent
+  for every `shares.<name>` beyond the first. `vmix run --macos --share DIR`.
+  (9p does not automount on macOS; the Linux `-virtfs` path is not used.)
+* **ephemeral OS disk + persistent home**: `generalize { persistHome = true; }`
+  adds `LABEL=vmix-home /Users apfs rw 0 2` to the image's fstab. The host
+  provides a virtio-blk disk (`macos.homeDisk` in the module, `--home FILE` in
+  the CLI: qcow2/raw file or zvol) that `formatVolume` formats as APFS
+  `vmix-home` by booting the PE for ~35 s on first use. macOS mounts it at
+  `/Users` before login, home directories are created there; the OS disk can run
+  with `snapshot=on` (`disks.os.persist = false`).
+* **SPICE**: `-vga vmware` (or `std`) is kept as the display device — macOS has
+  no QXL/virtio-gpu driver; USB redirection channels work as for other guests
+  (`spice.usbRedir`); there is no vdagent for macOS (no clipboard sharing).
+  virtio keyboard/tablet (`AppleVirtIOInput`) are available as
+  `qemu.virtioInputArgs` but the USB HID pair is the default.