Add EnsureGitignorePatterns to rig package that ensures .gitignore
has required Gas Town patterns (.runtime/, .claude/, .beads/, .logs/).
Called from crew and polecat managers when creating new workers.
This prevents runtime-gitignore warnings from gt doctor.
The function:
- Creates .gitignore if it doesn't exist
- Appends missing patterns to existing files
- Recognizes pattern variants (.runtime vs .runtime/)
- Adds "# Gas Town" header when appending
Includes comprehensive tests for all scenarios.
Changed findRuntimeProcesses() to only detect Claude processes that have
the --dangerously-skip-permissions flag. This is the signature of Gas Town
managed processes - user's personal Claude sessions don't use this flag.
Prevents false positives when users have personal Claude sessions running.
Closes#611
Co-Authored-By: dwsmith1983 <dwsmith1983@users.noreply.github.com>
Co-Authored-By: Claude Opus 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>
* fix(formulas): replace hardcoded ~/gt/ paths with $GT_ROOT
Formula files contained hardcoded ~/gt/ paths that break when running
Gas Town from a non-default location (e.g., ~/gt-private/). This causes:
- Dogs stuck in working state (can't write to wrong path)
- Cross-town contamination when ~/gt/ exists as separate town
- Boot triage, deacon patrol, and log archival failures
Replaces all ~/gt/ and $HOME/gt/ references with $GT_ROOT which is
set at runtime to the actual town root directory.
Fixes#757
* chore: regenerate embedded formulas
Run go generate to sync embedded formulas with .beads/formulas/ source.
- 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>
Agents were misfiling beads in HQ when they should go to project-specific
rigs (beads, gastown). The templates explained routing mechanics but not
decision making. Added "Where to File Beads" sections with:
- Routing table based on what code the issue affects
- Simple heuristic: "Which repo would the fix be committed to?"
- Examples for bd CLI → beads, gt CLI → gastown, coordination → HQ
Affects: mayor, deacon, crew, polecat templates.
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>
Verifies the codebase compiles for all supported platforms
(Linux, macOS, Windows, FreeBSD on amd64/arm64). This catches
cases where platform-specific code is called without providing
stubs for all platforms.
From PR #781.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes gt crew list showing wrong names when state.json contains stale data.
Always use directory name as source of truth in loadState() instead of
trusting potentially stale state.json.
Co-authored-by: joshuavial <git@codewithjv.com>
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).
Add initial prompt to deacon and witness startup commands to trigger
autonomous patrol. Without this, agents sit idle at the prompt after
SessionStart hooks run.
Implements GUPP (Gas Town Universal Propulsion Principle): agents start
patrol immediately when Claude launches.
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>
When starting crew without mayor running, tmux has-session can return
"no current target" if no tmux server exists. This error was not
mapped to ErrNoServer, causing crew start to fail instead of
bootstrapping a new tmux server.
Add "no current target" to the ErrNoServer detection so crew (and
other agents) can start independently without requiring an existing
tmux session.
Reproduction:
- Ensure no tmux server running (tmux kill-server)
- Run: gt crew start <rig>/<name>
- Before fix: "Error: checking session: tmux has-session: no current target"
- After fix: Crew session starts successfully
Co-authored-by: Shaun <TechnicallyShaun@users.noreply.github.com>
The WaitForRuntimeReady function was looking for "> " to detect
when Claude is ready, but Claude Code uses "❯" (U+276F) as its
prompt character. This caused refineries to timeout during startup.
Fixes#763
Executed-By: mayor
Role: mayor
When a human attaches to mayor via gt mayor and the runtime has
exited, it restarts with Topic: attach. But FormatStartupNudge
did not include instructions for this topic, causing Claude to act
generically instead of checking hook/mail.
Add attach to the list of topics that get explicit instructions.
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>
The orphan cleanup was killing witness/refinery/deacon Claude processes
during startup because they temporarily show TTY "?" before fully
attaching to the tmux session.
Added getGasTownSessionPIDs() to discover all PIDs belonging to valid
gt-* and hq-* tmux sessions (including child processes). The orphan
cleanup now skips these PIDs, only killing truly orphaned processes
from dead sessions.
This fixes the race condition where:
1. Daemon starts a witness/refinery session
2. Claude starts but takes time to show a prompt
3. Startup detection times out
4. Orphan cleanup sees Claude with TTY "?" and kills it
Now processes in valid sessions are protected regardless of TTY state.
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>
Tests calling bd create were picking up BD_ACTOR from the environment,
routing to production databases instead of isolated test databases.
After extensive investigation, discovered the root cause is bd CLI
0.47.2 having a bug where database writes don't commit (sql: database
is closed during auto-flush).
Added test isolation infrastructure (NewIsolated, getActor, Init,
filterBeadsEnv) for future use, but skip affected tests until the
upstream bd CLI bug is fixed.
Fixes: gt-lnn1xn
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>
Configure types.custom with Gas Town-specific types:
molecule, gate, convoy, merge-request, slot, agent, role, rig, event, message
These types are used by Gas Town infrastructure and will be removed from
beads core built-in types (bd-find4). This allows Gas Town to define its
own types while keeping beads core focused on work types.
Closes: bd-t5o8i
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>
Molecules are the LEDGER, not a task checklist. Each step closure
is a timestamped CV entry. Batch-closing corrupts the timeline.
Added explicit warnings to:
- molecules.md (first best practice)
- polecat-CLAUDE.md (new 🚨 section)
The discipline: mark in_progress BEFORE starting, closed IMMEDIATELY
after completing. Never batch-close at the end.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
