Cursor Agent CLI Dispatch

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

Hard Constraints (from testing)

Constraint	Value	Source
PTY required	INLINECODE1 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

CODEBLOCK0

Mode	Flags	Timeout	Use
Plan	INLINECODE3	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

CODEBLOCK1

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

CODEBLOCK2

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

CODEBLOCK3

Orphan Detection

Cursor agent processes that outlive their exec session become orphans:
CODEBLOCK4

Four Dispatch Chains

Chain A: Direct Execute

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

CODEBLOCK5

Chain B: Plan → Review → Execute ⭐

For complex tasks. Most reliable chain.

CODEBLOCK6

Chain C: Parallel Batch

For independent tasks across different files. Use background exec.

CODEBLOCK7

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.

CODEBLOCK8

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

CODEBLOCK9

Model Selection

Task	Model	Timeout
Default	INLINECODE8	—
Simple edits

auto | 120s | | Complex analysis | auto + --plan | 180s | | Code review | auto + --mode ask | 120s |

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

Session Resume

CODEBLOCK10

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)

CODEBLOCK11

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:
CODEBLOCK12

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.