Gas Town Multi-Agent Orchestration System

The Convoy Stage & Launch functionality is verified through a multi-tiered testing strategy designed to ensure DAG (Directed Acyclic Graph) integrity, correct wave computation, and reliable command execution.

Testing is categorized into four main types:

1. Unit Tests: Test pure logic (e.g., detectCycles, computeWaves, buildDAG) in isolation using in-memory data without external dependencies like Dolt or database stubs.
2. Integration Tests (Stubbed): Test the full command flow (package cmd) using stubbed bd and gt binaries to simulate user stories and command-line interactions.
3. Integration Tests (Real Store): Test DAG walking and wave computation against a real Dolt store (package convoy) to ensure compatibility with actual data persistence.
4. Snapshot & Property Tests: Use snapshot tests to ensure stable console output (TUI/JSON) and property tests to prove invariants (like determinism and acyclicity) over randomized DAGs.

Gas Town is a multi-agent orchestration system designed to coordinate AI coding agents (like Claude Code or GitHub Copilot) with persistent work tracking. It uses a hierarchical structure to manage complexity:

• The Mayor 🎩: The primary AI coordinator (typically a Claude Code instance) that holds full context of the workspace. This is your starting point.
• Town 🏘️: The root workspace directory (e.g., ~/gt/) containing all projects and configurations.
• Rigs 🏗️: Project containers that wrap a git repository and manage associated agents.
• Crew Members 👤: Your personal workspace within a specific rig for hands-on work.
• Polecats 🦨: Ephemeral worker agents that have persistent identities and work histories.
• Hooks 🪝: Git worktree-based persistent storage that ensures agent work survives crashes or restarts.
• Convoys 🚚: Units of work tracking that bundle multiple 'beads'. Convoys labeled mountain include autonomous stall detection and smart skip logic.
• Beads 📿: The underlying data format for the git-backed issue tracking system. 'Beads' and 'issues' are used interchangeably. Bead IDs follow a prefix + 5-character alphanumeric format (e.g., gt-abc12).

Gas Town's architecture is evaluated against industry standards like CrewAI, LangGraph, and OpenAI Agents SDK. Key differentiators include:

• Role Definition: Uses named operational roles (Mayor, Witness, Polecat) with Role Beads and Agent Beads, whereas others use triads (role/goal/backstory) or graph nodes.
• Task Definition: Uses Beads (atomic work items with ID, status, assignee) and Molecules (multi-step workflows). Other frameworks use Task classes or graph topology.
• Persistence: Gas Town roles and identities are persistent (survive restarts via Agent Bead + GUPP), unlike most frameworks that are per-session or checkpoint-based.
• Coordination: Uses a pull-based model via Hooks + GUPP and workflow graphs (Molecules). Others use explicit graph edges or sequential/hierarchical flows.
• State Management: Uses Beads backed by a Dolt database with cell-level merging, allowing high parallelism without conflicts. Most others use typed state, memory, or conversation context.
• Parallelism: Achieves high parallelism (20-30 polecats) using OS processes and Git worktrees, providing each worker with its own filesystem isolation.

The gt-proxy-server (running on the host) and gt-proxy-client (running in the container) enable secure communication from a sandboxed container back to the host using mTLS.

gt-proxy-server (Host)

• Listens on a configured address (e.g., 0.0.0.0:9876).
• Requires mTLS: client certificates must be signed by the GasTown CA.
• CLI Relay Model: It forwards arguments to gt or bd on the host and streams stdout, stderr, and exitCode back to the client. It injects --identity <rig>/<name> based on the certificate's Common Name (CN).
• It maintains an allowlist of permitted subcommands to prevent arbitrary shell execution.

gt-proxy-client (Container)

• Replaces the standard gt and bd binaries via symlinks.
• Automatically detects and uses the proxy if the following environment variables are set:
  • GT_PROXY_URL
  • GT_PROXY_CERT
  • GT_PROXY_KEY
• If these are not set, it falls back to normal local execution (backward compatibility).

API Endpoint Example

POST /v1/exec
  body:     {"argv": ["gt", "mail", "inbox", "--json"]}
  response: {"stdout": "...", "stderr": "...", "exitCode": 0}

Polecats (agent workers) operate through a specific lifecycle of states. The standard 'happy path' follows a linear progression from IDLE to WORKING to DONE, where completed sessions are retired rather than reused to ensure clean state management.

Operating States

The Happy Path Cycle

1. IDLE: Polecat is available.
2. gt sling: Assigns work, moving the polecat to WORKING.
3. WORKING: Active session with hooks set.
4. gt done: Signals completion, moving the polecat to DONE (session is killed, but metadata remains).

         ┌──────────┐
         │  IDLE    │──── gt sling
         └────┬─────┘
              v
         ┌──────────┐
         │ WORKING  │<──── session active, hook set
         └────┬─────┘
              │ gt done
              v
         ┌──────────┐
         │  DONE    │──── branch/MR evidence preserved, session exits
         └──────────┘