Onboarding: Gate indexer auto-start behind FDA decision

Indexer was running at every launch from `setup()`, recursively scanning `/`. On first launch this triggered macOS native permission popups (iCloud, Photos, etc.) before the in-app FDA modal mounted, stacking three prompts over our explanation modal.

- Add pure `should_auto_start_indexing(indexing_enabled, fda_choice, os_fda_granted)` in `indexing/mod.rs`. Skips auto-start when `fda_choice == NotAskedYet` AND the OS check reports FDA as not granted. 5 unit tests cover the truth table.
- Wire `setup()` in `lib.rs` to call the OS-level FDA check (`permissions::check_full_disk_access` per platform) and pass through to the gate.
- New `start_indexing_after_fda_decision` Tauri command (idempotent via `is_active()`). Frontend `FullDiskAccessPrompt` Deny handler calls it so the user doesn't need to restart for indexing to start in-session. Allow path needs no wiring — next-launch OS check passes the gate.
- Drop `#[allow(dead_code)]` on `Settings::full_disk_access_choice` (now consulted) and re-export `FullDiskAccessChoice` from `settings::mod`.
- Bump `mod.rs` and `lib.rs` entries in `file-length-allowlist.json`.
- Document the gate + `Decision/Why` in `indexing/CLAUDE.md`, `onboarding/CLAUDE.md`, `settings/CLAUDE.md`.

Author: vdavid

apps/desktop/src-tauri/src/commands/indexing.rs

@@ -59,3 +59,20 @@ pub async fn set_indexing_enabled(app: AppHandle, enabled: bool) -> Result<(), S
     }
     Ok(())
 }
+
+/// Start the indexer once the user has decided about Full Disk Access.
+///
+/// At app launch, indexing is skipped when the FDA choice is `NotAskedYet` AND
+/// the OS reports FDA as not granted (see `should_auto_start_indexing`). The
+/// frontend calls this command after the user clicks "Deny" so the indexer
+/// starts within the same session. The "Allow" path needs no call: the user
+/// restarts the app, and the launch-time gate passes via the OS check.
+///
+/// Idempotent: a no-op when indexing is already running or initializing.
+#[tauri::command]
+pub async fn start_indexing_after_fda_decision(app: AppHandle) -> Result<(), String> {
+    if indexing::is_active() {
+        return Ok(());
+    }
+    indexing::start_indexing(&app)
+}

apps/desktop/src-tauri/src/indexing/CLAUDE.md

