source-control:worktree cleanup classifies by cleanliness, not liveness — a clean worktree with a rebase in flight is removed without --force, and the 'locked' flag it honors is never armed

[kyle-sexton]

Found by two lanes colliding on a live machine during the #2163/#2171 drain, then reproduced from first principles in a disposable repo.

The gap

plugins/source-control/skills/worktree/context/cleanup.md:23-27 classifies every removal candidate by Active / Stale / Stranded / Orphaned. Every input to that classification is a point-in-time property of the tree: last-commit age, open-PR presence, git status --porcelain, landed-work.sh risk, the locked flag.

None of them answers a different question: is an agent operating in this worktree right now?

That is not visible in git status, and a worktree can be perfectly clean while an operation is mid-flight.

Reproduced — a clean worktree with a rebase in progress, removed without --force

Disposable repo, interactive rebase stopped at a break so no conflict exists and the tree stays clean:

rebase in progress?   YES
status --porcelain: []
status long says:     interactive rebase in progress; onto ead523f
worktree remove without --force: <no error>
directory still exists? NO — DELETED

git status --porcelain is completely empty. The long form knows — interactive rebase in progress — but porcelain v1 does not report it, and git worktree remove does not consult it. Plain removal, no --force, deleted a worktree with an in-flight rebase and printed nothing.

For contrast, in the same probe git does refuse plain removal for staged changes and for untracked files alike:

case A: STAGED new file    -> fatal: '../wA' contains modified or untracked files, use --force to delete it
case B: UNTRACKED file     -> fatal: '../wB' contains modified or untracked files, use --force to delete it
case C: CLEAN worktree     -> removed

So git's own guard covers dirty trees and nothing else. The skill inherits exactly that blind spot.

Two live incidents

1. D:/worktrees/fix-babysit-g — swept while clean; the removal killed another lane's in-flight rebase. No commits lost (they were already pushed), but the operation died halfway and cost that lane real time.
2. D:/worktrees/rn2171 — one lane observed it at ~23:09Z holding another agent's staged work plus UU plugins/source-control/CHANGELOG.md. By ~23:30Z it was clean and I removed it. Nothing was lost, and plain removal proves the tree was clean — but the sweep had no way to know an agent had been live in there twenty minutes earlier. It was safe by timing, not by any guard.

The locked flag is read but never armed

cleanup.md:26 qualifies Stale with "no locked flag", and both cleanup.md:103 and create.md:63 correctly document that a locked worktree needs --force --force. So the classifier already has the right signal wired in.

But a repo-wide grep finds no git worktree lock invocation anywhere. The only hit is a comment in babysit-prs/scripts/prune_babysit_worktrees.py:373 describing that prune preserves an existing lock — nothing sets one.

The locked input is therefore structurally always absent: a guard the classifier reads and no lane ever arms.

Suggested direction

Not prescribing the design, but the mechanical parts are cheap and reliable:

1. Detect in-progress operations before removal. All are directory probes via git -C <path> rev-parse --git-path <name>: rebase-merge, rebase-apply, MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, BISECT_LOG. Any present means "an operation is mid-flight here" and the candidate is not disposable, whatever --porcelain says. This alone would have prevented incident 1.
2. Arm the lock. Have lanes that take a worktree run git worktree lock --reason "<lane> <pid> <started>" on entry and unlock on exit, so the locked input the classifier already honors carries real signal. A stale lock then becomes its own detectable condition (reason string with a dead PID) rather than the current state of no locks at all.
3. Say so in the classifier table. Add liveness as an explicit non-candidate row next to Stranded, which is already there precisely because it is "the row most easily mistaken for Stale".

Framing

The existing Stranded guard exists because old and quiet does not mean disposable. This is the same lesson one step further: clean does not mean idle. Cleanliness is a point-in-time property; "an agent is mid-operation here" is a liveness property, and the sweep currently measures only the first.

Related worktree-reaping issues, none of which cover liveness: #1776, #1774.

[kyle-sexton]

Skip — covered by open PR #2315 (feat/2257-worktree-liveness-lock, Closes #2257).

[kyle-sexton]

Correction: the locked flag is armed — by Claude Code, not by us

The liveness gap this issue reports is real and I am not disputing it. But one stated mechanism is
wrong, and a fix built on it would be built on a false premise.

"a repo-wide grep finds no git worktree lock invocation anywhere … The locked input is
therefore structurally always absent: a guard the classifier reads and no lane ever arms."

The grep is correct. The conclusion drawn from it is not. Claude Code locks the worktrees it
creates itself, with a reason string that already carries the PID this issue proposes adding.
Measured just now on Claude Code 2.1.228, in a throwaway repo:

$ cd <throwaway repo> && claude -p '…' --worktree probe0
$ git worktree list --porcelain
worktree …/repoA
HEAD afac7948a7c083d0f886ca40d327d3fc5ffde43c
branch refs/heads/main

worktree …/repoA/.claude/worktrees/probe0
HEAD afac7948a7c083d0f886ca40d327d3fc5ffde43c
branch refs/heads/worktree-probe0
locked claude session probe0 (pid 29884)

