# Dispatch and poll

`scripts/relay.mjs` wraps Vibe's headless `--prompt` mode, captures its structured stream, and writes
a `result.json`. Run one command, then read one file.

## Before the first run

```bash
command -v vibe
vibe --version
```

Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then install Vibe with
`uv tool install mistral-vibe`. Configure your API key:

```bash
vibe --setup                    # interactive setup
export MISTRAL_API_KEY="..."    # or set it in the environment
```

Upstream Vibe works on Windows but officially supports and targets UNIX. This repository has not
smoke-tested the relay's native Windows launch; consult the
[official Mistral Vibe documentation](https://github.com/mistralai/mistral-vibe) for Windows guidance.

## 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. |
| `--max-turns <n>` | Maximum number of Vibe agent turns (`--max-turns`). Useful for cost control. |
| `--max-price <usd>` | Positive, indicative cost threshold in USD; not a hard budget (`--max-price`). |
| `--max-tokens <n>` | Positive maximum cumulative session tokens (`--max-tokens`). |
| `--session <id>` | Resume a specific Vibe session (`--resume SESSION_ID`); send only the delta brief. |
| `--resume-last` | Resume the most recent Vibe session (`--continue`); send only the delta brief. |
| `--plan-only` | Use Vibe's read-only `plan` agent. |
| `--full-access` | Use Vibe's `auto-approve` agent; arbitrary shell/tools run under the user account. |
| `--enabled-tools <tool>` | Enable only this tool (`--enabled-tools`). Repeatable. |
| `--disabled-tools <tool>` | Disable this tool (`--disabled-tools`). Repeatable. |
| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). Vibe 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, as are `--plan-only` and `--full-access`.
The relay always passes `--trust` so headless runs do not prompt for directory trust. That flag is not
a sandbox or tool permission.

Default mode uses `accept-edits`: Vibe's built-in file edits are approved, while approval-gated shell
commands — including most project gates — are denied headlessly rather than hanging. The orchestrator
runs the gates. Use `--full-access` only with explicit human authorization; it selects
`auto-approve`, which approves all tool executions. Inspect `touchedFiles` and the diff after every run.

## 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 Vibe stdout in streaming JSON format.
- `final.txt` — the last non-empty assistant message; absent if none was emitted.
- `stderr.txt` — complete stderr.
- `result.json` — the stable `delegate-relay.result.v1` contract.

`result.json` fields:

- `schema`, `tool` (`"vibe"`), `status` (`completed` | `failed` | `timeout` | `aborted` |
  `vibe_unavailable`), `exitCode`, and `signal` (`null` unless the child died on a signal).
- `workdir`, `agent` (`"accept-edits"`, `"plan"`, or `"auto-approve"`), `maxTurns`, `maxPrice`,
  `maxTokens`, `resumed`, `vibeVersion`, `sessionId`, `startedAt`, and `finishedAt`.
- `briefPath`, `finalPath`, `eventsPath`, and `stderrPath`.
- `finalMessage` — the last non-empty assistant content string; tool calls and tool results are excluded.
- `touchedFiles` — `git status --porcelain` lines for the **final working tree under `--cd`**. Not
  an attribution of Vibe's edits: anything already dirty before dispatch shows up too. Dispatch from
  a clean tree when you want the list to read as "what Vibe changed". `null` means git could not
  report; `[]` means git ran and the tree is clean.
- `stderrTail` — the last 20 non-empty stderr lines on a run that did not complete.
- `error` — present for launch failures, `timeout`, and `aborted`.

Vibe's streaming output does not expose its session id, so `sessionId` is always `null` for schema
compatibility. Use `--resume-last`; retain `--session <id>` only for an id obtained outside the relay.

## 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 `vibe` exits 127 and writes
`status: "vibe_unavailable"`.

## When a run misbehaves

