gastown/docs/mail-protocol.md

Gas Town Mail Protocol

Reference for inter-agent mail communication in Gas Town

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

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 polecat done command generates this automatically.

Handler: Witness creates a cleanup wisp for the polecat.

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

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>
Merged-At: <timestamp>

Trigger: Refinery sends after successful merge to main.

Handler: Witness completes cleanup wisp, nukes polecat worktree.

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

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

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

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 gastown/nux
HELP: Polecat stuck on test failures
🤝 HANDOFF: Schema work in progress

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

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

Examples:

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

Protocol Flows

Polecat Completion Flow

Polecat                    Witness                    Refinery
   │                          │                          │
   │ POLECAT_DONE             │                          │
   │─────────────────────────>│                          │
   │                          │                          │
   │                    (verify clean)                   │
   │                          │                          │
   │                          │ MERGE_READY              │
   │                          │─────────────────────────>│
   │                          │                          │
   │                          │                    (merge to main)
   │                          │                          │
   │                          │ MERGED                   │
   │                          │<─────────────────────────│
   │                          │                          │
   │                    (nuke polecat)                   │
   │                          │                          │

Second-Order Monitoring

Witness-1 ──┐
            │ WITNESS_PING
Witness-2 ──┼────────────────> Deacon
            │
Witness-N ──┘
                                 │
                          (if no response)
                                 │
            <────────────────────┘
            Escalate to Mayor

Implementation

Sending Mail

# Basic send
gt mail send <addr> -s "Subject" -m "Body"

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

Receiving Mail

# Check inbox
gt mail inbox

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

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

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

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.

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