feat(cua-driver): exact-target macOS background input v1

[hami-sh]

Implements macOS background input v1 per the included plan
(libs/cua-driver/docs/macos-background-input-v1-plan.md).

What this does

Every window-addressed background mutation on macOS now enforces the exact
(pid, CGWindowID) invariant. Immediately before acting, the driver gathers
fresh WindowServer and accessibility facts for the requested window. A pure
decision core either permits the selected route or refuses it with a structured
reason. A same-process sibling window cannot satisfy, receive, or confirm an
action addressed to the target window.

Routes

1. AxSemantic — exact-element AX actions, allowed only with proven
   ownership, ancestry, and fresh AXWindows membership.
2. WindowPointer — window-local routed pointer events, additionally
   requiring a visible, non-minimized live frame and an in-frame point.
3. InsertText / GenericKey — process-scoped keyboard delivery, allowed
   only when the requested window is the process's sole eligible destination.

Window-addressed refusals use explicit codes such as window_not_found,
owner_pid_mismatch, off_space_or_ax_unresolved,
minimized_or_hidden_window, same_pid_keyboard_ambiguity, and
element_outside_target_window. delivery_mode:"foreground" remains the
caller's explicit last resort.

Verification semantics

• Event-post success is not reported as effect confirmation.
• Native text readback is bound to the proven target window.
• Web-content writes remain unverifiable without an independent renderer
  oracle.
• A narrow per-process coordinator spans fact gathering, dispatch, focus
  restoration, and target-bound verification; independent processes remain
  concurrent.
• Element reveal is separately gated before AXScrollToVisible, and the
  pointer route is revalidated before wheel dispatch.

get_window_state now reports an additive background_input capability
section from the same fresh facts. Per-process Electron accessibility
enablement keys on (pid, process start time) so reused PIDs cannot inherit
stale enablement state.

Compatibility

• Gating applies only to window-addressed, non-foreground calls; pid-only and
  foreground behavior is unchanged.
• press_key and type_text_chars now reject stale element handles instead
  of silently proceeding unaddressed.
• Argument-shape errors retain their pre-gate precedence.
• Background window-local pointer calls reject out-of-frame points.

Validation

Local source validation at d19d186c734e59e299477953bbb722c8f296dbff:

• cargo test -p platform-macos --lib: 308 passed.
• Focused decision-core and background-mutation regression suites passed.
• cargo fmt --all -- --check passed.
• git diff --check passed.

Authoritative exact-head CI at the same SHA:

• Rust format: passed on Linux, macOS, and Windows.
• Rust Linux unit: passed.
• Rust Windows unit: passed.
• Cua Driver contract clients: generated bindings and portable parity passed on Linux, macOS, and Windows.

Native macOS certification used a logged-in Lume VM running macOS 26.5.2 on
arm64. The release binary was built from the exact source tree with embedded
source SHA d19d186c734e59e299477953bbb722c8f296dbff, signed with the established
local Cua Driver test identity, and externally verified against its designated
requirement. Installed binary SHA-256:
aca9547959ba89822395180e90d7b65e98d8f08bdb0379c98807f9c542ae9cf8.
The daemon reported Accessibility and Screen Recording as granted under its
own com.trycua.driver.local identity.

Representative exact-window results while Terminal remained frontmost and the
physical cursor remained fixed at (1033, 225):

• AppKit background AX click incremented the requested window counter from 2
  to 3.
• AppKit exact-field background text write was confirmed by AX readback as
  candidate-d19d-actual.
• AppKit raw background key delivery to a same-PID sibling was refused with
  same_pid_keyboard_ambiguity.
• Electron background AX click incremented the requested window counter from
  2 to 3.
• Terminal remained frontmost after each mutation and the cursor position did
  not change.

Known v1 limitations

• Competing-keyboard-destination count is a WindowServer approximation and
  excludes only AX-proven minimized siblings.
• Live-stream PiP, broad temporary restore behavior, arbitrary Space movement,
  and game/canvas input synthesis remain out of scope.

[f-trycua]

Maintainer refresh at ef637a057266d41a2e66358aa5182bacb98031a5:

