When adding a crew member with 'gt crew add' or spawning a polecat,
provision the .claude/commands/ directory with standard slash commands
like /handoff. This ensures all agents have Gas Town utilities even if
the source repo does not have them tracked.
Changes:
- Add embedded commands templates (internal/templates/commands/)
- Add ProvisionCommands() to templates package
- Call ProvisionCommands from crew and polecat managers
- Add gt doctor commands-provisioned check with --fix support
Route to the correct beads location based on whether the source repo
has .beads/ tracked in git:
- If source has .beads/ tracked: route to mayor/rig/.beads
- Otherwise: route to rig root .beads/ (created by initBeads)
Updates both route registration in rig.go and polecat manager's
NewManager/setupSharedBeads to use consistent conditional logic.
When slinging work to a rig (auto-spawning a polecat), the hook_bead
is now set atomically during agent bead creation rather than in a
separate updateAgentHookBead call after spawn.
This fixes cross-beads routing issues when town beads (hq-*) are slung
to rig polecats (gt-* agent beads). By setting hook_bead at creation
time within the polecat manager context, the correct beads routing is
used.
Changes:
- Add AddOptions struct with HookBead field to polecat.Manager
- Add AddWithOptions() and RecreateWithOptions() functions
- Pass HookBead through SlingSpawnOptions in cmd/polecat_spawn.go
- Pass beadID as HookBead in cmd/sling.go for rig target spawns
Note: updateAgentHookBead() is kept for non-spawn targets (existing
agents) and formula-on-bead mode (updates hook to wisp root after
creation).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When spawning polecats in rigs with custom prefixes (e.g., beads uses bd-
instead of gt-), agent beads were being created with hardcoded gt- prefix,
causing warnings like issue ID gt-beads-polecat-obsidian does not match
configured prefix bd.
Changes:
- polecat/manager.go: agentBeadID() now looks up the rigs configured prefix
from routes.jsonl via beads.GetPrefixForRig()
- prime.go: getAgentBeadID() now uses prefix lookup for rig-level agents
(witness, refinery, polecat, crew)
Town-level agents (mayor, deacon) continue to use gt- prefix as expected.
Same fix as crew: polecat manager was overwriting project CLAUDE.md with
Gas Town polecat context. Gas Town context is now injected ephemerally via
SessionStart hook (gt prime) only.
Removed installCLAUDETemplate function and associated tests.
Implements canonical naming convention for agent bead IDs:
- Town-level: gt-mayor, gt-deacon (unchanged)
- Rig-level: gt-<rig>-witness, gt-<rig>-refinery (was gt-witness-<rig>)
- Named: gt-<rig>-crew-<name>, gt-<rig>-polecat-<name> (was gt-crew-<rig>-<name>)
Changes:
- Added AgentBeadID helper functions to internal/beads/beads.go
- Updated all ID generation call sites to use helpers
- Fixed session parsing in theme.go, statusline.go, agents.go
- Updated doctor check and fix to use canonical format
- Updated tests for new format
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
crew_add.go: Use gt-crew-role instead of per-instance role bead
polecat/manager.go: Add RoleBead field pointing to gt-polecat-role
Per agent-as-bead design, role beads are shared class definitions.
Each agent bead references its role via the role_bead field/slot.
Fixes gt-ne9he
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Use tree characters (├── └── │) for hierarchical display
- Group agents by role type (Witness, Refinery, Crew, Polecats)
- Add role icons (🎩 Mayor, 🔔 Deacon, 👁 Witness, 🏭 Refinery, 👷 Crew, 😺 Polecats)
- Show pinned work inline with truncation
- Fix unused import in polecat/manager.go
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Instead of Go code checking git state to decide if polecat removal is safe,
the polecat now self-reports its cleanup_status via its agent bead.
Changes:
- Add CleanupStatus field to AgentFields struct
- Update FormatAgentDescription and ParseAgentFields for cleanup_status
- Add UpdateAgentCleanupStatus function to beads package
- Update gt done to compute and report git cleanup status
- Update RemoveWithOptions to read cleanup_status from agent bead first,
falling back to git check for backward compatibility
Valid cleanup_status values:
- clean: no uncommitted work
- has_uncommitted: has uncommitted changes
- has_stash: has stashed changes
- has_unpushed: has unpushed commits
- unknown: git check failed
This follows ZFC (Zero Figuring in Code) principles - the polecat is the
authority on its own state, not Go code inferring it from external signals.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Prevents data loss from concurrent/interrupted state file writes by using
atomic write pattern (write to .tmp, then rename).
Changes:
- Add internal/util package with AtomicWriteJSON/AtomicWriteFile helpers
- Update witness/manager.go saveState to use atomic writes
- Update refinery/manager.go saveState to use atomic writes
- Update crew/manager.go saveState to use atomic writes
- Update daemon/types.go SaveState to use atomic writes
- Update polecat/namepool.go Save to use atomic writes
- Add comprehensive tests for atomic write utilities
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds tests to prevent regression of polecat identity bugs:
1. TestInstallCLAUDETemplate: Verifies template is loaded from
mayor/rig/templates/ (not rig root) with correct variable substitution.
2. TestInstallCLAUDETemplateNotAtRigRoot: Verifies templates at the
old buggy location (rig root) are NOT used.
3. TestPolecatCommandFormat: Documents and verifies that polecat sessions
export GT_ROLE=polecat, GT_RIG, GT_POLECAT, BD_ACTOR inline before
starting Claude (because tmux SetEnvironment only affects new panes).
These tests ensure polecats correctly identify as polecats, not mayor.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Two bugs caused polecats to think they were mayor:
1. Template lookup path (gt-si6am):
- Was looking at rig.Path/templates/ which doesn't exist
- Now correctly looks at mayor/rig/templates/
- Polecats get the polecat CLAUDE.md instead of inheriting mayor's
2. Env var export (gt-y41ep):
- tmux SetEnvironment only affects new panes, not current shell
- Now exports GT_ROLE, GT_RIG, GT_POLECAT, BD_ACTOR inline before Claude
- Matches how crew sessions work
Combined effect (gt-9ar8x): Polecats now correctly identify as polecats
and work from their own directory instead of mayor/rig.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add installCLAUDETemplate() to Manager that:
- Reads templates/polecat-CLAUDE.md from rig root
- Substitutes {{rig}} and {{name}} with actual values
- Writes to polecats/<name>/CLAUDE.md
Called from both Add() and Recreate() after worktree creation.
Non-fatal if template is missing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create ephemeral agent beads for ZFC-compliant polecat state tracking.
- Add AgentFields struct and helpers to beads package
- CreateAgentBead: Creates agent bead with role_type/rig/agent_state
- UpdateAgentState: Updates agent_state and hook_bead fields
- DeleteAgentBead: Hard-deletes ephemeral agent bead
- GetAgentBead: Retrieves and parses agent bead
- Integrate lifecycle in polecat manager:
- Add(): Creates gt-polecat-<rig>-<name> bead with state=spawning
- Recreate(): Deletes old bead, creates fresh with state=spawning
- RemoveWithOptions(): Deletes agent bead on nuke
This enables Witness to read polecat state from beads instead of
tmux scraping. State updates (spawning→working→done) are done by
polecats via bd agent state (separate beads CLI enhancement).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changed polecat branch model to use unique timestamped branches
(polecat/<name>-<timestamp>) instead of reusing persistent branches.
This prevents JSONL drift issues where stale polecat branches don't
have recently created beads.
Changes:
- Add(): create unique branch, simplified (no reuse logic)
- Recreate(): create fresh branch, old ones left for GC
- loadFromBeads(): read actual branch from git worktree
- CleanupStaleBranches(): remove orphaned polecat branches
- ListBranches(pattern): new git helper for branch enumeration
- gt polecat gc: new command to clean up stale branches
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Theme is configuration (from settings/config.json), not runtime state.
Loading theme from state file was causing rig config to be ignored,
which is why the beads rig kept using mad-max names instead of minerals.
All 156 instances of _ = error suppression in non-test code now have
explanatory comments documenting why the error is intentionally ignored.
Categories of intentional suppressions:
- non-fatal: session works without these - tmux environment setup
- non-fatal: theming failure does not affect operation - visual styling
- best-effort cleanup - defer cleanup on failure paths
- best-effort notification - mail/notifications that should not block
- best-effort interrupt - graceful shutdown attempts
- crypto/rand.Read only fails on broken system - random ID generation
- output errors non-actionable - fmt.Fprint to io.Writer
This addresses the silent failure and debugging concerns raised in the
issue by making the intentionality explicit in the code.
Generated with Claude Code https://claude.com/claude-code
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When recreating a polecat worktree, the branch deletion might fail
silently, leaving a stale branch with old commits. The worktree would
then be created from this stale branch, missing recent main changes.
Fix:
- Add ResetBranch() method to git package for force-updating branches
- Fetch from origin before recreation to ensure fresh commits
- If branch deletion fails, force-reset the branch to origin/main
- This ensures polecats always start with the latest code
Discovered during gt-8tmz swarm when nux polecat was missing the
internal/formula/ directory that was added after its branch diverged.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add .repo.git as shared bare repo for worktrees
- Update polecat manager to use bare repo when available
- Add git.NewGitWithDir() and CloneBare() for bare repo support
- Update gt rig init to create bare repo architecture for new rigs
- Refinery and polecats now share branch visibility via shared .git
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Moved pending.go from deacon/ to polecat/ package
- Changed storage location from deacon/pending.json to spawn/pending.json
- Added 'gt spawn pending' subcommand for listing/clearing pending spawns
- Deprecated 'gt deacon pending' (still works, shows deprecation notice)
This decouples pending spawn observation from the Deacon role - anyone
can now observe pending polecats (Mayor, humans, debugging, etc.).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
ZFC cleanup: Go should be message transport, not decision-maker.
Before: loadFromBeads used switch on issue.Status to derive polecat
state (open/in_progress -> working, closed -> done).
After: Simple rule - has issue assigned = working, no issue = idle.
We do not interpret what issue.Status means; that is for Claude in
the Deacon molecule.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When polecat branches have .beads/ tracked from previous bd sync operations,
those files would contaminate the new worktree. Now setupSharedBeads():
1. Removes any existing .beads/ contents before creating redirect
2. Points redirect directly to mayor/rig/.beads (matches crew workers)
Also adds sling-design.md documenting the gt sling command design.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- .beads-ephemeral/ -> .beads-wisp/
- Rename doctor checks: EphemeralCheck -> WispCheck
- Update all docs to use 'transient' for polecats, 'wisp' for molecules
- Preserve 'ephemeral' only as descriptive adjective for wisps
- Steam engine metaphor: wisps are steam vapors that dissipate
Part of Christmas launch wisp terminology unification.
- Move router and polecatAddress definitions before if block to avoid
shadowing (defining same vars inside and after the block)
- Handle branch deletion failure in Recreate() by checking if branch
still exists and using WorktreeAddExisting like Add() does
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes gt-9nf: gt spawn should create fresh polecat worktree, never reuse
Changes:
- Add Recreate() method to polecat manager that removes and recreates worktrees
- Modify spawn.go to always recreate existing polecats with fresh worktrees
- Preserves safety checks: blocks if polecat is working or has uncommitted work
- Use --force to bypass uncommitted work checks
This ensures polecats always start with the latest code from the base branch,
avoiding stale code, stale beads, and git history pollution.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The Load() function wasn't reading the saved theme because the condition
p.Theme == "" was never true after NewNamePool() set it to "mad-max".
Now the loaded theme properly overrides constructor defaults.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When creating a polecat worktree, create a .beads/redirect file pointing
to the rig-level shared beads database. This eliminates git sync overhead
between polecats - they all connect to the same daemon and database.
Architecture:
gastown/
.beads/ <- Shared database (created if missing)
polecats/
nux/
.beads/
redirect <- Contains "../../.beads"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add comprehensive uncommitted work checks before any polecat cleanup:
- Check for uncommitted changes (modified/untracked files)
- Check for stashes
- Check for unpushed commits
Affected commands:
- gt polecat remove: now refuses if uncommitted work exists
- gt rig shutdown: checks all polecats before shutdown
- Witness cleanup: refuses to clean polecats with uncommitted work
- gt spawn: warns if spawning to polecat with uncommitted work
Safety model:
- --force: bypasses uncommitted changes check only
- --nuclear: bypasses ALL safety checks (will lose work)
New git helpers:
- StashCount(): count stashes in repo
- UnpushedCommits(): count commits not pushed to upstream
- CheckUncommittedWork(): comprehensive work status check
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The spawn command and polecat manager were incorrectly looking for beads
in <rig>/mayor/rig/.beads instead of <rig>/.beads. This caused:
- `gt spawn --issue ga-xxp` to fail with "no issue found" even when
`bd show ga-xxp` worked from the rig directory
- Polecats couldn't find rig-level issues (with ga- prefix) because
mayor/rig has a different beads database (with gt- prefix)
This fix:
- spawn.go: Use r.Path instead of filepath.Join(r.Path, "mayor", "rig")
- polecat/manager.go: Use r.Path for beads.New() initialization
- session/manager.go: Use r.Path/.beads for BEADS_DIR environment
Closes beads-2nh
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implement reusable name pool for polecat workers:
- Pool of 50 names (polecat-01 through polecat-50)
- Prefers lower-numbered slots for allocation
- Overflow uses rigname-N format when pool exhausted
- Pool names are reusable, overflow names are not
- State persisted to .gastown/namepool.json
Changes:
- Add NamePool type with Allocate/Release/Reconcile
- Integrate with polecat.Manager (auto-loads/saves)
- Update gt spawn to use AllocateName() from pool
- Remove legacy polecatNames list and generatePolecatName()
- Add comprehensive tests for name pooling
Benefits:
- Tmux sessions survive polecat restarts (same name)
- Users can stay attached and see work continue
- Bounded resource usage for common case
- Scales beyond 50 with overflow naming
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace polecat state.json with beads assignee field for state management:
- Remove state.json read/write from polecat.Manager
- Add loadFromBeads() to derive state from issue.assignee field
- Update AssignIssue() to set issue.assignee in beads
- Update ClearIssue() to clear assignee from beads
- Update SetState() to work with beads or gracefully degrade
- Add ListByAssignee and GetAssignedIssue to beads package
- Update spawn to create beads issues for free-form tasks
- Update tests for new beads-based architecture
State derivation:
- Polecat exists: worktree directory exists
- Polecat assigned: issue.assignee = 'rig/polecatName'
- Polecat working: issue.status = open/in_progress
- Polecat done: issue.status = closed or no assignee
Fixes: gt-qp98
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fix ~50 errcheck warnings across the codebase:
- Add explicit `_ =` for intentionally ignored error returns (cleanup,
best-effort operations, etc.)
- Use `defer func() { _ = ... }()` pattern for defer statements
- Handle tmux SetEnvironment, KillSession, SendKeysRaw returns
- Handle mail router.Send returns
- Handle os.RemoveAll, os.Rename in cleanup paths
- Handle rand.Read returns for ID generation
- Handle fmt.Fprint* returns when writing to io.Writer
- Fix for-select with single case to use for-range
- Handle cobra MarkFlagRequired returns
All tests pass. Code compiles without errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When adding a polecat, check if the branch already exists (e.g., from a
previous polecat that was removed but whose branch wasn't cleaned up).
If so, reuse the existing branch with WorktreeAddExisting instead of
failing with 'a branch named polecat/X already exists'.
Fixes: gt-bmjw
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This implements the ephemeral polecat model where polecats are spawned
fresh for each task and deleted upon completion.
Key changes:
**Spawn (internal/cmd/spawn.go):**
- Always create fresh worktree from main branch
- Run bd init in new worktree to initialize beads
- Remove --create flag (now implicit)
- Replace stale polecats with fresh worktrees
**Handoff (internal/cmd/handoff.go):**
- Add rig/polecat detection from environment and tmux session
- Send shutdown requests to correct witness (rig/witness)
- Include polecat name in lifecycle request body
**Witness (internal/witness/manager.go):**
- Add mail checking in monitoring loop
- Process LIFECYCLE shutdown requests
- Implement full cleanup sequence:
- Kill tmux session
- Remove git worktree
- Delete polecat branch
**Polecat state machine (internal/polecat/types.go):**
- Primary states: working, done, stuck
- Deprecate idle/active (kept for backward compatibility)
- New polecats start in working state
- ClearIssue transitions to done (not idle)
**Polecat commands (internal/cmd/polecat.go):**
- Update list to show "Active Polecats"
- Normalize legacy states for display
- Add deprecation warnings to wake/sleep commands
Closes gt-7ik
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds two new commands to transition polecats back to idle state:
- gt polecat done (alias: finish): Transitions from working/done/stuck
states to idle, clearing the assigned issue. For normal workflow when
work is complete but session was not properly cleaned up.
- gt polecat reset: Force resets any state to idle. For recovery when
polecat is stuck in an unexpected state.
Both commands check that the session is stopped before modifying state.
Fixes gt-s3m0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Mayor has <rig>/mayor/rig/ clone (decentralized, discoverable)
- Rig .beads/ symlinks to mayor/rig/.beads (Mayor is beads authority)
- Polecats are worktrees from Mayor's clone (not Refinery)
- Updated architecture.md with new structure
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- gt crew at: auto-detect crew from cwd, run gt prime after launch
- Polecats now use git worktrees from refinery (faster than clones)
- Updated architecture.md for two-tier beads mail model
- Town beads (gm-*) for Mayor mail/coordination
- Rig .beads/ symlinks to refinery/rig/.beads
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
