fix: sweep extraction directories abandoned by a crash

[miharp]

Why

Came up while explaining download()'s temp-extraction cleanup: what actually happens to that temp directory if the agent process is killed mid-extraction, not just returns an error?

download()'s cleanup is a defer os.RemoveAll(tmp), which never runs on a hard kill — SIGKILL, an OOM kill, a power loss. Whatever partial extraction existed at that instant is left on disk. Traced every path that could plausibly clean it up afterward, and found none do:

• reap() explicitly skips anything dot-prefixed. That's deliberate, not an oversight — it has no way to tell a crash-abandoned extraction apart from one a concurrently running agent process is still actively writing into, and deleting a live one out from under it would be worse than leaking one.
• The next reconciliation doesn't help either. sync() only checks whether the final directory exists; if not, it calls download() again, which calls os.MkdirTemp again, generating a brand-new, differently-named temp directory each time. It has no awareness the old orphaned one exists.

So a crash mid-download left a permanent leak — one more directory, forever, per crash — until an operator noticed and removed it by hand.

Fix

Age is what actually distinguishes "abandoned" from "still live": a live extraction keeps creating entries under its directory, which keeps bumping that directory's own mtime; an abandoned one stops moving the instant the process dies.

reapStaleExtractions() sweeps a dot-prefixed directory once it has sat untouched past MinAge — reusing the same bound reap already uses elsewhere for "how long before we're sure nothing still needs this," rather than inventing a second, unconfigurable threshold. performance.md's fixture unpacks in well under a second, so even the 2-hour default leaves an enormous safety margin before this could ever mistake a live extraction for a dead one.

Called once per Once() cycle, fleet-wide rather than per-environment — an abandoned extraction isn't tied to converging any particular environment.

Test

TestReapRemovesAbandonedExtractionsPastMinAge: creates one dot-prefixed directory backdated 2 hours (simulating a crash) and one with a fresh mtime (simulating a live extraction, MinAge set to 1 hour), runs a reconciliation, and asserts the old one is gone and the fresh one survives.

Docs

Added an "Extractions abandoned by a crash" section to agent.md's Reaping, and a short note to production.md's disk-sizing math, which previously had no way to account for this.

Checks

go test -race ./... passes (full suite). gofmt -l . and go vet ./... clean. markdownlint-cli2 and cspell clean on both docs.

🤖 Generated with Claude Code