File states

uploading and sync-error take precedence over every other value, including modified for a file that is still open.

Separately from the state, the answer says whether the entry is the root of a Team or Group folder.

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.

On Linux file managers 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:

A Team or Group folder root additionally carries a blue emblem with two people, next to its state emblem.

macOS mounts through Apple’s File Provider, and there the system draws the emblems, not Wusel. The always-visible scheme above does not apply: the Finder distinguishes only four cases, and one of them is no icon at all.

The last row is the one that surprises people, so it is worth stating plainly: a file with no icon is not broken and is not “missing its cloud symbol” — it means the file’s contents are already on this Mac. That happens as soon as you create the file here, open it, or the Finder reaches into it to build a thumbnail or let Spotlight index it. Apple shows the cloud only while a file is still dataless (no local bytes); once the bytes are here the icon disappears. Every File Provider works this way — iCloud Drive, OneDrive, Dropbox — and an app may not paint its own persistent overlay on a downloaded item, so Wusel cannot make macOS match the Linux scheme above. There is no Team or Group folder badge on macOS.

To send a file back to online-only — free the space and bring the cloud icon back — right-click it and choose Remove Download. macOS also evicts on its own when the disk runs low. The engine’s own view is always exact regardless of what the Finder draws: wusel ipc stat "/OpenProject/…/file.pdf" reports the values listed above (see Diagnose a problem).