| name | sling-dispatch |
| description | Instruction dispatch pipeline for routing work items to available agents. Implements a 7-stage fetch-allocate-prepare-hook-store-launch-confirm pipeline with batch convoy mode, formula expansion, idempotent dispatch, and crash recovery. |
| format | "2025-10-02T00:00:00.000Z" |
| version | 1.0.0 |
| status | ACTIVE |
| updated | "2026-04-25T00:00:00.000Z" |
| triggers | ["mayor needs to assign work items to available polecats","convoy of beads is ready for dispatch to a rig","formula template needs expansion into ordered dispatch steps","partial dispatch needs recovery after a crash or session restart"] |
| references_subdir | true |
| word_budget | 800 |
Sling Dispatch
Instruction dispatch unit for the Gastown chipset. The sling routes a work item (bead) to an available polecat through a 7-stage pipeline. In hardware terms, the sling is the instruction fetch-decode-dispatch unit — it sets up the conditions for execution and confirms the dispatch was recorded, but does not execute work itself.
Activation Triggers
This skill activates when:
- The mayor needs to assign work items to available polecats
- A convoy of beads is ready for dispatch to a rig
- A formula template needs expansion into ordered dispatch steps
- A partial dispatch needs recovery after a crash or session restart
The 7-Stage Dispatch Pipeline
Every dispatch flows through seven stages in strict order. Each stage completes before the next begins. If any stage fails, the pipeline halts at that stage and the partial state is recoverable.
| # | Stage | Purpose |
|---|
| 1 | Fetch | Resolve bead ID to a work item; reject anything not in open status (idempotency). |
| 2 | Allocate | Select an idle polecat from the pool, or spawn a new one if the pool has capacity. |
| 3 | Prepare | Set up the polecat's isolated workspace (worktree + execution context). |
| 4 | Hook | Set work item status to hooked and bind it to the polecat. Idempotency boundary. |
| 5 | Store | Write dispatch arguments to durable state so a crash after this point is recoverable. |
| 6 | Launch | Start the polecat's agent session and send assignment mail. GUPP activates immediately. |
| 7 | Confirm | Record the bead-to-agent assignment in convoy tracking and notify the witness. |
Full TypeScript implementations live in references/pipeline-implementation.md.
Batch Mode
When more than batch_threshold beads (default: 3, configurable in chipset YAML at dispatch.batch_threshold) target the same rig, the sling automatically batches them into a convoy and dispatches in parallel. The batch detection groups beads by target rig; groups exceeding the threshold become convoys. Dispatches within a batch run in parallel up to max_parallel. Convoy progress updates after each individual dispatch confirms.
Formula Mode
When a formula (TOML template) is specified, the sling expands it into step-ordered beads before dispatching. Formulas define multi-step workflows as declarative sequences. Beads respect dependency ordering — steps with depends_on wait for their dependencies to reach done status before being dispatched. Steps without dependencies dispatch immediately.
Idempotency
The sling is idempotent. Re-dispatching an already-hooked bead is a no-op:
- Stage 1 (Fetch) rejects any bead not in
open status
- A bead transitions to
hooked in Stage 4 and never returns to open
- Calling
dispatchSingle(beadId) multiple times for the same bead has the same effect as calling it once
- No side effects on repeated calls — the second call returns immediately at Stage 1
This makes the dispatch pipeline safe to retry after crashes, timeouts, or duplicate requests.
Crash Recovery
If the sling crashes mid-pipeline, the dispatch can be resumed from the durable state written in Stage 5 (Store). Records in the stored stage resume from Launch; records in the launched stage resume from Confirm; confirmed records are complete. All state updates use the write-then-rename pattern so partial writes are impossible.
Communication Protocol
The sling is invoked by the mayor, not by external events. The mayor decides what to dispatch and when; the sling handles how. On the outbound side, the sling sends durable mail to the polecat (work assignment) and the witness (dispatch confirmation), and writes the polecat's hook record in Stage 4. Inbound, it only receives dispatch and batch-dispatch mail from the mayor.
Boundary: What the Sling Does NOT Do
The sling dispatches; it does not execute work (the polecat does), decide what to dispatch (the mayor does), monitor agent progress (the witness does), resolve merge conflicts (the refinery does), or modify bead content. It fetches instructions, decodes them, assigns them to polecats, and confirms delivery.
Integration with Other Gastown Skills
Invoked by mayor-coordinator; targets polecat-worker via hook-persistence (Stage 4) and mail-async (Stages 6-7). Uses beads-state (StateManager) for work items and dispatch records. Emits confirmations to witness-observer. done-retirement processes the other end of the lifecycle.
References
Implementation detail moved to:
