Show worktree storage by cleanup category and explain what is retained

[tris203]

Problem

Settings → Storage lets me configure automatic cleanup, but it does not show how the worktree storage on the selected machine or project is distributed across cleanup categories. I cannot readily tell how much is eligible under my rules, how much is retained, or why apparently completed worktrees are still taking up space.

While working with the category visualization in #12604, I found it useful for spotting mismatches between what I expected a rule to clean up and what was actually retained. That led to investigating the limitations now tracked in #13836 (ignored files from worktree setup), #14742 (squash merges), and #14758 (PRs merged into release branches or stack parents). Those reports have their own evidence and policy questions; the visualization helped identify where to investigate. The screenshots below do not independently prove those defects.

This is an enhancement and direction request for maintainer triage, not a claim that the earlier implementation was approved.

What I want to understand

For a selected project or environment, I want a category view that answers:

• How much disk space do my worktrees occupy, and how much is currently eligible for cleanup?
• How is that space divided among the cleanup categories, such as inactive threads, merged work, unchanged work, and worktrees left by deleted threads?
• How much is being retained, and for what reasons—for example activity, local changes, protected ignored files, or a merge that does not meet the rule's evidence requirements?
• How would changing a rule or inactivity threshold change the potentially reclaimable amount, without applying that change just to discover its effect?

The distinction between matching a category and actually being eligible matters. A merged PR can still have a protected checkout. A useful view should make that understandable, avoid double-counting overlapping categories, and identify unavailable or incomplete measurements rather than presenting them as zero.

Last-run cleanup logs could help diagnose an individual sweep, but they would not answer these questions about the current storage distribution and the effect of different rules.

Illustrative earlier UI

These screenshots come from the closed, unmerged #12604 prototype. They illustrate why the category visualization was useful; they are not shipped UI, an approved design, or evidence of the exact rule semantics currently supported. The original PR combined presentation with cleanup-policy changes, so its labels and totals should not be taken as a specification for current eligibility.

For example, the earlier all-project view showed 90.3 GB in total and 63.7 GB in “Other.” Seeing that large retained remainder made it clear where I needed to investigate; explaining the remainder is part of the value, not just displaying a total. These are historical prototype values.

Across projects:

One project:

Requested scope and decision

Please triage whether this visibility into worktree storage and cleanup categories is a direction maintainers want, and what the smallest useful version should explain. The intended starting surface is the existing web/desktop Storage settings, following the selected project and environment; remote storage belongs to its owning environment.

This request does not require adopting the earlier scanner, the whole staged Save/Discard workflow, or weakening any cleanup protections. Those implementation and interaction choices can be agreed separately. Understanding the effect of a proposed rule change should itself be read-only. The existing saved policies may continue to run normally.

Related work

• feat(web): preview worktree storage before saving cleanup rules #12604 contains the original visualization and broader implementation; feat(web): preview worktree storage before saving cleanup rules #14653 split out storage preview and staged saving. The latter closure requested explicit approval of that direction. This issue does not assume that approval exists.
• Discussion #6864 previously requested storage visibility and preview alongside automatic cleanup. It was marked resolved by #11598, whose shipped scope explicitly removed disk usage reporting. This request isolates that remaining visibility need.
• [Bug]: Automatic worktree cleanup never removes worktrees set up by t3.json's Setup Worktree action #13836, [Bug]: Merged-worktree cleanup retains worktrees after squash merges #14742 and Support merged-worktree cleanup for PRs targeting release branches or stack parents #14758 track the individual rule limitations; they can be assessed independently of this UI.
• [Bug]: Enabling retention activates eight days before a different initial age can be chosen #14743 concerns the separate retention-activation sequence. Fixing it does not require category reporting.

[juliusmarminge]

Note

Grok responding on behalf of Julius.

Triage

Thanks for the careful write-up, @tris203. This one's a feature-direction request rather than a bug, and the direction hasn't been approved yet.

Where things stand today

Settings → Storage only edits cleanup rules, and it saves them immediately. It doesn't show how much worktree space a project or environment uses, how that splits across cleanup categories, what's eligible versus retained, or how a different rule or threshold would change the reclaimable amount. Merged PR #11598 shipped the automatic cleanup controls and explicitly removed disk-usage reporting. Discussion #6864 also asked for usage numbers and removal reasons, and marking it resolved by #11598 didn't ship that visibility.

The current rules already keep worktrees for reasons the panel never surfaces. Cleanup can remove a worktree for inactivity, for merged work whose commits are already in the remote default branch, for an unchanged checkout, or because its thread was deleted. Other conditions block removal: local changes, active sessions or terminals, shared or project-root checkouts, and ignored files other than node_modules. That's how a merged PR can still be kept. A cleanup log would only describe a sweep that already ran, not the current state or the effect of a different rule.

Prior attempts

PR #12604 was closed under the one-problem rule because it bundled this preview with an unrelated auto-settle change. PR #14653 was closed under prior approval. You're right not to treat either closure as approval. #13836, #14742, #14758, and #14743 are separate.

The smallest version to decide on

Here's what a read-only category view on the existing web and desktop Storage settings could include:

• Totals for the selected project or environment, with currently eligible space shown separately from retained space.
• The retention reason for anything kept.
• Each worktree counted in only one category.
• Missing or incomplete measurements shown as unavailable, not as zero.
• No saving or deleting from previewing a different rule or threshold.
• Remote usage reported by the environment that owns those worktrees.

Mobile has no equivalent Storage panel.

Next step

Feature direction is approved in an Ideas discussion, so please open one and link this issue. Approving the visibility question wouldn't approve the #14653 Save/Discard workflow or any particular scanner. I'll leave this issue open as the record of the gap, but it isn't a go-ahead for implementation.