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

package/src/local-worker/create-utm-vm.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# Create the NVDA worker VM in UTM, fully from the CLI. No GUI clicking.
+#
+#   ./packages/worker-fleet/src/local-worker/create-utm-vm.sh <windows-arm64.iso> [support.iso]
+#
+# Why UTM rather than plain QEMU: homebrew QEMU + HVF cannot boot Windows 11 ARM64 on
+# Apple Silicon (open upstream bug, https://gitlab.com/qemu-project/qemu/-/issues/2893,
+# reproduced here across five machine configurations). UTM ships a QEMU patched for
+# Windows-on-ARM, but it is a dlopen'd framework, not an executable, so it cannot be
+# driven from a shell.
+#
+# The way in is UTM's scripting interface, which DOES support creation even though
+# `utmctl` has no `create` subcommand:
+#     make new virtual machine with properties {backend:qemu, configuration:{...}}
+# (see /Applications/UTM.app/Contents/Resources/UTM.sdef -- the `make` command takes a
+# `qemu configuration` record).
+set -euo pipefail
+
+# architecture-audit.md §8: creates 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: create-utm-vm.sh creates 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:-}"
+SUPPORT_ISO="${2:-$HOME/a11y-worker-vm/support.iso}"
+VM_NAME="${A11Y_VM_NAME:-a11y-worker}"
+# 4 GB: the documented Windows 11 minimum, and measured sufficient. Driving Edge and NVDA is
+# not memory-intensive. Verified by running the same 10 cases on 4 GB and 8 GB VMs -- 165s vs
+# 167s, byte-identical evidence (62 phrases, 51 role words, 22 heading-levels), and ZERO
+# pagefile use on either guest, so nothing is being paged to fake the result.
+#
+# Do not size this from Windows' "in use" figure: that includes the file cache, which grows to
+# fill whatever it is given. An 8 GB guest reported 3.5 GB "in use" and needed less than half
+# of it. Committed bytes is the number that means anything.
+RAM_MB="${A11Y_VM_RAM_MB:-4096}"
+CPUS="${A11Y_VM_CPUS:-4}"
+DISK_MB="${A11Y_VM_DISK_MB:-65536}"
+
+die() { echo "error: $*" >&2; exit 1; }
+info() { echo "==> $*"; }
+
+[ -n "$WIN_ISO" ] || die "usage: $0 <windows-arm64.iso> [support.iso]"
+[ -f "$WIN_ISO" ] || die "not found: $WIN_ISO"
+[ -f "$SUPPORT_ISO" ] || die "support ISO not found: $SUPPORT_ISO (run build-vm.sh first)"
+[ -d /Applications/UTM.app ] || die "UTM not installed: brew install --cask utm"
+
+DOCS="$HOME/Library/Containers/com.utmapp.UTM/Data/Documents"
+BUNDLE="$DOCS/$VM_NAME.utm"
+[ -e "$BUNDLE" ] && die "$BUNDLE already exists. Remove it first: utmctl delete $VM_NAME"
+
+# Refuse to create a SECOND registration with this name. Two registrations end up pointing
+# at the same $VM_NAME.utm bundle, and then `utmctl delete` on EITHER of them removes that
+# shared directory -- taking the other VM's disk and UEFI vars with it. That is not a
+# name-resolution problem you can dodge by using UUIDs: it destroyed a fully provisioned
+# worker here, and the only symptom afterwards is a start failing with
+# 'The file "edk2-arm-vars.fd" doesn't exist'.
+EXISTING_REG="$(utmctl list 2>/dev/null | awk -v n="$VM_NAME" '$3 == n { print $1 }' || true)"
+if [ -n "$EXISTING_REG" ]; then
+  # Note we only get here when the bundle is ALREADY gone (checked just above), so this is
+  # an orphaned registration -- and `utmctl delete` on one of those fails with -2700 and
+  # leaves the entry behind. Editing UTM's registry is the route that works.
+  die "UTM already has a VM registered as '$VM_NAME', but its bundle is gone:
+$EXISTING_REG
+Clear the stale registration first -- see 'Never utmctl delete a VM whose name appears
+twice' in docs/local-worker-vm.md for the PlistBuddy recipe. Do NOT use 'utmctl delete':
+registrations sharing a name share one bundle, so it can destroy a working VM's disk.
+Or pass A11Y_VM_NAME=<other> to build alongside the existing one."
+fi
+
+# UTM is sandboxed and will not follow a symlink out to /private/tmp, so give it real
+# files in the user's home.
+STAGE="$HOME/a11y-worker-vm"
+mkdir -p "$STAGE"
+if [ "$(cd "$(dirname "$WIN_ISO")" && pwd)/$(basename "$WIN_ISO")" != "$STAGE/windows.iso" ]; then
+  info "Staging the Windows ISO into $STAGE (UTM's sandbox cannot read /private/tmp)"
+  cp "$WIN_ISO" "$STAGE/windows.iso"
+fi
+[ -f "$STAGE/support.iso" ] || cp "$SUPPORT_ISO" "$STAGE/support.iso"
+
+info "Launching UTM"
+open -a UTM
+for _ in $(seq 1 20); do pgrep -x UTM >/dev/null && break; sleep 1; done
+pgrep -x UTM >/dev/null || die "UTM did not start"
+sleep 3
+
+info "Creating the VM via UTM's scripting interface"
+# Three things here are load-bearing and were each found the hard way:
+#
+# 1. `displays` is NOT optional. Omit it and UTM builds the VM with no graphics adapter
+#    at all (`-vga none -nographic` in the launch line); Windows Setup cannot run
+#    without a framebuffer and the guest just sits there. virtio-ramfb is a plain UEFI
+#    framebuffer, which is what you want: Windows 11 ARM64 has no inbox virtio-gpu
+#    driver, and UTM disables the viogpu guest driver anyway (it causes a black screen).
+#
+# 2. DRIVE ORDER IS BOOT ORDER, and the SYSTEM DISK MUST COME FIRST. UTM assigns
+#    `bootindex` by position. Firmware skips the empty disk (no bootloader on it yet),
+#    boots the ISO, installs -- and then, crucially, Setup REBOOTS. If the ISO were
+#    first, that reboot starts the installer again from scratch, forever. With the disk
+#    first, the reboot finds the freshly written bootloader and Setup continues into its
+#    specialize/oobeSystem phases.
+#
+#    Do not "fix" a boot failure by moving the ISO first: if firmware drops to the EDK2
+#    UEFI Shell with the disk first, the real cause is that the ISO has no valid UEFI
+#    El Torito record (see fetch-windows-iso.sh), not the ordering.
+#
+# 3. Do not try to drive that shell with `input keystroke`: it routes through the SPICE
+#    guest agent, which does not exist in UEFI, so the text silently never arrives
+#    (`input scan code` does reach the hardware, and is the only way to send keys before
+#    an OS is installed).
+VM_ID="$(osascript <<APPLESCRIPT
+tell application "UTM"
+  set vm to make new virtual machine with properties {backend:qemu, configuration:{name:"$VM_NAME", architecture:"aarch64", machine:"virt", memory:$RAM_MB, cpu cores:$CPUS, hypervisor:true, uefi:true, displays:{{hardware:"virtio-ramfb"}}, network interfaces:{{mode:shared}}, drives:{{guest size:$DISK_MB, interface:NVMe}, {source:POSIX file "$STAGE/windows.iso", interface:USB}, {source:POSIX file "$STAGE/support.iso", interface:USB}}}}
+  return id of vm
+end tell
+APPLESCRIPT
+)"
+[ -n "$VM_ID" ] || die "VM creation returned no id"
+info "created $VM_NAME ($VM_ID)"
+
+# UTM's scripting layer imports an ISO given as `source` by CONVERTING it to a qcow2
+# and attaching it as a fixed Disk -- and `removable` is read-only in the sdef, so this
+# cannot be expressed at creation time. Windows Setup will not read autounattend.xml off
+# a fixed disk, and the windowsPE driver injection depends on that medium, so rewrite
+# the two entries as real read-only CDs. UTM caches configs in memory, hence the quit.
+#
+# Keep such edits to values of keys UTM already wrote. UTM decodes config.plist with
+# strict Swift Codable: one unexpected value and the VM silently DISAPPEARS from
+# `utmctl list` with no error anywhere. (Learned by writing lowercase "linear" where UTM
+# writes "Linear" for a display filter.) Anything structural should go through the
+# scripting interface instead, which validates and fills defaults.
+info "Rewriting the ISO drives as CD-ROMs (not expressible via scripting)"
+osascript -e 'tell application "UTM" to quit' >/dev/null 2>&1 || true
+for _ in $(seq 1 20); do pgrep -x UTM >/dev/null || break; sleep 1; done
+# #635: the loop above exits EITHER because UTM quit OR because 20s ran out -- and the edit below only
+# survives if UTM is actually gone (it caches config.plist in memory and would overwrite the edit on its
+# own next flush). Refuse rather than silently proceeding into an edit that would be lost.
+pgrep -x UTM >/dev/null && die "UTM did not quit; the config.plist edit below would be lost to its cache"
+sleep 2
+
+cp "$STAGE/windows.iso" "$BUNDLE/Data/windows.iso"
+cp "$STAGE/support.iso" "$BUNDLE/Data/support.iso"
+python3 - "$BUNDLE/config.plist" <<'PY'
+import plistlib, sys
+p = sys.argv[1]
+d = plistlib.load(open(p, 'rb'))
+for drive in d['Drive']:
+    name = drive.get('ImageName', '')
+    if name.startswith('windows'):
+        drive.update(ImageName='windows.iso', ImageType='CD', ReadOnly=True)
+    elif name.startswith('support'):
+        drive.update(ImageName='support.iso', ImageType='CD', ReadOnly=True)
+plistlib.dump(d, open(p, 'wb'))
+for drive in d['Drive']:
+    print("    %-12s %-6s %s" % (drive['ImageType'], drive['Interface'], drive['ImageName']))
+PY
+# Reclaim the qcow2 copies UTM made of both ISOs (~4.5 GB).
+rm -f "$BUNDLE/Data/windows.qcow2" "$BUNDLE/Data/support.qcow2"
+
+info "Starting the VM (Windows installs unattended from support.iso)"
+open -a UTM
+for _ in $(seq 1 20); do pgrep -x UTM >/dev/null && break; sleep 1; done
+# #635: without this, a UTM that never relaunches falls straight through into `utmctl start`, which
+# (per this file's own documented quirks) may report a misleading `unknown` state instead of a clear
+# failure -- die here, with the actual cause, instead.
+pgrep -x UTM >/dev/null || die "UTM did not relaunch before starting the VM"
+sleep 3
+# Operate by UUID, never by name. If two registrations ever share a name, `utmctl start
+# <name>` silently picks the wrong one -- and `utmctl delete <name>` will remove the
+# SHARED bundle directory, destroying the other VM's disk with it.
+utmctl start "$VM_ID"
+utmctl status "$VM_ID"
+
+DISK="$(ls "$BUNDLE/Data"/*.qcow2 | head -1)"
+cat <<EOF
+
+--- $VM_NAME started ---
+
+The install is unattended. There is no console screenshot from the CLI, so track it by
+side effect -- Windows only writes to the system disk once Setup is really running:
+
+    watch: du -h "$DISK"
+    (WinPE decompresses boot.wim into RAM first, so expect a few minutes at 0 growth)
+
+When it is up:
+    utmctl query ip $VM_ID            # needs qemu-ga, installed at first logon
+    curl http://<guest-ip>:8765/health
+    A11Y_WORKER=http://<guest-ip>:8765 npm run witness -- https://example.com --task "..."
+
+Guest commands without SSH (qemu-ga, via UTM):
+    utmctl exec $VM_ID --cmd "powershell -Command Get-Process node"
+
+Troubleshooting the worker itself: docs/nvda-worker-runbook.md
+EOF

