johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: unify daemon and agent lifecycle protocol

Browse Source 
- ONE daemon for all Gas Town (not per-rig)
- Daemon pokes Mayor and all Witnesses (heartbeat)
- Unified gt handoff command for all agent types
- Lifecycle hierarchy: daemon → mayor/witnesses, witness → polecats/refinery
- Context-aware defaults: polecats shutdown, others cycle

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-18 11:51:13 -08:00
parent ca67f7e779
commit 815b62d2a3
2 changed files with 68 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
.beads/issues.jsonl
View File

@@ -5,7 +5,6 @@
{"id":"gt-0pl","title":"Polecat CLAUDE.md: configure auto-approve for bd and gt commands","description":"Polecats get stuck waiting for bash command approval when running\nbd and gt commands. Need to configure Claude Code to auto-approve these.\n\nOptions:\n1. Add allowedTools to polecat CLAUDE.md\n2. Configure .claude/settings.json in polecat directory\n3. Use --dangerously-skip-permissions flag (not recommended)\n\nShould auto-approve:\n- bd (beads commands)\n- gt (gastown commands)\n- go build/test\n- git status/add/commit/push\n\nShould still require approval:\n- rm -rf\n- Arbitrary commands outside project\n\nRelated to polecat prompting (gt-e1y, gt-sd6).","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T14:10:27.611612-08:00","updated_at":"2025-12-17T14:22:00.715979-08:00","closed_at":"2025-12-17T14:22:00.715979-08:00","close_reason":"Permissions configured in .claude/settings.local.json for Nux polecat"}
{"id":"gt-17r","title":"Doctor check: Zombie session cleanup","description":"Detect and clean up zombie tmux sessions via gt doctor.\n\n## Problem\n\nZombie sessions occur when:\n- Agent crashes without cleanup\n- gt kill fails mid-operation\n- System restart leaves orphan sessions\n- Session naming collision\n\n## Checks\n\n### ZombieSessionCheck\n- List all tmux sessions matching gt-* pattern\n- Cross-reference with known polecats\n- Flag sessions with no corresponding polecat state\n- Flag sessions for removed polecats\n- Check session age vs polecat creation time\n\n### Detection Criteria\n- Session exists but polecat directory doesn't\n- Session name doesn't match any registered polecat\n- Polecat state=idle but session running\n- Multiple sessions for same polecat\n\n## Output\n\n```\n[WARN] Zombie tmux sessions detected:\n - gt-wyvern-OldPolecat (polecat removed)\n - gt-beads-Unknown (no matching polecat)\n - gt-wyvern-Toast (duplicate session)\n\n Run 'gt doctor --fix' to clean up\n```\n\n## Auto-Fix (--fix flag)\n\n- Kill orphan tmux sessions\n- Update polecat state to match reality\n- Log all cleanup actions\n\n## Safety\n\n- Never kill sessions where polecat state=working\n- Prompt before killing if --fix used without --force\n- Create audit log of killed sessions","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T23:18:01.446702-08:00","updated_at":"2025-12-15T23:18:39.517644-08:00","dependencies":[{"issue_id":"gt-17r","depends_on_id":"gt-f9x.4","type":"blocks","created_at":"2025-12-15T23:19:05.66301-08:00","created_by":"daemon"},{"issue_id":"gt-17r","depends_on_id":"gt-7ik","type":"blocks","created_at":"2025-12-17T15:44:41.945064-08:00","created_by":"daemon"}]}
{"id":"gt-1fl","title":"gt crew restart command","description":"Add a 'gt crew restart' command that kills the tmux session and restarts fresh. Useful when a crew member gets confused or needs a clean slate.\n\nShould:\n- Kill existing tmux session if running\n- Start fresh session with claude\n- Run gt prime to reinitialize context\n\nAlias: gt crew rs","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T19:47:32.131386-08:00","updated_at":"2025-12-17T19:47:32.131386-08:00"}
{"id":"gt-1gy","title":"gt mail read: Support numeric indices for message ID","description":"Allow 'gt mail read 1' to read the first message in inbox.\n\nCurrent behavior requires full message ID like 'msg-abc123'.\nShould support:\n- Numeric index: 'gt mail read 1' reads first/newest message\n- Partial ID match: 'gt mail read abc' matches 'msg-abc123'\n\nThis is a UX improvement - agents frequently type 'gt mail read 1'.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T21:49:54.60582-08:00","updated_at":"2025-12-17T22:28:59.846038-08:00","closed_at":"2025-12-17T22:28:59.846038-08:00","close_reason":"Implemented numeric index and partial ID matching for gt mail read/delete","dependencies":[{"issue_id":"gt-1gy","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:22:47.658947-08:00","created_by":"daemon"}]}
{"id":"gt-1j6","title":"Document harness concept in docs/harness.md","description":"Create comprehensive harness documentation:\n- What is a harness (installation directory)\n- Recommended structure and naming\n- .beads/redirect for default project\n- config/ contents (rigs.json, town.json)\n- Mayor home vs rig-level mayor/\n- Example configurations\n- Relationship to rigs","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T17:15:37.559374-08:00","updated_at":"2025-12-17T17:15:37.559374-08:00","dependencies":[{"issue_id":"gt-1j6","depends_on_id":"gt-cr9","type":"blocks","created_at":"2025-12-17T17:15:51.974059-08:00","created_by":"daemon"}]}
{"id":"gt-1ky","title":"CLI: workspace commands (init, add, list)","description":"GGT needs workspace management commands beyond install.\n\n## Commands (beyond gt-f9x.3 install)\n\n### gt workspace list\nList all rigs in current workspace.\n```\ngt workspace list [--json]\n```\nEssentially `gt rig list` but framed as workspace view.\n\n### gt workspace add\nAdd existing rig to workspace (alternative to gt rig add).\n```\ngt workspace add \u003cgit-url\u003e [--name NAME]\n```\n\n### gt onboard\nInteractive first-time setup wizard.\n```\ngt onboard\n```\n- Prompts for workspace location\n- Creates structure via gt install\n- Offers to add first rig\n\n## Note\nMay be redundant with gt-f9x.3 (install) and gt-u1j.16 (rig commands).\nConsider if this is needed or should be closed as covered by those.\n\n## PGT Reference\ngastown-py/src/gastown/cli/workspace_cmd.py","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:47:38.070203-08:00","updated_at":"2025-12-16T16:03:49.715667-08:00"}
{"id":"gt-1le","title":"town handoff command (optional)","description":"CLI commands for session handoff workflow (optional convenience).\n\n## Commands\n\n### gt handoff\nGenerate handoff interactively.\n```\ngt handoff [--send]\n```\n- Collects current state (status, inbox, beads)\n- Prompts for additional notes\n- --send: Mail to self and exit\n\n### gt resume\nCheck for and display pending handoff.\n```\ngt resume\n```\n- Checks inbox for handoff message\n- Displays formatted handoff if found\n- Suggests next actions\n\n## Implementation\n\nThese are convenience wrappers. The same workflow can be done manually:\n```bash\n# Manual handoff\ntown status \u003e /tmp/handoff\ntown inbox \u003e\u003e /tmp/handoff\nbd ready \u003e\u003e /tmp/handoff\n# Edit and send\ntown mail send mayor/ -s \"Session Handoff\" -f /tmp/handoff\n```\n\n## Priority\n\nP2 - Optional. Manual workflow works fine. Nice to have for UX.\n\n## Notes\n\nPart of session cycling workflow designed in gt-u82.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-15T20:15:31.954724-08:00","updated_at":"2025-12-15T23:17:23.967562-08:00","dependencies":[{"issue_id":"gt-1le","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.647043-08:00","created_by":"daemon"}]}
@@ -13,16 +12,13 @@
{"id":"gt-1u9","title":"Interactive prompts for destructive operations","description":"Add interactive confirmations for destructive operations.\n\n## Operations Needing Confirmation\n- `gt swarm cancel` - Cancels active swarm\n- `gt swarm land --force` - Force landing\n- `gt polecat decommission` - Removes polecat\n- `gt rig remove` - Removes rig\n- `gt stop --all` - Stops all sessions\n- `gt mail purge` - Permanently deletes mail\n\n## Implementation Options\n\n### Option 1: promptui library\n```go\nimport \"github.com/manifoldco/promptui\"\n\nprompt := promptui.Prompt{\n Label: \"Delete polecat Toast\",\n IsConfirm: true,\n}\nresult, err := prompt.Run()\n```\n\n### Option 2: Simple stdin\n```go\nfunc confirm(prompt string) bool {\n fmt.Printf(\"%s [y/N]: \", prompt)\n var response string\n fmt.Scanln(\u0026response)\n return strings.ToLower(response) == \"y\"\n}\n```\n\n## Bypass Flags\nAll confirmations skippable with --force or --yes:\n```go\nif !force \u0026\u0026 !confirm(\"Really cancel swarm?\") {\n return nil\n}\n```\n\n## Acceptance Criteria\n- [ ] Destructive ops prompt by default\n- [ ] --force or --yes bypasses\n- [ ] Clear prompt text explaining action\n- [ ] Non-interactive mode (piped input) auto-fails","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T14:48:51.551594-08:00","updated_at":"2025-12-16T16:06:54.283696-08:00"}
{"id":"gt-2bz","title":"Swarm learning: Refinery merge queue automation","description":"Manually merging 15 polecat branches was painful and error-prone. Refinery should automate: detect completed work, run tests, merge to main, handle conflicts. This is core Refinery value prop.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T01:21:51.137974-08:00","updated_at":"2025-12-16T01:51:40.603737-08:00","closed_at":"2025-12-16T01:51:40.603737-08:00","close_reason":"Addressed by gt-kmn.4 (Refinery semantic merge processing loop) and architecture.md Key Decision #12 which enables Refinery session cycling. Refinery merge queue automation is core to the swarm design."}
{"id":"gt-2c1","title":"Swarm learning: Spawn should auto-notify polecats","description":"town spawn assigns issues but doesn't notify polecats. Required separate 'town session send' to inject prompts. This should be one atomic operation - spawn assigns AND pokes the polecat to start working.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T01:21:47.223608-08:00","updated_at":"2025-12-16T01:27:48.746346-08:00","closed_at":"2025-12-16T01:27:48.746346-08:00","close_reason":"GGT spec already addresses this. gt-u1j.19 (spawn command) includes 'Inject initial context' as step 5, which pokes polecats to start working."}
{"id":"gt-2jl","title":"Add bulk polecat remove command (gt polecat remove --all)","description":"When decommissioning a rig, need to remove multiple polecats one at a time. A --all or --rig flag would allow: gt polecat remove --rig gastown --force","status":"closed","priority":3,"issue_type":"feature","created_at":"2025-12-18T11:33:35.206637-08:00","updated_at":"2025-12-18T11:38:53.829321-08:00","closed_at":"2025-12-18T11:38:53.829321-08:00","close_reason":"Wrong model: streaming doesn't need bulk removal - polecats are ephemeral, cleaned up after shutdown request"}
{"id":"gt-2kz","title":"CLI: cleanup commands for stale state","description":"Cleanup commands for recovering from stale state.\n\n## Commands\n\n### gt cleanup \u003cpolecat\u003e\nClean stale state for specific polecat.\n```\ngt cleanup \u003crig\u003e/\u003cpolecat\u003e [--dry-run]\n```\n\nActions:\n- Remove orphaned state.json if clone missing\n- Clear stale session references\n- Reset stuck state (working → idle after timeout)\n\n### gt cleanup --all\nClean all polecats in workspace.\n```\ngt cleanup --all [--dry-run]\n```\n\n## Implementation\n```go\nfunc CleanupPolecat(rigName, polecatName string, dryRun bool) (*CleanupResult, error)\n\ntype CleanupResult struct {\n OrphanedStateRemoved bool\n SessionsCleared int\n StateReset bool\n Warnings []string\n}\n```\n\n## Overlap with Doctor\n- Doctor diagnoses and offers --fix\n- Cleanup is more aggressive state recovery\n- Consider merging into doctor --fix\n\n## New File\ninternal/cmd/cleanup.go\n\n## Acceptance Criteria\n- [ ] Removes orphaned state files\n- [ ] Clears stale session refs\n- [ ] --dry-run shows what would happen\n- [ ] Reports all actions taken","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T14:48:31.944982-08:00","updated_at":"2025-12-16T16:07:12.430696-08:00"}
{"id":"gt-2p2","title":"Test message","description":"Testing GGT mail integration","status":"closed","priority":2,"issue_type":"message","assignee":"gastown-test-polecat","created_at":"2025-12-17T14:04:50.045948-08:00","updated_at":"2025-12-17T14:05:03.125655-08:00","closed_at":"2025-12-17T14:05:03.125655-08:00"}
{"id":"gt-2tp","title":"init.go: Replace custom contains() with strings.Contains","description":"","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-12-16T13:55:11.326407-08:00","updated_at":"2025-12-16T13:56:39.089057-08:00","closed_at":"2025-12-16T13:56:39.089057-08:00","close_reason":"Closed"}
{"id":"gt-2ux","title":"gt uninstall: Clean removal of Gas Town harness","description":"Add 'gt uninstall' command to cleanly remove a Gas Town installation.\n\nShould:\n- Remove harness directory structure\n- Optionally preserve rigs/data with --keep-data flag\n- Warn about running sessions\n- Clean up any global config references","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T21:47:16.175246-08:00","updated_at":"2025-12-17T22:31:12.816428-08:00","closed_at":"2025-12-17T22:31:12.816428-08:00","close_reason":"Implemented gt uninstall command","dependencies":[{"issue_id":"gt-2ux","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:22:47.419553-08:00","created_by":"daemon"}]}
{"id":"gt-30o","title":"Error handling improvements: retry logic and recovery hints","description":"Improve error handling across GGT codebase.\n\n## Issues Found\n\n### 1. Silent Failures in Refinery\nmanager.go ProcessMR():\n- git pull errors ignored\n- Continues processing even on partial failures\n\n### 2. Missing Beads CLI\nMany operations silently continue if `bd` not found:\n```go\n// Current\ntasks, err := m.loadTasksFromBeads(epicID)\nif err != nil {\n // Non-fatal - swarm can start without tasks\n}\n\n// Better\nif err != nil {\n return nil, fmt.Errorf(\"beads required: %w\", err)\n}\n```\n\n### 3. No Retry Logic\nNetwork/lock errors should retry:\n```go\nfunc withRetry(attempts int, delay time.Duration, fn func() error) error {\n for i := 0; i \u003c attempts; i++ {\n if err := fn(); err == nil {\n return nil\n }\n time.Sleep(delay)\n }\n return fmt.Errorf(\"failed after %d attempts\", attempts)\n}\n```\n\n### 4. Recovery Hints\nError messages should include fix suggestions:\n```go\n// Current\nreturn fmt.Errorf(\"polecat not found\")\n\n// Better\nreturn fmt.Errorf(\"polecat '%s' not found. Use 'gt polecat list' to see available polecats\", name)\n```\n\n## Domain Error Types\n```go\ntype SessionError struct {\n Op string\n Polecat string\n Err error\n}\n\nfunc (e *SessionError) Error() string {\n return fmt.Sprintf(\"session %s for %s: %v\", e.Op, e.Polecat, e.Err)\n}\n```\n\n## Files to Review\n- internal/refinery/manager.go\n- internal/swarm/manager.go\n- internal/session/manager.go\n- All cmd/*.go files\n\n## Acceptance Criteria\n- [ ] No silent error swallowing\n- [ ] Retry logic for transient failures\n- [ ] Helpful error messages with hints\n- [ ] Consistent error types per domain","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:48:48.183421-08:00","updated_at":"2025-12-16T16:06:52.751546-08:00"}
{"id":"gt-346","title":"Update harness beads redirect for GGT","description":"Change ~/ai/.beads/redirect from mayor/rigs/gastown/.beads to gastown/mayor/.beads for the GGT directory structure","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-17T16:42:41.650571-08:00","updated_at":"2025-12-17T16:42:41.650571-08:00","dependencies":[{"issue_id":"gt-346","depends_on_id":"gt-l1o","type":"blocks","created_at":"2025-12-17T16:42:54.495061-08:00","created_by":"daemon"},{"issue_id":"gt-346","depends_on_id":"gt-cr9","type":"blocks","created_at":"2025-12-17T17:15:59.04264-08:00","created_by":"daemon"}]}
{"id":"gt-35s","title":"Architecture: beads config and direct landing docs","description":"Added to architecture.md:\n- Beads multi-agent configuration table (daemon, worktree, sync-branch)\n- ASCII directory layout for non-mermaid rendering\n- Direct landing workflow (bypass merge queue)\n- Design decisions 9 and 10 for direct landing and daemon awareness\n- CLI commands for gt land","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T00:29:52.395906-08:00","updated_at":"2025-12-16T00:29:59.188921-08:00","closed_at":"2025-12-16T00:29:59.188921-08:00","close_reason":"Documented in architecture.md"}
{"id":"gt-35x","title":"Plugin: plan-oracle (work decomposition)","description":"Plugin that helps decompose epics/issues into sub-tasks. Analyzes scope, identifies dependencies, estimates complexity for parallelization, creates beads for sub-tasks with dependency links.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-15T22:53:05.772986-08:00","updated_at":"2025-12-15T23:17:06.423894-08:00","dependencies":[{"issue_id":"gt-35x","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.587726-08:00","created_by":"daemon"}]}
{"id":"gt-3a4","title":"Add gt decommission command for clean swarm/worker shutdown","description":"Single command to cleanly shut down a swarm and its workers: cancel swarm, stop sessions, optionally remove polecats. E.g. gt decommission gt-hw6 --cleanup","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-18T11:33:37.217682-08:00","updated_at":"2025-12-18T11:38:55.092852-08:00","closed_at":"2025-12-18T11:38:55.092852-08:00","close_reason":"Wrong model: no swarms to decommission - polecats request shutdown individually, Witness handles cleanup"}
{"id":"gt-3cu","title":"Default polecat names: Mad Max theme instead of AdjectiveNoun","description":"Current default naming for new polecats uses AdjectiveNoun convention.\nSince rigs already provide namespacing, we can use more thematic names.\n\nSuggestion: Use Mad Max / Fury Road character and vehicle names as defaults.\nExamples: Furiosa, Nux, Slit, Morsov, Toast, Rictus, Warboy, etc.\n\nCould also include:\n- War Rig parts: Guzzler, Tanker, Pursuit\n- Citadel roles: Imperator, Blackthumb, Organic\n- Wasteland terms: Chrome, Witness, Shiny\n\nImplementation:\n- Add name generator in internal/polecat/ or similar\n- Use when --create flag is used without explicit name\n- Cycle through pool to avoid duplicates within a rig","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-17T14:50:43.252922-08:00","updated_at":"2025-12-17T14:50:43.252922-08:00"}
{"id":"gt-3fm","title":"Mail orchestrator daemon","description":"Background mail orchestrator daemon.\n\n## Command\n```\ngt mail orchestrate [--interval N] [--once] [--verbose]\n```\n\n## Purpose\nBackground process that:\n1. Monitors outbox for pending mail\n2. Delivers to recipient inboxes\n3. Handles offline recipients (retry later)\n4. Cleans delivered messages from outbox\n\n## Why Needed?\nCurrent mail is synchronous. If recipient is offline or mailbox locked, send fails.\nOrchestrator enables async delivery with retry.\n\n## Implementation\n```go\nfunc (o *Orchestrator) Run(interval time.Duration) error {\n ticker := time.NewTicker(interval)\n for range ticker.C {\n o.processOutbox()\n }\n}\n\nfunc (o *Orchestrator) processOutbox() {\n // List outbox/*.json\n // For each, attempt delivery\n // On success, delete from outbox\n // On failure, increment retry count\n}\n```\n\n## Outbox Structure\n```\n\u003ctown\u003e/mayor/mail/outbox/\n├── msg-abc123.json\n└── msg-def456.json\n```\n\n## Lower Priority\nCurrent synchronous delivery works. Orchestrator is optimization.\n\n## Acceptance Criteria\n- [ ] Background daemon mode\n- [ ] Retry failed deliveries\n- [ ] --once for single pass\n- [ ] Configurable interval","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T14:48:29.830841-08:00","updated_at":"2025-12-16T16:07:35.973257-08:00"}
{"id":"gt-3pp","title":"Support numeric shortcuts in mail read (e.g., 'mail read 1')","description":"When inbox shows numbered messages like:\n* 1. gm-19b29031... 2025-12-16 mayor Subject...\n* 2. gm-19b26d51... 2025-12-16 Subject...\n\nUsers should be able to run 'gt mail read 1' instead of needing the full message ID 'gt mail read gm-19b29031f6a172206'.\n\nImplementation:\n- Track inbox message order in display\n- Map numeric indices to actual message IDs\n- Accept both numeric shortcuts and full IDs in 'mail read' command","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-16T13:15:07.857939-08:00","updated_at":"2025-12-16T13:15:29.273066-08:00"}
@@ -43,19 +39,16 @@
{"id":"gt-61o","title":"Review and audit all GGT beads","description":"Thorough review of all filed beads in gastown GGT repo. Check for: consistency, completeness, correct dependencies, accurate descriptions, proper prioritization. Ensure beads are self-contained and dont rely on external docs.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:07.152386-08:00","updated_at":"2025-12-15T21:23:58.255447-08:00","closed_at":"2025-12-15T21:23:58.255447-08:00","close_reason":"Audit complete: fixed 4 stale doc refs, 1 arch inconsistency, enriched 25+ sparse descriptions"}
{"id":"gt-662","title":"Swarm: report generation","description":"Generate markdown reports for completed swarms.\n\n## Command\n```\ngt swarm report \u003cswarm-id\u003e [--save \u003cfile\u003e]\n```\n\n## Report Content\n\n### Header\n- Swarm ID and title\n- Created/completed timestamps\n- Duration\n- Rig name\n\n### Task Summary\n| Task | Assignee | Status | Duration |\n|------|----------|--------|----------|\n| gt-xxx | Toast | merged | 15m |\n| gt-yyy | Nux | merged | 22m |\n\n### Worker Contributions\n- Commits per worker\n- Issues closed per worker\n- Lines changed (optional)\n\n### Timeline\n- Chronological events from events.jsonl\n- Key milestones (started, first merge, landing)\n\n### Issues Encountered\n- Conflicts resolved\n- Failed tasks (if any)\n- Escalations\n\n## Implementation\n```go\nfunc GenerateReport(swarmID string) (*SwarmReport, error)\nfunc (r *SwarmReport) ToMarkdown() string\n```\n\n## Storage\n- Save to \u003crig\u003e/.gastown/swarms/\u003cid\u003e/report.md\n- Or user-specified path with --save\n\n## PGT Reference\ngastown-py/src/gastown/swarm/manager.py generate_report()\n\n## Acceptance Criteria\n- [ ] Markdown report generated\n- [ ] Includes all sections above\n- [ ] Auto-saved to swarm directory\n- [ ] --save allows custom path","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T14:47:17.96767-08:00","updated_at":"2025-12-16T17:23:22.330075-08:00","closed_at":"2025-12-16T17:23:22.330075-08:00","close_reason":"Duplicate of gt-kmn.10 and depends on swarm ID infrastructure we eliminated. Report generation should work from epic, not swarm ID. See gt-kmn.10 for the reworked approach."}
{"id":"gt-69l","title":"Hook system for event extensibility","description":"GGT needs hook system for extensibility like PGT.\n\n## Event Types\n```go\ntype Event string\nconst (\n EventPreSessionStart Event = \"pre-session-start\"\n EventPostSessionStart Event = \"post-session-start\"\n EventPreShutdown Event = \"pre-shutdown\"\n EventPostShutdown Event = \"post-shutdown\"\n EventOnPaneOutput Event = \"on-pane-output\"\n EventSessionIdle Event = \"session-idle\"\n EventMailReceived Event = \"mail-received\"\n EventWorkAssigned Event = \"work-assigned\"\n)\n```\n\n## Hook Configuration\nFile: .claude/hooks.json or .gastown/hooks.json\n```json\n{\n \"hooks\": {\n \"pre-shutdown\": [\n {\"type\": \"command\", \"cmd\": \"./scripts/pre-shutdown.sh\"}\n ],\n \"on-pane-output\": [\n {\"type\": \"command\", \"cmd\": \"./scripts/activity-monitor.sh\"}\n ]\n }\n}\n```\n\n## Hook Types\n1. **Command**: Execute external script\n2. **Built-in**: Internal Go functions (pre-shutdown checks)\n\n## Hook Interface\n```go\ntype HookRunner struct {\n config *HookConfig\n}\n\ntype HookResult struct {\n Success bool\n Message string\n Block bool // For pre-* hooks: should operation be blocked?\n}\n\nfunc (r *HookRunner) Fire(event Event, ctx *HookContext) []HookResult\n```\n\n## CLI Commands\n```\ngt hooks list [\u003cevent\u003e] # List registered hooks\ngt hooks fire \u003cevent\u003e # Manually fire for testing\ngt hooks test [--all] # Validate hook config\n```\n\n## Integration Points\n- internal/session/manager.go: Fire pre/post session hooks\n- internal/mail/router.go: Fire mail-received hook\n\n## New Package\ninternal/hooks/\n├── types.go # Event, HookConfig, HookResult\n├── runner.go # HookRunner, Fire()\n└── builtin.go # Built-in hooks (pre-shutdown checks)\n\n## PGT Reference\ngastown-py/src/gastown/hooks/\n\n## Acceptance Criteria\n- [ ] Hook config loading from JSON\n- [ ] Command hooks execute subprocess\n- [ ] Pre-shutdown hook integration with session stop\n- [ ] CLI for listing and testing hooks","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:47:34.584907-08:00","updated_at":"2025-12-16T16:04:47.890588-08:00"}
{"id":"gt-6db","title":"gt rig shutdown: Gracefully stop all rig agents","description":"Add 'gt rig shutdown \u003crig\u003e' command to gracefully stop all agents in a rig.\n\nShould:\n- Stop all polecat sessions\n- Stop refinery\n- Stop witness\n- Optionally wait for graceful shutdown with timeout","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T21:50:07.938698-08:00","updated_at":"2025-12-17T21:50:07.938698-08:00","dependencies":[{"issue_id":"gt-6db","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:23:43.179236-08:00","created_by":"daemon"}]}
{"id":"gt-6t0","title":"gt swarm: Not discovering tasks from epic dependents","description":"gt swarm create/start shows '0 tasks loaded' even when epic has dependents.\n\nRepro:\n1. Create epic gt-hw6\n2. Create tasks and add deps: bd dep add gt-xxx gt-hw6\n3. gt swarm create gastown --epic gt-hw6 --worker Toast\n4. Swarm shows 'Tasks: 0'\n\nExpected: Swarm should discover tasks that depend on the epic.\nActual: Shows '(no tasks loaded)'","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-12-17T22:25:41.653628-08:00","updated_at":"2025-12-17T22:31:58.848858-08:00","closed_at":"2025-12-17T22:31:58.848858-08:00","close_reason":"Fixed: spawn wait time, swarm task discovery accepts 'blocks' deps, swarm start spawns workers"}
{"id":"gt-6tf","title":"Implement gt harness create command","description":"Add scaffolding command to create a new harness:\n- gt harness create [path]\n- Creates config/, mayor/, .beads/redirect (optional)\n- Optionally initializes git\n- Generates CLAUDE.md with Mayor role\n- Could also offer a template repo alternative","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-17T17:15:34.342552-08:00","updated_at":"2025-12-17T17:20:36.774805-08:00","closed_at":"2025-12-17T17:20:36.774805-08:00","close_reason":"Implemented as gt install command in gt-f9x.3","dependencies":[{"issue_id":"gt-6tf","depends_on_id":"gt-cr9","type":"blocks","created_at":"2025-12-17T17:15:51.845578-08:00","created_by":"daemon"}]}
{"id":"gt-6z2","title":"Test Epic: GGT MVP Validation","description":"","status":"closed","priority":0,"issue_type":"epic","created_at":"2025-12-16T21:57:37.355269-08:00","updated_at":"2025-12-16T22:06:41.124727-08:00","closed_at":"2025-12-16T22:06:41.124727-08:00","close_reason":"Test issues for MVP validation"}
{"id":"gt-6z2.1","title":"Test Task 1: Add comment to gt.go","description":"","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-16T21:57:43.554166-08:00","updated_at":"2025-12-16T22:06:41.126547-08:00","closed_at":"2025-12-16T22:06:41.126547-08:00","close_reason":"Test issues for MVP validation","dependencies":[{"issue_id":"gt-6z2.1","depends_on_id":"gt-6z2","type":"parent-child","created_at":"2025-12-16T21:57:43.55748-08:00","created_by":"daemon"}]}
{"id":"gt-6z2.2","title":"Test Task 2: Add comment to version.go","description":"","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-16T21:57:43.693217-08:00","updated_at":"2025-12-16T22:06:41.127126-08:00","closed_at":"2025-12-16T22:06:41.127126-08:00","close_reason":"Test issues for MVP validation","dependencies":[{"issue_id":"gt-6z2.2","depends_on_id":"gt-6z2","type":"parent-child","created_at":"2025-12-16T21:57:43.69361-08:00","created_by":"daemon"}]}
{"id":"gt-71i","title":"Update architecture.md: Engineer role and Beads merge queue","description":"Update docs/architecture.md with recent design decisions:\n\n1. Agent table: Change \"Refinery\" role to \"Engineer\"\n - Refinery = place/module/directory\n - Engineer = role (agent that works in the Refinery)\n\n2. Merge Queue section: Document Beads-native model\n - MRs are beads issues with --type=merge-request\n - gt mq commands (submit, list, next, process, reorder)\n - Ordering via depends-on links\n\n3. CLI section: Add gt mq commands\n\n4. Key Design Decisions: Add decisions for:\n - #15: Merge Queue in Beads\n - #16: Engineer role (distinct from Refinery place)\n - #17: Session restart protocol for Engineer","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T23:12:03.616159-08:00","updated_at":"2025-12-16T23:12:03.616159-08:00","dependencies":[{"issue_id":"gt-71i","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:12:14.92163-08:00","created_by":"daemon"}]}
{"id":"gt-7ik","title":"Ephemeral polecats: spawn fresh, delete on completion","description":"## Design Decision\n\nSwitch from pooled/idle polecats to ephemeral model:\n- Spawn creates fresh worktree from main\n- Polecat requests shutdown when done (bottom-up)\n- Witness verifies handoff, kills session, deletes worktree\n- No 'idle' state - polecats exist only while working\n\n## Rationale\n\n1. **Git worktrees are fast** - pooling optimization is obsolete\n2. **Pooling creates maintenance burden:**\n - Git stashes accumulate\n - Untracked artifacts pile up\n - Branches drift from main\n - Beads DB gets stale\n3. **PGT sync problems** came from persistent branches\n4. **Support infrastructure exists** - Witness, Refinery, Mayor handle continuity\n5. **Simpler mental model** - polecat exists = work in progress\n\n## Lifecycle\n\n```\nSpawn:\n gt spawn --issue \u003cid\u003e\n → Creates fresh worktree: git worktree add polecats/\u003cname\u003e -b polecat/\u003cname\u003e\n → Initializes beads in worktree\n → Starts session, assigns work\n\nWorking:\n Polecat does task\n → Pushes to polecat/\u003cname\u003e branch\n → Submits to merge queue when ready\n\nCompletion (POLECAT-INITIATED):\n Polecat runs: gt handoff\n → Verifies git state clean\n → Sends mail to Witness: \"Ready for shutdown\"\n → Marks itself done, waits for termination\n\nCleanup (WITNESS-OWNED):\n Witness receives shutdown request\n → Verifies PR merged or in queue\n → Verifies no uncommitted changes\n → Kills session: gt session stop \u003crig\u003e/\u003cpolecat\u003e\n → Deletes worktree: git worktree remove polecats/\u003cname\u003e\n → Deletes branch: git branch -d polecat/\u003cname\u003e\n → Optionally: Notifies Mayor of completion\n```\n\n## Key Insight: Bottom-Up Shutdown\n\n**Old model (wrong)**: Top-down batch shutdown - \"cancel the swarm\"\n**New model (right)**: Bottom-up individual shutdown - polecat requests, Witness executes\n\nThis enables streaming:\n- Workers come and go continuously\n- No \"swarm end\" to trigger cleanup\n- Each worker manages its own lifecycle\n- Witness is the lifecycle authority\n\n## Implementation\n\n1. Add `gt handoff` command for polecats to request shutdown\n2. Modify gt spawn to always create fresh worktree\n3. Run bd init in new worktree (beads needs initialization)\n4. Add shutdown request handler to Witness\n5. Witness verifies handoff, then cleans up:\n - Kill session\n - Remove worktree\n - Delete branch\n6. Remove 'idle' state from polecat state machine\n7. Simplify gt polecat list (only shows active)\n\n## Impact on Other Tasks\n\n- gt-17r (Zombie cleanup): Becomes trivial - orphan worktrees\n- gt-4my (Worker health): Simpler - no idle/stuck ambiguity\n- gt-f9x.5/f9x.6 (Doctor): Fewer states to validate\n- gt-eu9 (Witness handoff): Witness receives polecat shutdown requests","status":"open","priority":1,"issue_type":"feature","created_at":"2025-12-17T15:44:31.139964-08:00","updated_at":"2025-12-18T11:39:23.202854-08:00"}
{"id":"gt-7ik","title":"Ephemeral polecats: spawn fresh, delete on completion","description":"## Design Decision\n\nSwitch from pooled/idle polecats to ephemeral model:\n- Spawn creates fresh worktree from main\n- Completion deletes worktree and branch\n- No 'idle' state - polecats exist only while working\n\n## Rationale\n\n1. **Git worktrees are fast** - pooling optimization is obsolete\n2. **Pooling creates maintenance burden:**\n - Git stashes accumulate\n - Untracked artifacts pile up\n - Branches drift from main\n - Beads DB gets stale\n3. **PGT sync problems** came from persistent branches\n4. **Support infrastructure exists** - Witness, Refinery, Mayor handle continuity\n5. **Simpler mental model** - polecat exists = work in progress\n\n## Lifecycle\n\n```\nSpawn:\n git worktree add polecats/\u003cname\u003e -b polecat/\u003cname\u003e\n cd polecats/\u003cname\u003e \u0026\u0026 bd init # Initialize beads!\n Start session, assign work\n\nWorking:\n Polecat does task, pushes to integration branch\n\nCompletion:\n Kill session\n git worktree remove polecats/\u003cname\u003e\n git branch -d polecat/\u003cname\u003e\n```\n\n## Implementation\n\n1. Modify gt spawn to always create fresh worktree\n2. **Run bd init in new worktree** (beads needs initialization)\n3. Add cleanup hook to Refinery post-merge\n4. Remove 'idle' state from polecat state machine\n5. Simplify gt polecat list (only shows active)\n6. Simplify zombie handling (just detect orphan worktrees)\n\n## Impact on Other Tasks\n\n- gt-17r (Zombie cleanup): Becomes trivial\n- gt-4my (Worker health): Simpler - no idle/stuck ambiguity\n- gt-f9x.5/f9x.6 (Doctor): Fewer states to validate","status":"open","priority":1,"issue_type":"feature","created_at":"2025-12-17T15:44:31.139964-08:00","updated_at":"2025-12-17T15:45:53.439623-08:00"}
{"id":"gt-7o7","title":"Session pre-shutdown checks","description":"Session stop should verify clean state before killing, like PGT.\n\n## Pre-Shutdown Checks\n\n### 1. Git Working Tree Clean\n```go\nfunc checkGitClean(clonePath string) error {\n // git status --porcelain\n // Fail if any output\n}\n```\n\n### 2. All Commits Pushed\n```go\nfunc checkCommitsPushed(clonePath string) error {\n // git log origin/HEAD..HEAD\n // Fail if any unpushed commits\n}\n```\n\n### 3. Assigned Issues Handled\n```go\nfunc checkIssuesHandled(polecat *Polecat) error {\n // If polecat.Issue != \"\", check if closed or reassigned\n}\n```\n\n### 4. Beads Synced\n```go\nfunc checkBeadsSynced(clonePath string) error {\n // bd sync --status in clone directory\n}\n```\n\n## Behavior on Failure\n1. First attempt: Nudge worker to fix\n2. Retry up to 3 times with delay\n3. After retries: Escalate to Witness/Mayor\n\n## Integration\nModify internal/session/manager.go Stop():\n```go\nfunc (m *Manager) Stop(polecat string, force bool) error {\n if !force {\n if err := m.runPreShutdownChecks(polecat); err != nil {\n return fmt.Errorf(\"pre-shutdown checks failed: %w\", err)\n }\n }\n // existing stop logic\n}\n```\n\n## Flags\n- --force: Skip checks\n- --grace-period N: Time to wait for fixes\n\n## Dependencies\n- Ties into gt-69l (hook system) - can be hook-based\n- Ties into gt-f8v (Witness pre-kill verification)\n\n## Acceptance Criteria\n- [ ] Stop fails if uncommitted changes (without --force)\n- [ ] Stop fails if unpushed commits\n- [ ] Clear error messages with fix instructions\n- [ ] --force bypasses all checks","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:47:55.968983-08:00","updated_at":"2025-12-16T16:05:02.795812-08:00"}
{"id":"gt-7q4","title":"HOP: Skill vectors on work items","description":"Add skill embeddings to work items for capability-based matching. See ~/ai/stevey-gastown/hop/CONTEXT.md. Post-v0.1 work.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-17T01:00:43.251085-08:00","updated_at":"2025-12-17T01:00:43.251085-08:00"}
{"id":"gt-7we","title":"Swarms of One: Lightweight single-worker task dispatch","description":"Design and implement a lightweight pattern for firing off single workers to handle tasks without full swarm overhead.\n\n## Context\n\nCurrently we have:\n- town spawn: Creates a polecat in a rig with issue assignment\n- Swarms (sw-*): Full lifecycle tracking with manifest, state, events, reports\n- Ephemeral rigs (rig-*): Temporary worker groups for swarms\n\nWhat's missing: A simple way to say 'fire off a worker to do X' without swarm ceremony.\n\n## Design Questions\n\n1. Should this be a new command like 'gt fire' or an option on existing commands?\n2. Should single tasks still get swarm IDs (sw-N) for consistency/queryability?\n3. Should it default to creating new workers or support --reuse for idle polecats?\n4. How does this relate to crew workers (gt-cik)?\n\n## Possible Interface\n\ngt fire --rig gastown --issue gt-xyz [--prompt '...']\ngt fire gastown/QuickTask --issue gt-xyz\n\n## Related\n\n- gt-cik: Overseer Crew (user-managed persistent workspaces)\n- gt-kmn: Swarm System epic","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T16:51:02.716629-08:00","updated_at":"2025-12-16T17:23:18.589027-08:00","closed_at":"2025-12-16T17:23:18.589027-08:00","close_reason":"Swarms of One dissolves when we remove Swarm IDs. Work is a stream - spawning one worker is just `gt spawn --issue X`. No special pattern needed. See Key Decision #11 in architecture.md."}
{"id":"gt-82y","title":"Design: Swarm shutdown and worker cleanup","description":"Design for graceful swarm shutdown, worker cleanup, and session cycling.\n\n## Key Decisions\n\n1. Pre-kill verification uses model intelligence (not framework rules)\n2. Witness can request restart when context filling (mail self, exit)\n3. Mayor NOT involved in per-worker cleanup (Witness responsibility)\n4. Clear responsibility boundaries between Mayor/Witness/Polecat\n\n## Subtasks (implementation)\n\n- gt-sd6: Polecat decommission checklist prompting\n- gt-f8v: Witness pre-kill verification protocol\n- gt-eu9: Witness session cycling and handoff\n- gt-gl2: Mayor vs Witness cleanup responsibilities\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T19:47:44.936374-08:00","updated_at":"2025-12-15T20:49:22.849598-08:00","closed_at":"2025-12-15T20:12:05.441911-08:00","close_reason":"Design complete in docs/swarm-shutdown-design.md. Subtasks remain open for implementation."}
{"id":"gt-85a","title":"gt spawn: Not injecting work instructions to session","description":"gt spawn starts session but doesn't inject the issue assignment.\n\nRepro:\n1. gt spawn gastown/Toast --issue gt-2ux\n2. Session starts but polecat just sees Claude prompt\n3. No issue context injected\n\nExpected: Polecat should receive issue details automatically.\nActual: Polecat sits at blank prompt, needs manual injection.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-12-17T22:28:02.583003-08:00","updated_at":"2025-12-17T22:31:58.847834-08:00","closed_at":"2025-12-17T22:31:58.847834-08:00","close_reason":"Fixed: spawn wait time, swarm task discovery accepts 'blocks' deps, swarm start spawns workers"}
{"id":"gt-86w","title":"CLI: doctor diagnostics and auto-repair","description":"GGT completely lacks the doctor command which is critical for debugging.\n\nRequired Commands:\n- gt doctor [\u003crig\u003e] - Run diagnostic checks\n- gt doctor --fix - Auto-repair common issues\n\nChecks to Implement:\nWorkspace Level: Config validity, Mayor mailbox, Rig registry\nRig Level: Git state, clone health, witness/refinery presence, beads sync\nSwarm Level: Stuck detection, zombie sessions, heartbeat health\n\nPGT Reference: gastown-py/src/gastown/cli/dashboard_cmd.py","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T14:46:34.721484-08:00","updated_at":"2025-12-16T16:03:17.405433-08:00","closed_at":"2025-12-16T16:03:17.405433-08:00","close_reason":"Duplicate of gt-f9x.4 + gt-f9x.5 + gt-f9x.6 which cover doctor in detail"}
{"id":"gt-8dv","title":"CLI: plugin commands (list, status)","description":"Add gt plugins \u003crig\u003e to list plugins and gt plugin status \u003cname\u003e to check plugin state. Simple directory scan of \u003crig\u003e/plugins/.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-15T22:53:02.694926-08:00","updated_at":"2025-12-15T23:17:06.594328-08:00","dependencies":[{"issue_id":"gt-8dv","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.413809-08:00","created_by":"daemon"}]}
{"id":"gt-8lz","title":"Comprehensive help text and examples","description":"Improve help text with examples and cross-references.\n\n## Improvements\n\n### 1. Examples Section\nAdd to Long description:\n```go\nvar spawnCmd = \u0026cobra.Command{\n Long: `Spawn a polecat with work assignment.\n\nExamples:\n gt spawn gastown/Toast --issue gt-abc\n gt spawn gastown --issue gt-def # auto-select polecat\n gt spawn gastown/Nux -m \"Fix the tests\" # free-form task`,\n}\n```\n\n### 2. Cross-References\nReference related commands:\n```\nSee also:\n gt polecat list List available polecats\n gt session attach Attach to spawned session\n```\n\n### 3. Flag Descriptions\nMore detail on flags:\n```go\ncmd.Flags().StringVar(\u0026issue, \"issue\", \"\", \n \"Beads issue ID to assign. The polecat will work on this issue.\")\n```\n\n### 4. Common Workflows\nAdd workflow docs to gt --help:\n```\nCommon Workflows:\n Start a swarm:\n gt swarm preflight\n gt swarm create gastown --epic gt-abc --worker Toast --worker Nux --start\n gt refinery start gastown\n \n Check status:\n gt status\n gt swarm status \u003cid\u003e\n```\n\n## Files to Update\nAll internal/cmd/*.go files\n\n## Acceptance Criteria\n- [ ] All commands have Examples\n- [ ] Related commands cross-referenced\n- [ ] Flags have detailed descriptions\n- [ ] Root help shows workflows","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T14:48:53.303016-08:00","updated_at":"2025-12-16T16:07:37.391195-08:00"}
@@ -63,7 +56,6 @@
{"id":"gt-8wf","title":"Polecat prompting: gt mq submit on completion","description":"Update Polecat CLAUDE.md prompting to:\n\n1. On task completion, run: gt mq submit --issue \u003cid\u003e\n2. This creates a merge-request bead in the queue\n3. Engineer will process it\n\nThe Polecat self-reports completion to the merge queue.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T23:02:39.914724-08:00","updated_at":"2025-12-16T23:02:39.914724-08:00","dependencies":[{"issue_id":"gt-8wf","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:02:55.930679-08:00","created_by":"daemon"},{"issue_id":"gt-8wf","depends_on_id":"gt-svi","type":"blocks","created_at":"2025-12-16T23:03:12.950782-08:00","created_by":"daemon"}]}
{"id":"gt-95x","title":"Remove stale migration docs from gastown-py","description":"The gastown-py repo has migration-related documentation that is now misinformation since we have made design decisions. Remove or clearly mark as obsolete: any docs about migration paths, old architecture assumptions, or superseded designs.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:08.642373-08:00","updated_at":"2025-12-15T21:04:39.516436-08:00","closed_at":"2025-12-15T21:04:39.516436-08:00","close_reason":"Removed docs/go-port/ (4 files) and docs/town-design.md from gastown-py"}
{"id":"gt-974","title":"Refinery background daemon mode","description":"The refinery 'gt refinery start' command only works in foreground mode (--foreground). Need to implement background daemon mode for production use.\n\nOptions:\n1. Use a separate tmux session for the refinery\n2. Implement proper daemonization\n3. Use Claude Code session for the refinery agent\n\nFor MVP, option 1 (tmux session) is probably simplest.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T22:08:04.799753-08:00","updated_at":"2025-12-16T22:08:04.799753-08:00"}
{"id":"gt-99m","title":"gt daemon: Background service management","description":"Add 'gt daemon' command group for background service management.\n\nSubcommands:\n- gt daemon start - Start Gas Town daemon (manages all background services)\n- gt daemon stop - Stop daemon\n- gt daemon status - Show daemon status\n- gt daemon logs - View daemon logs\n\nDaemon would coordinate:\n- Witness instances\n- Refinery instances\n- Mail delivery\n- Health monitoring","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-17T21:50:09.763719-08:00","updated_at":"2025-12-17T21:50:09.763719-08:00","dependencies":[{"issue_id":"gt-99m","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:23:43.253877-08:00","created_by":"daemon"}]}
{"id":"gt-9a2","title":"Federation: Wasteland architecture for cross-town coordination","description":"## Overview\n\nFederation enables Gas Town to scale across machines via **Outposts** - remote compute environments that can run workers.\n\n**Design doc**: docs/federation-design.md\n\n## Outpost Types\n\n| Type | Description | Cost Model |\n|------|-------------|------------|\n| Local | Current model (tmux panes) | Free |\n| SSH/VM | Full Gas Town clone on VM | Always-on |\n| CloudRun | Container workers on GCP | Pay-per-use |\n\n## Key Concepts\n\n### Outpost Abstraction\n```go\ntype Outpost interface {\n Name() string\n Type() OutpostType // local, ssh, cloudrun\n MaxWorkers() int\n Spawn(issue string, config WorkerConfig) (Worker, error)\n Workers() []Worker\n Ping() error\n}\n```\n\n### Cloud Run Workers\n- Persistent HTTP/2 connections solve zero-to-one cold start\n- Pay only when working (~$0.017 per 5-min session)\n- Scale 0→N automatically\n- Git clone via persistent volumes\n\n### SSH/VM Outposts \n- Full Gas Town clone on remote machine\n- SSH for commands, git for sync\n- Good for long-running autonomous work\n\n## Design Principles\n\n1. **Outpost abstraction** - support multiple backends\n2. **Local-first** - remote is for overflow/burst\n3. **Git as source of truth** - code and beads sync everywhere\n4. **HTTP for Cloud Run** - dont force mail onto containers\n5. **Graceful degradation** - works with any subset of outposts\n\n## Related\n\n- gt-f9x.7-10: Connection interface (lower-level abstraction)\n- docs/federation-design.md: Full architectural analysis","status":"open","priority":3,"issue_type":"epic","created_at":"2025-12-15T19:21:32.462063-08:00","updated_at":"2025-12-16T18:01:24.224349-08:00"}
{"id":"gt-9a2.1","title":"Outpost/Worker interfaces: Core abstractions for remote compute","description":"## Overview\n\nDefine the core interfaces that all outpost types implement.\n\n## Interfaces\n\n```go\ntype OutpostType string\nconst (\n OutpostLocal OutpostType = \"local\"\n OutpostSSH OutpostType = \"ssh\"\n OutpostCloudRun OutpostType = \"cloudrun\"\n)\n\ntype Outpost interface {\n Name() string\n Type() OutpostType\n MaxWorkers() int\n ActiveWorkers() int\n Spawn(issue string, config WorkerConfig) (Worker, error)\n Workers() []Worker\n Ping() error\n SendMail(worker string, msg Message) error // optional\n}\n\ntype Worker interface {\n ID() string\n Outpost() string\n Status() WorkerStatus // idle, working, done, failed\n Issue() string\n Attach() error // for interactive outposts\n Logs() (io.Reader, error)\n Stop() error\n}\n\ntype WorkerConfig struct {\n RigPath string\n BeadsDir string\n GitBranch string\n Context map[string]string // hints for worker\n}\n```\n\n## Files\n\n- `internal/outpost/outpost.go` - Outpost interface\n- `internal/outpost/worker.go` - Worker interface\n- `internal/outpost/config.go` - WorkerConfig, OutpostType\n\n## Notes\n\nThis is the foundation for all federation work. Keep interfaces minimal - we can extend later.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T18:01:38.268086-08:00","updated_at":"2025-12-16T18:01:38.268086-08:00","dependencies":[{"issue_id":"gt-9a2.1","depends_on_id":"gt-9a2","type":"parent-child","created_at":"2025-12-16T18:01:38.27131-08:00","created_by":"daemon"}]}
{"id":"gt-9a2.10","title":"VM outpost setup: Terraform and documentation","description":"## Overview\n\nDocumentation and optional Terraform for setting up VM outposts.\n\n## Manual Setup Guide\n\n```markdown\n# Setting Up a VM Outpost\n\n## Prerequisites\n- GCE VM (or any Linux machine with SSH access)\n- SSH key pair\n- Git configured on VM\n\n## Steps\n\n1. Install Claude Code on VM:\n ```bash\n ssh user@vm\n npm install -g @anthropic-ai/claude-code\n ```\n\n2. Clone Gas Town:\n ```bash\n mkdir -p ~/ai\n cd ~/ai\n gt install .\n ```\n\n3. Configure Git credentials:\n ```bash\n git config --global user.name \"Your Name\"\n git config --global credential.helper store\n ```\n\n4. Add outpost to local config:\n ```bash\n gt outpost add ssh \\\n --name gce-burst \\\n --host 10.0.0.5 \\\n --user steve \\\n --key ~/.ssh/gce_worker \\\n --town-path /home/steve/ai \\\n --max-workers 8\n ```\n\n5. Test connectivity:\n ```bash\n gt outpost ping gce-burst\n ```\n```\n\n## Terraform Module (Optional)\n\n```hcl\n# deploy/terraform/vm-outpost/main.tf\n\nvariable \"project\" {}\nvariable \"zone\" { default = \"us-central1-a\" }\nvariable \"machine_type\" { default = \"e2-standard-4\" }\n\nresource \"google_compute_instance\" \"outpost\" {\n name = \"gastown-outpost\"\n machine_type = var.machine_type\n zone = var.zone\n\n boot_disk {\n initialize_params {\n image = \"ubuntu-2204-lts\"\n size = 100\n }\n }\n\n network_interface {\n network = \"default\"\n access_config {}\n }\n\n metadata_startup_script = file(\"${path.module}/startup.sh\")\n}\n\noutput \"external_ip\" {\n value = google_compute_instance.outpost.network_interface[0].access_config[0].nat_ip\n}\n```\n\n## Files\n\n- `docs/vm-outpost-setup.md`\n- `deploy/terraform/vm-outpost/` (optional)\n\nDepends on: gt-9a2.5 (SSHOutpost)","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T18:03:34.782908-08:00","updated_at":"2025-12-16T18:03:34.782908-08:00","dependencies":[{"issue_id":"gt-9a2.10","depends_on_id":"gt-9a2","type":"parent-child","created_at":"2025-12-16T18:03:34.78496-08:00","created_by":"daemon"},{"issue_id":"gt-9a2.10","depends_on_id":"gt-9a2.5","type":"blocks","created_at":"2025-12-16T18:03:46.408609-08:00","created_by":"daemon"}]}
@@ -100,14 +92,13 @@
{"id":"gt-cik.8","title":"Crew worker CLAUDE.md prompting","description":"Create CLAUDE.md template for crew workers:\n- Explain crew worker role (overseer's personal workspace)\n- Include mail-to-self handoff instructions\n- Document gt crew refresh for context cycling\n- Explain no witness monitoring (user-managed)\n- Include beads usage if BEADS_DIR configured","status":"closed","priority":2,"issue_type":"task","assignee":"Keeper","created_at":"2025-12-16T16:48:12.108074-08:00","updated_at":"2025-12-16T20:59:02.00287-08:00","closed_at":"2025-12-16T20:59:02.00287-08:00","close_reason":"Work completed and merged to main","dependencies":[{"issue_id":"gt-cik.8","depends_on_id":"gt-cik","type":"parent-child","created_at":"2025-12-16T16:48:12.109654-08:00","created_by":"daemon"}]}
{"id":"gt-cik.9","title":"Complete gt crew commands (list, attach, remove, refresh, status)","description":"Add remaining crew subcommands to internal/cmd/crew.go:\n\n1. gt crew list - List crew workspaces with status\n2. gt crew at/attach - Start tmux session in crew workspace \n3. gt crew remove - Remove crew workspace (with safety checks)\n4. gt crew refresh - Context cycling with mail-to-self handoff\n5. gt crew status - Show detailed workspace status\n\nBuild on existing crew add implementation in internal/cmd/crew.go.\nReference closed issues gt-cik.3-7 for original requirements.","status":"closed","priority":1,"issue_type":"task","assignee":"Furiosa","created_at":"2025-12-16T20:53:25.564877-08:00","updated_at":"2025-12-16T20:59:02.001789-08:00","closed_at":"2025-12-16T20:59:02.001789-08:00","close_reason":"Work completed and merged to main","dependencies":[{"issue_id":"gt-cik.9","depends_on_id":"gt-cik","type":"parent-child","created_at":"2025-12-16T20:53:25.566962-08:00","created_by":"daemon"}]}
{"id":"gt-cjb","title":"Witness updates: Remove issue filing proxy","description":"Update Witness prompting to remove issue filing proxy, since polecats now have direct beads access.\n\n## Remove from Witness Prompting\n\nThe following is NO LONGER Witness responsibility:\n- Processing polecat 'file issue' mail requests\n- Creating issues on behalf of polecats\n- Forwarding issue creation requests\n\n## Add: Legacy Request Handling\n\nIf Witness receives an old-style 'please file issue' request:\n\n1. Respond with update:\n town inject \u003cpolecat\u003e \"UPDATE: You have direct beads access now. Use bd create to file issues yourself.\"\n\n2. Do not file the issue - let the polecat learn the new workflow.\n\n## Keep in Witness Prompting\n\n- Monitoring polecat progress\n- Nudge protocol\n- Pre-kill verification\n- Session lifecycle management","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:19.921561-08:00","updated_at":"2025-12-15T20:48:36.020922-08:00","dependencies":[{"issue_id":"gt-cjb","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.896691-08:00","created_by":"daemon"}]}
{"id":"gt-cnt","title":"Swarm cleanup: delete merged polecat branches and reset state","description":"After a swarm completes and branches are merged, leftover state remains:\n\n## Current Problem\n\n1. **Remote branches not deleted** - polecat/* branches stay on origin after merge\n2. **Polecat clones not reset** - still on old branch with completed work\n3. **No cleanup command** - manual cleanup required\n\n## Observed After Swarm\n\nRemote branches still present:\n- origin/polecat/Morsov\n- origin/polecat/Nux \n- origin/polecat/Rictus\n- origin/polecat/Slit\n- origin/polecat/Toast\n\n## Proposed Solution\n\nAdd cleanup commands:\n\n1. gt swarm cleanup \u003cswarm-id\u003e - Clean up after swarm completion\n - Delete remote polecat branches that were merged\n - Reset polecat clones to main\n - Clear issue assignments\n \n2. gt polecat reset \u003crig\u003e/\u003cpolecat\u003e - Reset single polecat\n - git checkout main \u0026\u0026 git pull\n - Delete local polecat branch\n - Clear current issue assignment\n\n3. Auto-cleanup option on gt session stop --cleanup\n\n## Manual Cleanup For Now\n\ngit push origin --delete polecat/Nux polecat/Toast ...\ncd polecats/Nux \u0026\u0026 git checkout main \u0026\u0026 git pull","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T15:09:08.739193-08:00","updated_at":"2025-12-18T11:38:56.305923-08:00","closed_at":"2025-12-18T11:38:56.305923-08:00","close_reason":"Wrong model: swarm cleanup assumes discrete batches. In streaming model, polecats are ephemeral - deleted after work completes. See gt-7ik for ephemeral polecat design."}
{"id":"gt-cnt","title":"Swarm cleanup: delete merged polecat branches and reset state","description":"After a swarm completes and branches are merged, leftover state remains:\n\n## Current Problem\n\n1. **Remote branches not deleted** - polecat/* branches stay on origin after merge\n2. **Polecat clones not reset** - still on old branch with completed work\n3. **No cleanup command** - manual cleanup required\n\n## Observed After Swarm\n\nRemote branches still present:\n- origin/polecat/Morsov\n- origin/polecat/Nux \n- origin/polecat/Rictus\n- origin/polecat/Slit\n- origin/polecat/Toast\n\n## Proposed Solution\n\nAdd cleanup commands:\n\n1. gt swarm cleanup \u003cswarm-id\u003e - Clean up after swarm completion\n - Delete remote polecat branches that were merged\n - Reset polecat clones to main\n - Clear issue assignments\n \n2. gt polecat reset \u003crig\u003e/\u003cpolecat\u003e - Reset single polecat\n - git checkout main \u0026\u0026 git pull\n - Delete local polecat branch\n - Clear current issue assignment\n\n3. Auto-cleanup option on gt session stop --cleanup\n\n## Manual Cleanup For Now\n\ngit push origin --delete polecat/Nux polecat/Toast ...\ncd polecats/Nux \u0026\u0026 git checkout main \u0026\u0026 git pull","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-17T15:09:08.739193-08:00","updated_at":"2025-12-17T15:09:08.739193-08:00"}
{"id":"gt-cr0","title":"Consolidate design docs into beads descriptions","description":"The markdown design docs (swarm-shutdown-design.md, polecat-beads-access-design.md, mayor-handoff-design.md) will decay. Extract key decisions and prompting templates into the beads descriptions themselves, then archive or remove the markdown files. Beads are the source of truth.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:05.45131-08:00","updated_at":"2025-12-15T20:51:52.083465-08:00","closed_at":"2025-12-15T20:51:52.083465-08:00","close_reason":"Consolidated: created docs/architecture.md, moved design content into bead descriptions, deleted 4 individual design docs"}
{"id":"gt-cr9","title":"Harness Design \u0026 Documentation","description":"The harness (Gas Town installation directory) needs design cleanup, documentation, and tooling.\n\n## Current Problems\n\n1. **Shared harness confusion**: ~/ai is shared by PGT and GGT with overlapping structures\n - PGT uses ~/ai/mayor/ as town-level Mayor home\n - GGT Mayor works in ~/ai/mayor/rigs/gastown/\n - ~/ai/gastown/ has both .gastown/ (PGT) and mayor/ (git clone)\n\n2. **Beads redirect**: ~/ai/.beads/redirect → mayor/rigs/gastown/.beads\n - This is specific to GGT's decentralized structure\n - Should be documented as an example\n\n3. **architecture.md**: Verify rig-level mayor/rig/ is shown correctly\n\n4. **No harness creation tooling**: Users must manually set up\n\n## Proposed Work\n\n- Document what a harness IS (installation directory)\n- Create harness creation command or template repo\n- Update architecture.md if needed \n- Create example harness configuration for docs\n- Resolve PGT/GGT sharing issue","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-17T17:15:08.769961-08:00","updated_at":"2025-12-17T17:15:17.610323-08:00"}
{"id":"gt-ctr","title":"GGT vs PGT Gap Analysis Summary","description":"Summary of gaps comparing GGT (~4,500 LOC) to PGT (~27,700 LOC).\n\n## Critical Gaps (P1) - Existing Issues\n- gt-u1j.17: Polecat CLI (add, list, wake, sleep) - DETAILED\n- gt-u1j.16: Rig CLI (add, list, show, remove) - DETAILED\n- gt-u1j.18: Witness CLI (start, stop, status) - DETAILED\n- gt-f9x.4: Doctor framework - DETAILED\n- gt-f9x.5: Workspace doctor checks - DETAILED\n- gt-f9x.6: Rig doctor checks - DETAILED\n\n## Critical Gaps (P1) - New Issues\n- gt-a95: Refinery background daemon mode - ENHANCED\n- gt-hgk: Mail message types and threading - ENHANCED\n\n## Significant Gaps (P2) - New Issues\n- gt-d46: Mail CLI archive/purge/search - ENHANCED\n- gt-e9k: Swarm preflight/postflight - ENHANCED\n- gt-662: Swarm report generation - ENHANCED\n- gt-69l: Hook system - ENHANCED\n- gt-3yj: Agent monitoring - ENHANCED\n- gt-1ky: Workspace CLI (may overlap f9x.3) - ENHANCED\n- gt-9j9: Worker status reporting - ENHANCED\n- gt-qao: Mayor CLI - ENHANCED\n- gt-7o7: Session pre-shutdown checks - ENHANCED\n- gt-c92: Batch all command - ENHANCED\n- gt-lno: Swarm state persistence - ENHANCED\n- gt-a9y: File locking - ENHANCED\n- gt-30o: Error handling improvements - ENHANCED\n\n## Significant Gaps (P2) - Existing Issues\n- gt-kmn.12: Ephemeral rig support - DETAILED\n\n## Lower Priority (P3) - New Issues\n- gt-3fm: Mail orchestrator daemon - ENHANCED\n- gt-2kz: Cleanup commands - ENHANCED\n- gt-ebl: Names commands - ENHANCED\n- gt-1u9: Interactive prompts - ENHANCED\n- gt-8lz: Help text improvements - ENHANCED\n\n## Closed as Duplicates\n- gt-3tz → gt-u1j.17 (polecat CLI)\n- gt-e1r → gt-u1j.16 (rig CLI)\n- gt-86w → gt-f9x.4/5/6 (doctor)\n- gt-alx → gt-kmn.12 (ephemeral rigs)\n\n## Execution Order Recommendation\n1. P1 CLI commands (existing detailed issues ready to implement)\n2. gt-a95: Refinery daemon (blocks autonomous operation)\n3. gt-7o7: Pre-shutdown checks (prevents data loss)\n4. gt-a9y: File locking (prevents corruption)\n5. gt-hgk + gt-d46: Mail improvements\n6. gt-69l: Hook system (enables extensibility)\n7. Remaining P2s in any order\n8. P3s as time permits","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-16T14:49:09.555759-08:00","updated_at":"2025-12-16T16:07:58.413016-08:00"}
{"id":"gt-cxx","title":"Swarm learning: Witness needs automated context cycling","description":"Furiosa hit 2% context during swarm work. Witness role needs automated detection of low context and should trigger session cycling before agents get stuck. Add to Witness responsibilities in prompts.md.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T01:21:49.67756-08:00","updated_at":"2025-12-16T01:51:39.2553-08:00","closed_at":"2025-12-16T01:51:39.2553-08:00","close_reason":"Addressed by architecture.md Key Decision #12 (Agent Session Lifecycle). Daemon monitors agent health and restarts sessions after handoff. Witness self-cycling protocol documented in prompts.md."}
{"id":"gt-d3d","title":"Design: Additional design issues (placeholder)","description":"Placeholder for additional design issues the user wants to raise and work through. Convert to specific subtasks as issues are identified.","status":"open","priority":4,"issue_type":"epic","created_at":"2025-12-15T20:24:12.601585-08:00","updated_at":"2025-12-15T23:17:32.467687-08:00"}
{"id":"gt-d46","title":"Mail CLI: archive, purge, search, mark","description":"GGT mail CLI needs more commands for mail management.\n\n## Commands to Add\n\n### gt mail check\nCheck for new mail without full inbox display.\n```\ngt mail check [--quiet] [--inject]\n```\n- --quiet: Only output if new mail (for scripts)\n- --inject: Send notification to running session\n\n### gt mail mark\nChange read status.\n```\ngt mail mark \u003cid\u003e --read\ngt mail mark \u003cid\u003e --unread\n```\n\n### gt mail delete\nRemove message from inbox.\n```\ngt mail delete \u003cid\u003e [--force]\n```\n- Confirm unless --force\n\n### gt mail archive\nMove old/read messages to archive.\n```\ngt mail archive [--older-than DAYS] [--all-read] [--dry-run]\n```\n- Creates inbox.jsonl.archive or separate archive.jsonl\n\n### gt mail purge\nPermanently delete archived messages.\n```\ngt mail purge [--older-than DAYS] [--dry-run] [--force]\n```\n\n### gt mail search\nFind messages by content.\n```\ngt mail search \u003cquery\u003e [--from SENDER] [--subject] [--body]\n```\n\n### gt mail reply\nReply to a message.\n```\ngt mail reply \u003cid\u003e -m BODY\n```\n- Auto-sets reply_to and thread_id\n- Auto-addresses to original sender\n\n## Files to Modify\n- internal/cmd/mail.go: Add commands\n- internal/mail/mailbox.go: Add Archive(), Search(), Delete()\n\n## Acceptance Criteria\n- [ ] All commands implemented\n- [ ] Archive stores in separate file\n- [ ] Search supports regex patterns\n- [ ] Delete confirms by default","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:46:57.158136-08:00","updated_at":"2025-12-16T16:04:32.922813-08:00"}
{"id":"gt-d7i","title":"gt session capture: Support positional line count argument","description":"Make 'gt session capture gastown/Toast 50' work.\n\nCurrently requires: gt session capture gastown/Toast -n 50\nShould also accept: gt session capture gastown/Toast 50\n\nAgent UX principle: commands should work the way agents guess they work.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-17T22:28:44.291285-08:00","updated_at":"2025-12-17T22:28:44.291285-08:00"}
{"id":"gt-dck","title":"Update config location: .gastown/ → config/","description":"Move rig configuration from hidden .gastown/ to visible config/:\n- config/rig.json: Rig configuration\n- config/engineer.json: Engineer settings (test command, etc.)\n- config/witness.json: Witness settings (heartbeat interval, etc.)\n\nHidden directories are poorly discovered by AI agents.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T23:02:20.400818-08:00","updated_at":"2025-12-16T23:02:20.400818-08:00","dependencies":[{"issue_id":"gt-dck","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:02:55.69517-08:00","created_by":"daemon"}]}
{"id":"gt-dkc","title":"Add harness overview to Mayor priming","description":"Update gt prime Mayor context to explain the harness concept: umbrella repo for GT installation, rigs underneath, Mayor sits above all rigs","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T16:42:44.864606-08:00","updated_at":"2025-12-17T16:44:12.568963-08:00","closed_at":"2025-12-17T16:44:12.568963-08:00","close_reason":"Added harness overview, architecture section, and updated directory structure in prime.go","dependencies":[{"issue_id":"gt-dkc","depends_on_id":"gt-l1o","type":"blocks","created_at":"2025-12-17T16:42:54.736437-08:00","created_by":"daemon"}]}
{"id":"gt-dq3","title":"Split PGT/GGT harness or migrate to GGT-only","description":"Current ~/ai harness is shared by PGT and GGT with confusing overlap. Options:\n1. Keep separate (document the coexistence)\n2. Migrate fully to GGT structure\n3. Create separate harnesses\n\nThis affects the beads redirect, Mayor home location, and rig structure.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-17T17:15:32.308192-08:00","updated_at":"2025-12-17T17:15:32.308192-08:00","dependencies":[{"issue_id":"gt-dq3","depends_on_id":"gt-cr9","type":"blocks","created_at":"2025-12-17T17:15:51.717903-08:00","created_by":"daemon"}]}
@@ -115,10 +106,8 @@
{"id":"gt-e1r","title":"CLI: rig commands (add, list, show, remove)","description":"GGT needs rig management commands.\n\nMissing Commands:\n- gt rig add \u003cgit-url\u003e [--name NAME] - Add rig to workspace\n- gt rig list - List all rigs with status\n- gt rig show \u003crig\u003e - Show detailed rig info\n- gt rig remove \u003crig\u003e - Remove a rig\n\nPGT Reference: gastown-py/src/gastown/cli/rig_cmd.py\n\nCurrent State:\n- gt init creates rig structure but no ongoing management\n- Rig discovery in internal/rig/manager.go but not exposed via CLI","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T14:46:33.23951-08:00","updated_at":"2025-12-16T16:03:15.727426-08:00","closed_at":"2025-12-16T16:03:15.727426-08:00","close_reason":"Duplicate of gt-u1j.16 which has more detail"}
{"id":"gt-e1y","title":"Worker prompting: Beads write access","description":"Add beads write access section to polecat AGENTS.md.template.\n\n## Beads Access Section for Prompting\n\n```markdown\n## Beads Access\n\nYou have **full beads access** - create, update, and close issues.\n\n### Quick Reference\n\n```bash\n# View work\nbd ready # Issues ready (no blockers)\nbd list # All open issues\nbd show \u003cid\u003e # Issue details\n\n# Create issues\nbd create --title=\"Fix bug\" --type=bug --priority=2\nbd create --title=\"Add feature\" --type=feature\n\n# Update issues\nbd update \u003cid\u003e --status=in_progress # Claim work\nbd close \u003cid\u003e # Mark complete\n\n# Sync (required before merge!)\nbd sync # Commit beads changes to git\n```\n\n### When to Create Issues\n\nCreate beads issues when you discover work that:\n- Is outside your current task scope\n- Would benefit from tracking\n- Should be done by someone else\n\n**Good examples**:\n```bash\nbd create --title=\"Race condition in auth\" --type=bug --priority=1\nbd create --title=\"Document API rate limits\" --type=task --priority=3\n```\n\n**Don't create for**:\n- Tiny fixes you can do in 2 minutes\n- Vague \"improvements\" with no scope\n- Work already tracked elsewhere\n\n### Beads Sync Protocol\n\n**CRITICAL**: Always sync beads before merging!\n\n```bash\nbd sync # Commits beads changes\ngit add .beads/\ngit commit -m \"beads: sync\"\n```\n\nIf you forget to sync, beads changes are lost when session ends.\n```\n\n## Implementation\n\nAdd to AGENTS.md.template polecat section.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:18.459363-08:00","updated_at":"2025-12-15T20:48:03.813068-08:00","dependencies":[{"issue_id":"gt-e1y","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.81183-08:00","created_by":"daemon"}]}
{"id":"gt-e5o","title":"Fix role detection for nested rig structures","description":"When gastown/ has its own mayor/ dir, workspace detection finds it as town root instead of ~/ai. This breaks polecat/refinery/witness detection when running from within a rig.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-17T16:47:18.519581-08:00","updated_at":"2025-12-17T17:02:51.8271-08:00","closed_at":"2025-12-17T17:02:51.8271-08:00","close_reason":"Fixed workspace detection to prefer primary markers (config/town.json or mayor/config.json) over secondary marker (mayor/). Now continues searching upward after finding secondary marker to avoid matching rig-level mayor directories."}
{"id":"gt-e76","title":"gt mail reply/thread: Conversation support","description":"Add mail conversation features:\n\n- gt mail reply \u003cid\u003e -m 'message' - Reply to a message\n- gt mail thread \u003cid\u003e - Show all messages in a thread\n\nEnables back-and-forth communication between agents.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T21:50:06.215773-08:00","updated_at":"2025-12-17T21:50:06.215773-08:00","dependencies":[{"issue_id":"gt-e76","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:23:43.106435-08:00","created_by":"daemon"}]}
{"id":"gt-e9k","title":"Workspace cleanup: preflight and postflight","description":"Workspace preflight and postflight commands for clean state management.\n\n## Preflight\n```\ngt preflight [--rig \u003crig\u003e] [--dry-run]\n```\n\nRun before starting batch work:\n1. Clean stale mail in inboxes\n2. Check for stuck workers (warn)\n3. Check rig health (polecats, refinery)\n4. Verify git state is clean\n5. Run bd sync to ensure beads current\n\n## Postflight\n```\ngt postflight [--rig \u003crig\u003e] [--archive-mail] [--dry-run]\n```\n\nRun after batch work completes:\n1. Archive old mail with --archive-mail\n2. Clean up stale integration branches\n3. Sync beads\n4. Report on rig state\n\n## Implementation\n```go\nfunc Preflight(rigName string, dryRun bool) (*PreflightReport, error)\nfunc Postflight(rigName string, opts PostflightOptions) (*PostflightReport, error)\n```\n\n## Report Structures\n```go\ntype PreflightReport struct {\n MailCleaned int\n RigHealthy bool\n StuckWorkers []string\n Warnings []string\n}\n\ntype PostflightReport struct {\n MailArchived int\n BranchesCleaned int\n Warnings []string\n}\n```\n\n## Note\n\nThese are workspace maintenance commands, not tied to \"swarm\" lifecycle. Run them anytime to keep the rig clean.\n\n## Acceptance Criteria\n- [ ] Preflight cleans stale state\n- [ ] Postflight archives old mail\n- [ ] Both have --dry-run mode\n- [ ] Clear reports of actions taken","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:47:15.997677-08:00","updated_at":"2025-12-16T17:25:01.55269-08:00"}
{"id":"gt-ebl","title":"CLI: names commands for polecat naming pool","description":"Polecat naming pool for auto-generated names.\n\n## Commands\n\n### gt names generate\n```\ngt names generate [--count N]\n```\nGenerate N names from pool.\n\n### gt names add\n```\ngt names add \u003cname\u003e...\n```\nAdd custom names to pool.\n\n### gt names list\n```\ngt names list\n```\nShow available and used names.\n\n### gt names reset\n```\ngt names reset [--keep-used]\n```\nReset pool to defaults.\n\n## Config File\n\u003crig\u003e/town/naming.json:\n```json\n{\n \"enabled\": true,\n \"auto_refill\": true,\n \"refill_threshold\": 5,\n \"pool\": {\n \"available\": [\"Toast\", \"Nux\", \"Capable\", ...],\n \"used\": [\"Alice\", \"Bob\"]\n }\n}\n```\n\n## Default Pool\nMad Max themed: Toast, Nux, Capable, Furiosa, Immortan, etc.\n\n## Integration\ngt polecat add calls naming pool if no name given:\n```go\nif name == \"\" {\n name, err = naming.Generate(rigPath)\n}\n```\n\n## New Package\ninternal/naming/\n├── pool.go # Pool management\n└── defaults.go # Default name lists\n\n## Acceptance Criteria\n- [ ] Auto-generate names on polecat add\n- [ ] Track used vs available\n- [ ] Auto-refill when low\n- [ ] Custom names addable","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T14:48:33.592129-08:00","updated_at":"2025-12-16T16:07:13.882465-08:00"}
{"id":"gt-egu","title":"gt refinery attach: Attach to refinery session","description":"Add 'gt refinery attach [rig]' command to attach to refinery tmux session.\n\nMirrors 'gt mayor attach' pattern. If rig not specified, use current rig context.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T21:47:19.164342-08:00","updated_at":"2025-12-17T22:28:45.661097-08:00","closed_at":"2025-12-17T22:28:45.661097-08:00","close_reason":"Implemented gt refinery attach command","dependencies":[{"issue_id":"gt-egu","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:22:47.578871-08:00","created_by":"daemon"}]}
{"id":"gt-eu9","title":"Witness session cycling and handoff","description":"Add session cycling and handoff protocol to Witness CLAUDE.md template.\n\n## Session Cycling Protocol\n\n```markdown\n## Session Cycling\n\nYour context will fill over long swarms. Proactively cycle when:\n- Running for many hours\n- Losing track of which workers you've checked\n- Responses getting slower\n- About to start complex operation\n\n### Handoff Protocol\n\n1. **Capture current state**:\n```bash\ntown list . # Worker states\ntown all beads # Pending verifications \ntown inbox # Unprocessed messages\n```\n\n2. **Compose handoff note**:\n```\n[HANDOFF_TYPE]: witness_cycle\n[TIMESTAMP]: \u003cnow\u003e\n[RIG]: \u003crig\u003e\n\n## Active Workers\n\u003clist workers and status\u003e\n\n## Pending Verifications\n\u003cworkers signaled done but not verified\u003e\n\n## Recent Actions\n\u003clast 3-5 actions\u003e\n\n## Warnings/Notes\n\u003canything next session should know\u003e\n\n## Next Steps\n\u003cwhat should happen next\u003e\n```\n\n3. **Send handoff**:\n```bash\ntown mail send \u003crig\u003e/witness -s \"Session Handoff\" -m \"\u003cnote\u003e\"\n```\n\n4. **Exit cleanly**: End session, daemon spawns fresh one.\n\n### On Fresh Session Start\n\n1. Check for handoff: `town inbox | grep \"Session Handoff\"`\n2. If found, read it and resume from handoff state\n3. If not found, do full status check\n```\n\n## Implementation\n\nAdd to WITNESS_CLAUDE.md template.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:55.484911-08:00","updated_at":"2025-12-15T20:47:30.768506-08:00","dependencies":[{"issue_id":"gt-eu9","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:05.846443-08:00","created_by":"daemon"}]}
{"id":"gt-f8v","title":"Witness pre-kill verification protocol","description":"Add pre-kill verification protocol to Witness CLAUDE.md template.\n\n## Protocol for Witness Prompting\n\n```markdown\n## Pre-Kill Verification Protocol\n\nBefore killing any worker session, verify workspace is clean.\n\n### Verification Steps\n\nWhen a worker signals done:\n\n1. **Capture worker state**:\n```bash\ntown capture \u003cpolecat\u003e \"git status \u0026\u0026 git stash list \u0026\u0026 bd sync --status\"\n```\n\n2. **Assess the output** (use your judgment):\n- Is working tree clean?\n- Is stash list empty?\n- Is beads synced?\n\n3. **Decision**:\n- **CLEAN**: Proceed to kill session\n- **DIRTY**: Send nudge with specific issues\n\n### Nudge Templates\n\n**Uncommitted Changes**:\n```\ntown inject \u003cpolecat\u003e \"WITNESS CHECK: Uncommitted changes found. Please commit or discard: \u003cfiles\u003e. Signal done when clean.\"\n```\n\n**Beads Not Synced**:\n```\ntown inject \u003cpolecat\u003e \"WITNESS CHECK: Beads not synced. Run 'bd sync' then commit. Signal done when complete.\"\n```\n\n### Kill Sequence\n\nOnly after verification passes:\n```bash\ntown kill \u003cpolecat\u003e\ntown sleep \u003cpolecat\u003e\n```\n\n### Escalation\n\nIf worker fails verification 3+ times:\n```bash\ntown mail send mayor/ -s \"Escalation: \u003cpolecat\u003e stuck\" -m \"Cannot complete cleanup after 3 attempts. Issues: \u003clist\u003e.\"\n```\n```\n\n## Implementation\n\nAdd to WITNESS_CLAUDE.md template.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:54.065679-08:00","updated_at":"2025-12-15T20:47:30.415244-08:00","dependencies":[{"issue_id":"gt-f8v","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:05.763378-08:00","created_by":"daemon"}]}
{"id":"gt-f9x","title":"Town \u0026 Rig Management: install, doctor, federation","description":"Reify the Gas Town installation as a first-class concept.\n\n## Goals\n- Installable: gt install [path] creates complete installation\n- Diagnosable: gt doctor checks and fixes issues\n- Federable: Clone town to VMs with central control\n\n## Architecture Reference\n\nSee docs/architecture.md for full design, especially:\n- Directory structure (Town Level / Rig Level sections)\n- Configuration (town.json, rigs.json schemas)\n- Key design decisions (visible config dir, decentralized agents)","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-15T16:36:37.344283-08:00","updated_at":"2025-12-15T21:15:13.120038-08:00","dependencies":[{"issue_id":"gt-f9x","depends_on_id":"gt-u1j.1","type":"blocks","created_at":"2025-12-15T16:37:32.3363-08:00","created_by":"daemon"}]}
@@ -134,10 +123,9 @@
{"id":"gt-f9x.9","title":"Machine registry: Store and manage machine configs","description":"Registry for managing remote machines in federation.\n\n## Data Model\n\n```go\ntype Machine struct {\n Name string `json:\"name\"`\n Type string `json:\"type\"` // \"local\", \"ssh\", \"gcp\"\n Host string `json:\"host\"` // for ssh: user@host\n KeyPath string `json:\"key_path\"` // SSH key path\n TownPath string `json:\"town_path\"` // Path to town on remote\n}\n```\n\n## Interface\n\n```go\ntype MachineRegistry struct {\n path string // config/federation.json\n machines map[string]*Machine\n}\n\nfunc NewMachineRegistry(configPath string) *MachineRegistry\nfunc (r *MachineRegistry) Get(name string) (*Machine, error)\nfunc (r *MachineRegistry) Add(m *Machine) error\nfunc (r *MachineRegistry) Remove(name string) error\nfunc (r *MachineRegistry) List() []*Machine\nfunc (r *MachineRegistry) Connection(name string) (Connection, error)\n```\n\n## Storage\n\nfederation.json in config/:\n```json\n{\n \"version\": 1,\n \"machines\": {\n \"local\": {\"type\": \"local\"},\n \"gcp-vm-1\": {\n \"type\": \"ssh\",\n \"host\": \"user@10.0.0.1\",\n \"key_path\": \"~/.ssh/gcp_key\",\n \"town_path\": \"/home/user/ai\"\n }\n }\n}\n```\n\n## Connection Factory\n\n```go\nfunc (r *MachineRegistry) Connection(name string) (Connection, error) {\n m := r.machines[name]\n switch m.Type {\n case \"local\":\n return NewLocalConnection(), nil\n case \"ssh\":\n return NewSSHConnection(m.Host, m.KeyPath), nil\n }\n}\n```","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-15T16:37:21.968099-08:00","updated_at":"2025-12-15T23:17:18.644857-08:00","dependencies":[{"issue_id":"gt-f9x.9","depends_on_id":"gt-f9x","type":"parent-child","created_at":"2025-12-15T16:37:21.968442-08:00","created_by":"daemon"},{"issue_id":"gt-f9x.9","depends_on_id":"gt-f9x.7","type":"blocks","created_at":"2025-12-15T16:37:36.174052-08:00","created_by":"daemon"}]}
{"id":"gt-fko","title":"Add Gas Town theory of operation to all role primings","description":"All roles (Mayor, Witness, Refinery, Polecat) should get basic GT architecture context: harness, rigs, agents, mail, beads workflow","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-17T16:42:46.445526-08:00","updated_at":"2025-12-17T17:00:36.466742-08:00","closed_at":"2025-12-17T17:00:36.466742-08:00","close_reason":"Work completed in gt-u1j.20: All role templates now include Gas Town architecture section with harness, rigs, agents, mail, and beads workflow context","dependencies":[{"issue_id":"gt-fko","depends_on_id":"gt-l1o","type":"blocks","created_at":"2025-12-17T16:42:54.87032-08:00","created_by":"daemon"},{"issue_id":"gt-fko","depends_on_id":"gt-dkc","type":"blocks","created_at":"2025-12-17T16:42:56.409618-08:00","created_by":"daemon"}]}
{"id":"gt-g2d","title":"Mayor session cycling prompting","description":"Add session cycling section to Mayor CLAUDE.md template.\n\n## When to Cycle\n\nCycle proactively when:\n- Running for several hours\n- Context feels crowded (losing track of earlier state)\n- Major phase completed\n- About to start complex new work\n\n## Composing Handoff Notes\n\n1. Gather information:\n town status # Overall health\n town rigs # Each rig state\n town inbox # Pending messages\n bd ready # Work items\n\n2. Compose note with this structure:\n\n[HANDOFF_TYPE]: mayor_cycle\n[TIMESTAMP]: \u003ccurrent time\u003e\n[SESSION_DURATION]: \u003chow long running\u003e\n\n## Active Swarms\n\u003cper-rig swarm status\u003e\n\n## Rig Status\n\u003ctable of rig health\u003e\n\n## Pending Escalations\n\u003cissues needing your decision\u003e\n\n## In-Flight Decisions\n\u003cdecisions being made\u003e\n\n## Recent Actions\n\u003clast 5-10 things you did\u003e\n\n## Delegated Work\n\u003cwork sent to refineries\u003e\n\n## User Requests\n\u003cpending user asks\u003e\n\n## Next Steps\n\u003cwhat next session should do\u003e\n\n## Warnings/Notes\n\u003ccritical info for next session\u003e\n\n3. Send handoff:\n town mail send mayor/ -s \"Session Handoff\" -m \"\u003cnote\u003e\"\n\n4. End session - next instance picks up from handoff.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T20:15:26.188561-08:00","updated_at":"2025-12-15T20:48:39.861022-08:00","dependencies":[{"issue_id":"gt-g2d","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.361163-08:00","created_by":"daemon"}]}
{"id":"gt-gby","title":"gt handoff: Polecat shutdown request command","description":"## Summary\n\nImplement `gt handoff` command for polecats to request shutdown from Witness.\n\nIn the streaming model, polecats initiate their own shutdown (bottom-up) rather than being killed by top-down batch commands. This enables continuous work flow without artificial \"swarm\" boundaries.\n\n## Command: gt handoff\n\nRun by polecat when work is complete:\n\n```bash\ngt handoff [--message \"completion notes\"]\n```\n\n### What it does:\n\n1. **Verify git state clean**\n - No uncommitted changes\n - No untracked files (except .beads artifacts)\n - Branch pushed to remote\n\n2. **Verify work handed off**\n - PR created or in merge queue\n - Issue updated with completion status\n\n3. **Send shutdown request to Witness**\n ```bash\n gt mail send \u003crig\u003e/witness -s \"Shutdown request: \u003cpolecat\u003e\" -m \"...\"\n ```\n Message includes:\n - Polecat name\n - Completed issue ID\n - Branch name\n - Any completion notes\n\n4. **Update polecat state**\n - Set state to \"done\" (or new \"pending_shutdown\" state)\n - Polecat should NOT exit - wait for Witness to kill session\n\n### Failure modes:\n\n- Git state dirty → Fail with instructions to commit/push\n- PR not created → Fail with instructions to submit to merge queue\n- Witness unreachable → Retry or escalate\n\n## Witness Handler\n\nWitness receives shutdown request and:\n\n1. Verifies polecat is safe to kill\n - PR merged or queued\n - No data loss risk\n\n2. Kills session\n ```bash\n gt session stop \u003crig\u003e/\u003cpolecat\u003e\n ```\n\n3. Cleans up (per gt-7ik ephemeral design)\n ```bash\n git worktree remove polecats/\u003cname\u003e\n git branch -d polecat/\u003cname\u003e\n ```\n\n4. Optionally notifies Mayor of completion\n\n## Depends on\n\n- gt-7ik: Ephemeral polecats design (overall lifecycle)\n- gt-eu9: Witness session cycling (Witness receives mail)\n\n## Acceptance Criteria\n\n- [ ] `gt handoff` command implemented\n- [ ] Validates git state before requesting shutdown\n- [ ] Sends mail to Witness with shutdown request\n- [ ] Witness handler receives and processes request\n- [ ] Session killed, worktree removed, branch deleted\n- [ ] Polecat CLAUDE.md updated with handoff protocol","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-18T11:39:40.806863-08:00","updated_at":"2025-12-18T11:39:40.806863-08:00","dependencies":[{"issue_id":"gt-gby","depends_on_id":"gt-7ik","type":"blocks","created_at":"2025-12-18T11:39:46.423945-08:00","created_by":"daemon"},{"issue_id":"gt-gby","depends_on_id":"gt-eu9","type":"blocks","created_at":"2025-12-18T11:39:46.547204-08:00","created_by":"daemon"}]}
{"id":"gt-gl2","title":"Clarify Mayor vs Witness cleanup responsibilities","description":"Document the cleanup authority model: Witness owns ALL per-worker cleanup, Mayor never involved.\n\n## The Rule\n\n**Witness handles ALL per-worker cleanup. Mayor is never involved.**\n\n## Why This Matters\n\n1. Separation of concerns: Mayor strategic, Witness operational\n2. Reduced coordination overhead: No back-and-forth for routine cleanup\n3. Faster shutdown: Witness kills workers immediately upon verification\n4. Cleaner escalation: Mayor only hears about problems\n\n## What Witness Handles\n\n- Verifying worker git state before kill\n- Nudging workers to fix dirty state\n- Killing worker sessions\n- Updating worker state (sleep/wake)\n- Logging verification results\n\n## What Mayor Handles\n\n- Receiving swarm complete notifications\n- Deciding whether to start new swarms\n- Handling escalations (stuck workers after 3 retries)\n- Cross-rig coordination\n\n## Escalation Path\n\nWorker stuck -\u003e Witness nudges (up to 3x) -\u003e Witness escalates to Mayor -\u003e Mayor decides: force kill, reassign, or human\n\n## Anti-Patterns\n\nDO NOT: Mayor asks Witness if worker X is clean\nDO: Witness reports swarm complete, all workers verified\n\nDO NOT: Mayor kills worker sessions directly\nDO: Mayor tells Witness to abort swarm, Witness handles cleanup\n\nDO NOT: Workers report done to Mayor\nDO: Workers report to Witness, Witness aggregates and reports up","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:56.678724-08:00","updated_at":"2025-12-15T20:48:12.068964-08:00","dependencies":[{"issue_id":"gt-gl2","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:05.929877-08:00","created_by":"daemon"}]}
{"id":"gt-h5n","title":"Merge Queue in Beads: Universal chit system for all work","description":"\n\n**Design doc**: docs/merge-queue-design.md","status":"open","priority":0,"issue_type":"epic","created_at":"2025-12-16T23:01:45.782171-08:00","updated_at":"2025-12-17T13:43:43.211867-08:00"}
{"id":"gt-h5n.1","title":"MR field parsing: extract structured fields from description","description":"Parse merge-request beads to extract structured fields:\n- branch: source branch name\n- target: target branch (main or integration/xxx)\n- source_issue: the work item being merged\n- worker: who did the work\n- rig: which rig\n- merge_commit: (set on close)\n- close_reason: (set on close)\n\nFields stored in description as YAML block or key: value lines.\nProvide helper functions: ParseMRFields(issue) and SetMRFields(issue, fields).\n\nReference: docs/merge-queue-design.md#merge-request-schema","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-17T13:47:46.682379-08:00","updated_at":"2025-12-17T13:47:46.682379-08:00","dependencies":[{"issue_id":"gt-h5n.1","depends_on_id":"gt-h5n","type":"parent-child","created_at":"2025-12-17T13:47:46.682911-08:00","created_by":"daemon"}]}
{"id":"gt-h5n.1","title":"MR field parsing: extract structured fields from description","description":"Parse merge-request beads to extract structured fields:\n- branch: source branch name\n- target: target branch (main or integration/xxx)\n- source_issue: the work item being merged\n- worker: who did the work\n- rig: which rig\n- merge_commit: (set on close)\n- close_reason: (set on close)\n\nFields stored in description as YAML block or key: value lines.\nProvide helper functions: ParseMRFields(issue) and SetMRFields(issue, fields).\n\nReference: docs/merge-queue-design.md#merge-request-schema","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-17T13:47:46.682379-08:00","updated_at":"2025-12-18T11:46:18.970805-08:00","closed_at":"2025-12-18T11:46:18.970805-08:00","close_reason":"Implementation complete: MRFields struct with ParseMRFields, SetMRFields, and FormatMRFields functions in internal/beads/beads.go. All 6 test suites pass.","dependencies":[{"issue_id":"gt-h5n.1","depends_on_id":"gt-h5n","type":"parent-child","created_at":"2025-12-17T13:47:46.682911-08:00","created_by":"daemon"}]}
{"id":"gt-h5n.10","title":"Auto-rebase on conflict: optional automatic rebase","description":"Implement automatic rebase as conflict resolution option.\n\nWhen on_conflict=auto_rebase and conflicts detected:\n1. Attempt: git rebase \u003ctarget\u003e \u003csource-branch\u003e\n2. If clean rebase: update source branch, continue merge\n3. If conflicts in rebase: abort, fall back to assign_back\n4. Force push rebased branch (worker's branch)\n\nRequires:\n- Worker branch must be force-pushable\n- Config: on_conflict: auto_rebase\n\nRisks:\n- Force push can confuse workers\n- Complex conflicts still need manual resolution\n\nReference: docs/merge-queue-design.md#conflict-resolution-strategies","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T13:52:26.397214-08:00","updated_at":"2025-12-17T13:52:26.397214-08:00","dependencies":[{"issue_id":"gt-h5n.10","depends_on_id":"gt-h5n","type":"parent-child","created_at":"2025-12-17T13:52:26.399236-08:00","created_by":"daemon"},{"issue_id":"gt-h5n.10","depends_on_id":"gt-3x1.4","type":"blocks","created_at":"2025-12-17T13:53:23.158089-08:00","created_by":"daemon"}]}
{"id":"gt-h5n.11","title":"Retry logic: exponential backoff for transient failures","description":"Implement retry logic for transient failures.\n\nRetryable failures:\n- Push failed (network, auth transient)\n- Test flaky (config: retry_flaky_tests)\n- Fetch failed (network)\n\nRetry strategy:\n- Max retries: 3 (configurable)\n- Backoff: 1s, 2s, 4s (exponential)\n- On final failure: treat as permanent, assign back\n\nNon-retryable failures:\n- Merge conflict\n- Test consistently fails\n- Build error\n\nTrack retry count in MR metadata for debugging.\n\nReference: docs/merge-queue-design.md#failure-recovery","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T13:52:28.300658-08:00","updated_at":"2025-12-17T13:52:28.300658-08:00","dependencies":[{"issue_id":"gt-h5n.11","depends_on_id":"gt-h5n","type":"parent-child","created_at":"2025-12-17T13:52:28.302268-08:00","created_by":"daemon"},{"issue_id":"gt-h5n.11","depends_on_id":"gt-3x1.4","type":"blocks","created_at":"2025-12-17T13:53:23.277535-08:00","created_by":"daemon"}]}
{"id":"gt-h5n.12","title":"MQ metrics: pending count, processing time, success rate","description":"Implement merge queue metrics collection.\n\nMetrics to track:\n- mq_pending_count: MRs waiting\n- mq_processing_time: Time from submit to merge (histogram)\n- mq_success_rate: Merges vs rejections\n- mq_conflict_rate: How often conflicts occur\n- mq_test_failure_rate: Test failures\n\nStorage options:\n- Simple: JSON file with rolling stats\n- Advanced: Prometheus-compatible metrics endpoint\n\nDisplay via:\n- gt mq stats: summary statistics\n- Dashboard widget (separate task)\n\nReference: docs/merge-queue-design.md#observability","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T13:52:30.716666-08:00","updated_at":"2025-12-17T13:52:30.716666-08:00","dependencies":[{"issue_id":"gt-h5n.12","depends_on_id":"gt-h5n","type":"parent-child","created_at":"2025-12-17T13:52:30.718745-08:00","created_by":"daemon"},{"issue_id":"gt-h5n.12","depends_on_id":"gt-3x1.5","type":"blocks","created_at":"2025-12-17T13:53:23.392465-08:00","created_by":"daemon"}]}
@@ -153,8 +141,6 @@
{"id":"gt-h5n.8","title":"MQ config schema: merge_queue section in rig config.json","description":"Define and implement merge_queue configuration in rig config.\n\nSchema:\n{\n \"merge_queue\": {\n \"enabled\": true,\n \"target_branch\": \"main\",\n \"integration_branches\": true,\n \"on_conflict\": \"assign_back\", // or \"auto_rebase\"\n \"run_tests\": true,\n \"test_command\": \"go test ./...\",\n \"delete_merged_branches\": true,\n \"retry_flaky_tests\": 1,\n \"poll_interval\": \"30s\",\n \"max_concurrent\": 1\n }\n}\n\nImplement:\n- Config loading in rig package\n- Default values\n- Validation\n\nReference: docs/merge-queue-design.md#configuration","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-17T13:52:00.322779-08:00","updated_at":"2025-12-17T13:52:00.322779-08:00","dependencies":[{"issue_id":"gt-h5n.8","depends_on_id":"gt-h5n","type":"parent-child","created_at":"2025-12-17T13:52:00.324781-08:00","created_by":"daemon"}]}
{"id":"gt-h5n.9","title":"Per-epic config overrides: custom merge settings","description":"Allow per-epic merge configuration overrides.\n\nEpic can specify merge_config in its description:\n merge_config:\n run_tests: true\n test_command: 'go test -race ./...'\n on_conflict: assign_back\n\nWhen processing MRs for an epic:\n1. Load rig-level merge_queue config\n2. Check if epic has merge_config\n3. Merge epic config over rig config\n4. Use merged config for processing\n\nUse cases:\n- Risky refactors: more thorough testing\n- Urgent fixes: skip some checks\n- Experimental work: different test suite\n\nReference: docs/merge-queue-design.md#per-epic-overrides","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T13:52:02.32832-08:00","updated_at":"2025-12-17T13:52:02.32832-08:00","dependencies":[{"issue_id":"gt-h5n.9","depends_on_id":"gt-h5n","type":"parent-child","created_at":"2025-12-17T13:52:02.32997-08:00","created_by":"daemon"}]}
{"id":"gt-hgk","title":"Mail system: message types and threading","description":"GGT mail system needs message types and threading like PGT.\n\n## 1. Message Types\nAdd to internal/mail/types.go:\n```go\ntype MessageType string\nconst (\n TypeTask MessageType = \"task\" // Required processing\n TypeScavenge MessageType = \"scavenge\" // Optional first-come work\n TypeNotification MessageType = \"notification\" // Informational\n TypeReply MessageType = \"reply\" // Response to message\n)\n\n// Update Message struct\ntype Message struct {\n // existing fields...\n Type MessageType `json:\"type\"`\n ThreadID string `json:\"thread_id,omitempty\"`\n ReplyTo string `json:\"reply_to,omitempty\"`\n}\n```\n\n## 2. Priority Levels\nExpand from 2 to 4:\n```go\ntype Priority string\nconst (\n PriorityLow Priority = \"low\"\n PriorityNormal Priority = \"normal\"\n PriorityHigh Priority = \"high\"\n PriorityUrgent Priority = \"urgent\"\n)\n```\n\n## 3. CLI Updates\ninternal/cmd/mail.go:\n- Add --type flag to send: `gt mail send ... --type task`\n- Add --reply-to flag: `gt mail send ... --reply-to \u003cmsg-id\u003e`\n- Add thread command: `gt mail thread \u003cthread-id\u003e`\n\n## 4. Threading Logic\nNewMessage() should auto-generate thread_id if not a reply.\nReply messages inherit thread_id from original.\n\n## Files to Modify\n- internal/mail/types.go: Add types, expand Priority\n- internal/mail/mailbox.go: Thread filtering\n- internal/cmd/mail.go: CLI flags and thread command\n\n## PGT Reference\ngastown-py/src/gastown/mail/message.py\n\n## Acceptance Criteria\n- [ ] Messages have type field (default: notification)\n- [ ] 4 priority levels supported\n- [ ] Reply creates thread with shared thread_id\n- [ ] gt mail thread \u003cid\u003e shows conversation","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T14:46:55.29463-08:00","updated_at":"2025-12-16T16:04:20.748583-08:00"}
{"id":"gt-hw6","title":"GGT Command Parity: Complete gt command coverage","description":"Complete gt command set to match/exceed PGT town commands.\n\nCovers: uninstall, rig info, refinery attach, witness, session mgmt, mail UX, daemon.","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-17T22:22:21.720078-08:00","updated_at":"2025-12-17T22:22:21.720078-08:00"}
{"id":"gt-hzr","title":"gt witness: Witness management commands","description":"Add 'gt witness' command group for witness lifecycle management.\n\nSubcommands:\n- gt witness start [rig] - Start witness for a rig\n- gt witness stop [rig] - Stop witness\n- gt witness status [rig] - Show witness status\n- gt witness attach [rig] - Attach to witness session\n\nWitness monitors polecats and handles:\n- Idle detection and cleanup\n- Session health checks\n- Nudging stuck agents","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T21:47:32.210917-08:00","updated_at":"2025-12-17T21:47:32.210917-08:00","dependencies":[{"issue_id":"gt-hzr","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:23:42.955006-08:00","created_by":"daemon"}]}
{"id":"gt-iib","title":"Architecture: Decentralized rig structure with per-rig agents","description":"## Decision\n\nAdopt decentralized architecture where each rig contains all its agents (mayor/, witness/, refinery/, polecats/) rather than centralizing mayor clones at town level.\n\n## Town Level Structure\n\n```\n~/ai/ # Town root\n├── config/ # Town config (VISIBLE, not hidden)\n│ ├── town.json # {\"type\": \"town\"}\n│ ├── rigs.json # Registry of managed rigs\n│ └── federation.json # Wasteland config (future)\n│\n├── mayor/ # Mayor's HOME at town level\n│ ├── CLAUDE.md\n│ ├── mail/inbox.jsonl\n│ └── state.json\n│\n└── \u003crigs\u003e/ # Managed projects\n```\n\n## Rig Level Structure (e.g., wyvern)\n\n```\nwyvern/ # Rig = clone of project repo\n├── .git/info/exclude # Gas Town adds: polecats/ refinery/ witness/ mayor/\n├── .beads/ # Beads (if project uses it)\n├── [project files] # Clean project code on main\n│\n├── polecats/ # Worker clones\n│ └── \u003cname\u003e/ # Each is a git clone\n│\n├── refinery/\n│ ├── rig/ # Refinery's clone\n│ ├── state.json\n│ └── mail/inbox.jsonl\n│\n├── witness/ # NEW: Per-rig pit boss\n│ ├── rig/ # Witness's clone\n│ ├── state.json\n│ └── mail/inbox.jsonl\n│\n└── mayor/\n ├── rig/ # Mayor's clone for this rig\n └── state.json\n```\n\n## Key Decisions\n\n1. **Visible config dir**: `config/` not `.gastown/` (models don't find hidden dirs)\n2. **Witness per-rig**: Each rig has its own Witness (pit boss) with its own clone\n3. **Mayor decentralized**: Mayor's clones live IN each rig at `\u003crig\u003e/mayor/rig/`\n4. **Minimal invasiveness**: Only `.git/info/exclude` modified, no commits to project\n5. **Clone subdir name**: Keep `rig/` for consistency (refinery/rig/, witness/rig/, mayor/rig/)\n\n## Role Detection\n\n- Town root or mayor/ → Mayor (town level)\n- Rig root → Mayor (canonical main)\n- \u003crig\u003e/mayor/rig/ → Mayor (rig-specific)\n- \u003crig\u003e/refinery/rig/ → Refinery\n- \u003crig\u003e/witness/rig/ → Witness\n- \u003crig\u003e/polecats/\u003cname\u003e/ → Polecat\n\n## Migration from PGT\n\n- `mayor/rigs/\u003crig\u003e/` → `\u003crig\u003e/mayor/rig/`\n- `\u003crig\u003e/town/` → eliminated (rig root IS the clone)\n- Add `witness/` to each rig","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-15T19:21:19.913928-08:00","updated_at":"2025-12-15T19:21:40.461186-08:00","closed_at":"2025-12-15T19:21:40.461186-08:00","close_reason":"Design decision recorded","dependencies":[{"issue_id":"gt-iib","depends_on_id":"gt-u1j","type":"blocks","created_at":"2025-12-15T19:21:40.374551-08:00","created_by":"daemon"}]}
{"id":"gt-j87","title":"Design: Work flow simulation and validation","description":"Validate GGT designs through simulation before implementation.\n\n## Validation Approaches\n\n### 1. Dry-Run Simulation (Recommended First)\nMayor walks through scenarios mentally/on paper:\n- \"If polecat Toast signals done with dirty git state, what happens?\"\n- \"If Witness context fills mid-verification, what state is lost?\"\n- \"If two polecats try to close same issue, what happens?\"\n\nCreate beads for any gaps discovered.\n\n### 2. Real Work in gastown-py\nUse Python Gas Town to stress-test assumptions:\n- Run actual batch work on test repos\n- Observe edge cases in practice\n- Document issues found\n\n### 3. Edge Case Analysis\nSystematic review of failure modes:\n- Agent crashes mid-operation\n- Network failures during sync\n- Concurrent access to shared state\n- Context limits hit at bad times\n\n## Key Scenarios to Validate\n\n- [ ] Witness session cycling (state preservation)\n- [ ] Polecat decommission with dirty state\n- [ ] Merge conflicts in queue\n- [ ] Beads sync conflicts between workers\n- [ ] Escalation path (stuck worker -\u003e Mayor)\n- [ ] Cross-rig communication\n- [ ] Federation mail routing (future)\n\n## Success Criteria\n\n- No data loss scenarios identified\n- Clear recovery paths for all failure modes\n- Edge cases either handled or documented as limitations\n- Design improves as model cognition improves\n\n## Output\n\nFor each scenario validated:\n1. Document in relevant bead if issue found\n2. Create new beads for missing functionality\n3. Update architecture.md if design changes","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-15T20:24:11.251841-08:00","updated_at":"2025-12-16T17:25:49.858717-08:00"}
{"id":"gt-jpt","title":"Town-level beads: Real DB for coordination mail","description":"Implement Option A from mail redesign: Town gets real beads DB for coordination.\n\n## Background\n\nMail is now Beads. But currently:\n- Town .beads/redirect points to rig beads\n- mayor/mail/ has legacy JSONL files\n- Cross-rig coordination has no clear home\n\n## Design\n\nTown beads = coordination, cross-rig mail, mayor inbox, handoffs\nRig beads = project issues, work items\n\nMatches HOP hierarchy: platform \u003e project \u003e worker\n\n## Structure\n\n~/gt/\n .beads/ # REAL beads DB (prefix: gm-)\n mayor/\n town.json\n state.json # NO mail/ directory\n gastown/\n .beads/ # Rig beads (prefix: ga-)\n\n## Tasks\n\n1. Delete ~/gt/.beads/redirect\n2. Run bd init --prefix gm at ~/gt/ (town beads)\n3. Delete ~/gt/mayor/mail/ directory\n4. Update gt mail to use beads not JSONL\n5. Add mail fields (thread_id, reply_to, msg_type)\n6. Update gt prime for two-tier model\n7. Update docs/architecture.md\n\n## Addressing\n\n- mayor/ -\u003e town beads\n- rig/agent -\u003e rig beads\n- Cross-rig -\u003e town beads","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-17T19:09:55.855955-08:00","updated_at":"2025-12-17T19:10:06.399802-08:00"}
@@ -179,7 +165,6 @@
{"id":"gt-l9g","title":"Beads epic templates for batch work patterns","description":"Optional: Define templates for common batch work patterns.\n\n## Concept\n\nA template encodes a workflow pattern that can be instantiated as beads:\n\n```yaml\n# templates/batch-basic.yaml\nname: basic-batch\ndescription: Simple batch work pattern\nphases:\n - name: startup\n issues:\n - title: \"Verify workers ready\"\n - name: working\n # Actual work issues added separately\n - name: cleanup\n issues:\n - title: \"Merge all branches\"\n - title: \"Clean up workers\"\n - title: \"Report to Mayor\"\n```\n\n## Usage\n\n```bash\ngt spawn --template basic-batch --epic gt-u1j --workers 3\n```\n\nCreates beads epic with template phases + actual work from gt-u1j children.\n\n## Decision Point\n\nTemplates are OPTIONAL. The core design (beads as state, multi-wave orchestration) works without templates. Templates are sugar for common patterns.\n\nConsider deferring to P3 or dropping entirely if beads epics with dependencies suffice.\n\n## Note\n\nNo \"swarm IDs\" involved - templates just pre-populate epic/issue structure.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T01:51:24.399235-08:00","updated_at":"2025-12-16T17:26:08.868396-08:00"}
{"id":"gt-lno","title":"Swarm state persistence: manifest + state + events","description":"Upgrade swarm persistence to match PGT pattern.\n\n## Current State\nSingle .gastown/swarms.json with all swarms.\n\n## Target State (per-swarm)\n```\n.gastown/swarms/\n└── \u003cswarm-id\u003e/\n ├── manifest.json # Immutable config\n ├── state.json # Mutable progress\n ├── events.jsonl # Audit log\n └── report.md # Generated report\n```\n\n## File Schemas\n\n### manifest.json (immutable after creation)\n```json\n{\n \"id\": \"sw-1\",\n \"title\": \"Epic description\",\n \"epic_id\": \"gt-abc\",\n \"rig\": \"gastown\",\n \"base_commit\": \"abc123\",\n \"integration_branch\": \"swarm/sw-1\",\n \"target_branch\": \"main\",\n \"workers\": [\"Toast\", \"Nux\"],\n \"tasks\": [{\"id\": \"gt-xyz\", \"title\": \"...\"}],\n \"created_at\": \"2024-01-01T00:00:00Z\"\n}\n```\n\n### state.json (mutable)\n```json\n{\n \"state\": \"active\",\n \"task_states\": {\n \"gt-xyz\": {\"state\": \"merged\", \"assignee\": \"Toast\"}\n },\n \"updated_at\": \"2024-01-01T01:00:00Z\",\n \"error\": null\n}\n```\n\n### events.jsonl (append-only audit)\n```jsonl\n{\"event\": \"created\", \"ts\": \"...\", \"data\": {...}}\n{\"event\": \"task_assigned\", \"ts\": \"...\", \"data\": {...}}\n{\"event\": \"task_merged\", \"ts\": \"...\", \"data\": {...}}\n```\n\n## Benefits\n- Audit trail via events.jsonl\n- Manifest immutability prevents corruption\n- Cleaner separation of concerns\n- Per-swarm isolation\n\n## Migration\nKeep backward compat with swarms.json during transition.\n\n## Files to Modify\n- internal/swarm/manager.go: Refactor persistence\n- internal/cmd/swarm.go: SwarmStore → directory-based\n\n## Acceptance Criteria\n- [ ] Per-swarm directory structure\n- [ ] Events logged to JSONL\n- [ ] Manifest immutable after creation\n- [ ] List command aggregates from directories","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T14:48:14.151538-08:00","updated_at":"2025-12-16T17:23:19.716405-08:00","closed_at":"2025-12-16T17:23:19.716405-08:00","close_reason":"Swarm state persistence is redundant. Beads IS the persistence layer - epics track batch work, issues track tasks, status tracks progress. No separate manifest/state/events needed. See Key Decision #11 in architecture.md."}
{"id":"gt-njr","title":"Engineer session restart protocol","description":"Implement session restart flow for when the Engineer needs to split work:\n\n1. Engineer creates subtask(s) in Beads assigned to self\n2. Engineer sends handoff mail to self (🤝 HANDOFF)\n3. Engineer sends restart request to Witness\n4. Witness verifies:\n - Handoff mail exists in Engineer outbox/sent\n - Subtasks filed in Beads\n5. Witness restarts the Refinery session (new Engineer context)\n\nThis enables \"occasionally consistent, eventually convergent\" work patterns.\nThe Refinery continues; the Engineer gets fresh context.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T23:02:48.22994-08:00","updated_at":"2025-12-16T23:07:42.05363-08:00","dependencies":[{"issue_id":"gt-njr","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:02:56.148564-08:00","created_by":"daemon"}]}
{"id":"gt-ouo","title":"gt swarm start: Does not spawn polecat sessions","description":"gt swarm start marks swarm as 'active' but doesn't start any polecat sessions.\n\nRepro:\n1. gt swarm create gastown --epic gt-hw6 --worker Toast --worker Nux\n2. gt swarm start gt-hw6\n3. gt session list - shows no new sessions\n\nExpected: Polecat sessions should start for each worker.\nActual: No sessions started, workers sit idle.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-12-17T22:25:43.430981-08:00","updated_at":"2025-12-17T22:31:58.849531-08:00","closed_at":"2025-12-17T22:31:58.849531-08:00","close_reason":"Fixed: spawn wait time, swarm task discovery accepts 'blocks' deps, swarm start spawns workers"}
{"id":"gt-ov2","title":"Refinery agent: merge queue processing loop","description":"The Refinery agent processes the merge queue, merging polecat work to main.\n\n## Interface\n\n```go\ntype Refinery struct {\n rig *Rig\n queue *MergeQueue\n git *Git\n mail *Mailbox\n config RefineryConfig\n}\n\ntype RefineryConfig struct {\n AutoMerge bool // Auto-merge passing MRs\n RunTests bool // Run tests before merge\n TestCommand string // Command to run tests\n RequireReview bool // Require review before merge (future)\n}\n\nfunc NewRefinery(rig *Rig, ...) *Refinery\n\n// Lifecycle\nfunc (r *Refinery) Start() error\nfunc (r *Refinery) Stop() error\nfunc (r *Refinery) IsRunning() bool\n\n// Processing\nfunc (r *Refinery) ProcessQueue() error\nfunc (r *Refinery) ProcessMR(mr *MergeRequest) error\n```\n\n## Processing Loop\n\n1. Check queue for pending MRs\n2. For each pending MR:\n a. Fetch polecat branch\n b. Attempt merge to refinery/rig (local main)\n c. Run tests if configured\n d. If pass: push to origin, mark merged\n e. If fail: mark rejected, notify polecat\n3. Sleep, repeat\n\n## Merge Strategy\n\n- Fast-forward when possible\n- Merge commit when not\n- On conflict: reject MR, polecat must rebase\n\n## Test Integration\n\nIf tests configured:\n```bash\ncd refinery/rig\ngit merge polecat/branch\n\u003ctest_command\u003e # e.g., go test ./...\n```\nResult determines merge/reject.\n\n## Notifications\n\nOn merge success:\n- Mail to polecat: \"Your work merged\"\n- Update bead if issue tracked\n\nOn merge failure:\n- Mail to polecat: \"Merge failed: \u003creason\u003e\"\n- Include conflict details if applicable\n\n## Dependencies\n\nNeeds: Rig management, Git wrapper, Mail system, Merge queue","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-15T23:22:08.498771-08:00","updated_at":"2025-12-16T14:20:35.032221-08:00","closed_at":"2025-12-16T14:20:35.032221-08:00","close_reason":"Closed","dependencies":[{"issue_id":"gt-ov2","depends_on_id":"gt-u1j.14","type":"blocks","created_at":"2025-12-15T23:22:21.801826-08:00","created_by":"daemon"},{"issue_id":"gt-ov2","depends_on_id":"gt-u1j.6","type":"blocks","created_at":"2025-12-15T23:22:21.89716-08:00","created_by":"daemon"}]}
{"id":"gt-ox9","title":"Test from Mayor","description":"This is a test message via GGT mail","status":"closed","priority":2,"issue_type":"message","assignee":"gastown-Alpha","created_at":"2025-12-16T22:04:31.483843-08:00","updated_at":"2025-12-16T22:06:41.127633-08:00","closed_at":"2025-12-16T22:06:41.127633-08:00","close_reason":"Test issues for MVP validation"}
{"id":"gt-pio","title":"Plugin: merge-oracle (merge queue analysis)","description":"Example plugin that analyzes changesets before Refinery processes them. Builds overlap graph, classifies disjointness (parallel-safe vs needs-sequencing), uses LLM for semantic complexity, identifies high-risk patterns. Based on merge-orchestration proposal. See docs/architecture.md.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-15T22:53:04.027073-08:00","updated_at":"2025-12-15T23:17:06.507108-08:00","dependencies":[{"issue_id":"gt-pio","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.507459-08:00","created_by":"daemon"}]}
@@ -190,8 +175,7 @@
{"id":"gt-ruw","title":"Fix TestHasPolecat test failure in internal/session","description":"TestHasPolecat in internal/session/manager_test.go fails because it expects\nspecific polecats (Toast, Cheedo) to exist in the test environment.\n\nError:\n```\nmanager_test.go:46: expected hasPolecat(Toast) = true\nmanager_test.go:49: expected hasPolecat(Cheedo) = true\n```\n\nFix: Either create test fixtures or mock the filesystem check.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-17T15:02:30.030032-08:00","updated_at":"2025-12-17T15:02:30.030032-08:00"}
{"id":"gt-ry8","title":"HOP: Entity chain tracking for agents","description":"Track work history per-entity (CV chains). See ~/ai/stevey-gastown/hop/decisions/002-entity-chains.md for design. Post-v0.1 work.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-17T01:00:41.347764-08:00","updated_at":"2025-12-17T01:00:41.347764-08:00"}
{"id":"gt-sd6","title":"Enhanced polecat decommission prompting","description":"Add decommission checklist to polecat AGENTS.md.template. Make crystal clear: verify ALL before signaling done.\n\n## Checklist for AGENTS.md.template\n\n```markdown\n## Decommission Checklist\n\n**CRITICAL**: Before signaling done, you MUST complete this checklist.\nThe Witness will verify each item and bounce you back if dirty.\n\n### Pre-Done Verification\n\n```bash\n# 1. Git status - must be clean\ngit status\n# Expected: \"nothing to commit, working tree clean\"\n\n# 2. Stash list - must be empty\ngit stash list\n# Expected: (empty output)\n\n# 3. Beads sync - must be up to date\nbd sync --status\n# Expected: \"Up to date\" or \"Nothing to sync\"\n\n# 4. Branch merged - your work must be on main\ngit log main --oneline -1\ngit log HEAD --oneline -1\n# Expected: Same commit\n```\n\n### If Any Check Fails\n\n- **Uncommitted changes**: Commit them or discard if unnecessary\n- **Stashes**: Pop and commit, or drop if obsolete\n- **Beads out of sync**: Run `bd sync`\n- **Branch not merged**: Complete the merge workflow\n\n### Signaling Done\n\nOnly after ALL checks pass:\n\n```bash\nbd close \u003cissue-id\u003e\nbd sync\ntown mail send \u003crig\u003e/witness -s \"Work Complete\" -m \"Issue \u003cid\u003e done.\"\n```\n```\n\n## Implementation\n\nAdd to AGENTS.md.template in the polecat prompting section.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:57.911311-08:00","updated_at":"2025-12-15T20:47:30.062333-08:00","dependencies":[{"issue_id":"gt-sd6","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:06.008061-08:00","created_by":"daemon"}]}
{"id":"gt-slo","title":"Fix TestHasPolecat test failure","description":"","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-12-17T17:30:19.474356-08:00","updated_at":"2025-12-17T21:12:07.625984-08:00","closed_at":"2025-12-17T21:12:07.625984-08:00","close_reason":"Fixed: Remove() signature (added bool arg), hasPolecat() test (create temp dirs)"}
{"id":"gt-sqi","title":"gt session restart/status: Complete session management","description":"Add missing session subcommands:\n\n- gt session restart \u003crig\u003e \u003cpolecat\u003e - Restart a session (stop + start)\n- gt session status \u003crig\u003e \u003cpolecat\u003e - Show session status details\n\nstatus should show:\n- Running state\n- Uptime\n- Current activity\n- Last output timestamp","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T21:47:34.700494-08:00","updated_at":"2025-12-17T21:47:34.700494-08:00","dependencies":[{"issue_id":"gt-sqi","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:23:43.034222-08:00","created_by":"daemon"}]}
{"id":"gt-slo","title":"Fix TestHasPolecat test failure","description":"","status":"open","priority":0,"issue_type":"bug","created_at":"2025-12-17T17:30:19.474356-08:00","updated_at":"2025-12-17T17:30:19.474356-08:00"}
{"id":"gt-svi","title":"Implement gt mq CLI commands","description":"Add gt mq subcommands as sugar over bd:\n\n- gt mq submit: Create MR for current branch\n- gt mq list: Show open merge requests\n- gt mq next: Show next MR ready to process\n- gt mq process: Engineer processes the queue\n- gt mq reorder \u003cid\u003e --after \u003cx\u003e: Change ordering via deps\n- gt mq status \u003cid\u003e: Show MR details\n\nAll commands should work with the Beads data plane.","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T23:02:16.649648-08:00","updated_at":"2025-12-16T23:02:16.649648-08:00","dependencies":[{"issue_id":"gt-svi","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:02:55.456462-08:00","created_by":"daemon"},{"issue_id":"gt-svi","depends_on_id":"gt-kp2","type":"blocks","created_at":"2025-12-16T23:03:12.689547-08:00","created_by":"daemon"}]}
{"id":"gt-svi.1","title":"gt mq submit: create MR from current branch","description":"Implement 'gt mq submit' command that creates a merge-request bead.\n\nAuto-detection logic:\n1. Branch: current git branch\n2. Issue: parse from branch name (polecat/Nux/gt-xyz → gt-xyz)\n3. Target: main (or integration branch if --epic specified)\n4. Worker: parse from branch name\n5. Rig: current rig\n\nOptions:\n- --branch BRANCH: explicit source branch\n- --issue ISSUE: explicit source issue\n- --epic EPIC: target integration/EPIC instead of main\n- --priority P: override priority (default: inherit from source issue)\n\nCreates merge-request bead and prints MR ID.\n\nReference: docs/merge-queue-design.md#creating-merge-requests","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-17T13:50:21.652412-08:00","updated_at":"2025-12-17T13:50:21.652412-08:00","dependencies":[{"issue_id":"gt-svi.1","depends_on_id":"gt-svi","type":"parent-child","created_at":"2025-12-17T13:50:21.65435-08:00","created_by":"daemon"},{"issue_id":"gt-svi.1","depends_on_id":"gt-h5n.1","type":"blocks","created_at":"2025-12-17T13:53:02.317401-08:00","created_by":"daemon"},{"issue_id":"gt-svi.1","depends_on_id":"gt-h5n.2","type":"blocks","created_at":"2025-12-17T13:53:02.438987-08:00","created_by":"daemon"}]}
{"id":"gt-svi.2","title":"gt mq list: show queue with status/priority/age","description":"Implement 'gt mq list' command to display the merge queue.\n\nOutput format:\nID STATUS PRIORITY BRANCH WORKER AGE\ngt-mr-001 ready P0 polecat/Nux/gt-xyz Nux 5m\ngt-mr-002 in_progress P1 polecat/Toast/gt-abc Toast 12m\ngt-mr-003 blocked P1 polecat/Capable/gt-def Capable 8m\n (waiting on gt-mr-001)\n\nOptions:\n- --ready: show only ready-to-merge (no blockers, not in progress)\n- --status STATUS: filter by status\n- --worker WORKER: filter by worker\n- --epic EPIC: show MRs targeting integration/EPIC\n\nUnder the hood: bd list --type=merge-request with filters.\n\nReference: docs/merge-queue-design.md#gt-mq-list","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-17T13:50:23.295587-08:00","updated_at":"2025-12-17T13:50:23.295587-08:00","dependencies":[{"issue_id":"gt-svi.2","depends_on_id":"gt-svi","type":"parent-child","created_at":"2025-12-17T13:50:23.297307-08:00","created_by":"daemon"},{"issue_id":"gt-svi.2","depends_on_id":"gt-h5n.1","type":"blocks","created_at":"2025-12-17T13:53:02.560128-08:00","created_by":"daemon"}]}
@@ -225,11 +209,9 @@
{"id":"gt-u82","title":"Design: Mayor session cycling and handoff","description":"Design for Mayor session cycling and structured handoff.\n\n## Overview\n\nMayor coordinates across all rigs and runs for extended periods. Needs session cycling pattern with structured handoff notes.\n\n## Key Elements\n\n1. Session cycling recognition (when to cycle)\n2. Handoff note format (structured state capture)\n3. Handoff delivery (mail to self)\n4. Fresh session startup (reading and resuming)\n\n## Subtasks (implementation)\n\n- gt-g2d: Mayor session cycling prompting\n- gt-sye: Mayor startup protocol prompting\n- gt-vci: Mayor handoff mail template\n- gt-1le: town handoff command (optional, P2)\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T20:03:16.125725-08:00","updated_at":"2025-12-15T20:49:26.203276-08:00","closed_at":"2025-12-15T20:16:10.772149-08:00","close_reason":"Design complete in docs/mayor-handoff-design.md. 4 subtasks created for implementation."}
{"id":"gt-v5k","title":"Design: Failure modes and recovery","description":"Document failure modes and recovery strategies for Gas Town operations.\n\n## Critical Failure Modes\n\n### 1. Agent Crash Mid-Operation\n\n**Scenario**: Polecat crashes while committing, Witness crashes while verifying\n\n**Detection**:\n- Session suddenly gone (tmux check fails)\n- State shows 'working' but no session\n- Heartbeat stops (for Witness)\n\n**Recovery**:\n- Doctor detects via ZombieSessionCheck\n- Capture any recoverable state\n- Reset agent state to 'idle'\n- For Witness: auto-restart via supervisor or manual gt witness start\n\n### 2. Git State Corruption\n\n**Scenario**: Merge conflict, failed rebase, detached HEAD\n\n**Detection**:\n- Git commands fail\n- Dirty state that won't commit\n- Branch diverged from origin\n\n**Recovery**:\n- gt doctor reports git health issues\n- Manual intervention recommended\n- Severe cases: remove clone, re-clone\n\n### 3. Beads Sync Conflict\n\n**Scenario**: Two polecats modify same issue\n\n**Detection**:\n- bd sync fails with conflict\n- Beads tombstone mechanism handles most cases\n\n**Recovery**:\n- Beads has last-write-wins semantics\n- bd sync --force in extreme cases\n- Issues may need manual dedup\n\n### 4. Tmux Failure\n\n**Scenario**: Tmux server crashes, socket issues\n\n**Detection**:\n- All sessions inaccessible\n- \"no server running\" errors\n\n**Recovery**:\n- Kill any orphan processes\n- tmux kill-server \u0026\u0026 tmux start-server\n- All agent states reset to idle\n- Re-spawn active work\n\n### 5. Claude API Issues\n\n**Scenario**: Rate limits, outages, context limits\n\n**Detection**:\n- Sessions hang or produce errors\n- Repeated failure patterns\n\n**Recovery**:\n- Exponential backoff (handled by Claude Code)\n- For context limits: session cycling (mail-to-self)\n- For outages: wait and retry\n\n### 6. Disk Full\n\n**Scenario**: Clones, logs, or beads fill disk\n\n**Detection**:\n- Write operations fail\n- git/bd commands error\n\n**Recovery**:\n- Clean up logs: rm ~/.gastown/logs/*\n- Remove old polecat clones\n- gt doctor --fix can clean some cruft\n\n### 7. Network Failure\n\n**Scenario**: Can't reach GitHub, API servers\n\n**Detection**:\n- git fetch/push fails\n- Claude sessions hang\n\n**Recovery**:\n- Work continues locally\n- Queue pushes for later\n- Sync when connectivity restored\n\n## Recovery Principles\n\n1. **Fail safe**: Prefer stopping over corrupting\n2. **State is recoverable**: Git and beads have recovery mechanisms\n3. **Doctor heals**: gt doctor --fix handles common issues\n4. **Emergency stop**: gt stop --all as last resort\n5. **Human escalation**: Some failures need Overseer intervention\n\n## Implementation\n\n- Document each failure mode in architecture.md\n- Ensure doctor checks cover detection\n- Add recovery hints to error messages\n- Log all failures for debugging","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T23:19:07.198289-08:00","updated_at":"2025-12-15T23:19:28.171942-08:00"}
{"id":"gt-vci","title":"Mayor handoff mail template","description":"Add MAYOR_HANDOFF mail template to templates.py.\n\n## Template Function\n\ndef mayor_handoff(\n active_swarms: List[SwarmStatus],\n rig_status: Dict[str, RigStatus],\n pending_escalations: List[Escalation],\n in_flight_decisions: List[Decision],\n recent_actions: List[str],\n delegated_work: List[DelegatedItem],\n user_requests: List[str],\n next_steps: List[str],\n warnings: Optional[str] = None,\n session_duration: Optional[str] = None,\n) -\u003e Message:\n metadata = {\n 'template': 'MAYOR_HANDOFF',\n 'timestamp': datetime.utcnow().isoformat(),\n 'session_duration': session_duration,\n 'active_swarm_count': len(active_swarms),\n 'pending_escalation_count': len(pending_escalations),\n }\n # ... format sections ...\n return Message.create(\n sender='mayor/',\n recipient='mayor/',\n subject='Session Handoff',\n body=body,\n priority='high',\n )\n\n## Metadata Fields\n\n- template: MAYOR_HANDOFF\n- timestamp: ISO format\n- session_duration: Human readable\n- active_swarm_count: Number of active swarms\n- pending_escalation_count: Number of escalations\n\n## Mail Priority\n\nUse priority='high' to ensure handoff is seen on startup.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T20:15:30.26323-08:00","updated_at":"2025-12-15T20:48:59.550689-08:00","dependencies":[{"issue_id":"gt-vci","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.554108-08:00","created_by":"daemon"}]}
{"id":"gt-vjv","title":"Add bulk session stop command (gt session stop --all)","description":"When decommissioning a rig, need to stop multiple sessions one at a time. A --all or --rig flag would allow: gt session stop --rig gastown","status":"closed","priority":3,"issue_type":"feature","created_at":"2025-12-18T11:33:33.394649-08:00","updated_at":"2025-12-18T11:38:51.399298-08:00","closed_at":"2025-12-18T11:38:51.399298-08:00","close_reason":"Wrong model: streaming doesn't need bulk shutdown commands - polecats request their own shutdown"}
{"id":"gt-vjw","title":"Swarm learning: Session cleanup missing from swarm workflow","description":"## Problem\n\nAfter Enders Game swarm completed (18 issues merged), 16 polecat sessions were left running but idle. No automated cleanup occurred.\n\n## What Should Happen\n\n1. Witness detects polecat completed work (idle at prompt)\n2. Witness verifies git state is clean\n3. Witness shuts down session\n4. Witness reports completion to Mayor\n\n## GGT Components\n\n- gt-cxx: Witness context cycling (covers self-cycling)\n- gt-u1j.9: Witness daemon heartbeat loop\n- gt-kmn.6: Witness swarm landing protocol\n\n## Recommendation\n\nAdd to Witness responsibilities:\n- Monitor for 'work complete' signals (DONE keyword, idle detection)\n- Automated session shutdown after verification\n- Swarm completion reporting to Mayor\n\nSee also: architecture.md 'Worker Cleanup (Witness-Owned)' section which describes this but it wasn't implemented in PGT.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T01:27:52.796587-08:00","updated_at":"2025-12-16T01:51:37.409965-08:00","closed_at":"2025-12-16T01:51:37.409965-08:00","close_reason":"Addressed by gt-u1j.9 (daemon heartbeat) which now includes session lifecycle management and worker shutdown. See architecture.md Key Decision #12."}
{"id":"gt-y0t","title":"session stop: --force flag is defined but not used","description":"","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-16T13:55:12.848848-08:00","updated_at":"2025-12-16T13:56:39.09003-08:00","closed_at":"2025-12-16T13:56:39.09003-08:00","close_reason":"Closed"}
{"id":"gt-yls","title":"Document merge queue architecture","description":"Update docs/architecture.md with:\n\n- Merge Queue section explaining Beads-native approach\n- Engineer role (renamed from Refinery)\n- Session restart protocol\n- gt mq command reference\n- Federation considerations for queue\n\nAlso update any references to .gastown/ → config/.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T23:02:41.533065-08:00","updated_at":"2025-12-17T13:43:41.657433-08:00","closed_at":"2025-12-17T13:43:41.657433-08:00","close_reason":"Created docs/merge-queue-design.md","dependencies":[{"issue_id":"gt-yls","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:02:56.043373-08:00","created_by":"daemon"}]}
{"id":"gt-z4g","title":"Plugin: Plan-to-Epic converter","description":"## Purpose\n\nHelp users create beads epics from various planning inputs.\n\n## Inputs\n- Markdown task lists\n- GitHub issues\n- Linear/Jira exports\n- Free-form descriptions\n- Existing beads epics\n\n## Output\n- Beads epic with properly structured children\n- Dependencies set for wave ordering\n- Priorities assigned\n- Ready for `gt spawn --epic \u003cid\u003e`\n\n## Implementation Options\n\n### Option A: CLI Tool\n```bash\ngt plan import --from github --repo owner/repo --label batch-candidate\ngt plan import --from markdown tasks.md\ngt plan structure \u003cepic-id\u003e # analyze and add dependencies\n```\n\n### Option B: Plugin Agent\nA plugin at `\u003crig\u003e/plugins/plan-oracle/` that:\n- Receives planning requests via mail\n- Analyzes scope and requirements\n- Creates structured beads epic\n- Sets dependencies based on analysis\n\n### Option C: Interactive Mode\n```bash\ngt plan create\n# Walks through questions, creates epic interactively\n```\n\n## Axiom\n\nAs stated: 'The Planning phase should end in the creation of a workable Beads plan.'\n\nThis plugin bridges the gap between human planning and machine-executable work.\n\n## Priority\n\nP2 - Nice to have for MVP. Manual epic creation works for now.\n\n## Note\n\nNo \"swarm IDs\" - output is just a beads epic with children. Workers process it independently.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T02:10:20.663549-08:00","updated_at":"2025-12-16T17:26:41.087304-08:00"}
{"id":"gt-zko","title":"gt rig info: Show detailed rig information","description":"Add 'gt rig info \u003crig\u003e' command to show detailed rig status.\n\nShould show:\n- Rig path and git URL\n- Active polecats with status\n- Refinery status\n- Witness status\n- Recent activity\n- Beads summary (open issues count)","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-17T21:47:17.879255-08:00","updated_at":"2025-12-17T22:29:46.970197-08:00","closed_at":"2025-12-17T22:29:46.970197-08:00","close_reason":"Implemented gt rig info command with detailed rig status display","dependencies":[{"issue_id":"gt-zko","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:22:47.502099-08:00","created_by":"daemon"}]}
{"id":"gt-zly","title":"Swarm learning: Beads database locality gap","description":"## PGT Bug (GGT Design Already Correct)\n\nMayor created issues in `~/ai/mayor/rigs/beads/.beads/` but polecats use `~/ai/beads/.beads/`. Different databases = polecats can't see Mayor's beads.\n\n**GGT Fix**: architecture.md already specifies:\n- All agents use BEADS_DIR pointing to rig-level `.beads/`\n- Lines 116-143: Beads Configuration for Multi-Agent\n- Lines 573-586: Rig-Level Beads via BEADS_DIR\n\nThis is a PGT implementation gap, not a design issue. GGT spawn must set BEADS_DIR correctly.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T01:21:45.37072-08:00","updated_at":"2025-12-16T01:28:40.74469-08:00","closed_at":"2025-12-16T01:28:40.74469-08:00","close_reason":"PGT implementation gap documented. GGT design already correct - architecture.md specifies BEADS_DIR for all agents pointing to rig-level .beads/"}
{"id":"gt-zx3","title":"Per-rig beads repo configuration","description":"Add per-rig beads configuration to rig config schema.\n\n## Config Schema\n\nIn each rig's config.json:\n\n```json\n{\n \"version\": 1,\n \"name\": \"wyvern\",\n \"git_url\": \"https://github.com/steveyegge/wyvern\",\n \"beads\": {\n \"repo\": \"local\", // \"local\" | \"\u003cpath\u003e\" | \"\u003cgit-url\u003e\"\n \"root\": null, // Override bd --root (optional)\n \"prefix\": \"wyv\" // Issue prefix for this rig\n }\n}\n```\n\n## Repo Options\n\n| Value | Meaning | Use Case |\n|-------|---------|----------|\n| `\"local\"` | Use project's `.beads/` | Own projects, full commit access |\n| `\"\u003cpath\u003e\"` | Use beads at path | OSS contributions |\n| `\"\u003cgit-url\u003e\"` | Clone and use repo | Team shared beads |\n\n## Environment Injection\n\nWhen spawning polecats, Gas Town sets:\n```bash\nexport BEADS_ROOT=\"\u003cresolved-path\u003e\"\n```\n\n## Resolution Logic\n\n```go\nfunc ResolveBeadsRoot(rigConfig *RigConfig, rigPath string) (string, error) {\n beads := rigConfig.Beads\n switch {\n case beads.Root != \"\":\n return beads.Root, nil\n case beads.Repo == \"local\" || beads.Repo == \"\":\n return filepath.Join(rigPath, \".beads\"), nil\n case strings.HasPrefix(beads.Repo, \"/\"):\n return beads.Repo, nil\n case strings.Contains(beads.Repo, \"://\"):\n return cloneAndResolve(beads.Repo)\n default:\n return filepath.Join(rigPath, beads.Repo), nil\n }\n}\n```\n\n## Backwards Compatibility\n\nIf `beads` section missing, assume `\"repo\": \"local\"`.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:16.660049-08:00","updated_at":"2025-12-15T20:48:02.122203-08:00","dependencies":[{"issue_id":"gt-zx3","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.726502-08:00","created_by":"daemon"}]}

