Document MSAA stall handling and remaining Wine acceptance checks

Describe the single COM worker, bounded queues, focus invalidation, 500 ms
result expiry, native fallback, foreground filtering, owned-popup handling,
and shutdown behavior. State the limitation that a permanently blocked
provider occupies the one worker until helper exit.

Document the event-stall regression commands and their coverage: typing and
native button feedback during provider stalls, unchanged editor state,
late-focus suppression, bounded normal shutdown, unrelated background
providers, owned popups, both architectures, and the Orca endpoint.

Distinguish the supplied October 12 reader log from the confirmed shared
helper hang path. Successful D-Bus calls and clean reader shutdown do not
establish a reader crash, and synthetic provider stalls do not establish
the cause of every live MUSHclient failure. Keep command typing, incoming
plugin output, menus, output-buffer arrows, keypad review, audible speech,
and physical braille as explicit installed-helper acceptance checks.

Validation: reviewed the documented behavior against the worker, event
thread, and fixtures; git diff --check passed. Fresh CMake configure/build,
all four CTest checks, six event-stall runs, and eight existing menu/editor/
control/list fixture runs passed. GUI checks ran sequentially on a private
dummy Xorg display because Xvfb is unavailable; live speech and physical
braille checks were not performed.

README.md

@@ -237,6 +237,18 @@ contains stable comma-separated state labels decoded from the MSAA bitmask;
 protected values are excluded. Readers should filter name/state changes to
 their focused source and distinguish these labels from editor diagnostics.
 
+Application-owned MSAA queries run on one separate COM worker, with bounded
+pending requests and copied results. A stalled provider cannot block the
+helper's menu/editor event thread or normal shutdown. Focus/foreground changes
+retire previous results; event results expire after 500 ms. If focus queries
+do not finish, native control feedback uses the existing bounded fallback.
+Unrelated background events are rejected before querying providers; visible
+popups owned by the foreground window retain their accessible event path.
+A provider that never completes still occupies the one MSAA worker until
+helper exit; native menus, editing, focus fallback and controller requests
+remain available. No extra workers accumulate behind blocked providers.
+
+
 Standard `SysListView32` controls now report the current row's text columns,
 selection and position, including 32-bit installers driven by the 64-bit
 helper. Wine can expose these controls only as a generic client named `List1`,

tests/README.md

@@ -1,5 +1,39 @@
 # Wine control integration
 
+## MSAA event stalls
+
+Run sequentially on a private X display, for example with `xvfb-run -a`:
+
+```sh
+python3 tests/event_stall_integration.py --build-dir build
+python3 tests/event_stall_integration.py --build-dir build --32-bit
+python3 tests/event_stall_integration.py --build-dir build --getter
+python3 tests/event_stall_integration.py --build-dir build --background
+python3 tests/event_stall_integration.py --build-dir build --popup
+```
+
+The fixture needs the matching MinGW C++ compiler. It uses a disposable prefix
+and recording reader service. It stalls either `WM_GETOBJECT` or MSAA
+text-property retrieval for eight seconds. A separate foreground
+application must deliver both repeated typed characters and native button
+feedback before that stall ends, preserving native text, caret and selection.
+The old focus must not surface afterward. A second stall checks normal
+`WM_QUIT` shutdown before the provider completes. Background focus events must
+neither query unrelated providers nor invalidate foreground feedback, and an
+owned nonactivating accessible popup must retain reading without moving native
+focus. Use `--reader orca` to check the alternate recording endpoint.
+
+On October 12 the supplied Cthulhu log showed successful reader D-Bus calls,
+continued Xorg input and clean reader shutdown; it did not establish a reader
+crash. Source inspection found synchronous MSAA calls on the helper event
+thread. The original helper failed the blocked-provider typing check; the same
+editor fixture without a blocked provider passed. These synthetic checks
+establish the shared hang path, not the exact cause of every live MUSHclient
+failure. Recheck MUSHclient command typing, incoming plugin output, menus,
+plugin output-buffer arrows and keypad review after installing the helper and
+restarting the reader. Listen to speech and check physical braille separately.
+
+
 ## Reader endpoint selection
 
 After building, run these checks sequentially on private displays: