sling-dispatch

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](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:

• [references/pipeline-implementation.md](references/pipeline-implementation.md) — full TypeScript code for all 7 stages, batch mode, formula expansion, crash recovery, and error handling.
• [references/gastown-origin.md](references/gastown-origin.md) — how this pattern derives from Gastown's sling.go dispatch system.