--- name: macos-fda-grant-helper-8eb22506c3a2 description: Interactive helper for granting macOS Full Disk Access (FDA) to a launchd-spawned binary. TRIGGERS - full disk access, fda grant, TCC permission, "Maccy DB unreadable", "operation not permitted" on sandbox-protected paths, launchd binary needs file access --- # macOS Full Disk Access Grant Walkthrough > **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues. > **What this skill is for**: when a launchd-spawned binary (or any non-interactive process) needs to read sandbox-protected paths like `~/Library/Containers//Data/...`, macOS TCC will deny the access until that specific binary is added to the **Full Disk Access** allowlist in System Settings → Privacy & Security → Full Disk Access. We cannot grant this programmatically — Apple's design — but we can automate everything **up to** the manual click. ## Why this exists Discovered iter 21 (2026-05-19) after the iter-20 fleet heartbeat finally surfaced a **32-day-old chronic failure** in `com.example.maccy-backup`. The launchd job had been failing daily with `"Maccy DB unreadable"` since 2026-04-17. Root cause: the spawn binary `~/eon/terminal-scripts/bin/maccy-backup/maccy-backup-runner` was not in the FDA allowlist. Interactive shells (iTerm2, Warp, Terminal, mise binaries) all WERE — that's why running the script manually from a terminal succeeds, hiding the problem from casual debugging. Without this helper, the click-path is buried four levels deep in System Settings, and the absolute binary path has to be typed by hand. The helper makes it a 30-second manual operation instead of "10 minutes of fumbling, abandoned, fails for another week." ## How it works `fda-grant-walkthrough` performs four steps: 1. **Resolves** the binary path to its absolute canonical form (System Settings stores absolute paths) 2. **Checks** the current TCC database for an existing grant (fast-exits if already granted) 3. **Copies** the absolute path to the macOS clipboard via `pbcopy` 4. **Opens** System Settings directly to the FDA pane via `x-apple.systempreferences://...` The user then clicks **+** → Cmd+Shift+G → Cmd+V → Enter → select binary → toggle ON → authenticate. After the grant, `--check` mode confirms the new state without opening any UI. ## Usage ```bash # Full walkthrough — opens UI, copies path fda-grant-walkthrough ~/eon/terminal-scripts/bin/maccy-backup/maccy-backup-runner # Check-only — useful in scripts / CI / heartbeat-class probes if fda-grant-walkthrough --check /path/to/binary; then echo "FDA already granted — proceed" else echo "FDA needed — see exit code 3" fi ``` ### Exit codes | Exit | Meaning | | ---- | --------------------------------------------------------------------------- | | 0 | Binary already has FDA (or walkthrough launched successfully) | | 1 | Usage error (no path given, etc.) | | 2 | Binary does not exist or is not executable | | 3 | (--check only) Binary does NOT have FDA, OR caller lacks FDA to read TCC.db | ## Install ```bash ln -sf "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/devops-tools/skills/macos-fda-grant-helper/scripts/fda-grant-walkthrough.sh" ~/.local/bin/fda-grant-walkthrough ``` ## Worked example — fixing the chronic maccy-backup failure ```bash # 1. Run the walkthrough (System Settings opens; path on clipboard) fda-grant-walkthrough ~/eon/terminal-scripts/bin/maccy-backup/maccy-backup-runner # 2. In Settings: + → Cmd+Shift+G → Cmd+V → Enter → toggle ON → Touch ID # 3. Verify the grant landed fda-grant-walkthrough --check ~/eon/terminal-scripts/bin/maccy-backup/maccy-backup-runner # 4. Restart the failing launchd job and watch for green launchctl kickstart -p gui/$(id -u)/com.example.maccy-backup tail -f ~/.local/state/maccy-backup/logs/backup-$(date +%Y%m%d).log # 5. Tomorrow morning, fleet heartbeat (iter 20) should drop from WARN to INFO # because failed_services no longer includes com.example.maccy-backup=1 ``` ## Why we can't fully automate the grant macOS TCC enforces a human-authenticated boundary on FDA changes. There's no public API for `tccutil` to ADD entries — only RESET them. Even MDM (Mobile Device Management) profiles can pre-authorize FDA only for system-distributed apps, not for arbitrary user-compiled binaries. The walkthrough is therefore the optimum: 95% automated (path resolution, clipboard, UI navigation), 5% manual (the click + Touch ID). ## When to use this skill - A launchd job is failing with "Operation not permitted" or "DB unreadable" or "permission denied" on paths under `~/Library/Containers/` - A compiled Swift/Go binary needs to read app-private files (Maccy clipboard DB, Messages chat DB, Mail mbox, etc.) - You want a scripted way to check whether a given binary has FDA without opening any UI (use `--check`) ## Related - iter-20 fleet daily heartbeat — surfaced maccy-backup as the test case for this helper - macOS Privacy & Security framework: [Apple docs](https://support.apple.com/guide/mac-help/control-access-to-files-and-folders-on-mac-mchld5a35146/mac) - TCC database schema: ## Post-Execution Reflection After granting FDA via this helper, check: 1. **Did `--check` confirm the grant?** — Run after toggling ON; if it still returns exit 3, the toggle may not have stuck (try toggling OFF/ON again with auth). 2. **Did the dependent launchd job recover?** — Kickstart the job and verify the next log line shows the protected path was read successfully. 3. **Does the fleet heartbeat reflect the fix the next morning?** — The iter-20 heartbeat reports failed services; a successful FDA grant should drop the entry within a day. --- Source attribution: terrylica Original project: https://github.com/terrylica/cc-skills/blob/05b229e90559a414af83b5e29fc3bda1f73f8213/plugins/devops-tools/skills/macos-fda-grant-helper/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 terrylica Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: terrylica Original project: https://github.com/terrylica/cc-skills/blob/05b229e90559a414af83b5e29fc3bda1f73f8213/plugins/devops-tools/skills/macos-fda-grant-helper/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering Roles: Backend Developer, DevOps / SRE Specialties: Backend Tools: Macos Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 874125baeae1bf8abc78c8be5936ec7da538a8beecd2389f0835bf64dc402c68