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/<app>/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.terryli.maccy-backup. The launchd job had been failing daily with "Maccy DB unreadable" since 2026-04-17. Root cause: the spawn binary ~/eon/iterm2-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: