feat(tui): show the volume's free disk space in each pane frame (#171)

* feat(tui): show the volume's free disk space in each pane frame

Add a per-pane free-disk-space indicator in the frame's bottom-left (e.g.
`137.0 GiB free`), refreshed on every navigate. Shows the space available to the
current user (respects root-reserved blocks / quotas). Yields to the filter label
when a filter is active; degrades gracefully (truncates) on a very narrow pane.

- cairn-types: `SpaceInfo { total, available }` and a `Caps::SPACE` flag.
- cairn-vfs: `Vfs::space(path) -> Result<Option<SpaceInfo>>`, default `Ok(None)`.
  Path-scoped (a backend can straddle mounts).
- cairn-backend-local: implement via the cross-platform `fs4` crate (statvfs on
  Unix, GetDiskFreeSpaceEx on Windows) in spawn_blocking — no unsafe/ADR needed.
  Advertises `Caps::SPACE`.
- Other backends inherit the `None` default (object stores/containers have no
  meaningful free space). SSH/SFTP via `statvfs@openssh.com` is a tracked
  follow-up (#170) — russh-sftp only exposes it on the raw session.
- cairn-core: `PaneState.space`, cleared on navigate; `AppEvent::SpaceFetched`
  applied with the same conn/dir staleness guard as `Listed`.
- cairn: the runtime fetches space as a non-blocking sibling of each `List` and
  emits `SpaceFetched` — so the reducer still emits a single effect (no test churn).
- cairn-plugin: `SPACE` is host-only (no WIT counterpart yet), like `LOCAL_PATH`.

Tests: local `space()` (plausible totals, advertises the cap); reducer
(stores on match, ignores stale, cleared on navigate); a pane-free-space scenario
+ snapshots. README + CHANGELOG.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(tui): hide the free-space label when it would clip; gate the fetch on Caps::SPACE

Review fixes:
- Narrow-pane clipping (bug-bot): on a half-width pane the free-space label was
  clipped mid-word to a misleading unitless number (e.g. "137.0"). Only show it
  when it fits alongside the sort label (measured against the pane width);
  otherwise omit it entirely. Wide panes render the full "137.0 GiB free".
- Gate the runtime's space-fetch on `Caps::SPACE` (code-review): skip the task,
  the space() call, and the no-op SpaceFetched event for backends that can't
  report space (object stores, containers) — no pointless work.
- Log a debug line on a space() error instead of silently swallowing it.

Tests: free-space label shows on a wide pane and is omitted (not clipped) on a
narrow one. Snapshots regenerated (40x12 now omits the label).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zoza1982

CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Each pane's frame now shows the volume's free disk space** in the bottom-left corner (e.g.
+  `137.0 GiB free`), refreshed on every navigate. Available to the current user (respects
+  root-reserved blocks and quotas). Supported on the local backend on all platforms (via a
+  cross-platform statvfs); other backends that can't report it (object stores, containers) simply
+  omit it, and it yields to the filter label when a filter is active. (SSH/SFTP free space via
+  `statvfs@openssh.com` is a tracked follow-up.)
+
 - **`Ctrl-S` calculates a folder's size** (recursively) and shows it in a stats popup: total size
   (human-readable + exact bytes) plus file and subfolder counts. The walk runs in the background and
   the popup updates live, so a large or remote directory shows progress instead of blocking; `Esc`

Cargo.lock

@@ -89,7 +89,9 @@ right-aligned MC-style; on a narrow pane the columns drop out responsively — p
 keeping the date as long as it fits — so the name keeps priority, and are blank for backends that
 don't expose that metadata. Dates are shown in UTC (`YYYY-MM-DD`). By default `s` cycles the active pane's sort order (name → size → modified →
 type) and `.` toggles whether hidden entries (dotfiles) are listed; the current sort mode and hidden
-state show in each pane's bottom-right corner. `Ctrl-R` reloads the active pane. `F7` creates a new
+state show in each pane's bottom-right corner, and the volume's **free disk space** (e.g.
+`137.0 GiB free`) shows in the bottom-left for backends that report it (local now; SSH is a
+follow-up). `Ctrl-R` reloads the active pane. `F7` creates a new
 directory and `r` renames the entry under the cursor (`F2` is an alias; both
 open a text prompt; `Enter` confirms, `Esc` cancels). `Ctrl-S` recursively calculates the size of
 the folder under the cursor and shows it in a stats popup (total size, file and subfolder counts);

README.md

@@ -17,8 +17,11 @@ cairn-types = { workspace = true }
 cairn-vfs = { workspace = true }
 async-trait = "0.1"
 bytes = "1"
+# Cross-platform free/total disk space (statvfs on Unix, GetDiskFreeSpaceEx on Windows) behind a
+# safe API — avoids hand-rolled Windows FFI (which would need `unsafe` + an ADR per the repo rules).
+fs4 = { version = "1", features = ["sync"] }
 futures = "0.3"
-tokio = { version = "1", features = ["fs", "io-util"] }
+tokio = { version = "1", features = ["fs", "io-util", "rt"] }
 
 [dev-dependencies]
 tempfile = "3"

crates/cairn-backend-local/Cargo.toml

@@ -7,7 +7,7 @@
 
 use async_trait::async_trait;
 use bytes::Bytes;
-use cairn_types::{Caps, ConnectionId, Entry, EntryKind, Scheme, UnixPerms, VfsPath};
+use cairn_types::{Caps, ConnectionId, Entry, EntryKind, Scheme, SpaceInfo, UnixPerms, VfsPath};
 use cairn_vfs::{
     ByteRange, CapabilityProvider, ListOpts, ListPage, ReadHandle, Recurse, Vfs, VfsError,
     WriteHandle, WriteOpts, WriteSink,
@@ -27,7 +27,8 @@ const fn platform_caps() -> Caps {
         .union(Caps::RENAME_ATOMIC)
         .union(Caps::RANDOM_READ)
         .union(Caps::APPEND)
-        .union(Caps::LOCAL_PATH);
+        .union(Caps::LOCAL_PATH)
+        .union(Caps::SPACE);
     #[cfg(unix)]
     {
         base.union(Caps::CHMOD).union(Caps::SYMLINK)
@@ -251,6 +252,26 @@ impl Vfs for LocalVfs {
     async fn set_perms(&self, path: &VfsPath, perms: UnixPerms) -> Result<(), VfsError> {
         set_perms_impl(&self.resolve(path), path, perms).await
     }
+
+    async fn space(&self, path: &VfsPath) -> Result<Option<SpaceInfo>, VfsError> {
+        // `fs4::{available_space,total_space}` are blocking syscalls (statvfs / GetDiskFreeSpaceEx),
+        // so run them off the async reactor. `resolve` (not the symlink-confined `local_path`) is
+        // fine here — this is read-only telemetry, not a shell-out containment boundary.
+        let full = self.resolve(path);
+        let res = tokio::task::spawn_blocking(move || -> std::io::Result<SpaceInfo> {
+            Ok(SpaceInfo {
+                total: fs4::total_space(&full)?,
+                available: fs4::available_space(&full)?,
+            })
+        })
+        .await;
+        match res {
+            Ok(Ok(info)) => Ok(Some(info)),
+            // A statvfs failure (path vanished, unusual FS) or a join failure degrades to "unknown"
+            // rather than surfacing an error for a decorative indicator.
+            _ => Ok(None),
+        }
+    }
 }
 
 #[cfg(unix)]
@@ -431,6 +452,29 @@ mod tests {
         assert!(matches!(res, Err(VfsError::AlreadyExists(_))));
     }
 
+    #[tokio::test]
+    async fn space_reports_a_plausible_volume() {
+        let (_dir, vfs) = backend();
+        let info = vfs
+            .space(&p("/"))
+            .await
+            .expect("space call succeeds")
+            .expect("local backend reports space");
+        assert!(info.total > 0, "a real volume has non-zero capacity");
+        assert!(
+            info.available <= info.total,
+            "available ({}) must not exceed total ({})",
+            info.available,
+            info.total
+        );
+    }
+
+    #[test]
+    fn local_backend_advertises_the_space_cap() {
+        let (_dir, vfs) = backend();
+        assert!(vfs.caps().contains(Caps::SPACE));
+    }
+
     #[test]
     fn local_path_resolves_an_in_root_file() {
         let (dir, vfs) = backend();

crates/cairn-backend-local/src/lib.rs

@@ -198,6 +198,19 @@ pub enum AppEvent {
         /// The page result.
         result: Result<ListPage, VfsError>,
     },
+    /// Free/total disk space for a pane's directory. The runtime fetches it when it handles the
+    /// pane's [`AppEffect::List`] (a sibling of the listing), and delivers it here. Applied only if
+    /// the pane is still on the same `conn`/`dir`. `space` is `None` when unavailable.
+    SpaceFetched {
+        /// Which pane requested it.
+        pane: Side,
+        /// The connection it was measured on.
+        conn: ConnectionId,
+        /// The directory whose volume was measured.
+        dir: VfsPath,
+        /// The space totals, or `None` if the backend couldn't report them.
+        space: Option<cairn_types::SpaceInfo>,
+    },
     /// Pre-flight sizing progress for an in-flight transfer: the destination conflict-check and the
     /// recursive size scan walking the source tree, before any bytes move. Carries the running count
     /// of visited entries, the bytes discovered so far, and the path currently being visited so the

crates/cairn-core/src/msg.rs

@@ -257,6 +257,10 @@ pub struct PaneState {
     /// *inside* another mounted archive nests correctly. Empty for a pane that has never mounted
     /// an archive.
     pub mount_stack: Vec<MountFrame>,
+    /// Free/total space for the volume backing this pane's directory, shown in the pane frame.
+    /// `None` while loading or when the backend can't report it (object stores, containers, or an
+    /// SFTP server without the extension). Fetched alongside each listing; cleared on navigate.
+    pub space: Option<cairn_types::SpaceInfo>,
     /// When the next listing for this pane arrives, place the cursor on the entry with this name
     /// (instead of the default top row). Set by `leave_dir` to the name of the directory being
     /// exited, so going up (`..`) returns the cursor to the child you came from — MC behaviour —
@@ -290,6 +294,7 @@ impl PaneState {
             filter: None,
             filter_editing: false,
             mount_stack: Vec::new(),
+            space: None,
             select_after_load: None,
         }
     }

crates/cairn-core/src/state.rs

@@ -3740,6 +3740,9 @@ fn navigate(state: &mut AppState, side: Side, dir: cairn_types::VfsPath) -> Vec<
     p.filter_editing = false;
     // Default to the top row; `leave_dir` overrides this after the call to land on the exited child.
     p.select_after_load = None;
+    // Clear the stale free-space figure; the runtime refills it (via a `SpaceFetched` event) when it
+    // handles the `List` effect below — so the reducer still emits a single effect here.
+    p.space = None;
     vec![AppEffect::List {
         pane: side,
         conn: p.conn,
@@ -3753,6 +3756,7 @@ fn reload(state: &mut AppState, side: Side) -> Vec<AppEffect> {
     let dir = p.cwd.clone();
     p.listing = Listing::Loading;
     p.marked.clear();
+    p.space = None;
     vec![AppEffect::List {
         pane: side,
         conn: p.conn,
@@ -3816,6 +3820,20 @@ fn apply_event(state: &mut AppState, event: AppEvent) -> Vec<AppEffect> {
             }
             Vec::new()
         }
+        AppEvent::SpaceFetched {
+            pane,
+            conn,
+            dir,
+            space,
+        } => {
+            // Ignore a stale result for a directory/connection the pane has moved on from (same guard
+            // as `Listed`).
+            let p = state.pane_mut(pane);
+            if p.cwd == dir && p.conn == conn {
+                p.space = space;
+            }
+            Vec::new()
+        }
         AppEvent::AiPlanProposed(Ok(plan)) => {
             state.ai_pending = false;
             if plan.steps.is_empty() {
@@ -7115,6 +7133,61 @@ mod tests {
         assert!(!s.active().marked.contains(&0));
     }
 
+    #[test]
+    fn space_fetched_stores_on_the_matching_pane_and_ignores_stale() {
+        let mut s = state();
+        let conn = s.pane(Side::Left).conn;
+        let dir = s.pane(Side::Left).cwd.clone();
+        let info = cairn_types::SpaceInfo {
+            total: 1000,
+            available: 250,
+        };
+        // A result for the pane's current conn/dir is stored.
+        let _ = update(
+            &mut s,
+            Msg::Event(AppEvent::SpaceFetched {
+                pane: Side::Left,
+                conn,
+                dir: dir.clone(),
+                space: Some(info),
+            }),
+        );
+        assert_eq!(s.pane(Side::Left).space, Some(info));
+
+        // A stale result (different dir) is ignored — the pane keeps its value.
+        let _ = update(
+            &mut s,
+            Msg::Event(AppEvent::SpaceFetched {
+                pane: Side::Left,
+                conn,
+                dir: VfsPath::parse("/elsewhere").unwrap(),
+                space: None,
+            }),
+        );
+        assert_eq!(
+            s.pane(Side::Left).space,
+            Some(info),
+            "a stale space result must not clobber the current one"
+        );
+    }
+
+    #[test]
+    fn navigate_clears_the_stale_free_space() {
+        let mut s = state();
+        s.pane_mut(Side::Left).space = Some(cairn_types::SpaceInfo {
+            total: 1000,
+            available: 250,
+        });
+        deliver(&mut s, Side::Left, vec![Entry::new("d", EntryKind::Dir)]);
+        s.pane_mut(Side::Left).cursor = 0;
+        let _ = update(&mut s, Msg::Action(Action::Enter));
+        assert_eq!(
+            s.pane(Side::Left).space,
+            None,
+            "navigating clears the previous volume's free-space figure"
+        );
+    }
+
     #[test]
     fn stale_listing_is_ignored() {
         let mut s = state();

crates/cairn-core/src/update.rs

@@ -749,10 +749,11 @@ mod tests {
 
     #[test]
     fn map_caps_covers_every_wit_flag() {
-        // Every WIT `caps` flag must be translated; the host-only `LOCAL_PATH` has no WIT counterpart.
-        // This breaks if either side grows a flag without updating `map_caps`.
+        // Every WIT `caps` flag must be translated. Host-only caps have no WIT counterpart: a plugin
+        // backend can't currently advertise `LOCAL_PATH` (real OS path) or `SPACE` (statvfs) — both
+        // are host-implemented. This breaks if either side grows a flag without updating `map_caps`.
         let mapped = map_caps(Caps0::all());
-        assert_eq!(mapped, Caps::all() & !Caps::LOCAL_PATH);
+        assert_eq!(mapped, Caps::all() & !Caps::LOCAL_PATH & !Caps::SPACE);
     }
 
     #[test]

crates/cairn-plugin/src/component.rs

@@ -1605,16 +1605,33 @@ fn render_pane(frame: &mut Frame, area: Rect, state: &AppState, side: Side, them
     // Bottom-right status: current sort mode, plus a `+hidden` flag when dotfiles are shown.
     let hidden = if pane.show_hidden { " +hidden" } else { "" };
     let status = format!(" sort: {}{hidden} ", pane.sort.label());
-    // No `overlay_base` here: a pane isn't an overlay — it already sits on the theme background painted
-    // over the whole frame at the top of `render()`, so it needs no fill of its own.
+    let status_w = status.chars().count(); // captured before `status` is moved into the title below
+                                           // No `overlay_base` here: a pane isn't an overlay — it already sits on the theme background painted
+                                           // over the whole frame at the top of `render()`, so it needs no fill of its own.
     let mut block = Block::bordered()
         .title(title)
         .title_bottom(Line::from(status).right_aligned())
         .border_style(Style::default().fg(border));
-    // Bottom-left: the active filter (a trailing `_` marks live editing).
+    // Bottom-left: the active filter (a trailing `_` marks live editing), or — when not filtering —
+    // the free disk space of the volume backing this pane (backends that report it: local, and SSH
+    // once wired). The filter takes precedence since it's transient and interactive.
     if let Some(f) = &pane.filter {
         let cursor = if pane.filter_editing { "_" } else { "" };
         block = block.title_bottom(Line::from(format!(" filter: {f}{cursor} ")).left_aligned());
+    } else if let Some(space) = pane.space {
+        let text = format!(" {} free ", human_bytes(space.available));
+        // Only show it if it fits alongside the right-aligned sort label without the two colliding
+        // (ratatui would otherwise clip the left title mid-word, e.g. a misleading unitless `137.0`).
+        // Interior width is the pane minus its two border columns; leave a 1-col gap between them.
+        let interior = usize::from(area.width).saturating_sub(2);
+        // `<` (not `<=`) leaves at least a one-column gap between the two titles.
+        if text.chars().count() + status_w < interior {
+            block = block.title_bottom(
+                Line::from(text)
+                    .left_aligned()
+                    .style(Style::default().fg(theme.status)),
+            );
+        }
     }
 
     match &pane.listing {