From f56ac490aaee71efcbd794d621b9e5c57f5a8890 Mon Sep 17 00:00:00 2001
From: pmaxhogan <max@maxhogan.dev>
Date: Wed, 29 Jul 2026 12:03:29 -0500
Subject: [PATCH] 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.
---
 README.md                           |  35 +++-
 design/DESIGN.md                    |  55 ++++++
 src-tauri/capabilities/default.json |   6 +-
 ui/src/App.vue                      |   6 +
 ui/src/__tests__/app-shell.test.ts  |   5 +-
 ui/src/__tests__/fda-banner.test.ts | 263 ++++++++++++++++++++++++++++
 ui/src/components/FdaBanner.vue     | 110 ++++++++++++
 ui/src/locales/en-US.json           |   6 +
 ui/src/stores/fdaBanner.ts          |  89 ++++++++++
 9 files changed, 566 insertions(+), 9 deletions(-)
 create mode 100644 ui/src/__tests__/fda-banner.test.ts
 create mode 100644 ui/src/components/FdaBanner.vue
 create mode 100644 ui/src/stores/fdaBanner.ts

diff --git a/README.md b/README.md
index f47bda56..01bad98d 100644
--- a/README.md
+++ b/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,
diff --git a/design/DESIGN.md b/design/DESIGN.md
index 01e91f3e..0c065665 100644
--- a/design/DESIGN.md
+++ b/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:
diff --git a/src-tauri/capabilities/default.json b/src-tauri/capabilities/default.json
index 74d39672..f2d7223f 100644
--- a/src-tauri/capabilities/default.json
+++ b/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:*" }]
+    }
   ]
 }
diff --git a/ui/src/App.vue b/ui/src/App.vue
index b8233b90..58a13093 100644
--- a/ui/src/App.vue
+++ b/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')"
diff --git a/ui/src/__tests__/app-shell.test.ts b/ui/src/__tests__/app-shell.test.ts
index 6d2c6ab0..ba14a426 100644
--- a/ui/src/__tests__/app-shell.test.ts
+++ b/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);
diff --git a/ui/src/__tests__/fda-banner.test.ts b/ui/src/__tests__/fda-banner.test.ts
new file mode 100644
index 00000000..a4235ad0
--- /dev/null
+++ b/ui/src/__tests__/fda-banner.test.ts
@@ -0,0 +1,263 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { mount } from "@vue/test-utils";
+import { createPinia, setActivePinia } from "pinia";
+
+// FdaBanner tests: the wiring half (a BACKEND `activity:new` row carrying
+// `local.permission_denied` raises the banner) and the behaviour half (the
+// per-file dedupe that stops a re-scanned denial inflating the count every
+// cycle, the exact System Settings deep link, and the per-session dismiss).
+//
+// Two seams are mocked, both the way the existing tests mock them:
+// `@tauri-apps/api/event`'s `listen` is kept per channel so a test can play an
+// event into the mounted component exactly as Tauri would (toast-host.test.ts),
+// and `@tauri-apps/plugin-opener`'s `openUrl` is stubbed so asserting the deep
+// link never launches a real System Settings window (setup-wizard.test.ts).
+
+const handlers = new Map<string, (event: { payload: unknown }) => void>();
+const unlisten = vi.fn();
+
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: vi.fn(async () => undefined),
+}));
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async (name: string, handler: (event: { payload: unknown }) => void) => {
+    handlers.set(name, handler);
+    return unlisten;
+  }),
+}));
+
+const openUrlMock = vi.fn();
+vi.mock("@tauri-apps/plugin-opener", () => ({
+  openUrl: (url: string) => openUrlMock(url),
+}));
+
+import { i18n } from "../i18n";
+import FdaBanner from "../components/FdaBanner.vue";
+import { useFdaBannerStore } from "../stores/fdaBanner";
+
+const BANNER = '[data-testid="fda-banner"]';
+const OPEN = '[data-testid="fda-banner-open"]';
+const DISMISS = '[data-testid="fda-banner-dismiss"]';
+const UNSIGNED_NOTE = '[data-testid="fda-banner-unsigned-note"]';
+
+/** The one string this whole feature exists to deliver. A wrong anchor lands the
+ * user on the Privacy & Security root instead of Full Disk Access, which looks
+ * identical in a screenshot - hence asserting it literally. */
+const FDA_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
+
+/** One activity row, with the fields ActivityEntry declares. */
+function row(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 1,
+    ts: 1_700_000_000_000,
+    sourceId: "src-1",
+    level: "warn",
+    eventType: "local.permission_denied",
+    fileCount: null,
+    bytes: null,
+    message: "/Users/me/Documents/taxes.pdf",
+    ...overrides,
+  };
+}
+
+/** Play an `activity:new` event carrying one activity row. */
+function emitActivity(entry: Record<string, unknown>): void {
+  handlers.get("activity:new")?.({ payload: entry });
+}
+
+async function mountBanner() {
+  const pinia = createPinia();
+  setActivePinia(pinia);
+  const store = useFdaBannerStore();
+  const wrapper = mount(FdaBanner, { global: { plugins: [pinia, i18n] } });
+  // Let the onMounted `listen` call resolve so the handler is registered before
+  // a test plays an event.
+  await vi.waitFor(() => expect(handlers.has("activity:new")).toBe(true));
+  return { store, wrapper };
+}
+
+beforeEach(() => {
+  handlers.clear();
+  unlisten.mockClear();
+  openUrlMock.mockClear();
+  openUrlMock.mockResolvedValue(undefined);
+});
+
+describe("FdaBanner", () => {
+  it("shows nothing until macOS has actually refused a read", async () => {
+    const { wrapper } = await mountBanner();
+    expect(wrapper.find(BANNER).exists()).toBe(false);
+  });
+
+  it("appears when a local.permission_denied row arrives", async () => {
+    const { wrapper } = await mountBanner();
+
+    emitActivity(row());
+    await wrapper.vm.$nextTick();
+
+    const banner = wrapper.find(BANNER);
+    expect(banner.exists()).toBe(true);
+    expect(banner.text()).toContain("macOS is blocking Driven from reading some files");
+  });
+
+  it("ignores activity rows that are not permission denials", async () => {
+    const { store, wrapper } = await mountBanner();
+
+    emitActivity(row({ id: 2, eventType: "backup_done", message: null }));
+    emitActivity(row({ id: 3, eventType: "local.file_locked" }));
+    await wrapper.vm.$nextTick();
+
+    expect(store.deniedCount).toBe(0);
+    expect(wrapper.find(BANNER).exists()).toBe(false);
+  });
+
+  // A TCC denial is permanent, so the SAME file is re-denied and re-logged on
+  // every scan. Without the dedupe the banner would read "150 files" for one
+  // file after a day of cycles.
+  it("counts a file re-denied on every cycle exactly once", async () => {
+    const { store, wrapper } = await mountBanner();
+
+    for (const id of [10, 11, 12]) {
+      emitActivity(row({ id, message: "/Users/me/Documents/taxes.pdf" }));
+    }
+    await wrapper.vm.$nextTick();
+
+    expect(store.deniedCount).toBe(1);
+    expect(wrapper.find(BANNER).text()).toContain(
+      "macOS privacy protection is stopping Driven from reading 1 file."
+    );
+  });
+
+  it("counts two distinct files separately", async () => {
+    const { store, wrapper } = await mountBanner();
+
+    emitActivity(row({ id: 20, message: "/Users/me/Documents/taxes.pdf" }));
+    emitActivity(row({ id: 21, message: "/Users/me/Desktop/notes.txt" }));
+    await wrapper.vm.$nextTick();
+
+    expect(store.deniedCount).toBe(2);
+    expect(wrapper.find(BANNER).text()).toContain(
+      "macOS privacy protection is stopping Driven from reading 2 files."
+    );
+  });
+
+  it("opens the Full Disk Access pane with the exact deep link", async () => {
+    const { wrapper } = await mountBanner();
+    emitActivity(row());
+    await wrapper.vm.$nextTick();
+
+    await wrapper.find(OPEN).trigger("click");
+
+    expect(openUrlMock).toHaveBeenCalledTimes(1);
+    expect(openUrlMock).toHaveBeenCalledWith(FDA_URL);
+  });
+
+  it("stays up when the opener rejects", async () => {
+    openUrlMock.mockRejectedValue(new Error("no opener"));
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { wrapper } = await mountBanner();
+    emitActivity(row());
+    await wrapper.vm.$nextTick();
+
+    await wrapper.find(OPEN).trigger("click");
+    await wrapper.vm.$nextTick();
+
+    expect(wrapper.find(BANNER).exists()).toBe(true);
+    errorSpy.mockRestore();
+  });
+
+  // Dismissal must survive the very next cycle's denial rows, or the button
+  // would be useless: a denied file is re-reported minutes later, forever.
+  it("stays dismissed when further denials arrive", async () => {
+    const { store, wrapper } = await mountBanner();
+    emitActivity(row({ id: 30, message: "/Users/me/Documents/taxes.pdf" }));
+    await wrapper.vm.$nextTick();
+
+    await wrapper.find(DISMISS).trigger("click");
+    expect(wrapper.find(BANNER).exists()).toBe(false);
+
+    emitActivity(row({ id: 31, message: "/Users/me/Documents/taxes.pdf" }));
+    emitActivity(row({ id: 32, message: "/Users/me/Pictures/scan.png" }));
+    await wrapper.vm.$nextTick();
+
+    expect(wrapper.find(BANNER).exists()).toBe(false);
+    // The denials still COUNT while hidden, so a later reset shows the truth.
+    expect(store.deniedCount).toBe(2);
+  });
+
+  it("explains that an unsigned build can lose the permission on update", async () => {
+    const { wrapper } = await mountBanner();
+    emitActivity(row());
+    await wrapper.vm.$nextTick();
+
+    const note = wrapper.find(UNSIGNED_NOTE);
+    expect(note.exists()).toBe(true);
+    expect(note.text()).toContain("not signed yet");
+    expect(note.text()).toContain("remove Driven from the Full Disk Access list and add it back");
+  });
+
+  it("labels its actions", async () => {
+    const { wrapper } = await mountBanner();
+    emitActivity(row());
+    await wrapper.vm.$nextTick();
+
+    expect(wrapper.find(OPEN).text()).toBe("Open Full Disk Access settings");
+    expect(wrapper.find(DISMISS).text()).toBe("Close");
+  });
+
+  it("unsubscribes from the activity stream when it unmounts", async () => {
+    const { wrapper } = await mountBanner();
+    wrapper.unmount();
+    expect(unlisten).toHaveBeenCalledTimes(1);
+  });
+
+  it("survives a failed subscription without throwing", async () => {
+    const { listen } = await import("@tauri-apps/api/event");
+    const listenMock = vi.mocked(listen);
+    listenMock.mockRejectedValueOnce(new Error("listen failed"));
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const pinia = createPinia();
+    setActivePinia(pinia);
+    const wrapper = mount(FdaBanner, { global: { plugins: [pinia, i18n] } });
+    await vi.waitFor(() => expect(errorSpy).toHaveBeenCalled());
+
+    expect(wrapper.find(BANNER).exists()).toBe(false);
+    wrapper.unmount();
+    errorSpy.mockRestore();
+  });
+});
+
+describe("fdaBanner store", () => {
+  beforeEach(() => {
+    setActivePinia(createPinia());
+  });
+
+  it("falls back to the row id when a denial row carries no message", () => {
+    const store = useFdaBannerStore();
+
+    store.noteDenial(row({ id: 40, message: null }) as never);
+    store.noteDenial(row({ id: 41, message: null }) as never);
+
+    // No path to dedupe on, so each row counts - better than collapsing two
+    // different files into one.
+    expect(store.deniedCount).toBe(2);
+    expect(store.visible).toBe(true);
+  });
+
+  it("hides the banner once dismissed and restores it on reset", () => {
+    const store = useFdaBannerStore();
+    store.noteDenial(row() as never);
+    expect(store.visible).toBe(true);
+
+    store.dismiss();
+    expect(store.dismissed).toBe(true);
+    expect(store.visible).toBe(false);
+
+    store.reset();
+    expect(store.deniedCount).toBe(0);
+    expect(store.dismissed).toBe(false);
+    expect(store.visible).toBe(false);
+  });
+});
diff --git a/ui/src/components/FdaBanner.vue b/ui/src/components/FdaBanner.vue
new file mode 100644
index 00000000..fc9a1b1e
--- /dev/null
+++ b/ui/src/components/FdaBanner.vue
@@ -0,0 +1,110 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted } from "vue";
+import { useI18n } from "vue-i18n";
+import type { UnlistenFn } from "@tauri-apps/api/event";
+import { openUrl } from "@tauri-apps/plugin-opener";
+
+import { onActivityNew } from "../ipc/events";
+import { useFdaBannerStore } from "../stores/fdaBanner";
+
+// The Full Disk Access banner (DESIGN s5.3.2 - macOS TCC): when macOS refuses
+// Driven a read, the backup does not fail loudly, it just silently skips the
+// file every cycle forever. This bar is the only place the user is told that is
+// happening, and it carries the one-click fix.
+//
+// It owns its own `activity:new` subscription rather than reading the activity
+// store, for the same reason ToastHost does: it is mounted at the app ROOT and
+// never unmounted, so it cannot miss a denial that lands while the user is on
+// some other route. Which rows count, and the per-file dedupe that stops a
+// re-scanned denial from inflating the number every cycle, live in the store.
+const { t } = useI18n();
+const store = useFdaBannerStore();
+
+// The System Settings deep link. macOS resolves the pane from the bundle id and
+// the anchor after `?`; this exact string lands on Privacy & Security > Full
+// Disk Access (a wrong anchor silently degrades to the Privacy & Security root,
+// so it is verified verbatim in the test rather than assembled at runtime).
+const FULL_DISK_ACCESS_URL =
+  "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
+
+// Bound, not a template literal, so the i18n no-raw-text rule is satisfied and
+// the plural choice (file vs files) is passed the way the rest of the app does.
+const body = computed<string>(() =>
+  t("fdaBanner.body", { count: store.deniedCount }, store.deniedCount)
+);
+
+async function onOpenSettings(): Promise<void> {
+  try {
+    await openUrl(FULL_DISK_ACCESS_URL);
+  } catch (e) {
+    // Opening System Settings is a convenience, never a failure path worth
+    // interrupting the user for: the banner text already names the pane, so a
+    // rejected open (no opener, sandbox refusal) just logs. Swallowing it here
+    // also keeps a rejected promise from surfacing as an unhandled rejection.
+    console.error("failed to open the Full Disk Access pane", e);
+  }
+}
+
+let unlisteners: UnlistenFn[] = [];
+let disposed = false;
+
+onMounted(async () => {
+  const registered: UnlistenFn[] = [];
+  try {
+    registered.push(await onActivityNew((entry) => store.noteDenial(entry)));
+  } catch (e) {
+    // Same policy as the toast subscriptions: a banner is never a reason to
+    // break boot. Tear down whatever did register so a half-wired subscription
+    // cannot leak, and log.
+    for (const un of registered) un();
+    console.error("FDA banner subscribe failed", e);
+    return;
+  }
+  // Unmount may have raced ahead while we awaited `listen`; honor it rather than
+  // leaving a listener registered against a dead component.
+  if (disposed) {
+    for (const un of registered) un();
+    return;
+  }
+  unlisteners = registered;
+});
+
+onBeforeUnmount(() => {
+  disposed = true;
+  for (const un of unlisteners) un();
+  unlisteners = [];
+});
+</script>
+
+<template>
+  <div
+    v-if="store.visible"
+    class="mx-6 my-2 rounded-lg border border-amber-300 bg-amber-50 p-3 text-sm dark:border-amber-800/60 dark:bg-amber-950/40"
+    role="status"
+    data-testid="fda-banner"
+  >
+    <h4 class="font-semibold text-amber-800 dark:text-amber-300">{{ t("fdaBanner.title") }}</h4>
+    <p class="mt-1 text-amber-700 dark:text-amber-200/80">{{ body }}</p>
+    <p class="mt-1 text-amber-700 dark:text-amber-200/80" data-testid="fda-banner-unsigned-note">
+      {{ t("fdaBanner.unsignedNote") }}
+    </p>
+    <div class="mt-2 flex flex-wrap items-center gap-2">
+      <button
+        type="button"
+        class="rounded-sm border border-amber-500 px-2 py-0.5 font-medium text-amber-900 transition-colors hover:bg-amber-100 focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-amber-600 dark:border-amber-400/70 dark:text-amber-100 dark:hover:bg-amber-900/50"
+        data-testid="fda-banner-open"
+        @click="onOpenSettings"
+      >
+        {{ t("fdaBanner.openButton") }}
+      </button>
+      <button
+        type="button"
+        class="rounded-sm px-2 py-0.5 font-medium text-amber-800 transition-colors hover:bg-amber-100 focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-amber-600 dark:text-amber-200 dark:hover:bg-amber-900/50"
+        data-testid="fda-banner-dismiss"
+        @click="store.dismiss()"
+      >
+        {{ t("common.close") }}
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/ui/src/locales/en-US.json b/ui/src/locales/en-US.json
index b9dbd735..e8bf2c9b 100644
--- a/ui/src/locales/en-US.json
+++ b/ui/src/locales/en-US.json
@@ -33,6 +33,12 @@
     "timed": "Backups paused - {minutes}m left",
     "resume": "Resume"
   },
+  "fdaBanner": {
+    "title": "macOS is blocking Driven from reading some files",
+    "body": "macOS privacy protection is stopping Driven from reading {count} file. Driven skips it and retries each run. To back it up, give Driven Full Disk Access. | macOS privacy protection is stopping Driven from reading {count} files. Driven skips them and retries each run. To back them up, give Driven Full Disk Access.",
+    "unsignedNote": "macOS ties this permission to the app's signature, and Driven is not signed yet, so the permission can stop working after an update. If files start being skipped again, remove Driven from the Full Disk Access list and add it back.",
+    "openButton": "Open Full Disk Access settings"
+  },
   "toast": {
     "dismiss": "Dismiss notification",
     "kind": {
diff --git a/ui/src/stores/fdaBanner.ts b/ui/src/stores/fdaBanner.ts
new file mode 100644
index 00000000..9ccb151e
--- /dev/null
+++ b/ui/src/stores/fdaBanner.ts
@@ -0,0 +1,89 @@
+import { defineStore } from "pinia";
+import { computed, ref } from "vue";
+
+import type { ActivityEntry } from "../ipc/types";
+
+/** The activity `event_type` the backend writes when macOS TCC (Transparency,
+ * Consent and Control) refuses a read - the ONLY signal this banner keys off.
+ * It can only ever be emitted on macOS, so the banner is inherently mac-only
+ * and needs no platform sniff (exactly like the Windows VSS banner, which also
+ * derives purely from backend state). */
+export const PERMISSION_DENIED_EVENT = "local.permission_denied";
+
+/**
+ * Full Disk Access banner store (DESIGN s5.3.2 - macOS TCC). Drives the
+ * dismissible banner that explains why some files are being skipped and offers
+ * the one-click deep link into System Settings > Privacy & Security > Full Disk
+ * Access.
+ *
+ * Two properties of a TCC denial shape this store:
+ *
+ *  - **It is permanent until the user grants access.** Unlike a locked file
+ *    (which frees up on its own), a denied path is re-denied on EVERY scan, so
+ *    the backend writes one warn row per file per cycle, unbounded. We therefore
+ *    dedupe by the row's message (the path) - a file seen across 50 cycles
+ *    counts once, and the banner says "3 files", not "150". The dedupe lives
+ *    here, in the display layer, so neither the activity log nor the backend has
+ *    to change what it records.
+ *  - **Dismissal is PER-SESSION by design.** The condition outlives the app
+ *    process, so re-surfacing the banner on the next launch is correct, not a
+ *    bug - and it means no storage is involved (matching `updater.ts`, the only
+ *    other dismissible banner; `localStorage` is used nowhere in this UI).
+ *
+ * Like `updater.ts`'s banner, this one does NOT un-dismiss itself: once the user
+ * closes it, later denials - including ones for files never seen before - keep
+ * counting into `deniedCount` but do not re-open the banner. Re-opening on the
+ * next denial would mean re-opening within seconds, since a denied file is
+ * re-reported every cycle, which would make the dismiss button useless.
+ */
+export const useFdaBannerStore = defineStore("fdaBanner", () => {
+  // The distinct files macOS has refused, keyed by the activity row's message
+  // (the path). A row with no message falls back to its id, which is unique per
+  // row - that degrades to "no dedupe" for that row rather than collapsing
+  // unrelated files into one.
+  const deniedFiles = ref<Set<string>>(new Set());
+
+  // Whether the user closed the banner this session.
+  const dismissed = ref(false);
+
+  /** How many DISTINCT files macOS has refused this session. */
+  const deniedCount = computed(() => deniedFiles.value.size);
+
+  /** Whether the banner should be shown. */
+  const visible = computed(() => deniedCount.value > 0 && !dismissed.value);
+
+  /** Ingest one live activity row. Ignores everything that is not a TCC denial;
+   * a denial adds its dedupe key. Deliberately does not clear `dismissed` (see
+   * the store comment). */
+  function noteDenial(entry: ActivityEntry): void {
+    if (entry.eventType !== PERMISSION_DENIED_EVENT) return;
+    const key = entry.message ?? String(entry.id);
+    if (deniedFiles.value.has(key)) return;
+    // Replace the Set rather than mutating it: a plain `add` on a `ref<Set>` is
+    // not reactive, so the computed count would never re-run.
+    deniedFiles.value = new Set(deniedFiles.value).add(key);
+  }
+
+  /** Close the banner for the rest of this session. */
+  function dismiss(): void {
+    dismissed.value = true;
+  }
+
+  /** Clear both the denied set and the dismissal, so the banner behaves as if
+   * the app just started. Used by tests, and by a future "re-check permissions"
+   * action once access has been granted. */
+  function reset(): void {
+    deniedFiles.value = new Set();
+    dismissed.value = false;
+  }
+
+  return {
+    deniedFiles,
+    dismissed,
+    deniedCount,
+    visible,
+    noteDenial,
+    dismiss,
+    reset,
+  };
+});