Cleanup safety: protect session data for non-existent folders (stale detection)

[DrumRobot]

Problem

When a project folder no longer exists on disk, the cleanup logic may inadvertently remove or corrupt session data that references those paths.

• feat(core): sort projects by recency, detect stale directories #65 (temporarily removed)

Proposal

Add a safety layer to the stale detection system:

• Before marking sessions as stale, verify the folder existence
• Distinguish between "folder deleted" vs "folder temporarily unmounted/disconnected"
• Add a grace period or confirmation step before purging session data

Impact

• Prevents data loss when external drives are disconnected
• Protects session history during project directory reorganization
• Related to v0.4.9 stability milestone (Issue v0.4.9 release tracking #86)

Status

Open for discussion — seeking input on the best approach before implementation.

[DrumRobot]

Real-world impact: Cross-OS sync

Hitting this scenario with two machines (macOS + Windows) running Claude Code, with ~/.claude/projects/ synced across both via a folder-sync tool. Each machine sees the other OS's project directories under ~/.claude/projects/:

• macOS host sees C--Users-... directories (Windows-origin)
• Windows host sees -Users-... directories (macOS-origin)

These directories are legitimate — they hold real session history from the other machine. Their corresponding source project paths (encoded in the directory name) simply don't exist on the current OS.

A naive fs.access(decodedProjectPath) check would mark all foreign-OS directories as stale and delete them, destroying the cross-OS session history.

Suggested safety guards (incremental):

1. OS-aware path detection — distinguish current-OS vs foreign-OS encoded paths:
   • macOS/Linux native: starts with -Users- or -home-
   • Windows native: drive-letter pattern (e.g., C--)
   • Skip stale check entirely for foreign-OS paths
2. Folder-existence ≠ stale — even for current-OS paths, the source folder may be temporarily unmounted (external drive, network share) or renamed/moved. Treat folder absence as candidate, not confirmed stale.
3. Grace period / explicit confirmation — never auto-delete. Require explicit user confirmation with the affected paths shown.
4. Reversible deletion — move to a backup directory first, schedule purge later.

Current state (for context): packages/core/src/types.ts:286 defines isStale?: boolean but the detection logic isn't wired in core. PR #84 added vscode-side calls; PR #143 surfaced the gap via typecheck. Recommend keeping detection inert (extension.ts calls removed) until #1 + #3 above are designed.

Related: #65 (the original "stale projects" feature, partially reverted).

[DrumRobot]

Follow-up: concrete safety guards before PR #143 lands

Building on my cross-OS sync analysis, PR #143 surfaced the typecheck gap
for clearSessions({ clearStale, staleProjects }). The plan adds core API, but
deletion semantics need safety guards first.

Proposed concrete guards (combining suggestions 2 + 3 from the comment above):

1. Session activity time check in core

   • Before marking a project as isStale, check the most recent session JSONL mtime
   • If any session was modified within N days (default 30), skip stale classification
   • Rationale: a foreign-OS sync brings recent files; an actually-abandoned local
     folder typically has stale mtimes

2. Extension default opt-in

   • Revert extension's clearStale: totalStale > 0 default → clearStale: false
   • Add explicit toggle UI in cleanup confirmation panel
   • Rationale: even with time-check guard, automatic stale deletion on a button
     click is too aggressive for sync scenarios

Path forward

• Core (Issue Fix getCustomTitle to use latest custom-title and remove summary fallback #118): implement clearStale with time-check baked in
• Extension follow-up: opt-in toggle in cleanup UI
• PR feat(vscode): spike Custom Editor for JSONL preview #143 should land with core impl + extension default disabled

OS-aware detection (suggestion 1) remains a future enhancement; time-check covers
most cases without OS-encoding heuristics.