fix: probe the broker socket before reporting Ready; docs match advisory helper-dir check

osascript exits 0 as soon as the consent prompt resolves and the shell
backgrounds the broker, so the launcher reported Ready from the SPAWN
alone. A broker that died immediately then looked healthy - the exact
silent shape the sun_path overflow produced. Probe the socket
(connect-and-drop; a dead broker leaves a stale socket FILE behind) and
report Pending inside a 15s bind grace, then Disabled, so the UI shows
degraded rather than an undiagnosable eternal Pending.

Also update DESIGN s5.3.2 for #211: the co-installation helper-dir check
is advisory, not fatal, so locked-file backup works on a normal
drag-install and the residual is logged as DEGRADED.

Author: pmaxhogan

README.md

@@ -99,7 +99,7 @@ Notes:
 - ³⁸ Windows and macOS only; Linux needs third-party tools.
 - ³⁹ `bench/` runs Driven's real engine and rclone over identical seeded fixtures against a live Drive account, reporting wall time, throughput, API calls, CPU time, and peak memory for a cold and an incremental pass. See [`bench/README.md`](bench/README.md) for scales, costs, and what is and is not apples-to-apples.
 - ⁴⁰ The others publish unit-test microbenchmarks, internal tuning harnesses (Duplicati's unreleased AutoTune), or vendor marketing numbers, rather than a runnable end-to-end suite. Backblaze does publish a quarterly benchmark, but of B2 object storage rather than the backup client.
-- ⁴¹ Driven's checkmark is scoped to Windows, where a VSS snapshot lets a locked file (Outlook PST, running DB, VM disk) back up while it is held open. Neither macOS nor Linux backs a file up through a lock today - on macOS and Linux, a file Driven cannot open is instead classified precisely as a transient lock (`local.file_locked`) versus a macOS Full Disk Access denial (`local.permission_denied`) and skipped with a clear reason in the activity log, rather than misreported as a disk error. A macOS APFS-snapshot bypass equivalent to Windows VSS exists as a broker crate but is not yet wired into the backup path, so it does not do anything for a user yet; there is no Linux equivalent planned. See `design/DESIGN.md` §5.3 and §5.3.2.
+- ⁴¹ Driven's checkmark is scoped to Windows, where a VSS snapshot lets a locked file (Outlook PST, running DB, VM disk) back up while it is held open. macOS has an equivalent behind an opt-in setting (Settings > Rules): a small privileged helper mounts a read-only APFS local snapshot so a *busy* file can be read: it is off by default, and it does nothing for a Full Disk Access denial. On both macOS and Linux, a file Driven cannot open is in any case classified precisely as a transient lock (`local.file_locked`) versus a macOS Full Disk Access denial (`local.permission_denied`) and skipped with a clear reason in the activity log, rather than misreported as a disk error. Linux has no snapshot equivalent and none is planned. See `design/DESIGN.md` §5.3 and §5.3.2.
 
 Competitor rows were verified in July 2026 against rclone 1.74.4, restic 0.19.1,
 Duplicati 2.3.0.4, Backblaze Personal Backup 10.0.2, and Drive for desktop 128.0.
@@ -128,8 +128,9 @@ These move: check each project's current docs before relying on a cell.
   files, VM disks) still back up. On macOS and Linux, a file Driven cannot open
   is classified precisely - a transient lock versus a macOS Full Disk Access
   denial - and skipped with a clear reason rather than reported as a generic
-  disk error; an APFS-snapshot bypass equivalent to Windows VSS is in
-  development for macOS but not yet available.
+  disk error. macOS can also back up a *busy* file through an opt-in APFS
+  snapshot (Settings > Rules), which does not help with a Full Disk Access
+  denial; there is no Linux equivalent.
 - In-app restore browser with full-text file-name search and streaming decrypt.
 - Activity dashboard with a live tail and filterable history.
 - Rolling local log files covering both the backend and the webview console,
@@ -208,15 +209,47 @@ 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.
 
 **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
