cmd

Documentation

Index

• Constants
• func Execute()
• type CleanupPhysicalComponent
• type CleanupPhysicalTarget
• type CleanupPlan
  • func PlanWorktreeCleanup(units []WorktreeCleanupUnit, policy CleanupPolicy) CleanupPlan
• type CleanupPlanCandidate
  • func ClassicCleanupPlanCandidates(targets []types.DebrisInfo) []CleanupPlanCandidate
  • func WorktreeCleanupPlanCandidates(plan CleanupPlan, items []types.DebrisInfo) []CleanupPlanCandidate
• type CleanupPlanEvidence
• type CleanupPlanReason
• type CleanupPlanReasonCode
• type CleanupPlanRelation
• type CleanupPlanRow
• type CleanupPlanSelection
• type CleanupPlanTotals
• type CleanupPolicy
  • func DefaultCleanupPolicy(now time.Time) CleanupPolicy
• type DecisionClass
• type DecisionReason
• type DecisionReasonCode
• type GitEvidenceReason
• type GitEvidenceReasonCode
• type GitUpstreamMetadata
• type GitUpstreamState
• type GitWorktreeMember
• type UnifiedCleanupPlan
  • func BuildUnifiedCleanupPlan(ctx context.Context, candidates []CleanupPlanCandidate, ...) (UnifiedCleanupPlan, error)
  • func (p UnifiedCleanupPlan) SelectedPhysicalTargets() []types.DebrisInfo
  • func (p UnifiedCleanupPlan) Totals() CleanupPlanTotals
  • func (p UnifiedCleanupPlan) ValidateForExecution(ctx context.Context, now time.Time) error
• type WorktreeActivityEvidence
• type WorktreeActivitySource
• type WorktreeCleanupDecision
• type WorktreeCleanupUnit
  • func BuildWorktreeCleanupUnits(items []types.DebrisInfo) ([]WorktreeCleanupUnit, error)
  • func BuildWorktreeCleanupUnitsWithActivity(ctx context.Context, items []types.DebrisInfo) ([]WorktreeCleanupUnit, error)

Constants

const (
	DefaultRecentActivityWindow       = 6 * time.Hour
	DefaultKeepPerRepository          = 3
	DefaultMinIdleAge                 = 3 * 24 * time.Hour
	DefaultCleanupMinSize       int64 = 256 * 1024 * 1024
)

Functions

func Execute

func Execute()

Types

type CleanupPhysicalComponent

type CleanupPhysicalComponent struct {
	Key            string
	CanonicalPath  string
	OwnerTargetKey string
	Owner          types.DebrisInfo
	TargetKeys     []string
	RowKeys        []string
	Selection      CleanupPlanSelection
}

CleanupPhysicalComponent is one containment-connected on-disk unit. Owner is the outermost canonical target and is the only source of physical bytes.

type CleanupPhysicalTarget

type CleanupPhysicalTarget struct {
	Key             string
	OwnerKey        string
	Item            types.DebrisInfo
	RowKeys         []string
	PolicySelection CleanupPlanSelection
	Selection       CleanupPlanSelection
}

CleanupPhysicalTarget is one exact canonical path and retains every discovery row at that path. Component ownership is recorded separately so exact duplicates remain distinguishable without adding physical bytes.

type CleanupPlan

type CleanupPlan struct {
	Decisions []WorktreeCleanupDecision
}

func PlanWorktreeCleanup

func PlanWorktreeCleanup(units []WorktreeCleanupUnit, policy CleanupPolicy) CleanupPlan

PlanWorktreeCleanup evaluates hard locks, ranks every unit per canonical repository, then classifies by hard lock, retention, idle age, and size.

type CleanupPlanCandidate

type CleanupPlanCandidate struct {
	RowKey    string
	Item      types.DebrisInfo
	Selection CleanupPlanSelection
	Reasons   []CleanupPlanReason
}

CleanupPlanCandidate is the policy-neutral input boundary. Classic filtering and guided worktree policy each adapt their existing decisions into this shape instead of reimplementing policy in the unified plan.

