What --prune should do inside a container, where recorded paths resolve

[blooop]

Question

What should --prune do when it runs inside a container, where every recorded worktree path resolves?

Raised by the keystone decision on #445, and it goes first among the fog it raised because it is a principle 1 question with a live hazard behind it.

The whole host-side design rests on an asymmetry: a registered agent worktree carries a container path like /workspaces/<id>/.claude/worktrees/agent-abc, which does not resolve on the host. That is what makes git worktree remove <recorded path> a pure metadata operation there: git skips the dirty check and the tree deletion because file_exists(wt->path) is false, and drops only the registration.

Inside a container that path does resolve. So the same call:

• deletes a working tree, not just a registration, and
• does apply git's dirty check, which is a different safety profile rather than simply a worse one.

The two radii the keystone separated collapse into one.

And the hazard as it stands: the keystone's note says the only thing currently stopping a container from collecting its own live agent worktrees is the Held arm of the classification, which is an accident of the classification rather than a decision. Something that prevents data loss by accident is not a safety property, it is a coincidence with a good outcome so far.

Note that running dl inside a container is a supported thing here, not a hypothetical: CLAUDE.md documents pixi run dl as the in-container build, and aid opens nested workspaces (see #327).

Candidates to weigh, at least:

1. Refuse. --prune is a host maintenance command; detect the container and decline with a reason. Simplest, and principle 1's default. Establish how a container is detected without a guess.
2. Run, with the container's own semantics acknowledged — every removal is a real tree deletion, so the whole safety predicate applies to every candidate rather than only to the ones with host directories.
3. Scope it out — prune only what is not the container's own workspace. Weigh whether that distinction can be drawn soundly from inside.

Whatever wins must make the current accident into a stated property, and the answer feeds a row of the contract table on #455.

How the answer gets tested: a test that pins the in-container behaviour explicitly, so the property stops depending on which arm a classification happens to take.

[blooop]

agent-decided (principle 1, no data loss): --prune does the same thing inside a container that it does on a host, with no environment detection, no refusal, and no new flag. Candidate 2, and the reason is not tolerance for the container's semantics: it is that "where the pass runs" is not a variable in this design, and the thing the ticket calls an asymmetry between host and container is a consequence of R1 rather than a fact about hosts. The accident becomes a stated property with two clauses and a test, and #454 ships no interim refusal.

This is the rare row where principles 1 and 2 point the same way, so the map's tie-break never had to be used. Refusing buys no safety, and costs the only reclaim path a nested workspace's clones have.

Everything below was measured from inside a real devlaunch devcontainer (the one this run is in: git 2.51.1, /proc/1/comm = devpod, workspace bind-mounted from the host's ~/.cache/devlaunch/repos/...). Scripts were throwaway; nothing was written to the repo.

1. The premise is false, and the measurement is two lines

The ticket, and #446 §5(c), both rest on: inside a container the recorded paths resolve, so the only thing stopping a container from collecting its own live agent worktrees is the Held arm. Held is indeed an accident. But it is not the cover, and it never was.

$ pixi run dl --prune                 # inside this container, shipped code
Clone directories under /home/vscode/.cache/devlaunch/repos:

Nothing to prune.

The container's own workspace clone is at /workspaces/<id>. Its cache_dir is /home/vscode/.cache, and devlaunch/ does not exist under it. Held is downstream of enumeration and never runs, because the domain is empty. The clone the container is in is not in the domain, and cannot be, for a structural reason:

$ findmnt
/workspaces/devlaunch-…-zeletofi   /dev/nvme0n1p2[/home/ags/.cache/devlaunch/repos/blooop/devlaunch/devlaunch-…-twmm]

dl bind-mounts the clone directory alone, at a path outside the container's own cache, with the sibling .bare unmounted — which docs/cleanup.md:672-674 already documents, for the unrelated reason that an lfs.storage entry naming a host path would break every checkout inside the container. That sentence turns out to be load-bearing for this ticket too.

2. The property, stated. Two clauses, and they are already decided

P1, locality. --prune's domain is enumerated from cache_dir and from nothing else (R1), and devlaunch never mounts a cache_dir clone into a container at a path inside that container's cache_dir: it mounts the clone alone at /workspaces/<id>. Therefore every worktree registration in an enumerated clone was recorded in a different filesystem namespace, exactly one level in from the namespace enumerating it. Non-resolution of recorded paths is a consequence of the enumeration root, not a property of hosts.

It is also self-similar, which is what makes it a property rather than a happy accident about level 0. Run aid inside a container (#327) and the clones it makes land in that container's cache_dir; their agent worktrees are registered by the container one level further in, at /workspaces/<id2>, which does not resolve where the enumeration is happening. The asymmetry regenerates at every depth. There is no depth at which a --prune reaches its own live agent worktrees.

P2, ordering. From #445: carrying out takes the Collectable by value, removes the directory first, then forgets every name that rode in on it, and forgets nothing on a partial removal. So at the moment git worktree remove <recorded> runs, the recorded path does not resolve even where it resolved a moment earlier. Measured, in the container, at depth 2, on paths that resolved:

$ rm -rf clone/.claude/worktrees/agent-o          # the byte operation
$ git worktree remove <resolving path of nested>  # fatal: cannot remove a locked working tree   (128)
$ git worktree remove <resolving path of agent-o> # exit 0, no output; branches main/outer/inner all alive

The two radii do not collapse. They cannot: the byte-deleting operation is remove_tree_as_far_as_it_goes(<the discovered directory>) and the metadata operation is a pure metadata operation by construction of the order, wherever it runs. The ticket's "the same call deletes a working tree and applies git's dirty check" is true only of a forget invoked without a completed removal, which #445 already forbids and which #454 must not reintroduce.

3. The container gets no free safety net, and this is the important half

It would be comfortable to say "in a container git's dirty check is a second layer". It is not a layer. Measured on resolving paths, all exit 0, all silent, all without --force:

what the worktree held	git worktree remove <resolving path>
clean tree, unpushed commit on a branch	deleted, exit 0. Branch survives in the shared store, so no loss, but git asked nothing
clean tree, unpushed commit, detached HEAD	deleted, exit 0, no output. The commit went from reachable by rev-list --all to reachable by nothing. git cat-file -t still says commit; the next gc takes it
nothing but gitignored content (junk/, stand-in for .pixi/envs/default)	deleted, exit 0. status --porcelain was empty, so the dirty check had nothing to object to
tracked modification or untracked file	refused: contains modified or untracked files, use --force to delete it (128). --force deletes it

Row 2 and row 3 are the point. Git's check is Q2 only, it never asks Q3, and it is blind to exactly the bytes this map is about: the gitignored .pixi/envs/default copies that are 18 of 72 directories and the reason #426 measured 104.5 GB and not ~10. #446's predicate is the entirety of the protection in a container, exactly as it is on a host. Nothing may lean on git refusing — the sentence #446 wrote for the host case is unchanged in a container, for different reasons.

4. What git does contribute: it fails safe on the cross-namespace collision, unforceably

The one case where a forget could reach bytes the plan did not name is a recorded path that resolves to a worktree of some other clone — which is the shape a container-id collision produces. Measured: a registration in clone pruned recorded at a live worktree of clone victim, holding uncommitted LIVE.txt:

$ git --git-dir=pruned/.git worktree remove <victim's live worktree>
fatal: '<…>' is not a working tree        # 128
$ git --git-dir=pruned/.git worktree remove -f -f <same>
fatal: '<…>' is not a working tree        # 128 — -f -f does not get past it
$ cat <victim>/LIVE.txt
victim live work

The victim's registration is intact, its uncommitted work is intact, and -f -f cannot force it. Note also that pruned's listing calls that registration prunable, so the clone-wide git worktree prune would have dropped it — one more reason #445 was right to delete that operation rather than gate it.

And one boundary case that makes P2 non-obvious, so it is worth writing down. git worktree remove <path> resolves by path, not by registration identity. Point registration agent-a's gitdir at agent-b's live directory in the same clone and ask to remove agent-a's recorded path:

$ git worktree remove <agent-a's recorded path, = agent-b's tree>
fatal: '…/agent-b' contains modified or untracked files, use --force to delete it
$ git worktree remove -f -f <same>
$ ls .git/worktrees        # agent-a   <- agent-b's registration went, agent-a's stayed

It removed the wrong registration and, with -f -f, the wrong bytes. Git honoured agent-b's lock when agent-b was locked, so the protection follows the resolved tree rather than the named registration — which is the right direction, but it means "remove <recorded> drops exactly one registration" needs the qualifier the one that lives at that path.

That is only ever the same registration because the join derives the site from the recorded path's suffix (#446: the recorded path is used for the join key and for the argument to remove, and for nothing else). So the forget's argument and the removal's target are the same string by construction. Break that correspondence and the recorded path is naming another namespace's clone, which is §4's refusal. This is the seam P2 stands on, and #454 has to keep the two uses of the recorded path tied together rather than merely adjacent.

5. Container detection: how it could be sound, and why nothing should need it

Established rather than reasoned, because the ticket asked.

• /usr/local/bin/devpod — unsound, per CLAUDE.md: injected on the devpod route, absent on the VS Code / devcontainer up route.
• DEVPOD=true, DEVPOD_WORKSPACE_ID, REMOTE_CONTAINERS=true — all present in this container, all devpod's or VS Code's, all route-dependent in exactly the way the devpod binary is.
• /.dockerenv present, /run/.containerenv absent, /proc/1/cgroup = 0::/init, /proc/1/comm = devpod. Docker-driver-specific, and a guess.
• The container's hostname is the workspace id — but provision.rs:1024-1026 sets it with sudo hostname, which needs CAP_SYS_ADMIN, and HOSTNAME_STAGE exists precisely to report that it failed. Best-effort, so not a detector.
• What devlaunch actually controls, and the near miss. launch.rs:118 defines DEVLAUNCH_WORKSPACE_ID and launch.rs:828-831 injects it — via --init-env, which reaches devpod's host-side initializeCommand and nothing else. Confirmed by measurement: env | grep -i devlaunch inside this container returns no DEVLAUNCH_* at all. So devlaunch owns the value and does not deliver it inward. A sound detector is one --workspace-env away, and this ticket deliberately does not ask for it.

And the distinction candidate 3 needs is unavailable and unnecessary. Unavailable: identifying "my own workspace" from inside means trusting devpod's route-dependent variable or a best-effort hostname. Unnecessary: P1 already excludes the running namespace's own clone from the domain, without naming it, so there is nothing for candidate 3 to scope out.

6. Why refusing loses, including on the clause that was supposed to favour it

The ticket says principle 3's simplicity clause favours refusing. Measured, it does not, and the inversion is the crux.

• Refusing is not free: it costs an environment predicate that does not exist and cannot be built soundly today (§5). R1's exclusion, by contrast, is the same rule everywhere and has no detector to be wrong. One rule beats one rule plus a branch.
• The detector's failure mode is on the deleting side. Answer "host" while in a container and you are back to the unguarded behaviour, and the stated property is now a lie — strictly worse than an accident, because someone is relying on it. Principle 1 says fail towards keeping; a proxy that fails open is the wrong shape for a principle-1 guard.
• It forfeits reclaim for no safety. aid inside a container (#327) puts clones in that container's cache_dir. Those are the straggler class principle 2 names, sitting on a docker volume, and --prune in there is their only reclaim path short of deleting the whole outer workspace. Refusing trades a principle 2 loss for a principle 1 gain of zero.
• It breaks nothing today, and that cuts both ways. Nothing in this repo's workflow runs --prune inside a container: no invocation in .github/workflows/, pyproject.toml, test/, dev.sh, scripts/ or .devcontainer/, and every executed --prune/--purge (rust/dl/tests/lifecycle.rs, lock_wait.rs) runs on a bare ubuntu-latest runner. So the documented in-container flow this ticket worried about breaking is not exercised. But it is also invited: CLAUDE.md says to run pixi run dl inside and excludes nothing, and no document anywhere claims --prune is host-only (grep: no "host-only", "only on the host", "runs on the host"). Refusing would be devlaunch's first host/container behavioural split, and every reclaim path on this map would inherit two behaviours and two contract-table rows.
• Maintainability, concretely. The in-container path has zero coverage on every CI leg, and the unit tests that stand in for it (agent_worktrees/tests.rs, lifecycle.rs:6961,6978) string-replace clone paths with /workspaces/a-container — that is, they encode non-resolution as an assumption. A refusal would leave that gap permanent by making it unreachable. Candidate 2 closes it, because it makes the resolving case a case worth testing.

7. The type this refuses to add

Ran /constructive-modeling on the one type the losing candidates want: Environment { Host, Container }, threaded through the pass.

It is the plan-wide boolean shape one level over — the map's own second precedent, the force field PrunePlan deleted. A run-wide tag decides, at a distance, what every per-site operation may do, and nothing at the call site can check the tag against reality. The fact it is a proxy for is local and git already answers it definitively: does this path resolve, here, to a worktree of this clone. §4 measured that answer, including that -f -f cannot argue with it.

It also fails the skill's restraint test outright: under P2 nothing panics, nothing needs an apology, and there is no "this shouldn't happen" for the tag to remove. Adding it would be strengthening a type where nothing was weak, at the price of a value that can be wrong in the deleting direction. No type moves. #446's Verdict and #445's Site/Collectable stand unmodified, which is also the composition test #446 §9 set for this ticket, passed.

8. What #454 must do

No interim refusal, and no detector. #446 §5(c) and #454's second breadcrumb ask for a stated in-container refusal in Held's place. That is withdrawn: the premise was false (§1), and what goes in Held's place is a statement and a test, not a guard. Net effect on #454 is a small subtraction.

1. Delete Held as decided (agent_worktrees.rs:335, and its one decision site at agent_worktrees.rs:639), and delete the claim it carries. agent_worktrees.rs:37-40 ("this is the arm that stops a run inside a container … from collecting its own live worktrees") and its mirror at docs/cleanup.md:277-279 are a fourth and fifth false claim to correct, alongside the three already named (clients/git.rs:513-515, agent_worktrees.rs:64-66, docs/cleanup.md:283-286). Replace with P1 and P2 as module prose, stating that the container case is covered by the enumeration root and the carry-out order, and not by anything git does.
2. The test the ticket asks for: pin the resolving case. Today's tests encode non-resolution (/workspaces/a-container). Add the opposite: a clone inside the enumerated cache whose registrations record paths that do resolve, to real worktrees of that clone. Three assertions, and none of them may be satisfied by a classification arm:
   • a site holding uncommitted or gitignored-only content stands, and nothing is removed (§3 rows 3 and 4 are why gitignored-only must be its own case);
   • a site whose predicate answers clean-and-elsewhere is collected, and the forget's argument does not exist at the moment the forget is invoked — that is P2 asserted directly, and it is the assertion that replaces Held;
   • a registration whose recorded path resolves into another clone is refused by git, and devlaunch forgets nothing else as a result (§4).
3. Pin P1 itself, which is the accident-turned-property: the pass's enumerated domain never contains the clone the process is running inside. That is an absence, in the shape this map keeps asking for, and it is cheap — the domain is a list of paths and the running clone is a path.
4. Promote #446's suffix-join fog from "a test, not a ticket" to a required test. #446 says it fails safe today because the borrowed index reports the whole directory as changed, so Q2 objects. §4 shows that in the resolving case the consequence of it not failing safe is a wrong-target deletion rather than a wrong report — and two agent worktrees cut from the same commit with no edits yet is a clean Q2. The test must assert the join derivation (the site comes from the recorded path's suffix, so the forget's argument and the removal's target are one string), not the borrowed index's dirt.
5. Keep the recorded path whole. Research finding 4: the argument must be the value copied out of the listing, never assembled. §4 is why the two uses of that value have to stay tied.

9. For #455's contract table

One row, and one clarification.

• The clone the process is running inside — reclaimed by: nothing, from inside. It is not under cache_dir, it is never enumerated, and that is by construction rather than by exclusion (P1). Its reclaim path is the host's dl <ws> rm / --purge. Not a straggler: it is a live workspace's checkout.
• Clarification for the "what proves removal safe" column: git contributes exactly one safety fact and it should not be overstated. It refuses, unforceably, when a recorded path resolves into a clone that is not the one being pruned. It contributes nothing otherwise: measured, it deletes a detached worktree's only-copy commit and a worktree whose entire content is gitignored, both exit 0 and silent.

10. Fog

• DEVLAUNCH_WORKSPACE_ID reaches the host hook and not the container (§5). It is one --workspace-env from being the only sound self-identification devlaunch owns, and nothing on this map needs it now — this decision exists partly to establish that. Worth a ticket if any later surface wants "am I inside a workspace, and which", because the alternative every time is devpod's route-dependent variable.
• The sibling .bare is not mounted into the container, so #446's Q3 would fall back to the clone alone if it ever ran against a clone reached from inside. It never does, under P1. If P1 is ever weakened, Q3's answer quality changes with it, and that link should be written down before anyone weakens it.