@@ -122,6 +122,15 @@ Key test files are alongside each module (test functions within `#[cfg(test)]` b
 
 ## Key decisions
 
+**Defer indexer auto-start until the user decides about Full Disk Access**: At first launch on macOS, recursively
+scanning from `/` opens iCloud Drive, Photos, and other TCC-protected directories, which makes macOS show native
+permission popups stacked on top of the in-app FDA modal. The result is a confusing pile of dialogs before the user has
+seen our prompt. `should_auto_start_indexing(indexing_enabled, fda_choice, os_fda_granted)` (in `mod.rs`) gates the
+launch-time start: it skips when `fda_choice == NotAskedYet` AND `os_fda_granted == false`. Once the user picks Allow
+(restart) or Deny (same session, via `start_indexing_after_fda_decision`), the indexer starts. `os_fda_granted == true`
+overrides `NotAskedYet` so users who granted FDA before our prompt persisted a choice still get auto-start. Pure
+function so the gate logic is unit-tested without touching `setup()`.
+
 **`getattrlistbulk` (via jwalk) for scanning, not `enumeratorAtURL` or `searchfs`**: Benchmarked on ~5M files (macOS, Apple Silicon, APFS). `getattrlistbulk` recursive walk: 1m49s with sizes. `enumeratorAtURL` with prefetched keys: 2m05s (+11%), found ~500K fewer entries. `searchfs`: fast for name lookup but can't return sizes. `mdfind`: undercounts (Spotlight excludes `.git/`, `node_modules/`, caches). `getattrlistbulk` is what jwalk uses under the hood on macOS, and adding size collection costs only ~4% overhead (packed in the same bulk buffer, no extra syscalls).
 
 **Physical sizes may overcount ~10-20% due to APFS clones**: Per-file `st_blocks * 512` sums to ~905 GB vs ~746 GB true volume usage (`statfs()`). APFS clones (Xcode, simulators, Time Machine, `cp` since Ventura) share underlying blocks but each clone reports full allocation. Volume usage bar always uses `statfs()` for true totals.

apps/desktop/src-tauri/src/indexing/mod.rs

@@ -44,6 +44,8 @@ use store::{DirStats, IndexStore};
 use tauri::AppHandle;
 use writer::WriteMessage;
 
+use crate::settings::FullDiskAccessChoice;
+
 // ── Indexing state machine ────────────────────────────────────────────
 
 /// Lifecycle phases of the indexing system. Single source of truth for
@@ -86,6 +88,37 @@ pub fn should_auto_start(indexing_enabled: Option<bool>) -> bool {
     true
 }
 
+/// Pure decision: should the indexer auto-start at app launch?
+///
+/// Combines the user's indexing-enabled setting with the FDA gate. The FDA gate
+/// blocks the indexer from scanning `/` before the user has decided about Full
+/// Disk Access — otherwise macOS native permission popups (iCloud, Photos, etc.)
+/// stack on top of the in-app FDA modal at first launch.
+///
+/// Auto-start when ALL of the following hold:
+/// - The user has not disabled indexing (`indexing_enabled != Some(false)`).
+/// - Either the user has already made an FDA choice (Allow or Deny), OR the OS
+///   reports FDA is currently granted. When the choice is `NotAskedYet` AND the
+///   OS check returns `false`, we skip auto-start until the user decides.
+pub fn should_auto_start_indexing(
+    indexing_enabled: Option<bool>,
+    fda_choice: FullDiskAccessChoice,
+    os_fda_granted: bool,
+) -> bool {
+    if !should_auto_start(indexing_enabled) {
+        return false;
+    }
+
+    // FDA gate: only block when the user hasn't decided AND the OS confirms FDA
+    // is not currently granted. If the OS check returns true, we know we won't
+    // trigger native permission popups, so it's safe to start.
+    if fda_choice == FullDiskAccessChoice::NotAskedYet && !os_fda_granted {
+        return false;
+    }
+
+    true
+}
+
 /// Trigger background verification of a directory against the index DB.
 /// Called after enrichment on each navigation. No-op if indexing is not running.
 /// Fully fire-and-forget: the INDEXING lock is acquired on a spawned task,
@@ -1056,6 +1089,87 @@ mod tests {
         }
     }
 
+    // ── should_auto_start_indexing (FDA gate) ────────────────────────
+
+    /// First launch with no FDA grant: indexer must NOT auto-start.
+    /// Otherwise the recursive scan from `/` triggers macOS native permission
+    /// popups (iCloud, Photos, etc.) before the in-app FDA modal mounts.
+    #[test]
+    fn should_auto_start_indexing_blocked_when_not_asked_and_os_fda_false() {
+        assert!(!should_auto_start_indexing(
+            None,
+            FullDiskAccessChoice::NotAskedYet,
+            false
+        ));
+        assert!(!should_auto_start_indexing(
+            Some(true),
+            FullDiskAccessChoice::NotAskedYet,
+            false
+        ));
+    }
+
+    /// `NotAskedYet` but OS already grants FDA (user enabled it externally,
+    /// or stale persisted state): safe to auto-start.
+    #[test]
+    fn should_auto_start_indexing_allowed_when_os_fda_true_overrides_not_asked() {
+        assert!(should_auto_start_indexing(
+            None,
+            FullDiskAccessChoice::NotAskedYet,
+            true
+        ));
+        assert!(should_auto_start_indexing(
+            Some(true),
+            FullDiskAccessChoice::NotAskedYet,
+            true
+        ));
+    }
+
+    /// User picked Allow (typically restarts the app after granting in System
+    /// Settings): auto-start regardless of OS check (it should also be true,
+    /// but we trust the persisted choice).
+    #[test]
+    fn should_auto_start_indexing_allowed_when_user_choice_is_allow() {
+        assert!(should_auto_start_indexing(None, FullDiskAccessChoice::Allow, true));
+        // Even if the OS check returns false (FDA was revoked), the Allow
+        // branch still passes the gate — the +page.svelte revoked-prompt path
+        // handles re-asking the user. The indexer just won't be able to read
+        // protected dirs, which is fine; it skips them.
+        assert!(should_auto_start_indexing(None, FullDiskAccessChoice::Allow, false));
+    }
+
+    /// User picked Deny: indexer auto-starts (we respect the choice not to ask
+    /// again, and indexing without FDA still works for accessible paths).
+    #[test]
+    fn should_auto_start_indexing_allowed_when_user_choice_is_deny() {
+        assert!(should_auto_start_indexing(None, FullDiskAccessChoice::Deny, false));
+        assert!(should_auto_start_indexing(
+            Some(true),
+            FullDiskAccessChoice::Deny,
+            false
+        ));
+    }
+
+    /// Indexing disabled in settings always wins: never auto-start regardless
+    /// of FDA state.
+    #[test]
+    fn should_auto_start_indexing_blocked_when_indexing_disabled() {
+        assert!(!should_auto_start_indexing(
+            Some(false),
+            FullDiskAccessChoice::Allow,
+            true
+        ));
+        assert!(!should_auto_start_indexing(
+            Some(false),
+            FullDiskAccessChoice::Deny,
+            false
+        ));
+        assert!(!should_auto_start_indexing(
+            Some(false),
+            FullDiskAccessChoice::NotAskedYet,
+            true
+        ));
+    }
+
     /// After clearing READ_POOL, `enrich_entries_with_index` returns early
     /// without panic and leaves entries unenriched.
     #[test]

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

@@ -474,8 +474,22 @@ pub fn run() {
             // Initialize indexing state (does not start scanning until explicitly started)
             indexing::init();
 
-            // Auto-start indexing unless user disabled it in settings
-            if indexing::should_auto_start(saved_settings.indexing_enabled) {
+            // Auto-start indexing unless user disabled it in settings, or unless
+            // the FDA gate blocks (first launch with no Full Disk Access decision
+            // yet — starting the recursive scan from `/` would trigger macOS native
+            // permission popups before the in-app FDA modal mounts).
+            #[cfg(target_os = "macos")]
+            let os_fda_granted = permissions::check_full_disk_access();
+            #[cfg(target_os = "linux")]
+            let os_fda_granted = permissions_linux::check_full_disk_access();
+            #[cfg(not(any(target_os = "macos", target_os = "linux")))]
+            let os_fda_granted = stubs::permissions::check_full_disk_access();
+
+            if indexing::should_auto_start_indexing(
+                saved_settings.indexing_enabled,
+                saved_settings.full_disk_access_choice,
+                os_fda_granted,
+            ) {
                 let app_handle = app.handle().clone();
                 // Use tauri's runtime spawn instead of tokio::spawn since setup()
                 // runs synchronously before the Tokio runtime is fully available
@@ -484,8 +498,14 @@ pub fn run() {
                         log::warn!("Failed to auto-start indexing: {e}");
                     }
                 });
-            } else {
+            } else if saved_settings.indexing_enabled == Some(false) {
                 log::info!("Drive indexing auto-start skipped (disabled in settings)");
+            } else {
+                log::info!(
+                    "Drive indexing auto-start deferred until Full Disk Access decision (FDA choice: {:?}, OS-granted: {})",
+                    saved_settings.full_disk_access_choice,
+                    os_fda_granted,
+                );
             }
 
             Ok(())