-today; a macOS APFS-snapshot equivalent is in development, see the table
-above) exists to read around a file that is transiently *busy* - open in
+never tries to make it one.** Driven's locked-file handling (Windows VSS,
+and the opt-in macOS APFS snapshot described below) exists to read around a file that is transiently *busy* - open in
 another program. It does not and cannot read around a TCC *denial*, because a
 snapshot preserves the original file's permissions and is itself subject to
 the same TCC check. The historical `-o noowners` mount trick that could bypass
 this (CVE-2020-9771) is long patched and is now a signature EDR products flag
 as suspicious; Driven does not use it and never will.
 
+#### macOS locked-file backup (APFS snapshot, opt-in)
+
+Two different things stop a file being backed up on macOS, and they have
+different fixes:
+
+| Situation | Reported as | Fix |
+|-----------|-------------|-----|
+| The file is held open / busy - a live database, a VM disk, a mail store | `local.file_locked` | Turn on **Back up locked files using an APFS snapshot** in Settings > Rules |
+| macOS privacy protection denies the read | `local.permission_denied` | Grant Full Disk Access (above). Nothing else works. |
+
+The APFS snapshot option is **off by default**. Turning it on asks for your
+administrator password once per session, and from then on Driven reads busy
+files out of a read-only APFS local snapshot mounted by a small privileged
+helper - the app itself stays un-elevated, and the helper only ever mounts and
+unmounts. It works without Time Machine being set up.
+
+> **Note on drag-installed copies.** One of the helper's defence-in-depth
+> checks is weaker when Driven is installed the usual way. The helper confirms
+> that whatever is talking to it sits next to it in the same folder - which only
+> proves much if you could not write to that folder yourself. Dragging an app
+> out of a `.dmg` makes **you** the owner of everything inside it (this is true
+> even when you drag it into `/Applications`; only `.pkg` and App Store installs
+> land root-owned), so on a normal Driven install that check is advisory and the
+> helper records a `DEGRADED` line in its own log instead of enforcing it.
+>
+> Locked-file backup still works, and the checks that carry the real weight are
+> unaffected: the helper only talks to your own user account, only mounts
+> volumes Driven listed at launch, and only ever makes read-only mounts that
+> preserve the original file ownership. Someone who defeated the folder check
+> would already have to be running as you, and would gain a read-only copy of
+> files they could already read. Installing from a `.pkg` would restore the
+> check to full strength; it is an improvement, not a prerequisite.
+
 #### macOS auto-updater caveat
 
 Because the macOS build is not signed with a Developer ID, the in-app

design/DESIGN.md

@@ -745,21 +745,49 @@ nor replace the directory; if they pre-create it, it is owned by them and the
 broker's own "socket parent must be owned by the peer uid with mode 0700"
 check refuses to serve, so the failure is closed rather than silent.
 
