Session transcripts silently deleted by cleanupPeriodDays (keyed on file mtime): data loss, no warning, no recovery

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/59248
2. https://github.com/anthropics/claude-code/issues/41458
3. https://github.com/anthropics/claude-code/issues/46621

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Solution: claude-code #62250 — Session transcripts silently deleted by cleanupPeriodDays

Issue Summary

cleanupPeriodDays (default 30) deletes session transcript JSONLs keyed on file mtime, not conversation last-activity timestamp. Silent permanent deletion with no warning, no trash, no undo. 11 transcripts lost in the reporter's case.

Root Cause Analysis

Three distinct problems in src/utils/cleanup.ts:

1. mtime as deletion key: File mtime is externally mutable — backup/restore, sync tools, or any touch/os.utime call changes it independently of actual session activity.

1. Silent permanent deletion: fsImpl.unlink() with no warning, no trash, no log. Users have zero visibility until sessions are gone.

1. cleanupPeriodDays: 0 footgun: 0 means "delete everything now" not "disable cleanup". Combined with shouldSkipPersistence() treating === 0 as "don't persist", setting it to 0 wipes all transcripts AND prevents new ones.

Proposed Fix

Phase 1: Key on transcript metadata, not mtime

// Before: uses file mtime
async function unlinkIfOld(filePath, cutoffDate, fsImpl) {
  const stats = await fsImpl.stat(filePath)
  if (stats.mtime < cutoffDate) {
    await fsImpl.unlink(filePath)
    return true
  }
}

// After: read last activity from transcript itself
async function unlinkIfOld(filePath, cutoffDate, fsImpl) {
  const stats = await fsImpl.stat(filePath)
  // Read the JSONL and find the last message timestamp
  const lastActivity = await getLastActivityTimestamp(filePath, fsImpl)
  if (lastActivity && lastActivity < cutoffDate) {
    // Archive instead of delete (Phase 2)
    await archiveFile(filePath, fsImpl)
    return true
  }
  // Fallback to mtime only if we can't read the transcript
  if (!lastActivity && stats.mtime < cutoffDate) {
    await archiveFile(filePath, fsImpl)
    return true
  }
}

async function getLastActivityTimestamp(filePath, fsImpl): Promise<Date | null> {
  try {
    const content = await fsImpl.readFile(filePath, 'utf-8')
    const lines = content.trim().split('\n')
    if (lines.length === 0) return null
    // Last non-empty line should contain a message with timestamp
    for (let i = lines.length - 1; i >= 0; i--) {
      try {
        const entry = JSON.parse(lines[i])
        if (entry.timestamp) return new Date(entry.timestamp)
        if (entry.ts) return new Date(entry.ts)
      } catch {}
    }
  } catch {}
  return null
}

Phase 2: Archive/trash instead of unlink

async function archiveFile(filePath, fsImpl) {
  const archiveDir = path.join(
    path.dirname(filePath),
    '.claude-archive',
    new Date().toISOString().slice(0, 10)
  )
  await fsImpl.mkdir(archiveDir, { recursive: true })
  const archivePath = path.join(
    archiveDir,
    `${Date.now()}-${path.basename(filePath)}`
  )
  await fsImpl.rename(filePath, archivePath)
  // Log prominently
  console.warn(
    `[cleanup] Archived old session transcript: ${filePath} → ${archivePath}`
  )
}

Phase 3: Safer defaults and split the 0 overload

// settings.ts
const CLEANUP_SCHEMA = z.object({
  cleanupPeriodDays: z.number().int().min(1).default(90), // 90 days, min 1
  cleanupAction: z.enum(['archive', 'delete', 'skip']).default('archive'),
  cleanupEnabled: z.boolean().default(false), // opt-in, not opt-out
})

Key changes:

• Default retention: 30 → 90 days
• Default action: delete → archive
• Default enabled: true → false (opt-in)
• 0 no longer valid; use cleanupEnabled: false to disable

Phase 4: First-run warning

// On first cleanup run, show a warning
if (!settings.cleanupWarningShown) {
  console.warn(
    `[cleanup] Session transcript cleanup is enabled. ` +
    `Transcripts older than ${settings.cleanupPeriodDays} days will be ` +
    `${settings.cleanupAction === 'delete' ? 'permanently deleted' : 'archived'}. ` +
    `Set cleanupEnabled: false to disable. ` +
    `Set cleanupPeriodDays to adjust retention window.`
  )
  settings.cleanupWarningShown = true
}

Test Plan

1. mtime independence: Create a transcript with mtime 40 days ago but last message timestamp 2 days ago → should NOT be deleted
2. archive vs delete: Verify archived files appear in .claude-archive/ directory
3. 0 handling: Setting cleanupPeriodDays: 0 should be rejected by schema validation
4. opt-in behavior: With default settings, cleanup should not run
5. warning display: First cleanup run should show a prominent warning

Impact Assessment

• Severity: P0 data loss bug
• Affected users: Anyone who backs up/restores/syncs ~/.claude, anyone keeping sessions >30 days
• Fix complexity: Low (primarily changing the deletion key and adding archive logic)
• Risk: Minimal — this is a defensive change that only makes cleanup safer

Submission

Post as comment on: https://github.com/anthropics/claude-code/issues/62250

Folding into #59248 (the canonical silent-retention-deletion thread). Posted the mtime-keying mechanism, the cleanupPeriodDays: 0 overload, the #41458 / #45735 setting-sources bypass, and a SessionStart backup-hook stopgap there. Closing as a duplicate of #59248.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.