# Dispatch and poll

`scripts/relay.mjs` wraps Cursor's headless print mode (`cursor-agent -p`), captures its structured
stream, and writes a `result.json`. Run one command, then read one file.

## Before the first run

```bash
command -v cursor-agent
cursor-agent --version
cursor-agent status
```

Follow the installer for your platform at [cursor.com/cli](https://cursor.com/cli), inspect what it
will run, then authenticate with `cursor-agent login`. On Windows the CLI installs as a `.cmd` shim;
the relay handles that launch itself, no setup needed.

## Dispatching

```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
```

`<skill-dir>` is the installed folder containing this skill's `SKILL.md`.

| Flag | Effect |
| --- | --- |
| `--brief <file>` | Brief path. Omit it to read the brief from stdin. |
| `--cd <dir>` | Working root and child process cwd (default: current directory). |
| `--lane <name>` | Fleet lane from `delegate-setup` config. Applies that lane's dials; fails if the lane's `implementer` is not this relay. Explicit dial flags win. |
| `--model <name>` | Cursor model for this run (default: your Cursor default, usually `auto`). Names come from `cursor-agent models`. |
| `--read-only` | Run in Cursor's plan mode: read-only analysis, no edits, no `--force`. |
| `--sandbox <mode>` | Override Cursor's sandbox for this dispatch: `enabled` or `disabled`. |
| `--no-force` | Keep the run write-capable but withhold `--force`; commands requiring approval are refused. |
| `--session <id>` | Resume a specific Cursor chat (`--resume <id>`); send only the delta brief. |
| `--resume-last` | Resume the most recent Cursor chat (`--continue`); send only the delta brief. |
| `--add-dir <dir>` | Add an extra workspace root on Cursor `2026.07.23` or newer. Repeatable. Edits there are not reported in `touchedFiles`. |
| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). cursor-agent has no timeout flag. |
| `--out-dir <dir>` | Artifact directory (default: a fresh directory under the system temp dir). |
| `-h`, `--help` | Print the relay's header help. |

`--session` and `--resume-last` are mutually exclusive. The child cwd pins the primary workspace;
`--add-dir` adds extra workspace roots only.

A fresh run defaults to write-capable with `--force` (commands run without approval unless your
Cursor config denies them). `--no-force` withholds automatic command approval while retaining file
edits; `--read-only` switches to plan mode instead. The relay always passes `--trust` so a headless
run never stalls on the workspace-trust prompt — point `--cd` only at repositories you trust.

## Artifacts and result fields

Artifacts live outside the repo by default, so they do not appear in `touchedFiles`; an `--out-dir`
inside the worktree can make the artifacts appear there:

- `brief.txt` — the exact brief.
- `events.jsonl` — raw cursor-agent stdout events.
- `final.txt` — the final report; absent if none was emitted.
- `stderr.txt` — complete stderr.
- `result.json` — the stable `delegate-relay.result.v1` contract.

`result.json` fields:

- `schema`, `tool` (`"cursor-agent"`), `status` (`completed` | `failed` | `timeout` | `aborted` |
  `cursor_agent_unavailable`), `exitCode`, and `signal` (`null` unless the child died on a signal).
- `workdir`, `model` (the requested name or `null`), `resolvedModel` (the model Cursor actually
  served, from its init event), `permissionMode` (the mode Cursor reported applying), `readOnly`,
  `force`, `sandbox` (the requested value or `null`, not a claim about what Cursor applied),
  `resumed`, `cursorAgentVersion`, `sessionId`, `startedAt`, and `finishedAt`.
- `briefPath`, `finalPath`, `eventsPath`, and `stderrPath`.
- `finalMessage` — the `result` field of Cursor's closing event; when the run died before emitting
  one, the assistant text chunks joined with `"\n\n"` instead. Tool calls and tool results are
  excluded.
- `touchedFiles` — `git status --porcelain` lines for the **final working tree under `--cd` only**,
  not an attribution of Cursor's edits: anything already dirty before dispatch shows up too, and
  edits Cursor makes inside `--add-dir` roots do not show up at all — inspect those trees yourself.
  Dispatch from a clean tree when you want the list to read as "what Cursor changed". `null` means
  git could not report; `[]` means git ran and the tree is clean.
- `usage` — Cursor's token-usage object from the closing result event, or `null` if no result event
  supplied one.
- `stderrTail` — the last 20 non-empty stderr lines on any run that did not complete (`failed`,
  `timeout`, `aborted`), except a launch failure, which reports `failed` with no `stderrTail`.
- `error` — present for launch failures, when the relay watchdog fires (`timeout`), on an `aborted`
  run, and when Cursor's own result event carries `is_error: true`.

## Waiting for completion

The helper blocks. Use the orchestrator's background-command facility, or background it in a shell
and poll for `result.json`. The run is done only when the process exits and the file contains a
`status`.

A pre-run usage error exits 2 and writes no result. A missing `cursor-agent` exits 127 and writes
`status: "cursor_agent_unavailable"`.

## When a run misbehaves

- **`status: "cursor_agent_unavailable"` (exit 127):** install the Cursor CLI, authenticate with
  `cursor-agent login`, and re-dispatch.
- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. If the
  result event carried `is_error: true` the relay reports `failed` even on a zero exit; Cursor's own
  message is in `finalMessage`. An unknown `--model` name fails fast — re-check against
  `cursor-agent models`.
- **A version-preflight failure:** the relay writes `failed` with the probe's exit code, or `timeout`
  with exit 124 when the probe exceeds the smaller of the run watchdog and 10 seconds. Cursor is not
  dispatched.
- **`status: "aborted"`:** the relay itself was killed (its parent's timeout, a stopped task, a
  closed terminal) and forwarded the kill to cursor-agent. The result is written before the relay
  exits; inspect the working tree before re-dispatching. On native Windows a hard kill of the relay
  is uncatchable (Node supports no `SIGTERM` handler there), so this status may never get written —
  a relay process that is gone without a `result.json` is an aborted run; inspect the working tree
  and `events.jsonl` directly.
- **`status: "failed"` with `signal: "SIGKILL"`:** the host killed the process, commonly through the
  OOM killer or a supervisor timeout. This is not a Cursor error; check host memory and re-dispatch,
  or split the task into smaller briefs.
- **`status: "timeout"`:** the `--timeout` watchdog killed the run; `error` reads
  `cursor-agent did not finish within --timeout <dur>; killed by the relay watchdog`. Increase
  `--timeout` or split the task. The relay sends SIGTERM, waits 10 seconds, then sends SIGKILL if
  needed (on Windows a single process-tree kill).
- **Empty `finalMessage`:** inspect `touchedFiles` and the diff. Add a
  `<structured_output_contract>` to the next brief to require a closing report.
- **Every command Cursor runs is rejected with "Hook blocked with message: … eval: … syntax error
  near unexpected token `&`" (or Cursor reports "the terminal hook failed"):** a cursor-agent bug,
  not a hook bug. When cursor-agent is launched from a Git Bash (MSYS) console on Windows — which
  is what an orchestrator's bash tool uses — it selects `bash.exe` as its persistent shell while
  still generating its hook wrappers in PowerShell syntax, so every configured hook (its own
  `~/.cursor/hooks.json` and any imported Claude Code `PreToolUse` hooks) errors and Cursor blocks
  the command, fail-closed. File edits still work; command execution does not — which also means
  Cursor cannot run the gates, only claim it could not. Workaround: dispatch the relay from a
  PowerShell or cmd console instead (observed fixed there); or temporarily remove the hook entries
  for the run. Verified on cursor-agent 2026.07.23.

## Recovering lost work

`events.jsonl` in the run directory records every event the implementer streamed. If finished
work is lost — the run killed late, or the working tree damaged afterward — read the event log
before re-dispatching: it identifies which files and tool commands were involved, which scopes
what needs redoing. Whether it also carries the edit contents depends on what the CLI streams,
so treat any reconstruction as unverified until it matches a working-tree diff — when the tree
still holds the work, preserve the tree rather than replaying the log.

## What the relay runs

The argv is equivalent to:

```bash
cursor-agent --print --output-format stream-json --trust \
  [--force | --mode plan] [--sandbox enabled|disabled] [--model <name>] \
  [--resume <id> | --continue] \
  [--add-dir <dir> ...]   # brief on stdin
```

`--no-force` omits both `--force` and `--mode plan`; the run can edit files, but approval-gated
commands are refused.

The brief rides stdin, so it is not visible in the host process list and has no OS argument-size
cap. On Windows the launch goes through the shell so the `cursor-agent.cmd` shim resolves; the brief
still travels on stdin, sandbox, model, session, and directory values are validated, and spaceable
values are quoted.

## The commit boundary

The relay never commits. Cursor edits the working tree; the orchestrator reviews, re-runs the gates,
and commits. See [review-and-land.md](review-and-land.md).

# Multi-task queues

The single-task loop scales to a queue: a removal across layers, a migration across files, or a
refactor sweep. Sequencing and bookkeeping make it trustworthy.

## Run sequentially, one commit per task

Run tasks **one at a time, in dependency order**, landing each after review and gates before
dispatching the next:

```bash
node "<skill-dir>/scripts/relay.mjs" --brief task-01.txt --cd /path/to/repo
```

- Later briefs can rely on earlier work only after it lands.
- One commit per task keeps history reviewable and each step revertible.
- A clean tree before each dispatch keeps `touchedFiles` honest.

