feat(session): prune session files past the retention window at startup

Wires the existing cleanup_period_days config to a real implementation:
SessionHistory::cleanup_older_than removes session files (.json / .jsonl and
quarantined .corrupt-*) whose mtime is older than the configured number of
days, bounding unbounded growth of the sessions directory. Run best-effort at
CLI startup, skipped when persistence is disabled or the period is unset/zero.

Author: lingcoder

crates/cli/src/agent.rs

@@ -372,6 +372,22 @@ pub async fn run(cli: &Cli, resume_session_id: Option<String>) -> anyhow::Result
         Some(sessions_dir.clone())
     };
 
+    // Best-effort retention: prune session files older than the configured
+    // window so the sessions directory does not grow unbounded. Skipped when
+    // persistence is off or retention is unset/zero.
+    if let Some(ref dir) = effective_sessions_dir
+        && let Some(days) = settings.cleanup_period_days
+        && days > 0
+    {
+        match crab_session::SessionHistory::new(dir.clone()).cleanup_older_than(days) {
+            Ok(n) if n > 0 => {
+                tracing::info!("pruned {n} session file(s) older than {days} days");
+            }
+            Ok(_) => {}
+            Err(e) => tracing::warn!(error = %e, "session cleanup failed"),
+        }
+    }
+
     // Resolve resume ID: explicit --resume > -c (continue latest) > None
     let effective_resume_id = if resume_session_id.is_some() {
         resume_session_id

crates/session/src/history.rs

@@ -322,6 +322,37 @@ impl SessionHistory {
         self.read_session_file(session_id).ok().flatten()?.name
     }
 
+    /// Delete session files (`.json` / `.jsonl` and quarantined `.corrupt-*`)
+    /// whose modification time is older than `days`, bounding the growth of the
+    /// sessions directory. `days == 0` is a no-op (retention disabled). Returns
+    /// the number of files removed.
+    pub fn cleanup_older_than(&self, days: u32) -> crab_core::Result<u32> {
+        if days == 0 || !self.base_dir.exists() {
+            return Ok(0);
+        }
+        let Some(cutoff) = std::time::SystemTime::now()
+            .checked_sub(std::time::Duration::from_secs(u64::from(days) * 86_400))
+        else {
+            return Ok(0);
+        };
+
+        let mut removed = 0u32;
+        for entry in std::fs::read_dir(&self.base_dir)?.flatten() {
+            let path = entry.path();
+            if !path.is_file() {
+                continue;
+            }
+            if let Ok(meta) = entry.metadata()
+                && let Ok(modified) = meta.modified()
+                && modified < cutoff
+                && std::fs::remove_file(&path).is_ok()
+            {
+                removed += 1;
+            }
+        }
+        Ok(removed)
+    }
+
     /// Find the most recent session to resume for `--continue`.
     ///
     /// Prefers the newest session whose recorded working directory matches
@@ -1584,6 +1615,38 @@ mod tests {
         assert!(history.load_jsonl("s1").unwrap().is_none());
     }
 
+    #[test]
+    fn cleanup_older_than_removes_stale_and_keeps_recent() {
+        let dir = tempfile::tempdir().unwrap();
+        let history = SessionHistory::new(dir.path().to_path_buf());
+        history.save("recent", &[Message::user("new")]).unwrap();
+
+        // Backdate one session file well past the retention window.
+        let old_path = dir.path().join("old.json");
+        std::fs::write(&old_path, r#"{"session_id":"old","messages":[]}"#).unwrap();
+        let stale = std::time::SystemTime::now() - std::time::Duration::from_secs(40 * 86_400);
+        let f = std::fs::OpenOptions::new()
+            .write(true)
+            .open(&old_path)
+            .unwrap();
+        f.set_modified(stale).unwrap();
+        drop(f);
+
+        let removed = history.cleanup_older_than(30).unwrap();
+        assert_eq!(removed, 1);
+        assert!(!old_path.exists());
+        assert!(dir.path().join("recent.json").exists());
+    }
+
+    #[test]
+    fn cleanup_older_than_zero_is_disabled() {
+        let dir = tempfile::tempdir().unwrap();
+        let history = SessionHistory::new(dir.path().to_path_buf());
+        history.save("s1", &[Message::user("hi")]).unwrap();
+        assert_eq!(history.cleanup_older_than(0).unwrap(), 0);
+        assert!(dir.path().join("s1.json").exists());
+    }
+
     #[test]
     fn jsonl_skips_malformed_lines() {
         let dir = tempfile::tempdir().unwrap();