Does --purge need an unsaved-work check

[blooop]

Question

--purge applies no unsaved-work check to devlaunch's own clones, while rm and --prune both do. Is that right?

Raised by #452 and promoted to its own ticket because it is a principle 1 question, and principle 1 outranks everything else on this map.

The asymmetry, stated plainly. dl <ws> rm refuses a clone that holds work existing nowhere else. --prune weighs the same question per clone and keeps what it cannot prove safe. --purge removes the whole cache after one confirmation, and the only thing standing between a user and work that exists nowhere else is that they typed y. So the contract table's "what proves removal safe" column reads, for that row, the confirmation, and nothing else.

Two readings, and this ticket picks one:

1. It is correct as it stands. A purge is a stated intent to remove everything, the prompt names what goes, and a command whose whole purpose is "remove all devlaunch data" is entitled to take the user at their word. Adding a check makes the destructive-by-request command harder to complete than the routine one, and a purge that refuses is a purge that gets -y'd reflexively, which is worse.
2. It is an inconsistency principle 1 does not permit. The other two paths encode "work that exists nowhere else is different from disk", and a purge that does not is a hole in exactly the property the rest of the map is being built around. A count in the prompt ("3 clones hold work that exists nowhere else") costs the user nothing and changes what they are agreeing to.

Note that these are not symmetric in cost. Reading 2's minimum version is a report, not a refusal: it does not make the purge harder, only better informed, and --prune already computes exactly this. Weigh whether the cheap version is so cheap that reading 1's objection does not apply to it.

Also weigh: --purge already names what it is leaving before it asks. A command that has room to list foreign workspaces it will not touch has room to say how many of its own clones hold unpushed work.

How the answer gets tested: whichever way it goes, a test pins the prompt's content for a cache containing one clone with unpushed work, so the answer is asserted rather than assumed. If the verdict is "correct as it stands", that test still documents it.

[blooop]

agent-decided (principle 1, no data loss): reading 2, at its minimum, and not as this ticket frames it. --purge gets a figure in its prompt for what the tree it is about to remove holds that exists nowhere else. It does not get a refusal. And the figure is blocked on a defect this ticket surfaced by accident, which is larger than the asymmetry the ticket is about: the clone-level unsaved probe that dl <ws> rm and --prune's orphan arm both rely on is structurally blind to the agent worktrees nested inside a clone, so those two paths have a check that lies where --purge merely has none. Fix that first; a count that can read zero over a dirty worktree tree is worse than no count.

1. What principle 1 asks of a purge, and the one clause that has no move here

Principle 1 has two clauses and they land differently on this command.

"Work that exists nowhere else is never removed without an explicit human answer." --purge has the explicit answer: a plan, then Are you sure? [y/N]. What is missing is not consent, it is that the consent is about disk. The prompt says "4 DevPod workspace(s)" and "<cache>/ (workspace clones, repo caches, the shared pixi cache, completions)". rm and --prune both name the work per directory; this one names megabytes. So the clause is met literally and not in substance, and that gap is a reporting gap.

"Where a check cannot prove safety, fail towards keeping." This clause has no expressible action on --purge, and that is the real reason the asymmetry exists rather than being an oversight. rm acts on one workspace and --prune acts on one clone at a time, so "keep this one" is a complete answer for both, and it is what Guarded::Refused and KeptBecause::Objected say. --purge is one indivisible act on one root: the only "keep" it can express is do not purge, and a partial purge is already its documented failure mode (PurgeOutcome::RemovedWhatItCould, exit 1, "a clone you were told would go is still on disk"). There is nothing for a per-item keep to be.

So principle 1 does not license a refusal here. It licenses making the answer an informed one.

2. A refusal is refused, and the -y question answers itself

The ticket asks whether refusal-with--y-override differs meaningfully from a report. It differs, and in the wrong direction, on three counts.

