fix(realfs): avoid blocking async runtimes

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- RealFs path resolution and metadata updates no longer perform synchronous
+  host filesystem I/O inside async backend methods, preventing stalls and
+  deadlocks on current-thread Tokio runtimes. Async embedders should use the
+  new `RealFs::open`; the blocking `RealFs::new` constructor is deprecated.
+
 ## [0.14.3] - 2026-07-18
 
 ### Highlights

crates/bashkit-js/src/lib.rs

@@ -403,6 +403,7 @@ fn import_external_file_system(external: Unknown<'_>) -> napi::Result<Arc<dyn Ba
 }
 
 impl NativeFileSystemState {
+    #[allow(deprecated)] // FileSystem.real is an intentionally synchronous JS factory.
     fn real(
         host_path: String,
         writable: Option<bool>,
@@ -2057,7 +2058,8 @@ impl Bash {
             } else {
                 RealFsMode::ReadOnly
             };
-            let real_backend = RealFs::new(&host_path, mode)
+            let real_backend = RealFs::open(&host_path, mode)
+                .await
                 .map_err(|e| napi::Error::from_reason(e.to_string()))?;
             let fs: Arc<dyn BashFileSystem> = Arc::new(PosixFs::new(real_backend));
             bash.mount(Path::new(&vfs_path), fs)
@@ -2682,7 +2684,8 @@ impl BashTool {
             } else {
                 RealFsMode::ReadOnly
             };
-            let real_backend = RealFs::new(&host_path, mode)
+            let real_backend = RealFs::open(&host_path, mode)
+                .await
                 .map_err(|e| napi::Error::from_reason(e.to_string()))?;
             let fs: Arc<dyn BashFileSystem> = Arc::new(PosixFs::new(real_backend));
             bash.mount(Path::new(&vfs_path), fs)

crates/bashkit-python/src/lib.rs

@@ -1753,6 +1753,7 @@ impl PyFileSystem {
     #[cfg(not(target_arch = "wasm32"))]
     #[staticmethod]
     #[pyo3(signature = (host_path, writable=false))]
+    #[allow(deprecated)] // Python constructors cannot await RealFs::open.
     fn real(host_path: String, writable: bool) -> PyResult<Self> {
         let rt = make_runtime()?;
         let mode = if writable {

crates/bashkit/src/fs/mod.rs

@@ -219,7 +219,7 @@
 //! use bashkit::fs::{RealFs, RealFsMode};
 //! use std::sync::Arc;
 //!
-//! let backend = RealFs::new("/path/to/dir", RealFsMode::ReadOnly).unwrap();
+//! let backend = RealFs::open("/path/to/dir", RealFsMode::ReadOnly).await.unwrap();
 //! let fs = Arc::new(PosixFs::new(backend));
 //! let mut bash = Bash::builder().fs(fs).build();
 //! ```