Clearing agent scratch checkouts
Agent scratch checkouts — the throwaway copies agents make to work in — are invisible to every other cleanup road, and on one computer they reached 131 GiB. Omniscio now finds them under one declared list of scratch folders, proves each one disposable four ways, and clears the proven ones by moving them into that drive's own trash, where the ordinary drain deletes them. Below: what is checked before anything moves, why the first version only reports, and the one seed folder that is never cleared.
On this page
Agents make throwaway copies of the repository to work in. They are not registered worktrees, so the
reaper, npm run worktree:maintain and the removal routes cannot see them — and the machine's own
guard refuses a plain delete of any folder holding .git. They simply accumulate.
Where it looks
One declared list of folder names — patch-scratch, AMC-PatchScratch, amc-patch-scratch,
AMC-Scratch, amc-fixer-scratch — on the same drives the worktree location rule already names. No
drive letter is hardcoded, so the list means the same thing on every computer. A bare tmp is not in
the list: it is too generic to prove safe by name.
One more shape is declared, because it is where background Dev Ops fixers put their clone:
AMC-Maintenance\fixer-<n>\repo on any drive. Only a folder named fixer-… directly inside
AMC-Maintenance counts — the backups, the journal and the other working folders in there are never
touched — and the whole fixer-… folder is the thing that gets cleared, once the single repository
inside it passes every proof.
What it checks before anything moves
Four independent proofs, one folder at a time. Every refusal is reported with its reason, never as a count:
- Every tip is safe. The folder's
HEADand every local branch tip resolve in the main repository. One missing commit disqualifies the whole folder and the report names the sha. - Nothing unsaved. The tree is clean and there are no stashes.
- Nothing is using it. No ledger row, no live session and no running process names the folder.
- It is idle. The folder, its
.gitand everything directly inside it are older than six hours.
A git error counts as a disqualification, never as a pass.
A whole clone sitting under AMC-Maintenance but not in a fixer-… holder is reclaimed by
node scripts/ops/reclaim-proven-clones.mjs, which proves every one of its branch and tag tips against the remote's
master as fetched from the remote a moment ago — a stale local remote-tracking ref proves nothing.
It writes a recovery record naming each ref with the master commit that holds it, and only a clone
that passes every proof is renamed into .trash. Its full behaviour and flags are documented under
"Agent scratch checkouts" in the worktree maintenance guide.
How much one pass does
One pass examines at most --max-folders folders (default 8), or until --budget-minutes runs out,
whichever comes first; every folder it did not reach is reported as deferred with the reason. Both
flags accept --flag value and --flag=value, and a flag the tool does not know is a refusal
rather than a silently ignored token, so a run never reports a cap it was not asked for.
The scheduled maintenance job passes its own --max-folders (60 unless its caller names another),
so a backlog of a hundred folders clears in two runs instead of seventeen.
When the work landed under a different commit
The first proof compares commits, so a clone whose work was merged in a rewritten form still has commits the main repository never saw — and it is kept, deliberately, because the tool cannot tell "already landed" from "unpushed work". If you have confirmed the work is on the remote, retire that one clone by name:
node scripts/ops/patch-scratch-reclaim.mjs --path "F:\AMC-Maintenance\fixer-17567" --verified-on-origin --apply
Only a fixer-… folder directly inside AMC-Maintenance is accepted, so this cannot be pointed at a
real checkout, and every other proof still applies.
What it does with a proven folder
It renames it into that scratch folder's own .trash, the same move the worktree retire path uses.
Nothing is destroyed by the sweep — the existing trash drain deletes it later, under every guard it
already has: the mass-delete lock, the bulk-drive pacing, and the frozen-drive rule. The report says
moved, never bytes freed, because only the drain frees space.
Emptying that trash now
The move frees nothing on its own. A proven folder is a same-volume rename into .trash, so the space
stays taken until the background drain deletes the entry — and on a busy computer that can be a long
wait, which reads as "the sweep moved 24 GB and freed nothing".
POST /worktrees/scratch-sweep/drain?repo=<repo> runs that drain immediately:
{ "container": "F:\\AMC-Scratch\\.trash" }
Name one container, or send no body at all to drain this repository's declared scratch roots' .trash.
A maintenance fixer's queue is drained the same way, by naming it: {"container":"F:\\AMC-Maintenance\\.trash"}.
It stops starting new folders after 25 seconds and gives one folder at most 60 seconds, so a folder
already under way can finish a little past that. It never runs beside the background drain (it takes
the same box-wide delete lock), and nothing new may be deleted: a folder whose name carries no retire
stamp is still refused, and the retention and preservation floors still apply.
The answer also tells you what the background drain will and will not cover, which is the question "does the schedule reach this scratch root at all":
targets— the containers it drained, anddeleted, how many entries went.refused— a container the background drainer does not cover. It is never touched, and it never frees space until it is fixed. An empty list means every declared scratch root's.trashis in the same set the scheduled drain deletes from.absent— a container that does not exist on this computer yet; there is nothing to drain.cleanupEnabled—falsemeans automatic worktree cleanup is switched off, so no pass deletes anything until it is turned back on in Settings → Performance.busy— another delete held the lock this time; try again in a moment.
The seed that is always kept
Every new scratch copy is cloned from an existing one, so each scratch folder keeps its newest
detached clone whose HEAD resolves in the main repo. It is reported kept:seed and never cleared.
A dead copy with no resolvable HEAD is not a seed and is cleared normally.
Why the first version only reports
The sweep ships in report mode. It tells you what it would clear and touches nothing. Switching it
to sweep is a deliberate act through POST /worktrees/scratch-sweep/mode, which requires a reason
and records who changed it and when. GET /worktrees/scratch-sweep reports the current mode and that
recorded reason.