SMB: auto-upgrade on dev profiles, plus MCP visibility and trigger

Three fixes that all touch the same flow: existing OS-mounted SMB shares can now reach the fast direct-smb2 path automatically (or via MCP for agents), and agents can see which volumes are on which path.

Auto-upgrade for dev profiles (#1): `upgrade_existing_smb_mounts` now takes an `AppHandle` and calls `crate::network::ensure_mdns_started` itself when it finds SMB mounts to upgrade. The `firstTriggerDone` gate is gone from this call site — the function is a no-op when there are no SMB mounts (no network activity, no macOS Local Network prompt), so the gate was protecting nothing useful. With mounts present and `network.directSmbConnection` on (default true), mDNS now starts at launch and the upgrade can resolve hostname-keyed Keychain creds the same way the manual "Connect directly" button does. Dev profiles with `firstTriggerDone == false` and an auto-reconnected SMB share previously stayed on the slow OS-mount path indefinitely; that's the bug.

MCP visibility (#3): `cmdr://state`'s volumes section now emits structured entries for SMB volumes with `name`, `id`, and `smbConnectionState` (`direct` | `os_mount` | `disconnected`). Non-SMB volumes stay as bare `- {name}` lines for compactness. Agents can now distinguish which SMB shares are on the fast path.

MCP trigger (#2): new `upgrade_smb_to_direct` tool, sibling of `connect_to_server` and `remove_manual_server` in the network category. Thin wrapper around the same upgrade flow the manual UI uses. Calls a newly-extracted `upgrade_to_smb_volume_inner` helper (the Tauri command's body minus the concrete-AppHandle mDNS kick) so the MCP executor — generic over `Runtime` — can reuse the logic. Tool description steers agents: if mDNS isn't running and hostname-keyed Keychain creds matter, take a network action first.

Refactor along the way: `enrich_smb_connection_state` was duplicated across `commands/volumes.rs` (for `list_volumes`) and `volume_broadcast.rs` (for `volumes-changed`) with a "must stay in sync" gotcha. With MCP becoming a third caller, the sync risk grew. Extracted to `volumes::enrich_smb_connection_state`; all three call sites now share it. CLAUDE.md gotcha → decision.

Tests / docs:
- MCP `test_all_tools_count` / `test_network_tools_count` bumped (29 → 30, 2 → 3).
- MCP `test_total_tool_count` bumped to 30.
- file_system/volume/CLAUDE.md startup-upgrade lifecycle entry updated to reflect the new mDNS-kick path and no-gate semantics.
- mcp/CLAUDE.md tool count, network category list, and `cmdr://state` volumes-shape description updated.
- volumes/CLAUDE.md "two-site sync" gotcha replaced with a single-source decision entry.

Verified: full `./scripts/check.sh` green (50 checks, 1983 unit + 32 integration + every linter), including the 189 MCP unit tests.

Author: vdavid

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

@@ -354,6 +354,24 @@ pub async fn mount_network_share(
 #[tauri::command]
 #[specta::specta]
 pub async fn upgrade_to_smb_volume(volume_id: String, app_handle: tauri::AppHandle) -> Result<UpgradeResult, String> {
+    // Kick mDNS off so IP → hostname resolution has a shot before we hit the
+    // Keychain. Idempotent; no-op if already running or `network.enabled` is off.
+    // Kept here (and not in `upgrade_to_smb_volume_inner`) because
+    // `ensure_mdns_started` requires a concrete `AppHandle`, while the inner
+    // function needs to stay AppHandle-free so the MCP executor (generic over
+    // `Runtime`) can call it. MCP relies on mDNS having been started elsewhere
+    // (initial launch with `firstTriggerDone == true`, or any prior network
+    // action); the MCP tool's description tells agents to take a network
+    // action first if their target volume needs hostname-keyed creds.
+    crate::network::ensure_mdns_started(app_handle);
+    upgrade_to_smb_volume_inner(volume_id).await
+}
+
+/// Body of `upgrade_to_smb_volume` minus the mDNS kick (which needs concrete
+/// `AppHandle`). Used by the Tauri command above and by the MCP
+/// `upgrade_smb_to_direct` executor — both routes share the same Keychain
+/// lookup, mDNS-cached hostname resolution, and `try_smb_upgrade` body.
+pub async fn upgrade_to_smb_volume_inner(volume_id: String) -> Result<UpgradeResult, String> {
     use crate::file_system::get_volume_manager;
     #[cfg(target_os = "macos")]
     use crate::volumes::get_smb_mount_info;
@@ -387,10 +405,6 @@ pub async fn upgrade_to_smb_volume(volume_id: String, app_handle: tauri::AppHand
         info.username
     );
 
-    // Kick mDNS off so IP → hostname resolution has a shot before we hit the
-    // Keychain. Idempotent; no-op if already running or `network.enabled` is off.
-    crate::network::ensure_mdns_started(app_handle);
-
     // Try to get credentials from Keychain. The mount source has the IP, but Cmdr
     // stores Keychain credentials keyed by hostname (from mDNS). Try both. Briefly
     // wait for mDNS to warm up so we don't prompt for creds the user already saved.
@@ -691,7 +705,7 @@ pub fn remove_manual_server(server_id: String, app_handle: tauri::AppHandle) ->
 pub fn ensure_network_discovery_started(app_handle: tauri::AppHandle) {
     crate::network::start_discovery(app_handle.clone());
     manual_servers::load_manual_servers(&app_handle);
-    crate::file_system::upgrade_existing_smb_mounts();
+    crate::file_system::upgrade_existing_smb_mounts(app_handle.clone());
 
     #[cfg(feature = "smb-e2e")]
     crate::network::virtual_smb_hosts::setup_virtual_smb_hosts(&app_handle);

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

@@ -4,7 +4,6 @@ use serde::Serialize;
 use tokio::time::Duration;
 
 use super::util::{TimedOut, blocking_with_timeout_flag};
-use crate::file_system::get_volume_manager;
 use crate::volumes::{self, DEFAULT_VOLUME_ID, LocationCategory, VolumeInfo, VolumeSpaceInfo};
 
 /// Result of resolving a path to its containing volume.
@@ -26,32 +25,10 @@ const VOLUME_TIMEOUT: Duration = Duration::from_secs(2);
 pub async fn list_volumes() -> TimedOut<Vec<VolumeInfo>> {
     let mut result = blocking_with_timeout_flag(VOLUME_TIMEOUT, vec![], volumes::list_mounted_volumes).await;
     append_mtp_volumes(&mut result.data).await;
-    enrich_smb_connection_state(&mut result.data);
+    volumes::enrich_smb_connection_state(&mut result.data);
     result
 }
 
-/// Enriches volume entries with SMB connection state from the VolumeManager.
-///
-/// For each volume, looks up the registered Volume in VolumeManager and checks
-/// if it reports an `smb_connection_state`. This adds the green/yellow indicator
-/// for SMB shares in the frontend volume picker.
-fn enrich_smb_connection_state(volumes: &mut [VolumeInfo]) {
-    use crate::volumes::SmbConnectionState;
-
-    let manager = get_volume_manager();
-    for vol in volumes.iter_mut() {
-        if let Some(registered) = manager.get(&vol.id) {
-            vol.smb_connection_state = registered.smb_connection_state();
-        }
-
-        // SMB shares without a direct smb2 connection show as OsMount (yellow).
-        // This covers pre-existing mounts registered as LocalPosixVolume at startup.
-        if vol.smb_connection_state.is_none() && volumes::is_smb_fs_type(vol.fs_type.as_deref()) {
-            vol.smb_connection_state = Some(SmbConnectionState::OsMount);
-        }
-    }
-}
-
 /// Gets the default volume ID (root filesystem).
 #[tauri::command]
 #[specta::specta]

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

@@ -186,8 +186,22 @@ pub fn get_volume_manager() -> &'static VolumeManager {
 ///
 /// Scans all registered volumes, finds those on `smbfs`, and tries to establish
 /// a parallel smb2 session for each. Non-blocking: failures are logged and skipped.
+///
+/// If any SMB mounts are found, kicks off mDNS via `ensure_mdns_started` so the
+/// upgrade's Keychain lookup (keyed by hostname, not IP) can find stored creds.
+/// This mirrors the manual "Connect directly" and mount-time auto-upgrade paths,
+/// so existing OS-mounted SMB shares get the same treatment as new ones — see
+/// the "SMB upgrade waits briefly for mDNS to warm" gotcha in
+/// `network/CLAUDE.md`. Kicking off mDNS will pop the macOS Local Network prompt
+/// once per app on first launch; that's the trade-off for not requiring users
+/// to click "Connect directly" on every relaunch when they have direct-SMB on
+/// and an existing mount.
+///
+/// Returns silently when:
+/// - direct-SMB is disabled (`network.directSmbConnection`),
+/// - or no SMB mounts are registered (no scan cost, no prompt).
 #[cfg(any(target_os = "macos", target_os = "linux"))]
-pub fn upgrade_existing_smb_mounts() {
+pub fn upgrade_existing_smb_mounts(app_handle: tauri::AppHandle) {
     #[cfg(target_os = "macos")]
     use crate::volumes::get_smb_mount_info;
     #[cfg(target_os = "linux")]
@@ -229,6 +243,13 @@ pub fn upgrade_existing_smb_mounts() {
         volumes_to_upgrade.len()
     );
 
+    // Kick off mDNS so `resolve_ip_to_hostname` can find the host. Without this,
+    // the Keychain lookup misses on auth-required shares (creds are keyed by
+    // hostname like `smb://naspolya/share`, not by IP). Same pattern as the
+    // manual `upgrade_to_smb_volume` and mount-time `try_upgrade_smb_mount`
+    // paths. Idempotent: no-op if mDNS is already running.
+    crate::network::ensure_mdns_started(app_handle);
+
     // Use tauri's runtime spawn (this runs during setup() before Tokio is fully available).
     // Wait for mDNS discovery to reach Active state (initial burst complete) so hostname
     // resolution is available for Keychain lookup.

apps/desktop/src-tauri/src/file_system/volume/CLAUDE.md

@@ -207,17 +207,22 @@ The same rule applies to write paths: `write_from_stream` must drive the backend
 
 SMB mounts are automatically upgraded to `SmbVolume` (direct smb2 connection) in two scenarios:
 
-1. **Startup** (`file_system::upgrade_existing_smb_mounts`): Scans registered volumes for `smbfs` type. Waits for mDNS
-   discovery to reach `Active` state (polls every 500ms, up to 15s) because Keychain credentials are keyed by hostname
-   (from mDNS), not IP (from `statfs`). Uses `tauri::async_runtime::spawn` (not `tokio::spawn`; runs during `setup()`
-   before Tokio is fully available). Emits `volumes-changed` after upgrades so the frontend refreshes indicators.
+1. **Startup** (`file_system::upgrade_existing_smb_mounts(app_handle)`): Scans registered volumes for `smbfs` type. If
+   any are found, calls `network::ensure_mdns_started` to kick off mDNS itself (creds are keyed by hostname, not IP),
+   then waits for mDNS to reach `Active` state (polls every 500ms, up to 15s). Uses `tauri::async_runtime::spawn` (not
+   `tokio::spawn`; runs during `setup()` before Tokio is fully available). Emits `volumes-changed` after upgrades so
+   the frontend refreshes indicators. **No `firstTriggerDone` gate**: the function is a no-op when no SMB mounts are
+   present (no network activity, no macOS Local Network prompt). When mounts are present AND `network.directSmbConnection`
+   is on (default `true`), it kicks off mDNS — that's when the macOS prompt fires, once per app per data dir. Before
+   this change the upgrade was gated behind `firstTriggerDone`, so dev profiles with auto-reconnected SMB shares stayed
+   on the slow OS-mount path forever.
 
 2. **Mount detection** (`volumes/watcher.rs::try_upgrade_smb_mount`): When FSEvents detects a new volume in `/Volumes/`
-   and it's `smbfs`, spawns a background upgrade attempt. By this point mDNS is already active.
+   and it's `smbfs`, spawns a background upgrade attempt. Calls `ensure_mdns_started` to kick off mDNS too.
 
 Both paths check the `network.directSmbConnection` setting (global `AtomicBool`). Both are best-effort. Failures log a
 warning and the volume stays as `LocalPosixVolume`. The "Connect directly" UI action (`upgrade_to_smb_volume` command)
-provides a manual upgrade path.
+and the MCP `upgrade_smb_to_direct` tool provide manual upgrade paths.
 
 ## SMB live-reconnect lifecycle
 

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

@@ -501,15 +501,14 @@ pub fn run() {
             space_poller::start();
 
             // Upgrade existing SMB mounts to direct smb2 connections (background, non-blocking).
-            // Gated on the same lazy-startup conditions as mDNS above. Opening a TCP socket to
-            // a private-IP SMB server triggers macOS's Local Network prompt independently, so
-            // we must not run this on fresh installs either. Returning users already answered
-            // the prompt; lazy users wait until they click Network or use the picker's "Connect
-            // directly" indicator.
+            // No `firstTriggerDone` gate here: the function is a no-op when there are no SMB
+            // mounts (no network activity, no prompt). When there ARE mounts and direct-SMB is
+            // enabled, the function kicks off mDNS itself so the Keychain lookup can resolve
+            // hostnames — same shape as the manual "Connect directly" and mount-time paths.
+            // The macOS Local Network prompt fires once per app and only when an SMB mount is
+            // present at launch; subsequent launches start mDNS eagerly via `firstTriggerDone`.
             #[cfg(any(target_os = "macos", target_os = "linux"))]
-            if should_start_network_at_launch {
-                file_system::upgrade_existing_smb_mounts();
-            }
+            file_system::upgrade_existing_smb_mounts(app.handle().clone());
 
             // Check if there's an existing license (for menu text)
             let has_existing_license = licensing::get_license_info(app.handle()).is_some();

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

@@ -21,7 +21,7 @@ Expose Cmdr functionality to AI agents via the Model Context Protocol (MCP). Age
 
 ### Tools (`tools.rs`)
 
-29 semantic tools grouped by category:
+30 semantic tools grouped by category:
 - Navigation (6): `select_volume` (also accepts MTP volume names), `nav_to_path` (supports `mtp://` paths, skips filesystem existence check), `nav_to_parent`, `nav_back`, `nav_forward`, `scroll_to`
 - Cursor/Selection (3): `move_cursor`, `open_under_cursor`, `select`
 - File operations (6): `copy`, `move`, `delete`, `mkdir`, `mkfile`, `refresh`. `copy`/`move` accept optional `autoConfirm` (bool) and `onConflict` (`skip_all`|`overwrite_all`|`rename_all`). `delete` accepts optional `autoConfirm`. When `autoConfirm` is true, the dialog opens and immediately confirms.
@@ -31,12 +31,12 @@ Expose Cmdr functionality to AI agents via the Model Context Protocol (MCP). Age
 - App (3): `switch_pane`, `swap_panes`, `quit`
 - Search (2): `search` (structured file search across the drive index, optional `scope` for path/exclude filtering), `ai_search` (natural language search using configured LLM, optional `scope` merged with AI-inferred scope)
 - Settings (1): `set_setting` (change a setting value via round-trip to frontend)
-- Network (2): `connect_to_server` (add a manual SMB server by address, checks TCP reachability), `remove_manual_server` (remove a manually-added server by host ID)
+- Network (3): `connect_to_server` (add a manual SMB server by address, checks TCP reachability), `remove_manual_server` (remove a manually-added server by host ID), `upgrade_smb_to_direct` (upgrade an OS-mounted SMB volume to a direct smb2 session for faster I/O; thin wrapper over the existing manual "Connect directly" Tauri command — tries Keychain creds, returns a typed result mirroring `UpgradeResult`)
 - Async (1): `await` (poll PaneStateStore until a condition is met: `has_item`, `item_count_gte`, `path`, or `path_contains`. Supports `after_generation` to avoid matching stale state)
 
 ### Resources (`resources.rs`)
 
-- `cmdr://state`: Complete app state in YAML (both panes, volumes, dialogs, active `listings` cache, `recentErrors`). Includes MTP volumes with `name` and `id`, and per-pane `volumeId`. The `listings` section reflects every entry in `LISTING_CACHE` (id, volumeId, path, entry count, ageMs); `recentErrors` is the last 20 directory-listing failures with `atUnixMs`, `listingId`, `volumeId`, `path`, `message` (see `listing_errors.rs` and the freshness contract below). Supports `?include=panes,volumes,dialogs,listings,recentErrors` projection (defaults to all) and `?compact=true` (drops the `files:` list inside each pane while keeping every summary field). Example: `cmdr://state?include=listings,recentErrors` is the minimal payload for "did the last listing succeed?".
+- `cmdr://state`: Complete app state in YAML (both panes, volumes, dialogs, active `listings` cache, `recentErrors`). Includes MTP volumes with `name` and `id`, and per-pane `volumeId`. SMB volumes appear as structured entries with `name`, `id`, and `smbConnectionState` (`direct` | `os_mount` | `disconnected`) so agents can route the `upgrade_smb_to_direct` tool at the right volumes; non-SMB volumes stay as bare `- {name}` lines. The `listings` section reflects every entry in `LISTING_CACHE` (id, volumeId, path, entry count, ageMs); `recentErrors` is the last 20 directory-listing failures with `atUnixMs`, `listingId`, `volumeId`, `path`, `message` (see `listing_errors.rs` and the freshness contract below). Supports `?include=panes,volumes,dialogs,listings,recentErrors` projection (defaults to all) and `?compact=true` (drops the `files:` list inside each pane while keeping every summary field). Example: `cmdr://state?include=listings,recentErrors` is the minimal payload for "did the last listing succeed?".
 - `cmdr://dialogs/available`: Static metadata about available dialogs
 - `cmdr://indexing`: Drive indexing status in plain text (current phase, timeline history, DB stats). Calls `indexing::get_debug_status()` and formats as human-readable text.
 - `cmdr://settings`: All settings with current values, defaults, types, and constraints. Fetched via round-trip to the frontend (`mcp-get-all-settings` event).
@@ -50,7 +50,7 @@ Directory module split by tool category. `mod.rs` contains the main `execute_too
 - `nav.rs`: navigation commands (with and without params)
 - `file_ops.rs`: copy, move, delete, mkdir, mkfile, refresh, select
 - `dialogs.rs`: unified dialog open/focus/close/confirm
-- `async_tools.rs`: await, connect_to_server, remove_manual_server, set_setting
+- `async_tools.rs`: await, connect_to_server, remove_manual_server, upgrade_smb_to_direct, set_setting
 - `search.rs`: search index loading, search, ai_search
 
 **Action-tool ack contract.** Every fire-and-forget action tool now waits for a backend ack signal before returning `OK`. Previously the tool returned `OK` the instant the event was dispatched; if the FE was stalled (modal blocking input, error pane up, race during startup), the action was silently dropped and MCP reported success anyway. The ack contract makes `OK` a meaningful promise: the FE has actually processed the dispatched action.

apps/desktop/src-tauri/src/mcp/executor/async_tools.rs

@@ -141,6 +141,69 @@ pub fn execute_remove_manual_server<R: Runtime>(app: &AppHandle<R>, params: &Val
     }
 }
 
+/// Execute `upgrade_smb_to_direct`: upgrade an OS-mounted SMB volume to a direct
+/// smb2 session. Thin wrapper around the existing `upgrade_to_smb_volume` Tauri
+/// command (same code path that powers the "Connect directly" UI button) so
+/// agents get the same behaviour as users: tries stored Keychain credentials,
+/// returns a typed result mirroring `UpgradeResult` (Success / CredentialsNeeded
+/// / NetworkError). On `CredentialsNeeded`, agents are out of luck for now —
+/// credential prompts are interactive; a future tool could accept credentials
+/// inline and call `upgrade_to_smb_volume_with_credentials`.
+///
+/// Only meaningful on macOS / Linux (the underlying command is platform-gated).
+/// On other platforms the Tauri stub returns an error; we surface it as an
+/// MCP internal error.
+pub async fn execute_upgrade_smb_to_direct<R: Runtime>(_app: &AppHandle<R>, params: &Value) -> ToolResult {
+    let volume_id = params
+        .get("volume_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| ToolError::invalid_params("Missing 'volume_id' parameter"))?;
+
+    #[cfg(any(target_os = "macos", target_os = "linux"))]
+    {
+        use crate::network::smb_upgrade::UpgradeResult;
+        // Calls the inner helper rather than the Tauri command itself because
+        // the Tauri command takes concrete `tauri::AppHandle` (= `AppHandle<Wry>`)
+        // while the MCP executor's `app` is generic over `Runtime`. The inner
+        // function carries all the upgrade logic minus the mDNS kick (which
+        // needs a concrete handle). Agents wanting hostname-keyed Keychain
+        // creds need mDNS already running — see the tool description.
+        match crate::commands::network::upgrade_to_smb_volume_inner(volume_id.to_string()).await {
+            Ok(UpgradeResult::Success) => Ok(json!(format!("OK: Upgraded {} to direct smb2", volume_id))),
+            Ok(UpgradeResult::CredentialsNeeded {
+                server,
+                share,
+                display_name,
+                ..
+            }) => {
+                let server_label = if display_name.is_empty() { server } else { display_name };
+                Ok(json!(format!(
+                    "Needs credentials: share={} on {}. Cmdr's Keychain didn't have a working password for this share. \
+                     Agents can't prompt; the user has to enter credentials via the UI's 'Connect directly' button. \
+                     (If mDNS isn't running, hostname-keyed creds also won't be found; trigger any network UI action first.)",
+                    share, server_label
+                )))
+            }
+            Ok(UpgradeResult::NetworkError { message }) => Err(ToolError::internal(format!(
+                "Network error while upgrading {}: {}",
+                volume_id, message
+            ))),
+            Err(e) => Err(ToolError::internal(format!(
+                "upgrade_to_smb_volume_inner({}) failed: {}",
+                volume_id, e
+            ))),
+        }
+    }
+
+    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
+    {
+        let _ = volume_id;
+        Err(ToolError::internal(
+            "upgrade_smb_to_direct is only supported on macOS and Linux".to_string(),
+        ))
+    }
+}
+
 // ── Settings ─────────────────────────────────────────────────────────
 
 /// Execute set_setting command via round-trip to the frontend.

apps/desktop/src-tauri/src/mcp/executor/mod.rs

@@ -162,6 +162,7 @@ pub async fn execute_tool<R: Runtime>(app: &AppHandle<R>, name: &str, params: &V
         // Network commands
         "connect_to_server" => async_tools::execute_connect_to_server(app, params).await,
         "remove_manual_server" => async_tools::execute_remove_manual_server(app, params),
+        "upgrade_smb_to_direct" => async_tools::execute_upgrade_smb_to_direct(app, params).await,
         // Async wait
         "await" => async_tools::execute_await(app, params).await,
         _ => Err(ToolError::invalid_params(format!("Unknown tool: {name}"))),