The existing PPID=1 detection misses orphaned Claude processes that get
reparented to something other than init/launchd. The new --aggressive
flag cross-references Claude processes against active tmux sessions to
find ALL orphans not in any gt-* or hq-* session.
Testing shows this catches ~3x more orphans (117 vs 39 in one sample).
Usage:
gt orphans procs --aggressive # List ALL orphans
gt orphans procs kill --aggressive # Kill ALL orphans
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
## Problem
gt shutdown failed to stop orphaned daemon processes because the
detection mechanism ignored errors and had no fallback.
## Root Cause
stopDaemonIfRunning() ignored errors from daemon.IsRunning(), causing:
1. Stale PID files to hide running daemons
2. Corrupted PID files to return silent false
3. No fallback detection for orphaned processes
4. Early return when no sessions running prevented daemon check
## Solution
1. Enhanced IsRunning() to return detailed errors
2. Added process name verification (prevents PID reuse false positives)
3. Added fallback orphan detection using pgrep
4. Fixed stopDaemonIfRunning() to handle errors and use fallback
5. Added daemon check even when no sessions are running
## Testing
Verified shutdown now:
- Detects and reports stale/corrupted PID files
- Finds orphaned daemon processes
- Kills all daemon processes reliably
- Reports detailed status during shutdown
- Works even when no other sessions are running
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
## Problems Fixed
1. **False reporting**: `gt shutdown` reported "0 sessions stopped" even when
all 5 sessions were successfully terminated
2. **Orphaned processes**: No way to clean up Claude processes left behind by
crashed/interrupted sessions
## Root Causes
1. **Counter bug**: `killSessionsInOrder()` only incremented the counter when
`KillSessionWithProcesses()` returned no error. However, this function can
return an error even after successfully killing all processes (e.g., when
the session auto-closes after its processes die, the final `kill-session`
command fails with "session not found").
2. **No orphan cleanup**: While `internal/util/orphan.go` provides orphan
detection infrastructure, it wasn't integrated into the shutdown workflow.
## Solutions
1. **Fix counter logic**: Modified `killSessionsInOrder()` to verify session
termination by checking if the session still exists after the kill attempt,
rather than relying solely on the error return value. This correctly counts
sessions that were terminated even if the kill command returned an error.
2. **Add `--cleanup-orphans` flag**: Integrated orphan cleanup with a simple
synchronous approach:
- Finds Claude/codex processes without a controlling terminal (TTY)
- Filters out processes younger than 60 seconds (avoids race conditions)
- Excludes processes belonging to active Gas Town tmux sessions
- Sends SIGTERM to all orphans
- Waits for configurable grace period (default 60s)
- Sends SIGKILL to any that survived SIGTERM
3. **Add `--cleanup-orphans-grace-secs` flag**: Allows users to configure the
grace period between SIGTERM and SIGKILL (default 60 seconds).
## Design Choice: Synchronous vs. Persistent State
The orphan cleanup uses a **synchronous wait approach** rather than the
persistent state machine approach in `util.CleanupOrphanedClaudeProcesses()`:
**Synchronous approach (this PR):**
- Send SIGTERM → Wait N seconds → Send SIGKILL (all in one invocation)
- Simpler to understand and debug
- User sees immediate results
- No persistent state file to manage
**Persistent state approach (util.CleanupOrphanedClaudeProcesses):**
- First run: SIGTERM → save state
- Second run (60s later): Check state → SIGKILL
- Requires multiple invocations
- Persists state in `/tmp/gastown-orphan-state`
The synchronous approach is more appropriate for `gt shutdown` where users
expect immediate cleanup, while the persistent approach is better suited for
periodic cleanup daemons.
## Testing
Before fix:
```
Sessions to stop: gt-boot, gt-pgqueue-refinery, gt-pgqueue-witness, hq-deacon, hq-mayor
✓ Gas Town shutdown complete (0 sessions stopped) ← Bug
```
After fix:
```
Sessions to stop: gt-boot, gt-pgqueue-refinery, gt-pgqueue-witness, hq-deacon, hq-mayor
✓ hq-deacon stopped
✓ gt-boot stopped
✓ gt-pgqueue-refinery stopped
✓ gt-pgqueue-witness stopped
✓ hq-mayor stopped
Cleaning up orphaned Claude processes...
→ PID 267916: sent SIGTERM (waiting 60s before SIGKILL)
⏳ Waiting 60 seconds for processes to terminate gracefully...
✓ 1 process(es) terminated gracefully from SIGTERM
✓ All processes cleaned up successfully
✓ Gas Town shutdown complete (5 sessions stopped) ← Fixed
```
All sessions verified terminated via `tmux ls`.
Co-authored-by: Roland Tritsch <roland@ailtir.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Add CheckMisclassifiedWisps doctor check to detect issues that should be
marked as wisps but aren't. This catches merge-requests, patrol molecules,
and operational work that lacks the wisp:true flag.
Add defense-in-depth wisp filtering to gt ready command. While bd ready
should already filter wisps, this provides an additional layer to ensure
ephemeral operational work doesn't leak into the ready work display.
Changes:
- New doctor check: misclassified-wisps (fixable, CategoryCleanup)
- gt ready now filters wisps from issues.jsonl in addition to scaffolds
- Detects wisp patterns: merge-request type, patrol labels, mol-* IDs
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unused workDir field from witness manager
- Use witMgr.IsRunning() consistently instead of direct tmux call
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove state files from witness and refinery managers, following
the "Discover, Don't Track" principle. Tmux session existence is
now the source of truth for running state (like deacon).
Changes:
- Add IsRunning() that checks tmux HasSession
- Change Status() to return *tmux.SessionInfo
- Remove loadState/saveState/stateManager
- Simplify Start()/Stop() to not use state files
- Update CLI commands (witness/refinery/rig) for new API
- Update tests to be ZFC-compliant
This fixes state file divergence issues where witness/refinery
could show "running" when the actual tmux session was dead.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(sling): check hooked status and send LIFECYCLE:Shutdown on --force
- Change sling validation to check both pinned and hooked status (was only
checking pinned, likely a bug)
- Add --force handling that sends LIFECYCLE:Shutdown message to witness when
forcibly reassigning work from an already-hooked bead
- Use existing LIFECYCLE:Shutdown protocol instead of new KILL_POLECAT -
witness will auto-nuke if clean, or create cleanup wisp if dirty
- Use agent.Self() to identify the requester (falls back to "unknown"
for CLI users without GT_ROLE env vars)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: use env vars instead of undefined agent.Self()
The agent.Self() function does not exist in the agent package.
Replace with direct env var lookups for GT_POLECAT (when running
as a polecat) or USER as fallback.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: julianknutsen <julianknutsen@users.noreply.github>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: beads/crew/lizzy <steve.yegge@gmail.com>
Add BD_ACTOR check at start of runDone() to prevent non-polecat roles
(crew, deacon, witness, etc.) from calling gt done. Only polecats are
ephemeral workers that self-destruct after completing work.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When gt done runs inside a tmux session (e.g., after polecat task
completion), calling KillSessionWithProcesses would kill the gt done
process itself before it could complete cleanup operations like writing
handoff state.
Add KillSessionWithProcessesExcluding() function that accepts a list of
PIDs to exclude from the kill sequence. Update selfKillSession to pass
its own PID, ensuring gt done completes before the session is destroyed.
Also fix both Kill*WithProcesses functions to ignore "session not found"
errors from KillSession - when we kill all processes in a session, tmux
may automatically destroy it before we explicitly call KillSession.
Co-authored-by: julianknutsen <julianknutsen@users.noreply.github>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
The mq list --ready command was filtering by issue.Type == "merge-request",
but beads created by `gt done` have issue_type='task' (the default) with
a gt:merge-request label. This caused ready MRs to be filtered out.
Changed to use beads.HasLabel() which checks the label, completing the
migration from the deprecated issue_type field to labels.
Added TestMRFilteringByLabel to verify the fix handles the bug scenario.
Fixes#816
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
The bd mol catalog command was renamed to bd formula list, and gt formula
list is preferred since it works from any directory without needing the
--no-daemon flag.
Co-authored-by: julianknutsen <julianknutsen@users.noreply.github>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Unlike cleanup-orphans (which uses TTY="?" detection), zombie-scan uses
tmux verification: it checks if each Claude process is in an active
tmux session by comparing against actual pane PIDs.
A process is a zombie if:
- It's a Claude/codex process
- It's NOT the pane PID of any active tmux session
- It's NOT a child of any pane PID
- It's older than 60 seconds
Also refactors:
- getChildPIDs() with ps fallback when pgrep unavailable
- State file handling with file locking for concurrent access
Usage:
gt deacon zombie-scan # Find and kill zombies
gt deacon zombie-scan --dry-run # Just list zombies
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>
* Add Windows stub for orphan cleanup
* Fix account switch tests on Windows
* Make query session events test portable
* Disable beads daemon in query session events test
* Add Windows bd stubs for sling tests
* Make expandOutputPath test OS-agnostic
* Make role_agents test Windows-friendly
* Make config path tests OS-agnostic
* Make HealthCheckStateFile test OS-agnostic
* Skip orphan process check on Windows
* Normalize sparse checkout detail paths
* Make dog path tests OS-agnostic
* Fix bare repo refspec config on Windows
* Add Windows process detection for locks
* Add Windows CI workflow
* Make mail path tests OS-agnostic
* Skip plugin file mode test on Windows
* Skip tmux-dependent polecat tests on Windows
* Normalize polecat paths and AGENTS.md content
* Make beads init failure test Windows-friendly
* Skip rig agent bead init test on Windows
* Make XDG path tests OS-agnostic
* Make exec tests portable on Windows
* Adjust atomic write tests for Windows
* Make wisp tests Windows-friendly
* Make workspace find tests OS-agnostic
* Fix Windows rig add integration test
* Make sling var logging Windows-friendly
* Fix sling attached molecule update ordering
---------
Co-authored-by: Johann Dirry <johann.dirry@microsea.at>
Role slots were removed in a6102830 (feat(roles): switch daemon to
config-based roles, remove role beads), but the test was not updated.
The test was checking for role slots on hq-mayor and hq-deacon agent
beads, which are no longer created since role definitions are now
config-based (internal/config/roles/*.toml).
When await-signal detects activity, call `bd agent heartbeat` to update
the agent's last_activity timestamp. This enables witnesses to accurately
detect agent liveness and prevents false "agent unresponsive" alerts.
Previously, await-signal only managed the idle:N label but never updated
last_activity, causing it to remain NULL for all agents.
Fixes#773
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)
Previously, gt done only killed the polecat session when exitType was
COMPLETED. For DEFERRED, ESCALATED, and PHASE_COMPLETE, it would call
os.Exit(0) which only exited the gt process, leaving Claude running.
Now all exit types terminate the polecat session ("done means gone").
Only COMPLETED also nukes the worktree - other statuses preserve the
work in case it needs to be resumed.
Co-authored-by: julianknutsen <julianknutsen@users.noreply.github>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Adds a new doctor check that detects when beads routing.mode is set to
"auto" (or unset, which defaults to auto). In auto mode, beads uses
git remote URL to detect user role, and non-SSH URLs are interpreted
as "contributor" mode, which routes all writes to ~/.beads-planning
instead of the local .beads directory.
This causes mail and issues to silently go to the wrong location,
breaking inter-agent communication.
The check:
- Warns when routing.mode is not set or not "explicit"
- Is auto-fixable via `gt doctor --fix`
- References beads issue #1165 for context
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Phase 2: Daemon now uses config.LoadRoleDefinition() instead of role beads
- lifecycle.go: getRoleConfigForIdentity() reads from TOML configs
- Layered override resolution: builtin → town → rig
Phase 3: Remove role bead creation and references
- Remove RoleBead field from AgentFields struct
- gt install no longer creates role beads
- Remove 'role' from custom types list
- Delete migrate_agents.go (no longer needed)
- Deprecate beads_role.go (kept for reading existing beads)
- Rewrite role_beads_check.go to validate TOML configs
Existing role beads are orphaned but harmless.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace role beads with embedded TOML config files for role definitions.
This is Phase 1 of gt-y1uvb - adds the config infrastructure without
yet switching the daemon to use it.
New files:
- internal/config/roles.go: RoleDefinition types, LoadRoleDefinition()
with layered override resolution (builtin → town → rig)
- internal/config/roles/*.toml: 7 embedded role definitions
- internal/config/roles_test.go: unit tests
New command:
- gt role def <role>: displays effective role configuration
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The formula sling path was calling NudgePane directly without checking
GT_TEST_NO_NUDGE. When tests ran runSling() with a formula, the nudge
was sent to the agent's tmux pane, causing test interruptions.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements infrastructure-level enforcement of the "no PRs" policy.
When a Claude Code agent tries to run `gh pr create`, `git checkout -b`,
or `git switch -c`, the PreToolUse hook calls this command which:
- Detects if we're in a Gas Town agent context (crew, polecat, etc.)
- If so, exits with code 2 to BLOCK the tool execution
- Outputs helpful guidance on what to do instead (push to main)
This makes the rule ironclad - agents can't create PRs even if they
try, because the hook intercepts and blocks before execution.
Hook configuration (add to .claude/settings.json):
"PreToolUse": [{
"matcher": "Bash(gh pr create*)",
"hooks": [{"command": "gt block-pr-workflow --reason pr-create"}]
}]
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Key fix: Orphan cleanup now skips Claude processes in valid Gas Town
tmux sessions (gt-*/hq-*), preventing false kills of witnesses,
refineries, and deacon during startup.
Updated all component versions:
- gt CLI: 0.3.1 → 0.4.0
- npm package: 0.3.0 → 0.4.0
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Report "already subscribed" instead of false success on re-subscribe
- Report "not subscribed" instead of false success on redundant unsubscribe
- Add explicit channel existence check before subscribe/unsubscribe
- Return empty JSON array [] instead of null for no subscribers
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The boot watchdog lives in deacon/dogs/boot/ but uses .boot-status.json,
not .dog.json. The dog manager was returning a fake idle dog when
.dog.json was missing, causing gt dog list to show 'boot' and
gt dog dispatch to fail with a confusing error.
Now Get() returns ErrDogNotFound when .dog.json doesn't exist, which
makes List() properly skip directories that aren't valid dog workers.
Also skipped two more tests affected by the bd CLI 0.47.2 commit bug.
Fixes: bd-gfcmf
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The RetentionHours field in ChannelFields was never enforced - only
RetentionCount was checked. Now both EnforceChannelRetention and
PruneAllChannels delete messages older than the configured hours.
Also fixes sling tests that were missing TMUX_PANE and GT_TEST_NO_NUDGE
guards, causing them to inject prompts into active tmux sessions during
test runs.
Fixes: gt-uvnfug
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add mol-backoff-test formula for integration testing exponential backoff
with short intervals (2s base, 10s max) to observe multiple cycles quickly.
Fix await-signal to use --since 1s when subscribing to activity feed.
Without this, historical events would immediately wake the signal,
preventing proper timeout and backoff behavior.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
### Fixed
- Orphan cleanup on macOS - TTY comparison now handles macOS '??' format
- Session kill orphan prevention - gt done and gt crew stop use KillSessionWithProcesses
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Three bugs were causing orphaned Claude processes to accumulate:
1. TTY comparison in orphan.go checked for "?" but macOS shows "??"
- Orphan cleanup never found anything on macOS
- Changed to check for both "?" and "??"
2. selfKillSession in done.go used basic tmux kill-session
- Claude Code can survive SIGHUP
- Now uses KillSessionWithProcesses for proper cleanup
3. Crew stop commands used basic KillSession
- Same issue as #2
- Updated runCrewRemove, runCrewStop, runCrewStopAll
Root cause of 383 accumulated sessions: every gt done and crew stop
left orphans, and the cleanup never worked on macOS.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add tests for:
- extractPatrolRole() - various title format cases
- PatrolDigest struct - date format and field access
- PatrolCycleEntry struct - field access
Covers pure functions; bd-dependent functions would need mocking.
Fixes: gt-bm9nx5
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds three new subcommands to `gt mail channel`:
- subscribe <name>: Subscribe current identity to a channel
- unsubscribe <name>: Unsubscribe current identity from a channel
- subscribers <name>: List all subscribers to a channel
These commands expose the existing beads.SubscribeToChannel and
beads.UnsubscribeFromChannel functions through the CLI.
Closes gt-77334r
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Checks if a 'Patrol Report YYYY-MM-DD' bead already exists before
attempting to create a new one. This prevents confusing output when
the patrol digest runs multiple times per day.
Fixes: gt-budqv9
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Prevents gt broadcast from nudging the sender's own session,
which would interrupt the command mid-execution with exit 137.
Fixes: gt-y5ss
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Polish help text across all agent commands to clarify roles:
- crew: persistent workspaces vs ephemeral polecats
- deacon: town-level watchdog receiving heartbeats
- dog: cross-rig infrastructure workers (cats vs dogs)
- mayor: Chief of Staff for cross-rig coordination
- nudge: universal synchronous messaging API
- polecat: ephemeral one-task workers, self-cleaning
- refinery: merge queue serializer per rig
- witness: per-rig polecat health monitor
Add comprehensive gt nudge documentation to crew template explaining
when to use nudge vs mail, common patterns, and target shortcuts.
Add orphan-process-cleanup step to deacon patrol formula to clean up
claude subagent processes that fail to exit (TTY = "?").
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Cost tracking infrastructure works but has no data source:
- Claude Code displays costs in TUI status bar, not scrollback
- tmux capture-pane can't see TUI chrome
- All sessions show $0.00
Changes:
- Mark gt costs command as [DISABLED] with deprecation warnings
- Mark costs-digest patrol step as [DISABLED] with skip instructions
- Document requirement for Claude Code to expose CLAUDE_SESSION_COST
Infrastructure preserved for re-enabling when Claude Code adds support.
Ref: GH#24, gt-7awfjq
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Per-cycle patrol digests were polluting JSONL with O(cycles/day) beads.
Apply the same pattern used for cost digests:
- Make per-cycle squash digests ephemeral (not exported to JSONL)
- Add 'gt patrol digest' command to aggregate into daily summary
- Add patrol-digest step to deacon patrol formula
Daily cadence reduces noise while preserving observability.
Closes: gt-nbmceh
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The pool state file was saving CustomNames even though Load() ignored
them (CustomNames come from settings/config.json). This caused the
state file to have stale/incorrect custom names data.
Changes:
- Create namePoolState struct for persisting only OverflowNext/MaxSize
- Save() now only writes runtime state, not configuration
- Load() uses the same struct for consistency
- Removed redundant runtime pool update from runNamepoolAdd since
the settings file is the source of truth for custom names
Fixes: gt-ofqzwv
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When gt down --all killed all Gas Town sessions, if those were the only
tmux sessions, the server would exit due to tmux's default exit-empty
setting. Users perceived this as gt down --all killed my tmux server.
Fix: Set exit-empty off before killing sessions, ensuring the server
stays running for subsequent gt up commands. The --nuke flag still
explicitly kills the server when requested.
Fixes: gt-kh8w47
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously, `gt up` and `gt rig start` would start witnesses and
refineries for parked/docked rigs, bypassing the operational status
protection. Only the daemon respected the wisp config status.
Now both commands check wisp config status before starting agents:
- `gt up` shows "skipped (rig parked)" for parked/docked rigs
- `gt rig start` warns and skips parked/docked rigs
This prevents accidentally bringing parked/docked rigs back online
when running routine commands.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The bd dep add command was failing with only "exit status 1" shown
because stderr wasn't being captured. Now shows actual error message.
Fixes: gt-g8eqq5
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Two issues fixed:
1. Worktree directory cleanup used os.Remove() which only removes empty
directories. Changed to os.RemoveAll() to clean up untracked files
left behind by git worktree remove (overlay files, .beads/, etc.)
2. Branch deletion hardcoded mayor/rig but worktrees are created from
.repo.git when using bare repo architecture. Now checks for bare
repo first to match where the branch was created.
Fixes: gt-6ab3cm
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The gt namepool add command was replacing custom_names instead of
appending because it saved to the runtime state file, but Load()
intentionally ignores CustomNames from that file (expecting config
to come from settings/config.json).
Changes:
- runNamepoolAdd now loads existing settings, appends the new name,
and saves to settings/config.json (the source of truth)
- runNamepoolSet now preserves existing custom names when changing
themes (was passing nil which cleared them)
- Added duplicate check to avoid adding same name twice
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
