purge: reclaim stale AI-agent git worktrees & throwaway checkouts

[hhh2210]

Hi @tw93 — floating a design idea before writing code, per the contributing flow.

Problem

AI coding agents now create git worktrees and throwaway clones at a high rate, and they pile up as multi-GB dead weight that mo purge can't currently reclaim. On my machine a single scratch dir held 27 GB, almost all of it:

• git worktrees created by different tools in different default locations — Claude Code → <repo>/.claude/worktrees/agent-*, Codex CLI → <repo>/.codex/worktrees/*, opencode → $TMPDIR/opencode/*, plus hand-made ones under a scratch dir.
• custom-named build/proof trees — e.g. foo-proof/frozen-home/ (3.6 GB), bar-build/out/ (2 GB). Not matched by MOLE_PURGE_TARGETS, so purge never sees them.
• whole stale checkouts — re-cloneable, but nothing ages them out.

Two gaps in today's purge (I read lib/clean/project.sh):

1. It removes known artifact sub-dirs inside projects (great), but never whole stale checkouts, and doesn't recognize custom build-tree names.
2. It has no notion of git worktrees. When a worktree's working dir is removed out-of-band, the parent repo keeps a dangling registration (git worktree list → prunable). I found 29 dead registrations in one repo. rm is the wrong tool here — it needs git worktree remove / prune.

The architectural question (up front)

I read lib/clean/project.sh. is_safe_project_artifact enforces a deliberate invariant: purge only removes known-named artifacts nested inside a detected project, and explicitly "must not be a direct child of the search root". That's the right safety model for node_modules/.build.

But AI-agent scratch is the opposite shape: the GB-scale dead weight is whole top-level entries — worktree checkouts, and custom-named build/proof trees (frozen-home/ 3.6 GB, out/ 2 GB) that don't match PURGE_TARGETS. Reclaiming them means removing top-level entries under a search root, which today's purge deliberately refuses.

So this is a scope decision only you can make: is there room for an opt-in, per-path mode that removes whole top-level entries under paths the user explicitly designates as scratch — or should this live outside purge's nested-only model entirely (separate verb, or Mole Mac)?

Proposed solution (opt-in, config-gated) — if you're open to it

A scratch mode for purge, active only on paths the user explicitly marks as scratch in ~/.config/mole/purge_paths (never a default root), presented through purge's existing list → confirm flow:

• For each top-level entry under a marked scratch path, if untouched ≥ N days (default 7, matching MIN_AGE_DAYS), offer the whole entry for removal.
• git-worktree–aware: remove the working dir through the existing mole_delete funnel (Trash routing, oplog, path protection — no second delete path), then git worktree prune the parent so no dangling registration is left. Also GC already-dead registrations found during discovery.

Safety design (the crux)

• --dry-run default, same as purge today; mole_delete for all removals, never raw rm -rf.
• Never touch unique work: skip if a git worktree/clone is dirty (git status --porcelain), has unpushed commits on HEAD (git log --not --remotes HEAD), or has no remote.
• Opt-out: a .keep sentinel, plus existing whitelist and CACHEDIR.TAG respect.
• Opt-in only: does nothing unless the path is in purge_paths — no new default scan roots.
• Spotlight footnote: purging content out of a .metadata_never_index-excluded dir into ~/.Trash re-exposes it to indexing (I hit a reproducible mds_stores CPU storm). For excluded scratch paths, permanent-delete is safer than trashing — worth a flag.

Questions for you

1. UX preference — a new mo purge --scratch flag, a per-path mode in purge_paths, or a separate subcommand?
2. Is whole-entry removal within purge's scope, or would you rather keep purge to artifact sub-dirs and put this behind an explicit new verb?
3. Any objection to shelling out to git worktree from the purge path?

Happy to send a draft PR once the shape is agreed.

[tw93]

@hhh2210 Thanks for working the design out before writing code, and for reading the purge internals first.

I want the git worktree half, not the scratch path half. And the worktree half is simpler than you framed it.

You proposed breaking the "must not be a direct child of the search root" rule. You don't need to. That rule exists because a top-level directory carries no authority saying it is reproducible; all purge has for node_modules is a name guess. A worktree does have one: git worktree list --porcelain on the parent repo. Clean, remote-backed, no commits outside the remote means it is a checkout of objects that already exist locally, and git worktree add restores it offline in seconds. That is a stronger reproducibility claim than anything in PURGE_TARGETS today.

So the authorization comes from the git registration, not from the path. No purge_paths mode, no new config, no new scan root, and is_safe_project_artifact stays untouched. Discovery becomes "for each repo under the existing roots, ask git", which picks up Claude Code, Codex, opencode, $TMPDIR and hand-made worktrees for free, including ones sitting as plain top-level siblings that no location-based scan would ever find.

Two corrections, since your safety design rests on both: --dry-run is not purge's default (it scans, lists, confirms, then deletes), and purge does not use mole_delete. It calls safe_remove (lib/core/file_ops.sh:297), a validated, oplogged rm -rf. There is no Trash net under purge today, so treat everything here as a permanent delete.

Your three guards also need a fourth: staleness. A worktree can be clean, fully pushed and remote-backed and still be where I am working right now, and I had exactly that on this machine today. Take the age from git rather than is_recently_modified (lib/clean/project.sh:602), which reads the directory's own mtime and does not move when a file deep inside the tree is edited.

Not taking the scratch path mode. Your real weight, frozen-home/ and out/, are not worktrees, so no git guard applies and the only signal left is "marked directory, 7 days old". That is a generic mtime reaper, deleting things it cannot prove are reproducible. Not taking the permanent-delete flag either: purge is already permanent, and the mds_stores chain needs its own reproduction before it justifies a design decision.

You are right about one thing separately: purge undercounts inside checkouts. A 789 MB agent worktree here reclaims nothing, because 394 MB of it is Jekyll's _site plus .jekyll-cache, both locally reproducible and simply missing from PURGE_TARGETS. A small separate PR adding them is welcome, gated on a Jekyll marker so _site is never matched on name alone.

Send the worktree PR and I will review it. No objection to shelling out to git worktree, it is the only authoritative source here.

[hhh2210]

solute, i would send the PR in weekend luckly, thanks for your detailed explaination!

[tw93]

@hhh2210 Sounds good. Three constraints before you start, so review does not send you back:

1. is_safe_configured_purge_artifact (lib/clean/project.sh:1670) re-validates every item immediately before deletion, and any worktree sitting as a direct child of a search root fails it by design. Give worktrees a parallel revalidation predicate. Do not let the worktree branch skip that call, it is the last gate before rm.
2. Non-interactive purge auto-selects every non-recent item (lib/clean/project.sh:1611). Worktrees have to stay out of that automatic selection, otherwise a scripted mo purge removes them with no prompt at all.
3. Pick a delete mode explicitly and say why in the PR. git status --porcelain does not report ignored files, so a gitignored .env or local database inside a worktree is gone for good under purge's permanent delete. I lean toward routing this one category through mole_delete in trash mode.

tests/purge.bats is the place for coverage. I would like to see each of the four guards rejecting on its own, plus the prune path.

[hhh2210]

@tw93 PR is up: #1289

One thing to know before you open it. 9779a3a9 landed just under five hours after your go-ahead here and says the opposite: "Git worktree staleness is not decidable; do not build a feature that claims it is." I only found it while rebasing. I left that line in AGENTS.md exactly as you wrote it rather than quietly editing it out, and argued against it in the PR body instead.

Short version. Reasons (2) and (4) name failure modes this implementation does not have: nothing looks at merge state or deleted remote branches, and the unpushed check uses the per-worktree HEAD --not --remotes form you name in that same sentence, so a detached HEAD is covered. Reason (1) is right, and prune here is bookkeeping that runs after the working directory is already gone, not the reclaim mechanism.

Reason (3) is the real one, and your own sentence names the fix: a whitelist check against MOLE_PURGE_TARGETS. That is now guard five. git status --porcelain --ignored lists every ignored entry and each one has to match a purge target by name, so a gitignored node_modules passes and a gitignored .env, db.sqlite or stray note keeps the whole worktree. On top of that this category alone routes through mole_delete in trash mode, per your constraint 3.

So it is five independently provable negatives rather than a positive verdict. I am not claiming staleness is decidable in general.

Your ~/.codex/worktrees change and this one are complementary rather than competing: yours reclaims the 78% that is artifacts, this reclaims the checkout content it cannot reach, and a listed worktree absorbs the artifacts inside it so the same bytes are never listed or counted twice. Your new purge_target_activity_still_safe recheck also applies to worktrees unchanged, so the git guards prove nothing happened in git and the recheck proves nothing happened on disk, and both have to agree.

All three constraints from your second comment are implemented with tests. If the rule still stands after you have read it, say so and I will re-cut this as the blockers-only column it permits.

[tw93]

@hhh2210 closing the loop here after PR #1289. The later safety rule stands: Mole will not delete whole git worktrees or label them safe to delete, because repository-local Git configuration can hide state and pruning can affect registrations the user did not select.

mo purge will stay limited to whitelisted, rebuildable artifacts inside worktrees. The separate script(1) stdin fix from the PR was retained on main in d4174ea, but whole-worktree removal is closed as not planned.