Onboarding: get Cmdr into the Full Disk Access list on macOS 13+ by probing a protected directory

On macOS 13+ (Tahoe especially) a notarized app no longer appears in System Settings → Privacy & Security → Full Disk Access from our probe, so users had to add Cmdr by hand with "+". Traced the cause against Path Finder: its whole FDA probe is a raw `open()` on the `~/Library/Mail` *directory*, and it lands in the list the instant it does. A denied file `read()` (what Cmdr did) stopped registering notarized bundles on Tahoe; a denied directory `open()` still does.

- `permissions.rs`: on a denied probe, `check_full_disk_access` now also fires a raw `open()` on each existing protected directory (`fda_probe_dirs`: `~/Library/Mail`, `~/Library/Safari`, `~/Library/Messages`, and the always-present TCC dir) via the new `try_open_path`. Detection logic is unchanged: the file reads still decide granted/denied, so there's no behavior risk there. We keep the file/`mmap`/`NSData`/`read_dir` triggers for macOS 12 and earlier, where the file `read()` is what registered.
- Corrected the now-falsified docs: the old "Tahoe short-circuits `read()` denials" framing in `onboarding/DETAILS.md` and `docs/architecture.md` was wrong; it's specifically that file reads don't register but directory opens do.
- The quiet 500 ms poller stays side-effect-free (file reads only); registration rides on the heavy probe, which fires at boot, on onboarding mount, and right before opening System Settings.

Verification is deferred to the next release: this only manifests on a real notarized build, so reset the TCC state (`tccutil reset SystemPolicyAllFiles com.veszelovszki.cmdr`) and confirm Cmdr appears in the list after launch. The "+" step-tip stays as a backstop.

Author: vdavid

apps/desktop/src-tauri/src/permissions.rs

@@ -6,20 +6,20 @@ use std::io::{ErrorKind, Read};
 use std::os::unix::ffi::OsStrExt;
 use std::path::{Path, PathBuf};
 
-/// Specific TCC-protected files we probe to determine FDA status.
+/// Specific TCC-protected files we probe to determine FDA status, and (on
+/// older macOS) to register the bundle in the Full Disk Access list.
 ///
-/// We `open()` + `read()` actual *files*, not directory listings: TCC's
-/// registration hook fires on read syscalls into protected paths, not on
-/// `opendir()`. A `read_dir` attempt against a protected directory may be
-/// silently denied without ever adding the bundle to System Settings → Privacy
-/// & Security → Full Disk Access. Even `open()` alone has been observed not
-/// to register the bundle on some macOS versions; the actual `read()` is
-/// what reliably triggers `tccd`.
+/// We `open()` + `read()` actual *files*: a denied `read()` is what added the
+/// bundle to System Settings → Privacy & Security → Full Disk Access on macOS
+/// 12 and earlier. On macOS 13+ (Tahoe especially) that stopped working for
+/// notarized apps: the denied file `read()` is refused without listing the
+/// app, and the access that DOES register is now a raw `open()` on a protected
+/// *directory* (see `fda_probe_dirs`). We keep both: file reads for old macOS,
+/// directory opens for current macOS.
 ///
 /// Order matters: we walk until we hit a file that exists on this account,
