Cursor Dispatch

---

name: cursor-dispatch description: "Orchestrate Cursor Agent CLI for coding tasks with concurrency control, timeout recovery, and multi-task coordination. Use when: (1) dispatching coding tasks to cursor agent via CLI, (2) analyzing code before modifying (plan mode), (3) running parallel batch coding tasks with concurrency limits, (4) coordinating multi-step code changes with review gates, (5) recovering from stuck/timeout cursor processes. Triggers: cursor dispatch, plan then execute, code analysis pipeline, batch coding tasks, cursor agent orchestration, parallel coding, concurrent tasks."

---

Cursor Agent CLI Dispatch

Orchestrate cursor agent CLI with concurrency control, timeout recovery, and retry.

Hard Constraints (from testing)

| Constraint | Value | Source | |-----------|-------|--------| | PTY required | pty: true mandatory | No output without PTY | | Max safe concurrency | 6 parallel tasks | Tested 8 OK, 6 is safe margin | | Plan timeout (single file) | 60-120s | Tested on .gd files | | Plan timeout (multi-file) | >180s, WILL timeout | Don't attempt | | Execute timeout | 60-90s typical | Up to 180s for complex | | --output-format json | BROKEN in PTY | Use text format only | | Empty output = failure | Check output size > 20 bytes | Retry if empty |

Command Template

exec(
  command: "cd  && cursor agent -p --trust [FLAGS] --model auto --workspace . ''",
  pty: true,
  timeout: 
)

| Mode | Flags | Timeout | Use | |------|-------|---------|-----| | Plan | --plan | 180s | Read-only analysis | | Execute | --yolo | 180s | Auto-approve changes | | Ask | --mode ask | 120s | Q&A, no changes |

Concurrency Control Protocol

State Tracking

Before launching cursor tasks, track them via process(action=list). Each running exec session with cursor agent counts toward the limit.

Launch Rules

1. Check: process(action=list) → count sessions with "cursor agent" in command
2. If count >= MAX_CONCURRENT (default 4, max 6): WAIT or QUEUE
3. Launch: exec(command=..., pty=true, timeout=T, background=true)
4. Record: sessionId + taskId + startTime
5. Poll: process(action=poll, sessionId=X, timeout=T*1000)

Concurrency Limits by Task Type

| Scenario | Max Concurrent | Why | |----------|---------------|-----| | Plan-only (read) | 6 | No file conflicts | | Execute (write) | 3 | Avoid git/file conflicts | | Mixed plan+execute | 4 | Balance safety and speed | | Same-file tasks | 1 (serial only) | NEVER parallel on same file |

Timeout & Recovery Protocol

Detection

A task is stuck when:

process(action=poll, timeout=T) returns with process still running after timeout

Exit code 143 (SIGTERM) or 137 (SIGKILL) = was killed by timeout

Output is empty (< 20 bytes) after completion = silent failure

Recovery Steps

1. DETECT: poll returns "still running" or exit 143/137 or empty output
2. KILL: process(action=kill, sessionId=X)
3. WAIT: 3 seconds cooldown (avoid API rate limits)
4. SIMPLIFY: reduce prompt scope (fewer files, simpler question)
5. RETRY: relaunch with simplified prompt, same or higher timeout
6. MAX RETRIES: 2 attempts total. After 2 failures → report to user

Simplification Strategy

When a task times out, simplify before retrying:

| Original | Simplified | |----------|-----------| | "Scan all dungeon scripts for bugs" | "Scan dungeon_manager.gd for null refs" | | "Fix 5 issues in this file" | "Fix issue #1 and #2 only" | | "Analyze architecture of combat system" | "List all functions in arpg_monster.gd" |

Cleanup Protocol

When to Clean Up

Before starting a new batch of tasks

After any task failure

On session start (check for orphans)

How to Clean Up

1. process(action=list) → find all cursor-related sessions
2. For each: check if still running
3. If running > 10 minutes: process(action=kill, sessionId=X)
4. Verify: ps aux | grep "cursor agent -p" | grep -v grep
5. Nuclear option: pkill -f "cursor agent -p" (kills ALL cursor CLI agents)

Orphan Detection

Cursor agent processes that outlive their exec session become orphans:

# Find orphan cursor agent processes
ps aux | grep "cursor agent -p" | grep -v grep
Kill specific orphan
kill 

Four Dispatch Chains

Chain A: Direct Execute

For simple tasks (1-3 files, clear logic). Single exec call.

exec(
  command: "cd  && cursor agent -p --trust --yolo --model auto --workspace . ''",
  pty: true, timeout: 180
)
→ poll → verify output not empty → done

Chain B: Plan → Review → Execute ⭐

For complex tasks. Most reliable chain.

Step 1 — PLAN (pty:true, timeout:180):
  "检查  中会导致运行时崩溃的问题。重点：。只列会崩溃的。"
Step 2 — REVIEW (agent decides):
  Parse output → grade 🔴🟠🟡🟢 → select fixes for this round
Step 3 — EXECUTE (pty:true, timeout:180):
  "修复  中 N 个问题：[paste selected items with line numbers and fix code]。
   修复后运行：。确认无错误后 git commit。"
Step 4 — VERIFY:
  Run headless build/test to confirm

Chain C: Parallel Batch

