behruznassre · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 7, 2026 · Oct 7, 2026
@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 5233
+---
+**`worktree.reap-orphans` now removes a `.claude/worktrees/agent-*` directory left by an incomplete harness teardown, and only when every residue guard in `docs/CLI-TOOLS.md` passes** — the sweep used to miss such a directory and report `reaped: 0`; its three workflow callers now keep stderr, so a summary of what was removed or kept reaches the transcript, along with any runtime-build notice or Node warning, since `>/dev/null` discards only the JSON (#4941).
@@ -1523,6 +1523,16 @@ Known limit: the kill terminates `git`, not the hook process it spawned. A hook
 
 ---
 
+### Orphan sweep
+
+```bash
+# Reap orphaned agent worktrees; run at the start of /gsd-quick, /gsd-quick-batch and execute-phase.
+# Returns JSON: { ok: true, reaped, entries: [{ path, status, reason }], scan: { admin_dir, residue_dir } }
+gsd-tools query worktree.reap-orphans
+```
+
+It reaps locked worktrees in `.git/worktrees/` whose owner process is dead and whose branch is merged, and removes a `.claude/worktrees/agent-<id>` directory a harness teardown left behind only when it is a real, non-empty directory with no `.git` entry, not in `git worktree list`, older than five minutes, with a harness branch (`agent-<id>` or `worktree-agent-<id>`; `.gsd-reap-<16 hex>` is reserved for a directory the sweep stranded mid-removal, and one with that name needs neither the name nor a branch, but is left alone until five minutes after it was renamed, by its ctime, since until then it may be another sweep's removal in progress), no git-tracked file and no repository inside it, under a `.claude/worktrees` that is a real directory of the checkout (not a link). A candidate that fails a check is listed with `status: "skipped"` and the check's `reason` and left on disk; a child that is not a candidate (a link, one with a `.git` entry, one git still lists, a young or empty one) is left without a row. `scan` says which locations were read, so `reaped: 0` never stands for "did not look": `admin_dir` is `scanned`, `absent`, `unreadable`, `git_dir_unresolved` or `default_branch_unresolved`; `residue_dir` is `scanned`, `absent`, `unreadable`, `aliased` (`.claude` or `.claude/worktrees` is a link), `not_main_checkout` (run from a linked worktree — the sweep runs from the main checkout), `top_unresolved`, `git_mismatch` (git is pointed at another repository or work tree by `GIT_DIR`, `GIT_WORK_TREE` or `core.worktree`, so its answers are not about this checkout) or `not_scanned`. The workflow callers discard the JSON and keep stderr, which names removed directories (escaped, at most five), counts kept ones by reason, and says when `.claude/worktrees` was not swept. Wave cleanup blocks an entry whose directory exists with no `.git` entry as `reason: "worktree_unregistered"`.
+
 ## Graphify
 
 Build, query, and inspect the project knowledge graph in `.planning/graphs/`. Requires `graphify.enabled: true` in `config.json` (see [Configuration Reference](CONFIGURATION.md#graphify-settings)).

@@ -56,7 +56,7 @@ if [ "$ISOLATION" = "none" ] && [ "$USE_WORKTREES" != "false" ]; then
 fi
 
 # Sweep orphaned locked worktrees from prior crashed sessions (#3707).
-[ "$ISOLATION" != "none" ] && gsd_run query worktree.reap-orphans 2>/dev/null || true
+[ "$ISOLATION" != "none" ] && gsd_run query worktree.reap-orphans >/dev/null || true
 # Auto-degrade if HEAD diverged from the fork base (#683) — both isolation models.
 if [ "$ISOLATION" != "none" ]; then
   _SHOULD_DEGRADE=$(gsd_run query worktree.base-check --mode "$ISOLATION" --pick shouldDegrade 2>/dev/null || true)

@@ -118,7 +118,7 @@ when `ISOLATION = "harness-worktree"`, else empty.
 If `USE_WORKTREES` is not `"false"`, sweep orphaned worktrees before dispatching anything (mirrors `/gsd:quick`'s own startup sweep):
 ```bash
 if [ "$USE_WORKTREES" != "false" ]; then
-  gsd_run query worktree.reap-orphans 2>/dev/null || true
+  gsd_run query worktree.reap-orphans >/dev/null || true
 fi
 ```
 

@@ -160,7 +160,7 @@ If `USE_WORKTREES` is not `"false"`, run a startup orphan sweep before spawning
 
 ```bash
 if [ "$USE_WORKTREES" != "false" ]; then
-  gsd_run query worktree.reap-orphans 2>/dev/null || true
+  gsd_run query worktree.reap-orphans >/dev/null || true
 fi
 ```
 

@@ -249,6 +249,7 @@ module.exports = {
   "tests/workflow-shell-pinning.test.cjs",
   "tests/workstream-inventory.test.cjs",
   "tests/workstream.test.cjs",
+  "tests/worktree-safety-reap.test.cjs",
   "tests/worktree-safety.test.cjs",
   "tests/worktree.test.cjs",
   ],

@@ -335,6 +335,7 @@ module.exports = {
   "tests/workstream-scoped-paths.test.cjs",
   "tests/workstream.test.cjs",
   "tests/worktree-cleanup.test.cjs",
+  "tests/worktree-safety-reap.test.cjs",
   "tests/worktree-safety.test.cjs",
   "tests/worktree.test.cjs",
   "tests/xtrace-phase-timing.platform.test.cjs",
-Original file line number
+Diff line change
@@ Expand Up @@
     ```bash
     if [ "$USE_WORKTREES" != "false" ]; then
-      gsd_run query worktree.reap-orphans 2>/dev/null || true
+      gsd_run query worktree.reap-orphans >/dev/null || true
     fi
     ```
@@ Expand Down @@