fix: eager VSS helper launch with attended UAC window and decline-only memoisation

The live smoke of the wired helper (#112) failed: the lazy at-first-locked-file
launch gave the human only the ~5s pipe-connect budget to approve UAC, and one
timed-out shot memoised failure until restart -> every locked file skipped as
local.file_locked. This hardens the launch UX (Refs #25).

- SEE_MASK_NOASYNC on ShellExecuteExW so the runas call WAITS for the user to
  approve/decline even on a no-message-loop worker thread (the likely root cause
  of the early-return spurious failure).
- Eager launch on enable-toggle: flipping windows.vssHelper ON fires the attended
  UAC prompt immediately (the user is at Settings), on a background thread so the
  IPC returns at once; the UI polls status Pending -> Ready/Declined. Boot stays
  LAZY (no UAC at silent startup); the first locked file triggers it.
- Manager now built at boot whenever un-elevated (setting-independent) with an
  enabled flag, shared into every provider, so a runtime toggle works without an
  app restart.
- Decline-only memoisation: ERROR_CANCELLED (decline OR ignored prompt) memoises
  for the session; an approved-but-pipe-never-came-up launch is transient and
  retried on the next enable/start; an off->on re-toggle clears a prior decline.
- Attended 90s window for the post-approval pipe handshake (only the one-shot
  launch; steady-state reconnects stay tight).
- Transient classification: a locked file hit WHILE the helper is launching is
  skipped-and-requeued as the new local.vss_helper_pending (SnapshotOutcome::
  Pending -> FallbackDecision::SkipRetryLater -> SkipReason::VssHelperPending),
  never misreported as a permanent local.file_locked.
- Truthful status: launchPending / launchDeclined added; Rules tab shows a
  "waiting for elevation approval" hint (polled) and a "declined" hint.

Refs #25

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LQMbCLUj5JT2e35qQMvsyA

Author: pmaxhogan

crates/driven-core/src/executor.rs

@@ -388,6 +388,11 @@ pub enum SkipReason {
     /// up if Driven ran elevated" from "genuinely unreadable"
     /// (`local.vss_unavailable`, SPEC s24).
     VssUnavailable,
+    /// The file is locked and the least-privilege VSS helper broker is still
+    /// LAUNCHING / awaiting elevation approval (DESIGN s5.3.1). The file is
+    /// skipped TRANSIENTLY this cycle and retried next cycle (once the broker is
+    /// up) - NOT reported as a permanent lock (`local.vss_helper_pending`).
+    VssHelperPending,
 }
 
 impl SkipReason {
@@ -401,6 +406,7 @@ impl SkipReason {
             SkipReason::ChangedDuringUpload => ErrorCode::LocalFileChangedDuringUpload,
             SkipReason::Locked => ErrorCode::LocalFileLocked,
             SkipReason::VssUnavailable => ErrorCode::LocalVssUnavailable,
+            SkipReason::VssHelperPending => ErrorCode::LocalVssHelperPending,
         }
     }
 }
@@ -1136,6 +1142,14 @@ impl DefaultExecutor {
                     };
                 EffectiveOpen::Skip(reason)
             }
+            FallbackDecision::SkipRetryLater => {
+                // DESIGN s5.3.1: the least-privilege helper broker is launching /
+                // awaiting elevation approval. Skip this locked file TRANSIENTLY
+                // (it re-queues like any skip) and classify it as helper-pending -
+                // NOT a permanent lock - so the brief launch-in-progress window is
+                // not misreported. The next cycle (broker up) backs it up.
+                EffectiveOpen::Skip(SkipReason::VssHelperPending)
+            }
         }
     }
 
@@ -8635,6 +8649,67 @@ mod tests {
         assert_eq!(children[0].size, Some(size));
     }
 