func ClassicCleanupPlanCandidates

func ClassicCleanupPlanCandidates(targets []types.DebrisInfo) []CleanupPlanCandidate

ClassicCleanupPlanCandidates adapts already-filtered classic targets.

func WorktreeCleanupPlanCandidates

func WorktreeCleanupPlanCandidates(plan CleanupPlan, items []types.DebrisInfo) []CleanupPlanCandidate

WorktreeCleanupPlanCandidates adapts the existing deterministic worktree policy without duplicating its classification rules.

type CleanupPlanEvidence

type CleanupPlanEvidence struct {
	ObservedAt     time.Time
	MaxAge         time.Duration
	ProviderErrors []types.ScanProviderError
}

CleanupPlanEvidence records whether the scan can authorize a later execution. MaxAge zero means the caller has not imposed an expiry.

type CleanupPlanReason

type CleanupPlanReason struct {
	Code        CleanupPlanReasonCode
	Description string
}

type CleanupPlanReasonCode

type CleanupPlanReasonCode string

const (
	CleanupPlanReasonClassicEligible        CleanupPlanReasonCode = "classic_eligible"
	CleanupPlanReasonAgentStateOrphaned     CleanupPlanReasonCode = "agent_state_orphaned"
	CleanupPlanReasonContainsLockedTarget   CleanupPlanReasonCode = "contains_locked_target"
	CleanupPlanReasonOverlapsLockedTarget   CleanupPlanReasonCode = "overlaps_locked_target"
	CleanupPlanReasonWorktreePolicyDecision CleanupPlanReasonCode = "worktree_policy_decision"
)

type CleanupPlanRelation

type CleanupPlanRelation string

const (
	CleanupPlanRelationOwner  CleanupPlanRelation = "owner"
	CleanupPlanRelationExact  CleanupPlanRelation = "exact"
	CleanupPlanRelationNested CleanupPlanRelation = "nested"
)

type CleanupPlanRow

type CleanupPlanRow struct {
	Key             string
	TargetKey       string
	OwnerKey        string
	CanonicalPath   string
	Relation        CleanupPlanRelation
	Item            types.DebrisInfo
	PolicySelection CleanupPlanSelection
	Selection       CleanupPlanSelection
	Reasons         []CleanupPlanReason
	PhysicalBytes   int64
}

CleanupPlanRow is one visible policy decision. More than one row may refer to the same physical target.

type CleanupPlanSelection

type CleanupPlanSelection string

CleanupPlanSelection is the user-visible and executable state of a plan row. Locked rows are never selectable, including when --force is used later.

const (
	CleanupPlanSelected   CleanupPlanSelection = "selected"
	CleanupPlanUnselected CleanupPlanSelection = "unselected"
	CleanupPlanLocked     CleanupPlanSelection = "locked"
)

type CleanupPlanTotals

type CleanupPlanTotals struct {
	VisibleRows       int
	PhysicalTargets   int
	PhysicalBytes     int64
	EligibleTargets   int
	EligibleBytes     int64
	SelectedTargets   int
	SelectedBytes     int64
	ReviewableTargets int
	ReviewableBytes   int64
	UnselectedRows    int
	HardLockedRows    int
	HardLockedTargets int
	HardLockedBytes   int64
}

type CleanupPolicy

type CleanupPolicy struct {
	Now                     time.Time
	CurrentWorkingDirectory string
	RecentActivityWindow    time.Duration
	KeepPerRepository       int
	MinIdleAge              time.Duration
	MinSize                 int64
}

CleanupPolicy contains the independent inputs used to classify worktree cleanup units. Now is explicit so planning stays deterministic and free of clock or filesystem access.

func DefaultCleanupPolicy

func DefaultCleanupPolicy(now time.Time) CleanupPolicy

DefaultCleanupPolicy returns the product defaults for a caller-supplied reference time.

type DecisionClass

type DecisionClass string

DecisionClass is the policy result before any UI selection state is added.

