Expose per-mount cache policy and metadata timeouts in the SDK and CLI

[zfy0701]

Host-side edits to bind-mounted files can take several seconds to become fully visible inside a running sandbox. Could the SDK and CLI expose the existing filesystem cache controls per mount, so callers can choose freshness versus performance?

Existing support

microsandbox-filesystem already supports cache_policy, entry_timeout, and attr_timeout. However, the runtime uses their defaults when constructing directory mounts, and the Node SDK MountBuilder does not expose them.

Checked at commit fa3e43902e9bc49e1d85cc0a7298e13fe2374026 (v0.6.18):

• Filesystem cache configuration
• Runtime mount construction using defaults
• Node SDK MountBuilder

Observed behavior

Tested microsandbox 0.6.17 on Linux, with Node v24.21.0 in the guest and an ordinary read-only directory bind mount. The reads below used the bind mount directly, without going through a guest-created OverlayFS mount.

1. On the host, create sample.txt containing host-old (8 bytes, no newline), and bind its directory at /shared.
2. In the guest, read /shared/sample.txt using fs.readFileSync(path, 'utf8').
3. On the host, overwrite the same inode with host-longer-value (17 bytes).
4. In the guest, repeat readFileSync every 200 ms, reopening the file on each read.

The guest initially returned host-lon, then returned the complete host-longer-value after approximately 5.1 seconds. This appears consistent with the default 5-second attribute timeout retaining the old file size. This is an observation from one run, not a guaranteed refresh interval.

Requested behavior

Expose the existing controls through per-mount SDK and CLI configuration:

Control	Current default	Desired opt-in setting for frequently changing host files
entry_timeout	5 seconds	0
attr_timeout	5 seconds	0
cache_policy	Auto	Never

Preserve existing defaults, carry the selected options through saved sandbox configuration and stop/start, and document the extra host I/O cost of disabling caches. Per-mount settings would let shared source directories prioritize freshness while stable dependency caches retain caching.

The requested values have not yet been tested in a patched runtime. Coherence of host changes beneath a mounted guest OverlayFS is a separate concern; exposing these controls should not imply that such a layout becomes supported.

[SyedShaQutub]

Adding a data point that makes this more than a freshness trade-off: with the default ~5 s entry/attr timeouts, replacing a file by rename can make it disappear from the guest for several seconds.

Setup: microsandbox 0.7.3 (Python SDK), Linux host, guest kernel 6.12.109, python:3.12-slim. A read-write Volume.bind of a host directory with stat virtualization off. The host directory is a FUSE filesystem (JuiceFS 1.2.3, 1 s attr/entry TTL on the host client). 15 trials per cell; the guest clock is calibrated to ±0.2 ms.

Time until the guest sees a host-side change (p50 / max, ms):

Host-side change	host writes on the same FUSE client the guest's mount uses
new file (listdir)	≤ 0
in-place overwrite, re-open	≤ 0
temp file + rename() over the original	4,276 / 4,880
size change seen by stat	4,512 / 4,911
rename	4,254 / 4,907
delete	4,076 / 4,521

The ~5 s edge matches the passthrough default entry_timeout / attr_timeout. The measured bounds are consistent with the cache being armed at the guest's first lookup.

What the guest reads after a temp + rename over f.txt (one traced trial, reading every 250 ms):

• 0–0.8 s: the old bytes (old inode);
• 1.0–4.8 s: ENOENT ("No such file or directory");
• from 5.05 s: the new bytes (new inode).

Our reading: once the host FS drops the old inode (here after its 1 s TTL), the guest's cached dentry still names it, and the passthrough answers ENOENT rather than ESTALE, so the guest kernel doesn't re-look-up the name. An application in the guest that re-opens the file in that window is told it doesn't exist, which is worse than seeing stale bytes. Atomic save-by-rename is the common way editors and tools write files. In-place writes and new files are visible within milliseconds.

echo 2 > /proc/sys/vm/drop_caches in the guest makes the new file visible at once (0.87 ms), but it's guest-wide.

So +1 to exposing cache_policy / entry_timeout / attr_timeout per mount. It would also help if a lookup that hits a dead inode returned ESTALE (or re-validated the entry), so a rename-over never surfaces as ENOENT.