@a11ign/screenreader-fleet 0.0.0-reserved.0 → 0.1.0

package/src/local-worker/autounattend.xml

@@ -0,0 +1,280 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Unattended install for the local NVDA capture worker (Windows 11 ARM64 under QEMU).
+
+  Derived from the Autounattend.xml that UTM ships on utm-guest-tools.iso, which is
+  the proven ARM64 recipe: the LabConfig bypasses and the windowsPE ARM64 driver
+  paths come from there. What UTM's version does NOT do is complete the install
+  hands-off, so this adds:
+
+    * DiskConfiguration + ImageInstall   - partition and install with no clicking
+    * LocalAccounts + AutoLogon          - NVDA needs a logged-on interactive desktop,
+                                           so auto-logon is a REQUIREMENT here, not a
+                                           convenience: without it the worker is dead
+                                           after every reboot until a human logs in
+    * FirstLogonCommands                 - hand off to the worker bootstrap
+
+  Drive E: is the support ISO built by build-vm.sh (this file plus the
+  UTM guest-tools payload). Windows Setup picks autounattend.xml up automatically
+  from the root of removable media.
+
+  SECURITY: the account password below is in plain text, in a checked-in file. That is
+  acceptable ONLY because this is a disposable local VM behind QEMU user-mode
+  networking, reachable solely through the ports the launch script forwards to
+  127.0.0.1. Do not put this VM on a bridged network, and do not reuse the password.
+
+  NOTE: UTM's template sets EnableLUA=false (UAC off). We deliberately do NOT copy
+  that. With UAC off every process runs at high integrity, and the capture pipeline
+  depends on NVDA (nvda_noUIAccess.exe) and Edge sitting at the SAME integrity level;
+  leaving UAC at its default keeps that relationship the way the Proxmox worker has it,
+  rather than betting the pipeline on an untested configuration. Provisioning gets the
+  elevation it needs from a RunLevel Highest scheduled task instead, which elevates
+  without a prompt  -  and a prompt would be fatal, since UAC dialogs render on the
+  secure desktop where automation cannot reach them.
+-->
+<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State">
+
+  <settings pass="windowsPE">
+    <component name="Microsoft-Windows-International-Core-WinPE" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <SetupUILanguage>
+        <UILanguage>en-US</UILanguage>
+      </SetupUILanguage>
+      <InputLocale>en-US</InputLocale>
+      <SystemLocale>en-US</SystemLocale>
+      <UILanguage>en-US</UILanguage>
+      <UserLocale>en-US</UserLocale>
+    </component>
+
+    <component name="Microsoft-Windows-Setup" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <Diagnostics>
+        <OptIn>false</OptIn>
+      </Diagnostics>
+
+
+      <!-- UEFI/GPT layout: ESP, MSR, then Windows across the remainder. -->
+      <DiskConfiguration>
+        <WillShowUI>OnError</WillShowUI>
+        <Disk wcm:action="add">
+          <DiskID>0</DiskID>
+          <WillWipeDisk>true</WillWipeDisk>
+          <CreatePartitions>
+            <CreatePartition wcm:action="add">
+              <Order>1</Order>
+              <Type>EFI</Type>
+              <Size>300</Size>
+            </CreatePartition>
+            <CreatePartition wcm:action="add">
+              <Order>2</Order>
+              <Type>MSR</Type>
+              <Size>16</Size>
+            </CreatePartition>
+            <CreatePartition wcm:action="add">
+              <Order>3</Order>
+              <Type>Primary</Type>
+              <Extend>true</Extend>
+            </CreatePartition>
+          </CreatePartitions>
+          <ModifyPartitions>
+            <ModifyPartition wcm:action="add">
+              <Order>1</Order>
+              <PartitionID>1</PartitionID>
+              <Format>FAT32</Format>
+              <Label>System</Label>
+            </ModifyPartition>
+            <ModifyPartition wcm:action="add">
+              <Order>2</Order>
+              <PartitionID>2</PartitionID>
+            </ModifyPartition>
+            <ModifyPartition wcm:action="add">
+              <Order>3</Order>
+              <PartitionID>3</PartitionID>
+              <Format>NTFS</Format>
+              <Label>Windows</Label>
+              <Letter>C</Letter>
+            </ModifyPartition>
+          </ModifyPartitions>
+        </Disk>
+      </DiskConfiguration>
+
+      <!-- Match /IMAGE/NAME to the WIM's NAME, which is "Windows 11 Professional".
+           "Windows 11 Pro" is its DESCRIPTION, and matching that leaves Setup sitting on
+           the edition picker. Keep this block byte-for-byte simple: substituting
+           /IMAGE/INDEX here, or adding a comment inside <InstallFrom>, made Setup reject
+           the whole answer file and revert to a fully interactive install. -->
+      <ImageInstall>
+        <OSImage>
+          <InstallFrom>
+            <MetaData wcm:action="add">
+              <Key>/IMAGE/NAME</Key>
+              <Value>Windows 11 Professional</Value>
+            </MetaData>
+          </InstallFrom>
+          <InstallTo>
+            <DiskID>0</DiskID>
+            <PartitionID>3</PartitionID>
+          </InstallTo>
+          <WillShowUI>OnError</WillShowUI>
+        </OSImage>
+      </ImageInstall>
+
+      <!-- Windows 11 refuses to install without TPM 2.0 and Secure Boot. Rather than
+           wiring up swtpm, take UTM's approach and tell Setup to skip the checks. -->
+      <RunSynchronous>
+        <RunSynchronousCommand wcm:action="add">
+          <Order>1</Order>
+          <Path>reg add HKLM\System\Setup\LabConfig /v BypassCPUCheck /t REG_DWORD /d 0x00000001 /f</Path>
+        </RunSynchronousCommand>
+        <RunSynchronousCommand wcm:action="add">
+          <Order>2</Order>
+          <Path>reg add HKLM\System\Setup\LabConfig /v BypassRAMCheck /t REG_DWORD /d 0x00000001 /f</Path>
+        </RunSynchronousCommand>
+        <RunSynchronousCommand wcm:action="add">
+          <Order>3</Order>
+          <Path>reg add HKLM\System\Setup\LabConfig /v BypassSecureBootCheck /t REG_DWORD /d 0x00000001 /f</Path>
+        </RunSynchronousCommand>
+        <RunSynchronousCommand wcm:action="add">
+          <Order>4</Order>
+          <Path>reg add HKLM\System\Setup\LabConfig /v BypassTPMCheck /t REG_DWORD /d 0x00000001 /f</Path>
+        </RunSynchronousCommand>
+        <RunSynchronousCommand wcm:action="add">
+          <Order>5</Order>
+          <Path>reg add HKLM\System\Setup\LabConfig /v BypassDiskCheck /t REG_DWORD /d 0x00000001 /f</Path>
+        </RunSynchronousCommand>
+      </RunSynchronous>
+
+      <UserData>
+        <AcceptEula>true</AcceptEula>
+        <FullName>a11ign</FullName>
+        <Organization>a11ign</Organization>
+        <!-- Generic Windows 11 Pro KMS client key: selects the edition during an
+             unattended install. It does NOT activate, which is what we want  -  an
+             unactivated Windows is fully functional for capture, and leaving it
+             unactivated keeps the exported image portable between machines. -->
+        <ProductKey>
+          <Key>W269N-WFGWX-YVC9B-4J6C9-T83GX</Key>
+          <WillShowUI>Never</WillShowUI>
+        </ProductKey>
+      </UserData>
+    </component>
+
+    <!-- ARM64 virtio drivers, injected so the installed OS has storage, serial and
+         NETWORK working on first boot. Networking on first boot is what lets the
+         bootstrap fetch Node, Git and NVDA without any manual driver step.
+         Paths are UTM's, on the support ISO (drive E:). viogpu is deliberately left
+         out: UTM disables it because it causes a black screen. -->
+    <component name="Microsoft-Windows-PnpCustomizationsWinPE" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <DriverPaths>
+        <PathAndCredentials wcm:action="add" wcm:keyValue="1">
+          <Path>E:\Drivers\vioscsi\w10\ARM64</Path>
+        </PathAndCredentials>
+        <PathAndCredentials wcm:action="add" wcm:keyValue="2">
+          <Path>E:\Drivers\viostor\w10\ARM64</Path>
+        </PathAndCredentials>
+        <PathAndCredentials wcm:action="add" wcm:keyValue="3">
+          <Path>E:\Drivers\vioserial\w10\ARM64</Path>
+        </PathAndCredentials>
+        <PathAndCredentials wcm:action="add" wcm:keyValue="4">
+          <Path>E:\Drivers\NetKVM\w10\ARM64</Path>
+        </PathAndCredentials>
+        <PathAndCredentials wcm:action="add" wcm:keyValue="5">
+          <Path>E:\Drivers\Balloon\w10\ARM64</Path>
+        </PathAndCredentials>
+      </DriverPaths>
+    </component>
+  </settings>
+
+  <settings pass="specialize">
+    <component name="Microsoft-Windows-Shell-Setup" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <ComputerName>A11Y-WORKER</ComputerName>
+      <TimeZone>GMT Standard Time</TimeZone>
+    </component>
+    <component name="Microsoft-Windows-Security-SPP-UX" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <SkipAutoActivation>true</SkipAutoActivation>
+    </component>
+    <component name="Microsoft-Windows-SQMApi" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <CEIPEnabled>0</CEIPEnabled>
+    </component>
+  </settings>
+
+  <settings pass="oobeSystem">
+    <component name="Microsoft-Windows-International-Core" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <InputLocale>en-US</InputLocale>
+      <SystemLocale>en-US</SystemLocale>
+      <UILanguage>en-US</UILanguage>
+      <UserLocale>en-US</UserLocale>
+    </component>
+
+    <component name="Microsoft-Windows-Shell-Setup" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <UserAccounts>
+        <LocalAccounts>
+          <LocalAccount wcm:action="add">
+            <Name>witness</Name>
+            <DisplayName>witness</DisplayName>
+            <Group>Administrators</Group>
+            <Password>
+              <Value>witness</Value>
+              <PlainText>true</PlainText>
+            </Password>
+          </LocalAccount>
+        </LocalAccounts>
+      </UserAccounts>
+
+      <!-- The whole reason this file exists. NVDA is a GUI application: it needs a
+           real logged-on desktop session. No auto-logon means no session after a
+           reboot, which means captures silently return nothing at all. -->
+      <AutoLogon>
+        <Enabled>true</Enabled>
+        <Username>witness</Username>
+        <Password>
+          <Value>witness</Value>
+          <PlainText>true</PlainText>
+        </Password>
+        <LogonCount>2147483647</LogonCount>
+      </AutoLogon>
+
+      <OOBE>
+        <HideEULAPage>true</HideEULAPage>
+        <HideOEMRegistrationScreen>true</HideOEMRegistrationScreen>
+        <HideOnlineAccountScreens>true</HideOnlineAccountScreens>
+        <HideLocalAccountScreen>true</HideLocalAccountScreen>
+        <HideWirelessSetupInOOBE>true</HideWirelessSetupInOOBE>
+        <ProtectYourPC>3</ProtectYourPC>
+        <VMModeOptimizations>
+          <SkipWinREInitialization>true</SkipWinREInitialization>
+        </VMModeOptimizations>
+      </OOBE>
+
+      <FirstLogonCommands>
+        <SynchronousCommand wcm:action="add">
+          <Order>1</Order>
+          <Description>Disable hibernation</Description>
+          <CommandLine>cmd /c POWERCFG -H OFF</CommandLine>
+        </SynchronousCommand>
+        <!-- Adds qemu-ga, which gives the host a command channel into this guest over
+             QMP before SSH exists  -  the difference between debugging this VM and
+             guessing at it. /S is the NSIS silent switch. -->
+        <SynchronousCommand wcm:action="add">
+          <Order>2</Order>
+          <Description>Install UTM/virtio guest tools (adds qemu-ga)</Description>
+          <CommandLine>cmd /c for %i in (D E F G) do if exist %i:\utm-guest-tools.exe start /wait %i:\utm-guest-tools.exe /S</CommandLine>
+        </SynchronousCommand>
+        <!-- Never disable the screensaver's lock and then leave the console locked:
+             a locked desktop makes NVDA silent. Belt and braces alongside the
+             provisioning script, which also turns the screensaver off. -->
+        <SynchronousCommand wcm:action="add">
+          <Order>3</Order>
+          <Description>Disable screensaver (it steals foreground mid-capture)</Description>
+          <CommandLine>reg add "HKCU\Control Panel\Desktop" /v ScreenSaveActive /t REG_SZ /d 0 /f</CommandLine>
+        </SynchronousCommand>
+        <!-- Provisioning needs elevation (firewall rules, HKLM Edge policy). A
+             RunLevel Highest scheduled task elevates with NO prompt; a UAC dialog here
+             would render on the secure desktop and hang the build forever. -->
+        <SynchronousCommand wcm:action="add">
+          <Order>4</Order>
+          <Description>Run the worker bootstrap elevated, without a UAC prompt</Description>
+          <CommandLine>cmd /c for %i in (D E F G) do if exist %i:\first-boot.cmd start /wait %i:\first-boot.cmd</CommandLine>
+        </SynchronousCommand>
+      </FirstLogonCommands>
+    </component>
+  </settings>
+</unattend>

