fix: wrap read_all_index in spawn_blocking to avoid nested tokio runtime

Author: githubrobbi

LOG/2026_01_28_10_00_CHANGELOG_HEALING.md

@@ -173,3 +173,71 @@ The correct solution is to use `spawn_blocking` with **synchronous** function ve
 - **Total Time**: 485s
 - **Commit**: `cdafbae2e` pushed to `main`
 
+---
+
+## Third Fix: Polars Nested Runtime Issue (v0.2.137)
+
+### Problem
+v0.2.136 still failed with the same "Cannot start a runtime from within a runtime" panic.
+The error occurred during `compute_tree_metrics_impl()` execution, but the root cause was
+polars' internal tokio usage.
+
+### Root Cause Analysis
+1. Polars uses tokio internally through `polars-stream` for its streaming engine
+2. When polars operations are called from within a tokio async context, polars may try
+   to create its own runtime or call `block_on`
+3. The `load_or_build_dataframe_cached` function was running directly on the tokio worker
+   thread, and when it called `index.to_dataframe()` (which uses polars), the nested
+   runtime issue occurred
+
+### Evidence
+```bash
+$ cargo tree -p polars-stream 2>/dev/null | grep -i tokio
+│   │   │   │   │   ├── tokio v1.49.0
+│   │   │   │   │   ├── tokio-util v0.7.18
+│   │   │   │   ├── tokio v1.49.0 (*)
+...
+```
+
+### Fix Applied
+**File:** `crates/uffs-mft/src/cache.rs`
+
+Wrapped the entire `load_or_build_dataframe_cached` function body in `spawn_blocking`:
+
+```rust
+#[cfg(windows)]
+pub async fn load_or_build_dataframe_cached(
+    drive: char,
+    ttl_seconds: u64,
+) -> crate::Result<uffs_polars::DataFrame> {
+    // Use spawn_blocking to run all MFT reading and polars operations on a
+    // dedicated blocking thread. This avoids nested tokio runtime issues since
+    // polars uses tokio internally for some operations.
+    tokio::task::spawn_blocking(move || load_or_build_dataframe_cached_sync(drive, ttl_seconds))
+        .await
+        .map_err(|e| crate::MftError::InvalidInput(format!("Task join error: {e}")))?
+}
+
+/// Synchronous version of `load_or_build_dataframe_cached`.
+#[cfg(windows)]
+fn load_or_build_dataframe_cached_sync(
+    drive: char,
+    ttl_seconds: u64,
+) -> crate::Result<uffs_polars::DataFrame> {
+    // ... all MFT reading and polars operations run here on blocking thread
+}
+```
+
+### Why This Works
+- `spawn_blocking` moves the entire operation to a dedicated blocking thread pool
+- The blocking thread is NOT part of the tokio async worker pool
+- When polars tries to create a runtime or call `block_on`, it succeeds because
+  there's no existing runtime context on the blocking thread
+- All MFT reading and polars operations (including `to_dataframe()`) run in isolation
+
+### CI Result
+- **Status**: ✅ PASSED
+- **Version**: 0.2.137
+- **Total Time**: 495s
+- **Commit**: `721add5ef` pushed to `main`
+

crates/uffs-mft/src/reader.rs

@@ -915,13 +915,40 @@ impl MftReader {
     /// Use this when you need fast indexing and searching. Convert to DataFrame
     /// later with `MftIndex::to_dataframe()` if you need Polars analytics.
     ///
+    /// # Note
+    ///
+    /// This function uses `spawn_blocking` internally to run MFT reading on a
+    /// dedicated blocking thread. This avoids potential nested tokio runtime
+    /// issues that can occur when dependencies (like polars) try to create
+    /// their own runtime.
+    ///
     /// # Errors
     ///
     /// Returns an error if MFT reading fails.
     #[cfg(windows)]
-    #[allow(clippy::unused_async)]
     pub async fn read_all_index(&self) -> Result<crate::index::MftIndex> {
-        self.read_mft_index_internal(None::<fn(MftProgress)>)
+        // Capture configuration to recreate reader in blocking thread
+        let volume = self.volume;
+        let mode = self.mode;
+        let merge_extensions = self.merge_extensions;
+        let use_bitmap = self.use_bitmap;
+        let expand_hardlinks = self.expand_hardlinks;
+
+        tokio::task::spawn_blocking(move || {
+            // Create a new reader in the blocking thread
+            let handle = crate::platform::VolumeHandle::open(volume)?;
+            let reader = MftReader {
+                volume,
+                handle,
+                mode,
+                merge_extensions,
+                use_bitmap,
+                expand_hardlinks,
+            };
+            reader.read_mft_index_internal(None::<fn(MftProgress)>)
+        })
+        .await
+        .map_err(|e| MftError::InvalidInput(format!("Task join error: {e}")))?
     }
 
     /// Read MFT into lean index (non-Windows stub).
@@ -994,16 +1021,42 @@ impl MftReader {
     ///
     /// * `callback` - Function called periodically with progress updates
     ///
+    /// # Note
+    ///
+    /// This function uses `spawn_blocking` internally to run MFT reading on a
+    /// dedicated blocking thread. This avoids potential nested tokio runtime
+    /// issues.
+    ///
     /// # Errors
     ///
     /// Returns an error if MFT reading fails.
     #[cfg(windows)]
-    #[allow(clippy::unused_async)]
     pub async fn read_index_with_progress<F>(&self, callback: F) -> Result<crate::index::MftIndex>
     where
         F: Fn(MftProgress) + Send + 'static,
     {
-        self.read_mft_index_internal(Some(callback))
+        // Capture configuration to recreate reader in blocking thread
+        let volume = self.volume;
+        let mode = self.mode;
+        let merge_extensions = self.merge_extensions;
+        let use_bitmap = self.use_bitmap;
+        let expand_hardlinks = self.expand_hardlinks;
+
+        tokio::task::spawn_blocking(move || {
+            // Create a new reader in the blocking thread
+            let handle = crate::platform::VolumeHandle::open(volume)?;
+            let reader = MftReader {
+                volume,
+                handle,
+                mode,
+                merge_extensions,
+                use_bitmap,
+                expand_hardlinks,
+            };
+            reader.read_mft_index_internal(Some(callback))
+        })
+        .await
+        .map_err(|e| MftError::InvalidInput(format!("Task join error: {e}")))?
     }
 
     /// Read MFT into lean index with progress (non-Windows stub).