Windows MAX_PATH error blocks 'git worktree remove' — orch should fall back to 'cmd rd /s /q'

[HenryLach]

Summary

On Windows, git worktree remove --force fails with error: failed to delete '<path>': Filename too long when removing taskplane's deeply nested worker worktrees (typically <repo>/.worktrees/henrylach-<batch-id>/lane-N/). The failure is caused by Windows' default MAX_PATH = 260 limit being exceeded by the worktree's node_modules paths.

After the orch's worktree-removal fails, the worktree is left orphaned on disk (registered as removed in git but the directory persists), consuming disk space and potentially confusing future operations. The orch reports cleanup-incomplete via the post-integration banner but doesn't recover.

A reliable workaround exists (cmd /c "rd /s /q <path>"), which uses a different code path that doesn't hit MAX_PATH the same way.

Reproduction

1. On a Windows host with default settings (core.longpaths = false).
2. Run any taskplane batch that performs a npm install inside the worktree (most non-trivial Node projects).
3. Worker completes; orch fast-forwards merge.
4. Orch attempts to remove the worktree:

   git worktree remove --force C:/dev/<repo>/.worktrees/henrylach-<batch-id>/lane-1
   

5. Fails with: error: failed to delete 'C:/dev/<repo>/.worktrees/henrylach-<batch-id>/lane-1': Filename too long

Concrete evidence

Production batches 20260506T105850 and 20260506T131717 (both on the same Emailgistics-astro repo, ~700 npm dependencies, deeply nested):

$ git worktree remove --force C:/dev/emailgistics-astro/.worktrees/henrylach-20260506T105850/lane-1
error: failed to delete 'C:/dev/emailgistics-astro/.worktrees/henrylach-20260506T105850/lane-1': Filename too long

Followed by orch_integrate reporting:

⚠️ Cleanup incomplete — residual artifacts found:
  (default): 1 non-empty .worktrees/ container(s)

The supervisor recovered with:

$ cmd //c "rd /s /q C:\dev\emailgistics-astro\.worktrees\henrylach-20260506T105850"
(succeeds silently)

The cmd rd /s /q command bypasses MAX_PATH in practice (the cmd shell's deletion code path uses different APIs that handle long paths better than git's libc-style unlink chain).

Why this matters

Every Windows-based taskplane operator hits this on every batch with a large node_modules. Symptoms:

1. Orch's post-merge cleanup banner shows Cleanup incomplete after every batch (operator UX clutter).
2. Disk fills with abandoned worktrees over time (until the operator notices and manually cleans).
3. Operators eventually learn the cmd rd /s /q trick or enable Windows long-path support — but neither is documented.

The Emailgistics-astro repo had to do this twice during a single recovery flow (2 dead worktrees from 2 batches). Across many batches, the cumulative friction adds up.

Fix proposals

A. Detect and fall back to cmd rd on Windows

In the orch's worktree-removal code (probably in lane-runner.ts or worktree.ts):

async function removeWorktree(path: string): Promise<void> {
  const result = execCheck(`git worktree remove --force "${path}"`);
  if (!result.ok && process.platform === 'win32' && /Filename too long/i.test(result.stderr)) {
    // Fallback: cmd's rd handles long paths via its own deletion code path.
    execCheck(`cmd /c "rd /s /q "${path.replace(/\//g, '\\')}""`);
  }
}

This is local to the orch's worktree-cleanup code path; doesn't require any Windows configuration changes by the operator.

B. Document the Windows long-path enablement

Add to the taskplane setup docs (or a new docs/windows.md):

Windows operators: taskplane creates deeply nested worktrees that can exceed Windows' default 260-character path limit. To avoid git worktree remove failures during cleanup, enable long-path support either:

1. Globally (recommended): run git config --system core.longpaths true (administrator)
2. Per-repo: git config core.longpaths true in the project root

Additionally, set the OS-level long-path support via group policy or PowerShell:
Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1

C. Expose a manual orch_cleanup_worktrees() operator tool

For times when the auto-cleanup misses something (regardless of OS), provide an operator-callable tool that scans .worktrees/ for directories not registered with git worktree list and offers to remove them. Useful belt-and-suspenders even with A/B in place.

Recommendation

Ship A. It's a small, contained code change in the orch's worktree-cleanup path with no operator burden. B is useful documentation regardless. C is a nice-to-have for resilience.

Why this is P3 not higher

This is annoying but not blocking — the orch's cleanup-incomplete banner is informational, the worktrees don't break anything until disk fills, and the cmd rd /s /q workaround is reliable. It's a polish issue more than a correctness issue.

Acceptance criteria

• On Windows, git worktree remove failures from MAX_PATH automatically retry via cmd rd /s /q.
• The cleanup-incomplete banner only fires when both the primary path and the fallback failed.
• Test (Windows-only or skipped on other platforms): create a worktree with node_modules longer than 260 chars; run worktree removal; assert the cleanup succeeds.

Related

• Tangentially related to issue orch_resume(force=true) cannot reattach to a stopped batch after orch_abort() #539 — the operator's recovery path from the failed batch had to fight this on top of everything else.

Affected version: taskplane@0.28.4 on Windows. Reproducible on any project with a large node_modules tree.