Use parallel runs only for genuinely independent tasks in separate working trees. Sequential is the
default because it preserves clean task boundaries.

## Carry decided constraints forward

Fresh Cursor sessions do not remember earlier tasks. If task 2 chooses a helper name, fixture
location, or interface that task 5 needs, write that fact into task 5's brief.

Use a resumed Cursor session only for rework on the same task. Send a delta brief with
`--resume-last`, or with `--session <id>` from that task's `result.json`. Start unrelated queue items
in fresh sessions.

## Keep a progress file

For more than two or three tasks, maintain one progress file beside the work:

- **Status table** — queued / at-implementer / reviewed+committed, with the commit hash.
- **Per-task review notes** — what landed, what you verified, and gate outcomes.
- **Needs your eyes** — design decisions, non-blocking nitpicks, and questions for the human.
- **End-of-run checklist** — the final cross-task verification.

Update it when each task lands, not in one batch at the end.

## Close with a coherence check

After the last task:

- Run the full test/build once more.
- Search repo-wide for the thing the queue changed.
- Replay migrations from a clean state and check drift when applicable.
- Push and open or update the PR only after the final tree is coherent.

## When to stop and ask

Proceed on work that follows from the agreed plan. Stop and surface when:

- A task cannot be completed correctly within its brief.
- Review calls the plan itself into question.
- Gates reveal a problem affecting already-landed tasks.

Report the landed state, commit hashes, and open question, then wait.

# Review and land

Cursor did the typing; you own the judgment. Verify against reality, never the self-report, and read
the diff as generated code because a green gate cannot catch every failure mode.

## Check tests before trusting gates

If the diff touches existing tests, review those edits first:

- Treat unbriefed test edits as a contract change, not part of the fix.
- Treat newly skipped, disabled, or commented-out tests as failing until proven otherwise.
- Treat loosened assertions the same way: contains/truthy replacing exact matches, broadened error
  types, and widened tolerances all weaken the gate.

## Re-run the gates yourself

`result.json` carries Cursor's claims, not evidence. Re-run the project's actual test, lint, and
build commands in the working tree and read their output. Passing is necessary, not sufficient.

For changes with a specialized verification shape:

- **Migrations or schema:** round-trip them and check for drift.
- **Removals or renames:** grep for dangling references.
- **Stateful behavior:** exercise the behavior, not just compilation.

## Read the diff against the brief

Start with `touchedFiles`, open the diff, and compare it to the brief:

- **Scope creep** — changes the brief excluded.
- **Scope shortfall** — missed behavior, edges, or cleanup.
- **Quiet judgment calls** — defensible but unasked decisions that need review.

## The implementer sweep

Check every diff for patterns gates often miss:

- Hardcoded success or fixture data on a real-work path.
- Catch-all error handling that returns a default instead of propagating or recovering.
- Imports, dependencies, methods, and signatures not present in the installed version.
- Unused imports, uncalled helpers, unreachable branches, and scaffolding comments.
- A second client, error idiom, or logging style beside the repo's existing one.
- Tests that assert internals instead of behavior, or near-duplicate test bodies.
- Optional parameters, config flags, and abstractions with no caller.
- Guards for impossible cases that hide trust-boundary validation.

Send anything blocking back to Cursor as a delta brief, or fix it in the tree, and report either
choice to the human. Run relevant guard skills if installed.

## The commit boundary

When the gates pass and the diff holds, **the orchestrator commits**, never the implementer. Write a
clear message describing what landed.

From dispatch until that commit, the uncommitted working tree is the authoritative copy of the
implementer's work — the only one you can commit from, and often the only copy at all. Never run `git checkout`, `reset`, `clean`, or a branch switch in the
workspace between those two points — however messy an interrupted run looks, inspect it first:
`git status`, `git diff`, `git diff --cached` for anything the implementer staged (plain
`git diff` is blind to the index), and open any untracked files (`??` in `git status`) directly —
they are the implementer's new files, and no diff shows their contents. The tree is evidence,
not clutter. After that inspection the
verdict can legitimately be to discard — work built on a premise you have since corrected, for
example — and then `git checkout`/`clean` is the right tool. The ban is on reflexive cleanup
before anyone has looked.

## Rework: send the delta

Continue the same session with only the correction:

```bash
echo "The fix is right, but the test mocks the DB session. Use the real migrated fixture and remove the
unused import." | node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo
```

Use `--session <id>` instead when resuming the specific id recorded in `result.json`. The relay
rejects `--resume-last` plus `--session` before launch. Rework gets the same gate rerun, test
review, diff review, and implementer sweep.

A resumed run carries the same autonomy flags as a fresh one — write-capable with `--force` by
default, write-capable without automatic command approval under `--no-force`, or plan mode under
`--read-only`. Confirm `touchedFiles` after every fresh or resumed run.

