Gastown Troubleshooting Guide

Internal Reference for Claude Code - You diagnose and fix issues for the user.

Core Principle

When the user reports a problem or something seems broken:

1. Run gt doctor to diagnose
2. Interpret the results
3. Run gt doctor --fix if appropriate
4. Report what you found and fixed in a warm voice

The user never sees raw error messages or runs commands themselves.

Error Severity Guide

CRITICAL: Not all errors are equal. Know which to fix immediately.

| Severity | Description | Action | |----------|-------------|--------| | BLOCKER | Prevents core functionality | Must fix before slinging work | | WARNING | Degraded but functional | Fix when convenient | | INFO | Advisory only | Can ignore |

BLOCKER Errors (Fix Immediately)

• Prefix mismatch - Work won't route correctly
• Missing patrol molecules - Refinery/Witness won't run
• Refinery not running - Merges won't process
• Routes.jsonl missing entries - Beads can't find database
• bd doctor critical failures - Beads system broken

WARNING Errors (Fix Soon)

• Daemon timeout - Falls back to direct mode (slower)
• Beads sync issues - May resolve with bd sync
• Agent bead missing - Worker may not have full context

Rule: If gt doctor or bd doctor shows BLOCKER-level errors, fix them before declaring setup complete or slinging work.

Table of Contents

1. Running gt doctor
2. Doctor Checks Reference
3. Common Error Messages
4. Prefix Mismatch Errors
5. BEADS_NO_DAEMON Environment Variable
6. Session Errors
7. Git Errors
8. Beads Errors
9. Tmux Errors
10. Config Version Errors
11. Recovery Procedures

---

Running Diagnostics

Always run BOTH diagnostic tools:

# Gas Town diagnostics
gt doctor              # Check everything
gt doctor --fix        # Auto-fix issues
gt doctor --verbose    # Detailed output
gt doctor --check <name>  # Specific check

# Beads diagnostics
bd doctor              # Check beads health

Why both? Gas Town (gt) manages the engine. Beads (bd) manages work tracking. Problems in either can break slinging.

---

Doctor Checks Reference

Configuration Checks

config-version

Description: Verify config file versions are compatible

Detects:

• Config files with unsupported version numbers
• Missing required config files

Error: unsupported config version: got %d, max supported %d

Fix: Update config files to current schema version or regenerate with gt init

---

rig-config

Description: Validate rig configuration files

Detects:

• Invalid rig config type
• Missing required fields (name, git_url)
• Invalid merge queue settings

Error: invalid config type: expected type 'rig', got '%s' Error: missing required field: name

Fix: Run gt doctor --fix or manually edit config files

---

crew-state

Description: Validate crew worker state.json files

Detects:

• Empty or incomplete state.json files
• Missing name, rig, or clone_path fields
• Invalid JSON in state files

Symptoms: "can't find pane/session" errors

Error: invalid JSON in state.json Error: missing name, missing rig, missing clone_path

Fix: Run gt doctor --fix to regenerate state files with correct values

---

Beads Checks

beads-routes

Description: Check beads routing configuration

Detects:

• Missing routes.jsonl file
• Duplicate prefix routes (conflicts)
• Invalid route entries

Message: No routes.jsonl file (prefix routing not configured)

Fix: Run gt rig add to configure routes for a rig

---

agent-beads-exist

Description: Verify agent beads exist for all agents

Detects:

• Missing beads for global agents (deacon, mayor)
• Missing beads for per-rig agents (witness, refinery)
• Missing beads for crew workers

Error: %d agent bead(s) missing

FixHint: Run 'gt doctor --fix' to create missing agent beads

Agent bead naming convention:

• Witness: {prefix}-rig-{rigName}-witness
• Refinery: {prefix}-rig-{rigName}-refinery
• Crew: {prefix}-rig-{rigName}-crew-{workerName}
• Deacon: gt-deacon
• Mayor: gt-mayor

---

Tmux & Session Checks

