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

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. 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, 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 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:

# 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 – Defines the ProtoDispatchAttempt, ProtoDispatchOK, and ProtoDispatchFail message types and their parsers.
• internal/witness/handlers.go – Implements the Dispatched counter update and determines whether to send notifications to the mayor.
• internal/scheduler/capacity/state.go – Persists LastDispatchAt and LastDispatchCount via the RecordDispatch method for capacity‑aware scheduling.
• 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 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 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, updates the dispatch counters, and may trigger retry logic or back‑off delays based on LastDispatchAt values stored in internal/scheduler/capacity/state.go.

Where does Gas Town store dispatch history?

Dispatch timestamps and counts persist in 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}