package/src/local-worker/fetch-windows-iso.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# Build an official Windows 11 ARM64 ISO on macOS, from the CLI.
+#
+#   ./packages/worker-fleet/src/local-worker/fetch-windows-iso.sh [outdir]
+#
+# Microsoft's ARM64 ISO download is a session-token web flow that does not script
+# cleanly, so this uses UUP dump: it fetches the same Unified Update Platform packages
+# from Microsoft's update servers and assembles them locally. The bits are official;
+# the assembly is local.
+#
+# The conversion needs five tools. Four are in homebrew-core. `chntpw` is NOT, and the
+# only convenient macOS build is the universal one inside CrystalFetch.app -- which is
+# signed against that bundle, so invoking it directly dies with SIGTRAP (exit 133)
+# unless the bundle's OpenSSL.framework is on the framework path. Hence the shim below.
+set -euo pipefail
+
+# architecture-audit.md §8: builds an ISO for a local UTM worker VM, which is deprecated -- "The UTM is
+# deprecated, that was a testing thing." (repository owner, 2026-09-05). Bare-metal boxes install via
+# PXE/autounattend.xml instead — see packages/worker-fleet/src/provisioning/bare-metal/.
+echo "DEPRECATED: fetch-windows-iso.sh feeds a local UTM worker VM build. 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
+
+OUT_DIR="${1:-$HOME/a11y-worker-vm/iso-build}"
+EDITION="${A11Y_WIN_EDITION:-professional}"
+LANG_CODE="${A11Y_WIN_LANG:-en-us}"
+
+# Default to 23H2, NOT the newest build. Windows 11 24H2 replaced Setup with one that
+# calls SetupPrep.exe, is far stricter about autounattend.xml, and frequently ignores it
+# outright -- we saw the install boot fine and then stop dead on the language/region
+# prompt, which is the symptom widely reported by others. 23H2 uses the classic Setup and
+# honours the unattend file. Override with A11Y_WIN_VERSION if you want to retest 24H2.
+WIN_VERSION="${A11Y_WIN_VERSION:-23H2}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+die() { echo "error: $*" >&2; exit 1; }
+info() { echo "==> $*"; }
+
+command -v brew >/dev/null || die "homebrew required"
+
+info "Installing conversion tools"
+for f in aria2 cabextract wimlib cdrtools; do
+  brew list --formula "$f" >/dev/null 2>&1 || brew install "$f"
+done
+
+CF_BIN="/Applications/CrystalFetch.app/Contents/MacOS/chntpw"
+CF_FW="/Applications/CrystalFetch.app/Contents/Frameworks"
+if [ ! -x "$CF_BIN" ]; then
+  info "chntpw not found; installing CrystalFetch (it bundles a universal build)"
+  brew install --cask crystalfetch
+fi
+[ -x "$CF_BIN" ] || die "chntpw unavailable and CrystalFetch install failed"
+
+SHIM_DIR="$OUT_DIR/.tools"
+mkdir -p "$SHIM_DIR"
+cat > "$SHIM_DIR/chntpw" <<SHIM
+#!/bin/bash
+exec env DYLD_FRAMEWORK_PATH="$CF_FW" "$CF_BIN" "\$@"
+SHIM
+chmod +x "$SHIM_DIR/chntpw"
+export PATH="$SHIM_DIR:$PATH"
+
+for t in aria2c cabextract wimlib-imagex chntpw mkisofs; do
+  command -v "$t" >/dev/null || die "missing tool: $t"
+done
+info "toolchain ready"
+
+info "Finding the newest RETAIL Windows 11 ARM64 build for $WIN_VERSION"
+# The listing includes Insider Preview builds; filter to released versions so the worker
+# is not sitting on a preview OS. Titles look like "Windows 11, version 23H2".
+UUID="$(curl -sL --fail "https://api.uupdump.net/listid.php?search=windows%2011&sortByDate=1" \
+  | WANT="$WIN_VERSION" node -e '
+    let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{
+      const want = (process.env.WANT || "").toLowerCase();
+      const builds = JSON.parse(s)?.response?.builds || {};
+      const rows = Object.values(builds).filter(b =>
+        /arm64/i.test(b.arch || "") &&
+        /^Windows 11, version/i.test(b.title || "") &&
+        (b.title || "").toLowerCase().includes("version " + want));
+      if (!rows.length) { process.exit(1); }
+      console.log(rows[0].uuid);
+    });')"
+[ -n "$UUID" ] || die "could not find a retail Windows 11 ARM64 $WIN_VERSION build"
+info "build uuid: $UUID"
+
+mkdir -p "$OUT_DIR"
+cd "$OUT_DIR"
+
+# Idempotence: if a finished ISO with a UEFI boot record is already here, stop. And if the
+# converter's output is present, skip straight to the rebuild rather than re-downloading
+# ~10 GB. Re-running this script should cost minutes, not an hour.
+EXISTING="$(ls -t "$OUT_DIR"/*.ISO "$OUT_DIR"/*.iso 2>/dev/null | grep -vi support | head -1 || true)"
+if [ -n "$EXISTING" ] && xorriso -indev "$EXISTING" -report_el_torito plain 2>/dev/null | grep -q UEFI; then
+  echo "ISO ready (already built): $EXISTING"
+  echo "Next:  ./packages/worker-fleet/src/local-worker/create-utm-vm.sh \"$EXISTING\""
+  exit 0
+fi
+if [ -n "$EXISTING" ]; then
+  info "found an existing converter ISO; skipping download and going straight to the rebuild"
+  SKIP_DOWNLOAD=1
+fi
+
+info "Fetching the UUP download+convert pack"
+# autodl=2 is "download using aria2 and convert". autodl=3 is the virtual-editions
+# flow and errors out unless you request extra editions.
+curl -sL --fail -o pack.zip \
+  "https://uupdump.net/get.php?id=${UUID}&pack=${LANG_CODE}&edition=${EDITION}&autodl=2"
+unzip -o -q pack.zip
+chmod +x uup_download_macos.sh
+
+# Soften aria2's fan-out before running it. The stock script uses -x16 -s16 across many
+# hosts, which overwhelmed a resolver mid-download here: 42 x errorCode=19 ("Name
+# resolution ... failed") and the run aborted twice with ~7 GB still to fetch. Fewer
+# connections plus explicit resolvers and unlimited retries turns a DNS blip into a pause
+# instead of a failure. Costs nothing on a healthy link; rescues a flaky one.
+GENTLE='-x4 -s4 -j2 --async-dns-server=1.1.1.1,8.8.8.8,9.9.9.9 --max-tries=0 --retry-wait=5 --connect-timeout=30 --timeout=60'
+sed -i '' "s/-x16 -s16 -j5/$GENTLE/; s/-x16 -s16 -j2/$GENTLE/" uup_download_macos.sh
+grep -q 'async-dns-server' uup_download_macos.sh && info "aria2 settings softened for flaky links"
+
+if [ "${SKIP_DOWNLOAD:-0}" = "1" ]; then
+  info "skipping download/convert (existing ISO found)"
+else
+  info "Downloading (~10 GB) and converting. This is the slow part."
+  # aria2 resumes, so re-running after an interruption picks up where it left off.
+  ./uup_download_macos.sh
+fi
+
+ISO="$(ls -t "$OUT_DIR"/*.ISO "$OUT_DIR"/*.iso 2>/dev/null | grep -vi 'support\|fixed' | head -1 || true)"
+[ -n "$ISO" ] || die "conversion finished but no ISO was produced (see the log in $OUT_DIR)"
+info "converter produced: $ISO"
+
+# ---------------------------------------------------------------------------
+# The converter's ISO is NOT UEFI-bootable. Its arm64 branch runs
+#     mkisofs -b efi/microsoft/boot/efisys.bin --no-emul-boot ...
+# and `-b` registers a BIOS boot image (platform 0x00). A UEFI entry needs platform
+# 0xEF, so firmware finds no bootable UEFI record, silently declines the disc, and drops
+# to the EDK2 UEFI Shell -- which looks exactly like a hung VM. Confirm with:
+#     xorriso -indev <iso> -report_el_torito plain     # want "Pltf: UEFI", not BIOS
+#
+# While rebuilding we also swap efisys.bin for efisys_noprompt.bin. The default image
+# stops at "Press any key to boot from CD or DVD" and gives up if nobody presses one,
+# which is fatal for an unattended install.
+#
+# NOTE: xorriso cannot do this job -- `xorriso -as mkisofs` rejects `-udf`, and UDF is
+# required because install.wim exceeds 4 GB. cdrtools mkisofs supports both --udf and
+# -eltorito-platform, so it is the builder here.
+if xorriso -indev "$ISO" -report_el_torito plain 2>/dev/null | grep -q "UEFI"; then
+  info "ISO already has a UEFI El Torito record; leaving it alone"
+else
+  info "Rebuilding the ISO with a UEFI El Torito record (the converter's is BIOS-only)"
+  STAGE_DIR="$OUT_DIR/isodir"
+  MNT="$OUT_DIR/mnt"
+  # ditto preserves the ISO's read-only bits, so a previous staging tree cannot be
+  # removed (or modified) without restoring write permission first -- otherwise a re-run
+  # dies on "rm: ...: Permission denied" and leaves a half-deleted tree behind.
+  [ -d "$STAGE_DIR" ] && chmod -R u+w "$STAGE_DIR" 2>/dev/null || true
+  rm -rf "$STAGE_DIR" "$MNT"; mkdir -p "$STAGE_DIR" "$MNT"
+  # Must copy via a macOS UDF mount: the converter passes `--hide "*"`, so every file
+  # lives ONLY in the UDF tree and an ISO9660 reader (including xorriso) sees an empty
+  # disc. boot.catalog is unreadable and is regenerated by mkisofs anyway.
+  hdiutil attach -readonly -nobrowse -mountpoint "$MNT" "$ISO" >/dev/null
+  ditto --norsrc --noextattr "$MNT" "$STAGE_DIR" 2>/dev/null || true
+  hdiutil detach "$MNT" >/dev/null
+  rmdir "$MNT" 2>/dev/null || true
+  # Same reason: the staged copy is read-only, and we need to write autounattend.xml into
+  # it and update boot.wim.
+  chmod -R u+w "$STAGE_DIR"
+  [ -f "$STAGE_DIR/sources/boot.wim" ] || die "extraction failed (no sources/boot.wim)"
+
+  UNATTEND="$SCRIPT_DIR/autounattend.xml"
+
+  # GUARD 1: language must match the media. The answer file's SetupUILanguage/UILanguage
+  # must name a language pack that actually exists in sources/. Ask for en-GB on an EN-US
+  # disc and Setup cannot load its UI language, silently abandons the whole answer file,
+  # and shows the interactive language prompt -- indistinguishable from "file not found".
+  # This one cost hours; it is two lines to check.
+  MEDIA_LANG="$(ls "$STAGE_DIR/sources" | grep -oiE '^[a-z]{2}-[a-z]{2}$' | head -1)"
+  [ -n "$MEDIA_LANG" ] || die "could not determine the media language from sources/"
+  WANTED_LANGS="$(grep -oE '<(SetupUILanguage>)?[[:space:]]*<?UILanguage>[a-zA-Z-]+' "$UNATTEND" \
+    | grep -oE '[a-z]{2}-[A-Z]{2}' | sort -u | tr '\n' ' ')"
+  for l in $WANTED_LANGS; do
+    if [ "$(echo "$l" | tr 'A-Z' 'a-z')" != "$(echo "$MEDIA_LANG" | tr 'A-Z' 'a-z')" ]; then
+      die "autounattend.xml asks for UI language '$l' but the media only has '$MEDIA_LANG'. Setup will ignore the answer file. Fix the locales in $UNATTEND."
+    fi
+  done
+  info "language check: unattend wants [$WANTED_LANGS], media has [$MEDIA_LANG]"
+
+  # GUARD 2: the image name must match the WIM's NAME (not its DESCRIPTION). Getting this
+  # wrong does not break the answer file -- Setup just stops on the edition picker.
+  if command -v wimlib-imagex >/dev/null; then
+    WIM_NAME="$(wimlib-imagex info "$STAGE_DIR/sources/install.wim" 2>/dev/null \
+      | awk -F': *' '/^Name:/{print $2; exit}')"
+    WANT_NAME="$(grep -A2 'IMAGE/NAME' "$UNATTEND" | grep -oE '<Value>[^<]+' | sed 's/<Value>//' | head -1)"
+    if [ -n "$WIM_NAME" ] && [ -n "$WANT_NAME" ] && [ "$WIM_NAME" != "$WANT_NAME" ]; then
+      die "autounattend.xml installs image '$WANT_NAME' but the WIM's Name is '$WIM_NAME' (its Description may differ). Fix /IMAGE/NAME in $UNATTEND."
+    fi
+    info "image check: unattend wants '$WANT_NAME', WIM Name is '$WIM_NAME'"
+  fi
+
+  # autounattend.xml belongs on the ROOT OF THE INSTALL MEDIA, which is where Setup
+  # looks first. It is also on the support ISO; both is harmless and more robust.
+  cp "$UNATTEND" "$STAGE_DIR/autounattend.xml"
+
+  # Belt and braces: also inject it into boot.wim's Setup image at \Windows\Panther,
+  # which Setup reads explicitly. Removable-media discovery is not guaranteed when the
+  # disc is presented as USB mass storage rather than a real DVD, as it is here.
+  if command -v wimlib-imagex >/dev/null; then
+    chmod u+w "$STAGE_DIR/sources/boot.wim"
+    printf 'delete --force /Windows/Panther/unattend.xml\nadd "%s" /Windows/Panther/unattend.xml\n' \
+      "$UNATTEND" | wimlib-imagex update "$STAGE_DIR/sources/boot.wim" 2 >/dev/null 2>&1 \
+      && info "injected unattend into boot.wim (index 2, Windows Setup)"
+  fi
+
+  FIXED="$OUT_DIR/windows-arm64-uefi.iso"
+  LABEL="$(basename "$ISO" | sed 's/\.[Ii][Ss][Oo]$//' | cut -c1-32)"
+  rm -f "$FIXED"
+  mkisofs -eltorito-platform efi -b "efi/microsoft/boot/efisys_noprompt.bin" \
+    --no-emul-boot --udf -iso-level 3 --hide "*" -V "$LABEL" -o "$FIXED" "$STAGE_DIR"
+  xorriso -indev "$FIXED" -report_el_torito plain 2>/dev/null | grep -q "UEFI" \
+    || die "rebuild still has no UEFI El Torito record"
+  chmod -R u+w "$STAGE_DIR" 2>/dev/null || true
+  rm -rf "$STAGE_DIR"
+  ISO="$FIXED"
+  info "rebuilt: $ISO"
+fi
+
+echo
+echo "ISO ready: $ISO"
+echo "Next:  ./packages/worker-fleet/src/local-worker/build-vm.sh \"$ISO\""
+echo "       ./packages/worker-fleet/src/local-worker/create-utm-vm.sh \"$ISO\""

package/src/local-worker/first-boot.cmd

@@ -0,0 +1,58 @@
+@echo off
+rem Runs from the support ISO at first logon (invoked by autounattend.xml).
+rem
+rem Its only job: get an ELEVATED shell without a UAC prompt, then run the worker
+rem bootstrap. A UAC prompt here would be fatal -- it renders on the secure desktop,
+rem which no automation can click and NVDA cannot read.
+setlocal EnableDelayedExpansion
+set "LOG=C:\a11y-first-boot.log"
+echo [%DATE% %TIME%] first-boot starting from %~dp0 > "%LOG%"
+
+rem The NetKVM driver was injected during windowsPE so the NIC exists, but DHCP may
+rem not have finished by first logon. The bootstrap needs the network for winget.
+set NET=0
+for /L %%i in (1,1,60) do (
+  if !NET!==0 (
+    ping -n 1 -w 1000 8.8.8.8 >nul 2>&1 && set NET=1
+    if !NET!==0 timeout /t 2 /nobreak >nul
+  )
+)
+if !NET!==1 (echo [%DATE% %TIME%] network up >> "%LOG%") else (echo [%DATE% %TIME%] WARNING: no network after ~120s >> "%LOG%")
+
+rem Copy off the read-only ISO so it survives the ISO being detached after install.
+copy /y "%~dp0bootstrap-windows-worker.ps1" C:\bootstrap-windows-worker.ps1 >> "%LOG%" 2>&1
+
+rem The operator's PUBLIC SSH key, if one was staged beside this file. This is what turns
+rem "one console visit per box" into "none": bootstrap installs it into
+rem administrators_authorized_keys with the ACL sshd insists on, and the machine is then
+rem reachable by Ansible from the moment it finishes.
+rem
+rem Staged at ISO-build time rather than committed. A public key is not a secret, but it IS
+rem specific to whoever runs this fleet, and a checked-in one would silently grant access to
+rem whoever happened to be in the repo -- which is a worse default than asking.
+rem
+rem Copied to a FILE rather than exported as an environment variable. The fallback path below runs
+rem the bootstrap through a scheduled task, which starts a fresh session and inherits nothing from
+rem here -- so an exported variable would work on the elevated path and silently vanish on the other,
+rem which is the kind of "works when I tested it" difference this project keeps paying for.
+if exist "%~dp0operator-key.pub" (
+  if not exist "C:\ProgramData\a11y-witness" mkdir "C:\ProgramData\a11y-witness" >> "%LOG%" 2>&1
+  copy /y "%~dp0operator-key.pub" "C:\ProgramData\a11y-witness\operator-key.pub" >> "%LOG%" 2>&1
+  echo [%DATE% %TIME%] operator key staged from the install media >> "%LOG%"
+) else (
+  echo [%DATE% %TIME%] no operator-key.pub beside this script; this box will need one console >> "%LOG%"
+  echo [%DATE% %TIME%]   visit, or "ansible-playbook ssh-key.yml" once it is reachable >> "%LOG%"
+)
+
+rem FirstLogonCommands usually run elevated, but that is not guaranteed. Try inline
+rem first; fall back to a RunLevel Highest scheduled task, which elevates silently.
+powershell -NoProfile -ExecutionPolicy Bypass -Command ^
+ "$e=(New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())).IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator);" ^
+ "if ($e) { Write-Output 'already elevated; running inline'; & powershell -NoProfile -ExecutionPolicy Bypass -File C:\bootstrap-windows-worker.ps1 }" ^
+ "else { Write-Output 'not elevated; via RunLevel Highest task';" ^
+ "  $a=New-ScheduledTaskAction -Execute 'powershell' -Argument '-NoProfile -ExecutionPolicy Bypass -File C:\bootstrap-windows-worker.ps1';" ^
+ "  $p=New-ScheduledTaskPrincipal -UserId ([Security.Principal.WindowsIdentity]::GetCurrent().Name) -LogonType Interactive -RunLevel Highest;" ^
+ "  Register-ScheduledTask -TaskName 'a11y-firstboot' -Action $a -Principal $p -Force | Out-Null;" ^
+ "  Start-ScheduledTask -TaskName 'a11y-firstboot' }" >> "%LOG%" 2>&1
+
+echo [%DATE% %TIME%] first-boot finished >> "%LOG%"