Implements Option A from the issue: multiple refinery workers with locking.
Changes to mrqueue:
- Add ClaimedBy/ClaimedAt fields to MR struct
- Add Claim(id, worker) method with atomic file operations
- Add Release(id) method to unclaim on failure
- Add ListUnclaimed() to find available work
- Add ListClaimedBy(worker) for worker-specific queries
- Claims expire after 10 minutes for crash recovery
New CLI commands:
- gt refinery claim <mr-id> - Claim MR for processing
- gt refinery release <mr-id> - Release claim back to queue
- gt refinery unclaimed - List available MRs
Formula updates:
- queue-scan now uses gt refinery unclaimed
- process-branch claims MR before processing
- handle-failures releases claim on test failure
- Claims prevent double-processing by parallel workers
Worker ID comes from GT_REFINERY_WORKER env var (default: refinery-1).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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>
Reordered mol-sync-workspace.formula.toml so cleanup-worktrees runs after
handle-dirty-state instead of after run-tests. This is more logical:
worktree cleanup is housekeeping that should happen during workspace prep,
not after verification steps.
New execution order:
1. assess-state
2. handle-dirty-state
3. cleanup-worktrees ← moved here
4. sync-git
5. sync-beads → run-doctor → verify-build → run-tests
6. generate-report → signal-ready
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Witnesses were sending HEALTH_OK mail to mayor on every deacon health
check (~30s), flooding the inbox. Updated witness templates to:
- Explicitly state NOT to mail on HEALTH_CHECK nudges
- Explain that Deacon tracks health via session status
- Add gotcha note in the main template
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds a new subcommand `gt hook show <agent>` that displays what work
is on any agent's hook in a compact one-line format:
gastown/polecats/nux: gt-abc123 'Fix the widget bug' [hooked]
Use cases:
- Mayor checking what polecats are working on
- Witness checking polecat status
- Debugging coordination issues
- Quick status overview
Also supports --json flag for machine-readable output.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously, the Deacon patrol formula sent HEALTH_CHECK nudges to
Witnesses and Refineries on every patrol cycle (~1-2 minutes). This
disturbed idle agents constantly and wasted their context.
Now health check nudges are only sent when concerning signals are
detected:
- Agent not running or no heartbeat
- Status check hangs or fails
- Queue stuck or merge failures
The status commands (gt witness status, gt refinery status) provide
sufficient liveness info for healthy agents. Reserve nudges for
actual problems.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When BranchPushedToRemote fails to use the tracking ref (e.g., due to
missing remote.origin.fetch config in worktrees), fall back to using
git ls-remote to get the remote SHA directly and compare.
This makes gt done more resilient in worktrees where the fetch refspec
may be incomplete or missing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements the release subcommand to allow workers to release claimed
messages back to their queues. The command:
- Verifies the caller owns the claimed message
- Validates the message has a queue label
- Returns the message to open status with queue assignee
Includes TestMailReleaseValidation unit tests.
(gt-guyt5)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
DefaultWitnessHandler.HandleMerged was only logging a message but not
actually cleaning up the polecat worktree. This left worktrees behind
after merges, even though sessions were killed.
Fixed by calling witness.AutoNukeIfClean which:
- Verifies cleanup_status before nuking (prevents work loss)
- Calls NukePolecat to kill session, remove worktree, and cleanup
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Pass CLAUDE_SESSION_ID environment variable to bd close for work attribution
tracking, enabling queries like "what work did this session do?" for entity
CV building (per decision 009-session-events-architecture.md).
Changes:
- beads.Close() and CloseWithReason() now pass --session to bd close
- Updated all direct exec.Command("bd", "close"...) calls:
- internal/mail/mailbox.go - closeInDir()
- internal/cmd/swarm.go - swarm land and cancel
- internal/cmd/hook.go - auto-replace completed beads
- internal/cmd/synthesis.go - convoy close
- internal/cmd/crew_lifecycle.go - workspace removal
- internal/cmd/polecat.go - polecat nuke
The bd CLI already supports --session (or CLAUDE_SESSION_ID env var) so
this change ensures consistent session tracking across all gt close paths.
Fixes: gt-nvz8b
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add gt deacon zombie-scan command that provides defense-in-depth
against Witness cleanup failures. The command:
- Scans all rigs for polecats that are idle, have no session running,
no hooked work, and are stale (>10 min inactive)
- Reports found zombies with details
- Optionally nukes them and notifies the mayor
Flags:
--dry-run Preview only
--threshold Custom staleness threshold (default 10m)
--nuke=false Report only, do not clean up
Also adds zombie-scan step to mol-deacon-patrol formula.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Expanded the sync-git step in mol-sync-workspace.formula.toml with detailed
guidance for Refinery agents on how to handle merge conflicts inline:
- Trivial conflicts: resolve immediately (imports, whitespace, etc.)
- Semantic conflicts: assess carefully before merging
- Complex conflicts: abort and notify polecat to rebase
- Judgment call principle: when in doubt, abort rather than risk broken main
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extends gt nudge to support channel-based targeting:
- gt nudge channel:<name> <message> nudges all channel members
- Channels defined in ~/gt/config/messaging.json under "nudge_channels"
- Supports patterns: gastown/polecats/*, */witness, gastown/crew/*
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds `gt mail claim <queue-name>` command that:
- Lists unclaimed messages in a work queue
- Picks the oldest unclaimed message
- Verifies caller eligibility against workers patterns
- Claims the message by updating assignee and status
- Prints claimed message details
Includes tests for worker pattern matching.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The hook discovery code was reading hook_bead from the agent bead's
description field (parsed via ParseAgentFieldsFromDescription), but
the slot update code writes to the hook_bead database column via
'bd slot set'. This mismatch caused polecats to see stale hook values
from the description instead of the current value from the database.
Fixed in:
- molecule_status.go: Use agentBead.HookBead instead of parsing description
- status.go: Use issue.HookBead directly
- lifecycle.go: Update all GUPP and orphan detection to read from
database columns instead of parsing description
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add CommitsAhead check after BranchPushedToRemote to prevent stale
branches (pushed but 0 commits ahead of main) from being submitted
to the merge queue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
(gt-fpv2p)
Implements the synthesis step that combines leg outputs into a final
deliverable for convoy workflows:
- `gt synthesis start <convoy-id>` - Start synthesis after verifying
all legs are complete, collecting outputs, and slinging to polecat
- `gt synthesis status <convoy-id>` - Show synthesis readiness and
leg completion status
- `gt synthesis close <convoy-id>` - Close convoy after synthesis
Key features:
- Collects leg outputs from formula-defined paths (e.g., findings.md)
- Creates synthesis bead with combined context from all leg outputs
- Integrates with formula.toml synthesis configuration
- Provides TriggerSynthesisIfReady() for automated synthesis trigger
- Adds SynthesisFields struct for tracking synthesis state in beads
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add full convoy formula execution to gt formula run command:
- Parse formula file to extract legs, synthesis, and prompts
- Create convoy bead in town beads to track execution
- Create leg beads for each parallel leg with tracking relations
- Create synthesis bead with dependencies on all legs
- Sling each leg to a polecat with leg-specific context
- Support dry-run mode to preview execution
The implementation supports convoy-type formulas with parallel legs
and a synthesis step. Non-convoy formulas show manual execution steps.
(gt-574qn)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
CRITICAL: Prevents work loss from unpushed commits.
The bug: gt mq submit created MR beads without verifying the branch was pushed to remote. This allowed polecats to create MR beads for unpushed work, which the Refinery would skip and the Witness would nuke, losing work.
The fix: Add same push verification that gt done uses. Now both code paths require git push before MR submission.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a proper `gt formula` command with subcommands:
- gt formula list - List available formulas
- gt formula show <name> - Display formula details
- gt formula run <name> - Execute a formula (scaffold for gt-574qn)
- gt formula create <name> - Create new formula templates
The create command generates valid TOML templates for:
- task: Single-step task formula
- workflow: Multi-step workflow with dependencies
- patrol: Repeating patrol cycle for wisps
Replaces the simple formulas.go that only delegated to `bd formula list`.
The `formulas` alias is preserved for backwards compatibility.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implement internal/formula package for parsing and validating formula.toml files:
- types.go: Formula, Step, Leg, Aspect, Template, Input, Var structs
- parser.go: TOML parsing using BurntSushi/toml, validation, dependency resolution
- Supports convoy, workflow, expansion, and aspect formula types
- Infers type from content when not explicitly set
- Validates required fields, unique IDs, and dependency references
- Detects circular dependencies in workflow steps
- Provides TopologicalSort and ReadySteps for execution planning
(gt-5chbk)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Introduces the leg prompt template system for convoy-style formulas:
- Base prompt template with context injection (PR, files, formula name)
- 7 specialized review legs (correctness, performance, security, elegance,
resilience, style, smells)
- Per-leg focus and description for polecat instructions
- Output format specification with structured findings template
- Synthesis step configuration for combining leg outputs
This formula demonstrates the template system pattern for parallel
polecat execution in convoy workflows.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add .github/ISSUE_TEMPLATE/ with bug_report.md and feature_request.md
templates. Add .github/PULL_REQUEST_TEMPLATE.md for PR submissions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Full setup guide covering:
- Prerequisites for macOS and Linux
- Step-by-step installation
- Minimal vs Full Stack mode setup
- Verification with gt doctor
- Troubleshooting common issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add beads (bd) to Prerequisites with install link
- Move Prerequisites section before Quick Start for visibility
- Add version requirements: Go 1.23+, Git 2.25+, tmux 3.0+
Fixes gt-1ntmd
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Delete 5 legacy .formula.yaml files (have .toml replacements)
- Remove unused FileConfigYAML constant
- Add TODO for beads config.yaml → config.json migration (bd-10wg)
- Update docs to use JSON examples instead of yaml code blocks
- Change plugin frontmatter from YAML to TOML in docs
- Add .toml to code file detection in branch_check.go
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add .github/workflows/ci.yml with:
- .beads/ change detection to protect issue database
- Go build and test with race detection
- golangci-lint for code quality
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added centralized emoji constants in internal/constants/constants.go
for easy customization. Updated all files that hardcoded role emojis
to use the new constants.
Changes:
- Witness emoji: 👁 (eye) → 🦉 (owl) - less creepy, matches visual identity
- Deacon emoji: 🦉 (owl) → 🐺 (wolf) - matches hierarchy prompt (wolf in engine room)
- Added RoleEmoji() helper function for string-based lookups
- Maintained backwards compatibility with legacy role names
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- convoy.go: Escape single quotes in SQL to prevent injection
- engineer.go: Add comment clarifying test command trust model
(config.json is trusted infra, not PR-controlled)
- agents.go, prime.go, mayor.md.tmpl: Fix 'gt polecats' -> 'gt polecat list'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The unsling command had two bugs:
1. It used the local beads directory instead of the target agent's rig
2. It looked for status=hooked beads instead of the agent bead's hook_bead field
Changes:
- unsling.go: Rewrote to use agent bead's hook_bead field (matches how sling works)
- unsling.go: Now uses target agent's rig beads path, not local
- status.go: Prefer SQLite columns (issue.HookBead, issue.AgentState) over
parsing description text, with fallback for legacy beads
- beads.go: Added AgentState field to Issue struct for SQLite column access
This fixes the issue where `gt unsling gastown/crew/joe` would say "no work hooked"
even when gt status showed joe had a hook.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Witnesses should send HEALTH_OK to deacon/, not mayor/deacon.
Added explicit Health Check Protocol section to the witness template
explaining the correct address and why.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When gt sling is used without an existing convoy context, automatically
create a convoy for dashboard visibility. This ensures all work appears
in 'gt convoy list', even "swarm of one" assignments.
Changes:
- Add --no-convoy flag to skip auto-convoy creation
- Check if issue is already tracked by a convoy before creating new one
- Create convoy with title "Work: <issue-title>" and add tracks relation
- Display tracking info in sling output
- Update command help with auto-convoy documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
All role status lines now check for hooked work first:
- If hook has work: shows hook emoji with bead ID and title
- If hook empty: falls back to mail preview
Also fixed workspace detection for status-line command by using
the pane's working directory instead of relying on cwd.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add convoy ID validation to prevent SQL injection
- Add 5-second timeouts to all subprocess calls
- Batch issue lookups to eliminate N+1 query pattern
- Fix truncate() to handle multi-byte UTF-8 characters
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update all documentation to present convoy as the primary unit of work tracking:
- README.md: Show convoy create before sling in Quick Start and Workflows
- reference.md: Reorder to show Convoy Management before Work Assignment
- understanding-gas-town.md: Add convoy to dispatch workflow example
- mayor.md.tmpl: Add convoy commands to Work Management section
- crew.md.tmpl: Include convoy in dispatch workflow table
Convoy is now the standard workflow - all slings should be part of a convoy.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
In worktrees, git push -u origin <branch> may not create the local
refs/remotes/origin/<branch> tracking ref due to missing refspecs.
BranchPushedToRemote now explicitly creates the remote tracking ref
from FETCH_HEAD after fetching if it does not exist locally.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Use cwd-based detection instead of env-aware detection for gt hook status
display. This ensures we show the hook for the agent whose directory you're
in, not the agent from GT_ROLE env var.
Before: cd ~/gt/beads/crew/dave && gt hook → showed gastown/crew/joe (wrong)
After: cd ~/gt/beads/crew/dave && gt hook → shows beads/crew/dave (correct)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When slinging with . as target, resolve it to the current agent identity
instead of using literal dot. This matches git convention where dot means
current directory/context.
Fix applied to both runSling and runSlingFormula code paths.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add numbered prefixes to `gt convoy list` output (1. 2. 3. ...)
- Support numeric shortcuts in `gt convoy status <n>`
- Add `-i/--interactive` flag for expandable tree view TUI
- New internal/tui/convoy package with bubbletea-based UI
- j/k navigation, enter to expand/collapse
- 1-9 to jump directly to convoy
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Documents that session events stay in events.jsonl (orchestration),
with work attribution via session_id on beads mutations.
Filed:
- gt-nvz8b: gt done captures session_id
- bd-tksk: Beads session_id support (slung to dave)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds a stable actor-PID identifier alongside the Claude session_id.
Useful for correlation across session handoffs.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unused SessionBeacon function from session/names.go
- Add gt seance commands to reference.md Sessions section
- Document StartupNudge format for session discovery
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The SessionStart hook now parses stdin JSON to extract session_id
and passes it to gt prime via CLAUDE_SESSION_ID env var.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements automatic nuke of polecats after completion:
- HandlePolecatDone: Auto-nukes immediately for ESCALATED/DEFERRED exits
(no pending MR) when cleanup_status=clean
- HandleMerged: Auto-nukes after verifying commit is on main and
cleanup_status=clean
- HandleLifecycleShutdown: Auto-nukes immediately since shutdown means
no pending work
Safety checks preserved:
- Verifies cleanup_status from agent bead (clean/has_uncommitted/etc)
- Verifies commit is on main before nuking
- Falls back to cleanup wisp if any check fails
New functions:
- NukePolecat(): Executes gt polecat nuke
- AutoNukeIfClean(): Checks safety and nukes if safe
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Key optimizations:
- Use --no-daemon for bd commands to avoid daemon IPC overhead
- Pre-fetch all agent beads in single query (ListAgentBeads)
- Pre-fetch all hook beads in single query (ShowMultiple)
- Pre-fetch all tmux sessions for O(1) lookup
- Parallel rig processing with goroutines
- Add --fast flag to skip mail lookups
The main bottleneck was bd daemon communication timing out on
stale daemon processes, causing 5+ second delays per rig.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated mol-witness-patrol to properly clean up polecats that exit via
ESCALATED/DEFERRED (no MR). Previously, these polecats would sit idle
indefinitely waiting for a MERGED signal that would never come.
Changes:
- process-cleanups: Check for MR before sending MERGE_READY. If no MR
exists and polecat is clean, nuke immediately.
- survey-workers: Step 3a now handles both idle AND done polecats
without pending MR. Step 4a checks for MR before creating cleanup wisp.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
