Nested worktree guarantees and git worktree prune's real blast radius

[blooop]

Question

What does git actually guarantee about nested worktrees, and what is git worktree prune's real blast radius?

The unit decision should rest on git's semantics rather than on what eight probes happened to show. Establish, against a real git and with the version noted (the reviewer measured on 2.51):

1. Nesting. What happens when a linked worktree is created inside another linked worktree? Where does its admin directory live, whose .git does its gitfile point at, and does the outer worktree's removal have any defined effect on the inner one? Is nesting a supported configuration at all, or merely one git does not refuse?
2. Prune's scope. git worktree prune is invoked per repository. Confirm precisely which registrations it drops and which it spares: the review established it skips locked on 2.51, but does it spare anything else, and is --expire relevant? Is there any way to prune one registration, which would collapse the T2 mismatch outright?
3. Removal from the host. With a registration whose path is a container path that does not resolve, what are the supported ways to drop just that registration without touching others? Is git worktree repair relevant, and what would it do to a container path?
4. Locks. What exactly does a lock protect against, which commands honour it, and what does git say a lock means about liveness? dl --prune cannot reclaim agent worktrees inside live workspaces' clones (104 GB measured) #426 Ask 2 treats a lock as sacred; confirm that matches git's own contract rather than the agent harness's convention.
5. Whether git worktree list --porcelain reports enough to distinguish registered and present, registered and absent, locked, and prunable without a second filesystem walk.

Findings onto a research/git-worktree-semantics branch, linked from this ticket. Facts and citations, not a design.

[blooop]

agent-decided (principle 1, no data loss): findings on
research/git-worktree-semantics,
in docs/research/git-worktree-semantics.md.
Facts, not a design. Measured on four gits, 2.30.2, 2.34.1, 2.43.0 and
2.51.1, and every probe gave the same answer on all four; the only version
difference that matters is that 2.30.2 prints no locked or prunable
annotations in --porcelain at all (they arrived in 2.31.0, -z in 2.36.0).
Quotes are from git-worktree.adoc and gitrepository-layout.adoc at tag
v2.51.1, plus builtin/worktree.c, worktree.c and t/t2400/t/t2401.

The one that changes the answer: there is a single-registration prune

git worktree prune takes no path argument and never has, and git's own test
asserts the refusal. But git worktree remove <recorded-path> drops exactly
one registration when the recorded path does not resolve -- which on a host is
every container-registered worktree. No --force needed, exit 0, no output,
nothing else touched. remove_worktree() validates with
WT_VALIDATE_WORKTREE_MISSING_OK, keeps the dirty check and the tree deletion
inside if (file_exists(wt->path)), and then runs delete_git_dir(wt->id)
unconditionally. git names it in its own error text: "use 'add -f' to override,
or 'prune' or 'remove' to clear".

Reproduced in devlaunch's exact shape -- one clone, three registrations rewritten
to /workspaces/... paths, one locked, one nested inside another, invoked the way
Git::about invokes:

$ git --git-dir=<clone>/.git --work-tree=<clone> \
      worktree remove /workspaces/clone/.claude/worktrees/agent-a
                                                     # exit 0, no output
$ ls <clone>/.git/worktrees
agent-b  nested
$ git ... worktree remove /workspaces/clone/.claude/worktrees/agent-b
fatal: cannot remove a locked working tree, lock reason: claude session
use 'remove -f -f' to override or unlock first       # exit 128

And it fails towards keeping in every direction that matters. A recorded path that
does resolve on the host to somebody else's directory is refused, and -f -f
does not get past it (fatal: validation failed, cannot remove working tree: '<path>/.git' does not exist; the file in that directory survives). An ambiguous
identifier is refused rather than resolved. Branches survive. So this collapses
T2 outright: the prune gate exists to work around a constraint that is not
there, and Git::worktree_prune's doc comment ("git offers no way to drop one
registration and keep another") is false as written.

T2 is also worse than a race, and no gate closes it

git worktree prune's domain is readdir over $GIT_DIR/worktrees, not the
listing. Three registration states are pruned and never appear in
git worktree list --porcelain at all: gitdir file missing, empty, or
unreadable. Verified. A sweep that re-read the listing an instant before pruning
would still gate the prune with a set that cannot contain them.

And prune has an arm that deregisters a live, present worktree: two
registrations recording one path, or one recording the main worktree's path, are
dropped as duplicate entry, with no --expire gate and no path check. Locking
either one removes it from the comparison, so the duplicate then survives. There
is also gitdir file does not exist, which prunes a registration whose working
tree is alive and which --expire does not gate.

--expire is relevant but only to one arm (gitdir file points to non-existent location), and its clock is worktrees/<id>/index, not the gitdir mtime that
gitrepository-layout names. Practical consequence: git gc calls
git worktree prune --expire with gc.worktreePruneExpire, three months by
default, so any git gc in a container is a third party that drops
registrations. Registrations vanishing between two dl runs without dl doing
it is supported behaviour.