## Surface, do not absorb

The human opted into delegation, so committing verified, gate-passing work is the contract. Keep them
in the loop when the work changes shape:

- Report design decisions and defensible-but-unrequested turns.
- Note non-blocking nitpicks you did not block on.
- Stop and ask if correct completion requires going beyond the brief.

For a queue, keep these notes in the progress file described in
[multi-task-queues.md](multi-task-queues.md).

# Writing the brief

A brief is the entire task as Cursor will see it. It runs in a separate session with **no memory of
your conversation, no access to prior notes, and no shared context** — only the text you send and
whatever it can inspect in the workspace. If a constraint is not in the brief or discoverable in the
repo, it does not exist for Cursor.

## Model choice and resumed sessions

Omitting `--model` uses your Cursor default (usually `auto` — Cursor picks the model). Pass
`--model <name>` only with a name from the account's live `cursor-agent models` output. Do not
invent a name.

A resumed run keeps the session context. Send only the delta brief with `--resume-last` or
`--session <id>`.

## The shape that works

Use a compact, block-structured brief. State the task, what done means, the few constraints that
matter, and the report Cursor must return.

```xml
<task>
One or two sentences: the concrete job and where it lives. Then the specifics - current state, what to
change, and explicitly what to leave untouched. The leave-untouched list prevents unrelated refactors.
</task>

<verification_loop>
Run these before finishing and fix anything they surface, do not just report it:
  <the project's real test command>
  <the project's real lint/format command>
  <the project's real build/typecheck command>
Confirm the working tree shows only the intended changes afterward.
</verification_loop>

<action_safety>
Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
correctness. Do NOT run git add or git commit - the orchestrator commits after reviewing. Leave the
work uncommitted in the working tree.
</action_safety>

<structured_output_contract>
End with a report in this exact shape:
  1. What changed and why
  2. Files touched
  3. Gate outcomes (include test/lint counts)
  4. Anything you deviated on, left open, or want a decision on
</structured_output_contract>
```

Add extra blocks only when the task needs them:

- **Debugging or open-ended fixes** — add `<completeness_contract>` (resolve fully, not just the first
  plausible cause) and `<missing_context_gating>` (find missing repo facts or state what is unknown).
- **Research or recommendations** — add `<research_mode>` (separate observed facts, inferences, and
  open questions).

## Always ask for the report explicitly

The relay builds `finalMessage` from Cursor's closing result event, falling back to its assistant
text stream. Without a closing summary, the edits may exist but the result is hard to review. The
`<structured_output_contract>` block makes the expected report explicit.

## Discover the real gates

Read the repo's `AGENTS.md`, `CLAUDE.md`, `Makefile`, `package.json`, or equivalent first and copy the
actual commands into `<verification_loop>`. A brief that says only "run the tests" makes the
implementer guess or skip them.

## Honor repo conventions

Restate the load-bearing house rules in the brief. Cursor reads the repo's `.cursor/rules` and can
inspect the workspace, but the important constraints should be directly in front of it.

## One task per brief

Keep each brief bounded. One brief -> one Cursor run -> one reviewed commit keeps the diff and
rollback clean. Split mixed implementation, review, documentation, and roadmap requests into separate
dispatches.

## Premises freeze at dispatch

The implementer starts from the brief's facts and there is no steering channel mid-run. Audit the
fact block before sending — ownership, target branch, constraints, anything a judgment call rests
on. If a premise turns out wrong while the run is live, stop the run and re-dispatch a corrected
brief rather than discounting the output afterward; for a write-capable run, inspect the working
tree and reconcile any partial or premise-contaminated edits — keep or revert them — before the
re-dispatch.

## A worked example

```xml
<task>
In the payments service at services/billing/, the refund path double-charges when a refund is retried
after a network timeout. Make refund submission idempotent: check for an existing refund by idempotency
key before creating a new one. Touch only services/billing/refund.py and its tests. Leave the charge
path, API routes, and data models untouched.
</task>

<verification_loop>
Run and make green before finishing:
  pytest tests/billing/ -q
  ruff check services/billing/
Confirm git status shows only refund.py and its test file changed.
</verification_loop>

<action_safety>
Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
changes in the working tree for review.
</action_safety>

<structured_output_contract>
Report: (1) the root cause and fix, (2) files touched, (3) pytest and ruff outcomes with counts,
(4) anything left open or needing a decision.
</structured_output_contract>
```

## Delivery

The relay reads the brief from a file or stdin and feeds it to `cursor-agent` on stdin — it never
rides argv, so it is not visible in the host process list and has no OS argument-size cap. Large
context is still better referenced than inlined: put it in the workspace and tell Cursor which file
to read.

Dispatch with [dispatch-and-poll.md](dispatch-and-poll.md), then review and commit with
[review-and-land.md](review-and-land.md).