cthulhu/docs/testing/tentacle-updates.md

Tentacle update verification

Refresh an installed Tentacle's repository in Preferences, select the Tentacle, and choose Update. The confirmation displays both versions and the old and new capabilities. Cancel must leave the installation unchanged. Update preserves enablement at the point the package is saved, including a disable requested while downloading.

Versions use dotted numeric components, optional prerelease identifiers and optional build metadata. Missing numeric components compare as zero; build metadata does not make a release newer. Invalid versions are not offered as updates. Downloads retain the existing HTTPS, checksum and manifest checks.

An enabled replacement must register and activate before success is reported. Startup failure or cancellation attempts to restore the previous package and enablement. Recovery persistence errors are reported explicitly. Retired files remain until their session has stopped. A disabled package is replaced without starting it.

Automated checks:

go test ./internal/tentacle ./internal/app -run 'Test.*(Upgrade|Update|Version)' -count=1
go build -o /tmp/cthulhu-update-check ./cmd/cthulhu
CTHULHU_BINARY=/tmp/cthulhu-update-check CTHULHU_PREFS_TENTACLE_UPDATES_ONLY=1 python3 tests/native_preferences.py

The GTK harness uses fixture data and a private display/bus, checks Tab and Shift+Tab, confirmation details, Cancel and the upgrade request, and does not update installed packages. Lifecycle tests exercise activation and rollback.

For live acceptance:

1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G to rebuild and launch it. These are separate key presses.
2. Open Preferences and select an installed test Tentacle with a newer release. Refresh its repository, then Tab to Update and use Shift+Tab to return. Expect accessible control names in speech/Braille and no keyboard trap.
3. Activate Update. Verify versions and capabilities are readable, then Cancel. Verify the installed version and existing shortcuts still work.
4. If you intend to install that release, reopen Update and accept. Verify the new version, its shortcuts and its previous enabled/disabled state. Close and reopen Preferences to verify persistence.
5. Record exact speech, Braille, focus and keyboard results for discrepancies.