fix(worktree): unlock-retry on locked cleanup + startup orphan sweep (#3707) (#3719)

* fix(worktree): unlock-retry on locked cleanup + startup orphan sweep (#3707)

Two root causes fixed:

1. **In-session cleanup blocked**: `executeWorktreeWaveCleanupPlan` now attempts
   `git worktree unlock <path>` then retries `git worktree remove --force` when the
   initial single-force remove fails on a locked worktree. Previously every cleanup
   after a successful merge was silently blocked.

2. **Cross-session orphan accumulation**: new `reapOrphanWorktrees` helper sweeps
   `.git/worktrees/*/locked` at startup. It reaps entries where the pid is dead,
   the branch tip is an ancestor of the default branch (ancestry guard prevents data
   loss on squash-merge repos), and the lock mtime is older than 5 minutes (race
   guard). Wired into `quick.md` and `execute-phase.md` startup blocks guarded by
   `USE_WORKTREES != false`.

SDK: adds `worktree.reap-orphans` query command (routes through gsd-tools.cjs).
Tests: 11 real-fs tests covering unlock-retry, dead-pid reap, live-pid skip,
unmerged skip, fresh-mtime skip, idempotent double-call, and structural wiring.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore(changeset): add Fixed fragment for PR #3707 (worktree orphan cleanup)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(worktree): fix test portability on Windows + macOS for bug-3707 reap tests

- worktreeMeta helper: replace /\/\.git$/ with /[/\\]\.git$/ so the
  gitdir path suffix is stripped on both Windows (backslash) and Unix.
- worktreeMeta helper: normalize CRLF→LF before splitting porcelain
  blocks, fixing block parsing when git emits CRLF on Windows.
- reapOrphanWorktrees: replace single 'main' rev-parse with a
  [defaultBranch, 'main', 'master'] candidate loop so test fixtures
  without a remote origin (where branch may be 'master') don't bail
  early. Intentionally excludes 'HEAD' to prevent false reaping when
  HEAD is detached or on a feature branch (Codex adversarial finding).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(worktree): CI green — macOS symlink path, Windows test helper, pid portability, EPERM liveness

Four fixes to get macOS + Windows CI from red to green:

1. **macOS symlink mismatch** (worktree-safety.cjs): `reapOrphanWorktrees` now
   builds a canonical→listed path map from `git worktree list --porcelain` using
   `fs.realpathSync.native`. Uses the listed path (as git knows it) for
   `git worktree unlock/remove`, not the gitdir-derived path.  Fixes the
   `/var/folders` vs `/private/var/folders` discrepancy on GitHub macOS runners
   where `git worktree unlock <realpath>` was silently failing because git's
   list stored the unresolved symlink path.

2. **Windows path separator in test helper** (test file): `worktreeMeta`
   `.replace(/\/\.git$/, '')` → `.replace(/[/\\]\.git$/, '')`. On Windows,
   git writes backslash separators in the gitdir file; the Unix-only regex was
   causing `Cannot find .git/worktrees/<name>` for all Suite 2 tests.

3. **Non-portable PID in tests** (test file): All `'999999'` dead-PID literals
   replaced with `deadPid()` helper that spawns a real short-lived child, captures
   its PID, and returns it after exit. Eliminates flakiness on Linux systems where
   `pid_max` can reach 4194304, making 999999 a live PID.

4. **EPERM fail-closed in isPidAlive** (worktree-safety.cjs): `catch { return false }`
   → checks `err.code === 'EPERM'` and returns `true` (alive). On Windows and
   cross-user scenarios, `process.kill(pid, 0)` throws EPERM for live but
   inaccessible processes; treating that as dead would reap a live worktree.

Adversarial review via codex confirmed:
- Squash-merge repos: fail-closed (CONCERN, not BUG — by design, not data-loss)
- canonicalToListed map: SAFE (fail-closed on realpathSync error)
- Concurrent reapers: SAFE (both prune; second gets skipped: remove_failed)
- Startup blocking: CONCERN (no global cap, 10s/call × N worktrees) — tracked,
  not fixed here (requires separate perf work)
- gsd-sdk missing: SAFE (quick.md checks and fails fast with guidance)

All 27 local tests + Docker (holodeck) green.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(worktree): address codex adversarial findings — fail-closed default branch + CRLF map

Two fixes from codex adversarial review of PR 3718:

1. **Default branch resolution (data-loss risk)**: `reapOrphanWorktrees` now
   uses `refs/remotes/origin/<branch>` exclusively when a remote is configured.
   If `origin/HEAD` is absent but a remote exists, we bail out (fail-closed)
   rather than falling back to a local `main`/`master` that may not be the
   real integration branch.  The `main`/`master` fallback is only used when
   there is provably no remote (local-only test fixtures).

2. **CRLF normalization in canonical-path mapper**: The `worktree list
   --porcelain` output was split on '\n\n' without normalizing CRLF first.
   On Windows, git emits CRLF, which caused block-splitting to fail and
   left the canonicalToListed map only partially populated, weakening the
   symlink/path-mismatch fix introduced earlier.

3. **Windows 8.3 short-path fix (test helper)**: Both `beforeEach` blocks
   now call `resolvedTmpDir()` which pre-resolves `os.tmpdir()` via
   `fs.realpathSync.native` so temp paths avoid RUNNER~1-style short names
   that git stores in long form, causing worktreeMeta path comparisons to
   fail on Windows CI.

All 11 real-fs + 16 unit tests green locally.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(worktree): adversarial findings + macOS CI path-mismatch fix

## Root cause (macOS CI fail)
`reapOrphanWorktrees` stored `worktreePath` (gitdir-derived, real path via
git's symlink resolution, e.g. `/private/var/folders/…`) in results, while
the test's `wtDir` used the unresolved symlink form (`/var/folders/…`).  After
reaping, `canonicalPath(wtDir)` can no longer call `realpathSync.native`
(directory gone), so it falls back to `path.resolve` — which returns the
symlink form — causing the `result.find()` comparison to miss.

## Fixes applied

### Source — worktree-safety.cjs
1. **Finding 1 (fail-closed PID check)**: Non-parseable lock content (e.g.
   `"Locked by claude-code agent-xxx"`) is now treated as ALIVE with reason
   `lock_owner_unknown`, not as dead.  Previously it fell through as dead.
2. **Finding 1b (EPERM safe)**: `isPidAlive` call wrapped in try/catch; any
   thrown error (EPERM = process exists but cross-user on Windows) → ALIVE.
3. **Finding 2 (startup warning)**: `cmdWorktreeReapOrphans` now writes a
   one-line stderr warning when ≥1 entry is skipped or when reaper throws,
   while keeping exit-zero so workflows don't break.
4. **Finding 3 (default-branch discovery)**: Local-only fallback now tries
   `init.defaultBranch` config and HEAD symref before `main`/`master`, so
   repos configured with `trunk`, `dev`, etc. get correct orphan detection.
5. **macOS path fix**: Result entry for reaped worktrees now uses `gitKnownPath`
   (from `git worktree list`) instead of `worktreePath` (from gitdir file),
   ensuring the caller always sees the path git uses for the worktree.

### Test — bug-3707-locked-worktree-cleanup.test.cjs
6. **macOS CI fix**: Pre-compute `wtDirCanonical = canonicalPath(wtDir)` before
   calling `reapOrphanWorktrees` so the comparison works after removal.
7. **Gap 1**: New test — Claude Code lock format (`"Locked by claude-code …"`)
   must not be reaped; asserts `status=skipped, reason=lock_owner_unknown`.
8. **Gap 2**: New test — `isPidAlive` throwing EPERM → must not reap.
9. **Gap 3**: New test — repo with `init.defaultBranch=trunk`; merged worktree
   must be reaped (verifies trunk is discovered as the integration branch).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(test): raise waitForStoppedAt timeout 2 s → 5 s for Windows/Node22 CI load

Subprocess write latency exceeds 2 s on loaded windows-latest/Node22 runners
(test duration was 6181 ms); 5 s gives sufficient headroom without changing
any production behaviour.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

.changeset/3707-worktree-orphan-reap.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3707
+---
+**Locked worktrees now cleaned up correctly** — `executeWorktreeWaveCleanupPlan` previously issued a single `git worktree remove --force` which Git refuses on locked worktrees, blocking every post-merge cleanup when Claude Code's agent runtime held a lock file. The fix attempts `git worktree unlock` then retries the remove. A new `worktree.reap-orphans` command (`gsd-sdk query worktree.reap-orphans`) sweeps orphaned locked worktrees from prior crashed sessions at startup — it reaps entries whose pid is dead, branch is merged into the default branch, and lock mtime is older than 5 minutes. Wired into `quick.md` and `execute-phase.md` startup. (#3707)

get-shit-done/bin/gsd-tools.cjs

@@ -1207,8 +1207,10 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const worktreeSafety = require('./lib/worktree-safety.cjs');
       if (subcommand === 'cleanup-wave') {
         worktreeSafety.cmdWorktreeCleanupWave(cwd, args.slice(2));
+      } else if (subcommand === 'reap-orphans') {
+        worktreeSafety.cmdWorktreeReapOrphans(cwd);
       } else {
-        error('Unknown worktree subcommand. Available: cleanup-wave', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+        error('Unknown worktree subcommand. Available: cleanup-wave, reap-orphans', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }

get-shit-done/bin/lib/worktree-safety.cjs

@@ -475,7 +475,14 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
       break;
     }
 
-    const remove = execGit(['worktree', 'remove', entry.worktree_path, '--force'], { cwd: plan.repoRoot });
+    let remove = execGit(['worktree', 'remove', entry.worktree_path, '--force'], { cwd: plan.repoRoot });
+    if (!gitResultOk(remove)) {
+      // Locked worktrees require unlock before remove (or --force --force).
+      // Attempt: git worktree unlock <path> (ignore failure — already unlocked is ok)
+      // then retry git worktree remove --force.  (#3707)
+      execGit(['worktree', 'unlock', entry.worktree_path], { cwd: plan.repoRoot });
+      remove = execGit(['worktree', 'remove', entry.worktree_path, '--force'], { cwd: plan.repoRoot });
+    }
     if (!gitResultOk(remove)) {
       result.status = 'blocked';
       result.reason = 'worktree_remove_failed';
@@ -548,6 +555,304 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
   }
 }
 
+/**
+ * Reap orphaned linked worktrees whose lock owner process is dead, whose
+ * branch tip is fully merged into the default branch, and whose lock file
+ * mtime is older than REAP_MTIME_GUARD_MS (race guard).
+ *
+ * Invariants (Fail-closed — skip on any doubt):
+ *   Pre:  .git/worktrees/<id>/locked exists for a linked worktree
+ *   Reap: pid dead (or unparseable) AND branch-tip ancestor of default branch
+ *         AND lock mtime > REAP_MTIME_GUARD_MS old
+ *   Action: worktree unlock → worktree remove --force → prune
+ *   Post: worktree absent from git worktree list; no unmerged work lost
+ *
+ * @param {string} repoRoot  - Absolute path to the primary worktree root.
+ * @param {object} [deps]    - Optional dependency overrides for testing.
+ *   deps.execGit            - Replaces execGitDefault for all git calls.
+ *   deps.isPidAlive         - Function(pid:number):boolean (default: kill -0).
+ *   deps.readDirSafe        - Function(dir:string):string[] (default: fs.readdirSync).
+ *   deps.readFileSafe       - Function(file:string):string (default: fs.readFileSync).
+ *   deps.mtimeSafe          - Function(file:string):Date (default: fs.statSync).
+ *   deps.reapMtimeGuardMs   - Override stale-lock age threshold (default 5 min).
+ * @returns {Array<{path:string, status:'reaped'|'skipped', reason:string}>}
+ */
+const REAP_MTIME_GUARD_MS = 5 * 60 * 1000; // 5 minutes
+
+function reapOrphanWorktrees(repoRoot, deps = {}) {
+  const execGit = deps.execGit || execGitDefault;
+  const isPidAlive = deps.isPidAlive || defaultIsPidAlive;
+  const readDirSafe = deps.readDirSafe || defaultReadDirSafe;
+  const readFileSafe = deps.readFileSafe || defaultReadFileSafe;
+  const mtimeSafe = deps.mtimeSafe || defaultMtimeSafe;
+  const reapMtimeGuardMs = deps.reapMtimeGuardMs !== undefined ? deps.reapMtimeGuardMs : REAP_MTIME_GUARD_MS;
+
+  const results = [];
+
+  // 1. Discover the .git/worktrees/ admin directory.
+  const gitDir = execGit(['rev-parse', '--git-dir'], { cwd: repoRoot });
+  if (!gitResultOk(gitDir)) return results;
+  const gitDirPath = path.resolve(repoRoot, gitDir.stdout.trim());
+
+  const worktreesAdminDir = path.join(gitDirPath, 'worktrees');
+  const entries = readDirSafe(worktreesAdminDir);
+  if (!entries) return results;
+
+  // 2. Discover the default branch (main/master/etc) tip.
+  // Strategy (fail-closed):
+  //   a. Prefer refs/remotes/origin/HEAD — the authoritative integration branch.
+  //   b. Only fall back to 'main' / 'master' when origin/HEAD is absent AND the
+  //      remote itself doesn't exist (i.e. local-only test fixtures).  In all other
+  //      cases, bail out rather than guess: using a wrong branch tip would allow
+  //      `merge-base --is-ancestor` to pass against a non-authoritative ref and
+  //      reap a worktree whose branch is NOT merged into the real default.
+  //
+  // Intentionally excludes 'HEAD': using HEAD when detached or on a feature
+  // branch would make every branch appear "merged" into it, causing false reaping.
+  const defaultBranchResult = execGit(
+    ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'],
+    { cwd: repoRoot }
+  );
+
+  let mainTip;
+  if (gitResultOk(defaultBranchResult)) {
+    // Remote default branch is known — use it exclusively.
+    const branchName = defaultBranchResult.stdout.trim().replace(/^origin\//, '');
+    const r = execGit(['rev-parse', `refs/remotes/origin/${branchName}`], { cwd: repoRoot });
+    if (!gitResultOk(r)) return results; // remote ref unresolvable — fail closed
+    mainTip = r.stdout.trim();
+  } else {
+    // No remote configured (local-only repo, e.g. test fixtures).
+    // Fall back to 'main' then 'master' — only safe because there is no remote
+    // integration branch to confuse with.  A remote that exists but lacks
+    // origin/HEAD is treated as ambiguous and bails out (fail-closed).
+    const hasRemote = execGit(['remote'], { cwd: repoRoot });
+    if (gitResultOk(hasRemote) && hasRemote.stdout.trim()) {
+      // Remote exists but origin/HEAD not set — ambiguous; fail closed.
+      return results;
+    }
+    // Build candidate list: init.defaultBranch config, HEAD symref, then main, master.
+    const candidateBranches = [];
+    // Try git config init.defaultBranch first (user-configured default)
+    const configResult = execGit(['config', '--get', 'init.defaultBranch'], { cwd: repoRoot });
+    if (gitResultOk(configResult) && configResult.stdout.trim()) {
+      candidateBranches.push(configResult.stdout.trim());
+    }
+    // Try HEAD symref (the branch the repo is currently on — valid for local repos
+    // without detached HEAD; do not use when detached since it could be a feature branch)
+    const headSymref = execGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd: repoRoot });
+    if (gitResultOk(headSymref) && headSymref.stdout.trim()) {
+      const headBranch = headSymref.stdout.trim();
+      if (!candidateBranches.includes(headBranch)) {
+        candidateBranches.push(headBranch);
+      }
+    }
+    // Always include main and master as universal fallbacks
+    for (const b of ['main', 'master']) {
+      if (!candidateBranches.includes(b)) candidateBranches.push(b);
+    }
+    for (const candidate of candidateBranches) {
+      const r = execGit(['rev-parse', candidate], { cwd: repoRoot });
+      if (gitResultOk(r)) {
+        mainTip = r.stdout.trim();
+        break;
+      }
+    }
+    if (!mainTip) return results;
+  }
+
+  // 3. Build a canonical-path → listed-path index from git worktree list.
+  // git worktree list shows paths AS PROVIDED to git worktree add.
+  // On macOS, os.tmpdir() may be /var/folders/... (symlink) while git writes
+  // /private/var/folders/... (real path) in the gitdir file.  We need the
+  // LISTED path for git worktree unlock/remove to find the worktree.
+  const listedResult = execGit(['worktree', 'list', '--porcelain'], { cwd: repoRoot });
+  const canonicalToListed = new Map();
+  if (gitResultOk(listedResult)) {
+    // Normalize CRLF → LF before splitting: git on Windows may emit CRLF in
+    // porcelain output, which would break block splitting on '\n\n'.
+    const normalizedListed = listedResult.stdout.replace(/\r\n/g, '\n');
+    for (const block of normalizedListed.split('\n\n').filter(Boolean)) {
+      const wtLine = block.split('\n').find((l) => l.startsWith('worktree '));
+      if (!wtLine) continue;
+      const listed = wtLine.slice('worktree '.length).trim();
+      try {
+        const canonical = fs.realpathSync.native(listed);
+        canonicalToListed.set(canonical, listed);
+      } catch {
+        // If the path doesn't exist (already removed), skip silently.
+      }
+    }
+  }
+
+  // 4. Process each worktree admin entry that has a 'locked' file.
+  for (const entryName of entries) {
+    const adminDir = path.join(worktreesAdminDir, entryName);
+    const lockedFile = path.join(adminDir, 'locked');
+    const lockedContent = readFileSafe(lockedFile);
+    if (lockedContent === null) continue; // no lock file — not our concern
+
+    // Resolve the actual worktree path from the gitdir pointer.
+    // The gitdir file contains a path like "../../<name>/.git" relative to adminDir.
+    // Strip the trailing .git segment (cross-platform: handle both / and \).
+    const gitdirFile = path.join(adminDir, 'gitdir');
+    const gitdirContent = readFileSafe(gitdirFile);
+    if (!gitdirContent) continue;
+    const resolvedGitFile = path.resolve(adminDir, gitdirContent.trim());
+    const worktreePath = path.basename(resolvedGitFile) === '.git'
+      ? path.dirname(resolvedGitFile)
+      : resolvedGitFile;
+
+    // Look up the git-list path (the path git knows about) for use in
+    // git worktree unlock/remove commands.  Falls back to worktreePath if
+    // not found (e.g. already removed, or no symlink ambiguity).
+    let gitKnownPath = worktreePath;
+    try {
+      const canonical = fs.realpathSync.native(worktreePath);
+      gitKnownPath = canonicalToListed.get(canonical) || worktreePath;
+    } catch {
+      // worktreePath may not exist yet (already removed); use as-is.
+    }
+
+    // 4a. Stale-lock guard: skip if lock is too fresh (PID recycling / race).
+    const lockMtime = mtimeSafe(lockedFile);
+    if (!lockMtime || Date.now() - lockMtime.getTime() < reapMtimeGuardMs) {
+      results.push({ path: worktreePath, status: 'skipped', reason: 'lock_too_fresh' });
+      continue;
+    }
+
+    // 4b. PID liveness check.
+    // Fail-closed: any lock content that does not parse as a numeric PID (e.g.
+    // "Locked by claude-code agent-xxxx") is treated as ALIVE — we cannot
+    // confirm the owner is dead, so we must not reap.  This includes the real
+    // Claude Code lock format which is non-numeric text.
+    const pidStr = lockedContent.trim().match(/^\d+/)?.[0];
+    if (!pidStr) {
+      results.push({ path: worktreePath, status: 'skipped', reason: 'lock_owner_unknown' });
+      continue;
+    }
+    const pid = parseInt(pidStr, 10);
+    // Wrap isPidAlive in try/catch: any error (e.g. EPERM on Windows when the process
+    // exists but is owned by another user) must be treated as ALIVE (fail-closed).
+    let pidIsAlive;
+    try {
+      pidIsAlive = Number.isNaN(pid) || isPidAlive(pid);
+    } catch {
+      pidIsAlive = true; // Cannot determine liveness — treat as alive, do not reap.
+    }
+    if (pidIsAlive) {
+      results.push({ path: worktreePath, status: 'skipped', reason: 'pid_alive' });
+      continue;
+    }
+
+    // 4c. Ancestry guard: branch-tip must be reachable from main (fail closed).
+    // The admin HEAD file contains either "ref: refs/heads/<branch>" or a bare SHA.
+    // We read the file directly (no non-standard git ref parsing).
+    let branchTip;
+    {
+      const headContent = readFileSafe(path.join(adminDir, 'HEAD'));
+      if (!headContent) {
+        results.push({ path: worktreePath, status: 'skipped', reason: 'cannot_resolve_branch_tip' });
+        continue;
+      }
+      const trimmed = headContent.trim();
+      if (trimmed.startsWith('ref: refs/heads/')) {
+        // Symbolic ref — resolve to commit SHA via git
+        const branchName = trimmed.slice('ref: refs/heads/'.length);
+        const resolveResult = execGit(['rev-parse', `refs/heads/${branchName}`], { cwd: repoRoot });
+        if (!gitResultOk(resolveResult)) {
+          results.push({ path: worktreePath, status: 'skipped', reason: 'cannot_resolve_branch_tip' });
+          continue;
+        }
+        branchTip = resolveResult.stdout.trim();
+      } else if (/^[0-9a-f]{40}$/i.test(trimmed)) {
+        // Detached HEAD — bare SHA
+        branchTip = trimmed;
+      } else {
+        results.push({ path: worktreePath, status: 'skipped', reason: 'cannot_resolve_branch_tip' });
+        continue;
+      }
+    }
+
+    const ancestorCheck = execGit(
+      ['merge-base', '--is-ancestor', branchTip, mainTip],
+      { cwd: repoRoot }
+    );
+    if (!gitResultOk(ancestorCheck)) {
+      results.push({ path: worktreePath, status: 'skipped', reason: 'branch_not_merged' });
+      continue;
+    }
+
+    // 4d. Reap: unlock → remove --force.
+    // Use gitKnownPath (from git worktree list) so that git can locate the
+    // worktree even when the path in the gitdir file differs due to symlinks
+    // (e.g. macOS /var/folders vs /private/var/folders).
+    execGit(['worktree', 'unlock', gitKnownPath], { cwd: repoRoot }); // ignore failure (already unlocked)
+    const removeResult = execGit(['worktree', 'remove', gitKnownPath, '--force'], { cwd: repoRoot });
+    if (!gitResultOk(removeResult)) {
+      results.push({ path: worktreePath, status: 'skipped', reason: 'remove_failed' });
+      continue;
+    }
+
+    // Use the git-listed path so the result is consistent with what callers see
+    // from 'git worktree list', avoiding symlink vs real-path mismatches on macOS.
+    results.push({ path: gitKnownPath, status: 'reaped', reason: 'pid_dead_and_merged' });
+  }
+
+  // 5. Always prune stale metadata (handles missing-on-disk entries).
+  execGit(['worktree', 'prune'], { cwd: repoRoot });
+
+  return results;
+}
+
+// ─── reapOrphanWorktrees deps helpers ─────────────────────────────────────────
+
+function defaultIsPidAlive(pid) {
+  // process.kill(pid, 0) probes process existence without sending a real signal.
+  //   - Returns normally → process is alive.
+  //   - Throws ESRCH → process does not exist → dead.
+  //   - Throws EPERM → process exists but we lack permission (alive; fail-closed
+  //     on Windows where cross-user processes throw EPERM, not ESRCH).
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but we cannot signal it.
+    // Treat as alive (fail-closed: do not reap a process we cannot confirm dead).
+    if (err && err.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+function defaultReadDirSafe(dir) {
+  try { return fs.readdirSync(dir); } catch { return null; }
+}
+
+function defaultReadFileSafe(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return null; }
+}
+
+function defaultMtimeSafe(file) {
+  try { return fs.statSync(file).mtime; } catch { return null; }
+}
+
+function cmdWorktreeReapOrphans(cwd) {
+  let result;
+  try {
+    result = reapOrphanWorktrees(cwd);
+  } catch (err) {
+    // Surface failure as a one-line warning; keep exit-zero so workflows don't break.
+    process.stderr.write(`[gsd] worktree.reap-orphans failed: ${err && err.message ? err.message : String(err)}\n`);
+    result = [];
+  }
+  const skippedCount = result.filter((r) => r.status === 'skipped').length;
+  if (skippedCount > 0) {
+    // Surface skipped entries so operators are aware of unresolved orphans.
+    process.stderr.write(`[gsd] worktree.reap-orphans: ${skippedCount} orphan(s) skipped (run with DEBUG=1 for details)\n`);
+  }
+  process.stdout.write(`${JSON.stringify({ ok: true, reaped: result.filter((r) => r.status === 'reaped').length, entries: result }, null, 2)}\n`);
+}
+
 module.exports = {
   resolveWorktreeContext,
   parseWorktreePorcelain,
@@ -560,4 +865,6 @@ module.exports = {
   planWorktreeWaveCleanup,
   executeWorktreeWaveCleanupPlan,
   cmdWorktreeCleanupWave,
+  reapOrphanWorktrees,
+  cmdWorktreeReapOrphans,
 };

get-shit-done/workflows/execute-phase.md

@@ -89,6 +89,8 @@ if [ "$RUNTIME" = "codex" ] && [ "$USE_WORKTREES" != "false" ]; then
   echo "FATAL: Codex execute-phase worktree isolation is unsupported. Set workflow.use_worktrees=false or use a runtime with Agent isolation=\"worktree\" support." >&2
   exit 1
 fi
+# Sweep orphaned locked worktrees from prior crashed sessions before spawning executors (#3707).
+[ "$USE_WORKTREES" != "false" ] && gsd-sdk query worktree.reap-orphans 2>/dev/null || true
 ```
 Codex maps subagents to `spawn_agent`, which has no direct Codex mapping for Claude Code's `isolation="worktree"` parameter. Failing closed prevents main-checkout edits while the workflow believes agents are isolated.
 

get-shit-done/workflows/quick.md

@@ -152,6 +152,14 @@ Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_mo
 USE_WORKTREES=$(gsd-sdk query config-get workflow.use_worktrees 2>/dev/null || echo "true")
 ```
 
+If `USE_WORKTREES` is not `"false"`, run a startup orphan sweep before spawning any executors. This reaps locked worktrees whose lock-owner process is dead, whose branch is merged into the default branch, and whose lock file mtime is older than 5 minutes. Running it at startup prevents accumulation of orphaned worktrees from prior sessions that exited without cleanup (#3707).
+
+```bash
+if [ "$USE_WORKTREES" != "false" ]; then
+  gsd-sdk query worktree.reap-orphans 2>/dev/null || true
+fi
+```
+
 If the project uses git submodules, worktree isolation is unsafe **only when the quick task touches a submodule path**. The previous behavior unconditionally disabled worktree isolation whenever `.gitmodules` existed, which penalised every quick task in a submodule project even when the task was nowhere near a submodule. Parse submodule paths from `.gitmodules` so the executor can act on actual submodule paths rather than the mere file's existence:
 
 ```bash

sdk/src/query/command-static-catalog-domain.ts

@@ -20,7 +20,7 @@ import { uatRenderCheckpoint, auditUat } from './uat.js';
 // requires('./lib/intel.cjs') and calls the CJS functions in-process.
 import { writeProfile, generateClaudeProfile, generateDevPreferences, generateClaudeMd } from './profile-output.js';
 import { phaseMvpMode, taskIsBehaviorAdding, userStoryValidate } from './mvp.js';
-import { worktreeCleanupWave } from './worktree.js';
+import { worktreeCleanupWave, worktreeReapOrphans } from './worktree.js';
 import { promptBudget } from './prompt-budget.js';
 
 export const DOMAIN_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
@@ -67,6 +67,8 @@ export const DOMAIN_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler
   ['workstream progress', workstreamProgress],
   ['worktree.cleanup-wave', worktreeCleanupWave],
   ['worktree cleanup-wave', worktreeCleanupWave],
+  ['worktree.reap-orphans', worktreeReapOrphans],
+  ['worktree reap-orphans', worktreeReapOrphans],
   ['docs-init', docsInit],
   ['websearch', websearch],
   ['learnings.copy', learningsCopy],

sdk/src/query/worktree.ts

@@ -2,6 +2,42 @@ import { spawnSync } from 'node:child_process';
 import { resolveGsdToolsPath } from '../sdk-package-compatibility.js';
 import type { QueryHandler } from './utils.js';
 
+function worktreeSpawn(subcommand: string, args: string[], projectDir: string) {
+  const toolsPath = resolveGsdToolsPath(projectDir);
+  return spawnSync(process.execPath, [toolsPath, 'worktree', subcommand, ...args], {
+    cwd: projectDir,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 30000,
+    maxBuffer: 1024 * 1024,
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: '0',
+      GCM_INTERACTIVE: 'never',
+    },
+  });
+}
+
+function worktreeHandleResult(result: ReturnType<typeof spawnSync>) {
+  if (result.error) {
+    return { data: { ok: false, reason: (result.error as Error).message || 'gsd-tools invocation failed' } };
+  }
+  const stdout = (result.stdout as string || '').trim();
+  if (stdout) {
+    try {
+      return { data: JSON.parse(stdout) };
+    } catch {
+      return { data: { ok: result.status === 0, reason: stdout } };
+    }
+  }
+  return {
+    data: {
+      ok: result.status === 0,
+      reason: (result.stderr as string)?.trim() || (result.status === 0 ? 'ok' : 'gsd-tools error'),
+    },
+  };
+}
+
 export const worktreeCleanupWave: QueryHandler = async (args, projectDir) => {
   const toolsPath = resolveGsdToolsPath(projectDir);
   const result = spawnSync(process.execPath, [toolsPath, 'worktree', 'cleanup-wave', ...args], {
@@ -37,3 +73,12 @@ export const worktreeCleanupWave: QueryHandler = async (args, projectDir) => {
     },
   };
 };
+
+/**
+ * Sweep orphaned locked worktrees from prior crashed sessions (#3707).
+ * Reaps entries whose pid is dead, branch is merged into the default branch,
+ * and lock mtime is older than 5 minutes.
+ */
+export const worktreeReapOrphans: QueryHandler = async (_args, projectDir) => {
+  return worktreeHandleResult(worktreeSpawn('reap-orphans', [], projectDir));
+};

tests/bug-1974-context-exhaustion-record.test.cjs

@@ -55,7 +55,7 @@ function runHook(sessionId, remainingPct, cwd) {
 /**
  * Wait up to `ms` for a file to exist (the subprocess is fire-and-forget).
  */
-function waitForStoppedAt(statePath, ms = 2000) {
+function waitForStoppedAt(statePath, ms = 5000) {
   const deadline = Date.now() + ms;
   while (Date.now() < deadline) {
     try {

tests/bug-3707-locked-worktree-cleanup.test.cjs

@@ -0,0 +1,553 @@
+// allow-test-rule: source-text-is-the-product
+// Real-filesystem tests for the two failure modes pinned in #3707:
+//   1. executeWorktreeWaveCleanupPlan must unlock-then-retry when a worktree is locked.
+//   2. reapOrphanWorktrees must reap dead-pid+merged entries and skip live / unmerged / fresh-mtime entries.
+//   3. quick.md and execute-phase.md must wire gsd-sdk query worktree.reap-orphans at startup.
+
+'use strict';
+
+const { describe, test, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+const {
+  executeWorktreeWaveCleanupPlan,
+  planWorktreeWaveCleanup,
+  reapOrphanWorktrees,
+} = require('../get-shit-done/bin/lib/worktree-safety.cjs');
+
+// ─── PID helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Return a PID that is guaranteed to be dead.
+ * Spawns a short-lived child, captures its PID, waits for it to exit, then
+ * returns that PID.  This is cross-platform and not subject to pid_max races
+ * (unlike a hardcoded high number such as 999999).
+ */
+function deadPid() {
+  // Use the shortest possible no-op: `node -e ""` on all platforms.
+  const nodeExe = process.execPath;
+  const result = spawnSync(nodeExe, ['-e', ''], { stdio: 'ignore' });
+  if (result.pid == null || result.status === null) {
+    // Fallback: use a PID above the system max — 2^31-1 always exceeds any
+    // real OS limit (Linux max: 4194304, macOS max: 99998, Windows: variable).
+    return 2147483647;
+  }
+  return result.pid;
+}
+
+// ─── Git repo helpers ─────────────────────────────────────────────────────────
+
+function canonicalPath(p) {
+  try { return fs.realpathSync.native(path.resolve(p)); } catch { return path.resolve(p); }
+}
+
+/**
+ * Return a canonical (long-form) path for os.tmpdir().
+ * On Windows CI, os.tmpdir() often contains 8.3 short-name components
+ * (e.g. RUNNER~1 instead of runneradmin).  When 8.3 names are disabled
+ * (common in modern CI environments), those short paths are not resolvable
+ * and fs.realpathSync.native fails with ENOENT.  Pre-resolving the base
+ * ensures every path created under it uses the same long-form representation
+ * that git stores when given absolute paths.
+ */
+function resolvedTmpDir() {
+  try { return fs.realpathSync.native(os.tmpdir()); } catch { return os.tmpdir(); }
+}
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: 'pipe', encoding: 'utf8' });
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init'], dir);
+  git(['config', 'user.email', 'test@test.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  git(['config', 'commit.gpgsign', 'false'], dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), '# Test\n');
+  git(['add', '-A'], dir);
+  git(['commit', '-m', 'initial commit'], dir);
+  try { git(['branch', '-m', 'master', 'main'], dir); } catch { /* already main */ }
+}
+
+function addWorktree(repoDir, wtDir, branchName) {
+  git(['worktree', 'add', wtDir, '-b', branchName], repoDir);
+}
+
+function commitInWorktree(wtDir, filename) {
+  const fname = filename || 'work.txt';
+  fs.writeFileSync(path.join(wtDir, fname), 'content\n');
+  git(['add', '-A'], wtDir);
+  git(['commit', '-m', `work in ${path.basename(wtDir)}`], wtDir);
+}
+
+function mergeIntoMain(repoDir, branchName) {
+  git(['merge', branchName, '--no-ff', '-m', `merge ${branchName}`], repoDir);
+}
+
+function worktreeMeta(repoDir, wtDir) {
+  // Return the .git/worktrees/<name>/ directory for a given linked worktree
+  const worktrees = git(['worktree', 'list', '--porcelain'], repoDir);
+  const canonical = canonicalPath(wtDir);
+  // Normalize CRLF → LF before splitting (git on Windows may emit CRLF).
+  const normalized = worktrees.replace(/\r\n/g, '\n');
+  const blocks = normalized.split('\n\n').filter(Boolean);
+  for (const block of blocks) {
+    const lines = block.split('\n');
+    const wtLine = lines.find((l) => l.startsWith('worktree '));
+    if (!wtLine) continue;
+    const wtPath = wtLine.slice('worktree '.length).trim();
+    if (canonicalPath(wtPath) !== canonical) continue;
+    const gitCommonDir = git(['rev-parse', '--git-common-dir'], repoDir).trim();
+    const worktreesDir = path.join(path.resolve(repoDir, gitCommonDir), 'worktrees');
+    if (!fs.existsSync(worktreesDir)) continue;
+    for (const entry of fs.readdirSync(worktreesDir)) {
+      const gitdirFile = path.join(worktreesDir, entry, 'gitdir');
+      if (!fs.existsSync(gitdirFile)) continue;
+      const gitdirContent = fs.readFileSync(gitdirFile, 'utf8').trim();
+      const resolvedWtRoot = path.resolve(worktreesDir, entry, gitdirContent).replace(/[/\\]\.git$/, '');
+      if (canonicalPath(resolvedWtRoot) === canonical) {
+        return path.join(worktreesDir, entry);
+      }
+    }
+  }
+  throw new Error(`Cannot find .git/worktrees/<name> for worktree at ${wtDir}`);
+}
+
+function listedWorktreePaths(repoDir) {
+  const out = git(['worktree', 'list', '--porcelain'], repoDir);
+  return new Set(
+    out.split('\n').filter((l) => l.startsWith('worktree ')).map((l) => canonicalPath(l.slice('worktree '.length).trim()))
+  );
+}
+
+// ─── Suite 1: executeWorktreeWaveCleanupPlan — unlock-and-retry ───────────────
+
+describe('bug-3707: executeWorktreeWaveCleanupPlan unlocks and retries on locked worktree', () => {
+  let tmpBase;
+
+  beforeEach(() => {
+    tmpBase = fs.mkdtempSync(path.join(resolvedTmpDir(), 'gsd-3707-cleanup-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpBase, { recursive: true, force: true });
+  });
+
+  test('removes a locked worktree after unlock-retry (real-fs)', () => {
+    const repoDir = path.join(tmpBase, 'repo');
+    const wtDir = path.join(tmpBase, 'wt-locked');
+    const branchName = 'worktree-agent-test1';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir);
+    mergeIntoMain(repoDir, branchName);
+
+    // Simulate Claude Code's lock: write a .git/worktrees/<name>/locked file
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, 'Locked by claude-code agent-test1');
+
+    assert.ok(fs.existsSync(lockedFile), 'lock file should exist before test');
+
+    const baseCommit = git(['merge-base', 'HEAD', branchName], repoDir).trim();
+
+    const plan = {
+      ok: true,
+      repoRoot: repoDir,
+      action: 'cleanup_wave',
+      discovery: 'manifest',
+      entries: [{
+        agent_id: 'test1',
+        worktree_path: wtDir,
+        branch: branchName,
+        expected_base: baseCommit,
+      }],
+    };
+
+    const result = executeWorktreeWaveCleanupPlan(plan);
+
+    assert.equal(result.ok, true, `cleanup should succeed, got: ${JSON.stringify(result)}`);
+    assert.equal(result.entries[0].status, 'merged_removed');
+    assert.ok(!fs.existsSync(wtDir), 'worktree directory should be gone after cleanup');
+    assert.ok(!listedWorktreePaths(repoDir).has(canonicalPath(wtDir)), 'git worktree list should not include removed worktree');
+  });
+
+  test('cleanup succeeds without a lock file present (no regression)', () => {
+    const repoDir = path.join(tmpBase, 'repo2');
+    const wtDir = path.join(tmpBase, 'wt-unlocked');
+    const branchName = 'worktree-agent-test2';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir, 'unlocked.txt');
+    mergeIntoMain(repoDir, branchName);
+
+    const baseCommit = git(['merge-base', 'HEAD', branchName], repoDir).trim();
+
+    const plan = {
+      ok: true,
+      repoRoot: repoDir,
+      action: 'cleanup_wave',
+      discovery: 'manifest',
+      entries: [{
+        agent_id: 'test2',
+        worktree_path: wtDir,
+        branch: branchName,
+        expected_base: baseCommit,
+      }],
+    };
+
+    const result = executeWorktreeWaveCleanupPlan(plan);
+
+    assert.equal(result.ok, true, `unlocked cleanup should succeed: ${JSON.stringify(result)}`);
+    assert.equal(result.entries[0].status, 'merged_removed');
+    assert.ok(!fs.existsSync(wtDir), 'worktree directory should be gone');
+  });
+});
+
+// ─── Suite 2: reapOrphanWorktrees ─────────────────────────────────────────────
+
+describe('bug-3707: reapOrphanWorktrees', () => {
+  let tmpBase;
+
+  beforeEach(() => {
+    tmpBase = fs.mkdtempSync(path.join(resolvedTmpDir(), 'gsd-3707-reap-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpBase, { recursive: true, force: true });
+  });
+
+  // ── Dead PID + merged branch → reap ────────────────────────────────────────
+  test('reaps a worktree whose pid is dead and branch is merged into main', () => {
+    const repoDir = path.join(tmpBase, 'repo');
+    const wtDir = path.join(tmpBase, 'wt-dead-merged');
+    const branchName = 'worktree-agent-dead-merged';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir);
+    mergeIntoMain(repoDir, branchName);
+
+    // Write a lock file with a definitely-dead PID.  Use the deadPid() helper
+    // which spawns and reaps a real child process — avoids pid_max flakiness
+    // on Linux systems where 999999 could be a live PID.
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, String(deadPid()));
+
+    // Back-date mtime so the stale-lock guard passes (> 5 minutes old)
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockedFile, staleTime, staleTime);
+
+    // Pre-compute canonical path BEFORE reaping — the directory will be gone
+    // afterward, so fs.realpathSync.native will fail and canonicalPath falls
+    // back to path.resolve (non-symlink-resolved).  On macOS CI, git internally
+    // resolves /var/folders → /private/var/folders when writing the gitdir file,
+    // so r.path uses the real path while wtDir uses the symlink form.  Computing
+    // canonical before removal ensures we compare the resolved forms.
+    const wtDirCanonical = canonicalPath(wtDir);
+
+    const result = reapOrphanWorktrees(repoDir);
+
+    assert.ok(Array.isArray(result), 'reapOrphanWorktrees should return an array');
+    const reaped = result.find((r) => canonicalPath(r.path) === wtDirCanonical);
+    assert.ok(reaped, `worktree ${wtDir} should appear in reaped list`);
+    assert.equal(reaped.status, 'reaped');
+    assert.ok(!fs.existsSync(wtDir), 'worktree directory should be removed');
+    assert.ok(!listedWorktreePaths(repoDir).has(wtDirCanonical), 'git worktree list should not show reaped worktree');
+  });
+
+  // ── Live PID → skip ────────────────────────────────────────────────────────
+  test('skips a worktree whose pid is alive', () => {
+    const repoDir = path.join(tmpBase, 'repo2');
+    const wtDir = path.join(tmpBase, 'wt-live-pid');
+    const branchName = 'worktree-agent-live-pid';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir);
+    mergeIntoMain(repoDir, branchName);
+
+    // Write current process PID as the lock owner
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, String(process.pid));
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockedFile, staleTime, staleTime);
+
+    const result = reapOrphanWorktrees(repoDir);
+
+    const skipped = result.find((r) => canonicalPath(r.path) === canonicalPath(wtDir));
+    if (skipped) {
+      assert.notEqual(skipped.status, 'reaped', 'live-pid worktree must not be reaped');
+    }
+    assert.ok(fs.existsSync(wtDir), 'worktree directory must still exist for live-pid worktree');
+  });
+
+  // ── Dead PID + unmerged branch → skip (data loss guard) ────────────────────
+  test('skips a worktree whose branch has unmerged commits even with dead pid', () => {
+    const repoDir = path.join(tmpBase, 'repo3');
+    const wtDir = path.join(tmpBase, 'wt-unmerged');
+    const branchName = 'worktree-agent-unmerged';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir, 'unmerged.txt');
+    // NOTE: intentionally NOT merging the branch into main
+
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, String(deadPid()));
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockedFile, staleTime, staleTime);
+
+    const result = reapOrphanWorktrees(repoDir);
+
+    const entry = result.find((r) => canonicalPath(r.path) === canonicalPath(wtDir));
+    if (entry) {
+      assert.notEqual(entry.status, 'reaped', 'unmerged worktree must not be reaped (data loss guard)');
+    }
+    assert.ok(fs.existsSync(wtDir), 'unmerged worktree directory must still exist');
+  });
+
+  // ── Dead PID + merged + fresh mtime → skip (race guard) ───────────────────
+  test('skips a locked worktree with fresh mtime even when pid is dead and branch is merged', () => {
+    const repoDir = path.join(tmpBase, 'repo4');
+    const wtDir = path.join(tmpBase, 'wt-fresh-lock');
+    const branchName = 'worktree-agent-fresh-lock';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir, 'fresh.txt');
+    mergeIntoMain(repoDir, branchName);
+
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, String(deadPid()));
+    // Fresh mtime: within the race-guard window (< 5 minutes old); no utimes needed
+
+    const result = reapOrphanWorktrees(repoDir);
+
+    const entry = result.find((r) => canonicalPath(r.path) === canonicalPath(wtDir));
+    if (entry) {
+      assert.notEqual(entry.status, 'reaped', 'fresh-mtime worktree must not be reaped (race guard)');
+    }
+    assert.ok(fs.existsSync(wtDir), 'fresh-lock worktree directory must still exist');
+  });
+
+  // ── Double invocation → idempotent ─────────────────────────────────────────
+  test('is idempotent: second invocation is a no-op', () => {
+    const repoDir = path.join(tmpBase, 'repo5');
+    const wtDir = path.join(tmpBase, 'wt-idempotent');
+    const branchName = 'worktree-agent-idempotent';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir, 'idempotent.txt');
+    mergeIntoMain(repoDir, branchName);
+
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, String(deadPid()));
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockedFile, staleTime, staleTime);
+
+    const result1 = reapOrphanWorktrees(repoDir);
+    const reaped1 = result1.filter((r) => r.status === 'reaped');
+    assert.equal(reaped1.length, 1, 'first invocation should reap exactly one entry');
+
+    // Second invocation: nothing left to reap
+    const result2 = reapOrphanWorktrees(repoDir);
+    const reaped2 = result2.filter((r) => r.status === 'reaped');
+    assert.equal(reaped2.length, 0, 'second invocation should reap nothing (idempotent)');
+  });
+});
+
+// ─── Suite 3: Structural — startup sweep wiring ───────────────────────────────
+
+describe('bug-3707: startup orphan sweep is wired into workflow entry points', () => {
+  const QUICK_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'quick.md');
+  const EXECUTE_PHASE_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'execute-phase.md');
+
+  test('quick.md calls worktree.reap-orphans at startup when USE_WORKTREES is not false', () => {
+    const content = fs.readFileSync(QUICK_PATH, 'utf8');
+    assert.ok(
+      content.includes('worktree.reap-orphans'),
+      'quick.md must call gsd-sdk query worktree.reap-orphans at startup'
+    );
+    // Must be guarded by USE_WORKTREES check
+    assert.ok(
+      /USE_WORKTREES.*!=.*false[\s\S]{0,200}worktree\.reap-orphans/m.test(content) ||
+      /worktree\.reap-orphans[\s\S]{0,200}USE_WORKTREES.*!=.*false/m.test(content),
+      'quick.md startup sweep must be guarded by USE_WORKTREES != false'
+    );
+  });
+
+  test('execute-phase.md calls worktree.reap-orphans at startup when USE_WORKTREES is not false', () => {
+    const content = fs.readFileSync(EXECUTE_PHASE_PATH, 'utf8');
+    assert.ok(
+      content.includes('worktree.reap-orphans'),
+      'execute-phase.md must call gsd-sdk query worktree.reap-orphans at startup'
+    );
+    assert.ok(
+      /USE_WORKTREES.*!=.*false[\s\S]{0,200}worktree\.reap-orphans/m.test(content) ||
+      /worktree\.reap-orphans[\s\S]{0,200}USE_WORKTREES.*!=.*false/m.test(content),
+      'execute-phase.md startup sweep must be guarded by USE_WORKTREES != false'
+    );
+  });
+
+  test('worktree-safety module exports reapOrphanWorktrees', () => {
+    const mod = require('../get-shit-done/bin/lib/worktree-safety.cjs');
+    assert.strictEqual(typeof mod.reapOrphanWorktrees, 'function');
+  });
+
+  test('worktree-safety module exports cmdWorktreeReapOrphans', () => {
+    const mod = require('../get-shit-done/bin/lib/worktree-safety.cjs');
+    assert.strictEqual(typeof mod.cmdWorktreeReapOrphans, 'function');
+  });
+});
+
+// ─── Suite 4: Adversarial gap tests ──────────────────────────────────────────
+
+describe('bug-3707: reapOrphanWorktrees — adversarial edge cases', () => {
+  let tmpBase;
+
+  beforeEach(() => {
+    tmpBase = fs.mkdtempSync(path.join(resolvedTmpDir(), 'gsd-3707-adv-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpBase, { recursive: true, force: true });
+  });
+
+  // ── Gap 1: Non-numeric lock content (real Claude Code format) → ALIVE (fail-closed) ──
+  test('does NOT reap a worktree whose lock contains non-numeric Claude Code content', () => {
+    // Claude Code writes "Locked by claude-code agent-<id>" as the lock content.
+    // This is non-numeric and MUST be treated as ALIVE (fail-closed) — we cannot
+    // confirm the owner is dead, so reaping would risk data loss.
+    const repoDir = path.join(tmpBase, 'repo');
+    const wtDir = path.join(tmpBase, 'wt-claude-lock');
+    const branchName = 'worktree-agent-claude-lock';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir, 'claude-work.txt');
+    mergeIntoMain(repoDir, branchName);
+
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    // Write the real Claude Code lock format (non-numeric)
+    fs.writeFileSync(lockedFile, 'Locked by claude-code agent-a1b2c3d4e5f6');
+
+    // Back-date mtime so the stale-lock guard passes
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockedFile, staleTime, staleTime);
+
+    const result = reapOrphanWorktrees(repoDir);
+
+    const entry = result.find((r) => canonicalPath(r.path) === canonicalPath(wtDir));
+    if (entry) {
+      assert.notEqual(
+        entry.status,
+        'reaped',
+        'non-numeric Claude Code lock must NOT be reaped (fail-closed: owner unknown)'
+      );
+      assert.equal(entry.status, 'skipped', 'non-numeric lock entry should have status=skipped');
+      assert.equal(entry.reason, 'lock_owner_unknown', 'reason must be lock_owner_unknown');
+    }
+    assert.ok(fs.existsSync(wtDir), 'worktree with Claude Code lock must NOT be removed');
+  });
+
+  // ── Gap 2: EPERM in defaultIsPidAlive → ALIVE (fail-closed) ─────────────────
+  test('treats EPERM from isPidAlive as ALIVE (fail-closed)', () => {
+    // On Windows, signalling cross-user processes throws EPERM, not ESRCH.
+    // The reaper must treat EPERM as ALIVE to avoid false reaping.
+    const repoDir = path.join(tmpBase, 'repo2');
+    const wtDir = path.join(tmpBase, 'wt-eperm');
+    const branchName = 'worktree-agent-eperm';
+
+    initRepo(repoDir);
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir, 'eperm-work.txt');
+    mergeIntoMain(repoDir, branchName);
+
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, String(deadPid()));
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockedFile, staleTime, staleTime);
+
+    // Inject an isPidAlive that always throws EPERM — simulates Windows cross-user scenario
+    const epermIsPidAlive = (_pid) => {
+      const err = new Error('EPERM: operation not permitted');
+      err.code = 'EPERM';
+      throw err;
+    };
+
+    const result = reapOrphanWorktrees(repoDir, { isPidAlive: epermIsPidAlive });
+
+    const entry = result.find((r) => canonicalPath(r.path) === canonicalPath(wtDir));
+    if (entry) {
+      assert.notEqual(entry.status, 'reaped', 'EPERM from isPidAlive must be treated as ALIVE — must not reap');
+    }
+    assert.ok(fs.existsSync(wtDir), 'worktree must still exist when isPidAlive throws EPERM');
+  });
+
+  // ── Gap 3: Non-main/master default branch via init.defaultBranch ─────────────
+  test('uses init.defaultBranch config when default branch is not main or master', () => {
+    // Repos configured with init.defaultBranch=trunk (or dev, etc.) were
+    // previously unreachable by the main/master fallback, causing the reaper
+    // to bail out and silently skip all orphan detection.
+    const repoDir = path.join(tmpBase, 'repo3');
+    const wtDir = path.join(tmpBase, 'wt-trunk-default');
+    const branchName = 'worktree-agent-trunk-merged';
+
+    // Create a repo whose default branch is 'trunk'
+    fs.mkdirSync(repoDir, { recursive: true });
+    git(['init'], repoDir);
+    git(['config', 'user.email', 'test@test.com'], repoDir);
+    git(['config', 'user.name', 'Test'], repoDir);
+    git(['config', 'commit.gpgsign', 'false'], repoDir);
+    // Set init.defaultBranch to 'trunk' so the reaper discovers it
+    git(['config', 'init.defaultBranch', 'trunk'], repoDir);
+    fs.writeFileSync(path.join(repoDir, 'README.md'), '# Trunk Test\n');
+    git(['add', '-A'], repoDir);
+    git(['commit', '-m', 'initial commit'], repoDir);
+    // Rename to trunk (may fail if already trunk)
+    try { git(['branch', '-m', 'master', 'trunk'], repoDir); } catch { /* already trunk or main */ }
+    try { git(['branch', '-m', 'main', 'trunk'], repoDir); } catch { /* already trunk */ }
+
+    addWorktree(repoDir, wtDir, branchName);
+    commitInWorktree(wtDir, 'trunk-work.txt');
+    // Merge branch into trunk
+    git(['merge', branchName, '--no-ff', '-m', 'merge into trunk'], repoDir);
+
+    const metaDir = worktreeMeta(repoDir, wtDir);
+    const lockedFile = path.join(metaDir, 'locked');
+    fs.writeFileSync(lockedFile, String(deadPid()));
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    fs.utimesSync(lockedFile, staleTime, staleTime);
+
+    // Pre-compute canonical before reaping (symlink resolution may fail post-removal)
+    const wtDirCanonical = canonicalPath(wtDir);
+
+    const result = reapOrphanWorktrees(repoDir);
+
+    // The reaper must either reap the worktree (using trunk as the default branch)
+    // OR skip it for a safe reason — it must NOT return an empty result (which
+    // would mean it bailed out entirely, silently skipping orphan detection).
+    assert.ok(Array.isArray(result), 'reapOrphanWorktrees must return an array');
+    assert.ok(result.length > 0, 'reaper must not bail out entirely for trunk-default repos — must inspect the worktree');
+    const entry = result.find((r) => canonicalPath(r.path) === wtDirCanonical);
+    assert.ok(entry, 'worktree must appear in results (reaped or skipped with reason)');
+    // The branch IS merged into trunk, and the PID is dead, so it should be reaped.
+    assert.equal(entry.status, 'reaped', 'worktree with dead pid merged into trunk must be reaped');
+  });
+});

tests/workflow-size-budget.test.cjs

@@ -36,7 +36,9 @@ const WORKFLOWS_DIR = path.join(__dirname, '..', 'get-shit-done', 'workflows');
 // in execute-phase.md (1727 → ) and plan-phase.md (1714 → ) from #3178.
 // Follow-up #3182 (TBD): extract MVP-mode bodies to `<workflow>/modes/mvp.md`
 // per the discuss-phase/modes/ precedent and revert this back to 1700.
-const XL_BUDGET = 1800;
+// Bumped from 1800 → 1810 in #3707 to absorb the startup orphan-sweep
+// block added to execute-phase.md (+2 lines: one comment + one bash command).
+const XL_BUDGET = 1810;
 const LARGE_BUDGET = 1500;
 const DEFAULT_BUDGET = 1000;