For independent tasks across different files. Use background exec.

# Launch (respect concurrency limit)
exec(cmd="cursor agent ... task1", pty:true, background:true) → session1
exec(cmd="cursor agent ... task2", pty:true, background:true) → session2
exec(cmd="cursor agent ... task3", pty:true, background:true) → session3
Monitor
process(action=poll, sessionId=session1, timeout=180000)
process(action=poll, sessionId=session2, timeout=180000)
process(action=poll, sessionId=session3, timeout=180000)
Verify all
Run headless build/test

Rules:

Max 4 parallel execute tasks (6 for plan-only)

NEVER parallel on same file

Check for git conflicts after all complete

If any fails: kill remaining → fix conflict → retry failed ones

Chain D: Plan Global → Serial Execute

For large refactors with dependencies.

1. Plan pass on each file (can parallel, up to 6)
2. Collect all findings → sort by dependency
3. Execute in dependency order (serial)
4. Verify after each execute before next
5. If verify fails: stop, fix, re-plan remaining

Prompt Engineering for Cursor Agent

Plan Prompts (what works)

Good: "检查 scripts/dungeon/dungeon_manager.gd 中所有可能返回 null 的函数调用，以及调用方是否有 null 检查" Good: "列出 中所有 func 的名字" Bad: "扫描所有文件找出所有问题" (too broad, will timeout)

Execute Prompts (what works)

Good: Include exact line numbers + expected code change + verify command + git commit Bad: Vague "fix the bugs" without specifics

Template

Plan: "检查  中 。只列会崩溃/卡死的问题，给出行号和修复方案。"
Execute: "修复  中 N 个问题：
1. 第 X 行： → 
2. 第 Y 行： → 
修复后运行：
确认无错误后 git commit -m ''。"

Model Selection

| Task | Model | Timeout | |------|-------|---------| | Default | auto | — | | Simple edits | auto | 120s | | Complex analysis | auto + --plan | 180s | | Code review | auto + --mode ask | 120s |

auto routes to best available model (typically opus-4.6-thinking). Don't override unless needed.

Session Resume

cursor agent ls                              # List past sessions
cursor agent -p --trust --continue "..."     # Continue last
cursor agent -p --trust --resume  "..."  # Resume specific

Timing Benchmarks

v2.6.12 (tested 2026-03-06 evening, cursor 2.6.12)

| Task Type | Time | Concurrency Tested | |-----------|------|--------------------| | List functions (small file <50 lines) | 8-14s | 6/6 parallel ✅ | | List functions (medium file ~600 lines) | 17s | single ✅ | | List functions (large file ~1000 lines) | 40s | single ✅ | | Simple execute (add comment, 1 file) | 16-19s | 3/3 parallel ✅ | | Ask mode (simple Q&A) | 8s | single ✅ | | Complex analysis (null-check scan, 660 lines) | 84s | single ✅ | | Long complex prompt (3+ concerns, multi-file ref) | >180s | TIMEOUT ⚠️ | | Execute with broad prompt (3 bugs, multi-concern) | >180s | TIMEOUT ⚠️ |

Key Findings (v2.6.12)

Simple tasks (list/comment/ask) are MUCH faster than v2026.02.27 (8-40s vs 55-120s)

Complex analysis still takes 60-120s — similar to old version

Broad prompts (3+ separate concerns) STILL timeout — must split into 1-concern-per-task

Silent failures (empty output) reduced but still occur on timeout

6 parallel plan = all pass in ~53s wall clock (individual 8-14s each)

3 parallel execute = all pass in ~25s wall clock (individual 16-19s each)

Failure Mode: Prompt Complexity (NOT concurrency)

Timeouts correlate with prompt complexity, not concurrency:

6 simple tasks parallel → all pass in <20s each

1 complex task with 3+ concerns → timeout at 180s

Solution: ALWAYS split multi-concern prompts. One concern per cursor task.

Previous version (v2026.02.27, tested 2026-03-06 morning)

| Task Type | Time | Concurrency Tested | |-----------|------|--------------------| | List functions (1 file) | 15s | 8/8 passed | | Null-check scan (1 file) | 80-120s | 4/4 parallel ✅ | | Execute fix (1 file, 1-4 issues) | 55-90s | 3/3 parallel ✅ | | Multi-file analysis | >180s | TIMEOUT |

Validated Workflows

Workflow 1: Parallel Plan → Review → Parallel Execute (2026-03-06)

Round 1 (Chain B serial): 3 files × plan→execute = 9 fixes, 3 commits
Round 2 (Chain C parallel): 4 files × plan (parallel) → review → 3 files × execute (parallel) = 3 fixes, 3 commits
Total: 12 runtime crash risks fixed, 6 commits, Godot headless zero errors

Workflow 2: Skip Plan, Direct Execute (2026-03-06 evening)

When you already know exactly what to change, skip Plan and go straight to Execute:

3 parallel Execute (different files) = all pass, 16-19s each
Pre-requisite: dispatcher already analyzed the code and wrote precise prompts

Key insight: Plan can always be parallelized (read-only). Execute can be parallelized only when tasks touch different files. Review is always serial (agent decides). Critical: Keep prompts focused — 1 file, 1 concern, specific line numbers.

For model list and CLI parameters, see references/models-and-params.md.