title: Worker cleanup: Beads sync on shutdown

description:
Update worker cleanup/decommission protocol:

Add to shutdown checklist:
- bd sync before final merge
- Verify beads committed

Handle edge cases:
- Uncommitted beads changes
- Beads sync conflicts (rare with tombstones, but possible)

status: open

issue_type: task

type: blocks

created_by: daemon


title: Design: Swarm shutdown and worker cleanup

description: Gray area in handoff between Witness (pushes workers to finish) and Mayor (cleanup inspection). Need to design: session cycling for Witness, cleanup authority, state preservation (stashes/branches), and how this relates to Mayor session cycling and Refinery lifecycle.

issue_type: epic


title: Federation: Wasteland architecture for cross-town coordination

description:
## Overview

A Wasteland is a federation of Towns across multiple machines. This enables:
- Same project managed in multiple locations (local Mac + GCP VMs)
- Cross-town swarm coordination
- Unified UI for managing distributed work

## Use Cases

1. **Scale-out**: Spawn workers on cloud VMs when local resources exhausted
2. **Geographic distribution**: Run workers close to data/services
3. **Redundancy**: Continue work if one machine goes down

## Design Questions

- How do towns discover each other?
- Cross-town mail routing protocol
- Shared vs replicated beads databases
- Conflict resolution for concurrent edits
- Authentication between towns
- UI for wasteland-level visibility

## Placeholder Tasks

- [ ] Design wasteland discovery/registration
- [ ] Design cross-town mail protocol
- [ ] Design beads synchronization strategy
- [ ] Implement gt wasteland commands
- [ ] Implement federation UI

## Related

- gt-f9x: Town & Rig Management (has federation basics)
- Connection interface in town-design.md


title: Witness updates: Remove issue filing proxy

description:
Update Witness role since polecats can now file their own beads:

Remove:
- Processing polecat "file issue" mail requests
- Issue filing on behalf of polecats

Keep:
- Monitoring polecat progress
- Nudge protocol
- Session lifecycle management

issue_id: gt-cjb


title: Worker prompting: Beads write access

description:
Update polecat prompting to:
1. Grant bd write access (create, update, close)
2. Teach bd commands and when to use them
3. Encourage filing discovered work outside their purview
4. Explain beads repo configuration (where their beads go)

Remove:
- Mail-based issue filing proxy instructions
- "Cannot file beads" restrictions


title: Witness session cycling and handoff

description: Witness should be able to request restart when context filling. Mail self handoff notes listing checked polecats, exit cleanly. Daemon spawns fresh session with handoff context. Add to Witness prompting.


title: Witness pre-kill verification protocol

description: Before killing a polecat that signaled done, Witness should capture and assess git status, stash list, and unmerged commits. Only kill if clean; otherwise nudge with specific issues. Keeps intelligence in model, not framework.


title: Town & Rig Management: install, doctor, federation

description:
Reify the Gas Town installation as a first-class concept.

## Goals
- Installable: gt install [path] creates complete installation
- Diagnosable: gt doctor checks and fixes issues
- Federable: Clone town to VMs with central control

## Design Doc
See docs/town-design.md for full design.


title: Config package: Config, State types and JSON serialization

description: Define workspace and rig config structures

type: parent-child


title: Extended addressing: Parse [machine:]rig/polecat

description: Support machine-prefixed polecat addresses


title: Workspace detection: Find() walking up directory tree

description: Find workspace root by looking for mayor/ or .gastown/


title: gt install command: Create workspace structure

description: Create mayor/, mail/, rigs/, config.json, state.json


title: Doctor framework: Check interface, Result types, Report

description: Framework for gt doctor health checks


title: Workspace doctor checks: Config, state, mail, boss, rigs

description: Health checks for workspace-level components


title: Rig doctor checks: Refinery health, clones, gitignore

description: Health checks for rig-level components


title: Connection interface: Protocol for local/remote ops

description: Abstract interface for local vs SSH operations


title: LocalConnection: Local file/exec/tmux operations

