Cursor Dispatch

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

text

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

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

text

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

text

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

text

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:

bash

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

Four Dispatch Chains

Chain A: Direct Execute

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

text

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

Chain B: Plan → Review → Execute ⭐

For complex tasks. Most reliable chain.

text

Step 1 — PLAN (pty:true, timeout:180):
  "检查 <file> 中会导致运行时崩溃的问题。重点：<specific concerns>。只列会崩溃的。"

Step 2 — REVIEW (agent decides):
  Parse output → grade 🔴🟠🟡🟢 → select fixes for this round

Step 3 — EXECUTE (pty:true, timeout:180):
  "修复 <file> 中 N 个问题：[paste selected items with line numbers and fix code]。
   修复后运行：<verify command>。确认无错误后 git commit。"

Step 4 — VERIFY:
  Run headless build/test to confirm

Chain C: Parallel Batch

For independent tasks across different files. Use background exec.

text

# 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.

text

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

text

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

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

bash

cursor agent ls                              # List past sessions
cursor agent -p --trust --continue "..."     # Continue last
cursor agent -p --trust --resume <id> "..."  # 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)

text

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:

text

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.