-/// because `NotFound` doesn't trigger TCC. Once we hit one, the read attempt
-/// either succeeds (FDA granted) or returns `PermissionDenied` (FDA not
-/// granted, bundle now registered with TCC).
+/// because `NotFound` doesn't reach TCC. Once we hit one, the read either
+/// succeeds (FDA granted) or returns `PermissionDenied` (not granted).
 fn fda_probe_files() -> Vec<PathBuf> {
     let Some(home) = dirs::home_dir() else {
         return Vec::new();
@@ -34,6 +34,27 @@ fn fda_probe_files() -> Vec<PathBuf> {
     ]
 }
 
+/// Protected TCC *directories* we `open()` (read-only, no read) to register the
+/// bundle in the Full Disk Access list on macOS 13+ (Ventura/Sonoma/Tahoe).
+///
+/// On Tahoe a denied file `read()` no longer lists a notarized bundle, but a
+/// raw `open()` on a TCC-protected directory still does (verified against Path
+/// Finder, which polls `open(~/Library/Mail)` and lands in the list the instant
+/// it does). Use a raw `open()`, NOT `opendir`/`read_dir`: the latter doesn't
+/// register. The TCC dir always exists; the rest cover the common case where
+/// the user has Mail/Safari/Messages set up.
+fn fda_probe_dirs() -> Vec<PathBuf> {
+    let Some(home) = dirs::home_dir() else {
+        return Vec::new();
+    };
+    vec![
+        home.join("Library/Mail"),                              // present for Mail users
+        home.join("Library/Safari"),                            // present after Safari use
+        home.join("Library/Messages"),                          // present for Messages users
+        home.join("Library/Application Support/com.apple.TCC"), // always exists, TCC-protected
+    ]
+}
+
 /// Tries to open `path` and read at least one byte from it. The read is what
 /// trips TCC; `open()` alone has been observed not to register the bundle.
 fn try_read_byte(path: &Path) -> std::io::Result<()> {
@@ -46,6 +67,15 @@ fn try_read_byte(path: &Path) -> std::io::Result<()> {
     Ok(())
 }
 
+/// Tries to `open()` `path` read-only without reading from it. This is the
+/// access that lists the bundle in Full Disk Access on macOS 13+ when `path` is
+/// a protected directory (mirrors Path Finder's `open(~/Library/Mail)`). Works
+/// on dirs and files; we deliberately don't `read()` (a directory read returns
+/// `EISDIR`). The `Err(PermissionDenied)` case is the FDA denial that registers.
+fn try_open_path(path: &Path) -> std::io::Result<()> {
+    File::open(path).map(|_| ())
+}
+
 /// Tries to mmap the first byte of `path`. Different syscall path than
 /// `read()` (mmap goes through the VM subsystem); on some macOS versions
 /// this is observed to trigger tccd registration where plain `read()`
@@ -181,11 +211,12 @@ pub fn check_full_disk_access_quiet() -> bool {
 ///
 /// Probing is also how the bundle gets registered with TCC, which is what
 /// makes Cmdr show up in the Full Disk Access list in System Settings. On
-/// macOS 26 (Tahoe), the kernel/sandbox can short-circuit `read()` denials
-/// without consulting tccd, leaving the bundle out of the FDA list. To
-/// maximize the chance one of the access paths threads the needle, on a
-/// denial we fire all three: raw `read`, `mmap`, `NSData`, plus a
-/// `read_dir` of the parent directory.
+/// macOS 13+ (Tahoe especially) a denied file `read()` no longer lists a
+/// notarized bundle: the access that registers is a raw `open()` on a
+/// protected *directory* (what Path Finder uses). So on a denial we fire every
+/// trigger we know: the legacy file `mmap` / `NSData` / parent `read_dir` (old
+/// macOS), plus a directory `open()` on each protected dir (macOS 13+; see
+/// `fda_probe_dirs`).
 ///
 /// For repeated, side-effect-free polling (e.g. the onboarding grant
 /// detector), use `check_full_disk_access_quiet` instead, which skips these
@@ -230,6 +261,20 @@ pub fn check_full_disk_access() -> bool {
                         log::debug!(target: "fda_probe", "FDA probe extra: read_dir(parent of {:?}) → {} ({:?})", path, e, e.kind())
                     }
                 }
+                // macOS 13+/Tahoe: a raw open() on a protected DIRECTORY is the
+                // access that actually lists the bundle in Full Disk Access (the
+                // file read above no longer registers notarized apps there). Fire
+                // it on every existing protected dir. See `fda_probe_dirs`.
+                for dir in fda_probe_dirs() {
+                    match try_open_path(&dir) {
+                        Ok(()) => {
+                            log::debug!(target: "fda_probe", "FDA probe extra: open dir {:?} OK (FDA actually granted? unexpected)", dir)
+                        }
+                        Err(e) => {
+                            log::debug!(target: "fda_probe", "FDA probe extra: open dir {:?} → {} ({:?})", dir, e, e.kind())
+                        }
+                    }
+                }
                 return false;
             }
             Err(e) => {

apps/desktop/src/lib/ipc/bindings.ts

@@ -2214,11 +2214,12 @@ export const commands = {
    *
    *  Probing is also how the bundle gets registered with TCC, which is what
    *  makes Cmdr show up in the Full Disk Access list in System Settings. On
-   *  macOS 26 (Tahoe), the kernel/sandbox can short-circuit `read()` denials
-   *  without consulting tccd, leaving the bundle out of the FDA list. To
-   *  maximize the chance one of the access paths threads the needle, on a
-   *  denial we fire all three: raw `read`, `mmap`, `NSData`, plus a
-   *  `read_dir` of the parent directory.
+   *  macOS 13+ (Tahoe especially) a denied file `read()` no longer lists a
+   *  notarized bundle: the access that registers is a raw `open()` on a
+   *  protected *directory* (what Path Finder uses). So on a denial we fire every
+   *  trigger we know: the legacy file `mmap` / `NSData` / parent `read_dir` (old
+   *  macOS), plus a directory `open()` on each protected dir (macOS 13+; see
+   *  `fda_probe_dirs`).
    *
    *  For repeated, side-effect-free polling (e.g. the onboarding grant
    *  detector), use `check_full_disk_access_quiet` instead, which skips these

apps/desktop/src/lib/onboarding/DETAILS.md

@@ -333,11 +333,14 @@ wizard's footer remains consistent for the other steps (Back + Next / Finish / R
 - **Deep-link host changed in Ventura.** macOS 13+ uses `com.apple.settings.PrivacySecurity.extension`; older macOS uses
   `com.apple.preference.security`. `openPrivacySettings()` picks via `get_macos_major_version`. The same version informs
   the modal copy: macOS 12 and older append new FDA entries at the end of the list (instead of alphabetical).
-- **macOS 26 (Tahoe) FDA auto-add is broken.** Even with a notarized Developer ID build at `/Applications/Cmdr.app`, the
-  kernel / sandbox can short-circuit `read()` denials on TCC-protected paths without consulting `tccd`, meaning Cmdr may
-  not enter the FDA list automatically. The "+" button fallback (documented in step 1's `step-tip`) is the user-side
-  workaround. References: [Apple Developer Forums #809549](https://developer.apple.com/forums/thread/809549),
-  [Backrest issue #986](https://github.com/garethgeorge/backrest/issues/986),
+- **macOS 13+ (Tahoe) lists the app on a directory `open()`, not a file `read()`.** On macOS 12 a denied file `read()`
+  of a TCC-protected path registered a notarized bundle in the FDA list. On macOS 13+ (Tahoe especially) that read is
+  refused without listing the app; the access that still registers is a raw `open()` on a protected _directory_ (traced
+  from Path Finder, which polls `open(~/Library/Mail)` and lands in the list the instant it does). So
+  `check_full_disk_access` in `permissions.rs` fires directory opens (`fda_probe_dirs`: `~/Library/Mail`, the TCC dir,
+  etc.) alongside the legacy file `mmap` / `NSData` / `read_dir` triggers. The "+" button fallback (step 1's `step-tip`)
+  stays as a backstop for any machine that still doesn't list Cmdr. References:
+  [Apple Developer Forums #809549](https://developer.apple.com/forums/thread/809549),
   [Apple Developer Forums #757768](https://developer.apple.com/forums/thread/757768).
 - **The wizard renders the app behind it.** First launch lands on `~`, so what peeks through the backdrop is friendly.
   No "white screen until wizard done" code path.

docs/architecture.md

@@ -202,9 +202,10 @@ Rules that cut across many modules. All existing commands follow these; apply th
 
 - **Full Disk Access**: checked by trying to read 1 byte from a list of TCC-protected files
   (`~/Library/Safari/History.db`, `~/Library/Mail/V10/MailData/Envelope Index`, etc.) until one returns either `Ok` (FDA
-  granted) or `PermissionDenied` (denied; bundle gets registered with TCC). On denial, also fires `mmap` +
-  `NSData dataWithContentsOfFile:` + `read_dir` of the parent (multi-trigger fallback because macOS 26 (Tahoe) can
-  short-circuit `read()` denials without consulting tccd). Prompt on first launch. See
+  granted) or `PermissionDenied` (denied). Listing the app in System Settings is a separate concern: on macOS 12 the
+  denied file `read()` registered it, but on macOS 13+ (Tahoe) only a raw `open()` on a protected _directory_
+  (`~/Library/Mail`, the TCC dir, etc.) registers a notarized app, so on denial we fire that plus the legacy `mmap` /
+  `NSData` / `read_dir` triggers. Prompt on first launch. See `permissions.rs` and
   `apps/desktop/src/lib/onboarding/CLAUDE.md`.
 - **Keychain**: stores network credentials and trial state. Uses `security-framework` crate.
 - **copyfile(3)**: preserves xattrs, ACLs, resource forks. `COPYFILE_CLONE` for instant APFS clones.