- **`status: "vibe_unavailable"` (exit 127):** `vibe` isn't on PATH. Install
  [`uv`](https://docs.astral.sh/uv/getting-started/installation/), run
  `uv tool install mistral-vibe`, and configure `MISTRAL_API_KEY`, then re-dispatch.
- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. Common
  causes: an unconfigured or expired API key, an invalid model, or a trust-folder prompt that was
  not suppressed (the relay passes `--trust`, but check that the binary supports it).
- **`status: "aborted"`:** the relay itself was killed and terminated Vibe's process tree. Inspect the
  working tree before re-dispatching. Native Windows has no catchable `SIGTERM`; a relay that vanishes
  there without `result.json` is an aborted run, so inspect the 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 Vibe error; check host memory and re-dispatch, or
  split the task into smaller briefs.
- **`status: "timeout"`:** `error` reads
  `vibe 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.
- **Empty `finalMessage`:** inspect `touchedFiles` and the diff. Add a
  `<structured_output_contract>` to the next brief to require a closing report. The streaming events
  in `events.jsonl` are the source of truth for diagnosing missing messages.

## Recovering lost work

`events.jsonl` records every message Vibe streamed. If finished work is lost — the run ended late or
the tree was damaged afterward — read it before re-dispatching to scope which files and tools were
involved. It may not contain the edit contents, so treat 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
vibe --output streaming --agent <accept-edits|plan|auto-approve> --trust \
  [--max-turns <n>] [--max-price <usd>] [--max-tokens <n>] \
  [--resume SESSION_ID | --continue] \
  [--enabled-tools TOOL ...] [--disabled-tools TOOL ...] \
  --prompt=<brief>
```

The prompt rides argv and is visible in the host process list. The relay rejects briefs over 120 KB
on POSIX or 12 KB on Windows before launch because the platforms cap command arguments. It spawns the
native `vibe` binary directly with `--cd` as cwd; no shell or Vibe timeout flag is involved.

## The commit boundary

The relay never commits. Vibe 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 Vibe 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 Vibe session only for rework on the same task. Send a delta brief with `--resume-last`;
use `--session <id>` only for an id obtained outside the relay because Vibe's stream does not expose
one. 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

Vibe 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 Vibe'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 Vibe 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 Vibe's
work. Never reflexively run `git checkout`, `reset`, `clean`, or switch branches after an interrupted
run. Inspect `git status`, `git diff`, `git diff --cached` for staged changes, and open every untracked
file (`??`) directly because no diff shows its contents. After inspection, discarding a bad or
premise-contaminated change can be correct; the rule is to preserve the evidence until it is reviewed.

## 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
```

Vibe's stream does not expose a session id, so use `--resume-last` normally. Use `--session <id>` only
when the id came from outside the relay. Rework gets the same gate rerun, test review, diff review, and
implementer sweep.

Default `accept-edits` runs cannot execute most gates headlessly; the orchestrator runs them.
`--full-access` permits arbitrary shell/tool execution and requires explicit human authorization.

## 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 Vibe 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 Vibe.

## Resumed sessions

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 Vibe 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>
These are the real project gates the orchestrator will run after dispatch:
  <the project's real test command>
  <the project's real lint/format command>
  <the project's real build/typecheck command>
If shell execution was explicitly authorized for this run, run them and fix what they surface.
Otherwise do not claim they ran; perform the inspections available to you and report the gates as not run.
</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 with counts, or exactly which gates were not run
  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 uses Vibe's last non-empty assistant message as `finalMessage`. 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>`. Default `accept-edits` runs cannot execute most gates
headlessly, but naming them lets the orchestrator run the same commands after dispatch. Ask Vibe to
run them only when the human explicitly authorized `--full-access`.

## Honor repo conventions

Restate the load-bearing house rules in the brief. Vibe 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 Vibe 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

Vibe starts from the brief's facts and there is no steering channel mid-run. Audit ownership, target
branch, constraints, and other judgment-bearing premises before dispatch. If one proves wrong while
the run is live, stop it and inspect the working tree before sending a corrected brief; reconcile any
partial or premise-contaminated edits rather than discounting them after the fact.

## 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>
The orchestrator will run:
  pytest tests/billing/ -q
  ruff check services/billing/
If shell execution is authorized for this run, run them and fix failures. Otherwise report them as
not run and confirm 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 or
that they were not run,
(4) anything left open or needing a decision.
</structured_output_contract>
```

## Argv delivery limits

Vibe's headless mode requires the brief as a command-line argument via `--prompt`. The relay reads a
file or stdin for convenience, then passes the text with `--prompt=<brief>`. The equals form binds a
brief that starts with `-` instead of treating it as another flag.

This has two consequences:

- The brief is visible in the host process list (`ps`, `/proc`). Keep secrets out of it on shared
  machines; reference workspace files or environment variables instead.
- A brief over 120 KB on POSIX or 12 KB on Windows is rejected before launch because the platforms
  cap command arguments. Put large context in the workspace and tell Vibe 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).