Module dispatch 

GET /v1/agent/dispatch?wait=60 — long-poll dispatch delivery.

Replaces the pre-v0.2 dispatch-on-checkin contract. The agent calls this every time it wants new work (typically right after a Converged or every minute on idle, per nixfleet-agent policy). The contract is RFC-0003 §1 pull-only + RFC-0005 §2.1 + plan 06’s locked-in “long-poll, 60s wait window” decision.

Implementation:

1. mTLS + CN-vs-?hostname=… check (cert CN authoritative).
2. Peek dispatch_queue for the host. Row exists ⇒ atomic take_for_host + return. No row ⇒ park on the state.dispatch_kick watch channel for up to wait seconds (capped at 60). Wake on:
   • applier upsert (any host) — re-peek for this host;
   • timeout — return empty.
3. Response shape:
   • 200 + Dispatch JSON ⇒ work to do, agent processes;
   • 204 ⇒ no work, agent re-polls.

Backpressure: long-polls are cheap (one row peek per wake), and the watch channel collapses bursts to one wake. The 60s cap is the protocol-defined ceiling.

Structs

DispatchQuery

DispatchResponse

Constants

MAX_WAIT_SECS 🔒

Long-poll wait window cap. Locked by plan 06.

Functions

deliver 🔒

dispatch 🔒