Folders are empty or refused on macOS

You open the folder picker on your Mac, click Desktop (or Documents, or Downloads), and Qorin says something like:

macOS is hiding this folder from Qorin.

Or the folder opens but looks empty, when you can plainly see files in it in Finder.

This is macOS privacy protection, not a Qorin bug and not a problem with your account. It takes about thirty seconds to fix, once.

Why it happens

macOS has a privacy layer called TCC — the thing that makes apps ask "…would like to access files in your Desktop folder". It sits above UNIX permissions and answers a different question: not which user is asking, but which program is asking.

That matters here, because of two things that are both true:

1. The Qorin agent runs as a system service that starts at boot — that's what lets you reach your Mac from your phone whether or not you're sitting in front of it (ADR-022).
2. A service that starts before anyone logs in has no screen to put a window on. So macOS never asks you.

No question means no consent, and no consent means a refusal — silently, for as long as the machine exists. You never see anything to approve, so you never find out there was anything to approve.

This is not about your UNIX account

The folder is yours. The permission bits say yes. Granting yourself more UNIX rights, changing your mapped user, or asking an administrator will not change anything — none of them is the layer saying no.

Which folders

Only some, and it's a fixed list from Apple:

Protected — needs the permission	Not protected — works out of the box
Desktop, Documents, Downloads	Folders you created yourself: ~/Projects, ~/dev, ~/code, …
iCloud Drive	/opt, /usr/local, /srv
External and network volumes	/tmp
Other users' home folders	Anything under a path you added as a browse root

If your projects live in a folder you made yourself, you will probably never meet this at all. That is also the simplest workaround: keep the code somewhere like ~/Projects and nothing else is needed.

The fix: Full Disk Access for the agent

You are granting it to the binary, not to yourself — TCC evaluates the program.

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Click +. A file picker opens.
3. The binary lives in /usr/local/bin, which the picker hides. Press ⌘⇧G, type /usr/local/bin/qorin-agent, and press Return.
4. Make sure its switch is on.
5. Restart the service so it picks up the new permission:

sudo qorin-agent restart

Open the folder picker again — Desktop, Documents and Downloads are there.

The restart is not optional

macOS decides a process's privacy rights when it starts. An agent that was already running when you flipped the switch keeps the old answer until it restarts.

Check it without guessing

From macOS agent build 67 onwards, qorin-agent doctor tests this directly — it tries to read the protected folders and tells you what it found, instead of assuming:

qorin-agent doctor

  ✓ macOS protected folders        readable from /Users/you

or, when the permission is missing:

  ✗ macOS protected folders        macOS is blocking Desktop, Documents, Downloads — open
                                   System Settings › Privacy & Security › Full Disk Access,
                                   add /usr/local/bin/qorin-agent, then `sudo qorin-agent restart`

If your agent is older, the dashboard offers Update on the host — see Agent hosts.

Related

• The "Local Network" permission macOS 15 asks about is not involved. The agent connects outward to api.qorin.dev over the public internet; it does not scan or call anything on your LAN. If macOS offers you that prompt, Qorin does not need it.
• If the folder isn't protected and Qorin still refuses it, the refusal is a real UNIX one and names the account it used — see Workspace fails to spawn.