+    /// Issue #25 (launch-UX): a LOCKED file while the least-privilege helper is
+    /// still LAUNCHING is skipped TRANSIENTLY (re-queued) and classified
+    /// `local.vss_helper_pending` - NOT the permanent `local.file_locked`. Windows
+    /// only (a real `ERROR_SHARING_VIOLATION` cannot be produced cross-OS) but
+    /// NON-elevated-safe: `FakeVssProvider::pending()` returns `Pending` without
+    /// any real COM, so this runs on the (non-elevated) Windows CI runner. The
+    /// pure decision is table-tested in `driven_vss::fallback_decision`.
+    #[cfg(windows)]
+    #[tokio::test]
+    async fn locked_file_while_helper_pending_skips_as_pending_not_locked() {
+        use std::os::windows::fs::OpenOptionsExt;
+
+        let h = harness().await;
+        let (rel, size) = h.write_file("locked-pending.dat", b"bytes-behind-a-launching-helper");
+        let live = h.tmp_src.path().join("locked-pending.dat");
+
+        const GENERIC_WRITE: u32 = 0x4000_0000;
+        let _exclusive = std::fs::OpenOptions::new()
+            .access_mode(GENERIC_WRITE)
+            .share_mode(0)
+            .write(true)
+            .open(&live)
+            .expect("open locked-pending.dat exclusively");
+        assert!(
+            matches!(
+                super::open_shared(&live).await,
+                Err(super::OpenError::Locked)
+            ),
+            "test setup: file must be locked"
+        );
+
+        // The helper is available (capability) but its snapshot is Pending.
+        let vss: Arc<dyn driven_vss::VssProvider> = Arc::new(driven_vss::FakeVssProvider::pending(
+            driven_vss::VssMode::Auto,
+        ));
+        let exec = h.executor_with_vss(vss);
+        let out = exec
+            .execute(
+                &h.source,
+                &h.upload_plan(&rel, size),
+                &noop_progress,
+                &noop_outcome,
+            )
+            .await
+            .unwrap();
+        assert!(
+            matches!(
+                out[0],
+                OpOutcome::Skipped {
+                    reason: SkipReason::VssHelperPending,
+                    ..
+                }
+            ),
+            "a pending helper must skip-as-pending (retry next cycle), not lock; got {:?}",
+            out[0]
+        );
+        // Not committed as Synced (it re-queues for the next cycle).
+        let row = h.state.get_file_state(h.source.id, &rel).await.unwrap();
+        assert!(row.is_none() || row.unwrap().status != FileStateStatus::Synced);
+    }
+
     // --- resumable (large file) path ----------------------------------------
 
     #[tokio::test]

crates/driven-core/src/types.rs

