Detect low disk headroom and fail writes with a clear message

[wiverson]

Problem

The vault grows with the user's Obsidian vault and the Railway volume is the hard ceiling. Today the server gives no warning as it fills and no clear error when it runs out — writes would surface a raw ENOSPC from fs.writeFileSync through the generic tool-error path.

How Railway actually behaves

(Corrected — an earlier version of this issue mis-stated the 100% behaviour.)

A volume that simply fills up is not self-healing. Railway does not auto-grow volumes (there is no auto-scaling) and does not restart the service to reclaim space. Writes fail with ENOSPC and the application behaves however it handles that — support threads show services wedging in exactly this state until the operator intervenes.

The restart happens when you grow a volume that is already full. Resizing is normally live with no downtime; when the volume is at 100%, Railway performs the resize offline instead so it can run data-integrity checks, and that restarts the service. The growth is the operation — the restart is its cost, not a mechanism for freeing space.

Practical consequence: grow before hitting 100% and it's free; grow after and it costs a restart. That is a stronger argument for early warning, not a weaker one.

Also reported in the wild: after a resize the filesystem may not immediately reflect the new size (block storage expanded, ext4/xfs still showing the old size), and services can start before the volume finishes mounting. So recovery from a full volume is not always clean even after growing it.

Plan ceilings: Free/Trial 0.5 GB, Hobby 5 GB, Pro 50 GB, Enterprise up to 1 TB. This vault is ~252 MB plus ~29 MB SQLite, so Hobby is the realistic floor once attachments grow.

Monitoring available from the platform

• Disk usage metrics: all plans — "Disk Usage — storage utilization" in the service Metrics tab.
• Threshold alerts (Monitors): Pro plan only — configurable on CPU, RAM, disk usage, network egress; notifies by email, in-app, or webhook.
• A GraphQL metrics API can be polled for volume usage without Pro.

So on Pro this issue shrinks to "configure a monitor at ~80%". Below Pro, the server needs to watch its own disk.

Proposed fix

• Check free space on the data volume at boot and periodically; expose it via get_vault_info and on the dashboard.
• Warn on the dashboard below a threshold (e.g. <15% or <500 MB free) — early enough that growing the volume is still a live, no-restart operation.
• Catch ENOSPC on write paths and return an explicit "the server's data volume is full — grow the Railway volume" message instead of a generic failure.
• Consider pausing the sync daemon when critically low, so the server stops pulling attachments onto a full disk.
• Document the plan ceilings and the grow-before-100% caveat in the README.

Refs: https://docs.railway.com/volumes/reference · https://docs.railway.com/guides/monitoring

---

Related: #7 (delivering these warnings to the operator — MCP alerts, vault note, webhook)

[wiverson]

Partial: the Status tab now shows disk usage — a bar, used of total (percent) · free, plus what the vault itself accounts for (notes, attachments, index).

Easier than expected. fs.statfs gives total/available with no df, and the breakdown needs no directory walk because the index already records every note and attachment size, so SUM(size) answers it.

Two things worth carrying into the rest of this issue:

• It reports bavail, not bfree — the space an unprivileged process can actually use. Filesystems reserve a slice for root, and counting it would promise headroom the server cannot spend. Any threshold check should use the same number.
• It detects when the data directory is on the root filesystem rather than its own volume, by comparing statfs of both, and says so. Otherwise a local instance reads as having 900GB of vault room.

Still open: the server acting on this rather than only displaying it — a clear ENOSPC message on write, and warning before the volume fills.