@@ -1048,6 +1068,7 @@ pub fn run() {
             commands::indexing::get_dir_stats_batch,
             commands::indexing::clear_drive_index,
             commands::indexing::set_indexing_enabled,
+            commands::indexing::start_indexing_after_fda_decision,
             commands::indexing::get_index_debug_status,
             // Drive search commands
             commands::search::prepare_search_index,

apps/desktop/src-tauri/src/settings/CLAUDE.md

@@ -18,7 +18,7 @@ Thin read-only settings loader used during Rust startup. The frontend owns all s
 ```rust
 Settings {
     show_hidden_files: bool,           // default true
-    full_disk_access_choice: ...,      // persisted by frontend only, #[allow(dead_code)]
+    full_disk_access_choice: ...,      // consulted at launch by indexer FDA gate
     developer_mcp_enabled: Option<bool>,
     developer_mcp_port: Option<u16>,
     indexing_enabled: Option<bool>,
@@ -69,7 +69,9 @@ These are top-level keys — the dot is part of the key name, not a nesting sepa
 
 - **One-way read only.** This module never writes. All writes go through the frontend's settings store.
 - Direct file reading is the correct design — multiple backend systems (MCP, indexing, crash reporter) need settings before the frontend loads.
-- `full_disk_access_choice` is marked `#[allow(dead_code)]` — it is persisted by the frontend but the backend takes no action on it.
+- `full_disk_access_choice` is consulted at app launch by the indexer FDA gate (`indexing::should_auto_start_indexing`)
+  to defer the recursive scan from `/` until the user has decided. See `indexing/CLAUDE.md` § "Defer indexer auto-start
+  until the user decides about Full Disk Access".
 - Falls back gracefully: missing file → use `Default`.
 
 ## Dependencies

apps/desktop/src-tauri/src/settings/loader.rs

@@ -29,7 +29,6 @@ pub struct Settings {
     #[serde(alias = "showHiddenFiles", default = "default_show_hidden")]
     pub show_hidden_files: bool,
     #[serde(alias = "fullDiskAccessChoice", default)]
-    #[allow(dead_code, reason = "Only used by frontend, backend just persists it")]
     pub full_disk_access_choice: FullDiskAccessChoice,
     #[serde(alias = "developer.mcpEnabled", default)]
     pub developer_mcp_enabled: Option<bool>,

apps/desktop/src-tauri/src/settings/mod.rs

@@ -2,4 +2,4 @@
 
 pub mod loader;
 
-pub use loader::{early_load_max_log_storage_mb, early_load_verbose_logging, load_settings};
+pub use loader::{FullDiskAccessChoice, early_load_max_log_storage_mb, early_load_verbose_logging, load_settings};

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

@@ -16,7 +16,25 @@ Access in macOS System Settings.
 Two actions are available:
 
 - **Open System Settings** — calls `openPrivacySettings()` via IPC, then shows a follow-up hint to restart the app.
-- **Deny** — saves `fullDiskAccessChoice: 'deny'` to settings and calls `onComplete()` to dismiss.
+- **Deny** — saves `fullDiskAccessChoice: 'deny'` to settings, calls `startIndexingAfterFdaDecision()` so the indexer
+  starts within this session, then calls `onComplete()` to dismiss.
+
+## Indexer FDA gate
+
+At app launch, the backend defers starting the drive indexer until the user has decided about Full Disk Access. The
+recursive scan from `/` would otherwise trigger macOS native permission popups (iCloud, Photos, etc.) that stack on top
+of this in-app FDA modal.
+
+The gate fires when `fullDiskAccessChoice === 'notAskedYet'` AND the OS-level FDA check returns false. After the user
+decides:
+
+- **Deny** path: `FullDiskAccessPrompt.svelte` calls `startIndexingAfterFdaDecision()` so the indexer starts in the
+  current session.
+- **Allow** path: the user grants FDA in System Settings, then restarts the app. On next launch the OS check returns
+  true, the gate passes, and the indexer auto-starts.
+
+The Tauri command is idempotent — calling it when indexing is already running is a no-op. See
+`src-tauri/src/indexing/CLAUDE.md` for the backend side.
 
 The `wasRevoked` prop switches the copy from "first ask" to "revoked" framing.
 

apps/desktop/src/lib/onboarding/FullDiskAccessPrompt.svelte

@@ -1,8 +1,11 @@
 <script lang="ts">
-    import { openPrivacySettings } from '$lib/tauri-commands'
+    import { openPrivacySettings, startIndexingAfterFdaDecision } from '$lib/tauri-commands'
     import { saveSettings } from '$lib/settings-store'
     import ModalDialog from '$lib/ui/ModalDialog.svelte'
     import Button from '$lib/ui/Button.svelte'
+    import { getAppLogger } from '$lib/logging/logger'
+
+    const log = getAppLogger('onboarding')
 
     interface Props {
         onComplete: () => void
@@ -20,6 +23,14 @@
 
     async function handleDeny() {
         await saveSettings({ fullDiskAccessChoice: 'deny' })
+        // Indexing was deferred at app launch (FDA gate). Now that the user has
+        // decided, start it within this session so they don't need to restart
+        // for the index to start populating.
+        try {
+            await startIndexingAfterFdaDecision()
+        } catch (error) {
+            log.warn('Failed to start indexing after FDA deny: {error}', { error })
+        }
         onComplete()
     }
 </script>

apps/desktop/src/lib/tauri-commands/index.ts

@@ -295,6 +295,7 @@ export {
   setErrorReportsEnabled,
   setShowVirtualGitPortal,
   setIndexingEnabled,
+  startIndexingAfterFdaDecision,
   getDirStatsBatch,
   getE2eStartPath,
   getAiStatus,