98
docs/architecture.md
View File

@@ -738,55 +738,85 @@ gt-auth-epic # Epic: "Fix authentication bugs"
Workers process issues independently. Work flows through the merge queue. No "swarm ID" needed - the epic provides grouping, labels provide ad-hoc queries, dependencies provide sequencing.
### 12. Agent Session Lifecycle (Daemon Protection)
### 12. Agent Session Lifecycle (One Daemon)
**Decision**: A background daemon manages agent session lifecycles, including cycling sessions when agents request handoff.
**Decision**: ONE daemon (Go process) for all Gas Town manages agent lifecycles. Agents use a unified `gt handoff` command to request lifecycle actions.
**Architecture**:
```
Gas Town Daemon (gt daemon)
├── Pokes Mayor periodically
├── Pokes all Witnesses periodically
├── Processes lifecycle requests from daemon/ inbox
└── Restarts sessions when cycle requested
Lifecycle Hierarchy:
Daemon → manages Mayor, all Witnesses
Witness → manages Polecats, Refinery (per rig)
```
**Rationale**:
- Agents can't restart themselves after exiting
- Handoff mail is useless without someone to start the new session
- Daemon provides reliable session management outside agent context
- Enables autonomous long-running operation (hours/days)
- ONE daemon is simpler than per-rig daemons
- Daemon is dumb scheduler; intelligence is in agents
- Unified protocol means all agents work the same way
**Session cycling protocol**:
1. Agent detects context exhaustion or requests cycle
2. Agent sends handoff mail to own inbox
3. Agent sets `requesting_cycle: true` in state.json
4. Agent exits (or sends explicit signal to daemon)
5. Daemon detects exit + cycle request flag
6. Daemon starts new session
7. New session reads handoff mail, resumes work
**Unified lifecycle command** (`gt handoff`):
```bash
gt handoff # Context-aware default
gt handoff --shutdown # Terminate, don't restart (polecats)
gt handoff --cycle # Restart with handoff (long-running agents)
gt handoff --restart # Fresh restart, no handoff
```
**Daemon responsibilities**:
- Monitor agent session health (heartbeat)
- Detect session exit
- Check cycle request flag in state.json
- Start replacement session if cycle requested
- Clear cycle flag after successful restart
- Report failures to Mayor (escalation)
| Agent | Default | Sends request to |
|-------|---------|------------------|
| Polecat | --shutdown | rig/witness |
| Refinery | --cycle | rig/witness |
| Witness | --cycle | daemon/ |
| Mayor | --cycle | daemon/ |
**Applies to**: Witness, Refinery (both long-running agents that may exhaust context)
**Lifecycle request protocol**:
1. Agent runs `gt handoff` (verifies git clean, sends handoff mail)
2. Agent sends lifecycle request to its manager
3. Agent sets `requesting_<action>: true` in state.json
4. Agent waits (does NOT self-exit)
5. Manager receives request, verifies safe
6. Manager kills session
7. Manager starts new session (for cycle/restart)
8. New session reads handoff mail, resumes work
**Daemon heartbeat loop**:
- Poke Mayor: "HEARTBEAT: check your rigs"
- Poke each Witness: "HEARTBEAT: check your workers"
- Agents ignore poke if already working
- Process any lifecycle requests in daemon/ inbox
- Restart dead sessions if cycle was requested
```mermaid
sequenceDiagram
participant A1 as Agent Session 1
participant S as State.json
participant D as Daemon
participant M as Lifecycle Manager
participant A2 as Agent Session 2
participant MB as Mailbox
A1->>MB: Send handoff mail
A1->>S: Set requesting_cycle: true
A1->>A1: Exit cleanly
D->>D: Detect session exit
D->>S: Check requesting_cycle
S->>D: true
D->>D: Start new session
D->>S: Clear requesting_cycle
A2->>MB: Read handoff mail
A2->>A2: Resume from handoff
A1->>A1: gt handoff --cycle
A1->>A1: Send handoff mail to self
A1->>M: Lifecycle request: cycle
A1->>A1: Set requesting_cycle, wait
M->>M: Verify safe to act
M->>A1: Kill session
M->>A2: Start new session
A2->>A2: Read handoff mail
A2->>A2: Resume work
```
**Polecat shutdown** (--shutdown default):
After Witness kills session:
- Remove worktree: `git worktree remove polecats/<name>`
- Delete branch: `git branch -d polecat/<name>`
- Polecat ceases to exist (ephemeral)
### 13. Resource-Constrained Worker Pool
**Decision**: Each rig has a configurable `max_workers` limit for concurrent polecats.