potiuk opened a new pull request, #413:
URL: https://github.com/apache/airflow-steward/pull/413
## Summary
Adds a new check **8c** to `/setup-steward verify` that detects stale
worktrees the agent (or a prior session) created under
`<repo-root>/.claude/worktrees/` and surfaces them with a per-worktree
remediation proposal.
## Why
Stale agent-worktrees are a real friction source: they hold branches
(typically `main`, since `EnterWorktree` defaults to branching from
main), so a subsequent `git checkout main` from the main checkout fails
with *"main is already used by worktree at …"* — silently, in the
middle of a longer command pipeline, producing confusing downstream
failures. A session that ended without explicit
`ExitWorktree(action: "remove")` leaves the worktree on disk and the
next session has no signal that it was abandoned.
Concretely observed 2026-05-30: a stale
`.claude/worktrees/cozy-hugging-lerdorf`
from an earlier session blocked `git checkout main` for an entire
8-hour session, with multiple downstream commands silently retaining a
stale base branch. Each `/setup-steward verify` run during that session
would have caught it — *if* the check existed.
## What
`### 8c. Stale agent-worktrees under .claude/worktrees/`:
1. Filters `git worktree list --porcelain` to entries whose `worktree`
path is under `<repo-root>/.claude/worktrees/`.
2. Computes age as the **max** of:
- the worktree directory's `mtime`, and
- the most-recent commit timestamp on that worktree's HEAD.
Taking the max defends against both failure modes — old commits +
fresh files, *and* fresh commits + old files.
3. Buckets against a **7-day** default threshold (overridable via
`worktree_stale_days` in `<project-config>/setup-steward.md`):
- ✓ if age ≤ threshold
- ⚠ if age > threshold AND zero uncommitted changes
- ✗ if age > threshold AND uncommitted changes present
4. **Read-only.** Never auto-removes; proposes `git worktree remove
<path>` for clean stale worktrees, two-step cleanup (`EnterWorktree`
to triage → stash → `git worktree remove --force`) for dirty ones.
5. **Main-checkout only** — worktrees can only be inspected from the
checkout that owns them, and `git worktree list` output is the same
across the family anyway.
Threshold rationale (7 days): agent-worktrees are per-task isolation,
designed for open / work / close. Anything >7 days unclosed is
overwhelmingly an abandoned session. Lower thresholds (3 days) hit
false-positives on multi-day tasks; higher (30 days) lets the bug class
persist long enough to break a `git checkout main` weeks later.
## Test plan
- [ ] `/setup-steward verify` on a checkout with no agent-worktrees → check
8c reports "no worktrees under .claude/worktrees/" cleanly
- [ ] On a checkout with a fresh worktree (< 7 days) → ✓
- [ ] On a checkout with a stale clean worktree (>7 days, no uncommitted) →
⚠ with `git worktree remove` proposal
- [ ] On a checkout with a stale dirty worktree → ✗ with two-step cleanup
proposal
- [ ] Verify `worktree_stale_days` override in
`<project-config>/setup-steward.md` is respected
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
