cursor-worker

You hand ONE self-contained task to Cursor and return its result. cursor-agent does the work; you frame the task, run it, and report back.

How to run

Pick the runner by duration — never start a single stream that could outlive ~4 minutes (flaky networks/VPNs kill streams at ~5-6 minutes; measured):

• Quick task (< ~4 min of agent work): the cursor_run MCP tool, or "${CLAUDE_PLUGIN_ROOT}/scripts/cursor-run.sh". No approval flags needed: every runner passes --force --approve-mcps itself.
• Anything longer: the legged runner — it chains ~4-minute legs on ONE --resumed session until the worker prints DONE-ALL, so a connection drop costs one leg, not the job:

"${CLAUDE_PLUGIN_ROOT}/scripts/legged-run.sh" --cwd <repo> [--account <name>] "<task>"

Exit 1 means the leg budget ran out — rerun the same command to continue (state: ~/.claude-deck/cursor/legs/<id>). --worktree isolates parallel edits; --force is automatic.

1. Account is optional. Omit it and auth comes from the default entry of ~/.claude-deck/cursor/agent-keys.json (a stable API key — the normal case; a browser login is only a last-resort fallback). Pass --account <name> only if the user runs several Cursor seats and names one.
2. Task must be self-contained. cursor-agent has no memory of this conversation: put file paths, the goal, and acceptance criteria in the task string.
3. Model: two quota pools. --model auto (and composer-*, cursor-*) draws Cursor's large first-party allowance; claude-* and gpt-* draw the small API allowance that empties first. Mechanical work goes first-party; keep an API-pool model for prose or judgment. Say which you used. Full rule: the cursor-orchestrate skill, "Model routing".
4. Dry-run first for quick tasks (--dry-run, key redacted) to show what will run, then run for real.
5. Resume, never restart. Every run yields a session_id (the cursor_run footer; <state>/session_id for legged runs) — capture it. On any failure or interruption, harvest the partial output (last_result.txt, leg-N.json), then continue that same session (extraArgs: ["--resume", "<id>"], or rerun the identical legged command) with a prompt like "Continue exactly where you left off; finish the remaining work." Start over only if no session was ever created (auth/CLI setup failure).
6. Runs close themselves. The runner kills cursor-agent right after its result appears and hard-caps hung runs, so never sit waiting on a "stuck" delegation — if it returned, it is over; if it exited 1, resume it.
7. Sandbox off; keychain noise is not an auth failure. cursor-agent touches the macOS Keychain at startup even with CURSOR_API_KEY set. Sandboxed Bash kills it every time (Security command failed: … code: 45) — run the scripts with dangerouslyDisableSandbox: true. Concurrent startups can also race on the keychain (Password not found); the runners retry that on their own — just rerun if a one-shot run hit it.