description: Implementation for local machine operations


title: Machine registry: Store and manage machine configs

description: Registry for federation machine management


title: Clarify Mayor vs Witness cleanup responsibilities

description: Document that Mayor is NOT involved in per-worker cleanup or session killing. Mayor handles: swarm dispatch, escalation handling, final integration, strategic decisions. Witness handles: nudges, pre-kill verification, session lifecycle.


title: Architecture: Decentralized rig structure with per-rig agents

description:
## Decision

Adopt decentralized architecture where each rig contains all its agents (mayor/, witness/, refinery/, polecats/) rather than centralizing mayor clones at town level.

## Town Level Structure

```
~/ai/                              # Town root
├── config/                        # Town config (VISIBLE, not hidden)
│   ├── town.json                  # {"type": "town"}
│   ├── rigs.json                  # Registry of managed rigs
│   └── federation.json            # Wasteland config (future)
│
├── mayor/                         # Mayor's HOME at town level
│   ├── CLAUDE.md
│   ├── mail/inbox.jsonl
│   └── state.json
│
└── <rigs>/                        # Managed projects
```

## Rig Level Structure (e.g., wyvern)

```
wyvern/                            # Rig = clone of project repo
├── .git/info/exclude              # Gas Town adds: polecats/ refinery/ witness/ mayor/
├── .beads/                        # Beads (if project uses it)
├── [project files]                # Clean project code on main
│
├── polecats/                      # Worker clones
│   └── <name>/                    # Each is a git clone
│
├── refinery/
│   ├── rig/                       # Refinery's clone
│   ├── state.json
│   └── mail/inbox.jsonl
│
├── witness/                       # NEW: Per-rig pit boss
│   ├── rig/                       # Witness's clone
│   ├── state.json
│   └── mail/inbox.jsonl
│
└── mayor/
    ├── rig/                       # Mayor's clone for this rig
    └── state.json
```

## Key Decisions