const (
	DecisionLocked      DecisionClass = "locked"
	DecisionReviewable  DecisionClass = "reviewable"
	DecisionRecommended DecisionClass = "recommended"
)

type DecisionReason

type DecisionReason struct {
	Code         DecisionReasonCode
	Description  string
	WorktreePath string
}

DecisionReason wraps a stable code so future presentation details can be added without changing the planner contract.

type DecisionReasonCode

type DecisionReasonCode string

DecisionReasonCode is a stable machine-readable explanation for a cleanup decision. Hard-lock reasons are emitted in the declaration order below.

const (
	DecisionReasonCurrentWorkingDirectory DecisionReasonCode = "current_working_directory"
	DecisionReasonDirtyWorktree           DecisionReasonCode = "git_dirty_or_untracked"
	DecisionReasonGitEvidenceUnavailable  DecisionReasonCode = "git_evidence_unavailable"
	DecisionReasonDetachedUnreferenced    DecisionReasonCode = "git_detached_head_unreferenced"
	DecisionReasonActivityUnavailable     DecisionReasonCode = "activity_evidence_unavailable"
	DecisionReasonRecentActivity          DecisionReasonCode = "recent_activity"
	DecisionReasonRepositoryRetention     DecisionReasonCode = "retained_per_repository"
	DecisionReasonMinimumIdleAge          DecisionReasonCode = "younger_than_min_idle_age"
	DecisionReasonMinimumSize             DecisionReasonCode = "below_min_size"
	DecisionReasonEligible                DecisionReasonCode = "cleanup_recommended"
)

type GitEvidenceReason

type GitEvidenceReason struct {
	Code         GitEvidenceReasonCode
	Description  string
	WorktreePath string
}

GitEvidenceReason pairs a stable result code with human-facing context. The member path makes aggregate cleanup-unit failures attributable and testable.

type GitEvidenceReasonCode

type GitEvidenceReasonCode string

GitEvidenceReasonCode is a stable machine-readable recoverability result.

const (
	GitReasonEvidenceUnavailable      GitEvidenceReasonCode = "git_evidence_unavailable"
	GitReasonDirtyWorktree            GitEvidenceReasonCode = "git_dirty_or_untracked"
	GitReasonAttachedBranch           GitEvidenceReasonCode = "git_attached_local_branch"
	GitReasonDetachedHeadReachable    GitEvidenceReasonCode = "git_detached_head_reachable"
	GitReasonDetachedHeadUnreferenced GitEvidenceReasonCode = "git_detached_head_unreferenced"
)

type GitUpstreamMetadata

type GitUpstreamMetadata struct {
	State GitUpstreamState
	Ref   string
}

GitUpstreamMetadata explains tracking configuration without making it a hard-safety input. Ref remains populated for a configured but gone upstream.

type GitUpstreamState

type GitUpstreamState string

GitUpstreamState is explanatory only and never determines recoverability.

const (
	GitUpstreamNotApplicable GitUpstreamState = "not_applicable"
	GitUpstreamNone          GitUpstreamState = "none"
	GitUpstreamPresent       GitUpstreamState = "present"
	GitUpstreamGone          GitUpstreamState = "gone"
	GitUpstreamUnavailable   GitUpstreamState = "unavailable"
)

type GitWorktreeMember

type GitWorktreeMember struct {
	WorktreePath         string
	RepositoryID         string
	DisplayRepository    string
	BranchRef            string
	HeadOID              string
	ContainingLocalRefs  []string
	ContainingRemoteRefs []string
	Upstream             GitUpstreamMetadata
	Dirty                bool
	Recoverable          bool
	HardLocked           bool
	Reason               GitEvidenceReason
	// EvidenceAvailable reports whether repository identity metadata resolved.
	// GitEvidenceAvailable separately reports whether the recoverability
	// inspection completed; both are required for a member to pass hard safety.
	EvidenceAvailable      bool
	EvidenceError          string
	GitEvidenceAvailable   bool
	GitEvidenceError       string
	LastActivity           time.Time
	ActivitySource         WorktreeActivitySource
	ActivityAvailable      bool
	ActivityEvidence       []WorktreeActivityEvidence
	CodexActivityAvailable bool
	CodexActivitySource    string
	CodexActivityError     string
}