• Rebases the contribution onto current origin/main and preserves Hamish as author plus the linked Amp coauthor identity and source-SHA provenance.
• Fixes the press_key compile regression and binds its AX postcondition oracle to the requested window.
• Routes set_value, dedicated right_click, double_click, and scroll through the exact-target gate. Background double-click now chooses one actuator class and cannot silently fall through from failed AXOpen to an ungated pointer.
• Local: cua-driver-core 495 passed; platform-macos 300 passed; cua-driver passes except the existing host-state failure in protocol_tools_call_test::type_text_chars_tool because TextEdit owns multiple stale windows and the mainline PID-only ambiguity guard refuses before this change runs; formatting is clean.
• Local contributor-attribution and release-title validators pass.

Required near-merge Lume E2E matrix (not run yet):

1. Two-window AppKit, A targeted/B key: AX click and set_value mutate only A; B unchanged; frontmost pid, key window, z-order, and hardware cursor unchanged.
2. Two-window AppKit, A visible/occluded: routed click, right-click, double-click, and scroll land only in A; B unchanged; focus/z-order/cursor preserved.
3. Two-window AppKit keyboard: type_text, type_text_chars, press_key, hotkey, and key-scroll refuse same_pid_keyboard_ambiguity; both window journals and values remain unchanged.
4. AppKit refusal states: minimized/hidden A permits exact semantic AX but refuses pointer/keyboard; off-Space/AX-unresolved, stale ID, and foreign owner refuse before dispatch with no leakage.
5. Two-BrowserWindow Electron fixture: per-lifetime AX enablement materializes both exact windows; semantic AX and routed pointer affect only A; every PID-keyboard route refuses ambiguity; B/focus/z-order/cursor remain unchanged.
6. Electron relaunch: repeat rows 3 and 5 after process restart to prove the process-lifetime enablement cache does not suppress re-enablement.

Each row should record the fixture case ID, before/after values and journals, frontmost pid, key-window CGWindowID, ordered window IDs/z-order, cursor position, structured result/refusal, exact driver SHA/version, macOS version/arch, and fixture build identity.

One design item remains for review before merge: the checked-in plan requires a per-PID mutation coordinator, while this v1 still documents gate-to-dispatch TOCTOU as a limitation.

[f-trycua]

Maintainer update at exact head 53319cf1fb99f467ab4ab2a1d3a622c6f79e9a64:

• Added the plan-required narrow per-PID background-mutation coordinator. The lease is held from fresh exact-target fact gathering through dispatch, focus restoration, and target-bound verification; mutations for different PIDs remain concurrent. Nested focus clicks use task-local, PID-bound lease proof rather than a caller-supplied marker.
• Focused concurrency coverage proves same-PID serialization, different-PID independence, and nested proof scoping.
• Exact-head local verification: platform-macos 303/303; cua-driver-core 495 unit + 2 contract + 3 lifecycle; fmt and diff checks clean. Full cua-driver again reaches only the documented host-state failure in protocol_tools_call_test::type_text_chars_tool because the resident TextEdit PID owns multiple stale windows and main refuses it as ambiguous_window_target before this PR's dispatch path.

Required exact-head Lume evidence matrix (run the source-built driver at the SHA above and record tool journals plus before/after focus, key window, z-order, cursor, and both window values):

1. Two-window AppKit, same PID: start overlapping mutations for A and B; prove B does not gather or dispatch until A has restored focus and completed target-bound verification. Repeat with order reversed.
2. Two-window AppKit, different PIDs: synchronize two mutations behind a barrier and prove both can enter their mutation sections concurrently while each changes only its addressed window.
3. Two Electron BrowserWindows, same PID: repeat the serialized A/B case for semantic and pointer routes; PID keyboard routes must refuse same_pid_keyboard_ambiguity without dispatch.
4. Electron relaunch: repeat after PID/process-lifetime rotation to prove AX enablement and coordinator ownership do not leak across lifetimes.

For every case, capture exact SHA/version, guest OS/arch, fixture build, monotonic gather/dispatch/restore/verify timestamps, structured result, and unchanged sibling-window state. This extends the previously posted AppKit/Electron two-window matrix with the coordinator-specific concurrency oracle.

[f-trycua]

Reviewed the exact-target decision core and platform dispatch paths. The scroll reveal ordering defect was fixed before dispatch; focused tests, exact-SHA Lume AppKit/Electron proof, cross-platform Rust/contract CI, release metadata, and attribution all pass. Contributor credit is preserved.