Skip to content
Gas Town Hall

Gas Town Mail Protocol

Reference for inter-agent mail communication in Gas Town

Overview

Section titled “Overview”

Gas Town agents coordinate via mail messages routed through the beads system. Mail uses type=message beads with routing handled by gt mail.

Message Types

Section titled “Message Types”

POLECAT_DONE

Section titled “POLECAT_DONE”

Route: Polecat → Witness

Purpose: Signal work completion, trigger cleanup flow.

Subject format: POLECAT_DONE <polecat-name>

Body format:

Exit: MERGED|ESCALATED|DEFERRED
Issue: <issue-id>
MR: <mr-id>          # if exit=MERGED
Branch: <branch>

Trigger: gt done command generates this automatically.

Handler: Witness creates a cleanup wisp for the polecat.

MERGE_READY

Section titled “MERGE_READY”

Route: Witness → Refinery

Purpose: Signal a branch is ready for merge queue processing.

Subject format: MERGE_READY <polecat-name>

Body format:

Branch: <branch>
Issue: <issue-id>
Polecat: <polecat-name>
Verified: clean git state, issue closed

Trigger: Witness sends after verifying polecat work is complete.

Handler: Refinery adds to merge queue, processes when ready.

MERGED

Section titled “MERGED”

Route: Refinery → Witness

Purpose: Confirm branch was merged successfully, safe to nuke polecat.

Subject format: MERGED <polecat-name>

Body format:

Branch: <branch>
Issue: <issue-id>
Polecat: <polecat-name>
Rig: <rig>
Target: <target-branch>
Merged-At: <timestamp>
Merge-Commit: <sha>

Trigger: Refinery sends after successful merge to main.

Handler: Witness completes cleanup wisp, nukes polecat worktree.

MERGE_FAILED

Section titled “MERGE_FAILED”

Route: Refinery → Witness

Purpose: Notify that merge attempt failed (tests, build, or other non-conflict error).

Subject format: MERGE_FAILED <polecat-name>

Body format:

Branch: <branch>
Issue: <issue-id>
Polecat: <polecat-name>
Rig: <rig>
Target: <target-branch>
Failed-At: <timestamp>
Failure-Type: <tests|build|push|other>
Error: <error-message>

Trigger: Refinery sends when merge fails for non-conflict reasons.

Handler: Witness notifies polecat, assigns work back for rework.

REWORK_REQUEST

Section titled “REWORK_REQUEST”

Route: Refinery → Witness

Purpose: Request polecat to rebase branch due to merge conflicts.

Subject format: REWORK_REQUEST <polecat-name>

Body format:

Branch: <branch>
Issue: <issue-id>
Polecat: <polecat-name>
Rig: <rig>
Target: <target-branch>
Requested-At: <timestamp>
Conflict-Files: <file1>, <file2>, ...


Please rebase your changes onto <target-branch>:


  git fetch origin
  git rebase origin/<target-branch>
  # Resolve any conflicts
  git push -f


The Refinery will retry the merge after rebase is complete.

Trigger: Refinery sends when merge has conflicts with target branch.

Handler: Witness notifies polecat with rebase instructions.

WITNESS_PING

Section titled “WITNESS_PING”

Route: Witness → Deacon (all witnesses send)

Purpose: Second-order monitoring - ensure Deacon is alive.

Subject format: WITNESS_PING <rig>

Body format:

Rig: <rig>
Timestamp: <timestamp>
Patrol: <cycle-number>

Trigger: Each witness sends periodically (every N patrol cycles).

Handler: Deacon acknowledges. If no ack, witnesses escalate to Mayor.

HELP

Section titled “HELP”

Route: Any → escalation target (usually Mayor)

Purpose: Request intervention for stuck/blocked work.

Subject format: HELP: <brief-description>

Body format:

Agent: <agent-id>
Issue: <issue-id>       # if applicable
Problem: <description>
Tried: <what was attempted>

Trigger: Agent unable to proceed, needs external help.

Handler: Escalation target assesses and intervenes.

HANDOFF

Section titled “HANDOFF”

Route: Agent → self (or successor)

Purpose: Session continuity across context limits/restarts.

Subject format: 🤝 HANDOFF: <brief-context>

Body format:

attached_molecule: <molecule-id>   # if work in progress
attached_at: <timestamp>


## Context
<freeform notes for successor>


## Status
<where things stand>


## Next
<what successor should do>

Trigger: gt handoff command, or manual send before session end.

