feat(ui): guide macOS users to grant Full Disk Access when files are denied

A TCC denial is invisible from the user's side: the backup "succeeds",
some files just never reach Drive. Add a root-mounted dismissible banner
that latches on the first local.permission_denied activity row, counts
DISTINCT files (a denial is permanent, so the same file is re-reported
every cycle, unbounded), and offers a one-click deep link to the Full
Disk Access pane.

The deep link needs an explicit opener capability scope: opener:default
only permits mailto/tel/http/https, so a custom scheme would throw at
runtime while every mocked test still passed.

Document in README and DESIGN s5.3.3 that APFS snapshots do NOT bypass
TCC, and that an unsigned binary's TCC grant can silently invalidate on
update because macOS binds the grant to the code signature.

Author: pmaxhogan

README.md

@@ -139,6 +139,9 @@ These move: check each project's current docs before relying on a cell.
   selector.
 - Anonymous, opt-out telemetry (coarse counts only; never file names, paths, or
   content).
+- Guided Full Disk Access onboarding for macOS: when macOS privacy protection
+  blocks a file, Driven says so and offers a one-click jump to the right
+  System Settings pane instead of leaving you to find it.
 
 <!--
 DRAFT - do not uncomment until the corresponding PR merges. Flip each bullet
@@ -147,9 +150,6 @@ on individually as its PR lands, then delete this comment wrapper.
   unmerged - depends on the pluggable-backend seam / `driven-remote` crate,
   #200, also unmerged.)
 - Local / removable-drive backup destination. (unmerged - same seam as above.)
-- Guided Full Disk Access onboarding for macOS, so Driven walks you through
-  granting access to Mail / Messages / Photos instead of requiring a manual
-  System Settings visit. (#205, unmerged.)
 - Scheduled integrity scrub that periodically re-verifies already-backed-up
   files against the destination. (unmerged.)
 - Restore drill: a one-click "prove the backup actually restores" check.
@@ -204,9 +204,32 @@ Disk Access. A file in that state fails to open with a permission error, not a
 "file is busy" error, and Driven reports it in the activity log rather than
 silently skipping it or silently backing it up.
 
-There is currently no in-app guided flow for granting Full Disk Access - that
-is planned for a future release. Until then, grant it manually if you want
-those folders backed up; everything else backs up normally without it.
+Driven notices this and offers the fix. The first time a backup is refused,
+a banner appears with a button that opens the Full Disk Access pane directly.
+You can dismiss it; everything else backs up normally without the grant.
+
+To grant it:
+
+1. Click **Open Full Disk Access settings** in Driven's banner, or from a
+   terminal:
+
+   ```sh
+   open 'x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles'
+   ```
+
+2. Add Driven with the `+` button (or drag `Driven.app` in) and switch it on.
+3. Quit and reopen Driven. A grant only applies to a newly launched process,
+   so the running app keeps skipping until you restart it.
+
+**The grant can stop working after an update, because Driven is unsigned.**
+macOS ties Full Disk Access to the binary's code signature (its cdhash), not
+to its name or path. Driven's builds are not signed with a Developer ID, so
+every update is a different program as far as the privacy system is concerned.
+After installing one, the grant may quietly stop applying and the skips come
+back - even though Driven is still listed under Full Disk Access with its
+switch on. The fix is to remove the stale Driven entry from that list, add the
+new app, and relaunch. This is a consequence of the missing code signature
+rather than a bug, and it goes away once macOS code signing lands.
 
 **A locked-file snapshot is not a substitute for Full Disk Access, and Driven
 never tries to make it one.** Driven's locked-file handling (Windows VSS,

design/DESIGN.md

@@ -798,6 +798,61 @@ patched, and now an EDR-flagged signature we deliberately do not emit. A
 `local.permission_denied` file needs Full Disk Access; no snapshot setting
 substitutes for it.
 
+#### 5.3.3 Full Disk Access onboarding (macOS)
+
+The remedy s5.3.2 cannot provide. A `local.permission_denied` skip means TCC
+refused the read, and the ONLY fix is the user granting Driven Full Disk
+Access. So the UI has to ask, and has to ask well: the failure is silent
+from the user's point of view (the backup "succeeds", some files just never
+appear), and the error text alone does not tell them where to go.
+
+**Trigger.** A root-mounted banner subscribes to the `activity:new` stream
+and latches on the first row whose `event_type` is `local.permission_denied`.
+It is root-mounted (the `ToastHost` pattern) rather than living on a single
+view, so a denial during a background cycle is not missed just because the
+user happens to be on another tab. There is deliberately no per-cycle
+bookkeeping: a denial is PERMANENT until the user acts, unlike a lock, so
+"has this ever happened" is the right question and a sticky latch is the
+right shape. Gating on the `backup_done` row would have been wrong twice
+over - failed ops suppress it, and it is emitted per source, not per cycle.
+
+**Deduplication.** Because a denial is permanent, the same file produces one
+warn row EVERY cycle, forever - an unbounded stream. The banner therefore
+counts DISTINCT files, not rows, so a file denied across fifty cycles is
+reported once. This aggregation lives purely in the display layer; neither
+the executor's emission nor the activity store changes, so the raw rows stay
+available for diagnostics.
+
+**The deep link.** The banner's primary action opens the Full Disk Access
+pane directly via
+`x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`.
+Two things make this work and both are load-bearing: the anchor is
+version-sensitive (a wrong or stale one silently lands the user on the
+generic Privacy & Security list, which is why it is verified against a
+control rather than assumed), and the custom scheme must be added to the
+opener plugin's capability scope - `opener:default` only permits
+`mailto:`/`tel:`/`http`/`https`, so without an explicit
+`opener:allow-open-url` scope entry the button would throw at runtime while
+every mocked test still passed.
+
+**Dismissal is per-session, on purpose.** The banner is dismissible, but the
+dismissal is in-memory and does not persist across restarts (matching the
+one existing dismissible-banner precedent, the updater's). That is the
+correct semantic here rather than a shortcut: the underlying condition is
+unresolved until FDA is granted, so permanently silencing it would hide a
+real, ongoing data-coverage gap. Once the grant is in place the denials stop
+and the banner stops appearing on its own.
+
+**The unsigned-binary caveat is part of the copy, not a footnote.** macOS
+binds a TCC grant to the binary's code signature (its cdhash), not its path.
+Driven's V1 builds are unsigned, so every update is a different program as
+far as TCC is concerned and a previously working grant can silently stop
+applying - the app still appears in the Full Disk Access list, switch on,
+while being denied. This is a recurring, confusing support case rather than
+a hypothetical, so the banner states it in one line and the README explains
+the remove-and-re-add fix in full. It resolves itself when macOS code
+signing lands.
+
 ### 5.4 Upload pipeline
 
 Per-account:

src-tauri/capabilities/default.json

@@ -9,6 +9,10 @@
     "dialog:default",
     "updater:default",
     "process:default",
-    "opener:default"
+    "opener:default",
+    {
+      "identifier": "opener:allow-open-url",
+      "allow": [{ "url": "x-apple.systempreferences:*" }]
+    }
   ]
 }

