Disk space management

Status: Accepted · Audience: Operator · Area: D — Content & household

---

Purpose

Stop the disk filling, and make it obvious what’s consuming it.

A media stack’s natural trajectory is to fill any disk given to it. Nothing in the default configuration pushes back: the *arrs acquire what they’re told to, downloads accumulate, torrents seed indefinitely, and unpacked archives leave copies behind.

A full disk is the worst common failure because it breaks everything at once — downloads stall, imports fail, service databases can’t write, and some corrupt. Recovery is manual and the cause is often unclear.

Behaviour

Projection, not just measurement

Free space is a lagging indicator. What matters is free space against what’s already committed — the queue, active downloads, and seeding obligations.

Warning arrives when exhaustion is predicted, not when it happens.

Consumption is attributed

“You have 40 GB free” prompts the question the operator can’t easily answer: what’s using the rest? So it’s broken down by category, and by the things that are actually reclaimable:

The three marked as easy wins are typically where a surprisingly large amount of space has quietly gone.

Cleanup is suggested, never automatic

lemonfiber identifies reclaimable space and offers to reclaim it. It does not delete anything on its own. Automatic deletion of media is unacceptable — the operator may have obtained something irreplaceable, and no heuristic is worth that risk.

Seeding torrents get special care: removing them affects ratio and standing on private trackers, which can carry real consequences. Never removed without the tracker implication stated.

Hardlink awareness prevents wrong answers

With hardlinks working, a file appearing in both downloads/ and media/ occupies space once. Naive summation double-counts it and produces both wrong totals and misleading cleanup suggestions.

Space accounting must be inode-aware, or every figure it reports is wrong on a correctly configured system.

Thresholds escalate

Halting at exhaustion is a safety measure: a database that cannot write may corrupt, turning a space problem into a data-loss problem.

On the companion

The attribution table is the answer, and N12-R6 requires what is consuming space shown by those categories rather than as a file listing (N12). A listing is what an operator has instead of an answer, and a phone is the worst place to be handed one.

Cleanup is suggested, never automatic needs saying twice here, because a surface can undo it by arrangement alone. N12-R4 forbids the app pre-selecting candidates or proposing a set to remove, and N12-R9 forbids it removing anything on its own initiative, including on a threshold. A checkbox that arrives already ticked is a proposal, and Critical delivered as a notification with a button beside it is the threshold doing the deciding.

The reclaimable column is a standing rather than a flag. N12-R1 requires never imported, seeding and left alone kept apart instead of flattened; N12-R2 requires a seeding candidate’s ratio shown with it; and N12-R3 requires what removing it would cost shown with the candidate, not only in a confirmation. The tracker implication this feature insists on has to be readable at the moment of choosing, not at the moment of agreeing. Stopping seeding and removing are different acts with different costs, and N12-R7 requires them shown as different.

Removal is agreed to explicitly and is not reachable as one undifferentiated action (N12-R5). A rehearsed removal is labelled as a rehearsal and never reported as space freed (N12-R8). And space that could not be read is told apart from space that is comfortable (N12-R10) — on a dashboard, silence and good news look the same.

States

Edge cases

Acceptance criteria

Related

• C5 Storage management — the underlying filesystem contract
• C7 Queue health — orphan detection
• D2 Quality presets — the largest lever on consumption
• B5 Notifications