Handler: Next session reads handoff, continues from context.

Format Conventions

Section titled “Format Conventions”

Subject Line

Section titled “Subject Line”
  • Type prefix: Uppercase, identifies message type
  • Colon separator: After type for structured info
  • Brief context: Human-readable summary

Examples:

POLECAT_DONE nux
MERGE_READY greenplace/nux
HELP: Polecat stuck on test failures
🤝 HANDOFF: Schema work in progress

Body Structure

Section titled “Body Structure”
  • Key-value pairs: For structured data (one per line)
  • Blank line: Separates structured data from freeform content
  • Markdown sections: For freeform content (##, lists, code blocks)

Addresses

Section titled “Addresses”

Format: <rig>/<role> or <rig>/<type>/<name>

Examples:

greenplace/witness       # Witness for greenplace rig
beads/refinery           # Refinery for beads rig
greenplace/polecats/nux  # Specific polecat
mayor/                # Town-level Mayor
deacon/               # Town-level Deacon

Protocol Flows

Section titled “Protocol Flows”

Polecat Completion Flow

Section titled “Polecat Completion Flow”
Polecat                    Witness                    Refinery
   │                          │                          │
   │ POLECAT_DONE             │                          │
   │─────────────────────────>│                          │
   │                          │                          │
   │                    (verify clean)                   │
   │                          │                          │
   │                          │ MERGE_READY              │
   │                          │─────────────────────────>│
   │                          │                          │
   │                          │                    (merge attempt)
   │                          │                          │
   │                          │ MERGED (success)         │
   │                          │<─────────────────────────│
   │                          │                          │
   │                    (nuke polecat)                   │
   │                          │                          │

Merge Failure Flow

Section titled “Merge Failure Flow”
                           Witness                    Refinery
                              │                          │
                              │                    (merge fails)
                              │                          │
                              │ MERGE_FAILED             │
   ┌──────────────────────────│<─────────────────────────│
   │                          │                          │
   │ (failure notification)   │                          │
   │<─────────────────────────│                          │
   │                          │                          │
Polecat (rework needed)

Rebase Required Flow

Section titled “Rebase Required Flow”
                           Witness                    Refinery
                              │                          │
                              │                    (conflict detected)
                              │                          │
                              │ REWORK_REQUEST           │
   ┌──────────────────────────│<─────────────────────────│
   │                          │                          │
   │ (rebase instructions)    │                          │
   │<─────────────────────────│                          │
   │                          │                          │
Polecat                       │                          │
   │                          │                          │
   │ (rebases, gt done)       │                          │
   │─────────────────────────>│ MERGE_READY              │
   │                          │─────────────────────────>│
   │                          │                    (retry merge)

Second-Order Monitoring

Section titled “Second-Order Monitoring”
Witness-1 ──┐
            │ WITNESS_PING
Witness-2 ──┼────────────────> Deacon
            │
Witness-N ──┘
                                 │
                          (if no response)
                                 │
            <────────────────────┘
            Escalate to Mayor

Implementation

Section titled “Implementation”

Sending Mail

Section titled “Sending Mail”
Terminal window
# Basic send
gt mail send <addr> -s "Subject" -m "Body"


# With structured body
gt mail send greenplace/witness -s "MERGE_READY nux" -m "Branch: feature-xyz
Issue: gp-abc
Polecat: nux
Verified: clean"

Receiving Mail

Section titled “Receiving Mail”
Terminal window
# Check inbox
gt mail inbox


# Read specific message
gt mail read <msg-id>


# Mark as read
gt mail ack <msg-id>

In Patrol Formulas

Section titled “In Patrol Formulas”

Formulas should:

  1. Check inbox at start of each cycle
  2. Parse subject prefix to route handling
  3. Extract structured data from body
  4. Take appropriate action
  5. Mark mail as read after processing

Extensibility

Section titled “Extensibility”

New message types follow the pattern:

  1. Define subject prefix (TYPE: or TYPE_SUBTYPE)
  2. Document body format (key-value pairs + freeform)
  3. Specify route (sender → receiver)
  4. Implement handlers in relevant patrol formulas

The protocol is intentionally simple - structured enough for parsing, flexible enough for human debugging.

Section titled “Related Documents”
  • docs/agent-as-bead.md - Agent identity and slots
  • .beads/formulas/mol-witness-patrol.formula.toml - Witness handling
  • internal/mail/ - Mail routing implementation
  • internal/protocol/ - Protocol handlers for Witness-Refinery communication