| name | troubleshooting |
| description | GT troubleshooting guide for common issues. Use when diagnosing doctor failures, terminal issues, service problems, or beads anomalies. |
| user-invocable | false |
GT Troubleshooting
Common issues and their solutions.
Doctor Check Failures
agent-beads-exist
Symptom: Doctor reports "agent-beads-exist" failure
Cause: Beads prefix mismatch - agents use hq- prefix but configuration expects different prefix
Impact: Non-blocking. GT functions without agent beads.
Status: Known upstream issue (#591, #764)
Action: Note in status report, no immediate fix needed
patrol-not-stuck
Symptom: Doctor reports patrol agent as stuck (false positive)
Cause: Doctor doesn't filter by wisp status - closed wisps still appear
Impact: Warning only
Action: Verify wisp is actually closed. If so, can ignore.
clone-divergence
Symptom: Doctor reports clones have diverged from main
Cause: Rig clones fell behind upstream or are on different branches
Fix:
sudo -u gtuser bash -c 'cd /home/gtuser/gt && gt doctor 2>&1' | grep diverge
sudo -u gtuser bash -c 'cd /home/gtuser/gt/<rig> && git pull'
priming
Symptom: Doctor reports AGENTS.md exceeds 20-line bootstrap limit
Cause: AGENTS.md files in rigs have too much content
Action: Manual edit needed - trim AGENTS.md to be a pointer, not full documentation
Terminal Issues
Orphaned Input in tmux Buffer
Symptom: Mystery text in agent terminal prompt with send indicator
Cause: Crashed session left partial typed input
Fix:
sudo -u gtuser tmux send-keys -t gt-user:main.0 Escape C-u
Popup/Overlay Blocking Terminal
Symptom: Terminal appears frozen or unresponsive
Fix:
sudo -u gtuser tmux send-keys -t gt-user:main.0 Escape
sudo -u gtuser tmux send-keys -t gt-user:main.0 q
sudo -u gtuser tmux send-keys -t gt-user:main.0 Enter
Session Doesn't Exist
Symptom: Commands fail with "session not found"
Check:
sudo -u gtuser tmux list-sessions
Fix: Re-initialize dashboard
/root/projects/COO/tmuxMOO/bin/dashboard.sh
Service Issues
Services Not Starting
Diagnosis:
gt daemon status
sudo -u gtuser tmux list-sessions
sudo -u gtuser bash -c 'cd /home/gtuser/gt && gt doctor --fix --verbose 2>&1'
Mayor Not Responding
Check status:
sudo -u gtuser tmux send-keys -t gt-user:main.0 'gt mayor status' Enter
sleep 2
sudo -u gtuser tmux capture-pane -t gt-user:main.0 -p -S -20
If stuck, nudge:
sudo -u gtuser tmux send-keys -t gt-user:main.0 'gt nudge mayor "status check"' Enter
Beads Issues
Message ID Prefixes
Message IDs use town-level prefix (hq-) regardless of recipient. The prefix comes from beads database location, not recipient address.
Address Resolution
Addresses simplify in storage:
- Sent to:
DReader/crew/steve
- Stored as assignee:
DReader/steve
Be flexible when querying - exact form may vary.
When to Escalate
- Doctor failures persist after 2 fix attempts
- Services won't start after dashboard re-init
- Unknown errors in agent sessions
- Data loss concerns
Document the issue and create a bead for follow-up.
