Add three new flags to gt prime command:
- --state: Output role state as JSON and exit early (for scripting)
- --dry-run: Skip side effects (persistence, locks, events)
- --explain: Show verbose role detection reasoning
The --state flag is mutually exclusive with all other flags and errors
if combined. The other flags (--dry-run, --explain, --hook) can be
combined freely.
Also fixes missing filepath import in beads.go.
Closes: bd-t8ven
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
detectSessionState() and checkSlungWork() both contained identical
logic for finding hooked/in_progress beads assigned to an agent.
Extracted this into findHookedBead() helper function.
Also includes priming subsystem improvements from mayor:
- Add --dry-run flag for testing without side effects
- Add --state flag to output detected state only
- Add --explain flag to show why sections are included
- Add missing filepath import to beads.go
Fixes: bd-hvwnb
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 1 of dynamic priming subsystem:
1. PRIME.md provisioning for all workers (hq-5z76w, hq-ukjrr Part A)
- Added ProvisionPrimeMD to beads package with Gas Town context template
- Provision at rig level in AddRig() so all workers inherit it
- Added fallback provisioning in crew and polecat managers
- Created PRIME.md for existing rigs
2. Post-handoff detection to prevent handoff loop bug (hq-ukjrr Part B)
- Added FileHandoffMarker constant (.runtime/handoff_to_successor)
- gt handoff writes marker before respawn
- gt prime detects marker and outputs "HANDOFF COMPLETE" warning
- Marker cleared after detection to prevent duplicate warnings
3. Priming health checks for gt doctor (hq-5scnt)
- New priming_check.go validates priming subsystem configuration
- Checks: SessionStart hook, gt prime command, PRIME.md presence
- Warns if CLAUDE.md is too large (should be bootstrap pointer)
- Fixable: provisions missing PRIME.md files
This ensures crew workers get Gas Town context (GUPP, hooks, propulsion)
even if the gt prime hook fails, via bd prime fallback.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds support for alternative AI runtime backends (Codex, OpenCode) alongside
the default Claude backend through a runtime abstraction layer.
- internal/runtime/runtime.go - Runtime-agnostic helper functions
- Extended RuntimeConfig with provider-specific settings
- internal/opencode/ for OpenCode plugin support
- Updated session managers to use runtime abstraction
- Removed unused ensureXxxSession functions
- Fixed daemon.go indentation, updated terminology to runtime
Backward compatible: Claude remains default runtime.
Co-Authored-By: Ben Kraus <ben@cinematicsoftware.com>
Co-Authored-By: Cameron Palmer <cameronmpalmer@users.noreply.github.com>
Deacon is a town-level role, so its beads should be at ctx.TownRoot
(~/gt/.beads/) not ctx.WorkDir (~/gt/deacon/). This fixes the issue
where outputDeaconPatrolContext couldn't find patrol molecules because
it was looking in the wrong location.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Prevents mayor-specific files (CLAUDE.md, hooks) from polluting child
agent workspaces. Child agents inherit the parent's working directory,
so keeping mayor files in a dedicated subdirectory ensures they don't
interfere with agent operations.
Includes:
- MayorDir constant in templates for consistent path handling
- Updated hooks.go, prime.go, role.go to use mayor/ paths
- Documentation updates
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Additional cleanup from the agent_state refactoring:
- Remove dead code: checkStaleAgents(), markAgentDead() in lifecycle.go
- Remove dead code: reportAgentState(), getAgentFields() in prime.go
- Update getAgentBeadState() comment to clarify non-observable states only
- Update mol-witness-patrol.formula.toml to use tmux discovery
- Update mol-polecat-lease.formula.toml to use POLECAT_DONE mail
- Update docs/watchdog-chain.md to reflect new architecture
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The agent_state field was recording observable state like "running",
"dead", "idle" which violated the "Discover, Don't Track" principle.
This caused stale state bugs where agents were marked "dead" in beads
but actually running in tmux.
Changes:
- Remove daemon's checkStaleAgents() which marked agents "dead"
- Simplify ensureXxxRunning() to use tmux.IsClaudeRunning() directly
- Remove reportAgentState() calls from gt prime and gt handoff
- Add SetHookBead/ClearHookBead helpers that don't update agent_state
- Use ClearHookBead in gt done and gt unsling
- Simplify gt status to derive state from tmux, not bead
Non-observable states (stuck, awaiting-gate, muted, paused) are still
set because they represent intentional agent decisions that can't be
discovered from tmux state.
Fixes: gt-zecmc
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: Beads redirect architecture for tracked and local beads
This change implements proper redirect handling so that all rig agents
(Witness, Refinery, Crew, Polecats) can work with both:
- Tracked beads: .beads/ checked into git at mayor/rig/.beads
- Local beads: .beads/ created at rig root during gt rig add
Key changes:
1. SetupRedirect now handles tracked beads by skipping redirect chains.
The bd CLI doesn't support chains (A→B→C), so worktrees redirect
directly to the final destination (mayor/rig/.beads for tracked).
2. ResolveBeadsDir is now used consistently in polecat and refinery
managers instead of hardcoded mayor/rig paths.
3. Rig-level agents (witness, refinery) now use rig beads with rig
prefix instead of town beads. This follows the architecture where
town beads are only for Mayor/Deacon.
4. prime.go simplified to always use ../../.beads for crew redirects,
letting rig-level redirect handle tracked vs local routing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(doctor): Add beads-redirect check for tracked beads
When a repo has .beads/ tracked in git (at mayor/rig/.beads), the rig root
needs a redirect file pointing to that location. This check:
- Detects missing rig-level redirect for tracked beads
- Verifies redirect points to correct location (mayor/rig/.beads)
- Auto-fixes with 'gt doctor --fix'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: Handle fileLock.Unlock error in daemon
Wrap fileLock.Unlock() return value to satisfy errcheck linter.
🤖 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>
- Add DefaultBranch field to RoleData struct
- Update refinery.md.tmpl to use {{ .DefaultBranch }} template variable
- Populate DefaultBranch from rig config in prime.go and rig/manager.go
- Default to 'main' if not configured
- Add test verifying DefaultBranch rendering in refinery template
Fixes issue where refinery agents merged to master instead of the
configured default branch (e.g., 'develop' or 'develop-cstar').
When patrol agents (witness, refinery, deacon) complete their patrol wisp,
they were left idle because the instructions only said "loop back" without
specifying the command to create a new wisp.
Updated:
- Work loop instructions in prime.go now explicitly tell agents:
* If context LOW: run `bd mol wisp mol-<role>-patrol` to create new wisp
* If context HIGH: use `gt handoff` and exit for daemon respawn
- mol-witness-patrol.formula.toml loop-or-exit step now has clear commands
This ensures patrol agents always either create a new wisp or exit cleanly,
preventing the "session alive but idle" state that caused mail to pile up.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The hook query now falls back to checking in_progress beads assigned to the
agent when no hooked beads are found. This ensures work is not lost when
a session is interrupted after claiming work.
Previously, gt hook only looked for status=hooked beads, so work that had
been claimed but not completed appeared lost. The fix extends the query to
also include in_progress beads assigned to the agent.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Migrate all role bead references from gt-*-role to hq-*-role using
beads.RoleBeadIDTown() function. Role beads are stored in town beads
(~/gt/.beads/) with the hq- prefix.
Changes:
- internal/cmd/prime.go: Use RoleBeadIDTown() for all roles
- internal/doctor/agent_beads_check.go: Use RoleBeadIDTown() for rig agents
- internal/polecat/manager.go: Use RoleBeadIDTown("polecat")
- internal/cmd/crew_add.go: Use RoleBeadIDTown("crew")
- internal/beads/beads.go: Update comments to document hq- convention
- Templates: Update bd show gt-deacon to bd show hq-deacon
Note: Tmux session names remain as gt-* (runtime identifiers).
Bead IDs use hq-* for town-level agents (persistent storage).
🤖 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>
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>
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>
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>
New outputSessionMetadata() function prints a structured line at prime start:
[GAS TOWN] role:mayor pid:12345 session:abc-uuid-123
This enables gt seance to discover sessions from Claude transcripts,
complementing the existing event emission to .events.jsonl.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add checkpoint system for polecats and crew workers to recover state
after session crash or context limit.
Features:
- internal/checkpoint package with Checkpoint type
- gt checkpoint write/read/clear commands
- Checkpoint display in gt prime startup
- Auto-detection of molecule, step, hooked bead
- Git state capture (modified files, branch, commit)
The checkpoint captures:
- Current molecule and step being worked
- Hooked bead
- Modified files list
- Git branch and last commit
- Session notes
- Timestamp
Checkpoints are stored in .polecat-checkpoint.json and displayed
during session startup via gt prime.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Align rig-scoped agent beads with route prefixes so crew add/prime/status resolve the same IDs across rigs. Add tests that assert rig-prefixed agent IDs in prime and status.
🤖 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>
Add "Hookable Mail" section to all role templates explaining how mail beads
can be hooked for ad-hoc instruction handoff. Key documentation points:
- GUPP applies to hooked mail: read and execute instructions
- Two use cases: hook existing mail, create+hook via gt handoff
- Role-specific examples for each agent type
Templates updated:
- boot.md.tmpl
- crew.md.tmpl
- deacon.md.tmpl
- mayor.md.tmpl
- polecat.md.tmpl
- refinery.md.tmpl
- witness.md.tmpl
Also updated prime.go fallback output functions to include hookable mail
reference for when templates fail to render.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Major redesign based on design review:
1. REMOVED: Claude Code internal parsing (ZFC violation)
- Deleted internal/claude/sessions.go (parsed ~/.claude/projects/)
- This coupled us to Claude Code's undocumented internal format
2. ADDED: Event-based session discovery
- gt prime now emits session_start events to ~/gt/.events.jsonl
- Events include role, session_id, topic, cwd
- Discovery reads our own event stream (ZFC-compliant)
3. ADDED: --talk flag for actual seances
- gt seance --talk <session-id> spawns: claude --fork-session --resume <id>
- --fork-session creates a new session (read-only, no grave disturbance)
- You literally talk to your predecessor: "Where did you put X?"
4. ADDED: One-shot prompt mode
- gt seance --talk <id> -p "Where is the config?"
- Uses claude --print for quick questions
The name "seance" is now literal - you commune with the dead (past sessions).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Role templates (crew, polecat, mayor, deacon, witness, refinery)
- prime.go startup protocol messages
- Documentation (propulsion, reference, molecules, wisp architecture)
- Session hints and sling prompts
- Formula template instructions
- CLAUDE.md
The hook is the user-facing concept, molecules are implementation details.
Agents should use `gt hook` to check what work is assigned to them.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Agent beads must use gt- prefix (required by beads validation).
Only issue beads use rig-specific prefixes (ga-, bd-, etc.).
Fixed in:
- crew_add.go: Use CrewBeadID() not CrewBeadIDWithPrefix()
- prime.go: Use non-prefix variants for all agent types
- sling.go: Use non-prefix variants for all agent types
This fixes 'invalid agent ID' error when creating crew in rigs
with non-gt prefix (e.g., gastown with ga- prefix).
🤖 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.
Implements structured escalation channel for Gas Town:
- gt escalate command with CRITICAL/HIGH/MEDIUM severity levels
- Mayor startup check for pending escalations
- Escalation beads with tag for audit trail
- Mail routing to overseer with priority mapping
- Documentation in docs/escalation.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Several files were setting cmd.Stderr = nil, which hides potentially
critical error messages:
- prime.go: bd prime, gt mail check, and bd show commands now log
stderr on failure for debugging
- orphans.go: git fsck now includes stderr in error messages
- patrol_helpers.go: bd list/show/catalog commands now log stderr
Daemon launch cases (up.go, daemon.go, daemon_check.go) correctly
use nil for I/O detachment but now have clarifying comments.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added multiple layers of protection against circular redirects:
1. ResolveBeadsDir now detects when a redirect points back to itself
and auto-removes the errant redirect file with a warning
2. ensureBeadsRedirect now includes safety checks:
- Prevents creating redirects inside mayor/rig/ (the canonical location)
- Validates that the redirect target is not the same as the beads dir
3. Added test case for circular redirect detection
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously gt prime only detected the Mayor role from town root (~/gt) or
~/gt/mayor/. Now it also detects Mayor from <rig>/mayor/ paths like
~/gt/gastown/mayor/rig, enabling mayor sessions to work correctly
regardless of which rig directory they're attached to.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add "The Capability Ledger" section to all 6 role templates explaining:
- Work visibility and reputation
- Redemption through consistent quality
- Every completion as evidence of autonomous execution at scale
- Work history as growing portfolio/CV
Also fix hooked vs pinned terminology confusion:
- "Hooked" = work assigned to you (triggers autonomous mode)
- "Pinned" = permanent reference beads
- Add clarifying note to all startup behavior sections
- Update code examples to use --status=hooked
Update prime.go AUTONOMOUS MODE output with ledger framing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- checkSlungWork now queries for status=hooked instead of status=pinned
- This makes AUTONOMOUS WORK MODE fire correctly when work is slung via gt hook
- Added "physics not politeness" language to AUTONOMOUS MODE output
- Added full Theory of Operation section to refinery.md.tmpl for consistency
The bug was: gt hook sets status=hooked but gt prime was querying for
status=pinned, so AUTONOMOUS MODE never triggered for hooked work.
(gt-kc7yj.3)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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>
All agent bead creation now uses shared role beads:
- gt-mayor-role, gt-deacon-role
- gt-witness-role, gt-refinery-role
- gt-crew-role, gt-polecat-role
Previous code created per-instance role bead references like
gt-witness-gastown-role which is wrong. Role beads are shared
class definitions, not per-instance.
Files fixed:
- internal/rig/manager.go
- internal/doctor/agent_beads_check.go
- internal/cmd/prime.go
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changes:
1. prime.go: Create agent beads on first prime for all roles including crew
2. done.go: Update agent state to done/stuck/idle when work completes
3. sling.go: Populate hook_bead when work is assigned to agents
4. mol-witness-patrol.formula.toml: Document dead and spawning states
Closes: gt-hymm0, gt-0lop3, gt-59k2x, gt-c4j4j
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changes:
1. Fix reportAgentState in prime.go to use beads API directly instead of
non-existent `bd agent state` command. Agents now properly self-report
their state to their agent beads on startup.
2. Update witness patrol survey-workers step to use agent beads:
- List polecats via `bd list --type=agent --json`
- Filter by role_type: polecat in description
- Check agent_state field (running/idle/stuck/done)
- Trust agent-reported state (ZFC principle)
No more PID/tmux inference for polecat state - agents self-report.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Beads CLI restructured: pour and wisp are now subcommands of mol.
- bd pour → bd mol pour
- bd wisp → bd mol wisp
Updated all documentation, templates, and code to use new command structure.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The Deacon propulsion was broken because:
1. outputDeaconPatrolContext() created patrols in gastown/mayor/rig/.beads
2. checkSlungWork() looked in ~/gt/deacon/.beads/ (empty)
3. These were different locations - pinned work never found
Fix:
- Created redirect: ~/gt/deacon/.beads/redirect -> ../.beads (town beads)
- Changed outputDeaconPatrolContext() to use ctx.WorkDir instead of
hardcoded gastown path
- Updated deacon template to remove hardcoded gastown references
- Updated wisp creation docs to use two-step pattern (create then pin)
Also cleaned up 14 stale patrol wisps that accumulated in rig beads
from repeated startup attempts.
Filed gt-0pdhj to track remaining hardcoded gastown dependencies.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
