Document recovery from legacy Wine helper overwrites

Explain an installation mismatch confirmed while diagnosing missing
MUSHclient reading: an older helper bundled with Python Cthulhu replaced
the standalone launcher and Winelib sidecar, leaving native hook files
in the installation directory. The old helper still connected to the
reader service but did not start the native 32-bit menu/editor host.

Document how to distinguish a running helper from a complete standalone
installation, rebuild and install all five matching helper files, and
reload Cthulhu in its original desktop session. Include the requirement
to restart Wine applications when an older hook DLL remains loaded.
Point to existing isolated editor, controller, restart, and hook-safety
checks and the separate live speech/Braille acceptance requirements.

Validation for this documentation change:
- Reviewed the complete diff and ran git diff --check.
- Verified every installed helper file matches the standalone build.

Validation during the preceding installation repair:
- The old installed helper failed the isolated 32-bit editor check with
  missing character feedback; the current standalone build passed.
- Controller routing/SSML/service-loss checks passed.
- The 32-bit editor late-helper and helper-restart checks passed.
- Native hook-safety CTest passed for the actual hook DLLs.
- The reloaded helper exported WineReview, loaded its native 64-bit hook,
  and started the 32-bit host while the existing MUSHclient stayed open.
- The user confirmed that MUSHclient reading was restored. Physical
  Braille was not checked.

No helper source change was needed: the repaired installation uses the
existing standalone implementation. This commit preserves the recovery
procedure in tracked documentation.
This commit is contained in:
deedra committed 2026-10-20 02:45:08 -07:00
1 parent 3474bb39c7
commit a3b88ea670
1 file changed
+24
+24
View File
@@ -92,6 +92,30 @@ The helper is started automatically when Cthulhu-Go detects an active Wine
loader for the same user and prefix. It requires the selected reader service
to be running; it exits if that service is unavailable.
## Recovering an overwritten local helper
Older Python Cthulhu builds install a bundled helper at the same local path.
They can replace `cthulhu-wine-access.exe` and its `.exe.so` sidecar while leaving
this project's native hook files in place. A running helper and a working D-Bus
connection therefore do not establish that the standalone menu and editor
support is installed. Missing MUSHclient menu or command-field feedback can be
caused by this installation mismatch.
From this standalone repository, rebuild and install the complete five-file
helper set using `./build.sh`, then reload Cthulhu from its original desktop
session. Keep the launcher, sidecar, both hook DLLs, and 32-bit host from the same
build together. Updating only the reader executable does not update this helper.
For diagnosis, verify the running helper's executable path and session bus,
compare installed files with the standalone build, and check that
`wine-access-menu-host32.exe` is running for 32-bit editor support. Hook DLLs
already loaded into an application remain pinned; save work and restart that
Wine application after replacing those DLLs. Check MUSHclient menus, command
typing, and incoming plugin speech after recovery. The isolated editor,
controller, helper-restart, and hook-safety checks in
[tests/README.md](tests/README.md) cover the corresponding automated paths;
audible speech and physical Braille require live verification.
## Reader selection and Orca integration
The default invocation and `--reader cthulhu` use the existing Cthulhu endpoint.