Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
Add maintainer-run Lume macOS GUI E2E gate (#2248)
Francesco Bonaccia6115411554b
diff --git a/.github/scripts/tests/test_cua_driver_release_wiring.py b/.github/scripts/tests/test_cua_driver_release_wiring.pyindex c7dfc69442..68f33ac69e 100644--- a/.github/scripts/tests/test_cua_driver_release_wiring.py+++ b/.github/scripts/tests/test_cua_driver_release_wiring.py@@ -57,7 +57,9 @@ class TestCuaDriverReleaseWiring(unittest.TestCase):self.assertIn('["libs/cua-driver/rust/"]="cua-driver-rs"', workflow)self.assertIn("cua-driver desktop release validation", workflow)self.assertIn("e2e-rust-windows.yml", workflow)- self.assertIn("scripts/ci/macos/run-rust-e2e.sh", workflow)+ self.assertIn(+ "libs/cua-driver/tests/runners/macos-lume/run-all.sh", workflow+ )self.assertIn("e2e-rust-linux.yml", workflow)self.assertIn("e2e-rust-linux-wayland.yml", workflow)diff --git a/.github/workflows/ci-release-reminder.yml b/.github/workflows/ci-release-reminder.ymlindex c52735ba24..953a4ed802 100644--- a/.github/workflows/ci-release-reminder.yml+++ b/.github/workflows/ci-release-reminder.yml@@ -115,7 +115,7 @@ jobs:BODY+="\n\n### cua-driver desktop release validation\n\n"BODY+="Before adding the release label, a maintainer records green runs on the exact release SHA:\n"BODY+="- [ ] [Windows canonical matrix](https://github.com/${REPO}/actions/workflows/e2e-rust-windows.yml)\n"- BODY+="- [ ] macOS logged-in host: \`scripts/ci/macos/run-rust-e2e.sh\`, with the typed summary attached to the PR\n"+ BODY+="- [ ] macOS Lume maintainer gate: \`libs/cua-driver/tests/runners/macos-lume/run-all.sh\`, with the typed summary attached to the PR\n"BODY+="- [ ] [Linux X11 canonical matrix](https://github.com/${REPO}/actions/workflows/e2e-rust-linux.yml)\n"BODY+="- [ ] [Linux Sway canonical matrix](https://github.com/${REPO}/actions/workflows/e2e-rust-linux-wayland.yml) with environment \`sway\`\n"BODY+="- [ ] Result links and remaining experimental environment gaps are recorded in the PR\n"diff --git a/docs/content/docs/concepts/how-cua-driver-is-validated.mdx b/docs/content/docs/concepts/how-cua-driver-is-validated.mdxindex 310c8dd3e7..6dedc418a1 100644--- a/docs/content/docs/concepts/how-cua-driver-is-validated.mdx+++ b/docs/content/docs/concepts/how-cua-driver-is-validated.mdx@@ -1,6 +1,6 @@----title: "How Cua Driver Is Validated"-description: "Why Cua Driver uses source-built desktop harnesses, independent application oracles, and retained evidence to validate behavior between releases."+title: 'How Cua Driver Is Validated'+description: 'Why Cua Driver uses source-built desktop harnesses, independent application oracles, and retained evidence to validate behavior between releases.'---# How Cua Driver Is Validated@@ -51,7 +51,7 @@ The Rust catalog records the dimensions that affect delivery:| Addressing | AX element or PX coordinate || Delivery | foreground or background || Scope | target window or full desktop |-| Surface | shared renderer, native toolkit, embedded web view, or compositor |+| Surface | shared renderer, native toolkit, embedded web view, or compositor || Expected result | delivered or one exact structured refusal |Foreground and background are dimensions of an action, not separate test@@ -81,10 +81,10 @@ desktop remains unchanged.## Evidence makes a result auditable-Canonical hosted GUI runs retain the typed result for every declared cell, the-source commit, per-cell desktop video, before and after state, the tool-trajectory, fixture journals, driver logs, and environment preflight. The-GitHub Actions summary links each matrix row to its artifacts.+Canonical GUI runs retain the typed result for every declared cell, the source+commit, per-cell desktop video, before and after state, the tool trajectory,+fixture journals, driver logs, and environment preflight. The reporter writes a+Markdown summary that links each matrix row to its retained evidence.The reporter rejects missing or duplicate rows, undeclared outcomes,contradictory results, and incomplete required evidence. A failed environment@@ -96,9 +96,11 @@ an observed effect remains a failure.Deterministic unit, protocol, compile, and packaging checks run automaticallywhere configured. Interactive E2E suites require a real graphical session andare maintainer-triggered because they are slower and more environment-sensitive.-Windows and Linux have dispatchable GitHub Actions workflows; macOS runs the-same Rust catalog in a logged-in session with Accessibility and Screen-Recording permissions.+Windows and Linux have dispatchable GitHub Actions workflows. A maintainer runs+macOS in a disposable clone of a stopped Lume seed with a logged-in Aqua+session, stable source-build signature, and inherited macOS consent. See [Run+Cua Driver macOS tests in a Lume+VM](/how-to-guides/driver/run-tests-in-macos-lume-vm) for that process.Each accepted run builds the driver and fixtures from one exact source commit.Support claims change only after an unchanged behavior cell produces new@@ -113,3 +115,6 @@ oracles, and command-return-only checks do not establish support.engineering work and hard platform boundaries.- [Interface contracts](/reference/cua-driver/contracts) defines public driverbehavior and refusal semantics.+- [Run Cua Driver macOS tests in a Lume+ VM](/how-to-guides/driver/run-tests-in-macos-lume-vm) describes the+ maintainer-owned macOS acceptance gate.diff --git a/docs/content/docs/how-to-guides/driver/meta.json b/docs/content/docs/how-to-guides/driver/meta.jsonindex 0d0735f10d..393a3db7bf 100644--- a/docs/content/docs/how-to-guides/driver/meta.json+++ b/docs/content/docs/how-to-guides/driver/meta.json@@ -1 +1,15 @@-{ "title": "Driver", "pages": ["install", "connect-your-agent", "drive-a-web-page", "keep-running", "restrict-tool-access", "personalize-cursor", "update", "windows-ssh"] }+{+ "title": "Driver",+ "pages": [+ "install",+ "run-in-macos-lume-vm",+ "run-tests-in-macos-lume-vm",+ "connect-your-agent",+ "drive-a-web-page",+ "keep-running",+ "restrict-tool-access",+ "personalize-cursor",+ "update",+ "windows-ssh"+ ]+}diff --git a/docs/content/docs/how-to-guides/driver/run-in-macos-lume-vm.mdx b/docs/content/docs/how-to-guides/driver/run-in-macos-lume-vm.mdxnew file mode 100644index 0000000000..5e7c549aaa--- /dev/null+++ b/docs/content/docs/how-to-guides/driver/run-in-macos-lume-vm.mdx@@ -0,0 +1,256 @@+---+title: Run Cua Driver in a macOS Lume VM+description: Pull the published Tahoe image, install Cua Driver, grant macOS consent, and connect an agent to the VM desktop.+---++import { Callout } from 'fumadocs-ui/components/callout';++This guide shows you how to run Cua Driver in a local macOS Tahoe VM on an+Apple Silicon host. It uses the published `macos-tahoe-cua:26.5.2` Lume image+so the operating system, Command Line Tools, login session, and SSH setup match+the maintainer test environment.++<Callout type="info">+ The published image has SIP disabled, but SIP does not grant Accessibility, Screen Recording,+ Automation, or direct-capture consent. Approve those requests through macOS in your private VM.+ Cua Driver also works with SIP enabled; this guide uses the SIP-disabled image to match the+ maintainer test base.+</Callout>++## Before you start++You need:++- an Apple Silicon Mac with [Lume installed](/how-to-guides/lume/install-lume)+ and `jq` available on the host;+- enough host space for a 150 GB sparse VM disk; and+- access to the VM display for the first-run macOS prompts.++Use the versioned image tag for repeatable work. Reserve `latest` for+experimentation.++## Pull and boot the VM++On the host, run:++```bash+IMAGE=macos-tahoe-cua:26.5.2+VM=cua-driver-dev-26.5.2++lume pull "$IMAGE" "$VM"+lume run "$VM"+```++Keep `lume run` open. The VM display should log in as `lume`; the initial+username and password are both `lume`.++Open Terminal in the VM and inspect the base:++```bash+sw_vers+csrutil status+xcode-select -p+xcrun swiftc --version+```++The published `26.5.2` image reports:++- macOS 26.5.2, build 25F84;+- `System Integrity Protection status: disabled.`; and+- `/Library/Developer/CommandLineTools` as the selected developer directory.++Stop if those values differ. Pull the versioned image again instead of+repairing an unknown base.++## Install Cua Driver in the VM++Run the release installer from Terminal in the VM display:++```bash+/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"+```++Verify the installed app and CLI:++```bash+/Users/lume/.local/bin/cua-driver --version+/Users/lume/.local/bin/cua-driver doctor+```++The installer puts the app at `/Applications/CuaDriver.app` and the CLI at+`/Users/lume/.local/bin/cua-driver`.++## Grant every macOS consent path++Request the app-owned Accessibility and Screen Recording grants:++```bash+/Users/lume/.local/bin/cua-driver permissions grant+```++Approve both requests for CuaDriver. Then trigger app enumeration:++```bash+/Users/lume/.local/bin/cua-driver list_apps '{}'+```++When macOS asks whether CuaDriver may control System Events, choose **Allow**.++Tahoe also asks separately whether CuaDriver may capture the screen and audio+without the system picker. Trigger that request with an actual desktop capture:++```bash+DRIVER=/Users/lume/.local/bin/cua-driver++"$DRIVER" call set_config '{"capture_scope":"desktop"}'+"$DRIVER" call get_desktop_state '{}' \+ > /tmp/cua-driver-desktop-state.json+"$DRIVER" call set_config '{"capture_scope":"window"}'+```++Choose **Allow** on the direct-capture prompt. Check that the command returned+a PNG:++```bash+/usr/bin/python3 - <<'PY'+import json++with open('/tmp/cua-driver-desktop-state.json') as source:+ state = json.load(source)++assert state['screenshot_mime_type'] == 'image/png'+assert state['screenshot_width'] > 0+assert state['screenshot_height'] > 0+assert state['screenshot_png_b64']+PY+```++Rerun `list_apps` and the capture commands. They must finish without another+prompt.++## Verify the driver-owned grants++Query the running daemon rather than Terminal's permission state:++```bash+/Users/lume/.local/bin/cua-driver permissions status --json \+ > /tmp/cua-driver-permissions.json++/usr/bin/python3 - <<'PY'+import json++with open('/tmp/cua-driver-permissions.json') as source:+ status = json.load(source)++assert status['accessibility'] is True+assert status['screen_recording'] is True+assert status['screen_recording_capturable'] is True+assert status['source']['attribution'] == 'driver-daemon'+PY+```++Exercise both the accessibility and capture paths:++```bash+/Users/lume/.local/bin/cua-driver call get_accessibility_tree '{}'+/Users/lume/.local/bin/cua-driver call set_config '{"capture_scope":"desktop"}'+/Users/lume/.local/bin/cua-driver call get_desktop_state '{}' \+ > /tmp/cua-driver-desktop-state-second.json+/Users/lume/.local/bin/cua-driver call set_config '{"capture_scope":"window"}'+```++The commands must succeed without opening System Settings or another consent+dialog.++## Connect an agent++### Run the agent inside the VM++Run the agent inside the VM when it needs to operate the VM desktop. Generate+the current registration command for your client:++```bash+/Users/lume/.local/bin/cua-driver mcp-config --client codex+/Users/lume/.local/bin/cua-driver mcp-config --client claude+```++Follow the printed command, then restart the client. See [Connect your agent to+Cua Driver](/how-to-guides/driver/connect-your-agent) for other supported+clients.++### Run the agent on the host++The host can expose the guest's MCP process over SSH. First, copy only your host+public key into the guest:++```bash+VM_IP="$(lume get "$VM" --format json | jq -r '.[0].ipAddress')"+cat ~/.ssh/id_ed25519.pub | \+ ssh "lume@${VM_IP}" \+ 'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'+```++Enter the initial `lume` password when asked. Verify that noninteractive SSH+reaches the app-owned daemon:++```bash+ssh -T -o BatchMode=yes "lume@${VM_IP}" \+ /Users/lume/.local/bin/cua-driver permissions status --json+```++Register that SSH command as a stdio MCP server in Codex:++```bash+codex mcp add cua-driver-vm -- \+ ssh -T -o BatchMode=yes "lume@${VM_IP}" \+ /Users/lume/.local/bin/cua-driver mcp+```++The remote CLI proxies to the CuaDriver daemon in the logged-in guest session,+so the daemon retains the app's macOS permission identity.++## Save a reusable private VM++Close applications, stop the VM, and clone it while stopped:++```bash+lume stop "$VM"+lume clone "$VM" "${VM}-backup"+lume ls+```++Keep private VMs local. Do not add registry tokens, source-control credentials,+maintainer SSH private keys, or personal files before cloning.++## Troubleshooting++### A permission is `unknown`++Start CuaDriver through LaunchServices and query it again:++```bash+open -n -g -a CuaDriver --args serve+cua-driver permissions status --json+```++`unknown` means no app-owned daemon answered the status request.++### A clone asks for permissions again++Confirm that `/Applications/CuaDriver.app` has the release signature. A source+build with an ad-hoc or changing signature gets a different TCC identity. Use+the release installer for ordinary VM use. Maintainers testing source builds+should follow [Run Cua Driver macOS tests in a Lume VM](/how-to-guides/driver/run-tests-in-macos-lume-vm),+which creates a stable local signing identity.++### Commands work over SSH but GUI behavior differs++Use Terminal in the VM display for initial consent and GUI tests. SSH is useful+for source sync and artifact retrieval, but it is not the foreground Aqua+session that owns the visible desktop.++## Related guides++- [Manage local Lume VMs](/how-to-guides/lume/manage-vms)+- [macOS permissions reference](/reference/cua-driver/macos-permissions)+- [Run Cua Driver macOS tests in a Lume VM](/how-to-guides/driver/run-tests-in-macos-lume-vm)diff --git a/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx b/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdxnew file mode 100644index 0000000000..a999a30569--- /dev/null+++ b/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx@@ -0,0 +1,387 @@+---+title: Run Cua Driver macOS tests in a Lume VM+description: Build a private Tahoe test seed, run the complete GUI E2E gate from a disposable Lume clone, and retain its evidence.+---++import { Callout } from 'fumadocs-ui/components/callout';++This guide shows maintainers how to run the canonical Cua Driver macOS GUI E2E+gate in Lume. Each accepted run installs one committed source revision in a+disposable clone, executes the complete Rust behavior catalog from the logged-in+VM display, and pulls the evidence back to the host.++<Callout type="info">+ This is a maintainer-dispatched gate. It does not run in a GitHub-hosted macOS GUI job. The+ repository contains the runner and verifier; a private, host-local Lume seed supplies the macOS+ consent state.+</Callout>++## Before you start++You need:++- an Apple Silicon Mac with Lume and `jq` installed;+- enough host space for the 150 GB sparse builder, seed, backups, and worker;+- a clean, committed checkout of `trycua/cua`; and+- access to the VM display for Keychain and macOS consent prompts.++Record the host Lume version:++```bash+lume --version+```++Use `macos-tahoe-cua:26.5.2` as the public base. It contains macOS 26.5.2+build 25F84, disabled SIP, Command Line Tools 26.6, autologin, and SSH. It has+no repository source, TCC grants, or local signing identity.++Keep the private builder and seed on host-local Lume storage. Never push them+to a registry.++## Build the private seed once++You only need to build a seed when the macOS version, public base, developer+tools, signing identity, or consent state changes. Every acceptance run starts+from a clone of the stopped seed.++### Pull and inspect the public base++On the host, run:++```bash+IMAGE=macos-tahoe-cua:26.5.2+BUILDER=cua-driver-macos-e2e-builder-26.5.2++lume pull "$IMAGE" "$BUILDER"+lume run "$BUILDER"+```++Keep `lume run` open. In Terminal in the VM display, run:++```bash+sw_vers+csrutil status+xcode-select -p+xcrun swiftc --version+```++Require macOS 26.5.2 build 25F84, disabled SIP, and+`/Library/Developer/CommandLineTools`. The Command Line Tools agreement must+already be accepted. If macOS presents it during installation, accept it in the+VM display and rerun the checks.++### Install the pinned guest toolchain++Install Homebrew with the pinned upstream installer:++```bash+HOMEBREW_INSTALL_COMMIT=4b0227cf8416504142d23893368c2e1d211d5191+HOMEBREW_INSTALL_SHA256=99287f194a8b3c9e6b0203a11a5fa54518be57209343e6bb954dec4635796d9d+HOMEBREW_INSTALLER="/tmp/homebrew-install-${HOMEBREW_INSTALL_COMMIT}.sh"++curl -fsSL \+ "https://raw.githubusercontent.com/Homebrew/install/${HOMEBREW_INSTALL_COMMIT}/install.sh" \+ -o "$HOMEBREW_INSTALLER"+printf '%s %s\n' "$HOMEBREW_INSTALL_SHA256" "$HOMEBREW_INSTALLER" \+ | shasum -a 256 -c -+/bin/bash "$HOMEBREW_INSTALLER"++eval "$(/opt/homebrew/bin/brew shellenv)"+brew install node ffmpeg jq rust+printf '\n%s\n' 'eval "$(/opt/homebrew/bin/brew shellenv)"' \+ >> ~/.zprofile+```++Open a new Terminal window and verify the tools:++```bash+xcrun swiftc --version+cargo --version+node --version+npm --version+ffmpeg -version | head -1+ffprobe -version | head -1+jq --version+```++Keep autologin, sleep prevention, and screen-lock prevention enabled. Add only+the maintainer host's public SSH key to `/Users/lume/.ssh/authorized_keys`.+Never copy a private key, registry credential, or source-control token into the+VM.++### Sync one committed source revision++From the repository root on the host, get the builder IP and push the checkout:++```bash+VM_IP="$(lume get "$BUILDER" --format json | jq -r '.[0].ipAddress')"+libs/cua-driver/scripts/sync-vm-worktree.sh push \+ "lume@${VM_IP}" '~/cua'+```++The sync rejects a dirty host checkout. It omits `.git`, local credential+files, build outputs, and host-side test evidence. It writes the exact commit+to `/Users/lume/cua/.cua-e2e-source-sha`.++### Create a stable local signing identity++Source builds need a certificate-backed identity so macOS keeps CuaDriver's+TCC grants after the next install. Tahoe can unlock the login keychain while+still denying the partition ACL used by noninteractive `codesign`, so create a+dedicated keychain in the VM:++```bash+SIGNING_KEYCHAIN="$HOME/Library/Keychains/cua-driver-signing.keychain-db"++security create-keychain "$SIGNING_KEYCHAIN"+security set-keychain-settings "$SIGNING_KEYCHAIN"+security list-keychains -d user -s "$SIGNING_KEYCHAIN"+security unlock-keychain "$SIGNING_KEYCHAIN"+export CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN="$SIGNING_KEYCHAIN"+```++Use the `lume` account password for this private test keychain. Back in the+synced checkout, run the first install:++```bash+cd /Users/lume/cua+export CUA_DRIVER_SOURCE_SHA="$(cat .cua-e2e-source-sha)"+bash libs/cua-driver/scripts/install-local.sh --release --autostart+```++Open Keychain Access in the VM display. Select the `cua-driver-signing`+keychain, open `CuaDriver Local Signing (cua-driver-rs)`, and set Trust to+**Always Trust**.++Return to Terminal and allow Apple tooling to use the private key:++```bash+read -r -s -p 'Keychain password: ' KEYCHAIN_PASSWORD; echo+security set-key-partition-list \+ -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" \+ "$SIGNING_KEYCHAIN"+unset KEYCHAIN_PASSWORD+```++Run the installer again:++```bash+bash libs/cua-driver/scripts/install-local.sh --release --autostart+```++Require the message `signed staged app with a stable local identity`. Do not+grant TCC permissions to an ad-hoc build.++### Grant the seed's consent paths++Request Accessibility and Screen Recording through the app:++```bash+/Users/lume/.local/bin/cua-driver permissions grant+```++Approve both CuaDriver requests. Then trigger the two Automation paths and+Tahoe's direct-capture request:++```bash+# The test sentinel runs this probe from Terminal.+osascript -e \+ 'tell application "System Events" to get name of first application process whose frontmost is true'++# The installed app enumerates applications through System Events.+/Users/lume/.local/bin/cua-driver list_apps '{}'++# An actual desktop capture triggers Tahoe's separate direct-capture prompt.+DRIVER=/Users/lume/.local/bin/cua-driver+"$DRIVER" call set_config '{"capture_scope":"desktop"}'+"$DRIVER" call get_desktop_state '{}' \+ > /tmp/cua-driver-seed-desktop-state.json+"$DRIVER" call set_config '{"capture_scope":"window"}'+```++Choose **Allow** for:++- Terminal controlling System Events;+- CuaDriver controlling System Events; and+- CuaDriver capturing screen and audio without the system picker.++These are normal macOS consent flows. Do not edit `TCC.db`. Rerun all three+probes and require them to finish without another prompt.++Verify the app-owned grants, signature, capture result, and SIP state:++```bash+"$DRIVER" permissions status --json | jq -e '+ .accessibility == true+ and .screen_recording == true+ and .screen_recording_capturable == true+ and .source.attribution == "driver-daemon"+'++jq -e '+ .screenshot_mime_type == "image/png"+ and .screenshot_width > 0+ and .screenshot_height > 0+ and (.screenshot_png_b64 | length) > 0+' /tmp/cua-driver-seed-desktop-state.json >/dev/null++codesign -d -r- /Applications/CuaDriver.app 2>&1 \+ | grep 'certificate leaf'+csrutil status+```++### Freeze the seed and backups++Before cloning, inspect the builder for credentials, personal files, temporary+private keys, unrelated source, and old test evidence. Clean only the audited+paths. Keep the dedicated signing keychain because it is part of the private+seed contract.++On the host, stop the builder and clone it while stopped:++```bash+SEED=cua-driver-macos-e2e-seed-26.5.2-YYYYMMDD+BACKUP_A="${SEED}-backup-a"+BACKUP_B="${SEED}-backup-b"++lume stop "$BUILDER"+lume clone "$BUILDER" "$SEED"+lume clone "$SEED" "$BACKUP_A"+lume clone "$SEED" "$BACKUP_B"+lume ls+```++Require the seed and both backups to show `stopped`. Record their names, the+public image tag, macOS build, Lume version, Command Line Tools version, Rust+version, Node version, and signing-certificate hash in the maintainer log.+Treat these VMs as immutable and local-only.++## Run the acceptance gate from a fresh clone++Create one worker per accepted run. Never run the matrix in the seed itself.++### Clone and boot a worker++On the host:++```bash+SEED=cua-driver-macos-e2e-seed-26.5.2-YYYYMMDD+WORKER="cua-driver-macos-e2e-$(date -u +%Y%m%dT%H%M%SZ)"++lume clone "$SEED" "$WORKER"+lume run "$WORKER"+```++Keep the display open. In another host terminal, sync the exact clean commit:++```bash+VM_IP="$(lume get "$WORKER" --format json | jq -r '.[0].ipAddress')"+libs/cua-driver/scripts/sync-vm-worktree.sh push \+ "lume@${VM_IP}" '~/cua'+```++### Run the complete matrix in foreground Terminal++Open Terminal in the VM display and run:++```bash+cd /Users/lume/cua+libs/cua-driver/tests/runners/macos-lume/run-all.sh+```++Enter the dedicated keychain password when asked. Keep Terminal in the logged-in+Aqua session. Do not run this command over SSH.++The runner verifies the source marker, console user, SIP state, toolchain,+stable signature, app-owned TCC grants, Terminal Automation, CuaDriver+Automation, and live capture before it builds the fixtures. It then executes+the complete macOS catalog and requires typed result rows plus valid trajectory+videos.++An accepted run ends with:++```text+macOS Rust E2E suite completed: all+```++Any setup failure is an environment failure. Do not report a smaller or+filtered matrix as the canonical result.++### Pull and review the evidence++Pull artifacts before stopping or deleting the worker, including after a+failure:++```bash+REMOTE_ARTIFACT_DIR=artifacts/cua-driver/macos \+ libs/cua-driver/scripts/sync-vm-worktree.sh pull-artifacts \+ "lume@${VM_IP}" '~/cua'+```++The command prints a host directory under `artifacts/cua-driver/vm/`. Review:++- `summary.md` for the verified source SHA and pass/fail totals;+- `cases.jsonl` and `results.jsonl` for the declared and observed rows;+- `environment.jsonl`, `golden-environment.txt`, and `permissions.json` for the+ VM contract;+- `environment-preflight.log` and per-lane logs; and+- every `recordings/**/recording.mp4` referenced by a result row.++The reporter rejects missing, duplicate, undeclared, skipped, or evidence-free+rows. A zero exit status proves that the declarations, typed results, source+identity, and required videos agree.++After the artifacts are safely on the host:++```bash+lume stop "$WORKER"+lume delete "$WORKER" --force+```++Keep the seed and both backups stopped.++## Troubleshooting++### Codesign cannot find the local identity++Unlock the dedicated keychain after each worker boot:++```bash+security unlock-keychain \+ "$HOME/Library/Keychains/cua-driver-signing.keychain-db"+```++If the identity is present but `codesign` still prompts or fails, rerun+`security set-key-partition-list` in the builder and create a new seed.++### The run opens a System Events prompt++The seed is missing an Automation grant. Stop the worker, repair the builder+through the normal prompt flow, verify that the probe no longer prompts, and+create a new seed. Do not add prompt handling to the test matrix.++### Permission status is green but capture blocks++The ordinary Screen Recording toggle and Tahoe's direct-capture consent are+separate. Run the desktop-capture probe in the builder, choose **Allow**, rerun+it without a prompt, and create a new seed.++### The preflight works over SSH but the matrix fails++SSH does not own the foreground Aqua session. Run `run-all.sh` from Terminal in+the VM display so fixtures, focus checks, and macOS prompts use the console+session.++### The runner rejects the source revision++Commit or clean the host checkout, sync again, and confirm that+`/Users/lume/cua/.cua-e2e-source-sha` equals `git rev-parse HEAD`. Diagnostic+dirty syncs cannot produce an accepted result.++## Related documentation++- [Run Cua Driver in a macOS Lume VM](/how-to-guides/driver/run-in-macos-lume-vm)+- [How Cua Driver is validated](/concepts/how-cua-driver-is-validated)+- [macOS permissions reference](/reference/cua-driver/macos-permissions)+- [Change SIP on a macOS VM](/how-to-guides/lume/change-sip)+- [Runner source and seed reference](https://github.com/trycua/cua/tree/e743f8e4cce43f94c5718bc3cadf6024a63f4382/libs/cua-driver/tests/runners/macos-lume)diff --git a/docs/content/docs/reference/cua-driver/cli-reference.mdx b/docs/content/docs/reference/cua-driver/cli-reference.mdxindex d4cc946db4..71cb12cabd 100644--- a/docs/content/docs/reference/cua-driver/cli-reference.mdx+++ b/docs/content/docs/reference/cua-driver/cli-reference.mdx@@ -7,7 +7,7 @@ description: Command-line interface specification for Cua DriverAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: npx tsx scripts/docs-generators/cua-driver.tsSource: cua-driver dump-docs- Version: 0.8.2+ Version: 0.8.3*/}Cross-platform computer-use automation driver. Install via the official script:@@ -16,7 +16,7 @@ Cross-platform computer-use automation driver. Install via the official script:curl -fsSL https://cua.ai/driver/install.sh | bash```-Documented against Cua Driver **0.8.2**. Run `cua-driver --version` for your installed version.+Documented against Cua Driver **0.8.3**. Run `cua-driver --version` for your installed version.The macOS-only `cua-driver permissions` command is documented separately in [macOS permissions](/reference/cua-driver/macos-permissions).diff --git a/docs/content/docs/reference/cua-driver/macos-permissions.mdx b/docs/content/docs/reference/cua-driver/macos-permissions.mdxindex 64bf7b62de..ca4c320017 100644--- a/docs/content/docs/reference/cua-driver/macos-permissions.mdx+++ b/docs/content/docs/reference/cua-driver/macos-permissions.mdx@@ -16,6 +16,17 @@ cua-driver permissions grant # launch CuaDriver via LaunchServices so the pro**Flags:**-| Flag | Description |-| ---- | ----------- |+| Flag | Description |+| -------- | ------------------------------- || `--json` | Machine-readable status output. |++The JSON status also includes `screen_recording_capturable`, a live capture+probe attributed to the CuaDriver daemon. macOS Tahoe can present separate+consent dialogs when CuaDriver controls System Events or requests direct screen+and audio capture without the system picker. The Automation grant is outside+the `permissions status` payload.++For the complete prompt sequence in a Lume guest, see [Run Cua Driver in a+macOS Lume VM](/how-to-guides/driver/run-in-macos-lume-vm). Source-built test+seeds also need a stable certificate identity; follow [Run Cua Driver macOS+tests in a Lume VM](/how-to-guides/driver/run-tests-in-macos-lume-vm).diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdxindex fd2d306f74..21bfbfcf75 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx@@ -7,7 +7,7 @@ description: Reference for every MCP tool Cua Driver exposesAUTO-GENERATED FILE - DO NOT EDIT DIRECTLYGenerated by: npx tsx scripts/docs-generators/cua-driver.tsSource: cua-driver dump-docs- Version: 0.8.2+ Version: 0.8.3*/}import { Callout } from 'fumadocs-ui/components/callout';diff --git a/libs/cua-driver/docs/e2e-ci-reporting.md b/libs/cua-driver/docs/e2e-ci-reporting.mdindex f84d12c9fa..40a1657d37 100644--- a/libs/cua-driver/docs/e2e-ci-reporting.md+++ b/libs/cua-driver/docs/e2e-ci-reporting.md@@ -12,12 +12,14 @@ takes no suite selector:```textWindows: scripts/ci/windows/run-rust-e2e.ps1 -RequireGuiLinux: scripts/ci/linux/run-rust-e2e.sh-macOS: scripts/ci/macos/run-rust-e2e.sh+macOS: libs/cua-driver/tests/runners/macos-lume/run-all.sh```-Workflows set a private lane value to fan that matrix into shared, native, and-capture jobs so one failure does not hide another lane. These are execution-partitions, not public suite choices or separate behavioral sources of truth.+Automated workflows may set a private lane value to fan that matrix into+shared, native, and capture jobs so one failure does not hide another lane.+The maintainer-run macOS Lume gate runs the complete matrix by default. These+are execution partitions, not public suite choices or separate behavioral+sources of truth.## Execution Order@@ -26,12 +28,13 @@ Each runner follows the same sequence:1. Resolve one immutable source SHA and check out that SHA in every lane.2. Build the Rust driver and required repo-local fixtures.3. Run `e2e_environment_preflight_test` once; it verifies `git rev-parse HEAD`- against the workflow's resolved SHA.+ or the VM source marker against the resolved SHA. On macOS it also verifies+ that the installed, TCC-authorized daemon embeds that exact SHA.4. Abort before behavioral cells if the desktop, permissions, fixture, capture,or video lifecycle is unavailable.5. Run the selected Rust integration targets.6. Validate declarations, results, and evidence with `cua-e2e-report`.-7. Upload the report, logs, and recordings.+7. Upload or retrieve the report, logs, and recordings.The preflight prevents a single TCC or desktop-session problem from appearingas the same failure on every behavioral cell.diff --git a/libs/cua-driver/docs/test-harnesses-guide.md b/libs/cua-driver/docs/test-harnesses-guide.mdindex 40343d1ab4..cb4e03a290 100644--- a/libs/cua-driver/docs/test-harnesses-guide.md+++ b/libs/cua-driver/docs/test-harnesses-guide.md@@ -23,7 +23,7 @@ suite selector:```textLinux: scripts/ci/linux/run-rust-e2e.shWindows: .\scripts\ci\windows\run-rust-e2e.ps1 -RequireGui-macOS: scripts/ci/macos/run-rust-e2e.sh+macOS: libs/cua-driver/tests/runners/macos-lume/run-all.sh```The OS workflow may fan the complete matrix out into independent jobs for@@ -51,7 +51,8 @@ cua/| | | |-- shared/web/ Shared web page and external markers| | | |-- apps/ Repo-local fixture sources| | | `-- build/ macOS/Linux/Windows fixture builders-| | `-- runners/ Auxiliary VM and sandbox entrypoints+| | `-- runners/+| | `-- macos-lume/ Maintainer Lume setup and guest entrypoint| `-- docs/ Test matrix, reporting, and contributor docs`-- scripts/ci/|-- linux/run-rust-e2e.sh Linux canonical runner@@ -171,7 +172,7 @@ background delivery is tested.### macOS-Runner: `scripts/ci/macos/run-rust-e2e.sh`+Runner: `libs/cua-driver/tests/runners/macos-lume/run-all.sh`| Runner area | Rust test | Real harness or app || --- | --- | --- |@@ -188,6 +189,9 @@ The WKWebView host runs the same typed shared-web catalog as Electron andTauri. Calculator and TextEdit add typed supporting rows for built-in applaunch focus and native Cocoa background value delivery. They run in thecanonical logged-in macOS lane, but they do not replace repo-local fixtures.+The maintainer wrapper provisions the exact source build and verifies the+private Lume seed's TCC/signing contract before delegating the behavior matrix+to `scripts/ci/macos/run-rust-e2e.sh`.### Linuxdiff --git a/libs/cua-driver/docs/test-matrix.md b/libs/cua-driver/docs/test-matrix.mdindex f9ad25635b..b574985a5f 100644--- a/libs/cua-driver/docs/test-matrix.md+++ b/libs/cua-driver/docs/test-matrix.md@@ -122,10 +122,14 @@ background delivery and attach desktop-side-effect oracles.| Installed-app launch/focus | `installed_app_launch_macos_test.rs` | Real Calculator/TextEdit launch and focus behavior in the canonical logged-in lane || Installed-app text | `installed_app_textedit_macos_test.rs` | Real TextEdit AX background write and verification in the canonical logged-in lane |-macOS uses the installed ScreenCaptureKit/AX permissions for GUI runs. The-repo-local harnesses are canonical; Calculator and TextEdit are supporting-real-app checks. SwiftUI's popover trigger is proven independently from the-remaining transient-panel AX discovery gap.+macOS uses the installed ScreenCaptureKit/AX permissions for GUI runs. Its+maintainer acceptance gate runs in a disposable clone of the stopped Lume+SIP-off golden image described in the [macOS Lume runner+guide](../tests/runners/macos-lume/README.md). Maintainers build that private+seed from the sanitized public base `macos-tahoe-cua:26.5.2`. The repo-local+harnesses are canonical; Calculator and TextEdit are supporting real-app+checks. SwiftUI's popover trigger is proven independently from the remaining+transient-panel AX discovery gap.## Harness E2E: Linux@@ -180,7 +184,7 @@ allowed, and the desktop-side-effect oracles pass.| Linux Sway Harness E2E | Controlled wlroots session | `scripts/ci/linux/run-rust-e2e-wayland.sh` || Linux nested-compositor E2E | Controlled experimental session | `scripts/ci/linux/run-rust-e2e-inject.sh` || Linux representative desktop E2E | Existing GNOME, KDE, or Xorg login | `scripts/ci/linux/run-rust-e2e-desktop.sh <desktop>` |-| macOS Harness E2E | Logged-in macOS session with permissions | `scripts/ci/macos/run-rust-e2e.sh` |+| macOS Harness E2E | Maintainer Lume SIP-off worker with a logged-in session and inherited grants | `libs/cua-driver/tests/runners/macos-lume/run-all.sh` |Workflows select private execution lanes. Rust source owns scenario definitions,fixture oracles, and result records. OS runners only build the driver, stage thediff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/observer.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/observer.rsindex 1a6235ef87..778f333822 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/observer.rs+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/observer.rs@@ -498,6 +498,8 @@ pub mod macos {fn CGWindowListCopyWindowInfo(option: u32, relative_to_window: u32) -> CFArrayRef;fn CGEventCreate(source: *mut c_void) -> *mut c_void;fn CGEventGetLocation(event: *mut c_void) -> CGPoint;+ fn CGMainDisplayID() -> u32;+ fn CGDisplayBounds(display: u32) -> CGRect;}#[link(name = "CoreFoundation", kind = "framework")]@@ -506,11 +508,26 @@ pub mod macos {}#[repr(C)]+ #[derive(Clone, Copy)]struct CGPoint {x: f64,y: f64,}+ #[repr(C)]+ #[derive(Clone, Copy)]+ struct CGSize {+ width: f64,+ height: f64,+ }++ #[repr(C)]+ #[derive(Clone, Copy)]+ struct CGRect {+ origin: CGPoint,+ size: CGSize,+ }+#[derive(Clone, Copy)]struct Bounds {x: f64,@@ -530,6 +547,19 @@ pub mod macos {&& self.x + self.width >= other.x + other.width - tolerance&& self.y + self.height >= other.y + other.height - tolerance}++ fn intersection(self, other: Self) -> Option<Self> {+ let x = self.x.max(other.x);+ let y = self.y.max(other.y);+ let right = (self.x + self.width).min(other.x + other.width);+ let bottom = (self.y + self.height).min(other.y + other.height);+ (right > x && bottom > y).then_some(Self {+ x,+ y,+ width: right - x,+ height: bottom - y,+ })+ }}struct WindowRow {@@ -574,15 +604,23 @@ pub mod macos {fn snapshot(&self, target: TargetWindow) -> Result<DesktopSnapshot, ObserverError> {let rows = window_rows();let target_index = rows.iter().position(|row| row.id == target.native_id);+ let foreground = frontmost_pid();let target_z = match target_index {None => TargetZ::NotFound,Some(index) if !rows[index].on_screen => TargetZ::Minimized,- Some(_) if frontmost_pid() == Some(target.pid as u64) => TargetZ::Foreground,+ Some(_) if foreground == Some(target.pid as u64) => TargetZ::Foreground,Some(index) => {let target_bounds = rows[index].bounds;+ let display_bounds = main_display_bounds();let full_cover = target_bounds.area() > 0.0&& rows[..index].iter().any(|row| {- row.pid != target.pid && row.bounds.fully_contains(target_bounds, 2.0)+ row.pid != target.pid+ && row_occludes_target(+ row.bounds,+ target_bounds,+ display_bounds,+ 2.0,+ )});if full_cover {TargetZ::BackgroundOccluded@@ -591,7 +629,6 @@ pub mod macos {}}};- let foreground = frontmost_pid();Ok(DesktopSnapshot {foreground,input_focus: foreground,@@ -658,6 +695,41 @@ pub mod macos {}}+ fn main_display_bounds() -> Bounds {+ let bounds = unsafe { CGDisplayBounds(CGMainDisplayID()) };+ Bounds {+ x: bounds.origin.x,+ y: bounds.origin.y,+ width: bounds.size.width,+ height: bounds.size.height,+ }+ }++ fn row_occludes_target(+ cover: Bounds,+ target: Bounds,+ display: Bounds,+ tolerance: f64,+ ) -> bool {+ if cover.fully_contains(target, tolerance) {+ return true;+ }++ // A maximized foreground sentinel covers the application workspace,+ // but macOS excludes the Dock from its CGWindow bounds. Oversized test+ // fixtures can extend behind that system-owned area on a 1024x768 VM.+ // Accept the portion inside the workspace only when the covering row+ // spans the full display width and is anchored at its top edge; a+ // normal partially-overlapping window still fails the z-order oracle.+ let spans_workspace = cover.x <= display.x + tolerance+ && cover.x + cover.width >= display.x + display.width - tolerance+ && cover.y <= display.y + tolerance;+ spans_workspace+ && target+ .intersection(cover)+ .is_some_and(|visible_target| visible_target.area() > 0.0)+ }+fn cursor_position() -> Option<(f64, f64)> {unsafe {let event = CGEventCreate(std::ptr::null_mut());@@ -778,6 +850,37 @@ pub mod macos {assert!(full.fully_contains(target, 2.0));}+ #[test]+ fn maximized_workspace_occludes_the_visible_part_of_an_oversized_target() {+ let target = Bounds {+ x: 162.0,+ y: 30.0,+ width: 700.0,+ height: 852.0,+ };+ let display = Bounds {+ x: 0.0,+ y: 0.0,+ width: 1024.0,+ height: 768.0,+ };+ let workspace = Bounds {+ x: 0.0,+ y: 0.0,+ width: 1024.0,+ height: 682.0,+ };+ assert!(row_occludes_target(workspace, target, display, 2.0));++ let partial = Bounds {+ x: 0.0,+ y: 0.0,+ width: 900.0,+ height: 682.0,+ };+ assert!(!row_occludes_target(partial, target, display, 2.0));+ }+#[test]fn native_snapshot_reads_desktop_without_a_target() {let snapshot = MacosObserver::new()diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/README.md b/libs/cua-driver/rust/crates/cua-driver/tests/README.mdindex 021cb339d8..f83f842cdd 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/README.md+++ b/libs/cua-driver/rust/crates/cua-driver/tests/README.md@@ -79,8 +79,10 @@ only for focused diagnosis. Optionalexternal-app suites remain separate.The canonical macOS E2E entrypoint is-`scripts/ci/macos/run-rust-e2e.sh`. It requires a logged-in user session and an-installed driver with Accessibility and Screen Recording grants.+`libs/cua-driver/tests/runners/macos-lume/run-all.sh`. It runs in a disposable+clone of the private maintainer seed, requires a logged-in user session, and+verifies the installed driver's Accessibility and Screen Recording grants+before delegating to `scripts/ci/macos/run-rust-e2e.sh`.Legacy Windows Sandbox runs use`../../../../tests/runners/windows-sandbox/run-tests-in-sandbox.ps1`, whichdiff --git a/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rsindex 05274e8e0f..9393387879 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rs@@ -151,7 +151,8 @@ fn preflight_state_ready(response: &cua_driver_testkit::ToolResponse, ax_marker:}fn run_preflight() {- if let Ok(expected_sha) = std::env::var("CUA_E2E_SOURCE_SHA") {+ let expected_sha = std::env::var("CUA_E2E_SOURCE_SHA").ok();+ if let Some(expected_sha) = expected_sha.as_deref() {assert!(expected_sha.len() == 40 && expected_sha.chars().all(|ch| ch.is_ascii_hexdigit()),"CUA_E2E_SOURCE_SHA must be a full commit SHA"@@ -218,6 +219,13 @@ fn run_preflight() {Some(env!("CARGO_PKG_VERSION")),"connected driver version does not match the source build");+ if let Some(expected_sha) = expected_sha.as_deref() {+ assert_eq!(+ config.structured()["source_sha"].as_str(),+ Some(expected_sha),+ "connected macOS daemon was not built from the requested source SHA"+ );+ }let recording_dir = driver.recording_dir().expect("preflight evidence directory was not prepared")diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rsindex e935f75b72..79313eb528 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_config.rs@@ -1,5 +1,8 @@use async_trait::async_trait;-use cua_driver_core::{protocol::ToolResult, tool::{Tool, ToolDef}};+use cua_driver_core::{+ protocol::ToolResult,+ tool::{Tool, ToolDef},+};use serde_json::Value;use std::sync::Arc;@@ -10,7 +13,9 @@ pub struct GetConfigTool {}impl GetConfigTool {- pub fn new(state: Arc<ToolState>) -> Self { Self { state } }+ pub fn new(state: Arc<ToolState>) -> Self {+ Self { state }+ }}static DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();@@ -29,7 +34,9 @@ fn def() -> &'static ToolDef {#[async_trait]impl Tool for GetConfigTool {- fn def(&self) -> &ToolDef { def() }+ fn def(&self) -> &ToolDef {+ def()+ }async fn invoke(&self, args: Value) -> ToolResult {use cua_driver_core::tool_args::ArgsExt;@@ -39,7 +46,9 @@ impl Tool for GetConfigTool {let session_id = args.opt_str("_session_id");let max_image_dimension = {let cfg = self.state.config.read().unwrap();- self.state.session_config.effective_max_image_dimension(session_id.as_deref(), &cfg)+ self.state+ .session_config+ .effective_max_image_dimension(session_id.as_deref(), &cfg)};// Report the CALLING session's own cursor enabled-state, not a// nondeterministic HashMap.first(). Resolve the same key the click /@@ -47,7 +56,10 @@ impl Tool for GetConfigTool {// the seeded "default" cursor when this session hasn't materialised its// own cursor yet, and finally to `true` (the overlay default).let cursor_key = super::cursor_tools::resolve_cursor_key(&args);- let cursor_enabled = self.state.cursor_registry.get(&cursor_key)+ let cursor_enabled = self+ .state+ .cursor_registry+ .get(&cursor_key).or_else(|| self.state.cursor_registry.get("default")).map(|s| s.config.enabled).unwrap_or(true);@@ -57,19 +69,23 @@ impl Tool for GetConfigTool {// last wrote.let (pip_enabled, pip_geometry) = pip_preview::read_pip_keys_from_file();let capture_scope = self.state.config.read().unwrap().capture_scope.clone();- ToolResult::text("cua-driver-rs configuration")- .with_structured(serde_json::json!({- "version": env!("CARGO_PKG_VERSION"),- "platform": "macos",- // capture_mode is a per-call param; capture_scope is a global- // setting that gates get_desktop_state.- "max_image_dimension": max_image_dimension,- "capture_scope": capture_scope,- "agent_cursor": {- "enabled": cursor_enabled,- },- "experimental_pip": pip_enabled,- "experimental_pip_geometry": pip_geometry,- }))+ ToolResult::text("cua-driver-rs configuration").with_structured(serde_json::json!({+ "version": env!("CARGO_PKG_VERSION"),+ // Maintainer E2E builds set this at compile time so the+ // preflight can prove that the installed, TCC-authorized+ // daemon came from the requested commit rather than merely+ // sharing its package version.+ "source_sha": option_env!("CUA_DRIVER_SOURCE_SHA"),+ "platform": "macos",+ // capture_mode is a per-call param; capture_scope is a global+ // setting that gates get_desktop_state.+ "max_image_dimension": max_image_dimension,+ "capture_scope": capture_scope,+ "agent_cursor": {+ "enabled": cursor_enabled,+ },+ "experimental_pip": pip_enabled,+ "experimental_pip_geometry": pip_geometry,+ }))}}diff --git a/libs/cua-driver/scripts/_install-local-rust.sh b/libs/cua-driver/scripts/_install-local-rust.shindex cbf6a52483..ccc27802ba 100755--- a/libs/cua-driver/scripts/_install-local-rust.sh+++ b/libs/cua-driver/scripts/_install-local-rust.sh@@ -277,7 +277,10 @@ echo ""# and the daemon re-prompts ("I already granted!"). Signing with a certificate# keys the grant on the cert identity instead, which is stable across rebuilds.# We create a self-signed code-signing cert once (idempotent, in the login-# keychain) and reuse it. Local dev only; releases are CI-signed.+# keychain by default) and reuse it. A maintainer VM may point+# CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN at a dedicated, already-unlocked keychain;+# this avoids image-specific login-keychain ACL failures. Local dev only;+# releases are CI-signed.## Echoes the `codesign --sign` argument: the valid identity's SHA-1 when# available, or "-" when it can't be created — no codesign/openssl, CI,@@ -287,8 +290,10 @@ echo ""CUA_LOCAL_SIGN_CN="CuaDriver Local Signing (cua-driver-rs)"ensure_local_signing_identity() {{ [ "$OS" = "Darwin" ] && command -v codesign >/dev/null 2>&1; } || { printf -- '-'; return; }- local kc="$HOME/Library/Keychains/login.keychain-db"- [ -f "$kc" ] || kc="$HOME/Library/Keychains/login.keychain"+ local kc="${CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN:-$HOME/Library/Keychains/login.keychain-db}"+ if [ -z "${CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN:-}" ] && [ ! -f "$kc" ]; then+ kc="$HOME/Library/Keychains/login.keychain"+ fi[ -f "$kc" ] || { printf -- '-'; return; }local identityidentity="$(security find-identity -v -p codesigning "$kc" 2>/dev/null \@@ -331,12 +336,16 @@ ensure_local_signing_identity() {codesign_bounded() {local timeout_seconds="$1"shift+ local keychain_args=()+ if [ -n "${CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN:-}" ]; then+ keychain_args=(--keychain "$CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN")+ fiif command -v gtimeout >/dev/null 2>&1; then- gtimeout "$timeout_seconds" codesign "$@"+ gtimeout "$timeout_seconds" codesign "${keychain_args[@]}" "$@"elif command -v perl >/dev/null 2>&1; then- perl -e 'alarm shift; exec @ARGV' "$timeout_seconds" codesign "$@"+ perl -e 'alarm shift; exec @ARGV' "$timeout_seconds" codesign "${keychain_args[@]}" "$@"else- codesign "$@"+ codesign "${keychain_args[@]}" "$@"fi}@@ -396,7 +405,7 @@ if [ "$OS" = "Darwin" ]; thenelif [ -d "$APP_DEST" ] \&& codesign -d -r- "$APP_DEST" 2>&1 | grep -q 'certificate leaf'; thenecho "${RED}Error: stable signing failed; preserving the existing certificate-signed $APP_DEST and its TCC grants.${NORMAL}" >&2- echo "Unlock/authorize the login-keychain signing key, then rerun install-local." >&2+ echo "Unlock/authorize the configured signing-keychain key, then rerun install-local." >&2exit 1elseclean_partial_bundle_signature "$APP_STAGE"diff --git a/libs/cua-driver/scripts/sync-vm-worktree.sh b/libs/cua-driver/scripts/sync-vm-worktree.shindex cccc9e0966..1a31dbb982 100755--- a/libs/cua-driver/scripts/sync-vm-worktree.sh+++ b/libs/cua-driver/scripts/sync-vm-worktree.sh@@ -26,6 +26,8 @@ Modes:checkout that should commit or push.Environment:+ ALLOW_DIRTY_SYNC Set to 1 only for diagnostic, non-acceptance pushes.+ The source marker becomes noncanonical so E2E rejects it.REMOTE_ARTIFACT_DIR Remote artifact directory, relative to remote-dir.Default: vm-outRSYNC_SSH SSH command for rsync. Default: ssh@@ -48,10 +50,27 @@ rsync_ssh="${RSYNC_SSH:-ssh}"transport="${SYNC_TRANSPORT:-rsync}"remote_os="${REMOTE_OS:-posix}"+# RSYNC_SSH follows rsync's familiar command-string convention, so callers can+# include options such as `ssh -o BatchMode=yes`. Direct preparatory SSH calls+# need an argv array instead of treating the full string as one executable.+read -r -a rsync_ssh_argv <<< "$rsync_ssh"+if [[ ${#rsync_ssh_argv[@]} -eq 0 ]]; then+ echo "RSYNC_SSH must not be empty." >&2+ exit 2+fi+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"repo_root="$(cd "$script_dir/../../.." && pwd)"source_sha="$(git -C "$repo_root" rev-parse HEAD)"-artifact_root="$repo_root/libs/cua-driver/docs/vm-artifacts"+if [[ "$mode" == push ]] && [[ -n "$(git -C "$repo_root" status --porcelain --untracked-files=normal)" ]]; then+ if [[ "${ALLOW_DIRTY_SYNC:-}" != 1 ]]; then+ echo "Refusing to label a dirty host worktree as commit $source_sha." >&2+ echo "Commit or clean the source before an acceptance run; use ALLOW_DIRTY_SYNC=1 only for diagnostics." >&2+ exit 2+ fi+ source_sha="${source_sha}-dirty"+fi+artifact_root="$repo_root/artifacts/cua-driver/vm"target_slug="$(printf '%s' "$target" | tr -c 'A-Za-z0-9_.-' '_')"timestamp="$(date -u +%Y%m%dT%H%M%SZ)"@@ -61,6 +80,18 @@ exclude_args=(--exclude=.git--exclude=.DS_Store--exclude='._*'+ # Ignored local credentials are still present in a clean Git worktree.+ # Never copy them to a validation machine.+ --exclude=.env+ --exclude=.env.local+ --exclude=.netrc+ --exclude=.npmrc+ --exclude=.pypirc+ --exclude='*.key'+ --exclude='*.p12'+ --exclude='*.pem'+ --exclude=credentials/+ --exclude=secrets/--exclude=target/--exclude=libs/cua-driver/rust/test-apps/--exclude=node_modules/@@ -68,6 +99,9 @@ exclude_args=(--exclude=__pycache__/--exclude='*.pyc'--exclude=dist/+ # Host-side VM evidence is intentionally ignored by Git and can be large.+ # Never send pulled evidence back into a guest on the next source sync.+ --exclude=artifacts/--exclude=vm-out/)@@ -75,6 +109,23 @@ tar_exclude_args=(--exclude ./.git--exclude ./.DS_Store--exclude '._*'+ --exclude ./.env+ --exclude '*/.env'+ --exclude ./.env.local+ --exclude '*/.env.local'+ --exclude ./.netrc+ --exclude '*/.netrc'+ --exclude ./.npmrc+ --exclude '*/.npmrc'+ --exclude ./.pypirc+ --exclude '*/.pypirc'+ --exclude '*.key'+ --exclude '*.p12'+ --exclude '*.pem'+ --exclude '*/credentials'+ --exclude '*/credentials/*'+ --exclude '*/secrets'+ --exclude '*/secrets/*'--exclude ./target--exclude ./libs/cua-driver/rust/test-apps--exclude ./node_modules@@ -82,17 +133,18 @@ tar_exclude_args=(--exclude '*/__pycache__'--exclude '*.pyc'--exclude ./dist+ --exclude ./artifacts--exclude ./vm-out)remote_mkdir() {case "$remote_os" inwindows)- "$rsync_ssh" "$target" \+ "${rsync_ssh_argv[@]}" "$target" \"powershell -NoProfile -Command \"New-Item -ItemType Directory -Force '$remote_dir' | Out-Null\"";;posix)- "$rsync_ssh" "$target" "mkdir -p $remote_dir"+ "${rsync_ssh_argv[@]}" "$target" "mkdir -p $remote_dir";;*)echo "REMOTE_OS must be posix or windows, got: $remote_os" >&2@@ -103,7 +155,7 @@ remote_mkdir() {push_rsync() {ssh_cmd=${remote_dir/#\~/"\$HOME"}- "$rsync_ssh" "$target" "mkdir -p $ssh_cmd"+ "${rsync_ssh_argv[@]}" "$target" "mkdir -p $ssh_cmd"rsync -az --delete -e "$rsync_ssh" "${exclude_args[@]}" "$repo_root/" "$target:$remote_dir/"}@@ -111,19 +163,19 @@ push_tar() {remote_mkdirremote_path=${remote_dir/#\~/'$HOME'}COPYFILE_DISABLE=1 tar --no-xattrs "${tar_exclude_args[@]}" -czf - -C "$repo_root" . \- | "$rsync_ssh" "$target" "tar -xzf - -C \"$remote_path\""+ | "${rsync_ssh_argv[@]}" "$target" "tar -xzf - -C \"$remote_path\""}write_source_marker() {case "$remote_os" inwindows)- "$rsync_ssh" "$target" \+ "${rsync_ssh_argv[@]}" "$target" \"powershell -NoProfile -Command \"Set-Content -NoNewline -Path '$remote_dir/.cua-e2e-source-sha' -Value '$source_sha'\"";;posix)marker_dir=${remote_dir/#\~/"\$HOME"}printf '%s\n' "$source_sha" \- | "$rsync_ssh" "$target" "mkdir -p $marker_dir && tee $marker_dir/.cua-e2e-source-sha >/dev/null"+ | "${rsync_ssh_argv[@]}" "$target" "mkdir -p $marker_dir && tee $marker_dir/.cua-e2e-source-sha >/dev/null";;esac}@@ -131,12 +183,12 @@ write_source_marker() {ensure_remote_runtime_dirs() {case "$remote_os" inwindows)- "$rsync_ssh" "$target" \+ "${rsync_ssh_argv[@]}" "$target" \"powershell -NoProfile -Command \"New-Item -ItemType Directory -Force '$remote_dir/libs/cua-driver/rust/test-apps' | Out-Null\"";;posix)remote_path=${remote_dir/#\~/'$HOME'}- "$rsync_ssh" "$target" \+ "${rsync_ssh_argv[@]}" "$target" \"mkdir -p \"$remote_path/libs/cua-driver/rust/test-apps\"";;esac@@ -148,7 +200,7 @@ pull_artifacts_rsync() {pull_artifacts_tar() {remote_path=${remote_dir/#\~/'$HOME'}- "$rsync_ssh" "$target" "tar -czf - -C \"$remote_path/$remote_artifact_dir\" ." \+ "${rsync_ssh_argv[@]}" "$target" "tar -czf - -C \"$remote_path/$remote_artifact_dir\" ." \| tar -xzf - -C "$dest"}@@ -159,7 +211,7 @@ pull_code_rsync() {pull_code_tar() {remote_path=${remote_dir/#\~/'$HOME'}- "$rsync_ssh" "$target" "tar -czf - -C \"$remote_path\" ." \+ "${rsync_ssh_argv[@]}" "$target" "tar -czf - -C \"$remote_path\" ." \| COPYFILE_DISABLE=1 tar --no-xattrs "${tar_exclude_args[@]}" -xzf - -C "$repo_root"}diff --git a/libs/cua-driver/tests/runners/macos-lume/README.md b/libs/cua-driver/tests/runners/macos-lume/README.mdnew file mode 100644index 0000000000..cbfdf05d9e--- /dev/null+++ b/libs/cua-driver/tests/runners/macos-lume/README.md@@ -0,0 +1,316 @@+# Run macOS GUI E2E in a Lume golden image++This is the maintainer-owned macOS GUI acceptance gate for `cua-driver`. It is+not a GitHub Actions job. Run it on an Apple Silicon Mac with Lume, from a+disposable clone of a stopped SIP-disabled golden image.++The golden image supplies the logged-in Aqua session, stable local signing+identity, and existing Accessibility and Screen Recording grants. Every run+installs the requested source commit before testing. The preflight rejects a+source marker, source-built binary, or installed daemon that does not identify+that exact commit.++## Before you start++- Use an Apple Silicon Mac with enough free space for the 150 GB sparse guest.+- Install Lume and `jq` on the host.+- Start from a clean, committed checkout of this repository.+- Keep the public base, private seed, and workers on host-local Lume storage.++## Image contract++- Use the versioned public base `macos-tahoe-cua:26.5.2`; do not use `latest`+ for an acceptance result.+- Treat the public image as a sanitized base. It contains macOS Tahoe 26.5.2,+ SIP disabled, Xcode Command Line Tools 26.6, autologin, and SSH. It does not+ contain repository source, TCC grants, or a local signing identity.+- Build one private, host-local seed from the public base. The private seed owns+ the remaining toolchain, signing identity, and TCC grants and must never be+ pushed to a registry.+- Keep the named golden VM stopped and never run tests in it directly.+- Put no repository credentials, signing secrets, or maintainer private SSH+ keys in the guest. A host public key is sufficient for source sync.+- Grant TCC permissions through `CuaDriver.app`. Do not edit `TCC.db`.+- Require a certificate-backed local signature. An ad-hoc signature invalidates+ the inherited grants on the next build.+- Clone one worker per run, retrieve its evidence, then delete the worker.++SIP-off does not grant or bypass TCC. It makes the disposable behavior lane+repeatable while the private seed carries grants obtained through the normal+`CuaDriver.app` prompt flow. The SIP-on check below owns the separate claim that+the supported permission flow still works with normal platform protection.++## Create the private seed++Pull the versioned public base into a mutable local builder. The initial guest+credentials are `lume` / `lume`:++```bash+IMAGE=macos-tahoe-cua:26.5.2+BUILDER=cua-driver-macos-e2e-builder-26.5.2+lume pull "$IMAGE" "$BUILDER"+lume run "$BUILDER"+```++Keep `lume run` open. In Terminal in the VM display, verify the immutable base+properties before installing anything:++```bash+sw_vers+csrutil status+xcode-select -p+xcrun swiftc --version+```++Require macOS 26.5.2 build 25F84, disabled SIP, and+`/Library/Developer/CommandLineTools`. Stop if any value differs.++Install Homebrew from the pinned, checksum-verified upstream installer. Run it+from Terminal in the VM display so macOS can request the `lume` password when+needed:++```bash+HOMEBREW_INSTALL_COMMIT=4b0227cf8416504142d23893368c2e1d211d5191+HOMEBREW_INSTALL_SHA256=99287f194a8b3c9e6b0203a11a5fa54518be57209343e6bb954dec4635796d9d+HOMEBREW_INSTALLER="/tmp/homebrew-install-${HOMEBREW_INSTALL_COMMIT}.sh"+curl -fsSL \+ "https://raw.githubusercontent.com/Homebrew/install/${HOMEBREW_INSTALL_COMMIT}/install.sh" \+ -o "$HOMEBREW_INSTALLER"+printf '%s %s\n' "$HOMEBREW_INSTALL_SHA256" "$HOMEBREW_INSTALLER" \+ | shasum -a 256 -c -+/bin/bash "$HOMEBREW_INSTALLER"++eval "$(/opt/homebrew/bin/brew shellenv)"+brew install node ffmpeg jq rust++printf '\n%s\n' 'eval "$(/opt/homebrew/bin/brew shellenv)"' \+ >> "$HOME/.zprofile"+```++Open a new Terminal window and require each command to succeed:++```bash+xcrun swiftc --version+cargo --version+node --version+npm --version+ffmpeg -version | head -1+ffprobe -version | head -1+jq --version+```++Keep autologin, sleep prevention, and screen-lock prevention enabled. Add only+the maintainer host's public SSH key to `~/.ssh/authorized_keys`; never copy a+private key or registry credential into the guest.++The public base must already have the Command Line Tools agreement accepted.+If macOS presents that agreement while installing the tools, accept it in the+VM display, then rerun the four base-property checks above. Do not freeze a+builder while `xcrun` or `swiftc` still requests an agreement.++From another host terminal, get the builder address and sync a clean committed+checkout. The sync intentionally omits `.git` and writes the exact commit to+`.cua-e2e-source-sha`. It also excludes ignored credential files such as+`.env.local`.++```bash+BUILDER=cua-driver-macos-e2e-builder-26.5.2+VM_IP="$(lume get "$BUILDER" --format json | jq -r '.[0].ipAddress')"+libs/cua-driver/scripts/sync-vm-worktree.sh push "lume@${VM_IP}" '~/cua'+```++Back in Terminal in the VM display, install the app with the commit embedded+in the daemon. Tahoe Lume images can unlock their login keychain while still+rejecting the partition ACL that non-interactive `codesign` needs, so keep the+golden identity in a dedicated keychain. Create it with the same password as+the VM account so maintainers have only one local credential to enter:++```bash+SIGNING_KEYCHAIN="$HOME/Library/Keychains/cua-driver-signing.keychain-db"+security create-keychain "$SIGNING_KEYCHAIN"+security set-keychain-settings "$SIGNING_KEYCHAIN"+security list-keychains -d user -s "$SIGNING_KEYCHAIN"+security unlock-keychain "$SIGNING_KEYCHAIN"+export CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN="$SIGNING_KEYCHAIN"+```++The first local install creates and imports the self-signed identity. It may+fall back to an ad-hoc signature until the new certificate is trusted; this is+safe only because TCC has not been granted yet. Run it once, then open Keychain+Access in the VM display, select the `cua-driver-signing` keychain, open+`CuaDriver Local Signing (cua-driver-rs)`, and set Trust to Always Trust. Back+in Terminal, give Apple tooling access to the private key without storing the+keychain password in the image or repository:++```bash+cd ~/cua+export CUA_DRIVER_SOURCE_SHA="$(cat .cua-e2e-source-sha)"+bash libs/cua-driver/scripts/install-local.sh --release --autostart++read -r -s -p 'Keychain password: ' KEYCHAIN_PASSWORD; echo+security set-key-partition-list \+ -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" \+ "$SIGNING_KEYCHAIN"+unset KEYCHAIN_PASSWORD+```++Rerun the installer and require its `signed staged app with a stable local+identity` message before granting permissions through the app-owned flow:++```bash+bash libs/cua-driver/scripts/install-local.sh --release --autostart+~/.local/bin/cua-driver permissions grant+```++Complete the Accessibility and Screen Recording prompts. Tahoe 26 also asks+separately for Automation and direct ScreenCaptureKit access. Trigger all+remaining consent paths before freezing the seed:++```bash+# Terminal owns the test sentinel's read-only frontmost-state probes.+osascript -e \+ 'tell application "System Events" to get name of first application process whose frontmost is true'++# The installed app owns driver-side app enumeration.+~/.local/bin/cua-driver list_apps '{}'++# A desktop screenshot triggers Tahoe's direct-capture/private-window prompt.+~/.local/bin/cua-driver call set_config '{"capture_scope":"desktop"}'+~/.local/bin/cua-driver call get_desktop_state '{}' \+ > /tmp/cua-driver-seed-desktop-state.json+~/.local/bin/cua-driver call set_config '{"capture_scope":"window"}'+jq -e '+ .screenshot_mime_type == "image/png"+ and .screenshot_width > 0+ and .screenshot_height > 0+ and (.screenshot_png_b64 | length) > 0+' /tmp/cua-driver-seed-desktop-state.json >/dev/null+```++Choose Allow for both `Terminal` -> `System Events` and `CuaDriver` ->+`System Events`, and choose Allow on the CuaDriver direct-capture prompt. These+are normal macOS consent flows; do not edit `TCC.db`. Rerun the commands and+require them to finish without another prompt. Then verify the daemon's own+identity, live capture permission, stable signature, and SIP state:++```bash+~/.local/bin/cua-driver permissions status --json | jq -e '+ .accessibility == true+ and .screen_recording == true+ and .screen_recording_capturable == true+ and .source.attribution == "driver-daemon"+'+codesign -d -r- /Applications/CuaDriver.app 2>&1 | grep 'certificate leaf'+csrutil status+```++All three commands must succeed, and `csrutil status` must report disabled.+Stop the builder and clone it to a date/version-named private seed plus two+stopped backups:++```bash+SEED=cua-driver-macos-e2e-seed-26.5.2-YYYYMMDD+BACKUP_A="${SEED}-backup-a"+BACKUP_B="${SEED}-backup-b"+lume stop "$BUILDER"+lume clone "$BUILDER" "$SEED"+lume clone "$SEED" "$BACKUP_A"+lume clone "$SEED" "$BACKUP_B"+lume ls+```++Require the seed and both backups to show `stopped`. Treat them as immutable and+local-only. Record their names, the public base tag, macOS build (`sw_vers`),+Lume version, CLT version, Rust version, Node version, and signing-certificate+hash in the maintainer log. Also record that the following consent paths were+granted and then rerun without prompts:++- `CuaDriver.app`: Accessibility and Screen Recording+- Terminal controlling System Events+- CuaDriver controlling System Events+- CuaDriver direct screen and audio capture without the system picker++Build a new seed instead of updating one in place.++## Run the acceptance gate++Start from a clean committed host checkout. Give the worker a unique name:++```bash+SEED=cua-driver-macos-e2e-seed-26.5.2-YYYYMMDD+WORKER="cua-driver-macos-e2e-$(date -u +%Y%m%dT%H%M%SZ)"+lume clone "$SEED" "$WORKER"+echo "$WORKER"+lume run "$WORKER"+```++Keep `lume run` open. From another host terminal, set `WORKER` to the printed+name and sync the exact host commit:++```bash+WORKER=cua-driver-macos-e2e-YYYYMMDDTHHMMSSZ+VM_IP="$(lume get "$WORKER" --format json | jq -r '.[0].ipAddress')"+libs/cua-driver/scripts/sync-vm-worktree.sh push "lume@${VM_IP}" '~/cua'+```++Open Terminal in the VM display and run the single guest entrypoint. Do not run+it over SSH: GUI fixtures must inherit the logged-in console session. The+runner asks once for the dedicated keychain password after each worker boot;+do not put that password in the repository or VM image.++```bash+cd ~/cua+libs/cua-driver/tests/runners/macos-lume/run-all.sh+```++The entrypoint refuses the wrong OS, user session, SIP state, dirty or+unidentified source, missing dependencies, ad-hoc signature, stale installed+daemon, unusable TCC grants, or missing Terminal/CuaDriver Automation grants.+It reinstalls the exact source commit and then runs the canonical macOS matrix.++Pull evidence before deleting the worker, even after a failed run:++```bash+REMOTE_ARTIFACT_DIR=artifacts/cua-driver/macos \+ libs/cua-driver/scripts/sync-vm-worktree.sh pull-artifacts \+ "lume@${VM_IP}" '~/cua'+lume stop "$WORKER"+lume delete "$WORKER" --force+```++The host stores the pulled summary, typed JSONL rows, environment record, logs,+screenshots, and MP4 trajectories under `artifacts/cua-driver/vm/`, which Git+ignores. A setup failure is an environment failure, not permission to report a+smaller green matrix.++## Validate the SIP-on permission flow++Run this disposable lane before a release and after macOS, Lume, signing, or+TCC-related changes. It verifies the supported user flow rather than the+golden image's inherited grants.++1. Clone the golden seed to a new worker while both are stopped.+2. Run `lume sip on <worker> --yes`.+3. Boot it with a display, sync the exact source as above, and install it with+ `CUA_DRIVER_SOURCE_SHA` set to `.cua-e2e-source-sha`.+4. In the VM display, reset only the disposable worker's grants:++ ```bash+ tccutil reset Accessibility com.trycua.driver+ tccutil reset ScreenCapture com.trycua.driver+ ~/.local/bin/cua-driver permissions grant+ ```++5. Complete the prompts and require the same four-field+ `permissions status --json` check used during image creation.+6. Run `scripts/ci/macos/run-rust-e2e.sh` directly to prove the canonical+ preflight and matrix with SIP enabled.+7. Pull artifacts, stop the worker, and delete it. Never promote this mutated+ worker back to the SIP-off seed.++## Repair or rotate the seed++Discard and rebuild the private seed when its signature becomes ad-hoc, the+permission check fails, the public base or toolchain needs an update, or the+seed has been booted for a test. Keep the last known-good stopped seed until its+replacement passes one full worker run and one SIP-on permission-flow check.diff --git a/libs/cua-driver/tests/runners/macos-lume/run-all.sh b/libs/cua-driver/tests/runners/macos-lume/run-all.shnew file mode 100755index 0000000000..21ce1adac0--- /dev/null+++ b/libs/cua-driver/tests/runners/macos-lume/run-all.sh@@ -0,0 +1,172 @@+#!/usr/bin/env bash+# Install and run the canonical macOS GUI matrix inside a disposable Lume clone.+set -euo pipefail++SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../../.." && pwd)"+DRIVER_ROOT="${REPO_ROOT}/libs/cua-driver"+RUST_ROOT="${DRIVER_ROOT}/rust"+ARTIFACT_DIR="${REPO_ROOT}/artifacts/cua-driver/macos"+SOURCE_MARKER="${CUA_E2E_SOURCE_MARKER:-${REPO_ROOT}/.cua-e2e-source-sha}"+SIGNING_KEYCHAIN="${CUA_E2E_SIGNING_KEYCHAIN:-${HOME}/Library/Keychains/cua-driver-signing.keychain-db}"+SIGNING_CN="CuaDriver Local Signing (cua-driver-rs)"++usage() {+ cat <<'EOF'+Usage: run-all.sh [--no-build]++Run the canonical cua-driver macOS GUI E2E matrix in a disposable clone of+the maintainer Lume golden image. Start this command from Terminal in the VM's+logged-in desktop session, not over SSH.+EOF+}++for arg in "$@"; do+ case "${arg}" in+ --no-build) ;;+ -h|--help) usage; exit 0 ;;+ *) echo "unknown argument: ${arg}" >&2; usage >&2; exit 2 ;;+ esac+done++[[ "$(uname -s)" == Darwin ]] || {+ echo "The Lume macOS runner must run in a macOS guest" >&2+ exit 2+}+if [[ -n "${SSH_CONNECTION:-}" || -n "${SSH_TTY:-}" ]]; then+ echo "Run this command from Terminal in the VM display so fixtures inherit the GUI login session" >&2+ exit 2+fi++CURRENT_USER="$(id -un)"+CONSOLE_USER="$(stat -f '%Su' /dev/console)"+if [[ "${CONSOLE_USER}" != "${CURRENT_USER}" ]]; then+ echo "The current user (${CURRENT_USER}) is not the logged-in console user (${CONSOLE_USER})" >&2+ exit 2+fi+launchctl print "gui/$(id -u)" >/dev/null 2>&1 || {+ echo "No launchd GUI domain is available for ${CURRENT_USER}" >&2+ exit 2+}++SIP_STATUS="$(csrutil status 2>&1)"+if ! printf '%s\n' "${SIP_STATUS}" | grep -Fq "System Integrity Protection status: disabled."; then+ printf '%s\n' "${SIP_STATUS}" >&2+ echo "The canonical Lume behavior lane requires the SIP-off golden image" >&2+ exit 2+fi++for command_name in cargo codesign ffmpeg ffprobe jq node npm osascript security xcrun; do+ command -v "${command_name}" >/dev/null 2>&1 || {+ echo "Missing golden-image dependency: ${command_name}" >&2+ exit 2+ }+done++if [[ ! -f "${SIGNING_KEYCHAIN}" ]]; then+ echo "Missing golden-image signing keychain: ${SIGNING_KEYCHAIN}" >&2+ echo "Create the private seed according to tests/runners/macos-lume/README.md" >&2+ exit 2+fi+echo "[SIGNING] Unlocking the golden image's dedicated signing keychain"+if [[ -n "${CUA_E2E_SIGNING_KEYCHAIN_PASSWORD:-}" ]]; then+ security unlock-keychain -p "${CUA_E2E_SIGNING_KEYCHAIN_PASSWORD}" "${SIGNING_KEYCHAIN}"+ unset CUA_E2E_SIGNING_KEYCHAIN_PASSWORD+else+ security unlock-keychain "${SIGNING_KEYCHAIN}"+fi+if ! security find-identity -v -p codesigning "${SIGNING_KEYCHAIN}" 2>/dev/null \+ | grep -Fq "\"${SIGNING_CN}\""; then+ echo "The dedicated keychain has no valid ${SIGNING_CN} identity" >&2+ exit 2+fi+export CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN="${SIGNING_KEYCHAIN}"++if git -C "${REPO_ROOT}" rev-parse --is-inside-work-tree >/dev/null 2>&1; then+ if [[ -n "$(git -C "${REPO_ROOT}" status --porcelain --untracked-files=normal)" ]]; then+ echo "The synced source must have no working-tree changes" >&2+ exit 2+ fi+ SOURCE_SHA="$(git -C "${REPO_ROOT}" rev-parse HEAD)"+elif [[ -f "${SOURCE_MARKER}" ]]; then+ SOURCE_SHA="$(tr -d '[:space:]' < "${SOURCE_MARKER}")"+ export CUA_E2E_SOURCE_MARKER="${SOURCE_MARKER}"+else+ echo "The synced source needs git metadata or ${SOURCE_MARKER}" >&2+ exit 2+fi+if [[ ! "${SOURCE_SHA}" =~ ^[0-9a-fA-F]{40}$ ]]; then+ echo "The synced source identity is not a full commit SHA: ${SOURCE_SHA}" >&2+ exit 2+fi++export CUA_E2E_SOURCE_SHA="${SOURCE_SHA}"+export CUA_DRIVER_SOURCE_SHA="${SOURCE_SHA}"+mkdir -p "${ARTIFACT_DIR}"+printf '%s\n' "${SIP_STATUS}" > "${ARTIFACT_DIR}/sip-status.txt"+printf '%s\n' "${SOURCE_SHA}" > "${ARTIFACT_DIR}/requested-source-sha.txt"+{+ sw_vers+ printf 'console_user:\t%s\n' "${CONSOLE_USER}"+ printf 'rustc:\t%s\n' "$(rustc --version)"+ printf 'node:\t%s\n' "$(node --version)"+ printf 'xcode_select:\t%s\n' "$(xcode-select -p)"+} > "${ARTIFACT_DIR}/golden-environment.txt"++echo "[AUTOMATION] Verifying Terminal can read frontmost state through System Events"+if ! osascript -e \+ 'tell application "System Events" to get name of first application process whose frontmost is true' \+ > "${ARTIFACT_DIR}/terminal-system-events.txt"; then+ echo "Terminal cannot control System Events; rebuild the seed and grant the Automation prompt" >&2+ exit 2+fi++# CUA_DRIVER_SOURCE_SHA is consumed by option_env! in platform-macos. Cargo+# does not treat arbitrary compile-time environment variables as an input when+# deciding whether an otherwise unchanged crate is fresh. Force that crate and+# its dependent driver binary to rebuild so a doc-only commit cannot inherit a+# stale embedded source SHA from the seed or a previous worker run.+echo "[BUILD IDENTITY] Invalidating the macOS backend for ${SOURCE_SHA}"+cargo clean --manifest-path "${RUST_ROOT}/Cargo.toml" -p platform-macos++echo "[INSTALL] Building and installing ${SOURCE_SHA} with the golden signing identity"+bash "${DRIVER_ROOT}/scripts/install-local.sh" --release --autostart \+ 2>&1 | tee "${ARTIFACT_DIR}/install-local.log"++codesign -d -r- /Applications/CuaDriver.app \+ > "${ARTIFACT_DIR}/codesign-requirement.txt" 2>&1+if ! grep -Fq "certificate leaf" "${ARTIFACT_DIR}/codesign-requirement.txt"; then+ echo "CuaDriver.app is not signed with the golden image's stable certificate identity" >&2+ exit 1+fi++INSTALLED_BIN="${HOME}/.local/bin/cua-driver"+PERMISSIONS_FILE="${ARTIFACT_DIR}/permissions.json"+PERMISSIONS_READY=0+for _ in 1 2 3 4 5 6 7 8 9 10; do+ if "${INSTALLED_BIN}" permissions status --json > "${PERMISSIONS_FILE}" \+ && jq -e '+ .accessibility == true+ and .screen_recording == true+ and .screen_recording_capturable == true+ and .source.attribution == "driver-daemon"+ ' "${PERMISSIONS_FILE}" >/dev/null; then+ PERMISSIONS_READY=1+ break+ fi+ sleep 1+done+if [[ "${PERMISSIONS_READY}" != 1 ]]; then+ cat "${PERMISSIONS_FILE}" >&2 || true+ echo "The cloned golden image does not have usable Accessibility and Screen Recording grants" >&2+ exit 1+fi++echo "[AUTOMATION] Verifying the installed CuaDriver can query System Events"+if ! "${INSTALLED_BIN}" list_apps '{}' > "${ARTIFACT_DIR}/driver-list-apps.json"; then+ echo "CuaDriver cannot control System Events; rebuild the seed and grant the Automation prompt" >&2+ exit 2+fi++echo "[E2E] Running the canonical macOS matrix"+exec "${REPO_ROOT}/scripts/ci/macos/run-rust-e2e.sh" "$@"diff --git a/scripts/ci/README.md b/scripts/ci/README.mdindex 8e9adb9f74..7c800722f2 100644--- a/scripts/ci/README.md+++ b/scripts/ci/README.md@@ -17,13 +17,19 @@ and native harnesses, see| `linux/run-rust-e2e-inject.sh` | Nested `cua-compositor` session | no selector || `linux/run-rust-e2e-desktop.sh` | Existing representative Linux desktop | no selector || `windows/run-rust-e2e.ps1` | Windows console/RDP user session | `-RequireGui` |-| `macos/run-rust-e2e.sh` | Logged-in macOS session with TCC | no selector |+| `macos/run-rust-e2e.sh` | Logged-in macOS session already prepared by the maintainer wrapper | no selector |Use the command without a selector for the canonical complete run. CI sets theprivate `CUA_E2E_INTERNAL_LANE` partition to `shared`, `native`, or `capture`when it fans the same matrix into independent jobs. Those values are not publicalternate suites.+The maintainer-facing macOS command is+`libs/cua-driver/tests/runners/macos-lume/run-all.sh`. It verifies the private+Lume seed, installs the exact committed source, and then delegates to the thin+`macos/run-rust-e2e.sh` matrix runner above. There is no GitHub-hosted macOS GUI+job.+Run the Wayland wrapper through `nix develop .#cua-driver-wayland-e2e`. Itcreates a pure Wayland session with Xwayland disabled and delegates everyscenario to `run-rust-e2e.sh`.diff --git a/scripts/ci/macos/run-rust-e2e.sh b/scripts/ci/macos/run-rust-e2e.shindex b735cb6d55..a6a06052b6 100755--- a/scripts/ci/macos/run-rust-e2e.sh+++ b/scripts/ci/macos/run-rust-e2e.sh@@ -1,6 +1,7 @@#!/usr/bin/env bash# Run the canonical Rust desktop matrix in a logged-in macOS user session.# macOS harness tests use the installed, TCC-authorized cua-driver daemon path.+# The install must embed CUA_DRIVER_SOURCE_SHA; the Lume wrapper owns that step.set -euo pipefailSCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"@@ -16,6 +17,8 @@ Usage: run-rust-e2e.sh [--no-build]Run from a logged-in macOS desktop after install-local and TCC authorization.The testkit proxies MCP calls through the installed CuaDriver daemon.+The installed daemon must embed the same CUA_DRIVER_SOURCE_SHA as this source.+Maintainers should use libs/cua-driver/tests/runners/macos-lume/run-all.sh.The contributor-facing command always runs the complete matrix.EOF}@@ -34,18 +37,35 @@ case "$SUITE" in*) echo "unsupported internal lane: $SUITE" >&2; exit 2 ;;esac-if ! git -C "${REPO_ROOT}" diff --quiet || ! git -C "${REPO_ROOT}" diff --cached --quiet; then- echo "macOS canonical E2E requires a clean tracked working tree" >&2+SOURCE_MARKER="${CUA_E2E_SOURCE_MARKER:-${REPO_ROOT}/.cua-e2e-source-sha}"+if git -C "${REPO_ROOT}" rev-parse --is-inside-work-tree >/dev/null 2>&1; then+ if [[ -n "$(git -C "${REPO_ROOT}" status --porcelain --untracked-files=normal)" ]]; then+ echo "macOS canonical E2E requires a clean working tree" >&2+ exit 2+ fi+ RESOLVED_SOURCE_SHA="$(git -C "${REPO_ROOT}" rev-parse HEAD)"+elif [[ -f "${SOURCE_MARKER}" ]]; then+ RESOLVED_SOURCE_SHA="$(tr -d '[:space:]' < "${SOURCE_MARKER}")"+ export CUA_E2E_SOURCE_MARKER="${SOURCE_MARKER}"+else+ echo "macOS canonical E2E requires git metadata or ${SOURCE_MARKER}" >&2exit 2fiif [[ -z "${CUA_E2E_SOURCE_SHA:-}" ]]; then- CUA_E2E_SOURCE_SHA="$(git -C "${REPO_ROOT}" rev-parse HEAD)"+ CUA_E2E_SOURCE_SHA="${RESOLVED_SOURCE_SHA}"fiif [[ ! "${CUA_E2E_SOURCE_SHA}" =~ ^[0-9a-fA-F]{40}$ ]]; thenecho "CUA_E2E_SOURCE_SHA must be a full 40-character commit SHA" >&2exit 2fi+EXPECTED_SOURCE_SHA_LOWER="$(printf '%s' "${CUA_E2E_SOURCE_SHA}" | tr '[:upper:]' '[:lower:]')"+RESOLVED_SOURCE_SHA_LOWER="$(printf '%s' "${RESOLVED_SOURCE_SHA}" | tr '[:upper:]' '[:lower:]')"+if [[ "${EXPECTED_SOURCE_SHA_LOWER}" != "${RESOLVED_SOURCE_SHA_LOWER}" ]]; then+ echo "macOS E2E source ${RESOLVED_SOURCE_SHA} does not match requested SHA ${CUA_E2E_SOURCE_SHA}" >&2+ exit 2+fiexport CUA_E2E_SOURCE_SHA+export CUA_DRIVER_SOURCE_SHA="${CUA_E2E_SOURCE_SHA}"ARTIFACT_DIR="${REPO_ROOT}/artifacts/cua-driver/macos"RECORDING_ROOT="${ARTIFACT_DIR}/recordings"