Skip to content

Live mode: name the missing VoiceOver download and Full Disk Access instead of blaming automation - #50

Merged
Elizabeth1979 merged 3 commits into
Elizabeth1979:mainfrom
elizabeth-patrick:fix/live-missing-voiceover-prefs
Nov 15, 2026
Merged

Elizabeth1979 merged 3 commits into
Elizabeth1979:mainfrom
elizabeth-patrick:fix/live-missing-voiceover-prefs

Conversation

@elizabeth-patrick

Copy link
Copy Markdown
Contributor

What this fixes

On macOS 27, screenreader live read failed with "Failed to mount Guidepup preferences … Check that automation is permitted". The advice was wrong both times it happened, and it sent the user to automation and privacy settings that were not involved.

From Guidepup 0.36, VoiceOver starts with a settings file (a disk image), one per macOS version, that npx @guidepup/setup install downloads into a cache. Two real causes hid behind the same message:

  1. The settings file for this macOS was never downloaded. A Mac upgraded to macOS 27 still had only the macOS 26 file in its cache.
  2. macOS blocked the symlink step. Guidepup links into ~/Library/Group Containers/group.com.apple.VoiceOver. macOS privacy protection refuses that with EPERM unless the app running the terminal has Full Disk Access.

What changes for users

Before (both cases):

The screen reader did not finish starting. Check that automation is permitted (npx @guidepup/setup setup).

After, case 1. The pre-check now catches it before a browser or VoiceOver starts:

Live mode cannot start VoiceOver yet: a one-time download is missing.
…needs its VoiceOver settings file for this macOS (Darwin 27.2.0), and it is not on this machine:
  ~/Library/Caches/guidepup/voiceover/27/0.1.0-VoiceOver4/guidepup-voiceover-preferences-xcode-27.dmg
This is not a permissions problem. Download it with:
  cd "<this tool's install folder>" && npx @guidepup/setup install voiceover

The cd matters. setup install reads the manifest of whichever Guidepup it finds from the folder it runs in, so run anywhere else, it downloads files for a different Guidepup, or none.

After, case 2. It names Full Disk Access for the app the terminal runs in.

How

  • preflightLiveMode also checks for the exact file Guidepup will mount. It uses Guidepup's own rule: the cache path (honouring GUIDEPUP_SCREEN_READERS_PATH), then the manifest asset for this Darwin major version. The manifest is read from the installed Guidepup, so the two cannot disagree. If there is no manifest (an older Guidepup) or the release isn't listed, it doesn't block; Guidepup's own "not supported" path covers that.
  • explainStartFailure recognises "Failed to mount Guidepup preferences" and walks the error's cause chain for EPERM.
  • Everything that reads the machine can be swapped out in tests (platform, release, file check, manifest, cache path), so the tests run on Linux CI.

Testing

  • npm test: full suite, 176 tests, 176 pass, 0 fail.
  • New tests in test/live.test.js: missing file refuses with the right path and command; file present passes; an unlisted release doesn't block; the cache-path override; a mount failure points at the download; an EPERM chain names Full Disk Access.
  • On a real macOS 27.2 Mac: ran the CLI with GUIDEPUP_SCREEN_READERS_PATH set to an empty folder. It printed the new message and exited 1 before VoiceOver started. With the file downloaded and Full Disk Access granted, real VoiceOver live mode ran end to end.

🤖 Generated with Claude Code

Elizabeth1979 and others added 3 commits November 5, 2026 00:13
…ation

Guidepup 0.36+ mounts a per-macOS settings file that @guidepup/setup install
downloads. When it is missing, Guidepup says "Failed to mount Guidepup
preferences" and the old message pointed at automation permissions.

The preflight now checks for the exact file Guidepup will mount, using the
manifest Guidepup ships, and prints the install command with the folder it
must run from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Guidepup's mount step symlinks into ~/Library/Group Containers/group.com.apple.VoiceOver.
macOS privacy protection refuses that with EPERM unless the terminal's app has
Full Disk Access. Walk the cause chain and say so instead of suggesting a download.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Elizabeth1979
Elizabeth1979 merged commit 135daf5 into Elizabeth1979:main Nov 15, 2026
3 checks passed
@elizabeth-patrick elizabeth-patrick mentioned this pull request Nov 15, 2026
Elizabeth1979 added a commit that referenced this pull request Nov 15, 2026
Live mode names the missing VoiceOver settings download and Full Disk
Access instead of blaming automation (#50). Patch, not minor: the new
pre-check only refuses setups Guidepup would have refused anyway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants