## Problem
Claude processes were accumulating as orphans, with 100+ processes piling up
daily. Every `gt handoff` (used dozens of times/hour by crew) left orphaned
processes because `tmux respawn-pane -k` only sends SIGHUP, which Node/Claude
ignores.
## Root Cause
Previous fixes (1043f00d, f89ac47f, 2feefd17, 1b036aad) were laser-focused on
specific symptoms (shutdown, setsid, done.go, molecule_step.go) but never did
a comprehensive audit of ALL RespawnPane call sites. handoff.go was never
fixed despite being the main source of orphans.
## Solution
Added KillPaneProcesses() call before every RespawnPane() in:
- handoff.go (self handoff and remote handoff)
- mayor.go (mayor restart)
- crew_at.go (new session and restart)
KillPaneProcesses explicitly kills all descendant processes with SIGTERM/SIGKILL
before respawning, preventing orphans regardless of SIGHUP handling.
molecule_step.go already had this fix from commit 1b036aad.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When the repo is in a broken state (wrong branch, detached HEAD, deleted
worktree), gt handoff would fail with "cannot detect town root" error.
This is exactly when handoff is most needed - to recover and hand off
to a fresh session.
Changes:
- detectTownRootFromCwd() now falls back to GT_TOWN_ROOT and GT_ROOT
environment variables when cwd-based detection fails
- buildRestartCommand() now propagates GT_ROOT to ensure subsequent
handoffs can also use the fallback
- Added tests for the fallback behavior
Fixes gt-x2q81.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds GT_AGENT env var to track agent override when using --agent flag.
Handoff reads and preserves GT_AGENT so non-default agents persist across restarts.
Co-authored-by: joshuavial <git@codewithjv.com>
The handoff mail bead was created with un-normalized assignee
(e.g., gastown/crew/holden) but mailbox queries use normalized identity
(gastown/holden), causing self-mail to be invisible to the inbox.
Export addressToIdentity as AddressToIdentity and call it in
sendHandoffMail() to normalize the agent identity before storing,
matching the normalization performed in Router.sendToSingle().
Fix handoff mail delivery (hq-snp8)
The witness role doesn't have a /rig worktree like the refinery does.
The handoff command was trying to cd to <rig>/witness/rig which doesn't
exist, causing the respawned pane to fail immediately and the session
to die.
Changed witness workdir from <rig>/witness/rig to <rig>/witness.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
detectTownRootFromCwd() only checked for mayor/town.json, but
workspace.FindFromCwd() also accepts mayor/ directory as a secondary
marker. This fixes handoff failing in workspaces without town.json.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When using gastown/max style paths, resolvePathToSession was treating
all non-role names as polecats, generating gt-gastown-max instead of
gt-gastown-crew-max.
Now checks if <townRoot>/<rig>/crew/<name> exists before defaulting
to polecat format. This fixes gt sling to crew members using the
shorthand rig/name syntax.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
sessionWorkDir had cases for mayor, deacon, crew, witness, and refinery
but not polecats. When gt handoff was run from a polecat session like
gt-tanwa_info-slit, it failed with "unknown session type".
Fix uses session.ParseSessionName to parse the session name and extract
rig/name for polecat sessions, mapping to <townRoot>/<rig>/polecats/<name>.
Fixes: gm-lie6
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>
When routing-based verification (verifyBeadExists) fails due to
routes.jsonl configuration issues, gt sling now falls back to pattern
matching via looksLikeBeadID to accept valid bead ID formats.
The fix ensures:
1. verifyBeadExists is tried first (routing-based lookup)
2. verifyFormulaExists is tried second (formula check)
3. looksLikeBeadID pattern match is used as final fallback
Also improved looksLikeBeadID to accept any 1-5 letter lowercase
prefix followed by hyphen and alphanumeric chars.
Fixes: gt sling bd-xxx failing with "not a valid bead or formula"
when the bead exists but routing cannot find it.
Closes: gt-9e8s5
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Agents were confused when receiving "gt prime" as their first prompt,
interpreting it as a command to investigate rather than understanding
they were starting a Gas Town session.
Changed crew_at.go, start.go, and handoff.go to use FormatStartupNudge()
which produces a proper beacon like:
[GAS TOWN] george/crew/george <- human • 2026-01-09T10:30 • start
The SessionStart hook (gt prime --hook) still injects context - the
prompt just needs to be something agents recognize as a greeting.
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>
buildRestartCommand() now propagates Claude-related env vars when
respawning sessions via tmux. Fresh shells don't inherit parent env,
so CLAUDE_CODE_USE_BEDROCK, ANTHROPIC_API_KEY, AWS_*, etc. were lost.
This caused any tmux respawn to result in a non-functional claude.
Adds claudeEnvVars list and includes them in the export command when
building the restart command.
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>
Add --exit flag to `gt done` that terminates the Claude session
immediately after submitting the MR to the merge queue. This prevents
polecats from sitting idle (and wasting money) while waiting for the
Witness to kill them.
Changes:
- Rename existing --exit flag to --status (for exit type)
- Add new --exit boolean flag for session self-termination
- Update docs and help text to reflect new flag names
Usage: gt done --exit
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add --collect/-c flag to gt handoff: auto-collects hooked work,
inbox summary, ready beads, and in-progress items into the handoff
message body
- Add --handoff flag to gt resume: checks inbox for messages with
"HANDOFF" in subject and displays them formatted for continuation
- Supports both JSON and plain-text inbox output formats
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When gt handoff is run with -s and -m flags, it now:
- Creates the handoff mail bead directly using bd create
- Captures the created bead ID
- Auto-hooks the bead with status=hooked so the next session picks it up
This enables the handoff workflow:
gt handoff -s "Title" -m "Instructions..."
The next session startup hook (gt prime) will detect the hooked bead
and present it to the agent for immediate execution.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Agents weren't auto-executing after gt handoff because the SessionStart
hook only outputs text - it doesn't inject a prompt. Claude needs actual
user input to trigger a response.
The fix: pass "gt prime" as an argument to claude, just like gt crew at
already does. This treats the argument as the first user prompt, which
triggers GUPP execution immediately.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 1 of activity feed improvements: gt commands now log events to
~/gt/.events.jsonl. This is the raw audit log that the feed daemon
(phase 2) will curate into the user-facing feed.
Instrumented commands:
- gt sling: logs sling events with bead and target
- gt hook: logs hook events with bead
- gt handoff: logs handoff events with subject
- gt done: logs done events with bead and branch
- gt mail send: logs mail events with to and subject
Event format follows the specification:
```json
{"ts":"2025-12-30T07:36:28Z","source":"gt","type":"mail",
"actor":"gastown/crew/joe","payload":{...},"visibility":"feed"}
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add PrintWarning helper in internal/style/style.go
- Update 35 warning message outputs across 16 files to use consistent format
- All warnings now display as "⚠ Warning: <message>" in yellow/bold
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create AgentIdentity type to parse and construct session names, replacing
duplicated logic in sling.go and handoff.go.
- Add internal/session/identity.go with AgentIdentity type
- ParseSessionName handles: mayor, deacon, witness, refinery, crew, polecat
- SessionName() reconstructs valid tmux session name
- Address() returns mail-style address (e.g., "gastown/crew/max")
- GTRole() returns GT_ROLE env var format
- Update sling.go:sessionToAgentID to use ParseSessionName
- Update handoff.go:sessionToGTRole to use ParseSessionName
- Add comprehensive unit tests with round-trip verification
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace hook file mechanism with discovery-based pinned beads:
- gt hook: now runs bd update <bead> --status=pinned
- gt sling: same, plus nudge to target
- gt handoff: same when bead ID provided
- gt prime: checks pinned beads instead of hook files
- gt mol status: no longer checks hook files
Key changes:
- outputAttachmentStatus: extended to all roles (was Crew/Polecat only)
- checkSlungWork: now queries pinned beads instead of reading hook files
- wisp/io.go functions: marked deprecated with migration notes
This follows Gas Town discovery over explicit state principle.
Hook files are kept for backward compatibility but no longer written.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When gt spawns agents (polecats, crew, patrol roles), it now sets the
BD_ACTOR env var so that bd commands (like `bd hook`) know the agent
identity without coupling to gt.
Updated spawn points:
- gt up (mayor, deacon, witness via ensureSession/ensureWitness)
- gt deacon start
- gt witness start
- gt start refinery
- gt mayor start
- Daemon deacon restart
- Daemon lifecycle restart
- Handoff respawn
- Refinery manager start
BD_ACTOR uses slash format (e.g., gastown/witness, gastown/crew/max)
while GT_ROLE may use dash format internally.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Organize 43 commands into 7 logical groups using cobra's built-in
AddGroup/GroupID feature:
- Work Management: spawn, sling, hook, handoff, done, mol, mq, etc.
- Agent Management: mayor, witness, refinery, deacon, polecat, etc.
- Communication: mail, nudge, broadcast, peek
- Services: daemon, start, stop, up, down, shutdown
- Workspace: rig, crew, init, install, git-init, namepool
- Configuration: account, theme, hooks, issue, completion
- Diagnostics: status, doctor, prime, version, help
Also renamed molecule to mol as the primary command name
(molecule is now an alias).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds ClearHistory method to tmux package and calls it before
respawn-pane during handoff. This resets copy-mode display
from [0/N] to [0/0] for a clean session start.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- New gt role subcommands: show, home, detect, list, env
- Role detection now checks GT_ROLE env var first, falls back to cwd
- gt prime shows warning when role/cwd mismatch detected
- gt mol status uses env-aware role detection
- gt handoff injects GT_ROLE and resets to role canonical home
- Fixed witness/refinery home paths (was missing /rig suffix)
This prevents role confusion when agents wander to wrong directories.
After handoff, agents are always restored to their canonical home.
- Add gt hook <bead>: durability primitive, attaches work to hook
- Update gt handoff: accept optional bead arg (detects bead vs role)
- Deprecate gt sling: shows warning, points to new commands
- Update doctor fix hint to reference new commands
🤖 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>
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>
Three related fixes:
1. lifecycle.go: Use gt mail delete instead of gt mail read to prevent
lifecycle requests from accumulating.
2. handoff.go: Return exec claude command for respawn-pane instead of
gt crew at which tries to attach to existing session.
3. handoff.md skill: Work without --cycle and -m flags, send mail separately.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When `gt mq submit` is run from a polecat work branch (polecat/<worker>/<issue>),
it now automatically triggers polecat shutdown after submitting the MR. The
polecat sends a lifecycle request to its Witness and waits for termination.
This eliminates the need for polecats to manually run `gt handoff --shutdown`
after completing work - they can just run `gt mq submit` and the cleanup
happens automatically.
Added `--no-cleanup` flag to disable auto-cleanup when needed (e.g., for
submitting multiple MRs or continuing work).
Closes gt-tca
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The daemon verifies requesting_cycle=true in state.json before
executing lifecycle actions. For crew workers, the state file
must be at <townRoot>/<rig>/crew/<name>/state.json.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Crew workers now use deacon for lifecycle management instead of
requiring manual session termination. When a crew worker runs
'gt handoff', it sends a lifecycle request to the deacon which
handles session kill/restart like it does for Mayor and Witness.
Changes:
- Route crew manager to deacon/ instead of "human"
- Add getCrewIdentity() to extract <rig>-crew-<name> from session
- Include full crew identity in LIFECYCLE subject for daemon parsing
- Remove special case that skipped lifecycle flow for crew
Also fixes pre-existing test failures in daemon/lifecycle_test.go
where BeadsMessage field names were out of sync with the struct.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add crew session detection before polecat (gt-*-crew-* pattern)
- Crew workers exit immediately after sending handoff mail
- No waiting for manager since crew is human-managed
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
