# Dispatch and poll

`scripts/relay.mjs` is the dispatch layer. It wraps `agy --print`, runs the brief in Antigravity,
captures the final response, and writes a structured `result.json`. Your job collapses to: run one
command, then read one file.

## Before the first run: check the binary

```bash
command -v agy
agy help
agy models
```

`agy models` proves the CLI can authenticate and list available model labels. The relay records the
version it can infer from `agy changelog` into `result.json`. Neither command proves that a headless
write will be approved.

## Dispatching

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

(`<skill-dir>` is wherever this skill is installed - the folder containing its `SKILL.md`.)

Options:

| Flag | Effect |
| --- | --- |
| `--brief <file>` | The brief. Omit it to read the brief from stdin before passing it to `agy --print`. |
| `--cd <dir>` | Working root for Antigravity (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>` | Antigravity model label. Optional; a fresh run can use Antigravity's configured default. |
| `--effort <level>` | Reasoning effort: `low`, `medium`, or `high` (passed as agy's own `--effort`). |
| `--project <id>` | Use an existing Antigravity project. |
| `--new-project` | Force a fresh Antigravity project. This is the default for fresh dispatches. |
| `--resume-last` | Continue the most recent Antigravity conversation; send only the delta brief. |
| `--conversation <id>` | Continue a specific Antigravity conversation; send only the delta brief. |
| `--sandbox` | Enable Antigravity's terminal sandbox for the run. |
| `--read-only` | Run in plan mode (`--mode plan`), removing write and edit paths; mutually exclusive with `--dangerously-skip-permissions`. |
| `--dangerously-skip-permissions` | Pass Antigravity's permission-bypass flag; mutually exclusive with `--read-only`. Never use this unless the human explicitly accepts it. |
| `--print-timeout <duration>` | Timeout agy itself applies to print mode (default: `30m`). |
| `--timeout <dur>` | Relay-side watchdog (e.g. `30m`); overrides the default of `--print-timeout` plus a 60s grace. On expiry the agy process tree is killed and `result.json` gets `status: "timeout"`. Set it explicitly when agy may hang past its own print timeout. Malformed, zero, and out-of-range durations are rejected; the maximum is `596h31m23s`. |
| `--add-dir <dir>` | Add an extra workspace directory. Repeatable; relative paths resolve against `--cd`. Fresh runs always add the `--cd` repo (absolute path) as a workspace dir. Edits inside extra workspaces are not reported in `touchedFiles`. |
| `--out-dir <dir>` | Where artifacts go (default: a fresh dir under the system temp dir). |

Artifacts default to the system temp dir on purpose: the repo under review stays clean, so the
touched-files report shows only Antigravity's edits and nothing of the helper's own.

## The result

`<out-dir>/result.json` is the contract. Fields:

- `schema` - the result-format version (currently `delegate-relay.result.v1`)
- `tool` - `agy`
- `status` - `completed` | `failed` | `timeout` | `aborted` | `agy_unavailable`
- `exitCode` - mirrors Antigravity's exit code; `128` plus the signal number if the child was killed; `127` if `agy` is not on PATH; on a `timeout` the relay forces a non-zero code even when the child exited `0` after the watchdog's SIGTERM
- `signal` - the signal that killed the child, otherwise `null`
- `agyVersion` - inferred from `agy changelog` when available
- `projectId` / `conversationId` - parsed from the Antigravity log when present
- `finalMessage` - Antigravity's stdout response
- `touchedFiles` - `git status --porcelain` lines in the working root: your review starting point.
  `null` (not `[]`) when git cannot report; `[]` means git ran and the tree is clean
- `readOnlyViolation` - `true` when fingerprints prove a working-tree change, `false` when coverage is complete and proves none, and `null` when fingerprinting was incomplete or the run was not `--read-only`
- `briefPath` / `finalPath` / `logPath` / `stderrPath` - the exact brief, final message, Antigravity
  log, and stderr capture
- `workdir`, `model`, `effort`, `project` (the `--project` you passed, vs `projectId` parsed from the log),
  `sandbox`, `readOnly`, `dangerouslySkipPermissions`, `resumed` (true for a `--resume-last` or `--conversation`
  run), `startedAt`, `finishedAt`
- `stderrTail` - last ~20 stderr lines; present on every run that did not complete (`failed`, `timeout`, `aborted`), except a launch failure, which reports `failed` with no `stderrTail`; also present when `finalMessage` is empty so diagnostics are not discarded
- `error` - present on a launch failure, `timeout`, `aborted`, headless permission denial, or silent no-op

The helper also prints a summary to stdout and normally exits with Antigravity's exit code. It forces
exit 1 when Antigravity exits 0 after a detected headless permission denial or with neither a final
message nor observable working-tree changes, so a wrapping script can branch on success/failure directly.

## Waiting for completion

The helper blocks until Antigravity finishes. Back it with whatever your orchestrator offers:

- **Claude Code:** run the Bash call with `run_in_background: true`; you're notified on completion,
  then read `result.json`.
- **Plain shell / other agents:** foreground for short tasks, or background and poll. A run is done
  when `result.json` exists with a `status`. A pre-run usage error exits with code 2 before writing any
  file, so check the exit code too. A missing `agy` binary exits 127 and writes `result.json` with
  `status: agy_unavailable`.

Trust the working tree and the process state over any progress display. A run is finished when the
process has exited and `result.json` is written.

## When a run misbehaves

- **`status: agy_unavailable` (exit 127):** `agy` is not on PATH. Install the Antigravity CLI and run
  its first-launch setup, then re-dispatch.
- **`status: timeout`:** the relay watchdog killed the run. Inspect `error` to see whether the selected
  limit was explicit `--timeout` or the derived `--print-timeout` plus 60s grace. The working tree may
  hold a half-applied change — inspect it before changing that limit, reducing the brief, or resuming.
- **`status: aborted`:** the relay itself was killed (its parent's timeout, a stopped task, a
  closed terminal) and forwarded the kill to agy. 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 ended the child - commonly the OOM killer
  or a supervisor timeout, not an implementer error. Free up host memory or split the task into
  smaller briefs, then re-dispatch.
- **`status: failed`:** read `result.json`'s `stderrTail`, `stderrPath`, and `logPath` for the cause.
  Common causes: auth lapse, an unknown model label, timeout, or a permission the run needed.
- **Headless write permission denied:** the relay detects Antigravity's `no output produced ...
  auto-denied` stderr sentinel, reports `status: failed`, preserves `stderrTail`, and exits 1.
  Settings allow-rules under `permissions.allow` in `~/.gemini/antigravity-cli/settings.json` do
  apply to `--print` runs, but on Windows a `command(<name>)` rule may be unable to match. See
  [Windows permission engine traps](#windows-permission-engine-traps) below before re-dispatching
  or asking to use `--dangerously-skip-permissions`.
- **Empty `finalMessage`:** a run with edits may still be correct - check `touchedFiles`, the diff, and
  the preserved `stderrTail`. With no observable edits, the relay reports `status: failed` rather than
  claiming completion. To get a report next time, add a `<structured_output_contract>` block (see
  [writing-the-brief.md](writing-the-brief.md)).

## What the helper is doing

Under the hood the helper runs roughly:

```bash
agy --new-project --add-dir <repo> --print-timeout 30m --print=<brief>
agy --continue --print-timeout 30m --print=<delta brief>
agy --conversation <id> --print-timeout 30m --print=<delta brief>
```

`agy --print` requires the prompt as a flag argument, so keep briefs focused. The relay still accepts
stdin or `--brief <file>` for your convenience; it reads the text first, then passes it to `agy` as
`--print=<brief>` (the `=` form so a brief that begins with a bare flag like `--help` still runs).
Two consequences of the brief riding the command line: it is visible in the host process list (`ps`),
so on a shared machine keep secrets out of it; and a brief over ~120 KB is rejected up front (the OS
caps a single argument), so have `agy` read large context from the workspace instead of inlining it.

## The commit boundary

The helper never commits - by design, not omission. The robust contract is: Antigravity edits the
working tree, the orchestrator reviews and commits. See [review-and-land.md](review-and-land.md).

## Windows permission engine traps

When a headless `--print` run needs a permission `agy` cannot prompt for, it is auto-denied. `agy`'s
error message advises adding an allow-rule under `permissions.allow` in `~/.gemini/antigravity-cli/settings.json`,
e.g. `command(<target>)`. Allow-rules do apply in `--print` mode (a `write_file` rule naming the workspace is
what let a headless write run succeed here), but on Windows that instruction frequently cannot work due to an
open upstream defect in Antigravity's permission engine ([issue #614](https://github.com/google-antigravity/antigravity-cli/issues/614)).

### Executable path splitting

The permission engine splits a resolved executable path on whitespace before matching, so a binary living under a path
containing a space is evaluated as its first fragment. `node`, `git` and `npm` installed under `C:\Program Files\...`
are all evaluated as `C:\Program`, and no `command(<name>)` rule matches any of them. Measured directly on Windows 10
with agy 1.1.12: with `command(node)` present in the allow list, a brief whose verification loop ran `node --check`
was auto-denied anyway.

### Write file glob error

Upstream issue #614 also reports that a glob in a `write_file` rule - `write_file(C:\path\*)` - raises "globs not supported"
and blocks the agent's actions entirely. Directory rules are recursive already, so the glob is unnecessary as well as harmful.

### Workarounds and caveats

The workarounds documented in issue #614:

- **Command permissions:** `command(*)` matches commands where the executable path contains spaces. A deny list still
  applies over `command(*)`, because deny is evaluated above allow. Note that `command(*)` widens permission to
  auto-approve all command execution.
- **Directory permissions:** Write directory paths literally without a wildcard, e.g. `write_file(C:\path)`.

If settings allow-rules cannot resolve the denial, ask the human before re-dispatching with `--dangerously-skip-permissions`;
that flag auto-approves every tool permission request and the run must be treated as full access.

# Multi-task queues

The single-task loop scales to a queue, and that is where delegation pays off most - a removal split
across layers, a migration touching many files, a refactor sweep. The discipline that makes a queue
trustworthy is sequencing and bookkeeping, not parallelism.

## Run sequentially, one commit per task

Run tasks **one at a time, in dependency order**, landing each (review + gates + commit) before
dispatching the next. Three reasons:

- **Later tasks assume earlier ones landed.** Task 3's brief can say "the X added in the previous step
  exists" only if the previous step actually committed.
- **One commit per task** keeps the history reviewable and any single step revertible.
- **Each review is honest.** A clean working tree before each dispatch means the next task's
  `touchedFiles` shows only *its* changes.

Parallelism is occasionally worth it for genuinely independent tasks on separate files, but it
sacrifices the clean-tree-per-task property and makes review harder. Default to sequential.

## Carry decided constraints forward

Implementation surfaces facts the original plan did not have: a helper got named, a fixture lives in a
specific place, an interface was chosen. When a later task depends on one of those, fold it into that
task's brief as an explicit line. A fresh Antigravity conversation has no memory of the earlier run, so
a constraint that emerged in task 2 must be restated in task 5's brief or it will not hold.

## Keep a progress file

For anything longer than two or three tasks - especially a run the human steps away from - maintain a
single progress file alongside the work:

- **Status table** - each task: queued / at-implementer / reviewed+committed (with the commit hash).
- **Per-task review notes** - what landed, what you verified, the gate outcome.
- **Needs your eyes** - design decisions Antigravity made, non-blocking nitpicks, anything you want the
  human to overrule or confirm.
- **End-of-run checklist** - what happens after the last task.

Update it as each task lands, not in a batch at the end.

## Close with a coherence check

Per-task review proves each step in isolation; it does not prove the steps cohere. After the last task,
verify the whole:

- Run the full test/build once more on the final tree.
- Do a repo-wide check for the thing the queue was about.
- For schema work, replay all the new migrations from a clean state and check for drift.
- Then push and open or update the PR, with a description that reflects what actually shipped.

## When to stop and ask

Proceed without asking on anything that follows from the agreed plan. Stop and surface when:

- A task cannot be completed correctly within its brief's scope.
- A review finds something that calls the *plan* into question, not just the implementation.
- The gates reveal a problem that affects tasks already done.

Then report where you are, what is committed, and what the open question is - and wait.

# Review and land

Antigravity did the typing; you own the judgment. Verify against reality, never against the self-report
- and read the diff as generated code, which fails in ways a green gate cannot see.

## Check the tests before trusting the gates

If the diff touches existing tests, review those edits *first* - before the gate re-run means anything.
A weakened assertion, an added skip, or a deleted test makes the gate measure less than it did before
the run.

- **Unbriefed edits to existing tests are a contract change, not part of the fix.** Flag them, don't
  absorb them.
- **Skipped, disabled, or commented-out tests added in this diff:** treat the underlying test as
  failing until proven otherwise.
- **Loosened assertions** (exact match relaxed to contains/truthy, error-type checks broadened,
  tolerance widened): same treatment.

## Re-run the gates yourself

`result.json` carries Antigravity's own claims. Treat them as claims, not evidence - re-run the
project's actual test/lint/build commands in the working tree and read the output. Passing is necessary,
not sufficient.

For changes with their own verification shape, go further:

- **Migrations / schema:** round-trip them and check for drift.
- **Removals / renames:** grep the codebase for dangling references.
- **Anything stateful:** exercise the actual behavior, don't just confirm it compiles.

## Read the diff against the brief

Open the diff (`touchedFiles` in the result is your starting list) and hold it against what you asked
for:

- **Scope creep** - did Antigravity change things the brief said to leave untouched?
- **Scope shortfall** - did it do the whole task, including edge cases and cleanup?
- **Quiet judgment calls** - did it make a defensible but unasked decision you need to understand?

## The implementer sweep

Generated code fails in systematic ways that gates are structurally blind to. Walk these against every
diff before you commit:

- **Hardcoded success or fixture data** on a path the brief says does real work.
- **Catch-all error handling that returns a default** instead of propagating or recovering explicitly.
- **Unverified imports and API calls** - confirm new dependencies, methods, and signatures exist in the
  installed version.
- **Dead weight** - unused imports, helpers nothing calls, unreachable branches, scaffolding comments.
- **A second way to do what the file already does** - new client, error idiom, or logging style beside
  an existing one.
- **New tests that assert internals** instead of behavior.
- **Near-duplicate test bodies** differing by one value.
- **Speculative surface** - optional parameters, config flags, or abstractions with no caller.
- **Guards for impossible cases** that bury validation that matters at real trust boundaries.

Anything the sweep catches goes back to Antigravity as a delta brief or gets fixed in the tree before
commit - and either way is reported to the user.

If the `guard-skills` package is installed, run the relevant guard on the diff for the full treatment.

## The commit boundary

When the gates pass and the diff holds, **you commit** - the orchestrator, never the implementer. Write
a clear message describing what landed. If your project attributes co-authorship, that is the place for
it.

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.

## Reworking: send the delta, not the whole task

If the review turns up problems, don't restate the entire brief. Continue the same Antigravity
conversation with just the correction:

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

`--resume-last` keeps Antigravity's conversation context from the first run, so a short delta is enough.
Then review again - rework gets the same gate-rerun, test check, diff-read, and sweep as the original,
no shortcuts.

## Surface, don't absorb

The human opted into delegation, so committing verified, gate-passing work is the agreed contract. But
keep them in the loop on anything that changes the shape of the work:

- **Report design decisions** Antigravity made, and any defensible-but-unrequested turns it took.
- **Note non-blocking nitpicks** you chose not to block on, so the human can overrule you.
- **Stop and ask** if correct completion requires going beyond the brief.

For a multi-task run, capture these in the progress file rather than letting them scroll past - see
[multi-task-queues.md](multi-task-queues.md).

# Writing the brief

A brief is the entire task as Antigravity will see it. It runs in a separate conversation with **no
memory of your conversation, no access to your 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 Antigravity.

## Model choice

`agy` has a configured default model, so a fresh dispatch does not require `--model`. Pass `--model`
only when the human has named a preferred Antigravity model label for this task. `agy models` shows the
available labels.

A resumed run keeps the conversation context. Send only the delta brief.

## The shape that works

Antigravity responds well to compact, block-structured prompts with XML tags rather than long prose.
State the task, what "done" looks like, how to behave by default, and the few constraints that actually
matter. Add a block only when the task needs it.

```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 is what keeps Antigravity
from wandering into unrelated refactors.
</task>

<verification_loop>
Run these before finishing and fix anything they surface, don't 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 (paste the test/lint counts)
  4. Anything you deviated on, left open, or want a decision on
</structured_output_contract>
```

That four-block skeleton covers most implementation tasks. Reach for extra blocks when the task profile
calls for them:

- **Debugging / open-ended fixes** - add `<completeness_contract>` (resolve fully, don't stop at the
  first plausible fix) and `<missing_context_gating>` (don't guess missing repo facts; find them or
  state what's unknown).
- **Research / recommendations** - add `<research_mode>` (separate observed facts, inferences, open
  questions).

## Always ask for the report explicitly

The relay captures `agy --print` stdout as `finalMessage`. If Antigravity finishes without a closing
summary, the result is not useful to review. The `<structured_output_contract>` block is what guarantees
a report you can read.

## Discover the real gates

`<verification_loop>` is only useful if it names the project's *actual* commands. Read the repo's
`AGENTS.md` / `CLAUDE.md` / `Makefile` / `package.json` first and copy the real ones in (`make test`,
`npm run lint`, `cargo test`, `pytest -q`, whatever it is). A brief that says "run the tests" without
naming them gets you an implementer that guesses - or skips.

## Honor the repo's conventions

If the project has house rules in `AGENTS.md`, `CLAUDE.md`, or a similar file, restate the load-bearing
ones in the brief. Antigravity can inspect the workspace, but compliance is more reliable when the
important rules are directly in front of it.

## One task per brief

Keep each brief to a single, bounded job. "Review this, fix what you find, update the docs, and suggest
a roadmap" produces a muddled run; split it into separate dispatches. One brief -> one Antigravity run
-> one commit keeps review and rollback clean.

## 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 your fix, (2) files touched, (3) pytest + ruff outcomes with counts,
(4) anything you left open or want decided.
</structured_output_contract>
```

Send this with `relay.mjs` (see [dispatch-and-poll.md](dispatch-and-poll.md)); review the result and
commit it yourself (see [review-and-land.md](review-and-land.md)).