# Dispatch and poll

`scripts/relay.mjs` wraps Qoder's non-interactive print mode with `stream-json` output, captures raw
output, and writes a stable `result.json`.

## Before the first run

```bash
command -v qodercli
qodercli --version
qodercli --list-models
```

Install and authenticate using Qoder's
[official Quick Start](https://docs.qoder.com/en/cli/quick-start). Use `qodercli login` interactively or
`QODER_PERSONAL_ACCESS_TOKEN` for automation.

## Dispatch

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

| Flag | Effect |
| --- | --- |
| `--brief <file>` | Brief path; omit to read stdin. |
| `--cd <dir>` | Primary working root and child cwd; defaults to 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>` | Exact live model value from `qodercli --list-models`; omit for Qoder's default. |
| `--context-window <n>` | Positive integer requested for models that support explicit sizing. |
| `--resume <id>` | Resume one Qoder session with a delta brief. |
| `--resume-last` | Continue the most recent Qoder session with a delta brief. |
| `--add-dir <dir>` | Add a workspace directory; repeatable. |
| `--permission-mode <mode>` | `default`, `accept_edits`, `auto`, `bypass_permissions`, `dont_ask`, or `plan`; defaults to `auto`. |
| `--timeout <dur>` | Relay watchdog; also bounds version preflight to at most 10s. Defaults to `30m`, using h/m/s syntax. |
| `--out-dir <dir>` | Artifact directory; defaults to a fresh system-temp directory. |
| `-h`, `--help` | Print relay help. |

`--resume` and `--resume-last` are mutually exclusive. Relative `--add-dir` values resolve against
`--cd`.

## Model and context behavior

Qoder's catalog is account- and time-dependent. The relay deliberately accepts a model string rather
than maintaining a stale allowlist. It validates only that the value is non-empty; Qoder remains the
authority on availability.

The relay validates context windows as positive integers and forwards the value unchanged. Qoder
remains the authority on whether the selected model supports it. An omitted value uses Qoder's normal
model behavior.

## Permission behavior

Print mode cannot ask for approval. `auto` is the implementation default: Qoder makes
non-interactive allow/deny decisions. `accept_edits` allows workspace edits but may deny shell actions;
`dont_ask` fails closed; `plan` maps to `default` plus Qoder's Plan work state; and
`bypass_permissions` is only for an explicitly trusted broad run.

Outside a trusted directory, Qoder falls back from any non-default request to `default`. Compare
`permissionMode` with `actualPermissionMode` in `result.json`. No mode replaces diff review.

## Artifacts and result fields

Artifacts default outside the repository:

- `brief.txt` - exact dispatched brief.
- `events.jsonl` - raw Qoder stdout events.
- `final.txt` - final report when captured.
- `stderr.txt` - complete stderr.
- `result.json` - `delegate-relay.result.v1`.

Important `result.json` fields:

- `tool` (`"qoder"`), `status` (`completed`, `failed`, `timeout`, `aborted`, or
  `qoder_unavailable`), `exitCode`, `signal`.
- Requested `model`, `contextWindow`, and `permissionMode`; observed `actualModel` and
  `actualPermissionMode` from Qoder's init event.
- `qoderVersion`, `sessionId`, `resumed`, `startedAt`, and `finishedAt`.
- `usage`, `resultSubtype`, `qoderErrors`, and `permissionDenials` from Qoder's result event.
- `finalMessage` from the result event, falling back to assistant text.
- `touchedFiles` from final `git status --porcelain` under the primary `--cd` only. Existing dirty
  entries are included; `--add-dir` changes are not. `null` means git could not report; `[]` means the
  tree is clean.
- Artifact paths, plus `stderrTail` and `error` on failures.

## Waiting

The relay blocks. Use the orchestrator's background facility or run it in the foreground for short
tasks. A valid run is done when the process exits and `result.json` exists. A usage error exits 2 before
creating artifacts; missing Qoder exits 127 with `qoder_unavailable`.

## Failures

- **`qoder_unavailable`:** install Qoder CLI, authenticate, and re-dispatch.
- **Preflight `failed` or `timeout`:** `qodercli --version` failed or exceeded its bound; Qoder was
  not dispatched. Fix the installation before retrying.
- **`failed`:** read `qoderErrors`, `permissionDenials`, `stderrTail`, `stderr.txt`, and the tail of
  `events.jsonl`. Fix auth, model/context compatibility, permissions, or the brief, then re-dispatch.
- **`timeout`:** increase `--timeout` or split the task. The relay terminates Qoder's process tree.
- **`aborted`:** the orchestrator stopped the relay; review any touched files before re-dispatching.
- **No result after the relay disappears:** treat the run as aborted and inspect the working tree and
  `events.jsonl`. Native Windows cannot deliver Node a catchable `SIGTERM`.
- **Empty final message:** inspect the diff; require a structured report in the next delta brief.

## Recovering lost work

`events.jsonl` records what Qoder streamed. If a run is interrupted, preserve the working tree first;
use the event log to scope any redo, not as proof that edits or gates completed.

## What the relay runs

```bash
qodercli --output-format stream-json --permission-mode auto \
  [--model <name>] [--context-window <n>] [--resume <id> | -c] \
  [--add-dir <dir> ...] -p <brief>
```

The relay spawns `qodercli` directly without a shell, never commits, and makes no network calls of its
own. Continue with [review-and-land.md](review-and-land.md).

# Multi-task queues

Scale the single-task loop through sequencing and bookkeeping, not a larger brief.

## Run sequentially

Dispatch one task, review it, rerun its gates, and land it before 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 review and rollback bounded.
- A clean tree makes `touchedFiles` useful.
- Parallelize only genuinely independent tasks in separate worktrees.

## Carry constraints forward

Fresh Qoder sessions do not know earlier queue decisions. Put any helper name, fixture location, or
interface needed later into the later brief.

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

## Keep a progress file

For more than two or three tasks, track:

- queued / at-implementer / reviewed+committed status and commit hash;
- per-task review notes and gate outcomes;
- design choices and questions needing human review;
- the final cross-task verification.

Update it after every landed task.

## Close coherently

After the last task, run the full gates once more, search repository-wide for the changed concept,
round-trip migrations when applicable, and only then push or open a pull request.

Stop and ask if a task cannot fit its brief, review invalidates the plan, or gates reveal a problem in
already-landed work. Report the landed hashes and open question before waiting.

# Review and land

Qoder did the typing; the orchestrator owns the judgment. Verify reality, not the self-report.

## Review changed tests first

- Treat unbriefed test edits as contract changes.
- Treat skipped, disabled, or commented tests as failures.
- Treat loosened assertions as weakened gates.

## Re-run the gates

`finalMessage` contains Qoder's claims. Run the repository's actual test, lint, typecheck, and build
commands yourself. For specialized changes:

- Round-trip migrations and schemas.
- Search for dangling references after removals and renames.
- Exercise stateful behavior, not only compilation.

## Compare the diff to the brief

Start with `touchedFiles`, then read the full diff for:

- **Scope creep** - excluded changes.
- **Scope shortfall** - missing behavior or cleanup.
- **Quiet decisions** - defensible but unasked choices requiring review.

`touchedFiles` is final tree state, not attribution. Start clean when possible and inspect every
`--add-dir` workspace separately.

## Implementer sweep

Look for hardcoded success data, swallowed errors, nonexistent dependencies or APIs, dead helpers,
duplicate patterns, tests that assert internals, speculative options, and guards that hide missing
trust-boundary validation. Run relevant guard skills if installed.

## Rework with a delta brief

Continue the same Qoder session with only the correction:

```bash
echo "Keep the fix, replace the mocked DB assertion with the real migrated fixture, remove the unused import, and rerun the stated gates." |
  node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo
```

Use `--resume <id>` for the specific `sessionId` in `result.json`. Rework receives the same independent
gate and diff review.

## Commit boundary

When the gates pass and the diff holds, **the orchestrator commits**. Qoder must never run `git add` or
`git commit` for this workflow.

Until then, the working tree is the authoritative copy of the implementer's work. Before any cleanup
or branch switch, inspect `git status`, `git diff`, `git diff --cached`, and every untracked file.
Staged and untracked work is invisible to a plain `git diff`; preserve it until the review decides
what to keep.

## Surface, do not absorb

- Report Qoder's design decisions and defensible deviations.
- Note non-blocking issues you did not block on.
- Stop and ask when correct completion requires expanding the brief.

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

# Writing the brief

A brief is the complete task Qoder receives. It has no memory of this chat; it sees only the brief,
its resumed session when applicable, and workspace context it can inspect. A constraint not in the
brief or repository does not exist for the implementer.

## Model, context, and resumed sessions

Model and context-window choices belong to dispatch, not the brief. Select a requested model from the
fresh output of `qodercli --list-models`. Omit `--model` for Qoder's default. Pass
`--context-window <positive-integer>` only when an explicit size is useful and let Qoder reject an
unsupported model/size combination.

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

## The shape that works

```xml
<task>
State the concrete job, where it lives, the current behavior, what must change, and what must remain
untouched. Keep it to one bounded task.
</task>

<verification_loop>
Run these before finishing and fix what they surface:
  <the project's real test command>
  <the project's real lint/format command>
  <the project's real build/typecheck command>
Confirm the working tree contains only intended changes.
</verification_loop>

<action_safety>
Keep changes scoped. Do not perform unrelated refactors, renames, or cleanup. Do NOT run git add or git
commit; the orchestrator reviews and commits. Leave work uncommitted.
</action_safety>

<structured_output_contract>
End with:
  1. What changed and why
  2. Files touched
  3. Gate outcomes with counts
  4. Deviations, open items, or decisions needed
</structured_output_contract>
```

For debugging, add `<completeness_contract>` so Qoder resolves the cause rather than stopping at the
first plausible fix, and `<missing_context_gating>` so it finds missing repository facts instead of
guessing.

## Discover the real gates

Read `AGENTS.md`, `CLAUDE.md`, `Makefile`, `package.json`, or the repository's equivalents before
writing the brief. Copy the actual commands. "Run the tests" makes the implementer guess.

## Honor repository conventions

Qoder loads repository context such as `AGENTS.md`, but restate load-bearing constraints directly in
the brief. This is especially important for forbidden commands, narrow file scope, data safety, and
the no-commit boundary.

## Ask for the report

The relay prefers Qoder's `result.result` for `finalMessage`, then falls back to assistant text blocks.
An explicit output contract makes the result reviewable even when the edits are correct.

## One task per brief

One brief -> one Qoder run -> one reviewed commit. Split mixed implementation, review, documentation,
and roadmap requests. Resume only for rework on that same task.

## Premises freeze at dispatch

Audit the brief's facts before dispatch: ownership, target branch, constraints, and any premise a
judgment call depends on. If one proves wrong during a run, stop Qoder, inspect and reconcile any
partial edits, then dispatch a corrected brief.

## Keep secrets out of argv

Qoder print mode receives the brief as a command-line argument, visible through process inspection on
the host. The relay rejects briefs over 120 KB, or 12 KB on native Windows where command lines are
shorter. Put secrets and large context in appropriately protected workspace files or environment
variables, then reference them by name or path.

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