Repository navigation
Live mode: name the missing VoiceOver download and Full Disk Access instead of blaming automation - #50
Merged
Elizabeth1979 merged 3 commits intoNov 15, 2026
Conversation
…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>
Merged
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this fixes
On macOS 27,
screenreader live readfailed 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 installdownloads into a cache. Two real causes hid behind the same message:~/Library/Group Containers/group.com.apple.VoiceOver. macOS privacy protection refuses that withEPERMunless the app running the terminal has Full Disk Access.What changes for users
Before (both cases):
After, case 1. The pre-check now catches it before a browser or VoiceOver starts:
The
cdmatters.setup installreads 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
preflightLiveModealso checks for the exact file Guidepup will mount. It uses Guidepup's own rule: the cache path (honouringGUIDEPUP_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.explainStartFailurerecognises "Failed to mount Guidepup preferences" and walks the error's cause chain forEPERM.Testing
npm test: full suite, 176 tests, 176 pass, 0 fail.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; anEPERMchain names Full Disk Access.GUIDEPUP_SCREEN_READERS_PATHset 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