huskies: merge 1199 story Orphaned build-dir GC: reclaim dead worktree targets without touching warm caches

server/src/service/gc/mod.rs

@@ -0,0 +1,204 @@
+//! Orphaned build-dir GC (story 1199) — reclaims disk space from dead
+//! worktree `target/` directories and a stale `.huskies/merge_workspace`,
+//! without ever touching the main project's or any live worktree's
+//! `target/` (the warm caches that keep rebuilds fast).
+//!
+//! Follows service-module conventions: this file holds pure orphan-selection
+//! logic (no I/O); `io.rs` is the only place performing side effects
+//! (directory-size walks, `fs::remove_dir_all`, `spawn_blocking`, the pass
+//! orchestration entry point).
+
+/// Side effects for the GC pass: directory-size walks, recursive removal via
+/// `spawn_blocking`, and the pass orchestration entry point.
+pub mod io;
+
+use std::path::PathBuf;
+
+use crate::pipeline_state::Stage;
+use crate::worktree::WorktreeListEntry;
+
+/// A single directory identified as safe to reclaim by a GC pass.
+#[derive(Debug, Clone, PartialEq)]
+pub struct GcCandidate {
+    /// Human-readable label for reporting (story ID, or `"merge_workspace"`).
+    pub label: String,
+    pub path: PathBuf,
+}
+
+/// Summary of one GC pass: what was reclaimed, what was skipped (raced or
+/// errored), how many bytes were freed, and how long the pass took.
+#[derive(Debug, Clone, Default)]
+pub struct GcReport {
+    pub bytes_reclaimed: u64,
+    pub reclaimed: Vec<String>,
+    pub skipped: Vec<String>,
+    pub duration: std::time::Duration,
+}
+
+/// Select `target/` directories under worktrees whose story is no longer
+/// active in the pool (terminal stage, or absent from the CRDT entirely).
+///
+/// Reuses [`crate::worktree::worktree_should_be_swept`] — the same predicate
+/// that decides whether a whole worktree should be swept — so a `target/`
+/// dir is only ever reclaimed here for a worktree that full cleanup would
+/// also remove. Live worktrees (Backlog, Coding, Qa, Merge) are never
+/// touched, preserving their warm build cache.
+pub fn select_orphaned_worktree_targets<F>(
+    entries: &[WorktreeListEntry],
+    lookup: F,
+) -> Vec<GcCandidate>
+where
+    F: Fn(&str) -> Option<Stage>,
+{
+    entries
+        .iter()
+        .filter(|e| crate::worktree::worktree_should_be_swept(lookup(&e.story_id).as_ref()))
+        .map(|e| GcCandidate {
+            label: e.story_id.clone(),
+            path: e.path.join("target"),
+        })
+        .collect()
+}
+
+/// Select the `.huskies/merge_workspace` candidate, if it's safe to reclaim.
+///
+/// `merge_lock_free` should come from [`crate::agents::merge::merge_lock_is_free`]
+/// — a momentary snapshot of whether a squash-merge is currently running.
+/// When a merge is running, `merge_workspace` is live state, not an orphan.
+pub fn select_merge_workspace(
+    project_root: &std::path::Path,
+    merge_lock_free: bool,
+) -> Option<GcCandidate> {
+    if !merge_lock_free {
+        return None;
+    }
+    Some(GcCandidate {
+        label: "merge_workspace".to_string(),
+        path: project_root.join(".huskies").join("merge_workspace"),
+    })
+}
+
+/// Returns `true` if an automatic GC pass should run given the configured
+/// threshold and current free space.
+///
+/// `gc_min_free_gb == 0` disables automatic GC entirely — the on-demand `gc`
+/// MCP tool remains available regardless.
+pub fn should_auto_run(gc_min_free_gb: u64, free_bytes: u64) -> bool {
+    gc_min_free_gb > 0 && free_bytes < gc_min_free_gb * 1_000_000_000
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::Utc;
+
+    fn done_stage() -> Stage {
+        Stage::Done {
+            merged_at: Utc::now(),
+            merge_commit: crate::pipeline_state::GitSha("abc123".to_string()),
+        }
+    }
+
+    fn entry(story_id: &str) -> WorktreeListEntry {
+        WorktreeListEntry {
+            story_id: story_id.to_string(),
+            path: PathBuf::from(format!("/project/.huskies/worktrees/{story_id}")),
+        }
+    }
+
+    // ── select_orphaned_worktree_targets ─────────────────────────────────
+
+    #[test]
+    fn orphaned_target_is_selected_when_story_is_terminal() {
+        let entries = vec![entry("100_done")];
+        let candidates = select_orphaned_worktree_targets(&entries, |_| Some(done_stage()));
+
+        assert_eq!(candidates.len(), 1);
+        assert_eq!(candidates[0].label, "100_done");
+        assert_eq!(
+            candidates[0].path,
+            PathBuf::from("/project/.huskies/worktrees/100_done/target")
+        );
+    }
+
+    #[test]
+    fn orphaned_target_is_selected_when_story_absent_from_crdt() {
+        let entries = vec![entry("101_purged")];
+        let candidates = select_orphaned_worktree_targets(&entries, |_| None);
+
+        assert_eq!(candidates.len(), 1);
+        assert_eq!(candidates[0].label, "101_purged");
+    }
+
+    #[test]
+    fn live_worktree_target_is_kept_not_selected() {
+        let entries = vec![entry("102_coding")];
+        let candidates = select_orphaned_worktree_targets(&entries, |_| {
+            Some(Stage::Coding {
+                claim: None,
+                plan: Default::default(),
+                retries: 0,
+            })
+        });
+
+        assert!(
+            candidates.is_empty(),
+            "a live (Coding) worktree's target/ must never be selected for GC"
+        );
+    }
+
+    #[test]
+    fn mixed_pool_only_selects_the_orphan() {
+        let entries = vec![entry("103_coding"), entry("104_done")];
+        let candidates = select_orphaned_worktree_targets(&entries, |id| {
+            if id == "104_done" {
+                Some(done_stage())
+            } else {
+                Some(Stage::Coding {
+                    claim: None,
+                    plan: Default::default(),
+                    retries: 0,
+                })
+            }
+        });
+
+        assert_eq!(candidates.len(), 1);
+        assert_eq!(candidates[0].label, "104_done");
+    }
+
+    // ── select_merge_workspace ────────────────────────────────────────────
+
+    #[test]
+    fn merge_workspace_selected_when_lock_free() {
+        let root = PathBuf::from("/project");
+        let candidate = select_merge_workspace(&root, true);
+        assert_eq!(
+            candidate,
+            Some(GcCandidate {
+                label: "merge_workspace".to_string(),
+                path: PathBuf::from("/project/.huskies/merge_workspace"),
+            })
+        );
+    }
+
+    #[test]
+    fn merge_workspace_not_selected_when_merge_running() {
+        let root = PathBuf::from("/project");
+        assert_eq!(select_merge_workspace(&root, false), None);
+    }
+
+    // ── should_auto_run (disabled config) ──────────────────────────────────
+
+    #[test]
+    fn auto_run_disabled_when_threshold_is_zero() {
+        assert!(!should_auto_run(0, 0));
+        assert!(!should_auto_run(0, u64::MAX));
+    }
+
+    #[test]
+    fn auto_run_triggers_below_threshold() {
+        let gb = 1_000_000_000;
+        assert!(should_auto_run(50, 10 * gb));
+        assert!(!should_auto_run(50, 60 * gb));
+    }
+}