1. **Visible config dir**: `config/` not `.gastown/` (models don't find hidden dirs)
2. **Witness per-rig**: Each rig has its own Witness (pit boss) with its own clone
3. **Mayor decentralized**: Mayor's clones live IN each rig at `<rig>/mayor/rig/`
4. **Minimal invasiveness**: Only `.git/info/exclude` modified, no commits to project
5. **Clone subdir name**: Keep `rig/` for consistency (refinery/rig/, witness/rig/, mayor/rig/)

## Role Detection

- Town root or mayor/ → Mayor (town level)
- Rig root → Mayor (canonical main)
- <rig>/mayor/rig/ → Mayor (rig-specific)
- <rig>/refinery/rig/ → Refinery
- <rig>/witness/rig/ → Witness
- <rig>/polecats/<name>/ → Polecat

## Migration from PGT

- `mayor/rigs/<rig>/` → `<rig>/mayor/rig/`
- `<rig>/town/` → eliminated (rig root IS the clone)
- Add `witness/` to each rig

status: closed

close_reason: Design decision recorded

issue_id: gt-iib


title: Design: Polecat Beads write access

description:
## Background

Reversing the original decision to make polecats read-only for Beads. With v0.30.0's
tombstone-based rearchitecture for deletions, we now have solid multi-agent support
even at high loads.

## Benefits
- Simplifies design (no need for mail-based issue filing proxy)
- Empowers polecats to file discovered work that's out of their purview
- Beads solves the work-disavowal problem

## Complications
- For OSS projects where you're not a maintainer, polecats need to file beads
  in a separate repo (Beads supports this via --root)
- Need per-rig beads repo configuration
- Default: polecats file to rig's own .beads/
- Option: polecats file to external beads repo (for OSS contributions)

## Design Areas
1. Per-rig beads configuration (which repo to use)
2. Worker prompting updates (grant write access, teach bd commands)
3. Witness plan updates (no longer needs to proxy issue filing)
4. Worker cleanup code updates


title: Enhanced polecat decommission prompting

description: Strengthen polecat prompting around decommission checklist. Make crystal clear: git status clean, stash list empty, bd sync complete, merge to main done BEFORE signaling done. Witness will verify and bounce back if dirty.


title: Port Gas Town to Go

description:
Complete rewrite of Gas Town in Go for improved performance and single-binary distribution.

## Goals
- Single installable binary (gt)
- All Python functionality ported
- Federation support built-in
- Improved performance

## Phases
1. Core infrastructure (config, workspace, git wrapper)
2. Rig & polecat management
3. Session & tmux operations
4. Mail system
5. CLI commands
6. TUI (optional)


title: Go scaffolding: cmd/gt, go.mod, Cobra setup

description:
Set up Go project structure with CLI framework.

**Stack:**
- Cobra for command/flag handling
- Lipgloss for styled terminal output

**Deliverables:**
- cmd/gt/main.go with Cobra root command
- Basic subcommands: version, help
- Lipgloss styles for status output (success, warning, error)
- go.mod with dependencies


title: CLI: core commands (status, prime, version, init)

description: Essential CLI commands: gt status, gt prime, gt version, gt init.


title: CLI: session commands (start, stop, at, list, capture, inject)

description: Session CLI: gt session start/stop/at/list/capture/inject.


title: CLI: mail commands (send, inbox, read)

description: Mail CLI: gt mail send/inbox/read/check.


title: Beads CLI wrapper: shell out to bd

description: Wrapper for bd commands. List, show, create, update, close, sync.


title: Merge queue: per-rig queue management

description: FIFO merge queue per rig. Submit, process, git-based coordination.


title: Plugin system: subprocess JSON protocol

description: Language-agnostic plugin architecture via subprocess with JSON protocol.


title: CLI: rig commands (list, show, add)

description: Rig CLI: gt rig list/show/add.


title: CLI: polecat commands (add, remove, list, wake, sleep)

description: Polecat CLI: gt polecat add/remove/list/wake/sleep.


title: CLI: witness commands (start, stop, status)

description: Witness daemon CLI: gt witness start/stop/status.


title: CLI: spawn command

description: Spawn polecat with work assignment: gt spawn.


title: Bubbletea TUI dashboard

description: Interactive TUI using Charm Bubbletea. Root model, view routing, Lipgloss theme. Includes: dashboard, rig explorer, polecat detail with live tail, mail view, beads view, spawn wizard.


title: Prompt templates: role contexts, nudge messages

description: Go text/template for CLAUDE.md generation, role prompts, notification messages.


title: Test infrastructure: fixtures, mocks, integration tests

description: Go testing setup with fixtures, mocks for git/tmux, integration test harness.


title: Git wrapper: shell out to git

description: Wrapper for git operations via subprocess. Clone, checkout, commit, push, fetch, merge, rebase.


title: Tmux wrapper: session operations

description: Wrapper for tmux operations. Create/kill sessions, send keys, capture pane, list sessions.


title: Rig management: discover, load, create rigs

description: Rig discovery from workspace, loading rig config, creating new rigs.


title: Mail system: JSONL inbox, delivery, tmux injection

description: JSONL-based mail storage, delivery to polecats, tmux notification injection.


title: Session management: start, stop, attach, capture

description: Polecat session lifecycle. Start Claude in tmux, stop gracefully, attach for interaction, capture output.


title: Polecat management: add, remove, list, state

description: Create/destroy polecats, list polecats in rig, track polecat state (awake/asleep).


title: Witness daemon: heartbeat loop, spawn ephemeral agent

description: Background daemon that monitors polecats, spawns ephemeral agents for notifications, heartbeat checks.


title: Per-rig beads repo configuration

description:
Design config schema for per-rig beads repository settings.

Options needed:
- beads_repo: "local" (default) | "<git-url>" | "<path>"
- beads_root: override for bd --root

Use cases:
1. Local project (Wyvern): polecats write directly to project's .beads/
2. OSS contribution: polecats write to separate beads repo (e.g., ~/ai/my-oss-beads/)
3. Shared team beads: polecats write to team's central beads repo