fix: let a slow add-source wizard finish instead of failing with a phantom disk error (#291)

## The bug (diagnosed from a user diagnostic bundle)

Creating a backup source failed every time with **"Driven hit a disk
error reading a file"** — with zero real disk errors anywhere and **zero
trace of the six failed `add_source` calls in the logs**. Root cause
chain:

1. `add_source` resolved the local folder from a single-use dialog token
with a **5-minute TTL**. A real wizard session (big-tree exclusion
preview + Drive destination browsing + thinking) outlives that, so
Finish always failed.
2. `take_dialog_token` consumed the token **before** any validation, so
the first failed Finish destroyed it and every retry in the same session
failed too.
3. Both failure modes were mapped to `local.io_error`, whose copy tells
the user their **disk** is failing.
4. Command rejections were never logged, so the diagnostic bundle
contained nothing to diagnose with.

## The fix

- **`add_source` peeks up front and spends the token only at commit**
(the same R3-P2-1 pattern the restore command already uses), so failed
validation leaves the token intact.
- **`DIALOG_TOKEN_TTL` 5 min → 60 min**; the binding now stores its
expiry instant (testable without `Instant` underflow).
- **New stable code `internal.stale_dialog_token`** (SPEC §24 + en-US
copy "pick the folder again") replaces the `local.io_error` mapping for
unknown/spent/expired tokens across `add_source`, exclusion previews,
restore, and the diagnostic export. The dialog-*cancel* sentinel is
untouched.
- **Every `CommandError` is now logged (WARN) as it serialises across
the IPC boundary** — the single seam every rejection passes through — so
failures land in the rolling log and diagnostic bundles. Known
trade-off: a UI polling loop against a persistently failing command
writes one WARN per poll; accepted for diagnosability.
- **Wizard error UI**: the add-source and setup wizards render a muted,
monospace technical-detail line (stable code + redacted backend message)
under the localized error.

## ⚠️ Deliberate amendment to the R8-P2-1 contract

R8-P2-1 said backend English must never render. This PR **narrows**
that: the localized `t(errors.${code}.long)` string remains the only
primary error, but a dedicated muted detail element may carry the stable
code + backend `message`. Rationale: two failures sharing one code
(expired token vs. genuinely unreadable folder) were indistinguishable
on screen, which is how a token expiry masqueraded as a disk error. The
`recovery-reveal-error-i18n` test is updated to enforce the new shape
(primary line exactly localized; backend text only inside
`*-error-detail`).

## Tests

- `cargo check --workspace --all-targets` clean; `cargo fmt --check`
clean (dockerized); driven-core 555 + driven-app 417 lib tests +
ipc_path_validation pass
- New: token-expiry rejection test
(`expired_dialog_token_is_rejected_by_peek_and_take`), stale-token i18n
copy test, detail-line rendering assertions
- UI: eslint 0 errors, prettier clean, vue-tsc clean, 778 vitest pass

README checked, no changes needed (no stale claims; behavior-level fix
below the feature list).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01LRMdu3VkuhL6Ny6hRcnFpU

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: pmaxhogan

crates/driven-core/src/types.rs

@@ -1178,6 +1178,16 @@ pub enum ErrorCode {
     /// not an internal programming error, so the UI shows a "check your input"
     /// message rather than "please report a bug".
     InvalidInput,
+    /// `internal.stale_dialog_token` - a path-bearing command presented a
+    /// backend-minted dialog token that is unknown, already spent, or past its
+    /// TTL (SPEC s11.6.1 C1). The remedy is always the same: re-open the native
+    /// picker so a fresh token is minted, then retry - nothing else about the
+    /// request needs to change. Deliberately DISTINCT from
+    /// [`Self::LocalIoError`]: for months an expired add-source token surfaced
+    /// as "Driven hit a disk error reading a file", sending users off to check
+    /// a perfectly healthy drive when the wizard had simply outlived the
+    /// token's TTL.
+    StaleDialogToken,
     /// `sftp.root_missing` - the SSH (SFTP) destination's configured root path
     /// does not exist on the server. Surfaced only at account-creation time
     /// (`create_sftp_account`'s probe never creates the root - a typo must not
@@ -1268,6 +1278,7 @@ impl ErrorCode {
             ErrorCode::HarnessTimeout => "harness.timeout",
             ErrorCode::InternalBug => "internal.bug",
             ErrorCode::InvalidInput => "internal.invalid_input",
+            ErrorCode::StaleDialogToken => "internal.stale_dialog_token",
             ErrorCode::SftpRootMissing => "sftp.root_missing",
             ErrorCode::SftpRootNotADirectory => "sftp.root_not_a_directory",
             ErrorCode::SftpDestMarkerMismatch => "sftp.dest_marker_mismatch",
@@ -1329,6 +1340,7 @@ impl ErrorCode {
             "harness.timeout" => ErrorCode::HarnessTimeout,
             "internal.bug" => ErrorCode::InternalBug,
             "internal.invalid_input" => ErrorCode::InvalidInput,
+            "internal.stale_dialog_token" => ErrorCode::StaleDialogToken,
             "sftp.root_missing" => ErrorCode::SftpRootMissing,
             "sftp.root_not_a_directory" => ErrorCode::SftpRootNotADirectory,
             "sftp.dest_marker_mismatch" => ErrorCode::SftpDestMarkerMismatch,

design/SPEC.md

@@ -1821,6 +1821,7 @@ Stable codes (V1):
 | `drive.dest_folder_permission_denied` | Destination folder's sharing changed to read-only for this account |
 | `harness.timeout`            | A stress-harness scenario exceeded its budget (chaos crate only) |
 | `internal.bug`               | Programming error — please report             |
+| `internal.stale_dialog_token` | A backend-minted dialog token (§11.6.1 C1) was unknown, already spent, or past its TTL — re-open the native picker and retry. Distinct from `local.io_error`: the disk is fine |
 
 Frontend maps these to user-friendly messages via
 `t('errors.${code}.short')` and `t('errors.${code}.long')` per DESIGN

src-tauri/src/app_state.rs

@@ -263,9 +263,9 @@ pub struct AppState {
     /// bound to the path the USER actually chose. A path-bearing write command
     /// (`add_source`, `export_diagnostic_bundle`) must present a token that maps
     /// to exactly that path - so the (untrusted) webview can never inject an
-    /// arbitrary path. Single-use (taken on validation) with a short TTL so a
-    /// leaked token cannot be replayed later. Behind a sync `Mutex` (only ever
-    /// held for a quick insert / take, never across an await).
+    /// arbitrary path. Single-use (spent when the write commits) with a bounded
+    /// TTL so a leaked token cannot be replayed later. Behind a sync `Mutex`
+    /// (only ever held for a quick insert / take, never across an await).
     dialog_tokens: std::sync::Mutex<HashMap<String, DialogTokenBinding>>,
     /// R2-P1-1: per-account ASYNC lock serialising the FIRST-encrypted-source
     /// critical section (ensure-master-key -> stamp -> insert source). Without
@@ -606,20 +606,30 @@ fn prune_terminal_jobs(map: &mut HashMap<String, RestoreJobEntry>) {
 }
 
 /// C1: one backend-minted dialog-token binding - the path the user chose via a
-/// native dialog plus the instant it was minted (for the short single-use TTL).
+/// native dialog plus the instant the binding expires (single-use TTL).
 struct DialogTokenBinding {
     /// The path the native dialog returned (a folder for the folder dialog, a
     /// concrete file path for the save dialog).
     path: std::path::PathBuf,
-    /// When the token was minted (for TTL expiry).
-    minted_at: std::time::Instant,
+    /// When the token stops being valid (mint time + [`DIALOG_TOKEN_TTL`]).
+    /// Stored as the deadline rather than the mint instant so tests can force
+    /// expiry without `Instant` subtraction (which can underflow soon after
+    /// boot in CI).
+    expires_at: std::time::Instant,
 }
 
-/// C1: how long a backend-minted dialog token stays valid. The webview calls the
-/// dialog command then immediately calls the write command with the token, so a
-/// few minutes is generous; a token older than this is rejected so a leaked one
-/// cannot be replayed much later.
-const DIALOG_TOKEN_TTL: Duration = Duration::from_secs(300);
+/// C1: how long a backend-minted dialog token stays valid.
+///
+/// This must cover the LONGEST honest gap between the native dialog and the
+/// write command that spends the token - which is NOT "immediately": the
+/// add-source wizard picks the local folder first and then walks the whole
+/// tree for the exclusion preview, browses the destination, and waits on the
+/// user to think, which on a big source is well over the 5 minutes this
+/// originally allowed. An expired token used to surface as `local.io_error`
+/// ("disk error"), sending users to check a healthy drive. An hour keeps the
+/// replay window bounded (the token is also single-use and process-local)
+/// without a live wizard session ever outrunning it.
+const DIALOG_TOKEN_TTL: Duration = Duration::from_secs(3600);
 
 impl AppState {
     /// Build the managed state from the state repo, the per-account handles,
@@ -1208,12 +1218,12 @@ impl AppState {
         let token = uuid::Uuid::new_v4().to_string();
         let mut map = self.lock_dialog_tokens();
         let now = std::time::Instant::now();
-        map.retain(|_, b| now.duration_since(b.minted_at) < DIALOG_TOKEN_TTL);
+        map.retain(|_, b| now < b.expires_at);
         map.insert(
             token.clone(),
             DialogTokenBinding {
                 path,
-                minted_at: now,
+                expires_at: now + DIALOG_TOKEN_TTL,
             },
         );
         token
@@ -1226,7 +1236,7 @@ impl AppState {
     pub fn take_dialog_token(&self, token: &str) -> Option<std::path::PathBuf> {
         let mut map = self.lock_dialog_tokens();
         let binding = map.remove(token)?;
-        if std::time::Instant::now().duration_since(binding.minted_at) >= DIALOG_TOKEN_TTL {
+        if std::time::Instant::now() >= binding.expires_at {
             return None;
         }
         Some(binding.path)
@@ -1242,12 +1252,23 @@ impl AppState {
     pub fn peek_dialog_token(&self, token: &str) -> Option<std::path::PathBuf> {
         let map = self.lock_dialog_tokens();
         let binding = map.get(token)?;
-        if std::time::Instant::now().duration_since(binding.minted_at) >= DIALOG_TOKEN_TTL {
+        if std::time::Instant::now() >= binding.expires_at {
             return None;
         }
         Some(binding.path.clone())
     }
 
+    /// Test-only: force `token`'s binding past its TTL so expiry behaviour can
+    /// be exercised without sleeping or `Instant` arithmetic that underflows
+    /// soon after boot.
+    #[cfg(test)]
+    pub fn expire_dialog_token_for_test(&self, token: &str) {
+        let mut map = self.lock_dialog_tokens();
+        if let Some(b) = map.get_mut(token) {
+            b.expires_at = std::time::Instant::now();
+        }
+    }
+
     /// The streaming-exclusion-preview registry (see the
     /// [`Self::exclusion_previews`] field docs). Returns an owned `Arc` so the
     /// spawned blocking walk can deregister itself after the command that
@@ -2068,6 +2089,34 @@ pub(crate) mod tests {
         let _ = std::fs::remove_dir_all(dir);
     }
 
+    #[tokio::test]
+    async fn expired_dialog_token_is_rejected_by_peek_and_take() {
+        // C1: a token past its TTL must resolve for NEITHER the non-consuming
+        // peek nor the consuming take - the wizard gets the stable
+        // `internal.stale_dialog_token` rejection (never a phantom disk error)
+        // and re-picking mints a fresh, working token.
+        let (state, dir) = temp_state().await;
+        let app_state = AppState::new(
+            state,
+            HashMap::new(),
+            RemoteMode::Fake,
+            default_fake_registry(),
+        );
+        let path = std::path::PathBuf::from("/home/u/slow-wizard-root");
+        let token = app_state.mint_dialog_token(path.clone());
+        assert_eq!(app_state.peek_dialog_token(&token), Some(path.clone()));
+
+        app_state.expire_dialog_token_for_test(&token);
+        assert_eq!(app_state.peek_dialog_token(&token), None);
+        assert_eq!(app_state.take_dialog_token(&token), None);
+
+        // Re-picking (a fresh mint of the same path) works immediately.
+        let fresh = app_state.mint_dialog_token(path.clone());
+        assert_eq!(app_state.take_dialog_token(&fresh), Some(path));
+
+        let _ = std::fs::remove_dir_all(dir);
+    }
+
     #[tokio::test]
     async fn ensure_master_key_lock_is_shared_per_account_and_serialises() {
         // R2-P1-1: two `add_source` calls for the SAME account must get the SAME

src-tauri/src/commands/dialogs.rs

@@ -118,6 +118,12 @@ fn file_path_to_pathbuf(fp: tauri_plugin_dialog::FilePath) -> Option<std::path::
 }
 
 /// The shared "user cancelled the dialog" error (a benign no-advance signal).
+/// The message is the [`crate::commands::DIALOG_CANCELLED_MSG`] sentinel the
+/// IPC-boundary logging recognises, so a cancelled picker is not logged as a
+/// command failure.
 fn cancelled() -> CommandError {
-    CommandError::with_code(ErrorCode::LocalIoError, "dialog cancelled")
+    CommandError::with_code(
+        ErrorCode::LocalIoError,
+        crate::commands::DIALOG_CANCELLED_MSG,
+    )
 }

src-tauri/src/commands/mod.rs

@@ -44,7 +44,7 @@ use driven_core::types::ErrorCode;
 /// (not the SPEC s24 example's literal `retry_after_ms`). `code` + `message` are
 /// identical in both casings and `details` is single-word; only the retry-after
 /// hint differs, and the frontend reads only `.code`.
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CommandError {
     /// The stable dotted SPEC s24 error code (i18n key), e.g.
@@ -94,6 +94,46 @@ impl CommandError {
     }
 }
 
+/// The benign "user closed the native dialog" sentinel message. It rides the
+/// normal error channel purely as a no-advance signal to the webview (see
+/// [`dialogs`]), so the boundary logging below must not turn every cancelled
+/// picker into a scary WARN line.
+pub(crate) const DIALOG_CANCELLED_MSG: &str = "dialog cancelled";
+
+impl Serialize for CommandError {
+    /// Serialise the stable SPEC s24 wire shape - and, because a command's
+    /// `Err` is serialised exactly once, HERE, as it crosses the IPC boundary
+    /// to the webview, this is the single seam where every command rejection
+    /// can be logged into the rolling log file (and thus the SPEC s18
+    /// diagnostic bundle). Before this, a rejected command left no backend
+    /// trace at all: six straight failed `add_source` calls produced a
+    /// diagnostic bundle with zero ERROR/WARN lines about them, and the bug
+    /// had to be reconstructed from what was ABSENT from the log.
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        if self.message != DIALOG_CANCELLED_MSG {
+            tracing::warn!(
+                target: "driven::app::ipc",
+                code = %self.code,
+                message = %self.message,
+                "IPC command rejected"
+            );
+        }
+        use serde::ser::SerializeStruct as _;
+        let fields =
+            2 + usize::from(self.retry_after_ms.is_some()) + usize::from(self.details.is_some());
+        let mut s = serializer.serialize_struct("CommandError", fields)?;
+        s.serialize_field("code", &self.code)?;
+        s.serialize_field("message", &self.message)?;
+        if let Some(retry_after_ms) = self.retry_after_ms {
+            s.serialize_field("retryAfterMs", &retry_after_ms)?;
+        }
+        if let Some(details) = &self.details {
+            s.serialize_field("details", details)?;
+        }
+        s.end()
+    }
+}
+
 impl std::fmt::Display for CommandError {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}: {}", self.code, self.message)
@@ -543,6 +583,22 @@ pub fn atomic_write(dest: &Path, bytes: &[u8]) -> CommandResult<()> {
 /// component, (2) canonicalise via `dunce` (rejecting a non-existent path), and
 /// (3) require the canonical target to be a directory. Returns the canonical
 /// root the scanner then walks.
+/// The stable rejection for a backend-minted dialog token that is unknown,
+/// already spent, or past its TTL (SPEC s11.6.1 C1) - shared by every
+/// path-bearing command that resolves one (`add_source`, the exclusion
+/// previews, restore, the diagnostic-bundle export).
+///
+/// `internal.stale_dialog_token`, deliberately NOT `local.io_error`: the disk
+/// is fine, the folder pick just needs redoing. The io_error mapping made an
+/// expired add-source token render as "Driven hit a disk error reading a
+/// file", pointing users at a healthy drive.
+pub(crate) fn stale_dialog_token_error() -> CommandError {
+    CommandError::with_code(
+        ErrorCode::StaleDialogToken,
+        "the folder selection expired or was already used; open the folder picker again",
+    )
+}
+
 pub fn validate_readable_dir(path: &Path) -> CommandResult<PathBuf> {
     if path.components().any(|c| matches!(c, Component::ParentDir)) {
         return Err(CommandError::with_code(

src-tauri/src/commands/restore.rs

@@ -298,12 +298,9 @@ pub async fn restore_files(
     // token is CONSUMED only immediately before the job is actually accepted (just
     // before the atomic seed+spawn), so the single use is spent only on a real
     // restore. A missing / replayed / expired token is still rejected here.
-    let dest_dir = state.peek_dialog_token(&dest_token).ok_or_else(|| {
-        CommandError::with_code(
-            ErrorCode::LocalIoError,
-            "no matching destination folder; pick a restore folder first",
-        )
-    })?;
+    let dest_dir = state
+        .peek_dialog_token(&dest_token)
+        .ok_or_else(crate::commands::stale_dialog_token_error)?;
     // The destination directory must exist + be a directory (the user picked it).
     let dest_meta = std::fs::metadata(&dest_dir).map_err(|e| {
         CommandError::with_code(
@@ -346,10 +343,7 @@ pub async fn restore_files(
     // spend the single use so the token cannot be replayed. A concurrent take that
     // already consumed it (None) is rejected without spawning a job.
     if state.take_dialog_token(&dest_token).is_none() {
-        return Err(CommandError::with_code(
-            ErrorCode::LocalIoError,
-            "no matching destination folder; pick a restore folder first",
-        ));
+        return Err(crate::commands::stale_dialog_token_error());
     }
     // R5-P1-3 (DATA-SAFETY): BIND the approved root to a STABLE identity (canonical
     // path + on-disk dev/inode or volume file-id) right now, at consume time. The

src-tauri/src/commands/settings.rs

@@ -1767,12 +1767,9 @@ pub async fn export_diagnostic_bundle(
     // C1: resolve the save path from the backend-minted dialog token (single-use).
     // Reject any request without a matching token - the webview never supplies a
     // raw path here.
-    let dest = state.take_dialog_token(&token).ok_or_else(|| {
-        CommandError::with_code(
-            ErrorCode::LocalIoError,
-            "no matching dialog token for the export destination; pick a save location first",
-        )
-    })?;
+    let dest = state
+        .take_dialog_token(&token)
+        .ok_or_else(crate::commands::stale_dialog_token_error)?;
 
     // C2: the token's path is a concrete FILE. Confine the write to its parent
     // directory (the dialog-approved root) and re-validate the leaf.