• --purge --force is a grammar error today (rust/dl/src/cli.rs:1346, GrammarError::ModifierNotAllowed { modifier: "--force", command: "--purge" }). So the override would have to be -y, whose stated meaning is "answer yes to the confirmation --prune, --reconcile and --purge ask" (cli.rs:472). Making it also mean "destroy work that exists nowhere else" is one flag carrying two consents, which is the plan-wide-boolean shape PrunePlan deleted its force field to make inexpressible: "A plan-wide boolean says the user insisted about every directory in the plan, including the ones nothing objected to." A guard whose override is the flag that suppresses the prompt carrying the information is not a guard.
• -y is the scripted path. The e2e suite runs dl --purge (docs/development.md), and every automated caller passes -y because a purge that blocks on stdin is a hung job. So the refusal is null for the population that cannot read a warning and pure friction for the population that can, which is exactly reading 1's "a purge that refuses is a purge that gets -y'd reflexively".
• A refusal has nothing to offer. rm's refusal is useful because the user can go rescue that one clone and re-run. --purge's would be "one of your 37 clones is dirty, so you may not purge" and the only remedy is the flag that turns the whole check off.

Reading 1's objection therefore stands against a refusal in full. It does not survive against a report: a report adds no step, changes no exit code, and is the thing that turns a y about disk into a y about work. The precedent the ticket points at is exact and it decides this: the "Leaving N workspace(s)" block exists because "a user who asked for a clean slate and gets survivors should learn it while saying no is still an option" (PurgePlan's doc comment). A count of clones holding unpushed work is the same claim with a much higher cost of being wrong.

3. The premise to correct: --prune does not already compute this figure

The ticket says "--prune already computes exactly this". It does not, and the difference is the whole of the work.

--prune computes the unsaved answer for the clones it is removing — clone_status reaches holds_unsaved_work only on the CloneStatus::Orphaned arm, deliberately, because "asking them about a directory no answer could affect is time spent to learn nothing" (flows/lifecycle.rs:1877). It never weighs a referenced clone. Separately it sweeps the agent worktrees inside the clones it is keeping, and deliberately does not descend into ones it removes, because "a directory that is going takes everything inside it" (flows/agent_worktrees.rs, "Nesting").

--purge removes cache_dir whole. Its set is every clone under <cache>/repos, referenced and orphaned alike, and every agent worktree nested inside every one of them. That is precisely the union of the two populations each existing sweep excludes. Neither existing figure is purge's figure, and the intersection of the two is nearly empty.

Two more things follow, and both are R1 questions:

• The figure must be enumerated from cache_dir, not from repos_dir. Reusing prune_plan would take WorkspaceCloneManager::repos_dir() as its root, and Clones outside repos_dir and dl path or url workspaces #452 established those are two roots: a config.toml moves repos_dir and does not move cache_dir. Under such a config --purge removes a cache containing no clones at all, and a repos_dir-rooted count would report work at risk that the purge is not touching. Enumerate <cache_dir>/repos, per R1.
• A count over ownership.mine is the tempting cheap version and it is wrong. purge_plan already has that set in hand and listing::unsaved_work_in is the reader, so it looks like a two-line change. But ownership.mine is workspaces, and it reaches a clone only through a metadata.json record (unsaved_work_in returns NothingToLose for a workspace with no record). Orphan clones have no live workspace and are invisible to it, and --purge deletes them. On the reference host that population is non-empty by construction: 49 records, 37 clones, 39 workspaces.

4. The measurement that actually decides this ticket

Before writing any count I checked what the existing probe can see, because a figure that under-reports is a false assurance and the map's recurring defect shape is a pass reasoning over an enumeration that does not cover what it affects. It under-reports badly.

holds_unsaved_work on a clone is git status --porcelain plus git log --oneline <branch> --not --remotes, both with the repository pinned. Reproduced on real git, in a clone whose .claude/worktrees/agent-task/ holds one uncommitted file and one commit that no remote has:

$ git --git-dir=clone1/.git --work-tree=clone1 status --porcelain
                                    # empty