@@ -1031,6 +1031,12 @@ pub enum ErrorCode {
     /// `local.vss_unavailable` - Driven needs elevation to use VSS but
     /// isn't elevated.
     LocalVssUnavailable,
+    /// `local.vss_helper_pending` - the least-privilege VSS helper broker is
+    /// still launching / awaiting elevation approval (DESIGN s5.3.1), so this
+    /// locked file is skipped TRANSIENTLY and retried on the next cycle. Not a
+    /// permanent lock - distinct from [`Self::LocalFileLocked`] so the brief
+    /// launch-in-progress window is not misreported as "file locked".
+    LocalVssHelperPending,
     /// `local.file_changed_during_upload` - pre/post fstat showed file
     /// mutated mid-upload; re-queued.
     LocalFileChangedDuringUpload,
@@ -1136,6 +1142,7 @@ impl ErrorCode {
             ErrorCode::DriveDestFolderPermissionDenied => "drive.dest_folder_permission_denied",
             ErrorCode::LocalFileLocked => "local.file_locked",
             ErrorCode::LocalVssUnavailable => "local.vss_unavailable",
+            ErrorCode::LocalVssHelperPending => "local.vss_helper_pending",
             ErrorCode::LocalFileChangedDuringUpload => "local.file_changed_during_upload",
             ErrorCode::LocalFileReplacedDuringUpload => "local.file_replaced_during_upload",
             ErrorCode::LocalIoError => "local.io_error",
@@ -1189,6 +1196,7 @@ impl ErrorCode {
             "drive.dest_folder_permission_denied" => ErrorCode::DriveDestFolderPermissionDenied,
             "local.file_locked" => ErrorCode::LocalFileLocked,
             "local.vss_unavailable" => ErrorCode::LocalVssUnavailable,
+            "local.vss_helper_pending" => ErrorCode::LocalVssHelperPending,
             "local.file_changed_during_upload" => ErrorCode::LocalFileChangedDuringUpload,
             "local.file_replaced_during_upload" => ErrorCode::LocalFileReplacedDuringUpload,
             "local.io_error" => ErrorCode::LocalIoError,

crates/driven-vss-helper/src/launch.rs

@@ -24,25 +24,50 @@ pub fn generate_pipe_name() -> String {
     format!(r"\\.\pipe\driven-vss-{}", uuid::Uuid::new_v4().simple())
 }
 
-/// The on-demand launch seam the app-side [`BrokeredVssProvider`] consults the
-/// FIRST time a locked file needs the helper (DESIGN s5.3.1).
+/// The readiness of the elevated helper broker for one locked-file open
+/// (DESIGN s5.3.1). Returned by [`HelperLauncher::launch_status`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LaunchStatus {
+    /// The broker is up and serving - proceed to read the locked file through it.
+    Ready,
+    /// A launch is in progress: the broker has been asked to start and is
+    /// awaiting elevation approval / bringing its pipe up (within the attended
+    /// window). The caller skips this file TRANSIENTLY and retries next cycle -
+    /// it must NOT report the file as permanently locked, and must NOT block.
+    Pending,
+    /// The user declined (or ignored) the UAC prompt this session. Memoised: the
+    /// caller degrades to skip-the-locked-file and no further prompt is raised
+    /// until the app restarts (or the toggle is switched off then on again).
+    Declined,
+    /// The least-privilege helper is not in play (the `windows.vss_helper`
+    /// setting is off, or off Windows). The caller behaves exactly like the
+    /// historical un-elevated skip.
+    Disabled,
+}
+
+/// The on-demand launch seam the app-side [`BrokeredVssProvider`] consults on the
+/// locked-file path (DESIGN s5.3.1).
 ///
 /// The provider does not launch the elevated broker itself: launch is an
 /// app-level, at-most-once concern (one UAC prompt, one helper process, one
 /// pipe name shared across every account's provider), so the app owns a single
-/// launcher and hands the SAME `Arc<dyn HelperLauncher>` to each provider.
-/// [`Self::ensure_launched`] is called lazily on the locked-file path and MUST
-/// be idempotent + memoised: a first call launches the broker; later calls (and
-/// calls from other accounts' providers) return the cached verdict without
-/// re-prompting - a user who declined the UAC prompt is not asked again for the
-/// rest of the session.
+/// launcher and hands the SAME `Arc<dyn HelperLauncher>` to each provider. The
+/// eager path (the user enabling the setting) launches ahead of any sync; the
+/// lazy path (the setting already on at boot) launches on the first locked file.
 pub trait HelperLauncher: Send + Sync {
-    /// Ensure the elevated helper has been launched for this session, launching
-    /// it at most once. Returns `true` when the helper is believed up (launch
-    /// succeeded, or a prior call already launched it), `false` when it could
-    /// not be brought up (UAC declined, helper exe missing) so the caller
-    /// degrades to skip-the-locked-file.
-    fn ensure_launched(&self) -> bool;
+    /// Report the broker's readiness for a locked-file open, TRIGGERING an
+    /// at-most-once lazy launch (non-blocking) when the helper is enabled but no
+    /// launch has been attempted yet. Never blocks on the UAC prompt: a launch in
+    /// progress reports [`LaunchStatus::Pending`] so the caller skips-and-retries
+    /// rather than waiting.
+    fn launch_status(&self) -> LaunchStatus;
+
+    /// Capability: is helper-brokered VSS in play at all this run (the setting is
+    /// on AND the user has not declined)? The executor reads this as its
+    /// `elevated` input to `fallback_decision`, so it must be `true` whenever the
+    /// broker is up OR can still be brought up - and `false` once disabled or
+    /// declined, so a disabled/declined provider behaves like the un-elevated skip.
+    fn is_available(&self) -> bool;
 }
 
 /// Build the helper's argv (excluding the program path itself):
@@ -87,17 +112,50 @@ pub fn parse_helper_args(args: &[String]) -> Result<(String, Vec<PathBuf>), Stri
     Ok((pipe_name, roots))
 }
 
-/// Launch `helper_exe` elevated with `args` via the shell `runas` verb
-/// (raises one UAC prompt). Returns when the process has been STARTED, not when
-/// it exits (the helper runs for the session). On non-Windows this is
-/// unsupported.
+/// Why an elevated launch did not succeed (DESIGN s5.3.1). The distinction drives
+/// memoisation: [`Self::Declined`] is remembered for the session (never re-prompt);
+/// [`Self::Failed`] is transient and may be retried.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LaunchError {
+    /// The user DECLINED or ignored the UAC prompt (`ERROR_CANCELLED`, 1223).
+    /// Because a cancel and a prompt-timeout both surface as `ERROR_CANCELLED`,
+    /// this means "the user did not approve" - memoise it and do not re-prompt.
+    Declined,
+    /// Any OTHER launch failure (the exe is missing, a shell error, etc). This is
+    /// transient - a later enable-toggle or app start may retry. Carries a
+    /// secret-free detail for logs.
+    Failed(String),
+}
+
+impl std::fmt::Display for LaunchError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            LaunchError::Declined => write!(f, "elevation was declined at the UAC prompt"),
+            LaunchError::Failed(detail) => write!(f, "{detail}"),
+        }
+    }
+}
+
+/// Launch `helper_exe` elevated with `args` via the shell `runas` verb (raises
+/// one UAC prompt).
+///
+/// `SEE_MASK_NOASYNC` makes `ShellExecuteExW` WAIT for the elevation to resolve
+/// even on a thread with no message loop (e.g. a worker thread), so this returns
+/// only once the user has approved (the process is then starting) or the prompt
+/// was cancelled/ignored ([`LaunchError::Declined`]). Without that flag the call
+/// can return early while the prompt is still up and surface a spurious error -
+/// the root cause of the first-cut UAC race. It still returns as soon as the
+/// process is STARTED, not when it exits (the helper serves for the session). On
+/// non-Windows this is unsupported.
 #[cfg(windows)]