-**Install layout decides whether the feature works at all.** The broker
-refuses to serve when the helper's own directory is writable by the client
-uid, because the peer check ("the caller's executable sits next to mine") is
-meaningless if the caller can drop a binary there. Measured on macOS 26.6:
-every app drag-installed from a DMG - including into `/Applications`, not
-merely `~/Applications` - has `Contents/MacOS` owned by the installing USER
-(verified across AltTab, Audacity, Chrome, Claude, Discord, Docker, GIMP),
-whereas pkg- and App-Store-installed apps (Cloudflare WARP, GarageBand) are
-`root:wheel`. Driven currently ships a `.dmg` whose documented install is a
-drag to `/Applications`, so on a stock install the broker exits at startup
-and locked-file backup never engages. Shipping this feature in a usable state
-therefore requires a `.pkg` (or a post-install `chown root:wheel` step) that
-lands the bundle root-owned. This is a deliberate security property of the
-broker, not a bug to work around: the alternative is a co-installation check
-that looks like authentication and is not.
+**Install layout weakens one check but does not disable the feature.** The
+broker's co-installation check ("the caller's executable sits next to mine")
+is only strong if the peer user cannot WRITE to the helper's directory.
+Measured on macOS 26.6, essentially no drag-installed bundle satisfies that:
+every app installed by dragging out of a `.dmg` - including into
+`/Applications`, not merely `~/Applications` - has `Contents/MacOS` owned by
+the installing USER (verified across AltTab, Audacity, Chrome, Claude,
+Discord, Docker, GIMP), whereas pkg- and App-Store-installed apps (Cloudflare
+WARP, GarageBand) are `root:wheel`. Driven ships a `.dmg`, so this is the
+normal case, not the exotic one.
+
+The check is therefore **advisory** rather than fatal: the broker serves, and
+writes a `DEGRADED:` line to its root-owned audit log naming the directory and
+the uid. The reasoning is that the attacker it guards against is ALREADY the
+same uid - `getpeereid` is not bypassable by planting a binary - so defeating
+co-installation buys them a read-only, `nosuid`, `nodev`,
+ownership-preserving mount of an allow-listed volume at a broker-chosen
+mountpoint. That is a point-in-time copy of files that uid could already read,
+with TCC still applying to their own process. Trading locked-file backup away
+for every drag-install user would not have been a good exchange. The
+load-bearing checks are the peer uid, the volume allow-list, the snapshot-name
+validation and the mount options; this one is defence in depth.
+
+A `.pkg`-style install that lands the bundle root-owned restores the check to
+full strength and silences the `DEGRADED:` line, and remains the better
+end state - but it is an improvement, not a prerequisite.
+
+**`Ready` means the socket answered, not that a process was spawned.**
+`osascript` exits 0 as soon as the consent prompt resolves and the shell
+backgrounds the broker, so the launcher's own `Ready` reflects the SPAWN
+alone. If the broker then dies immediately - a failed pre-flight check, a bad
+sidecar, a socket path that will not bind - the user gets an administrator
+prompt followed by a healthy-looking status while nothing ever mounts. That
+silent shape is precisely what the `sun_path` overflow above produced, and it
+is the difference between a bug found in minutes and one found never. The app
+manager therefore probes the socket before passing `Ready` upward: a
+connect-and-drop liveness check (existence is not enough - a dead broker
+leaves its socket file behind, and connecting to that fails `ECONNREFUSED`).
+An unbacked `Ready` reports `Pending` - a transient skip, retried next cycle -
+for a 15s grace window covering the bind, and then `Disabled`, which makes
+`helper_launchable` false and surfaces as degraded in the UI rather than as an
+eternal `Pending` nobody can diagnose. Probing stops at the first success, so
+a healthy session pays a couple of connects, not one per status poll.
 
 **Not a TCC bypass.** Worth restating because it is the single most likely
 misreading of this whole section: an APFS snapshot lets Driven read a file

src-tauri/src/apfs_helper.rs

@@ -82,6 +82,38 @@ pub struct ApfsHelperManager {
     /// [`HelperLauncher::launch_status`] on a locked file, and the enable-toggle
     /// [`Self::launch_now`] - and cleared whenever the launcher is replaced.
     launch_attempted: AtomicBool,
+    /// Set once the broker's socket has actually answered, after which the
+    /// liveness probe in [`Self::confirm_ready`] is skipped for the session.
+    broker_confirmed: AtomicBool,
+    /// When the launcher FIRST claimed `Ready` without a live socket behind it,
+    /// so the grace window in [`Self::confirm_ready`] can expire.
+    ready_since: Mutex<Option<std::time::Instant>>,
+}
+
+/// How long a launcher-reported `Ready` may go unbacked by a live socket before
+/// the broker is declared dead. Generous: it only has to cover the gap between
+/// `osascript` returning and the broker binding its socket, and erring long
+/// costs a few extra transient skips while erring short would call a healthy
+/// broker dead.
+const BROKER_READY_GRACE: std::time::Duration = std::time::Duration::from_secs(15);
+
+/// Whether a unix-domain socket at `path` has a LISTENER behind it right now.
+///
+/// Existence alone is not enough: a broker that died leaves its socket file on
+/// disk, and connecting to that stale file fails with `ECONNREFUSED`. The
+/// connection is dropped immediately without speaking the protocol - this is a
+/// liveness probe, not a handshake, and [`crate::apfs_helper`] never treats it
+/// as authentication (the client's own root-peer check does that).
+#[cfg(unix)]
+fn socket_is_live(path: &Path) -> bool {
+    std::os::unix::net::UnixStream::connect(path).is_ok()
+}
+
+/// Off unix there are no unix-domain sockets, and the launcher can never report
+/// `Ready` there anyway (the osascript stub always fails).
+#[cfg(not(unix))]
+fn socket_is_live(_path: &Path) -> bool {
+    false
 }
 
 impl ApfsHelperManager {
@@ -119,6 +151,8 @@ impl ApfsHelperManager {
             enabled: AtomicBool::new(enabled),
             launcher: Mutex::new(launcher),
             launch_attempted: AtomicBool::new(false),
+            broker_confirmed: AtomicBool::new(false),
+            ready_since: Mutex::new(None),
         }
     }
 
