# What Is the Dispatch Command in Gas Town for Rig‑Owned Work?

> Learn how the gt dispatch command moves tasks to rigs records attempts and feeds metrics back into scheduling for optimal capacity decisions and retry logic.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: how-to-guide
- Published: 2026-07-07

---

**The `gt dispatch` command is the CLI entry point that moves ready tasks from the Gas Town central scheduler onto a specific rig (worker node), records the attempt via the internal witness protocol, and feeds dispatch metrics back into the scheduling loop to inform capacity decisions and retry logic.**

The **dispatch command in Gas Town for rig‑owned work**, implemented in the `gastownhall/gastown` repository, provides the mechanism for assigning workloads to specific worker nodes rather than placing them in a general queue. When the scheduler determines a task is ready, it uses this command to hand off execution to the designated rig while maintaining visibility into attempt counts, success states, and capacity limits through the witness protocol.

## How the Dispatch Command in Gas Town for Rig‑Owned Work Functions

When the scheduler decides that a task should run on a particular rig, the `gt dispatch` command executes a four‑step workflow that safely transfers ownership and updates internal state.

### Sending the DISPATCH Message via the Witness Protocol

The command creates a `DISPATCH_ATTEMPT` message defined in [`internal/witness/protocol.go`](https://github.com/gastownhall/gastown/blob/main/internal/witness/protocol.go). The witness layer parses this payload via `ParseDispatchAttempt`, and the scheduler processes it through `parseSchedulerRunDispatched`. Successful dispatches generate a `DISPATCH_OK` response, while failures trigger `DISPATCH_FAIL`. Both outcomes are recorded to maintain an accurate history of rig activity.

### Updating the Dispatched Counter in handlers.go

Inside [`internal/witness/handlers.go`](https://github.com/gastownhall/gastown/blob/main/internal/witness/handlers.go), the scheduler increments the `Dispatched` counter for the target rig. This update allows the system to throttle further work and prevents the rig from receiving more tasks than it can handle, keeping capacity information synchronized across the cluster.

### Suppressing Mayor Notifications

Unlike standard job scheduling, a successful dispatch suppresses the usual "slot‑open" notification to the mayor. Because the rig already owns the workload, the central scheduler does not need to advertise an available slot, reducing unnecessary message traffic.

### Persisting Dispatch Metadata in state.go

The [`internal/scheduler/capacity/state.go`](https://github.com/gastownhall/gastown/blob/main/internal/scheduler/capacity/state.go) file stores `LastDispatchAt` and `LastDispatchCount` through the `RecordDispatch` method. This persistence enables **back‑off logic** that prevents recently‑dispatched rigs from receiving new work immediately, protecting the node from overload and allowing time for the current task to initialize.

## CLI Usage for the Gas Town Dispatch Command

Trigger dispatches from the command line to assign work to specific rigs or execute plugins directly:

```bash

# Trigger a dispatch from the command line

# Example: run a plugin on a rig named "gt‑xyz"

gt dispatch gt‑xyz --prefer-skill=go

# Dispatch a plugin directly (new in vX.Y)

# The `--plugin` flag tells the scheduler to treat the payload as a plugin

gt dispatch --plugin my‑plugin.wasm

```

## Key Source Files

The dispatch workflow relies on four core files in the `gastownhall/gastown` codebase:

- **[`internal/witness/protocol.go`](https://github.com/gastownhall/gastown/blob/main/internal/witness/protocol.go)** – Defines the `ProtoDispatchAttempt`, `ProtoDispatchOK`, and `ProtoDispatchFail` message types and their parsers.
- **[`internal/witness/handlers.go`](https://github.com/gastownhall/gastown/blob/main/internal/witness/handlers.go)** – Implements the `Dispatched` counter update and determines whether to send notifications to the mayor.
- **[`internal/scheduler/capacity/state.go`](https://github.com/gastownhall/gastown/blob/main/internal/scheduler/capacity/state.go)** – Persists `LastDispatchAt` and `LastDispatchCount` via the `RecordDispatch` method for capacity‑aware scheduling.
- **[`internal/cmd/info.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/info.go)** – Documents the `gt dispatch --plugin` feature in the CLI help output.

## Summary

- The **dispatch command in Gas Town for rig‑owned work** moves tasks from the central scheduler to specific rigs that own the workload.
- It updates dispatch counters in [`internal/witness/handlers.go`](https://github.com/gastownhall/gastown/blob/main/internal/witness/handlers.go) to inform capacity throttling.
- It suppresses mayor notifications when work is successfully handed off to a rig.
- It persists dispatch timestamps and counts in [`internal/scheduler/capacity/state.go`](https://github.com/gastownhall/gastown/blob/main/internal/scheduler/capacity/state.go) to support back‑off logic and retry decisions.

## Frequently Asked Questions

### How does `gt dispatch` differ from standard job scheduling?

Standard job scheduling places work in a general queue for any available worker to claim. The **dispatch command in Gas Town for rig‑owned work** assigns tasks to specific rigs identified by the scheduler, bypassing the queue and suppressing slot‑open notifications because the target node already owns the workload.

### What happens when a dispatch fails?

When dispatching fails, the witness protocol sends a `DISPATCH_FAIL` message to the scheduler. The `parseSchedulerRunDispatched` handler records the failure in [`internal/witness/handlers.go`](https://github.com/gastownhall/gastown/blob/main/internal/witness/handlers.go), updates the dispatch counters, and may trigger retry logic or back‑off delays based on `LastDispatchAt` values stored in [`internal/scheduler/capacity/state.go`](https://github.com/gastownhall/gastown/blob/main/internal/scheduler/capacity/state.go).

### Where does Gas Town store dispatch history?

Dispatch timestamps and counts persist in [`internal/scheduler/capacity/state.go`](https://github.com/gastownhall/gastown/blob/main/internal/scheduler/capacity/state.go). The `RecordDispatch` method updates `LastDispatchAt` and `LastDispatchCount` fields, enabling the scheduler to reason about recent activity and implement capacity‑aware throttling for rig‑owned work.

### How do I dispatch a plugin directly?

Use the `--plugin` flag documented in [`internal/cmd/info.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/info.go). The command `gt dispatch --plugin my‑plugin.wasm` instructs the scheduler to treat the payload as a plugin executable, allowing direct dispatch of WebAssembly or other plugin artifacts to the target rig.