[DOCS] Worktree cleanup docs omit squash-merged PR cleanup behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/common-workflows

Section/Topic

"Subagent worktrees" / "Worktree cleanup" and the cleanupPeriodDays cleanup behavior it references

Current Documentation

The worktree cleanup docs currently say:

Subagent worktrees orphaned by a crash or an interrupted parallel run are removed automatically at startup once they are older than your cleanupPeriodDays setting, provided they have no uncommitted changes, no untracked files, and no unpushed commits. Worktrees you create with --worktree are never removed by this sweep.

The settings reference currently says:

cleanupPeriodDays | Session files older than this period are deleted at startup (default: 30 days, minimum 1). Setting to 0 is rejected with a validation error. Also controls the age cutoff for automatic removal of orphaned subagent worktrees at startup.

What's Wrong or Missing?

Changelog v2.1.105 says: "Improved stale agent worktree cleanup to remove worktrees whose PR was squash-merged instead of keeping them indefinitely."

The current docs still describe stale worktree cleanup as blocked whenever a worktree has unpushed commits. That is now outdated for at least one important case: agent worktrees whose pull request was squash-merged. Users reading the current docs would reasonably expect those worktrees to be kept indefinitely, but the changelog says they are now cleaned up automatically.

The docs should explain this exception clearly, including which kinds of agent/worktree sessions it applies to and how it relates to the existing "no unpushed commits" rule.

Suggested Improvement

Update the "Worktree cleanup" section in common-workflows to document that stale agent/subagent worktrees can also be removed after their PR has been squash-merged, even though the branch may still appear to have unpushed commits in the usual Git sense.

At minimum, clarify:

• which worktree types this applies to
• that this is an additional cleanup case beyond the currently documented "no unpushed commits" rule
• that user-created --worktree worktrees are still excluded if that remains true

Add a short note or cross-reference in the cleanupPeriodDays setting so users can discover this behavior from the settings page too.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/common-workflows | Primary cleanup rules for orphaned subagent worktrees; currently documents only the no-uncommitted/no-untracked/no-unpushed criteria |
| https://code.claude.com/docs/en/settings | cleanupPeriodDays points readers to stale worktree cleanup behavior |
| https://code.claude.com/docs/en/desktop | Documents that Desktop auto-merge uses squash, which makes the squash-merged cleanup case easier to hit in practice |

Total scope: 3 pages affected

Source: Changelog v2.1.105

Changelog entry: Improved stale agent worktree cleanup to remove worktrees whose PR was squash-merged instead of keeping them indefinitely