GitWorktreeMember identifies an actual direct or one-level nested Git worktree contained by a cleanup unit.

type UnifiedCleanupPlan

type UnifiedCleanupPlan struct {
	Rows       []CleanupPlanRow
	Targets    []CleanupPhysicalTarget
	Components []CleanupPhysicalComponent
	Evidence   CleanupPlanEvidence
}

UnifiedCleanupPlan is the shared, renderer-independent state for mixed cleanup review and execution.

func BuildUnifiedCleanupPlan

func BuildUnifiedCleanupPlan(ctx context.Context, candidates []CleanupPlanCandidate, evidence CleanupPlanEvidence) (UnifiedCleanupPlan, error)

BuildUnifiedCleanupPlan normalizes visible policy decisions into exact physical targets. A hard lock in either containment direction dominates the complete component.

func (UnifiedCleanupPlan) SelectedPhysicalTargets

func (p UnifiedCleanupPlan) SelectedPhysicalTargets() []types.DebrisInfo

SelectedPhysicalTargets returns deterministic, overlap-normalized execution targets. It never returns locked or unselected targets.

func (UnifiedCleanupPlan) Totals

func (p UnifiedCleanupPlan) Totals() CleanupPlanTotals

func (UnifiedCleanupPlan) ValidateForExecution

func (p UnifiedCleanupPlan) ValidateForExecution(ctx context.Context, now time.Time) error

ValidateForExecution rejects cancellation, partial scan evidence, and plans whose caller-defined evidence window has expired.

type WorktreeActivityEvidence

type WorktreeActivityEvidence struct {
	Source    WorktreeActivitySource
	Timestamp time.Time
	Available bool
	Error     string
}

WorktreeActivityEvidence preserves both positive timestamps and source availability. Available evidence may have no matching timestamp; this is distinct from an index or command outage.

type WorktreeActivitySource

type WorktreeActivitySource string

WorktreeActivitySource identifies the trusted metadata source selected for a member's last activity. Constant order is also the deterministic tie precedence: Codex session, HEAD reflog, then scanner metadata.

const (
	WorktreeActivityCodexSession WorktreeActivitySource = "codex_session"
	WorktreeActivityHeadReflog   WorktreeActivitySource = "head_reflog"
	WorktreeActivityFallback     WorktreeActivitySource = "scanner_metadata"
)

type WorktreeCleanupDecision

type WorktreeCleanupDecision struct {
	Unit    WorktreeCleanupUnit
	Class   DecisionClass
	Reasons []DecisionReason
}

type WorktreeCleanupUnit

type WorktreeCleanupUnit struct {
	TargetPath             string
	Size                   int64
	Source                 string
	Members                []GitWorktreeMember
	LastActivity           time.Time
	ActivitySource         WorktreeActivitySource
	ActivityMember         string
	ActivityAvailable      bool
	CodexActivityAvailable bool
	CodexActivitySource    string
	CodexActivityError     string
	HardLocked             bool
	HardLockReasons        []GitEvidenceReason
}

WorktreeCleanupUnit is one canonical physical deletion target. A unit may contain more than one Git worktree member, but its size is counted once.

func BuildWorktreeCleanupUnits

func BuildWorktreeCleanupUnits(items []types.DebrisInfo) ([]WorktreeCleanupUnit, error)

BuildWorktreeCleanupUnits adapts scanner rows into deterministic physical cleanup units without changing the persisted DebrisInfo or scan JSON shape.

func BuildWorktreeCleanupUnitsWithActivity

func BuildWorktreeCleanupUnitsWithActivity(ctx context.Context, items []types.DebrisInfo) ([]WorktreeCleanupUnit, error)

BuildWorktreeCleanupUnitsWithActivity builds cleanup units and enriches each member with metadata-only activity evidence. Policy and deletion decisions deliberately remain outside this evidence seam.