File states

A pin is a promise, and these three values report how it stands: kept, not yet delivered, no longer current. The distinction is not academic — a directory pin covers files the server grows afterwards, and an account-wide one covers everything that will ever exist in it, so a pin routinely runs ahead of the bytes. Drawing those as pinned tells someone about to board a train that a file is on their disk when it is not.

Staleness is shown for pinned files only. For an ordinary cached file it just means the next read goes live, which is what a VFS does all day; a pin promises the file is there when the server is not, so an outdated copy is a promise half-kept and worth showing before someone opens it.

Beside it sits an explicit Update now action — in the context menu when a pinned-stale or pinned-pending file is selected, and as wusel update <path> on the command line. One action for both, because it is one repair: fetch what the pin promised and the disk does not have, whether the copy here is outdated or absent. It fetches in place: deliberately not "unpin, then pin again", which would drop the eviction marker first, so a re-download that failed would leave the file outdated and unprotected.

Whether the user has to ask at all is [sync] refresh_pinned — manual (emblem only), ask (one notification when the backlog grows, naming the first file and counting the rest) or auto (fetch by itself, but only over an unmetered connection). See the policy for what happens when the connection’s cost cannot be established.

The engine guarantees this read is local and network-free, so a file manager may query it for every visible file. Directories report a value only when pinned.

Every state gets a distinct, always-visible emblem — the OneDrive model, rather than marking only the exceptions. Current Adwaita has pruned its stock emblem set, so the Nautilus extension ships its own icons, installed into the hicolor theme: