Add patrol instance tracking to witness manager:
- Add PatrolInstanceID to WitnessHandoffState for tracking
- Add ArmID to WorkerState for per-polecat arm tracking
- Add ensurePatrolInstance() method that:
- Checks if patrol instance already exists (from previous session)
- Creates new patrol instance if needed
- Persists instance ID in handoff state
This enables the molecule-based tracking ledger pattern where the
Go-based witness creates beads issues to track its patrol state.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Polecats share the same beads database at the rig level. The refinery
and witness manage syncing beads. Running bd sync on polecat startup
causes contention when multiple polecats spawn simultaneously and
creates potential race conditions.
This change removes bd sync --from-main from:
- prompts/roles/polecat.md On Startup section
- internal/beads/molecules_session.go orient step
- internal/beads/molecules_work.go orient step
- docs/polecat-wisp-architecture.md load context section
Troubleshooting sections that recommend bd sync --from-main for
recovery scenarios are preserved.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add BranchPushedToRemote() to git package that properly handles
polecat branches without upstream tracking. Update verifyPolecatState
in witness to check that branches are pushed before allowing cleanup.
This prevents the scenario where polecats close issues without pushing
their work, causing all commits to be lost when the worktree is deleted.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Architecture changes:
- Refinery created as worktree of mayor clone (shares .git)
- Polecat branches stay local (never pushed to origin)
- MRs stored as wisps in .beads-wisp/mq/ (ephemeral)
- Only main gets pushed to origin after merge
New mrqueue package for wisp-based MR storage.
Updated spawn, done, mq_submit, refinery, molecule templates.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename "Dependency Trap" to "Gotchas when Filing Beads" in all 6 role templates
- Fix "git clone" to "git worktree" in polecat template
- Simplify completion section to just "gt done"
- Condense Work Protocol section (let molecule define steps)
- Simplify "Before Signaling Done" to trust gt done internals
- Clarify work status: use "gt mol status" as primary command
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Revert IsWisp: false → true for patrol spawning. bd mol run now
auto-discovers the main database for templates when --db contains
.beads-wisp, so patrol molecules can spawn correctly into ephemeral storage.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When slinging work to patrol agents (witness, refinery, deacon), queue via
mail instead of replacing the hook. This preserves patrol continuity.
New behavior:
- Default: Check if patrol is running, start default patrol if not, send
work via mail. Patrol processes queued work during its cycle.
- --urgent: Marks mail as urgent (🚨 URGENT prefix)
- --replace: Legacy behavior, explicitly terminates patrol (break-glass)
New helper functions:
- isPatrolRole(kind): Returns true for witness/refinery/deacon
- getDefaultPatrolMolecule(role): Returns patrol template name
- resolvePatrolMoleculeID(path, title): Looks up beads issue ID by title
- isPatrolRunning(path, addr): Checks if patrol molecule is attached
Note: Patrol spawning currently uses main DB (not wisp storage) because
templates must be looked up from the main database. Wisp support for
patrol instances is a future enhancement.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When slinging with --force to an agent with occupied hook, the displaced
molecule is now returned to the ready pool rather than silently orphaned.
Changes:
- Modified checkHookCollision to take force param and return displaced ID
- Added releaseDisplacedWork helper to unpin and release displaced molecules
- Updated all 5 sling handlers (polecat, crew, witness, refinery, mayor)
Behavior:
- Without --force: still errors "hook already occupied by X"
- With --force: prints warning, releases old work, proceeds with new sling
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The witness session was starting in the rig root (e.g., /gt/gastown)
instead of the witness directory (e.g., /gt/gastown/witness/rig).
This caused gt prime to detect the Mayor role instead of Witness role.
Now ensureWitnessSession uses the same pattern as ensureRefinerySession:
1. Try <rig>/witness/rig/ first (for rigs with worktree setup)
2. Fall back to <rig>/witness/ (for simpler setups)
3. Last resort: use rig root (shouldn't happen normally)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Temporal language like "Phase 1 blocks Phase 2" triggers incorrect
dependency direction. Added a concise warning to all 6 role templates
(crew, polecat, mayor, witness, refinery, deacon) reminding agents:
- Think "X needs Y", not "X comes before Y"
- Verify with `bd blocked`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Crew: Updated to use 'gt handoff' instead of manual mail
- Crew: Added note about relaxed cycling (no fixed heuristic)
- Polecat: Added note that 'gt handoff' redirects to 'gt done'
Patrol workers (Deacon, Witness, Refinery) already had their
N-rounds heuristics documented in previous commits.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Most MRs are button-pushes (clean rebase + push). Only complex rebases
(conflicts, test failures) consume significant context.
- 20 simple MRs before handoff
- Immediate handoff after any complex rebase
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Each patrol role now has role-specific context management:
- Deacon: 20 loops or immediate on extraordinary action
- Witness: 15 polecats processed (spawns + nudges + decommissions)
- Refinery: 7 merge requests processed
Templates include state.json format and handoff instructions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
resolveRoleToSession now accepts paths like <rig>/crew/<name>,
<rig>/witness, and <rig>/refinery in addition to role shortcuts.
For example: 'gt handoff gastown/crew/max' now works.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update gt handoff to detect polecats (via GT_POLECAT env var) and
call gt done instead of respawning - polecats have Witness-managed lifecycle
- Update CLAUDE.md Session End Checklist to use gt handoff
- This is the canonical way to end any agent session - it handles mail,
respawn, and context restoration via SessionStart hook
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
buildRestartCommand now detects the town root and includes a cd to the
appropriate directory before launching claude. This ensures each role
starts in its correct working directory:
- gt-mayor → town root (~/gt)
- gt-deacon → ~/gt/deacon
- crew sessions → ~/gt/<rig>/crew/<name>
- witness sessions → ~/gt/<rig>/witness
- refinery sessions → ~/gt/<rig>/refinery
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The daemon was creating the deacon session in ~/gt (town root) which loaded
the Mayor CLAUDE.md instead of the Deacon CLAUDE.md. Also, tmux SetEnvironment
does not export variables to spawned processes.
Changes:
- Create deacon session in ~/gt/deacon (correct CLAUDE.md)
- Export GT_ROLE=deacon in launch command (process inherits env)
- Apply to both initial launch and restart paths
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added comment explaining that the pinned field gets overwritten by
subsequent bd commands due to a bug in the beads auto-import logic.
The handoff bead attachment mechanism works correctly and is the
primary work assignment mechanism.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New command that sends a message to all active workers (polecats + crew).
Supports filtering by rig with --rig flag, and can include infrastructure
agents (mayor, deacon, witness, refinery) with --all flag.
Usage:
gt broadcast "Check your mail"
gt broadcast --rig gastown "New work available"
gt broadcast --all "System maintenance in 5 minutes"
gt broadcast --dry-run "Test"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add doctor check to detect handoff beads for agents that no longer exist.
This happens when a polecat worktree is deleted but its handoff bead remains.
- Check: orphaned-attachments
- Warning if: Handoff bead exists for agent that no longer has worktree
- Supports polecats (rig/name), crew (rig/crew/name), mayor, witness, refinery
- Suggests re-sling to active agent or close the molecule
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add HookInfo struct and hook discovery to show which agents have work
attached to their hooks. Updates both JSON and text output:
- New HookInfo type with agent, role, has_work, molecule, and title fields
- RigStatus now includes Hooks slice
- StatusSum includes ActiveHooks count
- discoverRigHooks() scans polecats, crew, witness, and refinery
- getAgentHook() retrieves hook status from handoff beads
- Text output shows active hooks per rig with agent and molecule info
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Allows agents to self-pin work from mail messages. The command:
1. Reads a mail message by ID
2. Extracts molecule ID from the body (attached_molecule:, molecule_id:, etc.)
3. Attaches the molecule to the agent's pinned bead (hook)
4. Marks the mail as read
Includes unit tests for the molecule ID extraction logic.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated all role prompt templates to document the startup hook protocol:
- polecat.md.tmpl: Added gt mol status check, self-pin from mail protocol
- witness.md.tmpl: Added gt mol status check, self-pin from mail protocol
- refinery.md.tmpl: Added gt mol status check, self-pin from mail protocol
- crew.md.tmpl: Added new Startup Protocol section with hook-first flow
- deacon.md.tmpl: Added gt mol status check, self-pin from mail protocol
- mayor.md.tmpl: Expanded startup protocol with hook-first flow
Each template now includes:
1. Check hook first (gt mol status)
2. If empty, check mail for attached work
3. Self-pin protocol (gt mol attach-from-mail) if needed
4. Role-specific fallback behavior
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a command to list all hooks in the workspace. Scans for .claude/settings.json
files and displays hooks by type (SessionStart, PreCompact, UserPromptSubmit, etc).
Features:
- Scans town root, rigs, polecats, crew, witness, and refinery directories
- Shows hook type, location, status, and agent that owns it
- Supports --verbose flag to show hook commands
- Supports --json flag for machine-readable output
(gt-h6eq.5)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add doctor check to ensure each agent has at most one handoff bead.
Detects when multiple pinned beads exist with the same "{role} Handoff"
title, which can cause confusion about which handoff is authoritative.
- Check: hook-singleton
- Error if: Multiple pinned beads with same '{role} Handoff' title
- Fix: Automatically closes duplicates (keeps oldest) when run with --fix
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements a new doctor check that detects attached molecules that
haven't been updated in too long, which may indicate stuck work.
The check:
- Finds all pinned beads with attachments across rigs
- Checks the attached molecule's UpdatedAt timestamp
- Reports molecules in_progress with no activity for >1 hour
- Provides actionable fix hints for stuck polecats
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add doctor check to verify that attached molecules exist and are not closed.
Detects when a hook's attached_molecule field points to a non-existent or
closed issue, which can leave agents with stale work assignments.
- Check: hook-attachment-valid
- Error if: Hook's attached_molecule field points to non-existent or closed issue
- Fix: Automatically detaches invalid molecules when run with --fix
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds Pin() and Unpin() methods to the beads wrapper that call bd pin/unpin.
Updates pinToHook() to call b.Pin() after AttachMolecule() to set the
pinned boolean field and assignee on the work issue. This should enable
bd hook to show pinned work.
NOTE: There's a known issue where bd pin via subprocess doesn't actually
set the pinned field even though it reports success. The handoff bead
attachment remains the primary mechanism until this is resolved.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add DefaultCrewName constant ('max') to config package
- Add default_crew_name field to MayorConfig for town-level override
- Update gt rig add to resolve crew name: --crew flag > town config > default
- Update help text to reflect new default
Priority: --crew flag > MayorConfig.DefaultCrewName > config.DefaultCrewName ('max')
Adds support for slinging work to four new target types:
- crew (e.g., beads/crew/dave): Human-managed persistent workers
- No worktree recreation
- No auto-session start
- Sends work assignment mail
- witness (e.g., gastown/witness): Per-rig lifecycle manager
- Suggests --wisp for ephemeral work
- Pins to witness hook
- refinery (e.g., gastown/refinery): Per-rig merge queue
- Accepts protos, issues, and epics
- Pins to refinery hook
- mayor (e.g., mayor/): Town-level coordinator
- Uses town-level beads
- Human-managed like crew
- Sends work assignment mail
Updated help text with new target formats and examples.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The help text documented this subcommand but it wasn't implemented.
Adds status command showing currently resolved account with source
(GT_ACCOUNT env var or default).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds support for managing multiple Claude Code accounts in Gas Town:
- accounts.json config parsing in mayor/ directory
- gt account list/add/default commands
- GT_ACCOUNT env var support with priority resolution
- --account flag on gt spawn and gt crew at commands
- CLAUDE_CONFIG_DIR injection into tmux sessions
Priority order: GT_ACCOUNT env var > --account flag > default from config
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Shell loops bypassed the proper lifecycle architecture. Now:
- Witness: Launches Claude directly, daemon/deacon health-scan handles restart
- Deacon: Launches Claude directly, daemon detects exit and restarts
- Daemon: ensureDeaconRunning() now checks if Claude is running (pane cmd)
and restarts it if session exists but Claude has exited
- gt deacon restart: Now does stop+start instead of Ctrl-C
This enforces proper lifecycle flow through LIFECYCLE mail and daemon
heartbeat rather than bypassing it with shell loops.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Agents naturally expect `gt handoff -s "Subject" -m "Message"` to work
like `gt mail send`. Now it does:
- Added --subject/-s and --message/-m flags to gt handoff
- Added --self flag to gt mail send for sending to self
- Handoff auto-sends mail to self before respawning pane
This makes agent-initiated handoff more ergonomic - they can include
context in a single command instead of two separate steps.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add auto-spawn logic to outputDeaconPatrolContext()
- Deacon now auto-spawns mol-deacon-patrol if no active patrol
- All three patrol roles now have consistent auto-bond behavior:
Deacon, Witness, Refinery
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add outputWitnessPatrolContext() function in prime.go
- Witness now auto-spawns mol-witness-patrol if no active patrol
- Fixed catalog ID parsing (strip trailing colon) for both witness and refinery
- Created mol-witness-patrol template with 10 steps (gt-qflq)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
