Skip to content

Workspace gc loop

Definition

Background caretaker loop that periodically garbage-collects stale worktrees and orphaned branches. Handles three leak classes: worktrees tracked in StateTracker whose PR has been merged or closed, orphaned worktree directories on disk with no StateTracker entry, and orphaned remote branches with no open PR. Catches worktrees that leak when PRs are merged manually, via HITL resolution, or when implementations fail or crash mid-cleanup.

Invariants

  • Kill-switch: enabled_cb("workspace_gc") AND config.workspace_gc_loop_enabled — both must be true to run.
  • Caps at _MAX_GC_PER_CYCLE = 20 collections per tick to avoid long-running passes.
  • State removal happens before WorkspacePort.destroy() so a crash between the two steps leaves the entry gone; destroy() is idempotent.
  • An optional is_in_pipeline_cb guard prevents GC of issues still being actively processed by a phase.