package/src/local-worker/build-vm.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# Build a local NVDA capture worker VM on Apple Silicon, unattended.
+#
+#   ./packages/worker-fleet/src/local-worker/build-vm.sh /path/to/Win11_ARM64.iso
+#
+# Produces a self-contained VM directory (default ~/a11y-worker-vm) holding the disk
+# image, UEFI vars and a run script. That directory IS the portable artifact: copy it
+# to another Apple Silicon Mac, run ./run.sh, done. See docs/local-worker-vm.md.
+#
+# Why QEMU and not UTM: `utmctl` has no `create` subcommand, so a UTM-based flow can
+# only ever be "click through these GUI steps". QEMU is scriptable end to end, which is
+# the difference between a reproducible artifact and a folk recipe.
+set -euo pipefail
+
+# architecture-audit.md §8: builds a local UTM/QEMU worker VM, which is deprecated -- "The UTM is
+# deprecated, that was a testing thing." (repository owner, 2026-09-05). Capture on the bare-metal fleet
+# instead: npm run fleet:status, npm run fleet:deploy.
+echo "DEPRECATED: build-vm.sh builds a local UTM worker VM. UTM was a testing path and is not the fleet." >&2
+echo "Capture on the bare-metal fleet instead: npm run fleet:status, npm run fleet:deploy." >&2
+
+# #636: a warning on a path nobody watches is a warning nobody reads -- so this REFUSES, rather than
+# merely printing the two lines above and continuing. The measurements and reasoning behind the local-VM
+# work stay in docs/local-worker-vm.md as history; only the path that runs is fenced.
+if [ "${A11Y_LOCAL_VM:-}" != "1" ]; then
+  echo "refusing: set A11Y_LOCAL_VM=1 to run this deprecated local-VM script anyway." >&2
+  exit 1
+fi
+
+WIN_ISO="${1:-}"
+VM_DIR="${A11Y_VM_DIR:-$HOME/a11y-worker-vm}"
+DISK_GB="${A11Y_VM_DISK_GB:-64}"
+RAM_MB="${A11Y_VM_RAM_MB:-8192}"
+CPUS="${A11Y_VM_CPUS:-4}"
+WORKER_PORT="${A11Y_PORT:-8765}"
+SSH_PORT="${A11Y_VM_SSH_PORT:-2222}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+die() { echo "error: $*" >&2; exit 1; }
+info() { echo "==> $*"; }
+
+[ -n "$WIN_ISO" ] || die "usage: $0 <windows-11-arm64.iso>   (build one with CrystalFetch, or packages/worker-fleet/src/local-worker/fetch-windows-iso.sh)"
+[ -f "$WIN_ISO" ] || die "not found: $WIN_ISO"
+command -v qemu-system-aarch64 >/dev/null || die "qemu missing: brew install qemu"
+command -v qemu-img >/dev/null || die "qemu-img missing: brew install qemu"
+command -v mkisofs >/dev/null || die "mkisofs missing: brew install cdrtools"
+
+FW_CODE="$(ls /opt/homebrew/share/qemu/edk2-aarch64-code.fd /usr/local/share/qemu/edk2-aarch64-code.fd 2>/dev/null | head -1 || true)"
+FW_VARS_SRC="$(ls /opt/homebrew/share/qemu/edk2-arm-vars.fd /usr/local/share/qemu/edk2-arm-vars.fd 2>/dev/null | head -1 || true)"
+[ -n "$FW_CODE" ] || die "edk2-aarch64-code.fd not found (reinstall qemu)"
+[ -n "$FW_VARS_SRC" ] || die "edk2-arm-vars.fd not found (reinstall qemu)"
+
+mkdir -p "$VM_DIR"
+
+# ---------------------------------------------------------------------------
+info "Fetching UTM guest tools (ARM64 virtio drivers + qemu-ga)"
+# These drivers are the reason this works at all: Windows 11 ARM64 has no inbox
+# virtio-net driver, so without injecting NetKVM the installed OS has no network and
+# cannot fetch Node/Git/NVDA. The ISO also carries qemu-ga, which gives the host a
+# command channel into the guest over QMP before SSH exists.
+GT_ISO="$VM_DIR/utm-guest-tools.iso"
+if [ ! -f "$GT_ISO" ]; then
+  GT_URL="$(curl -sL https://api.github.com/repos/utmapp/qemu/releases/latest \
+    | grep -o 'https://[^"]*guest-tools[^"]*\.iso' | head -1 || true)"
+  [ -n "$GT_URL" ] || die "could not resolve the guest-tools ISO URL"
+  curl -L --fail -o "$GT_ISO" "$GT_URL"
+fi
+info "guest tools: $(du -h "$GT_ISO" | cut -f1)"
+
+# ---------------------------------------------------------------------------
+info "Building the support ISO (autounattend + drivers + bootstrap)"
+# One removable medium carrying everything Setup and first logon need. Windows Setup
+# picks autounattend.xml up automatically from the root of removable media.
+STAGE="$(mktemp -d)"
+trap 'rm -rf "$STAGE"' EXIT
+MNT="$(mktemp -d)"
+hdiutil attach -readonly -nobrowse -mountpoint "$MNT" "$GT_ISO" >/dev/null
+cp -R "$MNT/Drivers" "$STAGE/"
+cp "$MNT"/utm-guest-tools-*.exe "$STAGE/utm-guest-tools.exe"
+hdiutil detach "$MNT" >/dev/null
+rmdir "$MNT" 2>/dev/null || true
+
+cp "$SCRIPT_DIR/autounattend.xml" "$STAGE/autounattend.xml"
+cp "$SCRIPT_DIR/first-boot.cmd" "$STAGE/first-boot.cmd"
+cp "$REPO_ROOT/scripts/bootstrap-windows-worker.ps1" "$STAGE/bootstrap-windows-worker.ps1"
+
+SUPPORT_ISO="$VM_DIR/support.iso"
+# -J (Joliet) so Windows sees real filenames rather than mangled 8.3 names.
+mkisofs -quiet -J -R -V A11YSUPPORT -o "$SUPPORT_ISO" "$STAGE"
+info "support ISO: $(du -h "$SUPPORT_ISO" | cut -f1)"
+
+# ---------------------------------------------------------------------------
+info "Creating disk and UEFI vars"
+[ -f "$VM_DIR/disk.qcow2" ] || qemu-img create -f qcow2 "$VM_DIR/disk.qcow2" "${DISK_GB}G" >/dev/null
+[ -f "$VM_DIR/efi-vars.fd" ] || cp "$FW_VARS_SRC" "$VM_DIR/efi-vars.fd"
+# Symlink rather than copy: the Windows ISO is ~4 GB and only needed for --install.
+# (When exporting the VM to another machine, the symlink is simply absent, which is
+# fine -- normal boots do not use it.)
+#
+# Guard against the source ALREADY being $VM_DIR/windows.iso: `ln -sf x x` creates a
+# symlink to itself and destroys the file. Passing the staged ISO back in is the obvious
+# thing to do on a second run, so this must not eat it.
+WIN_ISO_ABS="$(cd "$(dirname "$WIN_ISO")" && pwd)/$(basename "$WIN_ISO")"
+if [ "$WIN_ISO_ABS" != "$VM_DIR/windows.iso" ]; then
+  ln -sf "$WIN_ISO_ABS" "$VM_DIR/windows.iso"
+else
+  info "ISO is already staged at $VM_DIR/windows.iso; leaving it alone"
+fi
+
+# ---------------------------------------------------------------------------
+info "Writing run.sh"
+cat > "$VM_DIR/run.sh" <<RUNSH
+#!/usr/bin/env bash
+# Launch the a11ign NVDA worker VM. Generated by build-vm.sh.
+#   ./run.sh            headless; worker on 127.0.0.1:${WORKER_PORT}, ssh on 2222
+#   ./run.sh --install  first run: boot from the Windows ISO to install unattended
+set -euo pipefail
+VM_DIR="\$(cd "\$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+INSTALL=0
+[ "\${1:-}" = "--install" ] && INSTALL=1
+
+ARGS=(
+  -M virt,highmem=on
+  -accel hvf
+  -cpu host
+  -smp ${CPUS}
+  -m ${RAM_MB}
+  -drive if=pflash,format=raw,unit=0,readonly=on,file=${FW_CODE}
+  -drive if=pflash,format=raw,unit=1,file="\$VM_DIR/efi-vars.fd"
+  # NVMe rather than virtio-blk for the system disk: Windows 11 ARM64 has an inbox
+  # NVMe driver, so the disk is visible to Setup with no driver injection at all.
+  -drive file="\$VM_DIR/disk.qcow2",if=none,id=hd0,format=qcow2,cache=writeback,discard=unmap
+  -device nvme,drive=hd0,serial=a11yworker
+  # User-mode networking: the guest is NAT'd and unreachable except through these
+  # forwards, bound to loopback. That is what makes the plaintext password in
+  # autounattend.xml tolerable -- keep it that way, do not bridge this VM.
+  -netdev user,id=net0,hostfwd=tcp:127.0.0.1:${WORKER_PORT}-:${WORKER_PORT},hostfwd=tcp:127.0.0.1:${SSH_PORT}-:22
+  -device virtio-net-pci,netdev=net0
+  -device virtio-gpu-pci
+  -device qemu-xhci
+  -device usb-kbd
+  -device usb-tablet
+  -device virtio-rng-pci
+  # The monitor socket is how you get EYES on a headless install:
+  #   echo "screendump /tmp/vm.ppm" | socat - unix:\$VM_DIR/monitor.sock
+  -monitor unix:"\$VM_DIR/monitor.sock",server,nowait
+  -qmp unix:"\$VM_DIR/qmp.sock",server,nowait
+  -display none
+  -vnc 127.0.0.1:1
+  -rtc base=localtime
+)
+
+# CD-ROMs attach as USB storage, NOT with a bare "-drive media=cdrom". The aarch64
+# "virt" machine has no IDE bus, so the bare form fails to start at all ("No 'ide' bus
+# found"). virtio-blk would work for QEMU but Windows Setup cannot see a virtio disk
+# without the driver it is trying to read FROM that disk; USB mass storage is inbox on
+# Windows, so it sidesteps the chicken-and-egg entirely.
+if [ \$INSTALL -eq 1 ]; then
+  ARGS+=(
+    -drive file="\$VM_DIR/windows.iso",if=none,id=cdwin,media=cdrom,readonly=on
+    -device usb-storage,drive=cdwin,removable=on,bootindex=0
+    -drive file="\$VM_DIR/support.iso",if=none,id=cdsup,media=cdrom,readonly=on
+    -device usb-storage,drive=cdsup,removable=on
+  )
+else
+  # Keep the support ISO attached: provisioning may want the guest-tools installer,
+  # and an absent drive letter is a confusing failure mode.
+  ARGS+=(
+    -drive file="\$VM_DIR/support.iso",if=none,id=cdsup,media=cdrom,readonly=on
+    -device usb-storage,drive=cdsup,removable=on
+  )
+fi
+
+exec qemu-system-aarch64 "\${ARGS[@]}"
+RUNSH
+chmod +x "$VM_DIR/run.sh"
+
+# Screenshot helper. The VM runs headless, so this is the only way to see what an
+# unattended install is actually doing -- and "it is silently sitting on a prompt" and
+# "it is working fine" look identical without it.
+cat > "$VM_DIR/shot.sh" <<'SHOTSH'
+#!/usr/bin/env bash
+# Screenshot the headless guest. Usage: ./shot.sh [outfile.png]
+set -euo pipefail
+D="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUT="${1:-$D/shot.png}"
+command -v socat >/dev/null || { echo "needs socat: brew install socat" >&2; exit 1; }
+[ -S "$D/monitor.sock" ] || { echo "no monitor.sock -- is the VM running?" >&2; exit 1; }
+echo "screendump $D/.shot.ppm" | socat - unix-connect:"$D/monitor.sock" >/dev/null 2>&1
+sips -s format png "$D/.shot.ppm" --out "$OUT" >/dev/null 2>&1
+echo "$OUT  (disk now $(du -h "$D/disk.qcow2" | cut -f1))"
+SHOTSH
+chmod +x "$VM_DIR/shot.sh"
+
+cat <<EOF
+
+--- VM prepared in $VM_DIR ---
+
+  1. Start the unattended install (takes ~20-40 min, no interaction):
+         $VM_DIR/run.sh --install
+
+  2. Watch it without a display (screendump needs socat: brew install socat):
+         echo "screendump $VM_DIR/shot.ppm" | socat - unix:$VM_DIR/monitor.sock
+         # then convert/view: sips -s format png $VM_DIR/shot.ppm --out $VM_DIR/shot.png
+
+  3. When it settles, the worker should answer on the host:
+         curl http://127.0.0.1:${WORKER_PORT}/health
+         ssh -p ${SSH_PORT} witness@127.0.0.1
+
+  4. Point the control plane at it:
+         A11Y_WORKER=http://127.0.0.1:${WORKER_PORT} npm run witness -- https://example.com --task "..."
+
+  Subsequent boots: $VM_DIR/run.sh   (no --install)
+
+  To hand this to someone else, copy the whole $VM_DIR directory. Shut the guest down
+  cleanly first, and see docs/local-worker-vm.md for shrinking it.
+EOF

package/src/local-worker/clone-worker.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# Clone the local NVDA worker VM into an additional, independent worker.
+#
+#   ./packages/worker-fleet/src/local-worker/clone-worker.sh [new-name]      # default: a11y-worker-2
+#
+# One worker serves one capture at a time by design (one desktop, one foreground window, one
+# NVDA), so throughput scales by running more of them. On APFS the clone is copy-on-write, so
+# it costs seconds and almost no disk until the two diverge.
+#
+# THE REASON THIS SCRIPT EXISTS: `utmctl clone` copies the MAC address. Two VMs with the same
+# MAC on one vmnet share a single DHCP lease — the clone takes the original's IP and the
+# original ends up with NO address at all. It boots perfectly and looks utterly dead from
+# outside, which is a miserable thing to debug. So the clone gets a fresh MAC before it is
+# ever started.
+#
+# Editing config.plist requires UTM to be quit: it caches configuration in memory and will
+# write its cached copy back over the edit.
+set -euo pipefail
+
+# architecture-audit.md §8: clones a local UTM worker VM, which is deprecated -- "The UTM is deprecated,
+# that was a testing thing." (repository owner, 2026-09-05). Capture on the bare-metal fleet instead:
+# npm run fleet:status, npm run fleet:deploy.
+echo "DEPRECATED: clone-worker.sh clones a local UTM worker VM. UTM was a testing path and is not the fleet." >&2
+echo "Capture on the bare-metal fleet instead: npm run fleet:status, npm run fleet:deploy." >&2
+
+# #636: a warning on a path nobody watches is a warning nobody reads -- so this REFUSES, rather than
+# merely printing the two lines above and continuing. The measurements and reasoning behind the local-VM
+# work stay in docs/local-worker-vm.md as history; only the path that runs is fenced.
+if [ "${A11Y_LOCAL_VM:-}" != "1" ]; then
+  echo "refusing: set A11Y_LOCAL_VM=1 to run this deprecated local-VM script anyway." >&2
+  exit 1
+fi
+
+SOURCE_NAME="${A11Y_VM_NAME:-a11y-worker}"
+NEW_NAME="${1:-${SOURCE_NAME}-2}"
+DOCS="$HOME/Library/Containers/com.utmapp.UTM/Data/Documents"
+BOOT_TIMEOUT_S=300
+PORT="${A11Y_PORT:-8765}"
+
+die() { echo "error: $*" >&2; exit 1; }
+say() { echo "==> $*"; }
+
+command -v utmctl >/dev/null || die "utmctl not found (brew install --cask utm)"
+pgrep -x UTM >/dev/null || { say "launching UTM (utmctl needs the app)"; open -a UTM; sleep 5; }
+
+uuid_of() { utmctl list | awk -v n="$1" '$3 == n { print $1 }'; }
+
+SOURCE_UUID="$(uuid_of "$SOURCE_NAME")"
+[ -n "$SOURCE_UUID" ] || die "no VM named '$SOURCE_NAME'"
+[ "$(echo "$SOURCE_UUID" | wc -l | tr -d ' ')" -eq 1 ] || die "several VMs named '$SOURCE_NAME'; see docs/local-worker-vm.md"
+[ -z "$(uuid_of "$NEW_NAME")" ] || die "'$NEW_NAME' already exists. Pick another name, or remove it in UTM first."
+
+# Clone a stopped VM. Copying a running disk gives a crash-consistent image — the clone would
+# boot as though the power had been pulled, with the dirty-volume repair that implies.
+if [ "$(utmctl status "$SOURCE_UUID")" != "stopped" ]; then
+  say "stopping '$SOURCE_NAME' cleanly first (a clone of a running disk boots dirty)"
+  utmctl stop "$SOURCE_UUID" --request >/dev/null
+  for _ in $(seq 1 40); do
+    [ "$(utmctl status "$SOURCE_UUID")" = "stopped" ] && break
+    sleep 3
+  done
+  [ "$(utmctl status "$SOURCE_UUID")" = "stopped" ] || die "'$SOURCE_NAME' would not shut down; stop it by hand and re-run"
+fi
+
+say "cloning '$SOURCE_NAME' -> '$NEW_NAME'"
+utmctl clone "$SOURCE_UUID" --name "$NEW_NAME" >/dev/null
+NEW_UUID="$(uuid_of "$NEW_NAME")"
+[ -n "$NEW_UUID" ] || die "clone reported success but '$NEW_NAME' is not registered"
+
+CONFIG="$DOCS/$NEW_NAME.utm/config.plist"
+[ -f "$CONFIG" ] || die "cloned bundle has no config.plist at $CONFIG"
+
+# Every VM must be stopped before UTM is quit, not just the one being cloned.
+#
+# Quitting UTM tries to SUSPEND anything still running, and suspend fails outright with an
+# emulated NVMe disk — which ours is. The result is a modal dialog ("Failed to save suspend
+# state ... Quitting UTM will kill all running VMs") that blocks the script and, if dismissed
+# with OK, takes down every running worker. Found by running this script while a second worker
+# was serving.
+say "stopping every running VM before quitting UTM (suspend fails on NVMe, and quitting kills running VMs)"
+for uuid in $(utmctl list | awk 'NR > 1 && $2 != "stopped" { print $1 }'); do
+  utmctl stop "$uuid" --request >/dev/null 2>&1 || true
+done
+for _ in $(seq 1 40); do pgrep -f QEMULauncher >/dev/null || break; sleep 3; done
+for uuid in $(utmctl list | awk 'NR > 1 && $2 != "stopped" { print $1 }'); do
+  utmctl stop "$uuid" >/dev/null 2>&1 || true
+done
+for _ in $(seq 1 10); do pgrep -f QEMULauncher >/dev/null || break; sleep 2; done
+pgrep -f QEMULauncher >/dev/null && die "a VM is still running; stop it by hand before re-running"
+
+say "quitting UTM so the config edit is not overwritten from its cache"
+osascript -e 'tell application "UTM" to quit' 2>/dev/null || true
+for _ in $(seq 1 10); do pgrep -x UTM >/dev/null || break; sleep 2; done
+
+# Locally administered, unicast: first octet 0x52 has bit 1 set (local) and bit 0 clear
+# (unicast), so it cannot collide with a real vendor's allocation.
+NEW_MAC="$(python3 -c "
+import random
+print(':'.join(['52'] + ['%02X' % random.randint(0, 255) for _ in range(5)]))")"
+cp "$CONFIG" "$CONFIG.bak"
+plutil -replace Network.0.MacAddress -string "$NEW_MAC" "$CONFIG" \
+  || die "could not set the MAC; the original config is at $CONFIG.bak"
+READBACK="$(plutil -extract Network.0.MacAddress raw "$CONFIG")"
+[ "$READBACK" = "$NEW_MAC" ] || die "MAC did not take (read back '$READBACK'); config backed up at $CONFIG.bak"
+say "new MAC $NEW_MAC (source keeps its own)"
+
+open -a UTM
+for _ in $(seq 1 15); do sleep 2; utmctl list >/dev/null 2>&1 && break; done
+# #635: without this, a UTM that never becomes responsive falls straight through into the loop below,
+# whose `utmctl list` would fail again, iterate zero names, and let the script finish having started
+# nothing -- with no error anywhere. Refuse instead.
+utmctl list >/dev/null 2>&1 || die "UTM did not become responsive after relaunch"
+
+# Start the source first. Both guests carry the same Windows machine identity, and letting one
+# settle before the other avoids two identical hostnames racing for the same DHCP server.
+for name in $(utmctl list | awk -v n="$SOURCE_NAME" 'NR > 1 && $3 ~ "^"n { print $3 }' | sort -u); do
+  uuid="$(uuid_of "$name")"
+  say "starting '$name'"
+  utmctl start "$uuid" >/dev/null
+  waited=0
+  ip=""
+  while [ "$waited" -lt "$BOOT_TIMEOUT_S" ]; do
+    sleep 10; waited=$((waited + 10))
+    # Ignore link-local: a guest reports 169.254.x.x while DHCP is still pending, and that
+    # reads as a failure when it is just "not yet".
+    ip="$(utmctl ip-address "$uuid" 2>/dev/null | grep -oE '^[0-9.]+' | grep -v '^127' | grep -v '^169\.254' | head -1 || true)"
+    [ -n "$ip" ] && break
+  done
+  [ -n "$ip" ] || die "'$name' never got a DHCP lease in ${BOOT_TIMEOUT_S}s. Check its MAC is unique: plutil -extract Network.0.MacAddress raw '$DOCS/$name.utm/config.plist'"
+  health=""
+  while [ "$waited" -lt "$BOOT_TIMEOUT_S" ]; do
+    health="$(curl -s -m 5 "http://$ip:$PORT/health" 2>/dev/null || true)"
+    [ -n "$health" ] && break
+    sleep 10; waited=$((waited + 10))
+  done
+  say "  $name  $ip  ${health:-NOT ANSWERING /health yet}"
+done
+
+echo
+say "pool:"
+./"$(dirname "$0")/worker-ctl.sh" pool 2>/dev/null || echo "  (run npm run worker:ctl -- pool)"