convoy

The convoy system is a core architectural component of the Gas Town workspace manager, designed to provide persistent, event-driven, and fault-tolerant work tracking across multiple AI agents and rigs. It enables developers to bundle work items (beads) into convoys, which are then autonomously managed, staged, and dispatched to worker agents (polecats). This skill is essential for engineers orchestrating complex, epic-scale projects where task dependencies must be respected and state must survive agent restarts or crashes.

• Automated batch work tracking via bead dependencies and DAG-based wave execution.

• Integrated safety guards, including IsSlingableType filtering and isIssueBlocked dependency checks, to prevent invalid dispatches.

• Event-driven feeding mechanism utilizing SDK events to trigger work dispatch upon completion of prerequisite tasks.

• Resilient stranded scan functionality that automatically recovers and re-dispatches work if a convoy becomes stalled.

• Structured lifecycle management supporting explicit creation via gt convoy create, staged workflows via gt convoy stage/launch, and automated sling processes.

• Use this skill to track epic-scale work, define dependencies, and ensure that AI agents process work in the correct logical sequence without manual intervention.

• Practical workflows include invoking gt convoy stage to compute dependency waves, followed by gt convoy launch to initialize execution.

• Expected inputs include bead identifiers, task types, and dependency graphs. Outputs include status updates for convoys, dispatch confirmation, and automated status transition logs.

• Constraints: The system is designed for git-backed environments; ensure your environment meets requirements for dolt, sqlite3, and the beads ledger. Always monitor convoy health using gt convoy check and gt convoy status to detect bottlenecks or stalled execution paths.

• When debugging, review event-driven behavior in operations.go or stranded scan logic in convoy_manager.go to identify why a specific task might be skipping or failing to dispatch.