Nesting: T1 confirmed, and the guard that seemed to hold does not

A nested worktree's admin directory is a sibling of its parent's, flat under
the main repository, named from the basename; its .git gitfile points at the
main repository; commondir is ../.. at any depth. Nothing anywhere records
that one worktree is inside another. The relation exists only as a prefix
relation between two recorded paths.

Nesting is tested and undocumented -- neither of the two options the ticket
offered. t2400's '"add" from a linked checkout' and t2401's
'not prune proper worktrees inside linked worktree with relative paths' both
create one; the phrase "nested worktree" appears nowhere in git's docs or source,
and check_candidate_path() has no containment or depth test. So creating one is
meant to work, and what an outer removal means for an inner one has never been
stated, because git does not model the relation.

What removal does, all four versions, exit 0, silent:

probe	result
remove ../outer, nested inner untracked	refuses: contains modified or untracked files
remove ../outer, nested inner gitignored by outer	succeeds, inner's tree deleted, no output
remove --force ../outer	succeeds, inner's tree deleted, no output
remove --force ../outer, inner worktree locked	succeeds, inner's tree deleted, no output

Row 2 is the one worth stopping on: the untracked-files check is not a guard.
Ignore the nested directory in the parent, which is the ordinary arrangement for
an agent worktree directory, and plain git worktree remove with no flag
typed destroys the nested worktree. A lock is not inherited and does not
radiate: it is honoured only by the subcommands that name the locked worktree,
and deleting something that contains it never names it. Cross-repository nesting
is worse again: r1 cannot see r2's registration, so no prune in r1 will ever
clean it.

Removal from the host, and locks

git worktree repair is not relevant and cannot be made to be. Its source
carries /* missing worktree can't be repaired */, and it reads the registration
id out of a .git file at the path you hand it, so it can never be told
"registration <id> now lives elsewhere". With a container-path registration it
is a no-op with no arguments and refuses with the path as an argument
(error: not a valid path, exit 1 on 2.51.1/2.43.0; fatal: Invalid path, exit
128 on 2.34.1/2.30.2). It never deletes a registration, in any invocation.
git worktree move fails the same validation. add -f <stale path> and a
move destination do drop one stale entry, both documented, but each creates
something in its place; remove is the one that only removes.

On locks: git documents a lock as "this worktree may be on a portable device or
network share which is not always mounted" and nothing else. It blocks prune
(unconditionally, no override), remove and move, is reported by list, and is
consulted by no other git command. Git never says a lock implies the worktree is
live or in use. If anything its wording says the opposite of staleness: a lock
means an unresolvable path is not evidence the registration is garbage, which is
the host's situation for every container-registered worktree. So #426's Ask 2 is
devlaunch honouring the agent harness's convention, and the sharpening comment's
"locked is not the same question as in use" is exactly right. Nothing in git
argues either way.

Sub-question 5: --porcelain alone is not enough

Three ways. locked masks prunable -- the lock check precedes every path
check in should_prune_worktree(), so a locked-and-absent record is
byte-identical to a locked-and-present one. Three states are pruned and never
listed. And prunable is a claim about whether <path>/.git exists as a
filesystem entry, so a directory holding gigabytes with no .git reads
prunable, while a path whose .git is an unrelated repository reads clean. HEAD
and branch are printed for absent worktrees too (they come from the admin area),
so they are not evidence of presence. A second filesystem look is unavoidable.

What this leaves for #445

• The unit cannot be "the clone": a per-registration removal exists, honours
  locks, refuses on collisions, and works on container paths.
• The unit cannot be "a directory the plan enumerated": prune reaches states no
  listing shows, and a registration and a directory are independent things.
• Nesting is not a unit git has. Derive it from path containment; expect nested
  registrations to be order-independent siblings; expect a nested worktree of a
  different repository to be invisible here.
• Nothing git offers makes a nested worktree safe from its parent's removal, so
  the conjunctive parent decision T1 proposed is the only source of that
  guarantee.
• Two claims in the tree go with the fix: Git::worktree_prune's doc comment,
  and docs/cleanup.md:283-286's argument for excluding nested worktrees from a
  parent's dirty check.

[blooop]

breadcrumb: record repair, findings unchanged. The link this ticket was closed with pointed at a branch that did not carry the file.

Two research runs were in flight at once and collided: the findings commit (179d388, "Establish what git guarantees about nested worktrees and prune") landed on research/devpod-image-record, while research/git-worktree-semantics was left pointing at 9b6180b4 — which is PR #442's head SHA and contains no findings at all.

Nothing was lost. docs/research/git-worktree-semantics.md is now on research/git-worktree-semantics at eeec584, cherry-picked onto main so it stands alone, and the 829 lines are byte-identical to what was reviewed. The stray value was safe to repoint because that commit is still the head of the PR branch that owns it.

Worth noting for the map: this is the second time in this effort that a pointer was wrong while the content was fine. The findings themselves are unaffected and the decision indexed on #444 still stands.