[Feature]: Add per-project retention limits for settled worktrees

[molu0v0]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server

Problem or use case

Summary

T3 Code keeps worktrees after a thread is marked as Settled. Settling a thread changes its state, but does not remove the associated worktree or enforce a per-project retention limit.

I am not suggesting that every Settle action should immediately delete the worktree. The desired behavior is bounded retention: each project should keep a configurable number of settled worktrees, and older eligible worktrees should be cleaned up after the limit is exceeded.

Environment

• T3 Code: 0.0.34-nightly.20260814.1093
• OS: Ubuntu Linux x86_64
• Worktree mode: enabled
• Worktree directory: ~/.t3/worktrees

Steps to reproduce

1. Enable worktree mode for a project.
2. Create several threads for the same project.
3. Let the threads finish and click Settle.
4. Repeat this for multiple threads.
5. Inspect the project's worktree directory.

Actual behavior

• Settled threads remain in the worktree directory.
• There is no visible per-project retention limit.
• Creating additional worktrees does not appear to remove the oldest settled worktree.
• Completed worktrees can accumulate and consume significant disk space.

Expected behavior

T3 Code should provide a retention policy per project, for example:

• Keep the latest N settled worktrees per project.
• When the limit is exceeded, remove the oldest eligible settled worktrees.
• Do not remove worktrees with an active session, running process, uncommitted changes, untracked files, pending approvals, or user-pinned status.
• Keep active and unsettled worktrees untouched.
• Use git worktree remove and clean up Git metadata safely.
• Show which worktrees were skipped or removed.

A global default plus a per-project override would be useful. For example:

settledWorktreeKeepCount = 3

### Proposed solution


Add a project-scoped retention policy for T3-managed worktrees that have been marked as settled.

- Add a configurable `settledWorktreeKeepCount`, with a global default and an optional per-project override.
- When a thread is settled or a new worktree is created, evaluate the settled worktrees belonging to that project.
- Keep the newest `N` eligible settled worktrees based on `settledAt`.
- Remove only older settled worktrees after the retention limit is exceeded.
- Never remove worktrees with active sessions, running processes, pending approvals, uncommitted changes, untracked files, or an explicit keep/pin flag.
- Use `git worktree remove` and clean up Git metadata safely.
- Do not delete branches by default.
- Report skipped and removed worktrees so the cleanup is transparent.


### Why this matters

Worktrees are useful for reopening, reviewing, or recovering completed threads, so deleting them immediately when a thread is settled would be undesirable.

However, settled worktrees can contain large source trees, dependencies, build artifacts, and development-server output. If they are kept indefinitely, disk usage grows while the worktrees become inactive and less visible in the UI.

A project-scoped retention policy would preserve recent completed work while preventing unbounded disk growth. It would also make the lifecycle behavior predictable: active work remains protected, while older inactive work is cleaned up only when the configured limit is exceeded.


### Smallest useful scope

The smallest useful implementation would be:

1. Add a global default retention count and an optional project-level override.
2. Run cleanup when a thread becomes settled or when a new worktree is created for the project.
3. Consider only T3-managed worktrees belonging to the same project.
4. Keep the newest `N` settled worktrees and remove only safe, older candidates.
5. Skip active, dirty, untracked, pending, or pinned worktrees.
6. Add tests covering active, dirty, pinned, and settled worktrees.

This initial implementation would not require a new background cleanup daemon, UI redesign, branch deletion, or time-only cleanup policy.

### Alternatives considered

_No response_

### Risks or tradeoffs

_No response_

### Examples or references

_No response_

### Contribution

- [ ] I would be open to helping implement this.

[juliusmarminge]

Note

Grok responding on behalf of Julius.

#15208, merged to main today, covers this with a time-based limit instead of a count. Settings → Storage → Delete settled worktrees removes settled worktrees a set number of days after settledAt, with a global default and per-project overrides. It skips worktrees with local changes, a live session or terminal, or other threads sharing them, and the cleanup report shows what was removed or kept and why. Branches and thread history are kept.

A "keep the newest N" count isn't implemented. If days-based retention doesn't work for you, please open a new discussion that explains why. Closing as resolved.