$ git --git-dir=clone1/.git --work-tree=clone1 log --oneline main --not --remotes
                                    # empty
$ git --git-dir=clone1/.git log --oneline --all --not --remotes
69b2536 work nowhere else           # the commit is there; the probe does not name --all

Both halves are blind, for two independent reasons. The status is blind because the harness directory is gitignored — .gitignore:188, .claude/worktrees/, in this very repository, and it is scratch nobody commits so it is ignored wherever the harness runs. The unpushed probe is blind because it names the parent's checked-out branch rather than --all, and a nested worktree's branch tip is not reachable from it. With the ignore removed the status does fire, as ?? .claude/, which is the right answer for the wrong reason and is the only thing masking this today.

So on the reference host, a clone-level count would have printed "0 clones hold work that exists nowhere else" across 72 agent worktrees and 104.5 GB, every one of them inside a clone belonging to a live workspace (devlaunch#426). That is not a weak report, it is a lie in the direction of deleting, and it is worse than the silence it replaces: silence leaves the user's own knowledge intact, a zero overwrites it.

And the same blindness is a live hole in the two paths this ticket holds up as the good examples, where principle 1's "fail towards keeping" does have a move.

• dl <ws> rm on a workspace whose clone is clean and whose agent worktree holds an afternoon deletes it with no refusal and no --force. The guard's entire promise is "it refuses a clone that holds work existing nowhere else", and for the largest at-risk population on the measured host it does not.
• --prune removing an orphan clone does the same. Its recursion rule is stated as an argument about bytes and it is correct about bytes: descending into a directory that is going would double-count. It is silently also a decision about safety, and there it is wrong, because the parent's Unsaved does not cover what is nested in it.

That reorders the ticket. --purge lacks a check on a population that is at least reported elsewhere. rm and --prune have checks that are blind to the population that is, by nature, likeliest to hold uncommitted work: agent working directories mid-task. Principle 1 says fix the checks that lie before adding one where the absence is at least stated.

5. Whether the report can wedge the command

Tested, because "it is only a report" stops being true if it can. It survives on one axis and fails on the other.

The git probes are the cheap half, and a count needs only that half. They are local reads with no network, no docker and no devpod; each is bounded at 30s (ABOUT_ONE_REPO, clients/git.rs:70) and a timeout arrives as GitAnswer::Refused, which is a CouldNotTell line rather than a hang. The figure the code already records for this work is 593 ms of git over 37 clones (lifecycle.rs:1878). The worktree sweep adds roughly two git calls per worktree, so ~72 more on the reference host: a few hundred bounded local git invocations, single-digit seconds. Crucially the unbounded half of a prune scan is disk_usage::exclusive_usage, "O(files) with no ceiling" — and a count does not need bytes. So the expensive half stays out by construction.

The lock is where it can wedge, and it must not take one. prune_plan takes hold_repo_lock per repository, and that is an unbounded blocking acquisition (locks::hold_lock_watching waits until free; the command layer prints dl: waiting for another dl run preparing <owner>/<repo> precisely because it can sit there). purge_all_data takes no lock at all today — devpod delete --force per workspace, then remove_tree_as_far_as_it_goes(cache_dir). A locked report would therefore be stricter than the deletion it precedes, and could queue behind a sibling dl owner/repo doing a long clone while the purge that follows it would have raced that clone happily. Use run_if_lock_free — "the caller never queues for anyone" — and let a repository it could not weigh read as could-not-tell. TOCTOU here is unclosable from the host anyway (the map's own constraint), and the purge does not close it today.

Compute the figure unconditionally, including under -y: PurgePlan's rule is that the count the user approves and the set that dies come from the same object, and a field that exists only when interactive is a plan with a hole. It costs seconds on a command that then removes multiple gigabytes.

6. The type: not a count

Ran /constructive-modeling on this and it has one finding, at the catalogue's highest severity — two sentinels in one field.

A bare usize reads 0 for "nothing in the tree holds work that exists nowhere else" and for "dl could not weigh these", and, before the §4 fix, for "dl did not look inside the worktrees". That is devlaunch#171's shipped bug re-created one level up: nothing carried both "nothing would be lost" and "I could not find out", and the destructive caller read both as permission. Unsaved is a three-armed sum for exactly that reason and the aggregate must be one too.

So the figure on PurgePlan mirrors Unsaved's three arms at tree level rather than inventing a fourth vocabulary: nothing at risk / these hold work that exists nowhere else (a NonEmpty, carrying any unweighed directories alongside, so "some at risk and some unknown" cannot collapse to either alone) / nothing was found and these could not be weighed (also NonEmpty). Field private with one constructor, per PurgePlan's and PrunePlan's existing rule, so a partial walk cannot mint a value that reads nothing at risk. And no Option around it: an absent figure and a zero figure must not be the same value.

7. Build work, and where it belongs

Named rather than ticketed, per the ticket's framing. Three pieces, in this order, and the order is the decision.

• First, and it is not this ticket's line of output: give the clone-level guard the reach its promise claims. rm's refusal and --prune's orphan arm must account for the agent worktrees nested inside a clone before either is trusted again. Two candidate mechanisms, and What proves an agent worktree safe to remove, and what if it cannot be proved #446 owns the choice because it owns the worktree predicate: fold agent_worktrees' per-worktree reader into the clone's answer (right, and composes with What unit does the agent-worktree sweep reason about #445's bottom-up subtree unit), or widen the clone's unpushed probe to --all --not --remotes and drop the ignore blindness (cheaper, partial, and does not reach uncommitted dirt at all — §4 shows the status half is blind independently). This is the highest-consequence item on this ticket and it is not about --purge. It wants a comment on What proves an agent worktree safe to remove, and what if it cannot be proved #446 and a build ticket downstream of it, most naturally inside Rebuild the agent-worktree sweep on the decided unit #454's rebuild.
• Then the purge figure itself, folded into #461. Folding is right: Name the sources in --purge's leaving list #461 already edits the same golden (PURGE_PLAN, rust/dl/tests/lifecycle.rs:751) and the same paragraph of docs/cleanup.md under "What purge deletes", and a second pass over one golden for one line is waste. But Name the sources in --purge's leaving list #461 must gain a blocked-by on the reach fix, and its scope note must say the line is a walk over <cache_dir>/repos with run_if_lock_free, not a reuse of prune_plan. The abort golden's devpod_calls() == ["devpod list --output json"] assertion is unaffected: the walk asks devpod nothing.
• If the reach fix does not land, print no count and say so. Reading 1 then becomes the answer, stated rather than inherited: docs/cleanup.md says in as many words that for --purge the confirmation is the whole of what proves removal safe, and Write the reclaim contract into docs/cleanup.md #455's row reads that way with a reason beside it. A stated abstention is a decision; a silent one is the thing this map exists to stop.

How it is tested, either way, per the ticket's own requirement: a test pins the prompt for a cache holding one clone with unpushed work — and, because §4 is the finding, a second for a cache whose clone is clean and whose nested agent worktree is not. That second case is the one that fails today, in rm and --prune as well as in the prompt.

Fog

• The unpushed probe names one branch, everywhere. git log --oneline <branch> --not --remotes is the whole of dl's unpushed answer for a clone, so commits on any other local branch in that clone are invisible too, worktrees aside. A user who committed on wip, switched back to main and let dl delete the clone loses them, with NothingToLose printed. --all --not --remotes is one word and would also have caught §4's commit half. Not raised as work here because What proves an agent worktree safe to remove, and what if it cannot be proved #446 owns the predicate and should decide it once for both readers.
• --purge applies no unsaved check and takes no lock, and the second is load-bearing for the first. Whatever the figure ends up being, it is a snapshot taken outside every lock in a system where containers are not lock participants. It informs a decision; it must never be read as a proof.