-pub fn launch_elevated(helper_exe: &std::path::Path, args: &[String]) -> Result<(), String> {
+pub fn launch_elevated(helper_exe: &std::path::Path, args: &[String]) -> Result<(), LaunchError> {
     use std::os::windows::ffi::OsStrExt;
 
     use windows::core::PCWSTR;
     use windows::Win32::Foundation::{CloseHandle, GetLastError, ERROR_CANCELLED};
-    use windows::Win32::UI::Shell::{ShellExecuteExW, SEE_MASK_NOCLOSEPROCESS, SHELLEXECUTEINFOW};
+    use windows::Win32::UI::Shell::{
+        ShellExecuteExW, SEE_MASK_NOASYNC, SEE_MASK_NOCLOSEPROCESS, SHELLEXECUTEINFOW,
+    };
     use windows::Win32::UI::WindowsAndMessaging::SW_HIDE;
 
     fn wide(s: &std::ffi::OsStr) -> Vec<u16> {
@@ -119,7 +177,10 @@ pub fn launch_elevated(helper_exe: &std::path::Path, args: &[String]) -> Result<
 
     let mut info = SHELLEXECUTEINFOW {
         cbSize: std::mem::size_of::<SHELLEXECUTEINFOW>() as u32,
-        fMask: SEE_MASK_NOCLOSEPROCESS,
+        // NOASYNC: block until the elevation prompt resolves on a no-message-loop
+        // thread. NOCLOSEPROCESS: keep the started process handle so we can close
+        // it ourselves (we manage the helper over the pipe, not via this handle).
+        fMask: SEE_MASK_NOCLOSEPROCESS | SEE_MASK_NOASYNC,
         lpVerb: PCWSTR(verb.as_ptr()),
         lpFile: PCWSTR(file.as_ptr()),
         lpParameters: PCWSTR(params_w.as_ptr()),
@@ -144,18 +205,24 @@ pub fn launch_elevated(helper_exe: &std::path::Path, args: &[String]) -> Result<
             // SAFETY: reading the thread's last-error code.
             let code = unsafe { GetLastError() };
             if code == ERROR_CANCELLED {
-                Err("elevation was declined at the UAC prompt".to_string())
+                // Cancel OR prompt-timeout - both are "the user did not approve".
+                Err(LaunchError::Declined)
             } else {
-                Err(format!("ShellExecuteEx(runas) failed (error {})", code.0))
+                Err(LaunchError::Failed(format!(
+                    "ShellExecuteEx(runas) failed (error {})",
+                    code.0
+                )))
             }
         }
     }
 }
 
 /// Non-Windows: elevated launch is unsupported (VSS is Windows-only).
 #[cfg(not(windows))]
-pub fn launch_elevated(_helper_exe: &std::path::Path, _args: &[String]) -> Result<(), String> {
-    Err("the VSS helper is only supported on Windows".to_string())
+pub fn launch_elevated(_helper_exe: &std::path::Path, _args: &[String]) -> Result<(), LaunchError> {
+    Err(LaunchError::Failed(
+        "the VSS helper is only supported on Windows".to_string(),
+    ))
 }
 
 /// Quote a single argv element for a Windows command-line parameter string.

crates/driven-vss-helper/src/lib.rs

@@ -33,7 +33,7 @@ pub mod protocol;
 pub mod validate;
 
 mod provider;
-pub use launch::HelperLauncher;
+pub use launch::{HelperLauncher, LaunchError, LaunchStatus};
 pub use provider::BrokeredVssProvider;
 
 #[cfg(windows)]