Clean up stale file-history session directories

[doudouOUC]

Background

PR #4064 introduced ~/.qwen/file-history/{sessionId}/ to back up file contents for /rewind. Each session creates its own directory; when the session ends (process exit, /clear, etc.) the directory is left on disk.

This works fine for the lifetime of one session — eviction (>100 snapshots) and /rewind truncation already remove orphaned backups within a live session. But across sessions, directories accumulate indefinitely. Local check after a few days of use:

$ ls ~/.qwen/file-history/ | wc -l
34

What upstream claude-code does

Treats it as part of a generic "background housekeeping" subsystem, not a per-session concern:

• utils/cleanup.ts:305 cleanupOldFileHistoryBackups — sweeps ~/.claude/file-history/ and removes session dirs whose mtime is older than cleanupPeriodDays (default 30, user-configurable via settings.cleanupPeriodDays)
• utils/backgroundHousekeeping.ts — schedules cleanup 10 minutes after startup (only when the user is idle), then on a 24h recurring interval. Uses a marker file + lockfile to throttle to once-per-day and skip immediately if another process holds the lock
• The same housekeeping pass also cleans messages, plans, sessions, pastes, image caches, debug logs, stale agent worktrees — file-history is one entry in a list

Why this is a follow-up, not part of #4064

A correct port adds:

• A cleanupOldFileHistoryBackups() function with mtime-based filtering
• A generic background-housekeeping framework (10 min boot delay, 24h recurrence, idle gating, marker + lockfile throttling) so file-history doesn't have to invent its own scheduler
• A cleanupPeriodDays setting (defaulting to 30 to match upstream)
• Wiring into app startup
• Tests

That's a non-trivial subsystem — closer to ~150 lines than to the inline fix proposed in the PR review (a destroy() on /clear). It also isn't file-history-specific: the same framework would naturally absorb other accumulating caches we have or will have. Bundling it into the /rewind PR would expand scope significantly and delay rewind landing for users who need it.

Acceptance criteria

• ~/.qwen/file-history/{sessionId}/ directories whose mtime is older than cleanupPeriodDays (default 30) are removed at most once per day
• Cleanup runs in the background, never blocks the REPL or interactive flow
• Marker / lockfile throttling so concurrent qwen-code processes don't race
• User can configure retention via settings.cleanupPeriodDays
• Other persistent caches (debug logs, image caches, etc.) can be added to the same housekeeping pass without further plumbing

Related

• PR feat(rewind): add file restoration support to /rewind command #4064 — introduces the directories that need cleaning
• Upstream reference: claude-code/src/utils/cleanup.ts + claude-code/src/utils/backgroundHousekeeping.ts

🤖 Generated with Qwen Code

[qwen-code-ci-bot]

This appears related to the broader background task management framework:

• Background task management: roadmap and next steps #3634 — Background task management: roadmap and next steps (tracks the background-housekeeping subsystem that would own this cleanup)

The background task framework described in #3634 already handles long-running processes (agents, shells, monitors). A function could be added as another entry in that same housekeeping pass, alongside the existing cleanup for messages, plans, sessions, and caches.