Explain why agent bead creation failures are hard errors while role bead
creation failures are soft errors (log and continue).
Agent beads are identity beads that form the CV/reputation ledger foundation.
Role beads are documentation templates not required for agent operation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The isFirstRig parameter was no longer used - it was being assigned
to a blank identifier. Since initAgentBeads is an internal function
with only 2 callers in this repo, remove the parameter entirely.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add Dog role bead creation to the roleDefs slice, ensuring Dog
agents have their role definition created during gt install.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Agent directories (witness/, refinery/, mayor/) contained state.json files
with last_active timestamps that were never updated, making them stale and
misleading. This change removes:
- initAgentStates function that created vestigial state.json files
- AgentState type and related Load/Save functions from config package
- MayorStateValidCheck from doctor checks
- requesting_* lifecycle verification (dead code - flags were never set)
- FileStateJSON constant and MayorStatePath function
Kept intact:
- daemon/state.json (actively used for daemon runtime state)
- crew/<name>/state.json (operational CrewWorker metadata)
- Agent state tracking via beads (the ZFC-compliant approach)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update all callers of deprecated MayorBeadID()/DeaconBeadID() to use
MayorBeadIDTown()/DeaconBeadIDTown() which return hq- prefix IDs for
town-level beads storage.
Changes:
- internal/daemon/lifecycle.go: identityToAgentBeadID and checkStaleAgents
- internal/cmd/prime.go: getAgentBeadID
- internal/cmd/molecule_status.go: buildAgentBeadID
- internal/cmd/prime_test.go: update expected values to hq-*
- Comments updated to reflect hq- prefix for town-level agents
The deprecated functions remain for backward compatibility and are used
by the migration tool (migrate_agents.go).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 5 of epic gt-4r1ph (align agent/role beads with two-level architecture):
- Create docs/architecture.md with agent bead storage table documenting
the correct two-level architecture:
- Town beads (~/gt/.beads/): hq-mayor, hq-deacon, hq-*-role
- Rig beads (<rig>/.beads/): <prefix>-<rig>-witness, <prefix>-<rig>-refinery
- Update internal/rig/manager.go initAgentBeads() comments with MIGRATION
NOTEs explaining current state vs target architecture (gt-4r1ph)
- Close PR #50 with explanation that the fix direction was wrong
CLAUDE.md templates already correctly document hq-* for town beads and
project prefix for rig beads.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 1: Create agent_ids.go with town-level bead ID helpers
- MayorBeadIDTown(), DeaconBeadIDTown(), DogBeadIDTown()
- RoleBeadIDTown() and role-specific helpers (hq-*-role)
- Add deprecation notices to old gt-* prefix functions
Phase 2: Create town-level agent beads during gt install
- initTownAgentBeads() creates hq-mayor, hq-deacon agent beads
- Creates role beads: hq-mayor-role, hq-deacon-role, etc.
- Update rig/manager.go to use rig beads for Witness/Refinery
This aligns with the two-level beads architecture:
- Town beads (~/gt/.beads/): hq-* prefix for Mayor, Deacon, roles
- Rig beads (<rig>/.beads/): <prefix>-* for Witness, Refinery, Polecats
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implement two-level beads architecture for agent lookups:
- Town-level agents (Mayor, Deacon) now use hq- prefix and are
looked up in town beads (~/.beads/)
- Rig-level agents continue using rig prefix (e.g., gt-) and are
looked up in rig beads
Changes:
- Add MayorBeadIDTown(), DeaconBeadIDTown(), DogBeadIDTown() helpers
- Add GetTownBeadsPath() for town beads path resolution
- Update gt status to pre-fetch town-level agent beads
- Update agentIDToBeadID() to use town-level IDs
- Update agent_beads_check.go to check/fix in correct tier
- Update agentAddressToIDs() in deacon.go
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add new helper functions for town-level agent bead IDs:
- MayorBeadIDTown() → "hq-mayor"
- DeaconBeadIDTown() → "hq-deacon"
- DogBeadIDTown(name) → "hq-dog-<name>"
- RoleBeadIDTown(role) → "hq-<role>-role"
These use the hq- prefix for town-level beads storage, distinct from
the gt- prefix used for rig-level beads.
Mark MayorBeadID() and DeaconBeadID() as deprecated in favor of the
new *Town() variants.
(gt-y24km)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements Phase 4 of the two-level beads architecture migration:
- Add hq- prefix helper functions for town-level agent beads
- Add CreateWithID method for deterministic bead creation
- Create gt migrate-agents command with dry-run/execute modes
- Migrate gt-mayor/gt-deacon to hq-mayor/hq-deacon in town beads
- Migrate role beads (gt-*-role) to town beads (hq-*-role)
- Add migration labels to old beads for tracking
- Idempotent: skips already-migrated beads
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When `gt install` creates a new HQ, formulas were not being provisioned
to `.beads/formulas/`. This embeds the formula library into the gt binary
and copies them during installation.
- Add go:generate directive to copy formulas from .beads/formulas/
- Add internal/formula/embed.go with ProvisionFormulas() function
- Call ProvisionFormulas() from runInstall() after beads init
- Add generate target to Makefile (build depends on it)
- Add TestInstallFormulasProvisioned integration test
- Log warning if formula stat fails with unexpected error
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The rigs/ directory was created by gt install but never used by
gt rig add, which puts rigs at the town root. Rather than restructure
the entire codebase to use rigs/, we remove the unused directory.
Flat structure is fine - similar to Android top-level layout with
100+ subprojects. Rigs at root works well and avoids a breaking change.
Closes#74🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes nested workspace detection and symlink path issues in workspace.Find()
- Remove filepath.EvalSymlinks() for consistency with os.Getwd()
- Add isInWorktreePath() to detect polecats/crew directories
- Continue walking up to outermost workspace when in worktree paths
- Add integration tests for symlink and nested workspace scenarios
- gt install now creates ~/gt/.claude/commands/ with all commands
- Removed per-workspace provisioning from crew/polecat managers
- Updated bd doctor to check town-level instead of per-workspace
- All agents inherit via Claude directory traversal
This eliminates duplicate /handoff skills in the picker.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update the archive command to accept variadic arguments like bd close,
allowing users to archive multiple messages in a single command.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Updates HandlePolecatDone to auto-nuke polecats immediately after MR submission
when cleanup_status=clean. This separates polecat lifecycle from MR lifecycle:
- Polecat lifecycle: spawning → working → mr_submitted → nuked
- MR lifecycle: created → queued → processed → merged (handled by Refinery)
Key changes:
- Try auto-nuke for ALL POLECAT_DONE messages regardless of MR status
- If cleanup_status=clean (branch pushed), nuke immediately
- If dirty state, create cleanup wisp for manual intervention
- Cleanup wisps are now exception handling, not the normal flow
Conflict resolution is handled by the Refinery, which creates NEW tasks
for NEW polecats when merge conflicts are detected.
(gt-si8rq.9)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Reverts the session naming changes from PR #70. Multi-town support
on a single machine is not a real use case - rigs provide project
isolation, and true isolation should use containers/VMs.
Changes:
- MayorSessionName() and DeaconSessionName() no longer take townName parameter
- ParseSessionName() handles simple gt-mayor and gt-deacon formats
- Removed Town field from AgentIdentity and AgentSession structs
- Updated all callers and tests
Generated with Claude Code
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add progress feedback during slow clone operations (30+ seconds)
- Fix README Quick Start to match actual workflow (--git flag, crew add)
- Update install output to use 'gt mayor attach' consistently
- Clarify "Next steps" wording in rig add output
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Refinery monitoring to daemon heartbeat (ensureRefineriesRunning)
- Add circuit breaker: agents marked dead by checkStaleAgents() are
now force-killed and restarted, even if Claude process is alive
- Fixes zombie Claude sessions that werent updating their bead state
The circuit breaker flow:
1. Agent gets stuck (stops updating bead state)
2. After 15 minutes: checkStaleAgents() marks bead as dead
3. On next heartbeat: ensure*Running() sees state=dead
4. Force-kill session and restart fresh
Generated with Claude Code
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updates mol-witness-patrol.formula.toml to document the new ephemeral model:
- Added Ephemeral Polecat Model section explaining lifecycle separation
- Updated POLECAT_DONE handling to describe immediate auto-nuke
- Updated process-cleanups to focus on exception handling (dirty polecats)
- Updated survey-workers Step 4a for ephemeral done polecat handling
- Updated patrol-cleanup for ephemeral model expectations
Key principle: Polecat lifecycle is separate from MR lifecycle.
Polecats are recyclable immediately after MR submission.
(gt-si8rq.9)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Runs integration tests on PRs that touch install, rig, config, or routing code.
Uses -tags=integration build tag with 5-minute timeout and Go module caching.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updates HandlePolecatDone to auto-nuke polecats immediately after MR submission
when cleanup_status=clean. This separates polecat lifecycle from MR lifecycle:
- Polecat lifecycle: spawning → working → mr_submitted → nuked
- MR lifecycle: created → queued → processed → merged (handled by Refinery)
Key changes:
- Try auto-nuke for ALL POLECAT_DONE messages regardless of MR status
- If cleanup_status=clean (branch pushed), nuke immediately
- If dirty state, create cleanup wisp for manual intervention
- Cleanup wisps are now exception handling, not the normal flow
Conflict resolution is handled by the Refinery, which creates NEW tasks
for NEW polecats when merge conflicts are detected.
(gt-si8rq.9)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
CI: Add integration test job that runs go test -tags=integration for
install, rig, and beads routing tests.
Crew lifecycle: Pass startup beacon as Claude's initial prompt instead
of nudging after startup. Removes timing-dependent sleep/nudge sequence.
Also removes redundant SetEnvironment calls (env vars already exported
in BuildCrewStartupCommand).
🤖 Generated with Claude Code
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Session names `gt-mayor` and `gt-deacon` were hardcoded, causing tmux
session name collisions when running multiple towns simultaneously.
Changed to `gt-{town}-mayor` and `gt-{town}-deacon` format (e.g.,
`gt-ai-mayor`) to allow concurrent multi-town operation.
Key changes:
- session.MayorSessionName() and DeaconSessionName() now take townName param
- Added workspace.GetTownName() helper to load town name from config
- Updated all callers in cmd/, daemon/, doctor/, mail/, rig/, templates/
- Updated tests with new session name format
- Bead IDs remain unchanged (already scoped by .beads/ directory)
Fixes#60🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The handleSuccessFromQueue function was missing critical steps that
exist in the legacy handleSuccess function:
1. Fetch and update the MR bead with merge_commit SHA and close_reason
2. Close the MR bead with CloseWithReason("merged", mr.ID)
Without these steps, the MR bead stayed "open" in beads even after the
queue file was deleted. This caused Mayor (which queries beads for open
merge-requests) to think there were pending MRs while Refinery (which
uses the queue) reported completion.
Fixes#46
When sending messages to Claude sessions via tmux, the Enter key send
could fail silently. This caused polecats to receive their initial
prompt but never submit it - the message appeared in Claude's input
area but Enter was never pressed.
Add retry logic (up to 3 attempts with 200ms delays) for the Enter
send step in both NudgeSession() and NudgePane(). This ensures message
submission is more reliable even if tmux has transient issues.
Fixes#41
Adds RemoteDefaultBranch() to git.go that detects the repo's actual
default branch by checking origin/HEAD, then falling back to checking
for origin/master or origin/main.
Updates done.go to use this detection instead of hardcoded "main":
- Line 168: CommitsAhead now uses detected default branch
- Line 173: Error message uses detected branch name
- Line 187: Target branch defaults to detected branch
Fixes repos using 'master' as default branch (pre-2020 repos).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
PropulsionNudgeForRole now accepts a workDir parameter and reads
session ID from .runtime/session_id to append [session:xxx] to the
nudge message. This enables Claude Code's /resume picker to discover
Gas Town sessions.
(gt-u49zh)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add LastActivity calculation for convoy dashboard (hq-x2xy)
Adds internal/activity package with color-coded activity tracking:
- Green: <2 minutes (active)
- Yellow: 2-5 minutes (stale)
- Red: >5 minutes (stuck)
Features:
- Calculate() function returns Info with formatted age and color class
- Helper methods: IsActive(), IsStale(), IsStuck()
- Handles edge cases: zero time, future time (clock skew)
Tests: 8 test functions with 25 sub-tests covering all thresholds.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add convoy dashboard HTML template with Last Activity (hq-fq1g)
Adds internal/web package with convoy dashboard template:
- convoy.html with Last Activity column and color coding
- Green (<2min), Yellow (2-5min), Red (>5min) activity indicators
- htmx auto-refresh every 30 seconds
- Progress bars for convoy completion
- Status indicators for open/closed convoys
- Empty state when no convoys
Also includes internal/activity package (dependency from hq-x2xy):
- Calculate() returns Info with formatted age and color class
- Helper methods: IsActive(), IsStale(), IsStuck()
Tests: 6 template tests + 8 activity tests, all passing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add convoy list handler with activity data (hq-3edt)
Adds HTTP handler that wires convoy dashboard template to real data:
- ConvoyHandler: HTTP handler for GET / rendering convoy dashboard
- LiveConvoyFetcher: Fetches convoys from beads with activity data
- ConvoyFetcher interface: Enables mocking for tests
Features:
- Fetches open convoys from town beads
- Calculates progress (completed/total) from tracked issues
- Gets Last Activity from worker agent beads
- Color codes activity: Green (<2min), Yellow (2-5min), Red (>5min)
Includes dependencies (not yet merged):
- internal/activity: Activity calculation (hq-x2xy)
- internal/web/templates: HTML template (hq-fq1g)
Tests: 5 handler tests + 6 template tests + 8 activity tests = 19 total
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add 'gt dashboard' CLI command (hq-s1bg)
Add dashboard command to start the convoy tracking web server.
Usage: gt dashboard [--port=8080] [--open]
Features:
- --port: Configurable HTTP port (default 8080)
- --open: Auto-open browser on start
- Cross-platform browser launch (darwin/linux/windows)
- Graceful workspace detection
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
tmux has-session -t does prefix matching by default, so "gt-deacon-boot"
would match when checking for "gt-deacon". This caused gt start to think
the Deacon was running when only a stale gt-deacon-boot session existed.
Using "=" prefix forces exact matching in tmux.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Enables gt prime to receive session metadata from LLM runtime hooks.
When called with --hook, reads JSON from stdin containing session_id
and persists it to .runtime/session_id for use by PropulsionNudge.
- Add --hook flag for hook mode
- Parse Claude Code session JSON from stdin
- Support GT_SESSION_ID environment variable fallback
- Persist session ID to .runtime/session_id
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Use git --reference-if-able when a local repo is provided so rigs and crew share objects without changing remotes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When the daemon checks if Deacon/Witness is running, it first checks the
agent bead state. If this check fails (bead not found, JSON parse error,
or stale state), it would previously attempt to restart the session -
even if the tmux session was perfectly healthy.
This caused "session already exists" errors when:
1. Agent bead state couldn't be read (prefix mismatch, missing bead)
2. But the tmux session was actually running with Claude active
Fix: Add a tmux session health check as fallback before attempting restart.
If the session exists AND Claude is running in it, skip the restart and
log that we're preserving the healthy session despite stale bead state.
This maintains ZFC compliance (still trusts agent bead as primary source)
while adding a defensive check to prevent unnecessary session kills.
Fixes#63🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The Quick Start section incorrectly showed `cd ~/gt && gt prime` as the
way to enter the Mayor's office. However, `gt prime` only outputs role
context to stdout (for use in Claude Code prompt hooks) - it doesn't
start or attach to any session.
Changed to `gt mayor attach` which properly attaches to the Mayor tmux
session (and auto-starts it if not running).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New molecule formula mol-polecat-conflict-resolve defines the workflow for
polecats handling merge conflict resolution tasks:
1. Load task and extract metadata from conflict-resolution bead
2. Acquire merge slot (prevents racing via "Monkey Knife Fight" prevention)
3. Checkout the conflicting branch
4. Rebase onto main and resolve conflicts
5. Run tests to verify resolution
6. Push resolved changes directly to main (bypasses queue)
7. Close original MR bead and source issue
8. Release merge slot for next waiter
9. Clean up and close the conflict-resolution task
This completes the polecat side of the ephemeral merge workflow architecture.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Validates:
- bd show routes to correct rig based on issue ID prefix
- bd show hq-* routes to town beads
- Redirect chains (.beads/redirect) resolve correctly
- bd list works from polecat/crew directories with redirects
- Prefix conflicts are detected in routes.jsonl
- Routes loading, appending, and removal work correctly
- GetPrefixForRig returns correct prefix for rig name
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The tmux session name "gt-deacon-boot" was causing HasSession("gt-deacon")
to return true due to tmux prefix matching behavior. This made the daemon
think the Deacon was running when only Boot was active, and caused commands
targeting "gt-deacon" to be sent to Boot session instead.
The fix renames Boot session from "gt-deacon-boot" to "gt-boot", which
has no prefix overlap with "gt-deacon".
Fixes: gt-sgzsb
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
