fix: add Windows troubleshooting for plan-phase freezes (#732)

Windows users experience plan-phase freezes due to Claude Code stdio
deadlocks with MCP servers. When a subagent hangs, the orchestrator
blocks indefinitely with no timeout or error.

Adds:
- Windows troubleshooting section to plan-phase.md with:
  - Orphaned process cleanup (PowerShell commands)
  - Stale task directory cleanup (~/.claude/tasks/)
  - MCP server reduction advice
  - --skip-research fallback to reduce agent chain
- Stale task directory detection to health.md (I002 diagnostic)
  - Reports count of stale dirs on --repair
  - Safe cleanup guidance

Closes #732
This commit is contained in:
Tom Boucher
2026-03-18 17:13:55 -04:00
parent a9be67f504
commit 297adf8425
2 changed files with 46 additions and 0 deletions

View File

@@ -157,3 +157,25 @@ Report final status.
- Orphaned plan cleanup
</repair_actions>
<stale_task_cleanup>
**Windows-specific:** Check for stale Claude Code task directories that accumulate on crash/freeze.
These are left behind when subagents are force-killed and consume disk space.
When `--repair` is active, detect and clean up:
```bash
# Check for stale task directories (older than 24 hours)
TASKS_DIR="$HOME/.claude/tasks"
if [ -d "$TASKS_DIR" ]; then
STALE_COUNT=$(find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null | wc -l)
if [ "$STALE_COUNT" -gt 0 ]; then
echo "⚠️ Found $STALE_COUNT stale task directories in ~/.claude/tasks/"
echo " These are leftover from crashed subagent sessions."
echo " Run: rm -rf ~/.claude/tasks/* (safe — only affects dead sessions)"
fi
fi
```
Report as info diagnostic: `I002 | info | Stale subagent task directories found | Yes (--repair removes them)`
</stale_task_cleanup>

View File

@@ -737,6 +737,30 @@ Verification: {Passed | Passed with override | Skipped}
───────────────────────────────────────────────────────────────
</offer_next>
<windows_troubleshooting>
**Windows users:** If plan-phase freezes during agent spawning (common on Windows due to
stdio deadlocks with MCP servers — see Claude Code issue anthropics/claude-code#28126):
1. **Force-kill:** Close the terminal (Ctrl+C may not work)
2. **Clean up orphaned processes:**
```powershell
# Kill orphaned node processes from stale MCP servers
Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force
```
3. **Clean up stale task directories:**
```powershell
# Remove stale subagent task dirs (Claude Code never cleans these on crash)
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\tasks\*" -ErrorAction SilentlyContinue
```
4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json
5. **Retry:** Restart Claude Code and run `/gsd:plan-phase` again
If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents:
```
/gsd:plan-phase N --skip-research
```
</windows_troubleshooting>
<success_criteria>
- [ ] .planning/ directory validated
- [ ] Phase validated against roadmap