So the accurate statement is narrower and more useful:

Worktree origin	locked?
claude --worktree, subagent isolation: "worktree", background session	armed by the harness, reason claude session <name> (pid <pid>)
scripts/worktree-create.sh (this plugin — plain git worktree add)	never armed
a lane's own git worktree add	never armed

The locked input is therefore absent exactly for the worktrees this plugin creates, and present
for the ones the harness creates. That changes three things about the suggested direction:

1. Direction 2 ("arm the lock") is not a greenfield design. The harness already established a
   reason-string format carrying a PID. A lane-side lock should match that shape rather than
   invent a second one, or cleanup will need two parsers for the same field and the stale-lock
   detection this issue wants ("reason string with a dead PID") will only work on one of them.
2. The classifier is not reading a dead input. It is reading an input that is armed for one
   class of worktree and not another — which is worse in a specific way worth naming: a sweep that
   trusts locked is already safer against harness-created worktrees than against this plugin's
   own, and nothing in cleanup.md says so. The asymmetry is invisible at the classifier.
3. Incident 1's framing survives intact. D:/worktrees/fix-babysit-g was a lane-created
   worktree, so it genuinely had no lock; the rebase-in-flight probe in this issue is unaffected and
   remains the strongest evidence here. Direction 1 (probe rebase-merge, rebase-apply,
   MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, BISECT_LOG via
   git -C <path> rev-parse --git-path <name>) is untouched by this correction and is still the
   cheapest real fix.

Not implemented in this batch. Lane SC shipped #2309 (worktree-create gate) and has #2212/#2213
branch-ready; this row was not reached. Filing the correction now so whoever takes it does not start
from "no lane ever arms it" — the batch this came out of has a dominant defect class of a real
symptom paired with a false stated mechanism, and this is one.

_{Measured by wave-2 lane SC, handoff-inbox batch 4. Claude Code 2.1.228, Windows. Probe recorded at plugins/source-control/skills/worktree/fixtures/worktree-create-hook-probe.sh (arm 1) in #2309.}

[kyle-sexton]

Disposition: correction filed, implementation not taken — and this is the fourth filed rationale to die on re-verification this batch

Adding the pattern note to the correction above, because the pattern is the point.

Status. Lane SC shipped #2309 (source-control 0.52.0, merged) and #2349 (open). This row was not implemented. What is settled is that one of its stated mechanisms is false, and a fix built on it would have been built on a false premise.

Recap of the correction, in one line

locked is not "structurally always absent". The harness arms it, with a PID-bearing reason string — measured on Claude Code 2.1.228:

worktree …/repoA/.claude/worktrees/probe0
branch refs/heads/worktree-probe0
locked claude session probe0 (pid 29884)

It is absent only for the worktrees this plugin creates via plain git worktree add. The repo-wide grep in the issue body is correct; the inference drawn from it is not. Probe: plugins/source-control/skills/worktree/fixtures/worktree-create-hook-probe.sh (arm 1), shipped in #2309.

What survives untouched

• The liveness gap is real. Cleanliness is a point-in-time property; "an agent is mid-operation here" is a liveness property, and the classifier measures only the first. Nothing above weakens that.
• The rebase-in-flight reproduction stands. git status --porcelain is empty while an interactive rebase is stopped at a break, and git worktree remove deletes without --force and prints nothing. Incident 1 involved a lane-created worktree, which genuinely had no lock, so the correction does not reach it.
• Direction 1 is still the cheapest real fix and is entirely unaffected: probe rebase-merge, rebase-apply, MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, BISECT_LOG via git -C <path> rev-parse --git-path <name>.
• Direction 2 changes shape. It is not a greenfield design: a lane-side lock should match the harness's existing claude session <name> (pid <pid>) reason format, or cleanup needs two parsers for one field and the stale-lock detection this issue wants only works on one of them.

The pattern, stated so it stays visible

This is the fourth filed rationale in handoff-inbox batch 4 to be falsified on re-verification while its symptom held:

#	Item	Symptom	Stated mechanism that failed
1	20260811-021645 (AD-4)	writes blocked at a non-repo root	"plugin-owned deadlock" — the docs say the harness skips isolation and edits in place; it is upstream
2	20260810-225908 (AD-5)	permission decisions look unrecorded	PermissionDenied fires on the auto-mode classifier, not permissions.deny; and OTEL already records them
3	#2209 / #2211	the gate's failure output is useless	filed as "only the first stderr line reaches the transcript" — measured, all of it does; and the opt-out was filed as an unmeasured question that turned out to brick creation rather than hand placement back
4	#2257 (this one)	a clean worktree with a rebase in flight is swept	"no lane ever arms locked" — the harness arms it, with the very PID format the issue proposes adding

Every one is a real symptom paired with a false stated mechanism. Three of the four were caught only by executing something rather than reasoning about it. Whoever picks this row up should start from the corrected mechanism above, not from the issue body's "no lane ever arms it".

_{Wave-2 lane SC, handoff-inbox batch 4. Claude Code 2.1.228, Windows.}