@@ -169,6 +203,10 @@ impl ApfsHelperManager {
         // A fresh launcher has not been triggered, so status reads must go back
         // to answering "not yet tried" WITHOUT touching it.
         self.launch_attempted.store(false, Ordering::SeqCst);
+        // The next launch gets a fresh broker, so re-prove its liveness rather
+        // than trusting a previous session's confirmation.
+        self.broker_confirmed.store(false, Ordering::SeqCst);
+        *self.ready_since.lock().unwrap_or_else(|p| p.into_inner()) = None;
     }
 
     /// The launcher's status, but ONLY once a launch has genuinely been
@@ -180,7 +218,48 @@ impl ApfsHelperManager {
         if !self.is_enabled() || !self.launch_attempted.load(Ordering::SeqCst) {
             return None;
         }
-        Some(self.current_launcher().launch_status())
+        Some(self.confirm_ready(self.current_launcher().launch_status()))
+    }
+
+    /// Downgrade a launcher-reported `Ready` that no live broker backs.
+    ///
+    /// `osascript` exits 0 as soon as the consent prompt resolves and the shell
+    /// BACKGROUNDS the broker (`... &`), so the launcher records `Ready` from
+    /// the spawn alone. If the broker then dies immediately - a refused
+    /// pre-flight check, a bad sidecar, a socket path that will not bind - the
+    /// user sees an administrator prompt followed by a healthy status while
+    /// nothing ever mounts. That silent shape is exactly what the `sun_path`
+    /// overflow produced, so `Ready` is only reported once the socket actually
+    /// answers.
+    ///
+    /// Timing matters: the broker needs a moment to bind after the spawn, so a
+    /// not-yet-live socket is `Pending` (a transient skip, retried next cycle)
+    /// until [`BROKER_READY_GRACE`] elapses, and only then `Disabled` - which
+    /// makes `helper_launchable` false and surfaces as "degraded" in the UI
+    /// rather than as an eternal `Pending` nobody can diagnose.
+    ///
+    /// Probing stops permanently at the first success, so a healthy session
+    /// costs at most a few connects rather than one per status poll.
+    fn confirm_ready(&self, status: HelperLaunchStatus) -> HelperLaunchStatus {
+        if status != HelperLaunchStatus::Ready || self.broker_confirmed.load(Ordering::SeqCst) {
+            return status;
+        }
+        if socket_is_live(&self.socket) {
+            self.broker_confirmed.store(true, Ordering::SeqCst);
+            return HelperLaunchStatus::Ready;
+        }
+        let mut first = self.ready_since.lock().unwrap_or_else(|p| p.into_inner());
+        let started = *first.get_or_insert_with(std::time::Instant::now);
+        if started.elapsed() < BROKER_READY_GRACE {
+            HelperLaunchStatus::Pending
+        } else {
+            tracing::warn!(
+                socket = %self.socket.display(),
+                "apfs broker reported launched but its socket never came up; \
+                 locked-file backup is unavailable this session"
+            );
+            HelperLaunchStatus::Disabled
+        }
     }
 
     /// Apply a change to the `macos.apfs_snapshot` setting (called from the
