diff --git a/hive-agent/src/disk_watch.rs b/hive-agent/src/disk_watch.rs
index bc991d2b..a38f1b63 100644
--- a/hive-agent/src/disk_watch.rs
+++ b/hive-agent/src/disk_watch.rs
@@ -16,6 +16,14 @@
 //! into a new bucket (or a change in which directories are big enough to
 //! list) speaks up again. Dropping back under the threshold clears the
 //! todo.
+//!
+//! Scoped by design: the `statvfs` reads the *whole filesystem*, which on
+//! a shared host volume (several agents' state dirs on the same
+//! subvolume) can sit over threshold because of bytes some other agent
+//! owns. The todo only fires when this agent's own tree ([`big_dirs`])
+//! actually contains something big enough to name — an agent whose own
+//! footprint is negligible has nothing it can safely free, so it stays
+//! silent instead of nagging everyone on a crowded volume.
 
 use std::ffi::CString;
 use std::fmt::Write as _;