daemon-tmux

Description: Check tmux availability for daemon

Detects:

• tmux not installed
• tmux server not running
• Incompatible tmux version

Error: no tmux server running

Fix: Install tmux or start tmux server with tmux new-session -d

---

orphan-sessions

Description: Detect orphaned tmux sessions

Detects:

• Sessions with gt- prefix not matching valid rigs
• Sessions for deleted polecats or crew members

Valid session patterns:

• gt-mayor
• gt-deacon
• gt-{rig}-witness
• gt-{rig}-refinery
• gt-{rig}-{polecat}
• gt-{rig}-crew-{name}

FixHint: Run 'gt doctor --fix' to kill orphaned sessions

Note: Crew sessions (gt-{rig}-crew-{name}) are protected from auto-cleanup

---

orphan-processes

Description: Detect orphaned Claude processes

Detects:

• Claude CLI processes without tmux parent
• Zombie processes from crashed sessions

Error: Found %d orphaned Claude process(es)

FixHint: Run 'gt doctor --fix' to kill orphaned processes

Note: Crew session processes are protected from auto-kill

---

themes

Description: Check tmux session theme configuration

Detects:

• Sessions with outdated theme format (brackets)

FixHint: Run 'gt theme apply --all' or 'gt doctor --fix'

---

Boot & Daemon Checks

boot-health

Description: Check Boot watchdog health ("the vet checks on the dog")

Detects:

• Boot directory not present
• Session not running
• Last run errors
• Stale marker file (indicates crash)

Messages:

• Boot directory not present
• Failed to load Boot status
• Boot last run had an error
• Boot marker is stale (possible crash)
• Boot watchdog healthy (degraded mode) - running without tmux

FixHint: Boot directory is created on first daemon run

---

Hook & Attachment Checks

hook-attachment-valid

Description: Verify attached molecules exist and are not closed

Detects:

• Hooks pointing to non-existent molecules
• Hooks pointing to closed issues

Error: %s: attached molecule %s not found Error: %s: attached molecule %s is closed

FixHint: Run 'gt doctor --fix' to detach invalid molecules, or 'gt mol detach <pinned-bead-id>' manually

---

hook-singleton

Description: Ensure each agent has at most one handoff bead

Detects:

• Multiple pinned beads with same "{role} Handoff" title

Error: "%s" has %d beads: %s

FixHint: Run 'gt doctor --fix' to close duplicates, or 'bd close <id>' manually

---

orphaned-attachments

Description: Detect handoff beads for non-existent agents

Detects:

• Handoffs for deleted polecats
• Handoffs for removed crew members

FixHint: Reassign with 'gt sling <id> <agent>', or close with 'bd close <id>'

---

Lifecycle Checks

lifecycle-hygiene

Description: Check for stale lifecycle messages and stuck state flags

Detects:

• Stale lifecycle messages in deacon inbox
• Stuck requesting_* flags in state.json files

Error: %d stale lifecycle message(s) in deacon inbox Error: %d agent(s) with stuck requesting_* flags

FixHint: Run 'gt doctor --fix' to clean up

---

Branch & Git Checks

persistent-role-branches

Description: Detect persistent roles not on main branch

Detects:

• Crew workers on feature branches
• Witness/refinery roles off main

Error: %d persistent role(s) not on main branch

FixHint: Run 'gt doctor --fix' to switch to main, or manually: git checkout main && git pull

---

beads-sync-orphans

Description: Detect orphaned code on beads-sync branch

Detects:

• Code changes on beads-sync that weren't merged to main

FixHint: Review with: git diff main..beads-sync -- <file>

---

clone-divergence

Description: Detect emergency divergence between git clones

Detects:

• Clones significantly behind origin/main (>10 commits = warning, >50 = error)

Error: %d clone(s) critically diverged

FixHint: Run 'git pull --rebase' in affected directories

---

Patrol Checks

patrol-molecules-exist

Description: Check if patrol molecules exist for each rig

Required molecules:

• Deacon Patrol
• Witness Patrol
• Refinery Patrol

FixHint: Run 'gt doctor --fix' to create missing patrol molecules

---

patrol-hooks-wired

Description: Check if hooks trigger patrol execution

Detects:

• Missing daemon config
• Patrols not configured in daemon.json

FixHint: Configure patrols in mayor/daemon.json or run 'gt deacon init'

---

patrol-not-stuck

Description: Check for stuck patrol wisps (>1h in_progress)

Detects:

• In-progress wisps older than 1 hour

FixHint: Manual review required - wisps may need to be burned or sessions restarted

---

patrol-plugins-accessible

Description: Check if plugin directories exist and are readable

FixHint: Run 'gt doctor --fix' to create missing directories

---

Wisp Checks

wisp-gc

Description: Detect and clean orphaned wisps (>1h old)

Detects:

• Wisps not closed and older than 1 hour

Error: %d abandoned wisp(s) found (>1h old)

FixHint: Run 'gt doctor --fix' to garbage collect orphaned wisps

Fix command: bd --no-daemon mol wisp gc

---

Version Control Checks

town-git

Description: Verify town root is under version control

Message: Town root is not under version control

FixHint: Run 'git init' in your town root to initialize a repository

---

Common Error Messages

Config Errors

config file not found: %s

Cause: Required config file doesn't exist Fix: Run gt init or create the missing config file

unsupported config version: got %d, max supported %d

Cause: Config file uses newer schema than gt supports Fix: Upgrade gt or downgrade config version

invalid config type: expected type '%s', got '%s'

Cause: Config file has wrong type field Fix: Correct the type field in the config file

missing required field: %s

Cause: Required field (name, role, etc.) not specified Fix: Add the missing field to the config

---

Session Errors

session already running

Cause: Attempting to start a session that's already active Fix: Use gt ps to check running sessions, stop with gt stop <name>

session not found

Cause: Referenced session doesn't exist Fix: Verify session name, check tmux list-sessions

polecat not found

Cause: Polecat worktree doesn't exist Fix: Verify polecat name, check gt polecat list

invalid session name "%s": missing "%s" prefix

Cause: Session name doesn't start with expected prefix (gt-) Fix: Use correct session naming convention

invalid session name "%s": empty after prefix

Cause: Session name has prefix but nothing after Fix: Use complete session name like gt-mayor

invalid session name "%s": expected rig-role format

Cause: Session name doesn't follow rig-role pattern Fix: Use format gt-{rig}-{role} or gt-{rig}-{name}

---

Git Errors

not a git repository

Cause: Command run outside a git repository Fix: Navigate to a git repository or initialize one

merge conflict

Cause: Git merge has conflicts requiring resolution Fix: Resolve conflicts manually, then git add and git commit

authentication failed

Cause: Git authentication failed (SSH key, token, etc.) Fix: Check SSH keys, refresh tokens, verify credentials

rebase conflict

Cause: Git rebase encountered conflicts Fix: Resolve conflicts, git add, then git rebase --continue

---

Mail & Routing Errors

unknown mailing list: %s

Cause: Mailing list not defined in messaging config Fix: Add list to config/messaging.json

unknown queue: %s

Cause: Queue not defined in messaging config Fix: Add queue to config/messaging.json

unknown announce channel: %s

Cause: Announce channel not defined Fix: Add announce channel to messaging config

---

Refinery Errors

refinery not running

Cause: Refinery session not active Fix: Start with gt refinery start

refinery already running

Cause: Attempting to start refinery that's running Fix: Stop existing refinery first

no items in queue

Cause: Merge queue is empty Fix: Normal state, no action needed

merge request not found

Cause: Referenced MR doesn't exist Fix: Verify MR ID, check with gt mq ls

invalid state transition: %s -> %s is not allowed

Cause: Attempted illegal MR state change Fix: Follow valid state transitions

closed merge requests are immutable

Cause: Attempting to modify a closed MR Fix: Closed MRs cannot be modified

---

Deacon/Stuck Agent Errors

agent is in cooldown period after recent force-kill

Cause: Agent was recently force-killed and is in cooldown Fix: Wait for cooldown to expire before restart

agent not found or session doesn't exist

Cause: Referenced agent has no active session Fix: Start the agent session first

agent is responsive, no action needed

Cause: Health check found agent is working normally Fix: No action needed

---

Prefix Mismatch Errors

⚠️ BLOCKER: Prefix mismatches must be fixed before slinging work.

Prefix mismatches are one of the most common issues in multi-rig setups. They prevent work from routing correctly and will cause slinging to fail.

Understanding Prefixes

Each rig can have a unique prefix for its beads:

• Default prefix: gt- (for gastown)
• Custom prefix: bd- (for beads project), my- (custom)

Prefixes are configured in ~/.beads/routes.jsonl:

{"prefix":"gt-","path":"gastown/mayor/rig"}
{"prefix":"bd-","path":"beads/mayor/rig"}

Common Prefix Problems

1. Wrong prefix in commands

Error: Commands fail silently or return "not found"

Cause: Using gt-xyz when bead is actually bd-xyz

Diagnosis:

# Check what prefixes are configured
cat ~/gt/.beads/routes.jsonl

# Check bead's actual prefix
bd show <full-id>

Fix: Use the correct prefix for the rig you're working with

2. Agent beads created with wrong prefix

Error: Agent beads not found during health checks

Cause: Routes not configured before rig was added

Diagnosis:

gt doctor --check agent-beads-exist

Fix:

gt doctor --fix

3. Conflicting prefix routes

Error: Multiple rigs claiming same prefix

Diagnosis:

# Check for duplicates
gt doctor --check beads-routes

Fix: Edit routes.jsonl to remove duplicate entries

Prefix Resolution Flow

1. Command parses bead ID (e.g., gt-abc12)
2. Extracts prefix (gt-)
3. Looks up prefix in routes.jsonl
4. Routes to correct .beads directory

If the prefix isn't in routes, commands may fail or route incorrectly.

---

BEADS_NO_DAEMON Environment Variable

Why It's Critical

BEADS_NO_DAEMON=1 prevents the beads daemon from committing to the wrong branch when running in worktrees (polecats, crew).

When It's Required

• Polecats - Always (set automatically by gt)
• Crew workers - Always (set automatically by gt)
• Refinery - Always (set automatically by gt)
• Manual bd commands in worktrees - Must set manually

What Happens Without It

1. Daemon process sees beads changes
2. Daemon commits from its own context (wrong branch)
3. Beads end up on wrong branch
4. Worktree gets out of sync

Setting It

Automatic (gt commands):

// From session/manager.go
_ = m.tmux.SetEnvironment(sessionID, "BEADS_NO_DAEMON", "1")

Manual (shell):

export BEADS_NO_DAEMON=1
bd create --title "My Issue"

Verifying It's Set

In tmux session:

echo $BEADS_NO_DAEMON
# Should output: 1

Check tmux environment:

tmux show-environment -t gt-gastown-polecat1 BEADS_NO_DAEMON

---

Session Errors

Session Identity Parsing

Sessions follow strict naming conventions:

| Pattern | Example | Components | |---------|---------|------------| | gt-mayor | gt-mayor | role=mayor | | gt-deacon | gt-deacon | role=deacon | | gt-{rig}-witness | gt-gastown-witness | rig=gastown, role=witness | | gt-{rig}-refinery | gt-gastown-refinery | rig=gastown, role=refinery | | gt-{rig}-crew-{name} | gt-gastown-crew-joe | rig=gastown, role=crew, name=joe | | gt-{rig}-{polecat} | gt-gastown-nux | rig=gastown, name=nux |

Session State Issues

Session exists but unresponsive

Symptoms: Commands hang, no output

Diagnosis:

tmux has-session -t gt-gastown-nux && echo "exists"
tmux capture-pane -t gt-gastown-nux -p | tail -20

Fix:

gt stop gastown/nux --force
gt start gastown/nux

Session zombie (process dead, session exists)

Symptoms: Session shows in tmux ls but pane is empty

Fix:

tmux kill-session -t gt-gastown-nux
gt start gastown/nux

Multiple sessions for same agent

Error: Confused state, duplicate work

Diagnosis:

tmux list-sessions | grep gastown-nux

Fix: Kill all and restart cleanly

tmux kill-session -t gt-gastown-nux
# If duplicates with suffix:
tmux list-sessions | grep gastown-nux | cut -d: -f1 | xargs -I {} tmux kill-session -t {}
gt start gastown/nux

---

Git Errors

Common Git Issues

Worktree Already Exists

Error: fatal: '<path>' already exists

Cause: Previous worktree not cleaned up

Fix:

git worktree remove <path> --force
# Or manually:
rm -rf <path>
git worktree prune

Detached HEAD in Worktree

Error: Operations fail because not on branch

Diagnosis:

cd <worktree>
git status
# Shows "HEAD detached at..."

Fix:

git checkout <branch>
# Or create new branch:
git checkout -b <new-branch>

Unpushed Commits in Persistent Roles

Warning: Crew/witness/refinery have local commits

Diagnosis:

git log origin/main..HEAD --oneline

Fix:

git push origin main

---

Beads Errors

Redirect Issues

Beads uses redirect files for shared beads access across worktrees.

Circular Redirect

Warning: circular redirect detected in %s (points to itself), ignoring redirect

Cause: Redirect file points back to same directory

Auto-fix: The redirect file is automatically removed

Manual fix:

rm <path>/.beads/redirect

Redirect Chain

Warning: redirect chain detected: %s -> %s (which also has a redirect)

Cause: Multiple levels of redirection

Fix: Remove intermediate redirect:

rm <target>/.beads/redirect

Missing Redirect Target

Symptom: Beads commands fail in worktree

Diagnosis:

cat .beads/redirect
# Check if target exists
ls -la <target-path>

Fix: Recreate redirect or fix target path:

echo "../../mayor/rig/.beads" > .beads/redirect

Routes File Issues

No Routes File

Message: No routes.jsonl file (prefix routing not configured)

Cause: Routes not configured (single-rig setup)

Fix (if needed):

# Routes are created by gt rig add
gt rig add <name> <git-url>

Invalid Route Entry

Symptom: Prefix lookup fails

Diagnosis:

cat ~/gt/.beads/routes.jsonl
# Look for malformed JSON lines

Fix: Edit to correct JSON format:

{"prefix":"gt-","path":"gastown/mayor/rig"}

---

Tmux Errors

No Tmux Server

Error: no tmux server running

Fix:

tmux new-session -d -s scratch
# Or let gt commands start it automatically

Session Already Exists

Error: session already exists

Cause: Tmux session with same name exists

Fix:

tmux kill-session -t <session-name>
# Then retry

Session Not Found

Error: session not found

Cause: Session doesn't exist or was killed

Fix: Start the session:

gt start <agent>

Linked Panes Crosstalk

Symptom: Commands sent to one pane affect another

Cause: Tmux panes sharing same shell process (rare)

Diagnosis:

tmux list-panes -t <session> -F '#{pane_id} #{pane_pid}'
# Check for duplicate PIDs

Fix:

tmux kill-session -t <session>
gt start <agent>

Timeout Errors

timeout waiting for command (still running excluded command)

Cause: Long-running command blocking pane

Fix: Wait for command to complete or:

tmux send-keys -t <session> C-c

timeout waiting for shell

Cause: Shell not ready in pane

Fix: Check if process is stuck:

tmux capture-pane -t <session> -p

timeout waiting for Claude prompt

Cause: Claude not starting or hung

Fix:

gt stop <agent> --force
gt start <agent>

---

Config Version Errors

Version Mismatch

Error: unsupported config version: got %d, max supported %d

Cause: Config file from newer gt version

Current versions:

• TownConfig: Check CurrentTownVersion constant
• RigsConfig: Check CurrentRigsVersion constant
• RigConfig: Check CurrentRigConfigVersion constant
• RigSettings: Check CurrentRigSettingsVersion constant

Fix options:

1. Upgrade gt to newer version
2. Downgrade config version (if compatible)
3. Regenerate config with gt init

Type Mismatch

Error: invalid config type: expected type '%s', got '%s'

Cause: Wrong config file used or corrupted type field

Fix: Correct the type field:

• Town config: "type": "town"
• Rig config: "type": "rig"
• Rig settings: "type": "rig-settings"
• Mayor config: "type": "mayor-config"
• Messaging config: "type": "messaging"

---

Recovery Procedures

Complete Reset

When everything is broken:

# 1. Stop all sessions
gt stop --all --force

# 2. Kill any orphaned tmux sessions
tmux list-sessions | grep '^gt-' | cut -d: -f1 | xargs -I {} tmux kill-session -t {}

# 3. Kill orphaned Claude processes
pkill -f "claude.*--dangerously-skip-permissions" || true

# 4. Run doctor with fix
gt doctor --fix

# 5. Restart daemon
gt deacon restart

# 6. Verify health
gt doctor

Rig Recovery

When a single rig is broken:

# 1. Stop rig agents
gt stop <rig>/witness --force
gt stop <rig>/refinery --force

# 2. Check rig config
cat ~/gt/<rig>/settings/config.json

# 3. Verify worktrees
git -C ~/gt/<rig>/mayor/rig worktree list

# 4. Clean stale worktrees
git -C ~/gt/<rig>/mayor/rig worktree prune

# 5. Restart rig
gt start <rig>/witness
gt start <rig>/refinery

Polecat Recovery

When a polecat is stuck:

# 1. Force stop
gt stop <rig>/<polecat> --force

# 2. Check worktree status
git -C ~/gt/<rig>/polecats/<polecat> status

# 3. Clean any locks
rm -f ~/gt/<rig>/polecats/<polecat>/.git/index.lock

# 4. Reset if needed
git -C ~/gt/<rig>/polecats/<polecat> reset --hard HEAD

# 5. Restart
gt start <rig>/<polecat>

Crew Recovery

When a crew workspace is broken:

# 1. Check state file
cat ~/gt/<rig>/crew/<name>/state.json

# 2. If state is corrupted, regenerate
gt doctor --fix

# 3. Verify git status
git -C ~/gt/<rig>/crew/<name> status

# 4. If on wrong branch
git -C ~/gt/<rig>/crew/<name> checkout main

# 5. Restart if session was running
gt crew attach <rig>/<name>

Beads Database Recovery

When beads are corrupted:

# 1. Backup current state
cp -r ~/gt/.beads ~/gt/.beads.backup

# 2. Check JSONL files for corruption
jq -c '.' ~/gt/.beads/issues.jsonl > /dev/null || echo "Corrupted"

# 3. If corrupted, try to recover valid lines
grep -E '^\{.*\}$' ~/gt/.beads/issues.jsonl > ~/gt/.beads/issues.jsonl.fixed
mv ~/gt/.beads/issues.jsonl.fixed ~/gt/.beads/issues.jsonl

# 4. Rebuild routes if needed
gt doctor --fix

Daemon Recovery

When the daemon is unresponsive:

# 1. Check daemon status
gt deacon status

# 2. Check daemon logs
cat ~/gt/.beads/daemon.log

# 3. Stop daemon forcefully
gt deacon stop --force

# 4. Clean stale markers
rm -f ~/gt/mayor/boot/.marker

# 5. Restart daemon
gt deacon start

# 6. Verify
gt deacon status