@@ -422,6 +501,84 @@ mod tests {
     /// on every Mac, not just unusual ones. Confirmed against the real broker
     /// binary on macOS 26.6. Nothing else in the suite binds a socket, so only
     /// a length assertion catches it.
+    /// The liveness probe must distinguish a LIVE listener from a stale socket
+    /// FILE. A broker that died leaves its socket on disk, so an
+    /// existence-only check would keep reporting a healthy helper forever -
+    /// which is the exact silent shape this probe exists to prevent.
+    #[cfg(unix)]
+    #[test]
+    fn socket_probe_sees_a_live_listener_and_rejects_a_stale_file() {
+        let dir = std::env::temp_dir().join(format!("driven-apfs-probe-{}", std::process::id()));
+        let _ = std::fs::create_dir_all(&dir);
+        let sock = dir.join("probe.sock");
+        let _ = std::fs::remove_file(&sock);
+
+        // Nothing there at all.
+        assert!(!socket_is_live(&sock), "absent socket is not live");
+
+        // A real listener answers.
+        let listener = std::os::unix::net::UnixListener::bind(&sock).expect("bind probe socket");
+        assert!(socket_is_live(&sock), "a bound listener must probe live");
+
+        // Dropping the listener leaves the FILE behind but nothing listening -
+        // connect must now fail (ECONNREFUSED), not succeed on file existence.
+        drop(listener);
+        assert!(sock.exists(), "the stale socket file is still on disk");
+        assert!(
+            !socket_is_live(&sock),
+            "a stale socket file must NOT probe live"
+        );
+
+        let _ = std::fs::remove_file(&sock);
+        let _ = std::fs::remove_dir(&dir);
+    }
+
+    #[test]
+    fn a_ready_launcher_without_a_live_socket_is_not_reported_ready() {
+        // The manager's socket path is never bound in this test, so a launcher
+        // claiming Ready is exactly the "osascript spawned it, then it died"
+        // case. It must degrade to Pending inside the grace window rather than
+        // telling the UI locked-file backup is healthy.
+        let m = manager_with_real_exe(true);
+        assert_eq!(
+            m.confirm_ready(HelperLaunchStatus::Ready),
+            HelperLaunchStatus::Pending,
+            "an unbacked Ready degrades to Pending while the broker may still be binding"
+        );
+        // Non-Ready statuses pass through untouched.
+        assert_eq!(
+            m.confirm_ready(HelperLaunchStatus::Declined),
+            HelperLaunchStatus::Declined
+        );
+        assert_eq!(
+            m.confirm_ready(HelperLaunchStatus::Disabled),
+            HelperLaunchStatus::Disabled
+        );
+    }
+
+    #[test]
+    fn an_unbacked_ready_becomes_disabled_once_the_grace_window_expires() {
+        let m = manager_with_real_exe(true);
+        // Backdate the first-Ready stamp past the grace window.
+        *m.ready_since.lock().expect("ready_since") = Some(
+            std::time::Instant::now()
+                .checked_sub(BROKER_READY_GRACE + std::time::Duration::from_secs(5))
+                .expect("backdate"),
+        );
+        assert_eq!(
+            m.confirm_ready(HelperLaunchStatus::Ready),
+            HelperLaunchStatus::Disabled,
+            "a broker whose socket never came up must end DISABLED (degraded + \
+             diagnosable), not Pending forever"
+        );
+        // Disabled is what `helper_launchable` maps to false, which is what the
+        // UI renders as degraded. That end-to-end mapping is not asserted here
+        // on purpose: reaching it requires `launch_attempted`, and setting that
+        // would make the accessors call the real launcher, whose NotAttempted
+        // transition spawns an actual osascript consent prompt. See
+        // `reading_status_never_triggers_a_consent_prompt` for that guard.
+    }
+
     #[test]
     fn socket_path_fits_in_sockaddr_un() {
         // Darwin's sun_path is 104 bytes including the NUL terminator.