ui/src/App.vue

@@ -3,6 +3,7 @@ import { onMounted } from "vue";
 import { useRoute } from "vue-router";
 import { useI18n } from "vue-i18n";
 
+import FdaBanner from "./components/FdaBanner.vue";
 import GlobalProgressBar from "./components/GlobalProgressBar.vue";
 import PausedBanner from "./components/PausedBanner.vue";
 import ToastHost from "./components/ToastHost.vue";
@@ -134,6 +135,11 @@ const NAV_LINK_ACTIVE = "text-teal-700 dark:text-teal-300 font-semibold";
     <header class="sticky top-0 z-30 bg-zinc-50 dark:bg-zinc-950" data-testid="app-header">
       <GlobalProgressBar />
       <PausedBanner />
+      <!-- macOS TCC (DESIGN s5.3.2): shown only once a read has actually been
+           refused, so it costs nothing on Windows/Linux. Lives in the sticky
+           header - and therefore mounts for the app's whole lifetime - so it
+           cannot miss the `activity:new` denial it subscribes to. -->
+      <FdaBanner />
       <nav
         class="flex flex-wrap items-center gap-x-6 gap-y-2 border-b border-zinc-200 bg-white px-6 py-3 text-sm dark:border-zinc-800 dark:bg-zinc-900"
         :aria-label="t('nav.primary')"

ui/src/__tests__/app-shell.test.ts

@@ -171,8 +171,9 @@ describe("App shell", () => {
     // progress store's TWO sync events (status_changed for the phase,
     // source_progress for the moving counters) + the pause event registered +
     // the two ToastHost subscriptions (status_changed for "Backup started",
-    // activity:new for the backup_done row behind "Backup complete").
-    expect(listenMock).toHaveBeenCalledTimes(8);
+    // activity:new for the backup_done row behind "Backup complete") + the
+    // FdaBanner's own activity:new subscription (the macOS TCC denial row).
+    expect(listenMock).toHaveBeenCalledTimes(9);
     expect(invokeMock).toHaveBeenCalledWith("get_pending_update_info", undefined);
     expect(invokeMock).toHaveBeenCalledWith("get_sync_status", undefined);
     expect(invokeMock).toHaveBeenCalledWith("get_pause_state", undefined);