feat(cli): add ralph clean --events

Removes event run history under .ralph/ (events.jsonl, events-*.jsonl, and
the current-events marker) without touching specs, loops registry, or other
.ralph state. Mirrors the --diagnostics UX: nothing-to-clean message, dry-run
listing, and a success summary of removed files.

Closes #350

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: rookopenclaw

crates/ralph-cli/src/lib.rs

@@ -79,6 +79,94 @@ pub fn clean_diagnostics(workspace_root: &Path, use_colors: bool, dry_run: bool)
     Ok(())
 }
 
+/// Collect event run-history artifacts under `.ralph/`: `events.jsonl`,
+/// `events-*.jsonl`, and the `current-events` marker.
+fn event_artifacts(workspace_root: &Path) -> Vec<std::path::PathBuf> {
+    let ralph_dir = workspace_root.join(".ralph");
+    let mut found = Vec::new();
+
+    let marker = ralph_dir.join("current-events");
+    if marker.exists() {
+        found.push(marker);
+    }
+
+    if let Ok(entries) = fs::read_dir(&ralph_dir) {
+        for entry in entries.flatten() {
+            let name = entry.file_name();
+            let name = name.to_string_lossy();
+            if name.ends_with(".jsonl") && (name == "events.jsonl" || name.starts_with("events-")) {
+                found.push(entry.path());
+            }
+        }
+    }
+
+    found.sort();
+    found
+}
+
+/// Clean event run history (`events*.jsonl` + `current-events` marker) from `.ralph/`
+pub fn clean_events(workspace_root: &Path, use_colors: bool, dry_run: bool) -> Result<()> {
+    let targets = event_artifacts(workspace_root);
+
+    if targets.is_empty() {
+        if use_colors {
+            println!(
+                "{}Nothing to clean:{} No event files found in '{}'",
+                colors::DIM,
+                colors::RESET,
+                workspace_root.join(".ralph").display()
+            );
+        } else {
+            println!(
+                "Nothing to clean: No event files found in '{}'",
+                workspace_root.join(".ralph").display()
+            );
+        }
+        return Ok(());
+    }
+
+    if dry_run {
+        if use_colors {
+            println!(
+                "{}Dry run mode:{} Would delete event files:",
+                colors::CYAN,
+                colors::RESET
+            );
+        } else {
+            println!("Dry run mode: Would delete event files:");
+        }
+        for path in &targets {
+            println!("  {}", path.display());
+        }
+        return Ok(());
+    }
+
+    for path in &targets {
+        fs::remove_file(path).with_context(|| {
+            format!(
+                "Failed to delete '{}'. Check permissions and try again.",
+                path.display()
+            )
+        })?;
+    }
+
+    if use_colors {
+        println!(
+            "{}✓{} Cleaned: Deleted {} event file(s)",
+            colors::GREEN,
+            colors::RESET,
+            targets.len()
+        );
+    } else {
+        println!("Cleaned: Deleted {} event file(s)", targets.len());
+    }
+    for path in &targets {
+        println!("  {}", path.display());
+    }
+
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -112,4 +200,56 @@ mod tests {
         clean_diagnostics(temp_dir.path(), false, false).expect("clean diagnostics");
         assert!(!diagnostics_dir.exists());
     }
+
+    /// Creates a `.ralph/` with event artifacts plus non-event files that must survive.
+    fn events_fixture() -> tempfile::TempDir {
+        let temp_dir = tempfile::tempdir().expect("temp dir");
+        let ralph_dir = temp_dir.path().join(".ralph");
+        std::fs::create_dir_all(ralph_dir.join("specs")).expect("create .ralph");
+        for name in [
+            "events.jsonl",
+            "events-20260101-000000.jsonl",
+            "current-events",
+            "loops.json",
+            "merge-queue.jsonl",
+            "events-notes.md",
+        ] {
+            std::fs::write(ralph_dir.join(name), "x").expect("write fixture");
+        }
+        std::fs::write(ralph_dir.join("specs/plan.md"), "x").expect("write spec");
+        temp_dir
+    }
+
+    #[test]
+    fn clean_events_no_files_is_ok() {
+        let temp_dir = tempfile::tempdir().expect("temp dir");
+        assert!(clean_events(temp_dir.path(), false, false).is_ok());
+    }
+
+    #[test]
+    fn clean_events_dry_run_keeps_files() {
+        let temp_dir = events_fixture();
+        clean_events(temp_dir.path(), false, true).expect("dry run");
+        assert!(temp_dir.path().join(".ralph/events.jsonl").exists());
+        assert!(temp_dir.path().join(".ralph/current-events").exists());
+    }
+
+    #[test]
+    fn clean_events_deletes_only_event_artifacts() {
+        let temp_dir = events_fixture();
+        clean_events(temp_dir.path(), false, false).expect("clean events");
+
+        let ralph_dir = temp_dir.path().join(".ralph");
+        for gone in [
+            "events.jsonl",
+            "events-20260101-000000.jsonl",
+            "current-events",
+        ] {
+            assert!(!ralph_dir.join(gone).exists(), "{gone} should be deleted");
+        }
+        for kept in ["loops.json", "merge-queue.jsonl", "events-notes.md"] {
+            assert!(ralph_dir.join(kept).exists(), "{kept} should survive");
+        }
+        assert!(ralph_dir.join("specs/plan.md").exists());
+    }
 }

crates/ralph-cli/src/main.rs

@@ -918,6 +918,11 @@ struct CleanArgs {
     /// Clean diagnostic logs instead of `.ralph/` directory
     #[arg(long)]
     diagnostics: bool,
+
+    /// Clean event run history (`.ralph/events*.jsonl` + `current-events` marker)
+    /// instead of the agent directory
+    #[arg(long, conflicts_with = "diagnostics")]
+    events: bool,
 }
 
 /// Arguments for the emit subcommand.
@@ -2413,6 +2418,12 @@ fn clean_command(
         return ralph_cli::clean_diagnostics(&workspace_root, use_colors, args.dry_run);
     }
 
+    // If --events flag is set, clean event run history only
+    if args.events {
+        let workspace_root = std::env::current_dir().context("Failed to get current directory")?;
+        return ralph_cli::clean_events(&workspace_root, use_colors, args.dry_run);
+    }
+
     // Load config with overrides applied
     let config = load_config_with_overrides(config_sources)?;
 

docs/guide/cli-reference.md

@@ -262,7 +262,8 @@ ralph emit <TOPIC> [PAYLOAD] [OPTIONS]
 
 ### ralph clean
 
-Clean `.ralph/agent` scratchpad and memory state.
+By default, deletes the whole `.ralph/agent` directory — scratchpad, `memories.md`, and
+`tasks.jsonl` included. Use `--diagnostics` or `--events` to target run artifacts instead.
 
 ```bash
 ralph clean [OPTIONS]
@@ -272,9 +273,12 @@ ralph clean [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `--diagnostics` | Clean diagnostics directory |
+| `--diagnostics` | Clean `.ralph/diagnostics` instead of the agent directory |
+| `--events` | Clean event run history: `.ralph/events.jsonl`, `.ralph/events-*.jsonl`, and the `.ralph/current-events` marker |
 | `--dry-run` | Preview deletions |
 
+`--diagnostics` and `--events` are mutually exclusive; run the command twice to clear both.
+
 ### ralph loops
 
 Manage parallel loops and worktree loop lifecycle.