feat(statusline): lower max rigs to 3 and add alias support

- Add Alias field to RigEntry struct for short display names
- Limit displayed rigs to 3 (was unlimited, causing overflow)
- Use alias in statusline when configured (e.g., gcr instead of google_cookie_retrieval)
- Show +N overflow indicator when more rigs exist

Closes: hq-5j33zz

.beads/.gitignore

@@ -10,6 +10,7 @@ daemon.lock
 daemon.log
 daemon.pid
 bd.sock
+bd.sock.startlock
 sync-state.json
 last-touched
 

.beads/formulas/code-review.formula.toml

@@ -15,6 +15,8 @@ Each leg examines the code from a different perspective. Findings are
 collected and synthesized into a prioritized, actionable review.
 
 ## Legs (parallel execution)
+
+### Analysis Legs (read and analyze code)
 - **correctness**: Logic errors, bugs, edge cases
 - **performance**: Bottlenecks, efficiency issues
 - **security**: Vulnerabilities, OWASP concerns
@@ -23,6 +25,16 @@ collected and synthesized into a prioritized, actionable review.
 - **style**: Convention compliance, consistency
 - **smells**: Anti-patterns, technical debt
 
+### Verification Legs (check implementation quality)
+- **wiring**: Installed-but-not-wired gaps (deps added but not used)
+- **commit-discipline**: Commit quality and atomicity
+- **test-quality**: Test meaningfulness, not just coverage
+
+## Presets
+- **gate**: Light review for automatic flow (wiring, security, smells, test-quality)
+- **full**: Comprehensive review (all 10 legs)
+- **custom**: Select specific legs via --legs flag
+
 ## Execution Model
 1. Each leg spawns as a separate polecat
 2. Polecats work in parallel
@@ -293,6 +305,125 @@ Review the code for code smells and anti-patterns.
 - Is technical debt being added or paid down?
 """
 
+# ============================================================================
+# VERIFICATION LEGS - Check implementation quality (not just code analysis)
+# ============================================================================
+
+[[legs]]
+id = "wiring"
+title = "Wiring Review"
+focus = "Installed-but-not-wired gaps"
+description = """
+Detect dependencies, configs, or libraries that were added but not actually used.
+
+This catches subtle bugs where the implementer THINKS they integrated something,
+but the old implementation is still being used.
+
+**Look for:**
+- New dependency in manifest but never imported
+  - Go: module in go.mod but no import
+  - Rust: crate in Cargo.toml but no `use`
+  - Node: package in package.json but no import/require
+
+- SDK added but old implementation remains
+  - Added Sentry but still using console.error for errors
+  - Added Zod but still using manual typeof validation
+
+- Config/env var defined but never loaded
+  - New .env var that isn't accessed in code
+
+**Questions to answer:**
+- Is every new dependency actually used?
+- Are there old patterns that should have been replaced?
+- Is there dead config that suggests incomplete migration?
+"""
+
+[[legs]]
+id = "commit-discipline"
+title = "Commit Discipline Review"
+focus = "Commit quality and atomicity"
+description = """
+Review commit history for good practices.
+
+Good commits make the codebase easier to understand, bisect, and revert.
+
+**Look for:**
+- Giant "WIP" or "fix" commits
+  - Multiple unrelated changes in one commit
+  - Commits that touch 20+ files across different features
+
+- Poor commit messages
+  - "stuff", "update", "asdf", "fix"
+  - No context about WHY the change was made
+
+- Unatomic commits
+  - Feature + refactor + bugfix in same commit
+  - Should be separable logical units
+
+- Missing type prefixes (if project uses conventional commits)
+  - feat:, fix:, refactor:, test:, docs:, chore:
+
+**Questions to answer:**
+- Could this history be bisected effectively?
+- Would a reviewer understand the progression?
+- Are commits atomic (one logical change each)?
+"""
+
+[[legs]]
+id = "test-quality"
+title = "Test Quality Review"
+focus = "Test meaningfulness, not just coverage"
+description = """
+Verify tests are actually testing something meaningful.
+
+Coverage numbers lie. A test that can't fail provides no value.
+
+**Look for:**
+- Weak assertions
+  - Only checking != nil / !== null / is not None
+  - Using .is_ok() without checking the value
+  - assertTrue(true) or equivalent
+
+- Missing negative test cases
+  - Happy path only, no error cases
+  - No boundary testing
+  - No invalid input testing
+
+- Tests that can't fail
+  - Mocked so heavily the test is meaningless
+  - Testing implementation details, not behavior
+
+- Flaky test indicators
+  - Sleep/delay in tests
+  - Time-dependent assertions
+
+**Questions to answer:**
+- Do these tests actually verify behavior?
+- Would a bug in the implementation cause a test failure?
+- Are edge cases and error paths tested?
+"""
+
+# ============================================================================
+# PRESETS - Configurable leg selection
+# ============================================================================
+
+[presets]
+[presets.gate]
+description = "Light review for automatic flow - fast, focused on blockers"
+legs = ["wiring", "security", "smells", "test-quality"]
+
+[presets.full]
+description = "Comprehensive review - all legs, for major features"
+legs = ["correctness", "performance", "security", "elegance", "resilience", "style", "smells", "wiring", "commit-discipline", "test-quality"]
+
+[presets.security-focused]
+description = "Security-heavy review for sensitive changes"
+legs = ["security", "resilience", "correctness", "wiring"]
+
+[presets.refactor]
+description = "Review focused on code quality during refactoring"
+legs = ["elegance", "smells", "style", "commit-discipline"]
+
 # Synthesis step - combines all leg outputs
 [synthesis]
 title = "Review Synthesis"
@@ -310,10 +441,13 @@ A synthesized review at: {{.output.directory}}/{{.output.synthesis}}
 2. **Critical Issues** - P0 items from all legs, deduplicated
 3. **Major Issues** - P1 items, grouped by theme
 4. **Minor Issues** - P2 items, briefly listed
-5. **Positive Observations** - What's done well
-6. **Recommendations** - Actionable next steps
+5. **Wiring Gaps** - Dependencies added but not used (from wiring leg)
+6. **Commit Quality** - Notes on commit discipline
+7. **Test Quality** - Assessment of test meaningfulness
+8. **Positive Observations** - What's done well
+9. **Recommendations** - Actionable next steps
 
 Deduplicate issues found by multiple legs (note which legs found them).
 Prioritize by impact and effort. Be actionable.
 """
-depends_on = ["correctness", "performance", "security", "elegance", "resilience", "style", "smells"]
+depends_on = ["correctness", "performance", "security", "elegance", "resilience", "style", "smells", "wiring", "commit-discipline", "test-quality"]

.beads/formulas/gastown-release.formula.toml

@@ -47,7 +47,7 @@ Check all crew workspaces and the mayor rig:
 
 ```bash
 # Check each workspace
-for dir in ~/gt/gastown/crew/* ~/gt/gastown/mayor; do
+for dir in $GT_ROOT/gastown/crew/* $GT_ROOT/gastown/mayor; do
   if [ -d "$dir/.git" ] || [ -d "$dir" ]; then
     echo "=== Checking $dir ==="
     cd "$dir" 2>/dev/null || continue

.beads/formulas/mol-boot-triage.formula.toml

@@ -47,7 +47,7 @@ bd show hq-deacon 2>/dev/null
 gt feed --since 10m --plain | head -20
 
 # Recent wisps (operational state)
-ls -lt ~/gt/.beads-wisp/*.wisp.json 2>/dev/null | head -5
+ls -lt $GT_ROOT/.beads-wisp/*.wisp.json 2>/dev/null | head -5
 ```
 
 **Step 4: Check Deacon mail**
@@ -221,7 +221,7 @@ Then exit. The next daemon tick will spawn a fresh Boot.
 **Update status file**
 ```bash
 # The gt boot command handles this automatically
-# Status is written to ~/gt/deacon/dogs/boot/.boot-status.json
+# Status is written to $GT_ROOT/deacon/dogs/boot/.boot-status.json
 ```
 
 Boot is ephemeral by design. Each instance runs fresh.

.beads/formulas/mol-deacon-patrol.formula.toml

@@ -480,7 +480,7 @@ needs = ["zombie-scan"]
 description = """
 Execute registered plugins.
 
-Scan ~/gt/plugins/ for plugin directories. Each plugin has a plugin.md with TOML frontmatter defining its gate (when to run) and instructions (what to do).
+Scan $GT_ROOT/plugins/ for plugin directories. Each plugin has a plugin.md with TOML frontmatter defining its gate (when to run) and instructions (what to do).
 
 See docs/deacon-plugins.md for full documentation.
 
@@ -497,7 +497,7 @@ For each plugin:
 
 Plugins marked parallel: true can run concurrently using Task tool subagents. Sequential plugins run one at a time in directory order.
 
-Skip this step if ~/gt/plugins/ does not exist or is empty."""
+Skip this step if $GT_ROOT/plugins/ does not exist or is empty."""
 
 [[steps]]
 id = "dog-pool-maintenance"
@@ -665,59 +665,84 @@ Skip dispatch - system is healthy.
 
 [[steps]]
 id = "costs-digest"
-title = "Aggregate daily costs"
+title = "Aggregate daily costs [DISABLED]"
 needs = ["session-gc"]
 description = """
-**DAILY DIGEST** - Aggregate yesterday's session cost wisps.
+**⚠️ DISABLED** - Skip this step entirely.
 
-Session costs are recorded as ephemeral wisps (not exported to JSONL) to avoid
-log-in-database pollution. This step aggregates them into a permanent daily
-"Cost Report YYYY-MM-DD" bead for audit purposes.
+Cost tracking is temporarily disabled because Claude Code does not expose
+session costs in a way that can be captured programmatically.
+
+**Why disabled:**
+- The `gt costs` command uses tmux capture-pane to find costs
+- Claude Code displays costs in the TUI status bar, not in scrollback
+- All sessions show $0.00 because capture-pane can't see TUI chrome
+- The infrastructure is sound but has no data source
+
+**What we need from Claude Code:**
+- Stop hook env var (e.g., `$CLAUDE_SESSION_COST`)
+- Or queryable file/API endpoint
+
+**Re-enable when:** Claude Code exposes cost data via API or environment.
+
+See: GH#24, gt-7awfj
+
+**Exit criteria:** Skip this step - proceed to next."""
+
+[[steps]]
+id = "patrol-digest"
+title = "Aggregate daily patrol digests"
+needs = ["costs-digest"]
+description = """
+**DAILY DIGEST** - Aggregate yesterday's patrol cycle digests.
+
+Patrol cycles (Deacon, Witness, Refinery) create ephemeral per-cycle digests
+to avoid JSONL pollution. This step aggregates them into a single permanent
+"Patrol Report YYYY-MM-DD" bead for audit purposes.
 
 **Step 1: Check if digest is needed**
 ```bash
-# Preview yesterday's costs (dry run)
-gt costs digest --yesterday --dry-run
+# Preview yesterday's patrol digests (dry run)
+gt patrol digest --yesterday --dry-run
 ```
 
-If output shows "No session cost wisps found", skip to Step 3.
+If output shows "No patrol digests found", skip to Step 3.
 
 **Step 2: Create the digest**
 ```bash
-gt costs digest --yesterday
+gt patrol digest --yesterday
 ```
 
 This:
-- Queries all session.ended wisps from yesterday
-- Creates a single "Cost Report YYYY-MM-DD" bead with aggregated data
-- Deletes the source wisps
+- Queries all ephemeral patrol digests from yesterday
+- Creates a single "Patrol Report YYYY-MM-DD" bead with aggregated data
+- Deletes the source digests
 
 **Step 3: Verify**
-The digest appears in `gt costs --week` queries.
-Daily digests preserve audit trail without per-session pollution.
+Daily patrol digests preserve audit trail without per-cycle pollution.
 
 **Timing**: Run once per morning patrol cycle. The --yesterday flag ensures
 we don't try to digest today's incomplete data.
 
-**Exit criteria:** Yesterday's costs digested (or no wisps to digest)."""
+**Exit criteria:** Yesterday's patrol digests aggregated (or none to aggregate)."""
 
 [[steps]]
 id = "log-maintenance"
 title = "Rotate logs and prune state"
-needs = ["costs-digest"]
+needs = ["patrol-digest"]
 description = """
 Maintain daemon logs and state files.
 
 **Step 1: Check daemon.log size**
 ```bash
 # Get log file size
-ls -la ~/.beads/daemon*.log 2>/dev/null || ls -la ~/gt/.beads/daemon*.log 2>/dev/null
+ls -la ~/.beads/daemon*.log 2>/dev/null || ls -la $GT_ROOT/.beads/daemon*.log 2>/dev/null
 ```
 
 If daemon.log exceeds 10MB:
 ```bash
 # Rotate with date suffix and gzip
-LOGFILE="$HOME/gt/.beads/daemon.log"
+LOGFILE="$GT_ROOT/.beads/daemon.log"
 if [ -f "$LOGFILE" ] && [ $(stat -f%z "$LOGFILE" 2>/dev/null || stat -c%s "$LOGFILE") -gt 10485760 ]; then
     DATE=$(date +%Y-%m-%dT%H-%M-%S)
     mv "$LOGFILE" "${LOGFILE%.log}-${DATE}.log"
@@ -729,7 +754,7 @@ fi
 
 Clean up daemon logs older than 7 days:
 ```bash
-find ~/gt/.beads/ -name "daemon-*.log.gz" -mtime +7 -delete
+find $GT_ROOT/.beads/ -name "daemon-*.log.gz" -mtime +7 -delete
 ```
 
 **Step 3: Prune state.json of dead sessions**

.beads/formulas/mol-session-gc.formula.toml

@@ -246,5 +246,4 @@ Dog returns to available state in the pool.
 [vars]
 [vars.mode]
 description = "GC mode: 'conservative' or 'aggressive'"
-required = true
 default = "conservative"

.beads/formulas/mol-shutdown-dance.formula.toml

@@ -8,7 +8,7 @@ goroutine (NOT a Claude session) that runs the interrogation state machine.
 
 Dogs are lightweight workers in Boot's pool (see dog-pool-architecture.md):
 - Fixed pool of 5 goroutines (configurable via GT_DOG_POOL_SIZE)
-- State persisted to ~/gt/deacon/dogs/active/<id>.json
+- State persisted to $GT_ROOT/deacon/dogs/active/<id>.json
 - Recovery on Boot restart via orphan state files
 
 ## State Machine
@@ -151,7 +151,7 @@ If target doesn't exist:
 - Skip to EPITAPH with outcome=already_dead
 
 **3. Initialize state file:**
-Write initial state to ~/gt/deacon/dogs/active/{dog-id}.json
+Write initial state to $GT_ROOT/deacon/dogs/active/{dog-id}.json
 
 **4. Set initial attempt counter:**
 attempt = 1
@@ -477,11 +477,11 @@ bd close {warrant_id} --reason "{epitaph_summary}"
 
 **3. Move state file to completed:**
 ```bash
-mv ~/gt/deacon/dogs/active/{dog-id}.json ~/gt/deacon/dogs/completed/
+mv $GT_ROOT/deacon/dogs/active/{dog-id}.json $GT_ROOT/deacon/dogs/completed/
 ```
 
 **4. Report to Boot:**
-Write completion file: ~/gt/deacon/dogs/active/{dog-id}.done
+Write completion file: $GT_ROOT/deacon/dogs/active/{dog-id}.done
 ```json
 {
   "dog_id": "{dog-id}",

.beads/formulas/mol-town-shutdown.formula.toml

@@ -132,7 +132,7 @@ gt daemon rotate-logs
 gt doctor --fix
 ```
 
-Old logs are moved to `~/gt/logs/archive/` with timestamps.
+Old logs are moved to `$GT_ROOT/logs/archive/` with timestamps.
 """
 
 [[steps]]

.githooks/pre-push

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Block PRs by preventing pushes to arbitrary feature branches.
 # Gas Town agents push to main (crew) or polecat/* branches (polecats).
 # PRs are for external contributors only.
@@ -8,6 +8,11 @@
 #   polecat/*         - Polecat working branches (Refinery merges these)
 
 while read local_ref local_sha remote_ref remote_sha; do
+  # Skip tags - they're allowed for releases
+  if [[ "$remote_ref" == refs/tags/* ]]; then
+    continue
+  fi
+
   branch="${remote_ref#refs/heads/}"
 
   case "$branch" in
@@ -15,17 +20,22 @@ while read local_ref local_sha remote_ref remote_sha; do
       # Allowed branches
       ;;
     *)
-      echo "ERROR: Invalid branch for Gas Town agents."
-      echo ""
-      echo "Blocked push to: $branch"
-      echo ""
-      echo "Allowed branches:"
-      echo "  main        - Crew workers push here directly"
-      echo "  polecat/*   - Polecat working branches"
-      echo "  beads-sync  - Beads synchronization"
-      echo ""
-      echo "Do NOT create PRs. Push to main or let Refinery merge polecat work."
-      exit 1
+      # Allow feature branches when contributing to upstream (fork workflow).
+      # If an 'upstream' remote exists, this is a contribution setup where
+      # feature branches are needed for PRs. See: #848
+      if ! git remote get-url upstream &>/dev/null; then
+        echo "ERROR: Invalid branch for Gas Town agents."
+        echo ""
+        echo "Blocked push to: $branch"
+        echo ""
+        echo "Allowed branches:"
+        echo "  main        - Crew workers push here directly"
+        echo "  polecat/*   - Polecat working branches"
+        echo "  beads-sync  - Beads synchronization"
+        echo ""
+        echo "Do NOT create PRs. Push to main or let Refinery merge polecat work."
+        exit 1
+      fi
       ;;
   esac
 done

.github/workflows/block-internal-prs.yml

@@ -1,51 +0,0 @@
-name: Block Internal PRs
-
-on:
-  pull_request:
-    types: [opened, reopened]
-
-jobs:
-  block-internal-prs:
-    name: Block Internal PRs
-    # Only run if PR is from the same repo (not a fork)
-    if: github.event.pull_request.head.repo.full_name == github.repository
-    runs-on: ubuntu-latest
-    steps:
-      - name: Close PR and comment
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const prNumber = context.issue.number;
-            const branch = context.payload.pull_request.head.ref;
-
-            const body = [
-              '**Internal PRs are not allowed.**',
-              '',
-              'Gas Town agents push directly to main. PRs are for external contributors only.',
-              '',
-              'To land your changes:',
-              '```bash',
-              'git checkout main',
-              'git merge ' + branch,
-              'git push origin main',
-              'git push origin --delete ' + branch,
-              '```',
-              '',
-              'See CLAUDE.md: "Crew workers push directly to main. No feature branches. NEVER create PRs."'
-            ].join('\n');
-
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: prNumber,
-              body: body
-            });
-
-            await github.rest.pulls.update({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-              state: 'closed'
-            });
-
-            core.setFailed('Internal PR blocked. Push directly to main instead.');

.github/workflows/release.yml

@@ -60,15 +60,15 @@ jobs:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Update npm for OIDC trusted publishing
-        run: npm install -g npm@latest  # Requires npm >= 11.5.1 for trusted publishing
+      - name: Update npm for provenance support
+        run: npm install -g npm@latest
 
       - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           cd npm-package
-          npm publish --access public
-          # Uses OIDC trusted publishing - no token needed
-          # Provenance attestations are automatic with trusted publishing
+          npm publish --access public --provenance
 
   update-homebrew:
     runs-on: ubuntu-latest

.github/workflows/windows-ci.yml

@@ -0,0 +1,32 @@
+name: Windows CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Windows Build and Unit Tests
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "CI Bot"
+          git config --global user.email "ci@gastown.test"
+
+      - name: Build
+        run: go build -v ./cmd/gt
+
+      - name: Unit Tests
+        run: go test -short ./...

.gitignore

@@ -51,3 +51,10 @@ CLAUDE.md
 
 # Embedded formulas are committed so `go install @latest` works
 # Run `go generate ./...` after modifying .beads/formulas/
+
+# Gas Town (added by gt)
+.beads/
+.logs/
+logs/
+settings/
+.events.jsonl

.goreleaser.yml

@@ -164,7 +164,7 @@ release:
 
     **Homebrew (macOS/Linux):**
     ```bash
-    brew install steveyegge/gastown/gt
+    brew install gastown
     ```
 
     **npm (Node.js):**

CHANGELOG.md

@@ -7,18 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.0] - 2026-01-17
+## [0.5.0] - 2026-01-22
+
+### Added
+
+#### Mail Improvements
+- **Numeric index support for `gt mail read`** - Read messages by inbox position (e.g., `gt mail read 1`)
+- **`gt mail hook` alias** - Shortcut for `gt hook attach` from mail context
+- **`--body` alias for `--message`** - More intuitive flag in `gt mail send` and `gt mail reply`
+- **Multiple message IDs in delete** - `gt mail delete msg1 msg2 msg3`
+- **Positional message arg in reply** - `gt mail reply <id> "message"` without --message flag
+- **`--all` flag for inbox** - Show all messages including read
+- **Parallel inbox queries** - ~6x speedup for mail inbox
+
+#### Command Aliases
+- **`gt bd`** - Alias for `gt bead`
+- **`gt work`** - Alias for `gt hook`
+- **`--comment` alias for `--reason`** - In `gt close`
+- **`read` alias for `show`** - In `gt bead`
+
+#### Configuration & Agents
+- **OpenCode as built-in agent preset** - Configure with `gt config set agent opencode`
+- **Config-based role definition system** - Roles defined in config, not beads
+- **Env field in RuntimeConfig** - Custom environment variables for agent presets
+- **ShellQuote helper** - Safe env var escaping for shell commands
+
+#### Infrastructure
+- **Deacon status line display** - Shows deacon icon in mayor status line
+- **Configurable polecat branch naming** - Template-based branch naming
+- **Hook registry and install command** - Manage Claude Code hooks via `gt hooks`
+- **Doctor auto-fix capability** - SessionHookCheck can auto-repair
+- **`gt orphans kill` command** - Clean up orphaned Claude processes
+- **Zombie-scan command for deacon** - tmux-verified process cleanup
+- **Initial prompt for autonomous patrol startup** - Better agent priming
+
+#### Refinery & Merging
+- **Squash merge for cleaner history** - Eliminates redundant merge commits
+- **Redundant observers** - Witness and Refinery both watch convoys
 
 ### Fixed
 
-- **Orphan cleanup skips valid tmux sessions** - `gt orphans kill` and automatic orphan cleanup now check for Claude processes belonging to valid Gas Town tmux sessions (gt-*/hq-*) before killing. This prevents false kills of witnesses, refineries, and deacon during startup when they may temporarily show TTY "?"
+#### Crew & Session Stability
+- **Don't kill pane processes on new sessions** - Prevents destroying fresh shells
+- **Auto-recover from stale tmux pane references** - Recreates sessions automatically
+- **Preserve GT_AGENT across session restarts** - Handoff maintains identity
 
-## [0.3.1] - 2026-01-17
+#### Process Management
+- **KillPaneProcesses kills pane process itself** - Not just descendants
+- **Kill pane processes before all RespawnPane calls** - Prevents orphan leaks
+- **Shutdown reliability improvements** - Multiple fixes for clean shutdown
+- **Deacon spawns immediately after killing stuck session**
 
-### Fixed
+#### Convoy & Routing
+- **Pass convoy ID to convoy check command** - Correct ID propagation
+- **Multi-repo routing for custom types** - Correct beads routing across repos
+- **Normalize agent ID trailing slash** - Consistent ID handling
 
-- **Orphan cleanup on macOS** - Fixed TTY comparison (`??` vs `?`) so orphan detection works on macOS
-- **Session kill leaves orphans** - `gt done` and `gt crew stop` now use `KillSessionWithProcesses` to properly terminate all child processes before killing the tmux session
+#### Miscellaneous
+- **Sling auto-apply mol-polecat-work** - Auto-attach on open polecat beads
+- **Wisp orphan lifecycle bug** - Proper cleanup of abandoned wisps
+- **Misclassified wisp detection** - Defense-in-depth filtering
+- **Cross-account session access in seance** - Talk to predecessors across accounts
+- **Many more bug fixes** - See git log for full details
+
+## [0.4.0] - 2026-01-19
+
+_Changelog not documented at release time. See git log v0.3.1..v0.4.0 for changes._
+
+## [0.3.1] - 2026-01-18
+
+_Changelog not documented at release time. See git log v0.3.0..v0.3.1 for changes._
 
 ## [0.3.0] - 2026-01-17
 

Makefile

@@ -10,7 +10,8 @@ BUILD_TIME := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 LDFLAGS := -X github.com/steveyegge/gastown/internal/cmd.Version=$(VERSION) \
            -X github.com/steveyegge/gastown/internal/cmd.Commit=$(COMMIT) \
-           -X github.com/steveyegge/gastown/internal/cmd.BuildTime=$(BUILD_TIME)
+           -X github.com/steveyegge/gastown/internal/cmd.BuildTime=$(BUILD_TIME) \
+           -X github.com/steveyegge/gastown/internal/cmd.BuiltProperly=1
 
 generate:
 	go generate ./...
@@ -22,11 +23,8 @@ ifeq ($(shell uname),Darwin)
 	@echo "Signed $(BINARY) for macOS"
 endif
 
-install: build
-	cp $(BUILD_DIR)/$(BINARY) ~/.local/bin/$(BINARY)
-ifeq ($(shell uname),Darwin)
-	@codesign -s - -f ~/.local/bin/$(BINARY) 2>/dev/null || true
-endif
+install: generate
+	go install -ldflags "$(LDFLAGS)" ./cmd/gt
 
 clean:
 	rm -f $(BUILD_DIR)/$(BINARY)

README.md

@@ -97,9 +97,11 @@ Git-backed issue tracking system that stores work state as structured data.
 
 ```bash
 # Install Gas Town
-go install github.com/steveyegge/gastown/cmd/gt@latest
+$ brew install gastown                                    # Homebrew (recommended)
+$ npm install -g @gastown/gt                              # npm
+$ go install github.com/steveyegge/gastown/cmd/gt@latest  # From source
 
-# Add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)
+# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)
 export PATH="$PATH:$HOME/go/bin"
 
 # Create workspace with git initialization
@@ -120,11 +122,11 @@ gt mayor attach
 ## Quick Start Guide
 
 ### Getting Started
-Run 
+Run
 ```shell
-gt install ~/gt --git && 
-cd ~/gt && 
-gt config agent list && 
+gt install ~/gt --git &&
+cd ~/gt &&
+gt config agent list &&
 gt mayor attach
 ```
 and tell the Mayor what you want to build!

cmd/gt/build_test.go

@@ -0,0 +1,57 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"runtime"
+	"testing"
+)
+
+// TestCrossPlatformBuild verifies that the codebase compiles for all supported
+// platforms. This catches cases where platform-specific code (using build tags
+// like //go:build !windows) is called from platform-agnostic code without
+// providing stubs for all platforms.
+func TestCrossPlatformBuild(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping cross-platform build test in short mode")
+	}
+
+	// Skip if not running on a platform that can cross-compile
+	// (need Go toolchain, not just running tests)
+	if os.Getenv("CI") == "" && runtime.GOOS != "darwin" && runtime.GOOS != "linux" {
+		t.Skip("skipping cross-platform build test on unsupported platform")
+	}
+
+	platforms := []struct {
+		goos   string
+		goarch string
+		cgo    string
+	}{
+		{"linux", "amd64", "0"},
+		{"linux", "arm64", "0"},
+		{"darwin", "amd64", "0"},
+		{"darwin", "arm64", "0"},
+		{"windows", "amd64", "0"},
+		{"freebsd", "amd64", "0"},
+	}
+
+	for _, p := range platforms {
+		p := p // capture range variable
+		t.Run(p.goos+"_"+p.goarch, func(t *testing.T) {
+			t.Parallel()
+
+			cmd := exec.Command("go", "build", "-o", os.DevNull, ".")
+			cmd.Dir = "."
+			cmd.Env = append(os.Environ(),
+				"GOOS="+p.goos,
+				"GOARCH="+p.goarch,
+				"CGO_ENABLED="+p.cgo,
+			)
+
+			output, err := cmd.CombinedOutput()
+			if err != nil {
+				t.Errorf("build failed for %s/%s:\n%s", p.goos, p.goarch, string(output))
+			}
+		})
+	}
+}

docs/INSTALLING.md

@@ -44,8 +44,8 @@ sudo apt update
 sudo apt install -y git
 
 # Install Go (apt version may be outdated, use official installer)
-wget https://go.dev/dl/go1.24.linux-amd64.tar.gz
-sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.linux-amd64.tar.gz
+wget https://go.dev/dl/go1.24.12.linux-amd64.tar.gz
+sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.12.linux-amd64.tar.gz
 echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc
 source ~/.bashrc
 

docs/concepts/convoy.md

@@ -51,6 +51,7 @@ so you can see when it lands and what was included.
 |---------|-------------|-----|-------------|
 | **Convoy** | Yes | hq-cv-* | Tracking unit. What you create, track, get notified about. |
 | **Swarm** | No | None | Ephemeral. "The workers currently on this convoy's issues." |
+| **Stranded Convoy** | Yes | hq-cv-* | A convoy with ready work but no polecats assigned. Needs attention. |
 
 When you "kick off a swarm", you're really:
 1. Creating a convoy (the tracking unit)

docs/concepts/molecules.md

@@ -25,6 +25,7 @@ Protomolecule (frozen template) ─── Solid
 | **Molecule** | Active workflow instance with trackable steps |
 | **Wisp** | Ephemeral molecule for patrol cycles (never synced) |
 | **Digest** | Squashed summary of completed molecule |
+| **Shiny Workflow** | Canonical polecat formula: design → implement → review → test → submit |
 
 ## Common Mistake: Reading Formulas Directly
 

docs/reference.md

@@ -89,6 +89,58 @@ Debug routing: `BD_DEBUG_ROUTING=1 bd show <id>`
 
 Process state, PIDs, ephemeral data.
 
+### Rig-Level Configuration
+
+Rigs support layered configuration through:
+1. **Wisp layer** (`.beads-wisp/config/`) - transient, local overrides
+2. **Rig identity bead labels** - persistent rig settings
+3. **Town defaults** (`~/gt/settings/config.json`)
+4. **System defaults** - compiled-in fallbacks
+
+#### Polecat Branch Naming
+
+Configure custom branch name templates for polecats:
+
+```bash
+# Set via wisp (transient - for testing)
+echo '{"polecat_branch_template": "adam/{year}/{month}/{description}"}' > \
+  ~/gt/.beads-wisp/config/myrig.json
+
+# Or set via rig identity bead labels (persistent)
+bd update gt-rig-myrig --labels="polecat_branch_template:adam/{year}/{month}/{description}"
+```
+
+**Template Variables:**
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{user}` | From `git config user.name` | `adam` |
+| `{year}` | Current year (YY format) | `26` |
+| `{month}` | Current month (MM format) | `01` |
+| `{name}` | Polecat name | `alpha` |
+| `{issue}` | Issue ID without prefix | `123` (from `gt-123`) |
+| `{description}` | Sanitized issue title | `fix-auth-bug` |
+| `{timestamp}` | Unique timestamp | `1ks7f9a` |
+
+**Default Behavior (backward compatible):**
+
+When `polecat_branch_template` is empty or not set:
+- With issue: `polecat/{name}/{issue}@{timestamp}`
+- Without issue: `polecat/{name}-{timestamp}`
+
+**Example Configurations:**
+
+```bash
+# GitHub enterprise format
+"adam/{year}/{month}/{description}"
+
+# Simple feature branches
+"feature/{issue}"
+
+# Include polecat name for clarity
+"work/{name}/{issue}"
+```
+
 ## Formula Format
 
 ```toml
@@ -545,6 +597,24 @@ gt stop --all                # Kill all sessions
 gt stop --rig <name>         # Kill rig sessions
 ```
 
+### Health Check
+
+```bash
+gt deacon health-check <agent>   # Send health check ping, track response
+gt deacon health-state           # Show health check state for all agents
+```
+
+### Merge Queue (MQ)
+
+```bash
+gt mq list [rig]             # Show the merge queue
+gt mq next [rig]             # Show highest-priority merge request
+gt mq submit                 # Submit current branch to merge queue
+gt mq status <id>            # Show detailed merge request status
+gt mq retry <id>             # Retry a failed merge request
+gt mq reject <id>            # Reject a merge request
+```
+
 ## Beads Commands (bd)
 
 ```bash

internal/beads/beads.go

@@ -44,8 +44,8 @@ type Issue struct {
 
 	// Agent bead slots (type=agent only)
 	HookBead   string `json:"hook_bead,omitempty"`   // Current work attached to agent's hook
-	RoleBead   string `json:"role_bead,omitempty"`   // Role definition bead (shared)
 	AgentState string `json:"agent_state,omitempty"` // Agent lifecycle state (spawning, working, done, stuck)
+	// Note: role_bead field removed - role definitions are now config-based
 
 	// Counts from list output
 	DependencyCount int `json:"dependency_count,omitempty"`
@@ -114,6 +114,17 @@ type Beads struct {
 	workDir  string
 	beadsDir string // Optional BEADS_DIR override for cross-database access
 	isolated bool   // If true, suppress inherited beads env vars (for test isolation)
+
+	// Lazy-cached town root for routing resolution.
+	// Populated on first call to getTownRoot() to avoid filesystem walk on every operation.
+	townRoot     string
+	searchedRoot bool
+
+	// RPC client for daemon communication (lazy-initialized).
+	// When available, RPC is preferred over subprocess for performance.
+	rpcClient     *rpcClient
+	rpcChecked    bool
+	rpcAvailable  bool
 }
 
 // New creates a new Beads wrapper for the given directory.
@@ -144,6 +155,26 @@ func (b *Beads) getActor() string {
 	return os.Getenv("BD_ACTOR")
 }
 
+// getTownRoot returns the Gas Town root directory, using lazy caching.
+// The town root is found by walking up from workDir looking for mayor/town.json.
+// Returns empty string if not in a Gas Town project.
+func (b *Beads) getTownRoot() string {
+	if !b.searchedRoot {
+		b.townRoot = FindTownRoot(b.workDir)
+		b.searchedRoot = true
+	}
+	return b.townRoot
+}
+
+// getResolvedBeadsDir returns the beads directory this wrapper is operating on.
+// This follows any redirects and returns the actual beads directory path.
+func (b *Beads) getResolvedBeadsDir() string {
+	if b.beadsDir != "" {
+		return b.beadsDir
+	}
+	return ResolveBeadsDir(b.workDir)
+}
+
 // Init initializes a new beads database in the working directory.
 // This uses the same environment isolation as other commands.
 func (b *Beads) Init(prefix string) error {
@@ -262,7 +293,14 @@ func filterBeadsEnv(environ []string) []string {
 }
 
 // List returns issues matching the given options.
+// Uses daemon RPC when available for better performance (~40ms faster).
 func (b *Beads) List(opts ListOptions) ([]*Issue, error) {
+	// Try RPC first (faster when daemon is running)
+	if issues, err := b.listViaRPC(opts); err == nil {
+		return issues, nil
+	}
+
+	// Fall back to subprocess
 	args := []string{"list", "--json"}
 
 	if opts.Status != "" {
@@ -375,7 +413,14 @@ func (b *Beads) ReadyWithType(issueType string) ([]*Issue, error) {
 }
 
 // Show returns detailed information about an issue.
+// Uses daemon RPC when available for better performance (~40ms faster).
 func (b *Beads) Show(id string) (*Issue, error) {
+	// Try RPC first (faster when daemon is running)
+	if issue, err := b.showViaRPC(id); err == nil {
+		return issue, nil
+	}
+
+	// Fall back to subprocess
 	out, err := b.run("show", id, "--json")
 	if err != nil {
 		return nil, err
@@ -534,7 +579,14 @@ func (b *Beads) CreateWithID(id string, opts CreateOptions) (*Issue, error) {
 }
 
 // Update updates an existing issue.
+// Uses daemon RPC when available for better performance (~40ms faster).
 func (b *Beads) Update(id string, opts UpdateOptions) error {
+	// Try RPC first (faster when daemon is running)
+	if err := b.updateViaRPC(id, opts); err == nil {
+		return nil
+	}
+
+	// Fall back to subprocess
 	args := []string{"update", id}
 
 	if opts.Title != nil {
@@ -573,15 +625,26 @@ func (b *Beads) Update(id string, opts UpdateOptions) error {
 // Close closes one or more issues.
 // If a runtime session ID is set in the environment, it is passed to bd close
 // for work attribution tracking (see decision 009-session-events-architecture.md).
+// Uses daemon RPC when available for better performance (~40ms faster per call).
 func (b *Beads) Close(ids ...string) error {
 	if len(ids) == 0 {
 		return nil
 	}
 
+	sessionID := runtime.SessionIDFromEnv()
+
+	// Try RPC for single-issue closes (faster when daemon is running)
+	if len(ids) == 1 {
+		if err := b.closeViaRPC(ids[0], "", sessionID, false); err == nil {
+			return nil
+		}
+	}
+
+	// Fall back to subprocess
 	args := append([]string{"close"}, ids...)
 
 	// Pass session ID for work attribution if available
-	if sessionID := runtime.SessionIDFromEnv(); sessionID != "" {
+	if sessionID != "" {
 		args = append(args, "--session="+sessionID)
 	}
 
@@ -592,16 +655,51 @@ func (b *Beads) Close(ids ...string) error {
 // CloseWithReason closes one or more issues with a reason.
 // If a runtime session ID is set in the environment, it is passed to bd close
 // for work attribution tracking (see decision 009-session-events-architecture.md).
+// Uses daemon RPC when available for better performance (~40ms faster per call).
 func (b *Beads) CloseWithReason(reason string, ids ...string) error {
 	if len(ids) == 0 {
 		return nil
 	}
 
+	sessionID := runtime.SessionIDFromEnv()
+
+	// Try RPC for single-issue closes (faster when daemon is running)
+	if len(ids) == 1 {
+		if err := b.closeViaRPC(ids[0], reason, sessionID, false); err == nil {
+			return nil
+		}
+	}
+
+	// Fall back to subprocess
 	args := append([]string{"close"}, ids...)
 	args = append(args, "--reason="+reason)
 
 	// Pass session ID for work attribution if available
-	if sessionID := runtime.SessionIDFromEnv(); sessionID != "" {
+	if sessionID != "" {
+		args = append(args, "--session="+sessionID)
+	}
+
+	_, err := b.run(args...)
+	return err
+}
+
+// CloseForced closes an issue with force flag and optional reason.
+// The force flag bypasses blockers and other validation checks.
+// Uses daemon RPC when available for better performance (~40ms faster).
+func (b *Beads) CloseForced(id, reason string) error {
+	sessionID := runtime.SessionIDFromEnv()
+
+	// Try RPC first (faster when daemon is running)
+	if err := b.closeViaRPC(id, reason, sessionID, true); err == nil {
+		return nil
+	}
+
+	// Fall back to subprocess
+	args := []string{"close", id, "--force"}
+	if reason != "" {
+		args = append(args, "--reason="+reason)
+	}
+	if sessionID != "" {
 		args = append(args, "--session="+sessionID)
 	}
 
@@ -722,6 +820,7 @@ This is physics, not politeness. Gas Town is a steam engine - you are a piston.
 - ` + "`gt mol status`" + ` - Check your hooked work
 - ` + "`gt mail inbox`" + ` - Check for messages
 - ` + "`bd ready`" + ` - Find available work (no blockers)
+- ` + "`bd tree <id>`" + ` - View bead ancestry, siblings, and dependencies
 - ` + "`bd sync`" + ` - Sync beads changes
 
 ## Session Close Protocol
@@ -774,3 +873,19 @@ func ProvisionPrimeMDForWorktree(worktreePath string) error {
 	// Provision PRIME.md in the target directory
 	return ProvisionPrimeMD(beadsDir)
 }
+
+// GetPrimeContent returns the beads workflow context content.
+// It checks for a custom PRIME.md file first, otherwise returns the default.
+// This eliminates the need to spawn a bd subprocess for gt prime.
+func GetPrimeContent(workDir string) string {
+	beadsDir := ResolveBeadsDir(workDir)
+	primePath := filepath.Join(beadsDir, "PRIME.md")
+
+	// Check for custom PRIME.md
+	if content, err := os.ReadFile(primePath); err == nil {
+		return strings.TrimSpace(string(content))
+	}
+
+	// Return default content
+	return strings.TrimSpace(primeContent)
+}

internal/beads/beads_agent.go

@@ -5,9 +5,32 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"os/exec"
 	"strings"
 )
 
+// runSlotSet runs `bd slot set` from a specific directory.
+// This is needed when the agent bead was created via routing to a different
+// database than the Beads wrapper's default directory.
+func runSlotSet(workDir, beadID, slotName, slotValue string) error {
+	cmd := exec.Command("bd", "slot", "set", beadID, slotName, slotValue)
+	cmd.Dir = workDir
+	if output, err := cmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("%s: %w", strings.TrimSpace(string(output)), err)
+	}
+	return nil
+}
+
+// runSlotClear runs `bd slot clear` from a specific directory.
+func runSlotClear(workDir, beadID, slotName string) error {
+	cmd := exec.Command("bd", "slot", "clear", beadID, slotName)
+	cmd.Dir = workDir
+	if output, err := cmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("%s: %w", strings.TrimSpace(string(output)), err)
+	}
+	return nil
+}
+
 // AgentFields holds structured fields for agent beads.
 // These are stored as "key: value" lines in the description.
 type AgentFields struct {
@@ -15,10 +38,11 @@ type AgentFields struct {
 	Rig               string // Rig name (empty for global agents like mayor/deacon)
 	AgentState        string // spawning, working, done, stuck
 	HookBead          string // Currently pinned work bead ID
-	RoleBead          string // Role definition bead ID (canonical location; may not exist yet)
 	CleanupStatus     string // ZFC: polecat self-reports git state (clean, has_uncommitted, has_stash, has_unpushed)
 	ActiveMR          string // Currently active merge request bead ID (for traceability)
 	NotificationLevel string // DND mode: verbose, normal, muted (default: normal)
+	// Note: RoleBead field removed - role definitions are now config-based.
+	// See internal/config/roles/*.toml and config-based-roles.md.
 }
 
 // Notification level constants
@@ -53,11 +77,7 @@ func FormatAgentDescription(title string, fields *AgentFields) string {
 		lines = append(lines, "hook_bead: null")
 	}
 
-	if fields.RoleBead != "" {
-		lines = append(lines, fmt.Sprintf("role_bead: %s", fields.RoleBead))
-	} else {
-		lines = append(lines, "role_bead: null")
-	}
+	// Note: role_bead field no longer written - role definitions are config-based
 
 	if fields.CleanupStatus != "" {
 		lines = append(lines, fmt.Sprintf("cleanup_status: %s", fields.CleanupStatus))
@@ -111,7 +131,7 @@ func ParseAgentFields(description string) *AgentFields {
 		case "hook_bead":
 			fields.HookBead = value
 		case "role_bead":
-			fields.RoleBead = value
+			// Ignored - role definitions are now config-based (backward compat)
 		case "cleanup_status":
 			fields.CleanupStatus = value
 		case "active_mr":
@@ -128,7 +148,21 @@ func ParseAgentFields(description string) *AgentFields {
 // The ID format is: <prefix>-<rig>-<role>-<name> (e.g., gt-gastown-polecat-Toast)
 // Use AgentBeadID() helper to generate correct IDs.
 // The created_by field is populated from BD_ACTOR env var for provenance tracking.
+//
+// This function automatically ensures custom types are configured in the target
+// database before creating the bead. This handles multi-repo routing scenarios
+// where the bead may be routed to a different database than the one this wrapper
+// is connected to.
 func (b *Beads) CreateAgentBead(id, title string, fields *AgentFields) (*Issue, error) {
+	// Resolve where this bead will actually be written (handles multi-repo routing)
+	targetDir := ResolveRoutingTarget(b.getTownRoot(), id, b.getResolvedBeadsDir())
+
+	// Ensure target database has custom types configured
+	// This is cached (sentinel file + in-memory) so repeated calls are fast
+	if err := EnsureCustomTypes(targetDir); err != nil {
+		return nil, fmt.Errorf("prepare target for agent bead %s: %w", id, err)
+	}
+
 	description := FormatAgentDescription(title, fields)
 
 	args := []string{"create", "--json",
@@ -158,19 +192,14 @@ func (b *Beads) CreateAgentBead(id, title string, fields *AgentFields) (*Issue,
 		return nil, fmt.Errorf("parsing bd create output: %w", err)
 	}
 
-	// Set the role slot if specified (this is the authoritative storage)
-	if fields != nil && fields.RoleBead != "" {
-		if _, err := b.run("slot", "set", id, "role", fields.RoleBead); err != nil {
-			// Non-fatal: warn but continue
-			fmt.Printf("Warning: could not set role slot: %v\n", err)
-		}
-	}
+	// Note: role slot no longer set - role definitions are config-based
 
 	// Set the hook slot if specified (this is the authoritative storage)
 	// This fixes the slot inconsistency bug where bead status is 'hooked' but
 	// agent's hook slot is empty. See mi-619.
+	// Must run from targetDir since that's where the agent bead was created
 	if fields != nil && fields.HookBead != "" {
-		if _, err := b.run("slot", "set", id, "hook", fields.HookBead); err != nil {
+		if err := runSlotSet(targetDir, id, "hook", fields.HookBead); err != nil {
 			// Non-fatal: warn but continue - description text has the backup
 			fmt.Printf("Warning: could not set hook slot: %v\n", err)
 		}
@@ -204,6 +233,9 @@ func (b *Beads) CreateOrReopenAgentBead(id, title string, fields *AgentFields) (
 		return nil, err
 	}
 
+	// Resolve where this bead lives (for slot operations)
+	targetDir := ResolveRoutingTarget(b.getTownRoot(), id, b.getResolvedBeadsDir())
+
 	// The bead already exists (should be closed from previous polecat lifecycle)
 	// Reopen it and update its fields
 	if _, reopenErr := b.run("reopen", id, "--reason=re-spawning agent"); reopenErr != nil {
@@ -223,21 +255,17 @@ func (b *Beads) CreateOrReopenAgentBead(id, title string, fields *AgentFields) (
 		return nil, fmt.Errorf("updating reopened agent bead: %w", err)
 	}
 
-	// Set the role slot if specified
-	if fields != nil && fields.RoleBead != "" {
-		if _, err := b.run("slot", "set", id, "role", fields.RoleBead); err != nil {
-			// Non-fatal: warn but continue
-			fmt.Printf("Warning: could not set role slot: %v\n", err)
-		}
-	}
+	// Note: role slot no longer set - role definitions are config-based
 
 	// Clear any existing hook slot (handles stale state from previous lifecycle)
-	_, _ = b.run("slot", "clear", id, "hook")
+	// Must run from targetDir since that's where the agent bead lives
+	_ = runSlotClear(targetDir, id, "hook")
 
 	// Set the hook slot if specified
+	// Must run from targetDir since that's where the agent bead lives
 	if fields != nil && fields.HookBead != "" {
-		if _, err := b.run("slot", "set", id, "hook", fields.HookBead); err != nil {
-			// Non-fatal: warn but continue
+		if err := runSlotSet(targetDir, id, "hook", fields.HookBead); err != nil {
+			// Non-fatal: warn but continue - description text has the backup
 			fmt.Printf("Warning: could not set hook slot: %v\n", err)
 		}
 	}

internal/beads/beads_role.go

@@ -1,4 +1,11 @@
 // Package beads provides role bead management.
+//
+// DEPRECATED: Role beads are deprecated. Role definitions are now config-based.
+// See internal/config/roles/*.toml and config-based-roles.md for the new system.
+//
+// This file is kept for backward compatibility with existing role beads but
+// new code should use config.LoadRoleDefinition() instead of reading role beads.
+// The daemon no longer uses role beads as of Phase 2 (config-based roles).
 package beads
 
 import (
@@ -6,10 +13,12 @@ import (
 	"fmt"
 )
 
-// Role bead ID naming convention:
-// Role beads are stored in town beads (~/.beads/) with hq- prefix.
+// DEPRECATED: Role bead ID naming convention is no longer used.
+// Role definitions are now config-based (internal/config/roles/*.toml).
 //
-// Canonical format: hq-<role>-role
+// Role beads were stored in town beads (~/.beads/) with hq- prefix.
+//
+// Canonical format was: hq-<role>-role
 //
 // Examples:
 //   - hq-mayor-role
@@ -19,8 +28,8 @@ import (
 //   - hq-crew-role
 //   - hq-polecat-role
 //
-// Use RoleBeadIDTown() to get canonical role bead IDs.
-// The legacy RoleBeadID() function returns gt-<role>-role for backward compatibility.
+// Legacy functions RoleBeadID() and RoleBeadIDTown() still work for
+// backward compatibility but should not be used in new code.
 
 // RoleBeadID returns the role bead ID for a given role type.
 // Role beads define lifecycle configuration for each agent type.
@@ -67,6 +76,9 @@ func PolecatRoleBeadID() string {
 
 // GetRoleConfig looks up a role bead and returns its parsed RoleConfig.
 // Returns nil, nil if the role bead doesn't exist or has no config.
+//
+// Deprecated: Use config.LoadRoleDefinition() instead. Role definitions
+// are now config-based, not stored as beads.
 func (b *Beads) GetRoleConfig(roleBeadID string) (*RoleConfig, error) {
 	issue, err := b.Show(roleBeadID)
 	if err != nil {
@@ -94,7 +106,9 @@ func HasLabel(issue *Issue, label string) bool {
 }
 
 // RoleBeadDef defines a role bead's metadata.
-// Used by gt install and gt doctor to create missing role beads.
+//
+// Deprecated: Role beads are no longer created. Role definitions are
+// now config-based (internal/config/roles/*.toml).
 type RoleBeadDef struct {
 	ID    string // e.g., "hq-witness-role"
 	Title string // e.g., "Witness Role"
@@ -102,8 +116,9 @@ type RoleBeadDef struct {
 }
 
 // AllRoleBeadDefs returns all role bead definitions.
-// This is the single source of truth for role beads used by both
-// gt install (initial creation) and gt doctor --fix (repair).
+//
+// Deprecated: Role beads are no longer created by gt install or gt doctor.
+// This function is kept for backward compatibility only.
 func AllRoleBeadDefs() []RoleBeadDef {
 	return []RoleBeadDef{
 		{

internal/beads/beads_rpc.go

@@ -0,0 +1,330 @@
+package beads
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// MaxUnixSocketPath is the maximum length for Unix socket paths.
+const MaxUnixSocketPath = 103
+
+// rpcClient represents an RPC client for the bd daemon.
+type rpcClient struct {
+	conn       net.Conn
+	socketPath string
+	timeout    time.Duration
+	cwd        string
+}
+
+// rpcRequest represents an RPC request to the daemon.
+type rpcRequest struct {
+	Operation string          `json:"operation"`
+	Args      json.RawMessage `json:"args"`
+	Cwd       string          `json:"cwd,omitempty"`
+}
+
+// rpcResponse represents an RPC response from the daemon.
+type rpcResponse struct {
+	Success bool            `json:"success"`
+	Data    json.RawMessage `json:"data,omitempty"`
+	Error   string          `json:"error,omitempty"`
+}
+
+// tryConnectRPC attempts to connect to the bd daemon.
+// Returns nil if no daemon is running.
+func tryConnectRPC(workspacePath string) *rpcClient {
+	socketPath := socketPathForWorkspace(workspacePath)
+
+	// Check if socket exists
+	if _, err := os.Stat(socketPath); os.IsNotExist(err) {
+		return nil
+	}
+
+	conn, err := net.DialTimeout("unix", socketPath, 200*time.Millisecond)
+	if err != nil {
+		return nil
+	}
+
+	client := &rpcClient{
+		conn:       conn,
+		socketPath: socketPath,
+		timeout:    30 * time.Second,
+		cwd:        workspacePath,
+	}
+
+	// Quick health check
+	if err := client.ping(); err != nil {
+		_ = conn.Close()
+		return nil
+	}
+
+	return client
+}
+
+// close closes the RPC connection.
+func (c *rpcClient) close() error {
+	if c.conn != nil {
+		return c.conn.Close()
+	}
+	return nil
+}
+
+// execute sends a request and returns the response.
+func (c *rpcClient) execute(operation string, args interface{}) (*rpcResponse, error) {
+	argsJSON, err := json.Marshal(args)
+	if err != nil {
+		return nil, fmt.Errorf("marshaling args: %w", err)
+	}
+
+	req := rpcRequest{
+		Operation: operation,
+		Args:      argsJSON,
+		Cwd:       c.cwd,
+	}
+
+	reqJSON, err := json.Marshal(req)
+	if err != nil {
+		return nil, fmt.Errorf("marshaling request: %w", err)
+	}
+
+	if c.timeout > 0 {
+		deadline := time.Now().Add(c.timeout)
+		if err := c.conn.SetDeadline(deadline); err != nil {
+			return nil, fmt.Errorf("setting deadline: %w", err)
+		}
+	}
+
+	writer := bufio.NewWriter(c.conn)
+	if _, err := writer.Write(reqJSON); err != nil {
+		return nil, fmt.Errorf("writing request: %w", err)
+	}
+	if err := writer.WriteByte('\n'); err != nil {
+		return nil, fmt.Errorf("writing newline: %w", err)
+	}
+	if err := writer.Flush(); err != nil {
+		return nil, fmt.Errorf("flushing: %w", err)
+	}
+
+	reader := bufio.NewReader(c.conn)
+	respLine, err := reader.ReadBytes('\n')
+	if err != nil {
+		return nil, fmt.Errorf("reading response: %w", err)
+	}
+
+	var resp rpcResponse
+	if err := json.Unmarshal(respLine, &resp); err != nil {
+		return nil, fmt.Errorf("unmarshaling response: %w", err)
+	}
+
+	if !resp.Success {
+		return &resp, fmt.Errorf("operation failed: %s", resp.Error)
+	}
+
+	return &resp, nil
+}
+
+// ping verifies the daemon is alive.
+func (c *rpcClient) ping() error {
+	_, err := c.execute("ping", nil)
+	return err
+}
+
+// socketPathForWorkspace returns the socket path for a workspace.
+// This mirrors the logic in beads/internal/rpc/socket_path.go.
+func socketPathForWorkspace(workspacePath string) string {
+	// Compute the "natural" socket path in .beads/
+	naturalPath := filepath.Join(workspacePath, ".beads", "bd.sock")
+
+	// If natural path is short enough, use it
+	if len(naturalPath) <= MaxUnixSocketPath {
+		return naturalPath
+	}
+
+	// Path too long - use /tmp with hash
+	hash := sha256.Sum256([]byte(workspacePath))
+	hashStr := hex.EncodeToString(hash[:4])
+	return filepath.Join("/tmp", "beads-"+hashStr, "bd.sock")
+}
+
+// getRPCClient returns the RPC client, initializing on first call.
+// Returns nil if daemon is not available.
+func (b *Beads) getRPCClient() *rpcClient {
+	if b.rpcChecked {
+		return b.rpcClient
+	}
+
+	b.rpcChecked = true
+
+	// Don't use RPC in isolated mode (tests)
+	if b.isolated {
+		return nil
+	}
+
+	// Resolve workspace path for socket discovery
+	workspacePath := b.beadsDir
+	if workspacePath == "" {
+		workspacePath = ResolveBeadsDir(b.workDir)
+	}
+
+	// Get the workspace root (parent of .beads)
+	if filepath.Base(workspacePath) == ".beads" {
+		workspacePath = filepath.Dir(workspacePath)
+	}
+
+	b.rpcClient = tryConnectRPC(workspacePath)
+	b.rpcAvailable = b.rpcClient != nil
+	return b.rpcClient
+}
+
+// closeRPC closes the RPC client if connected.
+func (b *Beads) closeRPC() {
+	if b.rpcClient != nil {
+		_ = b.rpcClient.close()
+		b.rpcClient = nil
+	}
+}
+
+// RPC operation argument types
+
+type rpcListArgs struct {
+	Status        string   `json:"status,omitempty"`
+	Assignee      string   `json:"assignee,omitempty"`
+	Labels        []string `json:"labels,omitempty"`
+	LabelsAny     []string `json:"labels_any,omitempty"`
+	ExcludeStatus []string `json:"exclude_status,omitempty"`
+	Priority      *int     `json:"priority,omitempty"`
+	ParentID      string   `json:"parent_id,omitempty"`
+	NoAssignee    bool     `json:"no_assignee,omitempty"`
+	Limit         int      `json:"limit,omitempty"`
+}
+
+type rpcShowArgs struct {
+	ID string `json:"id"`
+}
+
+type rpcUpdateArgs struct {
+	ID           string   `json:"id"`
+	Title        *string  `json:"title,omitempty"`
+	Status       *string  `json:"status,omitempty"`
+	Priority     *int     `json:"priority,omitempty"`
+	Description  *string  `json:"description,omitempty"`
+	Assignee     *string  `json:"assignee,omitempty"`
+	AddLabels    []string `json:"add_labels,omitempty"`
+	RemoveLabels []string `json:"remove_labels,omitempty"`
+	SetLabels    []string `json:"set_labels,omitempty"`
+}
+
+type rpcCloseArgs struct {
+	ID      string `json:"id"`
+	Reason  string `json:"reason,omitempty"`
+	Session string `json:"session,omitempty"`
+	Force   bool   `json:"force,omitempty"`
+}
+
+// listViaRPC performs a list operation via the daemon RPC.
+func (b *Beads) listViaRPC(opts ListOptions) ([]*Issue, error) {
+	client := b.getRPCClient()
+	if client == nil {
+		return nil, fmt.Errorf("no RPC client")
+	}
+
+	args := rpcListArgs{
+		Status:   opts.Status,
+		Assignee: opts.Assignee,
+		ParentID: opts.Parent,
+	}
+
+	// Convert Label to Labels array if set
+	if opts.Label != "" {
+		args.Labels = []string{opts.Label}
+	}
+
+	// Handle priority: -1 means no filter
+	if opts.Priority >= 0 {
+		args.Priority = &opts.Priority
+	}
+
+	if opts.NoAssignee {
+		args.NoAssignee = true
+	}
+
+	resp, err := client.execute("list", args)
+	if err != nil {
+		return nil, err
+	}
+
+	var issues []*Issue
+	if err := json.Unmarshal(resp.Data, &issues); err != nil {
+		return nil, fmt.Errorf("unmarshaling issues: %w", err)
+	}
+
+	return issues, nil
+}
+
+// showViaRPC performs a show operation via the daemon RPC.
+func (b *Beads) showViaRPC(id string) (*Issue, error) {
+	client := b.getRPCClient()
+	if client == nil {
+		return nil, fmt.Errorf("no RPC client")
+	}
+
+	resp, err := client.execute("show", rpcShowArgs{ID: id})
+	if err != nil {
+		return nil, err
+	}
+
+	var issue Issue
+	if err := json.Unmarshal(resp.Data, &issue); err != nil {
+		return nil, fmt.Errorf("unmarshaling issue: %w", err)
+	}
+
+	return &issue, nil
+}
+
+// updateViaRPC performs an update operation via the daemon RPC.
+func (b *Beads) updateViaRPC(id string, opts UpdateOptions) error {
+	client := b.getRPCClient()
+	if client == nil {
+		return fmt.Errorf("no RPC client")
+	}
+
+	args := rpcUpdateArgs{
+		ID:           id,
+		Title:        opts.Title,
+		Status:       opts.Status,
+		Priority:     opts.Priority,
+		Description:  opts.Description,
+		Assignee:     opts.Assignee,
+		AddLabels:    opts.AddLabels,
+		RemoveLabels: opts.RemoveLabels,
+		SetLabels:    opts.SetLabels,
+	}
+
+	_, err := client.execute("update", args)
+	return err
+}
+
+// closeViaRPC performs a close operation via the daemon RPC.
+func (b *Beads) closeViaRPC(id, reason, session string, force bool) error {
+	client := b.getRPCClient()
+	if client == nil {
+		return fmt.Errorf("no RPC client")
+	}
+
+	args := rpcCloseArgs{
+		ID:      id,
+		Reason:  reason,
+		Session: session,
+		Force:   force,
+	}
+
+	_, err := client.execute("close", args)
+	return err
+}

internal/beads/beads_test.go

@@ -1972,7 +1972,6 @@ func TestCreateOrReopenAgentBead_ClosedBead(t *testing.T) {
 		Rig:        "testrig",
 		AgentState: "spawning",
 		HookBead:   "test-task-1",
-		RoleBead:   "test-polecat-role",
 	})
 	if err != nil {
 		t.Fatalf("Spawn 1 - CreateOrReopenAgentBead: %v", err)
@@ -1993,7 +1992,6 @@ func TestCreateOrReopenAgentBead_ClosedBead(t *testing.T) {
 		Rig:        "testrig",
 		AgentState: "spawning",
 		HookBead:   "test-task-2", // Different task
-		RoleBead:   "test-polecat-role",
 	})
 	if err != nil {
 		t.Fatalf("Spawn 2 - CreateOrReopenAgentBead: %v", err)
@@ -2020,7 +2018,6 @@ func TestCreateOrReopenAgentBead_ClosedBead(t *testing.T) {
 		Rig:        "testrig",
 		AgentState: "spawning",
 		HookBead:   "test-task-3",
-		RoleBead:   "test-polecat-role",
 	})
 	if err != nil {
 		t.Fatalf("Spawn 3 - CreateOrReopenAgentBead: %v", err)
@@ -2059,7 +2056,6 @@ func TestCloseAndClearAgentBead_FieldClearing(t *testing.T) {
 				Rig:               "testrig",
 				AgentState:        "running",
 				HookBead:          "test-issue-123",
-				RoleBead:          "test-polecat-role",
 				CleanupStatus:     "clean",
 				ActiveMR:          "test-mr-456",
 				NotificationLevel: "normal",
@@ -2279,7 +2275,6 @@ func TestCloseAndClearAgentBead_ReopenHasCleanState(t *testing.T) {
 		Rig:               "testrig",
 		AgentState:        "running",
 		HookBead:          "test-old-issue",
-		RoleBead:          "test-polecat-role",
 		CleanupStatus:     "clean",
 		ActiveMR:          "test-old-mr",
 		NotificationLevel: "normal",
@@ -2300,7 +2295,6 @@ func TestCloseAndClearAgentBead_ReopenHasCleanState(t *testing.T) {
 		Rig:        "testrig",
 		AgentState: "spawning",
 		HookBead:   "test-new-issue",
-		RoleBead:   "test-polecat-role",
 	})
 	if err != nil {
 		t.Fatalf("CreateOrReopenAgentBead: %v", err)

internal/beads/beads_types.go

@@ -0,0 +1,131 @@
+// Package beads provides custom type management for agent beads.
+package beads
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+
+	"github.com/steveyegge/gastown/internal/constants"
+)
+
+// typesSentinel is a marker file indicating custom types have been configured.
+// This persists across CLI invocations to avoid redundant bd config calls.
+const typesSentinel = ".gt-types-configured"
+
+// ensuredDirs tracks which beads directories have been ensured this session.
+// This provides fast in-memory caching for multiple creates in the same CLI run.
+var (
+	ensuredDirs = make(map[string]bool)
+	ensuredMu   sync.Mutex
+)
+
+// FindTownRoot walks up from startDir to find the Gas Town root directory.
+// The town root is identified by the presence of mayor/town.json.
+// Returns empty string if not found (reached filesystem root).
+func FindTownRoot(startDir string) string {
+	dir := startDir
+	for {
+		townFile := filepath.Join(dir, "mayor", "town.json")
+		if _, err := os.Stat(townFile); err == nil {
+			return dir
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			return "" // Reached filesystem root
+		}
+		dir = parent
+	}
+}
+
+// ResolveRoutingTarget determines which beads directory a bead ID will route to.
+// It extracts the prefix from the bead ID and looks up the corresponding route.
+// Returns the resolved beads directory path, following any redirects.
+//
+// If townRoot is empty or prefix is not found, falls back to the provided fallbackDir.
+func ResolveRoutingTarget(townRoot, beadID, fallbackDir string) string {
+	if townRoot == "" {
+		return fallbackDir
+	}
+
+	// Extract prefix from bead ID (e.g., "gt-gastown-polecat-Toast" -> "gt-")
+	prefix := ExtractPrefix(beadID)
+	if prefix == "" {
+		return fallbackDir
+	}
+
+	// Look up rig path for this prefix
+	rigPath := GetRigPathForPrefix(townRoot, prefix)
+	if rigPath == "" {
+		return fallbackDir
+	}
+
+	// Resolve redirects and get final beads directory
+	beadsDir := ResolveBeadsDir(rigPath)
+	if beadsDir == "" {
+		return fallbackDir
+	}
+
+	return beadsDir
+}
+
+// EnsureCustomTypes ensures the target beads directory has custom types configured.
+// Uses a two-level caching strategy:
+//   - In-memory cache for multiple creates in the same CLI invocation
+//   - Sentinel file on disk for persistence across CLI invocations
+//
+// This function is thread-safe and idempotent.
+func EnsureCustomTypes(beadsDir string) error {
+	if beadsDir == "" {
+		return fmt.Errorf("empty beads directory")
+	}
+
+	ensuredMu.Lock()
+	defer ensuredMu.Unlock()
+
+	// Fast path: in-memory cache (same CLI invocation)
+	if ensuredDirs[beadsDir] {
+		return nil
+	}
+
+	// Fast path: sentinel file exists (previous CLI invocation)
+	sentinelPath := filepath.Join(beadsDir, typesSentinel)
+	if _, err := os.Stat(sentinelPath); err == nil {
+		ensuredDirs[beadsDir] = true
+		return nil
+	}
+
+	// Verify beads directory exists
+	if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
+		return fmt.Errorf("beads directory does not exist: %s", beadsDir)
+	}
+
+	// Configure custom types via bd CLI
+	typesList := strings.Join(constants.BeadsCustomTypesList(), ",")
+	cmd := exec.Command("bd", "config", "set", "types.custom", typesList)
+	cmd.Dir = beadsDir
+	// Set BEADS_DIR explicitly to ensure bd operates on the correct database
+	cmd.Env = append(os.Environ(), "BEADS_DIR="+beadsDir)
+	if output, err := cmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("configure custom types in %s: %s: %w",
+			beadsDir, strings.TrimSpace(string(output)), err)
+	}
+
+	// Write sentinel file (best effort - don't fail if this fails)
+	// The sentinel contains a version marker for future compatibility
+	_ = os.WriteFile(sentinelPath, []byte("v1\n"), 0644)
+
+	ensuredDirs[beadsDir] = true
+	return nil
+}
+
+// ResetEnsuredDirs clears the in-memory cache of ensured directories.
+// This is primarily useful for testing.
+func ResetEnsuredDirs() {
+	ensuredMu.Lock()
+	defer ensuredMu.Unlock()
+	ensuredDirs = make(map[string]bool)
+}

internal/beads/beads_types_test.go

@@ -0,0 +1,234 @@
+package beads
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestFindTownRoot(t *testing.T) {
+	// Create a temporary town structure
+	tmpDir := t.TempDir()
+	mayorDir := filepath.Join(tmpDir, "mayor")
+	if err := os.MkdirAll(mayorDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(mayorDir, "town.json"), []byte("{}"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create nested directories
+	deepDir := filepath.Join(tmpDir, "rig1", "crew", "worker1")
+	if err := os.MkdirAll(deepDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	tests := []struct {
+		name     string
+		startDir string
+		expected string
+	}{
+		{"from town root", tmpDir, tmpDir},
+		{"from mayor dir", mayorDir, tmpDir},
+		{"from deep nested dir", deepDir, tmpDir},
+		{"from non-town dir", t.TempDir(), ""},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := FindTownRoot(tc.startDir)
+			if result != tc.expected {
+				t.Errorf("FindTownRoot(%q) = %q, want %q", tc.startDir, result, tc.expected)
+			}
+		})
+	}
+}
+
+func TestResolveRoutingTarget(t *testing.T) {
+	// Create a temporary town with routes
+	tmpDir := t.TempDir()
+	beadsDir := filepath.Join(tmpDir, ".beads")
+	if err := os.MkdirAll(beadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create mayor/town.json for FindTownRoot
+	mayorDir := filepath.Join(tmpDir, "mayor")
+	if err := os.MkdirAll(mayorDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(mayorDir, "town.json"), []byte("{}"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create routes.jsonl
+	routesContent := `{"prefix": "gt-", "path": "gastown/mayor/rig"}
+{"prefix": "hq-", "path": "."}
+`
+	if err := os.WriteFile(filepath.Join(beadsDir, "routes.jsonl"), []byte(routesContent), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create the rig beads directory
+	rigBeadsDir := filepath.Join(tmpDir, "gastown", "mayor", "rig", ".beads")
+	if err := os.MkdirAll(rigBeadsDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	fallback := "/fallback/.beads"
+
+	tests := []struct {
+		name     string
+		townRoot string
+		beadID   string
+		expected string
+	}{
+		{
+			name:     "rig-level bead routes to rig",
+			townRoot: tmpDir,
+			beadID:   "gt-gastown-polecat-Toast",
+			expected: rigBeadsDir,
+		},
+		{
+			name:     "town-level bead routes to town",
+			townRoot: tmpDir,
+			beadID:   "hq-mayor",
+			expected: beadsDir,
+		},
+		{
+			name:     "unknown prefix falls back",
+			townRoot: tmpDir,
+			beadID:   "xx-unknown",
+			expected: fallback,
+		},
+		{
+			name:     "empty townRoot falls back",
+			townRoot: "",
+			beadID:   "gt-gastown-polecat-Toast",
+			expected: fallback,
+		},
+		{
+			name:     "no prefix falls back",
+			townRoot: tmpDir,
+			beadID:   "noprefixid",
+			expected: fallback,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := ResolveRoutingTarget(tc.townRoot, tc.beadID, fallback)
+			if result != tc.expected {
+				t.Errorf("ResolveRoutingTarget(%q, %q, %q) = %q, want %q",
+					tc.townRoot, tc.beadID, fallback, result, tc.expected)
+			}
+		})
+	}
+}
+
+func TestEnsureCustomTypes(t *testing.T) {
+	// Reset the in-memory cache before testing
+	ResetEnsuredDirs()
+
+	t.Run("empty beads dir returns error", func(t *testing.T) {
+		err := EnsureCustomTypes("")
+		if err == nil {
+			t.Error("expected error for empty beads dir")
+		}
+	})
+
+	t.Run("non-existent beads dir returns error", func(t *testing.T) {
+		err := EnsureCustomTypes("/nonexistent/path/.beads")
+		if err == nil {
+			t.Error("expected error for non-existent beads dir")
+		}
+	})
+
+	t.Run("sentinel file triggers cache hit", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create sentinel file
+		sentinelPath := filepath.Join(beadsDir, typesSentinel)
+		if err := os.WriteFile(sentinelPath, []byte("v1\n"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		// Reset cache to ensure we're testing sentinel detection
+		ResetEnsuredDirs()
+
+		// This should succeed without running bd (sentinel exists)
+		err := EnsureCustomTypes(beadsDir)
+		if err != nil {
+			t.Errorf("expected success with sentinel file, got: %v", err)
+		}
+	})
+
+	t.Run("in-memory cache prevents repeated calls", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		beadsDir := filepath.Join(tmpDir, ".beads")
+		if err := os.MkdirAll(beadsDir, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		// Create sentinel to avoid bd call
+		sentinelPath := filepath.Join(beadsDir, typesSentinel)
+		if err := os.WriteFile(sentinelPath, []byte("v1\n"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		ResetEnsuredDirs()
+
+		// First call
+		if err := EnsureCustomTypes(beadsDir); err != nil {
+			t.Fatal(err)
+		}
+
+		// Remove sentinel - second call should still succeed due to in-memory cache
+		os.Remove(sentinelPath)
+
+		if err := EnsureCustomTypes(beadsDir); err != nil {
+			t.Errorf("expected cache hit, got: %v", err)
+		}
+	})
+}
+
+func TestBeads_getTownRoot(t *testing.T) {
+	// Create a temporary town
+	tmpDir := t.TempDir()
+	mayorDir := filepath.Join(tmpDir, "mayor")
+	if err := os.MkdirAll(mayorDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(mayorDir, "town.json"), []byte("{}"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Create nested directory
+	rigDir := filepath.Join(tmpDir, "myrig", "mayor", "rig")
+	if err := os.MkdirAll(rigDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	b := New(rigDir)
+
+	// First call should find town root
+	root1 := b.getTownRoot()
+	if root1 != tmpDir {
+		t.Errorf("first getTownRoot() = %q, want %q", root1, tmpDir)
+	}
+
+	// Second call should return cached value
+	root2 := b.getTownRoot()
+	if root2 != root1 {
+		t.Errorf("second getTownRoot() = %q, want cached %q", root2, root1)
+	}
+
+	// Verify searchedRoot flag is set
+	if !b.searchedRoot {
+		t.Error("expected searchedRoot to be true after getTownRoot()")
+	}
+}

internal/beads/handoff.go

@@ -158,6 +158,7 @@ func (b *Beads) AttachMolecule(pinnedBeadID, moleculeID string) (*Issue, error)
 		return nil, fmt.Errorf("fetching pinned bead: %w", err)
 	}
 
+	// Only allow pinned beads (permanent records like role definitions)
 	if issue.Status != StatusPinned {
 		return nil, fmt.Errorf("issue %s is not pinned (status: %s)", pinnedBeadID, issue.Status)
 	}

internal/boot/boot.go

@@ -160,9 +160,10 @@ func (b *Boot) Spawn(agentOverride string) error {
 
 // spawnTmux spawns Boot in a tmux session.
 func (b *Boot) spawnTmux(agentOverride string) error {
-	// Kill any stale session first
+	// Kill any stale session first.
+	// Use KillSessionWithProcesses to ensure all descendant processes are killed.
 	if b.IsSessionAlive() {
-		_ = b.tmux.KillSession(SessionName)
+		_ = b.tmux.KillSessionWithProcesses(SessionName)
 	}
 
 	// Ensure boot directory exists (it should have CLAUDE.md with Boot context)

internal/claude/config/settings-autonomous.json

@@ -1,15 +1,45 @@
 {
+  "editorMode": "normal",
   "enabledPlugins": {
     "beads@beads-marketplace": false
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash(gh pr create*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$PATH\" && gt tap guard pr-workflow"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git checkout -b*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$PATH\" && gt tap guard pr-workflow"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git switch -c*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$PATH\" && gt tap guard pr-workflow"
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "",
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime && gt mail check --inject && gt nudge deacon session-started"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime --hook && gt mail check --inject && gt nudge deacon session-started"
           }
         ]
       }
@@ -20,7 +50,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime --hook"
           }
         ]
       }
@@ -35,17 +65,6 @@
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt costs record"
-          }
-        ]
-      }
     ]
   }
 }

internal/claude/config/settings-interactive.json

@@ -1,15 +1,45 @@
 {
+  "editorMode": "normal",
   "enabledPlugins": {
     "beads@beads-marketplace": false
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash(gh pr create*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$PATH\" && gt tap guard pr-workflow"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git checkout -b*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$PATH\" && gt tap guard pr-workflow"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git switch -c*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "export PATH=\"$HOME/go/bin:$HOME/.local/bin:$PATH\" && gt tap guard pr-workflow"
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "",
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime && gt nudge deacon session-started"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime --hook && gt nudge deacon session-started"
           }
         ]
       }
@@ -20,7 +50,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime"
+            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt prime --hook"
           }
         ]
       }
@@ -35,17 +65,6 @@
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "export PATH=\"$HOME/go/bin:$HOME/bin:$PATH\" && gt costs record"
-          }
-        ]
-      }
     ]
   }
 }

internal/cmd/account_test.go

@@ -3,6 +3,8 @@ package cmd
 import (
 	"os"
 	"path/filepath"
+	"runtime"
+	"strings"
 	"testing"
 	"time"
 
@@ -54,15 +56,33 @@ func setupTestTownForAccount(t *testing.T) (townRoot string, accountsDir string)
 	return townRoot, accountsDir
 }
 
+func setTestHome(t *testing.T, fakeHome string) {
+	t.Helper()
+
+	t.Setenv("HOME", fakeHome)
+
+	if runtime.GOOS != "windows" {
+		return
+	}
+
+	t.Setenv("USERPROFILE", fakeHome)
+
+	drive := filepath.VolumeName(fakeHome)
+	if drive == "" {
+		return
+	}
+
+	t.Setenv("HOMEDRIVE", drive)
+	t.Setenv("HOMEPATH", strings.TrimPrefix(fakeHome, drive))
+}
+
 func TestAccountSwitch(t *testing.T) {
 	t.Run("switch between accounts", func(t *testing.T) {
 		townRoot, accountsDir := setupTestTownForAccount(t)
 
 		// Create fake home directory for ~/.claude
 		fakeHome := t.TempDir()
-		originalHome := os.Getenv("HOME")
-		os.Setenv("HOME", fakeHome)
-		defer os.Setenv("HOME", originalHome)
+		setTestHome(t, fakeHome)
 
 		// Create account config directories
 		workConfigDir := filepath.Join(accountsDir, "work")
@@ -133,9 +153,7 @@ func TestAccountSwitch(t *testing.T) {
 		townRoot, accountsDir := setupTestTownForAccount(t)
 
 		fakeHome := t.TempDir()
-		originalHome := os.Getenv("HOME")
-		os.Setenv("HOME", fakeHome)
-		defer os.Setenv("HOME", originalHome)
+		setTestHome(t, fakeHome)
 
 		workConfigDir := filepath.Join(accountsDir, "work")
 		if err := os.MkdirAll(workConfigDir, 0755); err != nil {
@@ -186,9 +204,7 @@ func TestAccountSwitch(t *testing.T) {
 		townRoot, accountsDir := setupTestTownForAccount(t)
 
 		fakeHome := t.TempDir()
-		originalHome := os.Getenv("HOME")
-		os.Setenv("HOME", fakeHome)
-		defer os.Setenv("HOME", originalHome)
+		setTestHome(t, fakeHome)
 
 		workConfigDir := filepath.Join(accountsDir, "work")
 		if err := os.MkdirAll(workConfigDir, 0755); err != nil {
@@ -224,9 +240,7 @@ func TestAccountSwitch(t *testing.T) {
 		townRoot, accountsDir := setupTestTownForAccount(t)
 
 		fakeHome := t.TempDir()
-		originalHome := os.Getenv("HOME")
-		os.Setenv("HOME", fakeHome)
-		defer os.Setenv("HOME", originalHome)
+		setTestHome(t, fakeHome)
 
 		workConfigDir := filepath.Join(accountsDir, "work")
 		personalConfigDir := filepath.Join(accountsDir, "personal")

internal/cmd/attention.go

@@ -0,0 +1,374 @@
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/workspace"
+)
+
+var attentionJSON bool
+var attentionAll bool
+
+var attentionCmd = &cobra.Command{
+	Use:     "attention",
+	GroupID: GroupWork,
+	Short:   "Show items requiring overseer attention",
+	Long: `Show what specifically needs the overseer's attention.
+
+Groups items into categories:
+  REQUIRES DECISION - Issues needing architectural/design choices
+  REQUIRES REVIEW   - PRs and design docs awaiting approval
+  BLOCKED           - Items stuck on unresolved dependencies
+
+Examples:
+  gt attention          # Show all attention items
+  gt attention --json   # Machine-readable output`,
+	RunE: runAttention,
+}
+
+func init() {
+	attentionCmd.Flags().BoolVar(&attentionJSON, "json", false, "Output as JSON")
+	attentionCmd.Flags().BoolVar(&attentionAll, "all", false, "Include lower-priority items")
+	rootCmd.AddCommand(attentionCmd)
+}
+
+// AttentionCategory represents a group of items needing attention.
+type AttentionCategory string
+
+const (
+	CategoryDecision AttentionCategory = "REQUIRES_DECISION"
+	CategoryReview   AttentionCategory = "REQUIRES_REVIEW"
+	CategoryBlocked  AttentionCategory = "BLOCKED"
+	CategoryStuck    AttentionCategory = "STUCK_WORKERS"
+)
+
+// AttentionItem represents something needing overseer attention.
+type AttentionItem struct {
+	Category    AttentionCategory `json:"category"`
+	Priority    int               `json:"priority"`
+	ID          string            `json:"id"`
+	Title       string            `json:"title"`
+	Context     string            `json:"context,omitempty"`
+	DrillDown   string            `json:"drill_down"`
+	Source      string            `json:"source,omitempty"` // "beads", "github", "agent"
+	Details     string            `json:"details,omitempty"`
+}
+
+// AttentionOutput is the full attention report.
+type AttentionOutput struct {
+	Decisions    []AttentionItem `json:"decisions,omitempty"`
+	Reviews      []AttentionItem `json:"reviews,omitempty"`
+	Blocked      []AttentionItem `json:"blocked,omitempty"`
+	StuckWorkers []AttentionItem `json:"stuck_workers,omitempty"`
+}
+
+func runAttention(cmd *cobra.Command, args []string) error {
+	townRoot, err := workspace.FindFromCwdOrError()
+	if err != nil {
+		return fmt.Errorf("not in a Gas Town workspace: %w", err)
+	}
+
+	output := AttentionOutput{}
+
+	// Collect items from various sources in parallel
+	// 1. Blocked beads
+	output.Blocked = collectBlockedItems(townRoot)
+
+	// 2. Items needing decision (issues with needs-decision label)
+	output.Decisions = collectDecisionItems(townRoot)
+
+	// 3. PRs awaiting review
+	output.Reviews = collectReviewItems(townRoot)
+
+	// 4. Stuck workers (agents marked as stuck)
+	output.StuckWorkers = collectStuckWorkers(townRoot)
+
+	// Sort each category by priority
+	sortByPriority := func(items []AttentionItem) {
+		sort.Slice(items, func(i, j int) bool {
+			return items[i].Priority < items[j].Priority // Lower priority number = higher importance
+		})
+	}
+	sortByPriority(output.Decisions)
+	sortByPriority(output.Reviews)
+	sortByPriority(output.Blocked)
+	sortByPriority(output.StuckWorkers)
+
+	if attentionJSON {
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		return enc.Encode(output)
+	}
+
+	return outputAttentionText(output)
+}
+
+func collectBlockedItems(townRoot string) []AttentionItem {
+	var items []AttentionItem
+
+	// Query blocked issues from beads
+	blockedCmd := exec.Command("bd", "blocked", "--json")
+	var stdout bytes.Buffer
+	blockedCmd.Stdout = &stdout
+
+	if err := blockedCmd.Run(); err != nil {
+		return items
+	}
+
+	var blocked []struct {
+		ID        string   `json:"id"`
+		Title     string   `json:"title"`
+		Priority  int      `json:"priority"`
+		BlockedBy []string `json:"blocked_by,omitempty"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &blocked); err != nil {
+		return items
+	}
+
+	for _, b := range blocked {
+		// Skip ephemeral/internal issues
+		if strings.Contains(b.ID, "wisp") || strings.Contains(b.ID, "-mol-") {
+			continue
+		}
+		if strings.Contains(b.ID, "-agent-") {
+			continue
+		}
+
+		context := ""
+		if len(b.BlockedBy) > 0 {
+			context = fmt.Sprintf("Blocked by: %s", strings.Join(b.BlockedBy, ", "))
+		}
+
+		items = append(items, AttentionItem{
+			Category:  CategoryBlocked,
+			Priority:  b.Priority,
+			ID:        b.ID,
+			Title:     b.Title,
+			Context:   context,
+			DrillDown: fmt.Sprintf("bd show %s", b.ID),
+			Source:    "beads",
+		})
+	}
+
+	return items
+}
+
+func collectDecisionItems(townRoot string) []AttentionItem {
+	var items []AttentionItem
+
+	// Query issues with needs-decision label
+	listCmd := exec.Command("bd", "list", "--label=needs-decision", "--status=open", "--json")
+	var stdout bytes.Buffer
+	listCmd.Stdout = &stdout
+
+	if err := listCmd.Run(); err != nil {
+		return items
+	}
+
+	var issues []struct {
+		ID       string `json:"id"`
+		Title    string `json:"title"`
+		Priority int    `json:"priority"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &issues); err != nil {
+		return items
+	}
+
+	for _, issue := range issues {
+		items = append(items, AttentionItem{
+			Category:  CategoryDecision,
+			Priority:  issue.Priority,
+			ID:        issue.ID,
+			Title:     issue.Title,
+			Context:   "Needs architectural/design decision",
+			DrillDown: fmt.Sprintf("bd show %s", issue.ID),
+			Source:    "beads",
+		})
+	}
+
+	return items
+}
+
+func collectReviewItems(townRoot string) []AttentionItem {
+	var items []AttentionItem
+
+	// Query open PRs from GitHub
+	prCmd := exec.Command("gh", "pr", "list", "--json", "number,title,headRefName,reviewDecision,additions,deletions")
+	var stdout bytes.Buffer
+	prCmd.Stdout = &stdout
+
+	if err := prCmd.Run(); err != nil {
+		// gh not available or not in a git repo - skip
+		return items
+	}
+
+	var prs []struct {
+		Number         int    `json:"number"`
+		Title          string `json:"title"`
+		HeadRefName    string `json:"headRefName"`
+		ReviewDecision string `json:"reviewDecision"`
+		Additions      int    `json:"additions"`
+		Deletions      int    `json:"deletions"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &prs); err != nil {
+		return items
+	}
+
+	for _, pr := range prs {
+		// Skip PRs that are already approved
+		if pr.ReviewDecision == "APPROVED" {
+			continue
+		}
+
+		details := fmt.Sprintf("+%d/-%d lines", pr.Additions, pr.Deletions)
+
+		items = append(items, AttentionItem{
+			Category:  CategoryReview,
+			Priority:  2, // Default P2 for PRs
+			ID:        fmt.Sprintf("PR #%d", pr.Number),
+			Title:     pr.Title,
+			Context:   fmt.Sprintf("Branch: %s", pr.HeadRefName),
+			DrillDown: fmt.Sprintf("gh pr view %d", pr.Number),
+			Source:    "github",
+			Details:   details,
+		})
+	}
+
+	return items
+}
+
+func collectStuckWorkers(townRoot string) []AttentionItem {
+	var items []AttentionItem
+
+	// Query agent beads with stuck state
+	// Check each rig's beads for stuck agents
+	rigDirs, _ := filepath.Glob(filepath.Join(townRoot, "*", "mayor", "rig", ".beads"))
+	for _, rigBeads := range rigDirs {
+		rigItems := queryStuckAgents(rigBeads)
+		items = append(items, rigItems...)
+	}
+
+	return items
+}
+
+func queryStuckAgents(beadsPath string) []AttentionItem {
+	var items []AttentionItem
+
+	// Query agents with stuck state
+	dbPath := filepath.Join(beadsPath, "beads.db")
+	if _, err := os.Stat(dbPath); err != nil {
+		return items
+	}
+
+	// Query for agent beads with agent_state = 'stuck'
+	query := `SELECT id, title, agent_state FROM issues WHERE issue_type = 'agent' AND agent_state = 'stuck'`
+	queryCmd := exec.Command("sqlite3", "-json", dbPath, query)
+	var stdout bytes.Buffer
+	queryCmd.Stdout = &stdout
+
+	if err := queryCmd.Run(); err != nil {
+		return items
+	}
+
+	var agents []struct {
+		ID         string `json:"id"`
+		Title      string `json:"title"`
+		AgentState string `json:"agent_state"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &agents); err != nil {
+		return items
+	}
+
+	for _, agent := range agents {
+		// Extract agent name from ID (e.g., "gt-gastown-polecat-goose" -> "goose")
+		parts := strings.Split(agent.ID, "-")
+		name := parts[len(parts)-1]
+
+		items = append(items, AttentionItem{
+			Category:  CategoryStuck,
+			Priority:  1, // Stuck workers are high priority
+			ID:        agent.ID,
+			Title:     fmt.Sprintf("Worker %s is stuck", name),
+			Context:   "Agent escalated - needs help",
+			DrillDown: fmt.Sprintf("bd show %s", agent.ID),
+			Source:    "agent",
+		})
+	}
+
+	return items
+}
+
+func outputAttentionText(output AttentionOutput) error {
+	hasContent := false
+
+	// Decisions
+	if len(output.Decisions) > 0 {
+		hasContent = true
+		fmt.Printf("%s (%d items)\n", style.Bold.Render("REQUIRES DECISION"), len(output.Decisions))
+		for i, item := range output.Decisions {
+			fmt.Printf("%d. [P%d] %s: %s\n", i+1, item.Priority, item.ID, item.Title)
+			if item.Context != "" {
+				fmt.Printf("   %s\n", style.Dim.Render(item.Context))
+			}
+			fmt.Printf("   %s\n\n", style.Dim.Render("→ "+item.DrillDown))
+		}
+	}
+
+	// Reviews
+	if len(output.Reviews) > 0 {
+		hasContent = true
+		fmt.Printf("%s (%d items)\n", style.Bold.Render("REQUIRES REVIEW"), len(output.Reviews))
+		for i, item := range output.Reviews {
+			fmt.Printf("%d. [P%d] %s: %s\n", i+1, item.Priority, item.ID, item.Title)
+			if item.Details != "" {
+				fmt.Printf("   %s\n", style.Dim.Render(item.Details))
+			}
+			if item.Context != "" {
+				fmt.Printf("   %s\n", style.Dim.Render(item.Context))
+			}
+			fmt.Printf("   %s\n\n", style.Dim.Render("→ "+item.DrillDown))
+		}
+	}
+
+	// Stuck Workers
+	if len(output.StuckWorkers) > 0 {
+		hasContent = true
+		fmt.Printf("%s (%d items)\n", style.Bold.Render("STUCK WORKERS"), len(output.StuckWorkers))
+		for i, item := range output.StuckWorkers {
+			fmt.Printf("%d. %s\n", i+1, item.Title)
+			if item.Context != "" {
+				fmt.Printf("   %s\n", style.Dim.Render(item.Context))
+			}
+			fmt.Printf("   %s\n\n", style.Dim.Render("→ "+item.DrillDown))
+		}
+	}
+
+	// Blocked
+	if len(output.Blocked) > 0 {
+		hasContent = true
+		fmt.Printf("%s (%d items)\n", style.Bold.Render("BLOCKED"), len(output.Blocked))
+		for i, item := range output.Blocked {
+			fmt.Printf("%d. [P%d] %s: %s\n", i+1, item.Priority, item.ID, item.Title)
+			if item.Context != "" {
+				fmt.Printf("   %s\n", style.Dim.Render(item.Context))
+			}
+			fmt.Printf("   %s\n\n", style.Dim.Render("→ "+item.DrillDown))
+		}
+	}
+
+	if !hasContent {
+		fmt.Println("No items requiring attention.")
+		fmt.Println(style.Dim.Render("All clear - nothing blocked, no pending reviews."))
+	}
+
+	return nil
+}

internal/cmd/bead.go

@@ -13,6 +13,7 @@ import (
 
 var beadCmd = &cobra.Command{
 	Use:     "bead",
+	Aliases: []string{"bd"},
 	GroupID: GroupWork,
 	Short:   "Bead management utilities",
 	Long:    `Utilities for managing beads across repositories.`,
@@ -57,10 +58,29 @@ Examples:
 	},
 }
 
+var beadReadCmd = &cobra.Command{
+	Use:   "read <bead-id> [flags]",
+	Short: "Show details of a bead (alias for 'show')",
+	Long: `Displays the full details of a bead by ID.
+
+This is an alias for 'gt bead show'. All bd show flags are supported.
+
+Examples:
+  gt bead read gt-abc123          # Show a gastown issue
+  gt bead read hq-xyz789          # Show a town-level bead
+  gt bead read bd-def456          # Show a beads issue
+  gt bead read gt-abc123 --json   # Output as JSON`,
+	DisableFlagParsing: true, // Pass all flags through to bd show
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return runShow(cmd, args)
+	},
+}
+
 func init() {
 	beadMoveCmd.Flags().BoolVarP(&beadMoveDryRun, "dry-run", "n", false, "Show what would be done")
 	beadCmd.AddCommand(beadMoveCmd)
 	beadCmd.AddCommand(beadShowCmd)
+	beadCmd.AddCommand(beadReadCmd)
 	rootCmd.AddCommand(beadCmd)
 }
 

internal/cmd/beads_version.go

@@ -3,13 +3,18 @@ package cmd
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"os"
 	"os/exec"
+	"path/filepath"
 	"regexp"
 	"strconv"
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/steveyegge/gastown/internal/state"
 )
 
 // MinBeadsVersion is the minimum required beads version for Gas Town.
@@ -90,8 +95,60 @@ func (v beadsVersion) compare(other beadsVersion) int {
 // Pre-compiled regex for beads version parsing
 var beadsVersionRe = regexp.MustCompile(`bd version (\d+\.\d+(?:\.\d+)?(?:-\w+)?)`)
 
+// versionCacheTTL is how long a cached version check remains valid.
+// 24 hours is reasonable since version upgrades are infrequent.
+const versionCacheTTL = 24 * time.Hour
+
+// versionCache stores the result of a beads version check.
+type versionCache struct {
+	Version   string    `json:"version"`
+	CheckedAt time.Time `json:"checked_at"`
+	Valid     bool      `json:"valid"` // true if version meets minimum requirement
+}
+
+// versionCachePath returns the path to the version cache file.
+func versionCachePath() string {
+	return filepath.Join(state.CacheDir(), "beads-version.json")
+}
+
+// loadVersionCache reads the cached version check result.
+func loadVersionCache() (*versionCache, error) {
+	data, err := os.ReadFile(versionCachePath())
+	if err != nil {
+		return nil, err
+	}
+	var cache versionCache
+	if err := json.Unmarshal(data, &cache); err != nil {
+		return nil, err
+	}
+	return &cache, nil
+}
+
+// saveVersionCache writes the version check result to cache.
+func saveVersionCache(c *versionCache) error {
+	dir := state.CacheDir()
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(c, "", "  ")
+	if err != nil {
+		return err
+	}
+	// Atomic write via temp file
+	tmp := versionCachePath() + ".tmp"
+	if err := os.WriteFile(tmp, data, 0600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, versionCachePath())
+}
+
+// isCacheFresh returns true if the cache is within the TTL.
+func (c *versionCache) isCacheFresh() bool {
+	return time.Since(c.CheckedAt) < versionCacheTTL
+}
+
 func getBeadsVersion() (string, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 
 	cmd := exec.CommandContext(ctx, "bd", "version")
@@ -132,8 +189,27 @@ func CheckBeadsVersion() error {
 }
 
 func checkBeadsVersionInternal() error {
+	// Try to use cached result first to avoid subprocess spawning
+	if cache, err := loadVersionCache(); err == nil && cache.isCacheFresh() {
+		if cache.Valid {
+			return nil // Cached successful check
+		}
+		// Cached failure - still need to check (version might have been upgraded)
+	}
+
 	installedStr, err := getBeadsVersion()
 	if err != nil {
+		// On timeout, try to use stale cache or gracefully degrade
+		if strings.Contains(err.Error(), "timed out") {
+			if cache, cacheErr := loadVersionCache(); cacheErr == nil && cache.Valid {
+				// Use stale cache but warn
+				fmt.Fprintf(os.Stderr, "Warning: bd version check timed out, using cached result (v%s)\n", cache.Version)
+				return nil
+			}
+			// No cache available - gracefully degrade with warning
+			fmt.Fprintf(os.Stderr, "Warning: bd version check timed out (high system load?), proceeding anyway\n")
+			return nil
+		}
 		return fmt.Errorf("cannot verify beads version: %w", err)
 	}
 
@@ -148,7 +224,16 @@ func checkBeadsVersionInternal() error {
 		return fmt.Errorf("cannot parse required beads version %q: %w", MinBeadsVersion, err)
 	}
 
-	if installed.compare(required) < 0 {
+	valid := installed.compare(required) >= 0
+
+	// Cache the result
+	_ = saveVersionCache(&versionCache{
+		Version:   installedStr,
+		CheckedAt: time.Now(),
+		Valid:     valid,
+	})
+
+	if !valid {
 		return fmt.Errorf("beads version %s is required, but %s is installed\n\nPlease upgrade beads: go install github.com/steveyegge/beads/cmd/bd@latest", MinBeadsVersion, installedStr)
 	}
 

internal/cmd/boot.go

@@ -301,9 +301,10 @@ func runDegradedTriage(b *boot.Boot) (action, target string, err error) {
 			// Nudge the session to try to wake it up
 			age := hb.Age()
 			if age > 30*time.Minute {
-				// Very stuck - restart the session
+				// Very stuck - restart the session.
+				// Use KillSessionWithProcesses to ensure all descendant processes are killed.
 				fmt.Printf("Deacon heartbeat is %s old - restarting session\n", age.Round(time.Minute))
-				if err := tm.KillSession(deaconSession); err == nil {
+				if err := tm.KillSessionWithProcesses(deaconSession); err == nil {
 					return "restart", "deacon-stuck", nil
 				}
 			} else {

internal/cmd/cleanup.go

@@ -0,0 +1,127 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/util"
+)
+
+var (
+	cleanupDryRun bool
+	cleanupForce  bool
+)
+
+var cleanupCmd = &cobra.Command{
+	Use:     "cleanup",
+	GroupID: GroupWork,
+	Short:   "Clean up orphaned Claude processes",
+	Long: `Clean up orphaned Claude processes that survived session termination.
+
+This command finds and kills Claude processes that are not associated with
+any active Gas Town tmux session. These orphans can accumulate when:
+- Polecat sessions are killed without proper cleanup
+- Claude spawns subagent processes that outlive their parent
+- Network or system issues interrupt normal shutdown
+
+Uses aggressive tmux session verification to detect ALL orphaned processes,
+not just those with PPID=1.
+
+Examples:
+  gt cleanup              # Clean up orphans with confirmation
+  gt cleanup --dry-run    # Show what would be killed
+  gt cleanup --force      # Kill without confirmation`,
+	RunE: runCleanup,
+}
+
+func init() {
+	cleanupCmd.Flags().BoolVar(&cleanupDryRun, "dry-run", false, "Show what would be killed without killing")
+	cleanupCmd.Flags().BoolVarP(&cleanupForce, "force", "f", false, "Kill without confirmation")
+
+	rootCmd.AddCommand(cleanupCmd)
+}
+
+func runCleanup(cmd *cobra.Command, args []string) error {
+	// Find orphaned processes using aggressive zombie detection
+	zombies, err := util.FindZombieClaudeProcesses()
+	if err != nil {
+		return fmt.Errorf("finding orphaned processes: %w", err)
+	}
+
+	if len(zombies) == 0 {
+		fmt.Printf("%s No orphaned Claude processes found\n", style.Bold.Render("✓"))
+		return nil
+	}
+
+	// Show what we found
+	fmt.Printf("%s Found %d orphaned Claude process(es):\n\n", style.Warning.Render("⚠"), len(zombies))
+	for _, z := range zombies {
+		ageStr := formatProcessAgeCleanup(z.Age)
+		fmt.Printf("  %s %s (age: %s, tty: %s)\n",
+			style.Bold.Render(fmt.Sprintf("PID %d", z.PID)),
+			z.Cmd,
+			style.Dim.Render(ageStr),
+			z.TTY)
+	}
+	fmt.Println()
+
+	if cleanupDryRun {
+		fmt.Printf("%s Dry run - no processes killed\n", style.Dim.Render("ℹ"))
+		return nil
+	}
+
+	// Confirm unless --force
+	if !cleanupForce {
+		fmt.Printf("Kill these %d process(es)? [y/N] ", len(zombies))
+		var response string
+		_, _ = fmt.Scanln(&response)
+		if response != "y" && response != "Y" && response != "yes" && response != "Yes" {
+			fmt.Println("Aborted")
+			return nil
+		}
+	}
+
+	// Kill the processes using the standard cleanup function
+	results, err := util.CleanupZombieClaudeProcesses()
+	if err != nil {
+		return fmt.Errorf("cleaning up processes: %w", err)
+	}
+
+	// Report results
+	var killed, escalated int
+	for _, r := range results {
+		switch r.Signal {
+		case "SIGTERM":
+			fmt.Printf("  %s PID %d sent SIGTERM\n", style.Success.Render("✓"), r.Process.PID)
+			killed++
+		case "SIGKILL":
+			fmt.Printf("  %s PID %d sent SIGKILL (didn't respond to SIGTERM)\n", style.Warning.Render("⚠"), r.Process.PID)
+			killed++
+		case "UNKILLABLE":
+			fmt.Printf("  %s PID %d survived SIGKILL\n", style.Error.Render("✗"), r.Process.PID)
+			escalated++
+		}
+	}
+
+	fmt.Printf("\n%s Cleaned up %d process(es)", style.Bold.Render("✓"), killed)
+	if escalated > 0 {
+		fmt.Printf(", %d unkillable", escalated)
+	}
+	fmt.Println()
+
+	return nil
+}
+
+// formatProcessAgeCleanup formats seconds into a human-readable age string
+func formatProcessAgeCleanup(seconds int) string {
+	if seconds < 60 {
+		return fmt.Sprintf("%ds", seconds)
+	}
+	if seconds < 3600 {
+		return fmt.Sprintf("%dm%ds", seconds/60, seconds%60)
+	}
+	hours := seconds / 3600
+	mins := (seconds % 3600) / 60
+	return fmt.Sprintf("%dh%dm", hours, mins)
+}

internal/cmd/close.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"os"
 	"os/exec"
+	"strings"
 
 	"github.com/spf13/cobra"
 )
@@ -20,6 +21,7 @@ Examples:
   gt close gt-abc              # Close bead gt-abc
   gt close gt-abc gt-def       # Close multiple beads
   gt close --reason "Done"     # Close with reason
+  gt close --comment "Done"    # Same as --reason (alias)
   gt close --force             # Force close pinned beads`,
 	DisableFlagParsing: true, // Pass all flags through to bd close
 	RunE:               runClose,
@@ -30,8 +32,20 @@ func init() {
 }
 
 func runClose(cmd *cobra.Command, args []string) error {
+	// Convert --comment to --reason (alias support)
+	convertedArgs := make([]string, len(args))
+	for i, arg := range args {
+		if arg == "--comment" {
+			convertedArgs[i] = "--reason"
+		} else if strings.HasPrefix(arg, "--comment=") {
+			convertedArgs[i] = "--reason=" + strings.TrimPrefix(arg, "--comment=")
+		} else {
+			convertedArgs[i] = arg
+		}
+	}
+
 	// Build bd close command with all args passed through
-	bdArgs := append([]string{"close"}, args...)
+	bdArgs := append([]string{"close"}, convertedArgs...)
 	bdCmd := exec.Command("bd", bdArgs...)
 	bdCmd.Stdin = os.Stdin
 	bdCmd.Stdout = os.Stdout

internal/cmd/convoy.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 	"sync"
@@ -69,10 +70,15 @@ var (
 	convoyListStatus   string
 	convoyListAll      bool
 	convoyListTree     bool
+	convoyListOrphans  bool
+	convoyListEpic     string
+	convoyListByEpic   bool
 	convoyInteractive  bool
 	convoyStrandedJSON bool
 	convoyCloseReason  string
 	convoyCloseNotify  string
+	convoyCheckDryRun  bool
+	convoyEpic         string // --epic: link convoy to parent epic (Goals layer)
 )
 
 var convoyCmd = &cobra.Command{
@@ -158,6 +164,9 @@ Examples:
   gt convoy list --all        # All convoys (open + closed)
   gt convoy list --status=closed  # Recently landed
   gt convoy list --tree       # Show convoy + child status tree
+  gt convoy list --orphans    # Convoys with no parent epic
+  gt convoy list --epic gt-abc    # Convoys linked to specific epic
+  gt convoy list --by-epic    # Group convoys by parent epic
   gt convoy list --json`,
 	RunE: runConvoyList,
 }
@@ -177,14 +186,22 @@ Examples:
 }
 
 var convoyCheckCmd = &cobra.Command{
-	Use:   "check",
+	Use:   "check [convoy-id]",
 	Short: "Check and auto-close completed convoys",
-	Long: `Check all open convoys and auto-close any where all tracked issues are complete.
+	Long: `Check convoys and auto-close any where all tracked issues are complete.
+
+Without arguments, checks all open convoys. With a convoy ID, checks only that convoy.
 
 This handles cross-rig convoy completion: convoys in town beads tracking issues
 in rig beads won't auto-close via bd close alone. This command bridges that gap.
 
-Can be run manually or by deacon patrol to ensure convoys close promptly.`,
+Can be run manually or by deacon patrol to ensure convoys close promptly.
+
+Examples:
+  gt convoy check              # Check all open convoys
+  gt convoy check hq-cv-abc    # Check specific convoy
+  gt convoy check --dry-run    # Preview what would close without acting`,
+	Args: cobra.MaximumNArgs(1),
 	RunE: runConvoyCheck,
 }
 
@@ -244,10 +261,16 @@ func init() {
 	convoyListCmd.Flags().StringVar(&convoyListStatus, "status", "", "Filter by status (open, closed)")
 	convoyListCmd.Flags().BoolVar(&convoyListAll, "all", false, "Show all convoys (open and closed)")
 	convoyListCmd.Flags().BoolVar(&convoyListTree, "tree", false, "Show convoy + child status tree")
+	convoyListCmd.Flags().BoolVar(&convoyListOrphans, "orphans", false, "Show only orphan convoys (no parent epic)")
+	convoyListCmd.Flags().StringVar(&convoyListEpic, "epic", "", "Show convoys for a specific epic")
+	convoyListCmd.Flags().BoolVar(&convoyListByEpic, "by-epic", false, "Group convoys by parent epic")
 
 	// Interactive TUI flag (on parent command)
 	convoyCmd.Flags().BoolVarP(&convoyInteractive, "interactive", "i", false, "Interactive tree view")
 
+	// Check flags
+	convoyCheckCmd.Flags().BoolVar(&convoyCheckDryRun, "dry-run", false, "Preview what would close without acting")
+
 	// Stranded flags
 	convoyStrandedCmd.Flags().BoolVar(&convoyStrandedJSON, "json", false, "Output as JSON")
 
@@ -297,10 +320,22 @@ func runConvoyCreate(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
+	// Ensure custom types (including 'convoy') are registered in town beads.
+	// This handles cases where install didn't complete or beads was initialized manually.
+	if err := beads.EnsureCustomTypes(townBeads); err != nil {
+		return fmt.Errorf("ensuring custom types: %w", err)
+	}
+
 	// Create convoy issue in town beads
 	description := fmt.Sprintf("Convoy tracking %d issues", len(trackedIssues))
-	if convoyOwner != "" {
-		description += fmt.Sprintf("\nOwner: %s", convoyOwner)
+
+	// Default owner to creator identity if not specified
+	owner := convoyOwner
+	if owner == "" {
+		owner = detectSender()
+	}
+	if owner != "" {
+		description += fmt.Sprintf("\nOwner: %s", owner)
 	}
 	if convoyNotify != "" {
 		description += fmt.Sprintf("\nNotify: %s", convoyNotify)
@@ -365,8 +400,8 @@ func runConvoyCreate(cmd *cobra.Command, args []string) error {
 	if len(trackedIssues) > 0 {
 		fmt.Printf("  Issues:   %s\n", strings.Join(trackedIssues, ", "))
 	}
-	if convoyOwner != "" {
-		fmt.Printf("  Owner:    %s\n", convoyOwner)
+	if owner != "" {
+		fmt.Printf("  Owner:    %s\n", owner)
 	}
 	if convoyNotify != "" {
 		fmt.Printf("  Notify:   %s\n", convoyNotify)
@@ -472,7 +507,14 @@ func runConvoyCheck(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	closed, err := checkAndCloseCompletedConvoys(townBeads)
+	// If a specific convoy ID is provided, check only that convoy
+	if len(args) == 1 {
+		convoyID := args[0]
+		return checkSingleConvoy(townBeads, convoyID, convoyCheckDryRun)
+	}
+
+	// Check all open convoys
+	closed, err := checkAndCloseCompletedConvoys(townBeads, convoyCheckDryRun)
 	if err != nil {
 		return err
 	}
@@ -480,7 +522,11 @@ func runConvoyCheck(cmd *cobra.Command, args []string) error {
 	if len(closed) == 0 {
 		fmt.Println("No convoys ready to close.")
 	} else {
-		fmt.Printf("%s Auto-closed %d convoy(s):\n", style.Bold.Render("✓"), len(closed))
+		if convoyCheckDryRun {
+			fmt.Printf("%s Would auto-close %d convoy(s):\n", style.Warning.Render("⚠"), len(closed))
+		} else {
+			fmt.Printf("%s Auto-closed %d convoy(s):\n", style.Bold.Render("✓"), len(closed))
+		}
 		for _, c := range closed {
 			fmt.Printf("  🚚 %s: %s\n", c.ID, c.Title)
 		}
@@ -489,6 +535,92 @@ func runConvoyCheck(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// checkSingleConvoy checks a specific convoy and closes it if all tracked issues are complete.
+func checkSingleConvoy(townBeads, convoyID string, dryRun bool) error {
+	// Get convoy details
+	showArgs := []string{"show", convoyID, "--json"}
+	showCmd := exec.Command("bd", showArgs...)
+	showCmd.Dir = townBeads
+	var stdout bytes.Buffer
+	showCmd.Stdout = &stdout
+
+	if err := showCmd.Run(); err != nil {
+		return fmt.Errorf("convoy '%s' not found", convoyID)
+	}
+
+	var convoys []struct {
+		ID          string `json:"id"`
+		Title       string `json:"title"`
+		Status      string `json:"status"`
+		Type        string `json:"issue_type"`
+		Description string `json:"description"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &convoys); err != nil {
+		return fmt.Errorf("parsing convoy data: %w", err)
+	}
+
+	if len(convoys) == 0 {
+		return fmt.Errorf("convoy '%s' not found", convoyID)
+	}
+
+	convoy := convoys[0]
+
+	// Verify it's actually a convoy type
+	if convoy.Type != "convoy" {
+		return fmt.Errorf("'%s' is not a convoy (type: %s)", convoyID, convoy.Type)
+	}
+
+	// Check if convoy is already closed
+	if convoy.Status == "closed" {
+		fmt.Printf("%s Convoy %s is already closed\n", style.Dim.Render("○"), convoyID)
+		return nil
+	}
+
+	// Get tracked issues
+	tracked := getTrackedIssues(townBeads, convoyID)
+	if len(tracked) == 0 {
+		fmt.Printf("%s Convoy %s has no tracked issues\n", style.Dim.Render("○"), convoyID)
+		return nil
+	}
+
+	// Check if all tracked issues are closed
+	allClosed := true
+	openCount := 0
+	for _, t := range tracked {
+		if t.Status != "closed" && t.Status != "tombstone" {
+			allClosed = false
+			openCount++
+		}
+	}
+
+	if !allClosed {
+		fmt.Printf("%s Convoy %s has %d open issue(s) remaining\n", style.Dim.Render("○"), convoyID, openCount)
+		return nil
+	}
+
+	// All tracked issues are complete - close the convoy
+	if dryRun {
+		fmt.Printf("%s Would auto-close convoy 🚚 %s: %s\n", style.Warning.Render("⚠"), convoyID, convoy.Title)
+		return nil
+	}
+
+	// Actually close the convoy
+	closeArgs := []string{"close", convoyID, "-r", "All tracked issues completed"}
+	closeCmd := exec.Command("bd", closeArgs...)
+	closeCmd.Dir = townBeads
+
+	if err := closeCmd.Run(); err != nil {
+		return fmt.Errorf("closing convoy: %w", err)
+	}
+
+	fmt.Printf("%s Auto-closed convoy 🚚 %s: %s\n", style.Bold.Render("✓"), convoyID, convoy.Title)
+
+	// Send completion notification
+	notifyConvoyCompletion(townBeads, convoyID, convoy.Title)
+
+	return nil
+}
+
 func runConvoyClose(cmd *cobra.Command, args []string) error {
 	convoyID := args[0]
 
@@ -755,8 +887,9 @@ func isReadyIssue(t trackedIssueInfo, blockedIssues map[string]bool) bool {
 }
 
 // checkAndCloseCompletedConvoys finds open convoys where all tracked issues are closed
-// and auto-closes them. Returns the list of convoys that were closed.
-func checkAndCloseCompletedConvoys(townBeads string) ([]struct{ ID, Title string }, error) {
+// and auto-closes them. Returns the list of convoys that were closed (or would be closed in dry-run mode).
+// If dryRun is true, no changes are made and the function returns what would have been closed.
+func checkAndCloseCompletedConvoys(townBeads string, dryRun bool) ([]struct{ ID, Title string }, error) {
 	var closed []struct{ ID, Title string }
 
 	// List all open convoys
@@ -795,6 +928,12 @@ func checkAndCloseCompletedConvoys(townBeads string) ([]struct{ ID, Title string
 		}
 
 		if allClosed {
+			if dryRun {
+				// In dry-run mode, just record what would be closed
+				closed = append(closed, struct{ ID, Title string }{convoy.ID, convoy.Title})
+				continue
+			}
+
 			// Close the convoy
 			closeArgs := []string{"close", convoy.ID, "-r", "All tracked issues completed"}
 			closeCmd := exec.Command("bd", closeArgs...)
@@ -1041,6 +1180,16 @@ func showAllConvoyStatus(townBeads string) error {
 	return nil
 }
 
+// convoyListItem holds convoy info for list display.
+type convoyListItem struct {
+	ID          string `json:"id"`
+	Title       string `json:"title"`
+	Status      string `json:"status"`
+	CreatedAt   string `json:"created_at"`
+	ParentEpic  string `json:"parent_epic,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
 func runConvoyList(cmd *cobra.Command, args []string) error {
 	townBeads, err := getTownBeadsDir()
 	if err != nil {
@@ -1065,16 +1214,59 @@ func runConvoyList(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("listing convoys: %w", err)
 	}
 
-	var convoys []struct {
-		ID        string `json:"id"`
-		Title     string `json:"title"`
-		Status    string `json:"status"`
-		CreatedAt string `json:"created_at"`
+	var rawConvoys []struct {
+		ID          string `json:"id"`
+		Title       string `json:"title"`
+		Status      string `json:"status"`
+		CreatedAt   string `json:"created_at"`
+		Description string `json:"description"`
 	}
-	if err := json.Unmarshal(stdout.Bytes(), &convoys); err != nil {
+	if err := json.Unmarshal(stdout.Bytes(), &rawConvoys); err != nil {
 		return fmt.Errorf("parsing convoy list: %w", err)
 	}
 
+	// Convert to convoyListItem and extract parent_epic from description
+	convoys := make([]convoyListItem, 0, len(rawConvoys))
+	for _, rc := range rawConvoys {
+		item := convoyListItem{
+			ID:          rc.ID,
+			Title:       rc.Title,
+			Status:      rc.Status,
+			CreatedAt:   rc.CreatedAt,
+			Description: rc.Description,
+		}
+		// Extract parent_epic from description (format: "Parent-Epic: xxx")
+		for _, line := range strings.Split(rc.Description, "\n") {
+			if strings.HasPrefix(line, "Parent-Epic: ") {
+				item.ParentEpic = strings.TrimPrefix(line, "Parent-Epic: ")
+				break
+			}
+		}
+		convoys = append(convoys, item)
+	}
+
+	// Apply filtering based on new flags
+	if convoyListOrphans {
+		// Filter to only orphan convoys (no parent epic)
+		filtered := make([]convoyListItem, 0)
+		for _, c := range convoys {
+			if c.ParentEpic == "" {
+				filtered = append(filtered, c)
+			}
+		}
+		convoys = filtered
+	} else if convoyListEpic != "" {
+		// Filter to convoys linked to specific epic
+		filtered := make([]convoyListItem, 0)
+		for _, c := range convoys {
+			if c.ParentEpic == convoyListEpic {
+				filtered = append(filtered, c)
+			}
+		}
+		convoys = filtered
+	}
+
+
 	if convoyListJSON {
 		enc := json.NewEncoder(os.Stdout)
 		enc.SetIndent("", "  ")
@@ -1082,33 +1274,81 @@ func runConvoyList(cmd *cobra.Command, args []string) error {
 	}
 
 	if len(convoys) == 0 {
-		fmt.Println("No convoys found.")
+		if convoyListOrphans {
+			fmt.Println("No orphan convoys found.")
+		} else if convoyListEpic != "" {
+			fmt.Printf("No convoys found for epic %s.\n", convoyListEpic)
+		} else {
+			fmt.Println("No convoys found.")
+		}
 		fmt.Println("Create a convoy with: gt convoy create <name> [issues...]")
 		return nil
 	}
 
+	// Group by epic view
+	if convoyListByEpic {
+		return printConvoysByEpic(townBeads, convoys)
+	}
+
 	// Tree view: show convoys with their child issues
 	if convoyListTree {
-		return printConvoyTree(townBeads, convoys)
+		return printConvoyTreeFromItems(townBeads, convoys)
 	}
 
 	fmt.Printf("%s\n\n", style.Bold.Render("Convoys"))
 	for i, c := range convoys {
 		status := formatConvoyStatus(c.Status)
-		fmt.Printf("  %d. 🚚 %s: %s %s\n", i+1, c.ID, c.Title, status)
+		epicSuffix := ""
+		if c.ParentEpic != "" {
+			epicSuffix = style.Dim.Render(fmt.Sprintf(" [%s]", c.ParentEpic))
+		}
+		fmt.Printf("  %d. 🚚 %s: %s %s%s\n", i+1, c.ID, c.Title, status, epicSuffix)
 	}
 	fmt.Printf("\nUse 'gt convoy status <id>' or 'gt convoy status <n>' for detailed view.\n")
 
 	return nil
 }
 
-// printConvoyTree displays convoys with their child issues in a tree format.
-func printConvoyTree(townBeads string, convoys []struct {
-	ID        string `json:"id"`
-	Title     string `json:"title"`
-	Status    string `json:"status"`
-	CreatedAt string `json:"created_at"`
-}) error {
+// printConvoysByEpic groups and displays convoys by their parent epic.
+func printConvoysByEpic(townBeads string, convoys []convoyListItem) error {
+	// Group convoys by parent epic
+	byEpic := make(map[string][]convoyListItem)
+	for _, c := range convoys {
+		epic := c.ParentEpic
+		if epic == "" {
+			epic = "(No Epic)"
+		}
+		byEpic[epic] = append(byEpic[epic], c)
+	}
+
+	// Get sorted epic keys (No Epic last)
+	var epics []string
+	for epic := range byEpic {
+		if epic != "(No Epic)" {
+			epics = append(epics, epic)
+		}
+	}
+	sort.Strings(epics)
+	if _, ok := byEpic["(No Epic)"]; ok {
+		epics = append(epics, "(No Epic)")
+	}
+
+	// Print grouped output
+	for _, epic := range epics {
+		convoys := byEpic[epic]
+		fmt.Printf("%s (%d convoys)\n", style.Bold.Render(epic), len(convoys))
+		for _, c := range convoys {
+			status := formatConvoyStatus(c.Status)
+			fmt.Printf("  🚚 %s: %s %s\n", c.ID, c.Title, status)
+		}
+		fmt.Println()
+	}
+
+	return nil
+}
+
+// printConvoyTreeFromItems displays convoys with their child issues in a tree format.
+func printConvoyTreeFromItems(townBeads string, convoys []convoyListItem) error {
 	for _, c := range convoys {
 		// Get tracked issues for this convoy
 		tracked := getTrackedIssues(townBeads, c.ID)
@@ -1127,7 +1367,11 @@ func printConvoyTree(townBeads string, convoys []struct {
 		if total > 0 {
 			progress = fmt.Sprintf(" (%d/%d)", completed, total)
 		}
-		fmt.Printf("🚚 %s: %s%s\n", c.ID, c.Title, progress)
+		epicSuffix := ""
+		if c.ParentEpic != "" {
+			epicSuffix = style.Dim.Render(fmt.Sprintf(" [%s]", c.ParentEpic))
+		}
+		fmt.Printf("🚚 %s: %s%s%s\n", c.ID, c.Title, progress, epicSuffix)
 
 		// Print tracked issues as tree children
 		for i, t := range tracked {
@@ -1157,6 +1401,40 @@ func printConvoyTree(townBeads string, convoys []struct {
 	return nil
 }
 
+// getEpicTitles fetches titles for the given epic IDs.
+func getEpicTitles(epicIDs []string) map[string]string {
+	result := make(map[string]string)
+	if len(epicIDs) == 0 {
+		return result
+	}
+
+	// Use bd show to get epic details (handles routing automatically)
+	args := append([]string{"show"}, epicIDs...)
+	args = append(args, "--json")
+
+	showCmd := exec.Command("bd", args...)
+	var stdout bytes.Buffer
+	showCmd.Stdout = &stdout
+
+	if err := showCmd.Run(); err != nil {
+		return result
+	}
+
+	var issues []struct {
+		ID    string `json:"id"`
+		Title string `json:"title"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &issues); err != nil {
+		return result
+	}
+
+	for _, issue := range issues {
+		result[issue.ID] = issue.Title
+	}
+
+	return result
+}
+
 func formatConvoyStatus(status string) string {
 	switch status {
 	case "open":
@@ -1170,6 +1448,61 @@ func formatConvoyStatus(status string) string {
 	}
 }
 
+// getConvoyParentEpics returns a map from convoy ID to parent epic ID.
+// Convoys link to epics via child_of dependency type.
+// Uses a single batched query for efficiency.
+func getConvoyParentEpics(townBeads string, convoyIDs []string) map[string]string {
+	result := make(map[string]string)
+	if len(convoyIDs) == 0 {
+		return result
+	}
+
+	dbPath := filepath.Join(townBeads, "beads.db")
+
+	// Build IN clause with properly escaped IDs
+	var quotedIDs []string
+	for _, id := range convoyIDs {
+		safeID := strings.ReplaceAll(id, "'", "''")
+		quotedIDs = append(quotedIDs, fmt.Sprintf("'%s'", safeID))
+	}
+	inClause := strings.Join(quotedIDs, ", ")
+
+	// Query child_of dependencies for all convoys at once
+	query := fmt.Sprintf(
+		`SELECT issue_id, depends_on_id FROM dependencies WHERE issue_id IN (%s) AND type = 'child_of'`,
+		inClause)
+
+	queryCmd := exec.Command("sqlite3", "-json", dbPath, query)
+	var stdout bytes.Buffer
+	queryCmd.Stdout = &stdout
+
+	if err := queryCmd.Run(); err != nil {
+		return result
+	}
+
+	var deps []struct {
+		IssueID     string `json:"issue_id"`
+		DependsOnID string `json:"depends_on_id"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &deps); err != nil {
+		return result
+	}
+
+	for _, dep := range deps {
+		epicID := dep.DependsOnID
+		// Handle external reference format: external:rig:issue-id
+		if strings.HasPrefix(epicID, "external:") {
+			parts := strings.SplitN(epicID, ":", 3)
+			if len(parts) == 3 {
+				epicID = parts[2] // Extract the actual issue ID
+			}
+		}
+		result[dep.IssueID] = epicID
+	}
+
+	return result
+}
+
 // trackedIssueInfo holds info about an issue being tracked by a convoy.
 type trackedIssueInfo struct {
 	ID        string `json:"id"`
@@ -1208,30 +1541,51 @@ func getTrackedIssues(townBeads, convoyID string) []trackedIssueInfo {
 		return nil
 	}
 
-	// First pass: collect all issue IDs (normalized from external refs)
-	issueIDs := make([]string, 0, len(deps))
+	// First pass: collect all issue IDs and track which rig they belong to
+	type issueRef struct {
+		ID      string
+		RigName string // empty for local issues, rig name for external
+	}
+	issueRefs := make([]issueRef, 0, len(deps))
 	idToDepType := make(map[string]string)
+
 	for _, dep := range deps {
 		issueID := dep.DependsOnID
+		rigName := "" // Local issue by default
 
 		// Handle external reference format: external:rig:issue-id
 		if strings.HasPrefix(issueID, "external:") {
 			parts := strings.SplitN(issueID, ":", 3)
 			if len(parts) == 3 {
+				rigName = parts[1]   // Extract rig name
 				issueID = parts[2] // Extract the actual issue ID
 			}
 		}
 
-		issueIDs = append(issueIDs, issueID)
+		issueRefs = append(issueRefs, issueRef{ID: issueID, RigName: rigName})
 		idToDepType[issueID] = dep.Type
 	}
 
-	// Single batch call to get all issue details
-	detailsMap := getIssueDetailsBatch(issueIDs)
+	// Query issues, grouped by rig
+	detailsMap := make(map[string]*issueDetails)
+	for _, ref := range issueRefs {
+		var details *issueDetails
+		if ref.RigName != "" {
+			// External reference: query the rig database
+			details = getExternalIssueDetails(townBeads, ref.RigName, ref.ID)
+		} else {
+			// Local reference: query town database
+			details = getIssueDetails(ref.ID)
+		}
+		if details != nil {
+			detailsMap[ref.ID] = details
+		}
+	}
 
 	// Get workers for these issues (only for non-closed issues)
-	openIssueIDs := make([]string, 0, len(issueIDs))
-	for _, id := range issueIDs {
+	openIssueIDs := make([]string, 0)
+	for _, ref := range issueRefs {
+		id := ref.ID
 		if details, ok := detailsMap[id]; ok && details.Status != "closed" {
 			openIssueIDs = append(openIssueIDs, id)
 		}
@@ -1240,7 +1594,8 @@ func getTrackedIssues(townBeads, convoyID string) []trackedIssueInfo {
 
 	// Second pass: build result using the batch lookup
 	var tracked []trackedIssueInfo
-	for _, issueID := range issueIDs {
+	for _, ref := range issueRefs {
+		issueID := ref.ID
 		info := trackedIssueInfo{
 			ID:   issueID,
 			Type: idToDepType[issueID],
@@ -1268,6 +1623,58 @@ func getTrackedIssues(townBeads, convoyID string) []trackedIssueInfo {
 	return tracked
 }
 
+// getExternalIssueDetails fetches issue details from an external rig database.
+// townBeads: path to town .beads directory
+// rigName: name of the rig (e.g., "claycantrell")
+// issueID: the issue ID to look up
+func getExternalIssueDetails(townBeads, rigName, issueID string) *issueDetails {
+	// Resolve rig directory path: town parent + rig name
+	townParent := filepath.Dir(townBeads)
+	rigDir := filepath.Join(townParent, rigName)
+
+	// Check if rig directory exists
+	if _, err := os.Stat(rigDir); os.IsNotExist(err) {
+		return nil
+	}
+
+	// Query the rig database by running bd show from the rig directory
+	// Use --allow-stale to handle cases where JSONL and DB are out of sync
+	showCmd := exec.Command("bd", "--no-daemon", "show", issueID, "--json", "--allow-stale")
+	showCmd.Dir = rigDir // Set working directory to rig directory
+	var stdout bytes.Buffer
+	showCmd.Stdout = &stdout
+
+	if err := showCmd.Run(); err != nil {
+		return nil
+	}
+	if stdout.Len() == 0 {
+		return nil
+	}
+
+	var issues []struct {
+		ID        string `json:"id"`
+		Title     string `json:"title"`
+		Status    string `json:"status"`
+		IssueType string `json:"issue_type"`
+		Assignee  string `json:"assignee"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &issues); err != nil {
+		return nil
+	}
+	if len(issues) == 0 {
+		return nil
+	}
+
+	issue := issues[0]
+	return &issueDetails{
+		ID:        issue.ID,
+		Title:     issue.Title,
+		Status:    issue.Status,
+		IssueType: issue.IssueType,
+		Assignee:  issue.Assignee,
+	}
+}
+
 // issueDetails holds basic issue info.
 type issueDetails struct {
 	ID        string

internal/cmd/costs.go

@@ -63,28 +63,29 @@ The infrastructure remains in place and will work once cost data is available.
 
 Examples:
   gt costs              # Live costs from running sessions
-  gt costs --today      # Today's costs from wisps (not yet digested)
-  gt costs --week       # This week's costs from digest beads + today's wisps
+  gt costs --today      # Today's costs from log file (not yet digested)
+  gt costs --week       # This week's costs from digest beads + today's log
   gt costs --by-role    # Breakdown by role (polecat, witness, etc.)
   gt costs --by-rig     # Breakdown by rig
   gt costs --json       # Output as JSON
 
 Subcommands:
-  gt costs record       # Record session cost as ephemeral wisp (Stop hook)
-  gt costs digest       # Aggregate wisps into daily digest bead (Deacon patrol)`,
+  gt costs record       # Record session cost to local log file (Stop hook)
+  gt costs digest       # Aggregate log entries into daily digest bead (Deacon patrol)`,
 	RunE: runCosts,
 }
 
 var costsRecordCmd = &cobra.Command{
 	Use:   "record",
-	Short: "Record session cost as an ephemeral wisp (called by Stop hook)",
-	Long: `Record the final cost of a session as an ephemeral wisp.
+	Short: "Record session cost to local log file (called by Stop hook)",
+	Long: `Record the final cost of a session to a local log file.
 
 This command is intended to be called from a Claude Code Stop hook.
-It captures the final cost from the tmux session and creates an ephemeral
-event that is NOT exported to JSONL (avoiding log-in-database pollution).
+It captures the final cost from the tmux session and appends it to
+~/.gt/costs.jsonl. This is a simple append operation that never fails
+due to database availability.
 
-Session cost wisps are aggregated daily by 'gt costs digest' into a single
+Session costs are aggregated daily by 'gt costs digest' into a single
 permanent "Cost Report YYYY-MM-DD" bead for audit purposes.
 
 Examples:
@@ -95,12 +96,12 @@ Examples:
 
 var costsDigestCmd = &cobra.Command{
 	Use:   "digest",
-	Short: "Aggregate session cost wisps into a daily digest bead",
-	Long: `Aggregate ephemeral session cost wisps into a permanent daily digest.
+	Short: "Aggregate session cost log entries into a daily digest bead",
+	Long: `Aggregate session cost log entries into a permanent daily digest.
 
 This command is intended to be run by Deacon patrol (daily) or manually.
-It queries session.ended wisps for a target date, creates a single aggregate
-"Cost Report YYYY-MM-DD" bead, then deletes the source wisps.
+It reads entries from ~/.gt/costs.jsonl for a target date, creates a single
+aggregate "Cost Report YYYY-MM-DD" bead, then removes the source entries.
 
 The resulting digest bead is permanent (exported to JSONL, synced via git)
 and provides an audit trail without log-in-database pollution.
@@ -114,18 +115,18 @@ Examples:
 
 var costsMigrateCmd = &cobra.Command{
 	Use:   "migrate",
-	Short: "Migrate legacy session.ended beads to the new wisp architecture",
+	Short: "Migrate legacy session.ended beads to the new log-file architecture",
 	Long: `Migrate legacy session.ended event beads to the new cost tracking system.
 
 This command handles the transition from the old architecture (where each
-session.ended event was a permanent bead) to the new wisp-based system.
+session.ended event was a permanent bead) to the new log-file-based system.
 
 The migration:
 1. Finds all open session.ended event beads (should be none if auto-close worked)
-2. Closes them with reason "migrated to wisp architecture"
+2. Closes them with reason "migrated to log-file architecture"
 
 Legacy beads remain in the database for historical queries but won't interfere
-with the new wisp-based cost tracking.
+with the new log-file-based cost tracking.
 
 Examples:
   gt costs migrate            # Migrate legacy beads
@@ -279,7 +280,7 @@ func runCostsFromLedger() error {
 	if costsToday {
 		// For today: query ephemeral wisps (not yet digested)
 		// This gives real-time view of today's costs
-		entries, err = querySessionCostWisps(now)
+		entries, err = querySessionCostEntries(now)
 		if err != nil {
 			return fmt.Errorf("querying session cost wisps: %w", err)
 		}
@@ -292,8 +293,8 @@ func runCostsFromLedger() error {
 		}
 
 		// Also include today's wisps (not yet digested)
-		todayWisps, _ := querySessionCostWisps(now)
-		entries = append(entries, todayWisps...)
+		todayEntries, _ := querySessionCostEntries(now)
+		entries = append(entries, todayEntries...)
 	} else {
 		// No time filter: query both digests and legacy session.ended events
 		// (for backwards compatibility during migration)
@@ -738,8 +739,29 @@ func outputLedgerHuman(output CostsOutput, entries []CostEntry) error {
 	return nil
 }
 
-// runCostsRecord captures the final cost from a session and records it as a bead event.
-// This is called by the Claude Code Stop hook.
+// CostLogEntry represents a single entry in the costs.jsonl log file.
+type CostLogEntry struct {
+	SessionID string    `json:"session_id"`
+	Role      string    `json:"role"`
+	Rig       string    `json:"rig,omitempty"`
+	Worker    string    `json:"worker,omitempty"`
+	CostUSD   float64   `json:"cost_usd"`
+	EndedAt   time.Time `json:"ended_at"`
+	WorkItem  string    `json:"work_item,omitempty"`
+}
+
+// getCostsLogPath returns the path to the costs log file (~/.gt/costs.jsonl).
+func getCostsLogPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "/tmp/gt-costs.jsonl" // Fallback
+	}
+	return filepath.Join(home, ".gt", "costs.jsonl")
+}
+
+// runCostsRecord captures the final cost from a session and appends it to a local log file.
+// This is called by the Claude Code Stop hook. It's designed to never fail due to
+// database availability - it's a simple file append operation.
 func runCostsRecord(cmd *cobra.Command, args []string) error {
 	// Get session from flag or try to detect from environment
 	session := recordSession
@@ -773,92 +795,49 @@ func runCostsRecord(cmd *cobra.Command, args []string) error {
 	// Parse session name
 	role, rig, worker := parseSessionName(session)
 
-	// Build agent path for actor field
-	agentPath := buildAgentPath(role, rig, worker)
-
-	// Build event title
-	title := fmt.Sprintf("Session ended: %s", session)
-	if recordWorkItem != "" {
-		title = fmt.Sprintf("Session: %s completed %s", session, recordWorkItem)
+	// Build log entry
+	entry := CostLogEntry{
+		SessionID: session,
+		Role:      role,
+		Rig:       rig,
+		Worker:    worker,
+		CostUSD:   cost,
+		EndedAt:   time.Now(),
+		WorkItem:  recordWorkItem,
 	}
 
-	// Build payload JSON
-	payload := map[string]interface{}{
-		"cost_usd":   cost,
-		"session_id": session,
-		"role":       role,
-		"ended_at":   time.Now().Format(time.RFC3339),
-	}
-	if rig != "" {
-		payload["rig"] = rig
-	}
-	if worker != "" {
-		payload["worker"] = worker
-	}
-	payloadJSON, err := json.Marshal(payload)
+	// Marshal to JSON
+	entryJSON, err := json.Marshal(entry)
 	if err != nil {
-		return fmt.Errorf("marshaling payload: %w", err)
+		return fmt.Errorf("marshaling cost entry: %w", err)
 	}
 
-	// Build bd create command for ephemeral wisp
-	// Using --ephemeral creates a wisp that:
-	// - Is stored locally only (not exported to JSONL)
-	// - Won't pollute git history with O(sessions/day) events
-	// - Will be aggregated into daily digests by 'gt costs digest'
-	bdArgs := []string{
-		"create",
-		"--ephemeral",
-		"--type=event",
-		"--title=" + title,
-		"--event-category=session.ended",
-		"--event-actor=" + agentPath,
-		"--event-payload=" + string(payloadJSON),
-		"--silent",
+	// Append to log file
+	logPath := getCostsLogPath()
+
+	// Ensure directory exists
+	logDir := filepath.Dir(logPath)
+	if err := os.MkdirAll(logDir, 0755); err != nil {
+		return fmt.Errorf("creating log directory: %w", err)
 	}
 
-	// Add work item as event target if specified
-	if recordWorkItem != "" {
-		bdArgs = append(bdArgs, "--event-target="+recordWorkItem)
-	}
-
-	// NOTE: We intentionally don't use --rig flag here because it causes
-	// event fields (event_kind, actor, payload) to not be stored properly.
-	// The bd command will auto-detect the correct rig from cwd.
-
-	// Find town root so bd can find the .beads database.
-	// The stop hook may run from a role subdirectory (e.g., mayor/) that
-	// doesn't have its own .beads, so we need to run bd from town root.
-	townRoot, err := workspace.FindFromCwd()
+	// Open file for append (create if doesn't exist).
+	// O_APPEND writes are atomic on POSIX for writes < PIPE_BUF (~4KB).
+	// A JSON log entry is ~200 bytes, so concurrent appends are safe.
+	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
 	if err != nil {
-		return fmt.Errorf("finding town root: %w", err)
-	}
-	if townRoot == "" {
-		return fmt.Errorf("not in a Gas Town workspace")
+		return fmt.Errorf("opening costs log: %w", err)
 	}
+	defer f.Close()
 
-	// Execute bd create from town root
-	bdCmd := exec.Command("bd", bdArgs...)
-	bdCmd.Dir = townRoot
-	output, err := bdCmd.CombinedOutput()
-	if err != nil {
-		return fmt.Errorf("creating session cost wisp: %w\nOutput: %s", err, string(output))
-	}
-
-	wispID := strings.TrimSpace(string(output))
-
-	// Auto-close session cost wisps immediately after creation.
-	// These are informational records that don't need to stay open.
-	// The wisp data is preserved and queryable until digested.
-	closeCmd := exec.Command("bd", "close", wispID, "--reason=auto-closed session cost wisp")
-	closeCmd.Dir = townRoot
-	if closeErr := closeCmd.Run(); closeErr != nil {
-		// Non-fatal: wisp was created, just couldn't auto-close
-		fmt.Fprintf(os.Stderr, "warning: could not auto-close session cost wisp %s: %v\n", wispID, closeErr)
+	// Write entry with newline
+	if _, err := f.Write(append(entryJSON, '\n')); err != nil {
+		return fmt.Errorf("writing to costs log: %w", err)
 	}
 
 	// Output confirmation (silent if cost is zero and no work item)
 	if cost > 0 || recordWorkItem != "" {
-		fmt.Printf("%s Recorded $%.2f for %s (wisp: %s)", style.Success.Render("✓"), cost, session, wispID)
+		fmt.Printf("%s Recorded $%.2f for %s", style.Success.Render("✓"), cost, session)
 		if recordWorkItem != "" {
 			fmt.Printf(" (work: %s)", recordWorkItem)
 		}
@@ -928,44 +907,6 @@ func detectCurrentTmuxSession() string {
 	return ""
 }
 
-// buildAgentPath builds the agent path from role, rig, and worker.
-// Examples: "mayor", "gastown/witness", "gastown/polecats/toast"
-func buildAgentPath(role, rig, worker string) string {
-	switch role {
-	case constants.RoleMayor, constants.RoleDeacon:
-		return role
-	case constants.RoleWitness, constants.RoleRefinery:
-		if rig != "" {
-			return rig + "/" + role
-		}
-		return role
-	case constants.RolePolecat:
-		if rig != "" && worker != "" {
-			return rig + "/polecats/" + worker
-		}
-		if rig != "" {
-			return rig + "/polecat"
-		}
-		return "polecat/" + worker
-	case constants.RoleCrew:
-		if rig != "" && worker != "" {
-			return rig + "/crew/" + worker
-		}
-		if rig != "" {
-			return rig + "/crew"
-		}
-		return "crew/" + worker
-	default:
-		if rig != "" && worker != "" {
-			return rig + "/" + worker
-		}
-		if rig != "" {
-			return rig
-		}
-		return worker
-	}
-}
-
 // CostDigest represents the aggregated daily cost report.
 type CostDigest struct {
 	Date         string             `json:"date"`
@@ -976,21 +917,7 @@ type CostDigest struct {
 	ByRig        map[string]float64 `json:"by_rig,omitempty"`
 }
 
-// WispListOutput represents the JSON output from bd mol wisp list.
-type WispListOutput struct {
-	Wisps []WispItem `json:"wisps"`
-	Count int        `json:"count"`
-}
-
-// WispItem represents a single wisp from bd mol wisp list.
-type WispItem struct {
-	ID        string    `json:"id"`
-	Title     string    `json:"title"`
-	Status    string    `json:"status"`
-	CreatedAt time.Time `json:"created_at"`
-}
-
-// runCostsDigest aggregates session cost wisps into a daily digest bead.
+// runCostsDigest aggregates session cost entries into a daily digest bead.
 func runCostsDigest(cmd *cobra.Command, args []string) error {
 	// Determine target date
 	var targetDate time.Time
@@ -1009,31 +936,31 @@ func runCostsDigest(cmd *cobra.Command, args []string) error {
 
 	dateStr := targetDate.Format("2006-01-02")
 
-	// Query ephemeral session.ended wisps for target date
-	wisps, err := querySessionCostWisps(targetDate)
+	// Query session cost entries for target date
+	costEntries, err := querySessionCostEntries(targetDate)
 	if err != nil {
-		return fmt.Errorf("querying session cost wisps: %w", err)
+		return fmt.Errorf("querying session cost entries: %w", err)
 	}
 
-	if len(wisps) == 0 {
-		fmt.Printf("%s No session cost wisps found for %s\n", style.Dim.Render("○"), dateStr)
+	if len(costEntries) == 0 {
+		fmt.Printf("%s No session cost entries found for %s\n", style.Dim.Render("○"), dateStr)
 		return nil
 	}
 
 	// Build digest
 	digest := CostDigest{
 		Date:     dateStr,
-		Sessions: wisps,
+		Sessions: costEntries,
 		ByRole:   make(map[string]float64),
 		ByRig:    make(map[string]float64),
 	}
 
-	for _, w := range wisps {
-		digest.TotalUSD += w.CostUSD
+	for _, e := range costEntries {
+		digest.TotalUSD += e.CostUSD
 		digest.SessionCount++
-		digest.ByRole[w.Role] += w.CostUSD
-		if w.Rig != "" {
-			digest.ByRig[w.Rig] += w.CostUSD
+		digest.ByRole[e.Role] += e.CostUSD
+		if e.Rig != "" {
+			digest.ByRig[e.Rig] += e.CostUSD
 		}
 	}
 
@@ -1060,105 +987,70 @@ func runCostsDigest(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("creating digest bead: %w", err)
 	}
 
-	// Delete source wisps (they're ephemeral, use bd mol burn)
-	deletedCount, deleteErr := deleteSessionCostWisps(targetDate)
+	// Delete source entries from log file
+	deletedCount, deleteErr := deleteSessionCostEntries(targetDate)
 	if deleteErr != nil {
-		fmt.Fprintf(os.Stderr, "warning: failed to delete some source wisps: %v\n", deleteErr)
+		fmt.Fprintf(os.Stderr, "warning: failed to delete some source entries: %v\n", deleteErr)
 	}
 
 	fmt.Printf("%s Created Cost Report %s (bead: %s)\n", style.Success.Render("✓"), dateStr, digestID)
 	fmt.Printf("  Total: $%.2f from %d sessions\n", digest.TotalUSD, digest.SessionCount)
 	if deletedCount > 0 {
-		fmt.Printf("  Deleted %d source wisps\n", deletedCount)
+		fmt.Printf("  Removed %d entries from costs log\n", deletedCount)
 	}
 
 	return nil
 }
 
-// querySessionCostWisps queries ephemeral session.ended events for a target date.
-func querySessionCostWisps(targetDate time.Time) ([]CostEntry, error) {
-	// List all wisps including closed ones
-	listCmd := exec.Command("bd", "mol", "wisp", "list", "--all", "--json")
-	listOutput, err := listCmd.Output()
+// querySessionCostEntries reads session cost entries from the local log file for a target date.
+func querySessionCostEntries(targetDate time.Time) ([]CostEntry, error) {
+	logPath := getCostsLogPath()
+
+	// Read log file
+	data, err := os.ReadFile(logPath)
 	if err != nil {
-		// No wisps database or command failed
-		if costsVerbose {
-			fmt.Fprintf(os.Stderr, "[costs] wisp list failed: %v\n", err)
+		if os.IsNotExist(err) {
+			return nil, nil // No log file yet
 		}
-		return nil, nil
+		return nil, fmt.Errorf("reading costs log: %w", err)
 	}
 
-	var wispList WispListOutput
-	if err := json.Unmarshal(listOutput, &wispList); err != nil {
-		return nil, fmt.Errorf("parsing wisp list: %w", err)
-	}
-
-	if wispList.Count == 0 {
-		return nil, nil
-	}
-
-	// Batch all wisp IDs into a single bd show call to avoid N+1 queries
-	showArgs := []string{"show", "--json"}
-	for _, wisp := range wispList.Wisps {
-		showArgs = append(showArgs, wisp.ID)
-	}
-
-	showCmd := exec.Command("bd", showArgs...)
-	showOutput, err := showCmd.Output()
-	if err != nil {
-		return nil, fmt.Errorf("showing wisps: %w", err)
-	}
-
-	var events []SessionEvent
-	if err := json.Unmarshal(showOutput, &events); err != nil {
-		return nil, fmt.Errorf("parsing wisp details: %w", err)
-	}
-
-	var sessionCostWisps []CostEntry
 	targetDay := targetDate.Format("2006-01-02")
+	var entries []CostEntry
 
-	for _, event := range events {
-		// Filter for session.ended events only
-		if event.EventKind != "session.ended" {
+	// Parse each line as a CostLogEntry
+	lines := strings.Split(string(data), "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
 			continue
 		}
 
-		// Parse payload
-		var payload SessionPayload
-		if event.Payload != "" {
-			if err := json.Unmarshal([]byte(event.Payload), &payload); err != nil {
-				if costsVerbose {
-					fmt.Fprintf(os.Stderr, "[costs] payload unmarshal failed for event %s: %v\n", event.ID, err)
-				}
-				continue
+		var logEntry CostLogEntry
+		if err := json.Unmarshal([]byte(line), &logEntry); err != nil {
+			if costsVerbose {
+				fmt.Fprintf(os.Stderr, "[costs] failed to parse log entry: %v\n", err)
 			}
-		}
-
-		// Parse ended_at and filter by target date
-		endedAt := event.CreatedAt
-		if payload.EndedAt != "" {
-			if parsed, err := time.Parse(time.RFC3339, payload.EndedAt); err == nil {
-				endedAt = parsed
-			}
-		}
-
-		// Check if this event is from the target date
-		if endedAt.Format("2006-01-02") != targetDay {
 			continue
 		}
 
-		sessionCostWisps = append(sessionCostWisps, CostEntry{
-			SessionID: payload.SessionID,
-			Role:      payload.Role,
-			Rig:       payload.Rig,
-			Worker:    payload.Worker,
-			CostUSD:   payload.CostUSD,
-			EndedAt:   endedAt,
-			WorkItem:  event.Target,
+		// Filter by target date
+		if logEntry.EndedAt.Format("2006-01-02") != targetDay {
+			continue
+		}
+
+		entries = append(entries, CostEntry{
+			SessionID: logEntry.SessionID,
+			Role:      logEntry.Role,
+			Rig:       logEntry.Rig,
+			Worker:    logEntry.Worker,
+			CostUSD:   logEntry.CostUSD,
+			EndedAt:   logEntry.EndedAt,
+			WorkItem:  logEntry.WorkItem,
 		})
 	}
 
-	return sessionCostWisps, nil
+	return entries, nil
 }
 
 // createCostDigestBead creates a permanent bead for the daily cost digest.
@@ -1228,96 +1120,63 @@ func createCostDigestBead(digest CostDigest) (string, error) {
 	return digestID, nil
 }
 
-// deleteSessionCostWisps deletes ephemeral session.ended wisps for a target date.
-func deleteSessionCostWisps(targetDate time.Time) (int, error) {
-	// List all wisps
-	listCmd := exec.Command("bd", "mol", "wisp", "list", "--all", "--json")
-	listOutput, err := listCmd.Output()
-	if err != nil {
-		if costsVerbose {
-			fmt.Fprintf(os.Stderr, "[costs] wisp list failed in deletion: %v\n", err)
-		}
-		return 0, nil
-	}
+// deleteSessionCostEntries removes entries for a target date from the costs log file.
+// It rewrites the file without the entries for that date.
+func deleteSessionCostEntries(targetDate time.Time) (int, error) {
+	logPath := getCostsLogPath()
 
-	var wispList WispListOutput
-	if err := json.Unmarshal(listOutput, &wispList); err != nil {
-		return 0, fmt.Errorf("parsing wisp list: %w", err)
+	// Read log file
+	data, err := os.ReadFile(logPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, nil // No log file
+		}
+		return 0, fmt.Errorf("reading costs log: %w", err)
 	}
 
 	targetDay := targetDate.Format("2006-01-02")
+	var keepLines []string
+	deletedCount := 0
 
-	// Collect all wisp IDs that match our criteria
-	var wispIDsToDelete []string
-
-	for _, wisp := range wispList.Wisps {
-		// Get full wisp details to check if it's a session.ended event
-		showCmd := exec.Command("bd", "show", wisp.ID, "--json")
-		showOutput, err := showCmd.Output()
-		if err != nil {
-			if costsVerbose {
-				fmt.Fprintf(os.Stderr, "[costs] bd show failed for wisp %s: %v\n", wisp.ID, err)
-			}
+	// Filter out entries for target date
+	lines := strings.Split(string(data), "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
 			continue
 		}
 
-		var events []SessionEvent
-		if err := json.Unmarshal(showOutput, &events); err != nil {
-			if costsVerbose {
-				fmt.Fprintf(os.Stderr, "[costs] JSON unmarshal failed for wisp %s: %v\n", wisp.ID, err)
-			}
+		var logEntry CostLogEntry
+		if err := json.Unmarshal([]byte(line), &logEntry); err != nil {
+			// Keep unparseable lines (shouldn't happen but be safe)
+			keepLines = append(keepLines, line)
 			continue
 		}
 
-		if len(events) == 0 {
+		// Remove entries from target date
+		if logEntry.EndedAt.Format("2006-01-02") == targetDay {
+			deletedCount++
 			continue
 		}
 
-		event := events[0]
-
-		// Only delete session.ended wisps
-		if event.EventKind != "session.ended" {
-			continue
-		}
-
-		// Parse payload to get ended_at for date filtering
-		var payload SessionPayload
-		if event.Payload != "" {
-			if err := json.Unmarshal([]byte(event.Payload), &payload); err != nil {
-				if costsVerbose {
-					fmt.Fprintf(os.Stderr, "[costs] payload unmarshal failed for wisp %s: %v\n", wisp.ID, err)
-				}
-				continue
-			}
-		}
-
-		endedAt := event.CreatedAt
-		if payload.EndedAt != "" {
-			if parsed, err := time.Parse(time.RFC3339, payload.EndedAt); err == nil {
-				endedAt = parsed
-			}
-		}
-
-		// Only delete wisps from the target date
-		if endedAt.Format("2006-01-02") != targetDay {
-			continue
-		}
-
-		wispIDsToDelete = append(wispIDsToDelete, wisp.ID)
+		keepLines = append(keepLines, line)
 	}
 
-	if len(wispIDsToDelete) == 0 {
+	if deletedCount == 0 {
 		return 0, nil
 	}
 
-	// Batch delete all wisps in a single subprocess call
-	burnArgs := append([]string{"mol", "burn", "--force"}, wispIDsToDelete...)
-	burnCmd := exec.Command("bd", burnArgs...)
-	if burnErr := burnCmd.Run(); burnErr != nil {
-		return 0, fmt.Errorf("batch burn failed: %w", burnErr)
+	// Rewrite file without deleted entries
+	newContent := strings.Join(keepLines, "\n")
+	if len(keepLines) > 0 {
+		newContent += "\n"
 	}
 
-	return len(wispIDsToDelete), nil
+	if err := os.WriteFile(logPath, []byte(newContent), 0644); err != nil {
+		return 0, fmt.Errorf("rewriting costs log: %w", err)
+	}
+
+	return deletedCount, nil
 }
 
 // runCostsMigrate migrates legacy session.ended beads to the new architecture.
@@ -1399,7 +1258,7 @@ func runCostsMigrate(cmd *cobra.Command, args []string) error {
 	// Close all open session.ended events
 	closedMigrated := 0
 	for _, event := range openEvents {
-		closeCmd := exec.Command("bd", "close", event.ID, "--reason=migrated to wisp architecture")
+		closeCmd := exec.Command("bd", "close", event.ID, "--reason=migrated to log-file architecture")
 		if err := closeCmd.Run(); err != nil {
 			fmt.Fprintf(os.Stderr, "warning: could not close %s: %v\n", event.ID, err)
 			continue
@@ -1409,7 +1268,7 @@ func runCostsMigrate(cmd *cobra.Command, args []string) error {
 
 	fmt.Printf("\n%s Migrated %d session.ended events (closed)\n", style.Success.Render("✓"), closedMigrated)
 	fmt.Println(style.Dim.Render("Legacy beads preserved for historical queries."))
-	fmt.Println(style.Dim.Render("New session costs will use ephemeral wisps + daily digests."))
+	fmt.Println(style.Dim.Render("New session costs will use ~/.gt/costs.jsonl + daily digests."))
 
 	return nil
 }

internal/cmd/costs_workdir_test.go

@@ -37,6 +37,11 @@ func filterGTEnv(env []string) []string {
 // 2. Creates session.ended events in both town and rig beads
 // 3. Verifies querySessionEvents finds events from both locations
 func TestQuerySessionEvents_FindsEventsFromAllLocations(t *testing.T) {
+	// Skip: bd CLI 0.47.2 has a bug where database writes don't commit
+	// ("sql: database is closed" during auto-flush). This affects all tests
+	// that create issues via bd create. See gt-lnn1xn for tracking.
+	t.Skip("bd CLI 0.47.2 bug: database writes don't commit")
+
 	// Skip if gt and bd are not installed
 	if _, err := exec.LookPath("gt"); err != nil {
 		t.Skip("gt not installed, skipping integration test")

internal/cmd/crew_add.go

@@ -106,7 +106,6 @@ func runCrewAdd(cmd *cobra.Command, args []string) error {
 				RoleType:   "crew",
 				Rig:        rigName,
 				AgentState: "idle",
-				RoleBead:   beads.RoleBeadIDTown("crew"),
 			}
 			desc := fmt.Sprintf("Crew worker %s in %s - human-managed persistent workspace.", name, rigName)
 			if _, err := bd.CreateAgentBead(crewID, desc, fields); err != nil {

internal/cmd/crew_at.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 	"github.com/steveyegge/gastown/internal/config"
@@ -15,6 +16,9 @@ import (
 	"github.com/steveyegge/gastown/internal/workspace"
 )
 
+// crewAtRetried tracks if we've already retried after stale session cleanup
+var crewAtRetried bool
+
 func runCrewAt(cmd *cobra.Command, args []string) error {
 	var name string
 
@@ -209,6 +213,10 @@ func runCrewAt(cmd *cobra.Command, args []string) error {
 		if runtimeConfig.Session != nil && runtimeConfig.Session.ConfigDirEnv != "" && claudeConfigDir != "" {
 			startupCmd = config.PrependEnv(startupCmd, map[string]string{runtimeConfig.Session.ConfigDirEnv: claudeConfigDir})
 		}
+		// Note: Don't call KillPaneProcesses here - this is a NEW session with just
+		// a fresh shell. Killing it would destroy the pane before we can respawn.
+		// KillPaneProcesses is only needed when restarting in an EXISTING session
+		// where Claude/Node processes might be running and ignoring SIGHUP.
 		if err := t.RespawnPane(paneID, startupCmd); err != nil {
 			return fmt.Errorf("starting runtime: %w", err)
 		}
@@ -242,8 +250,22 @@ func runCrewAt(cmd *cobra.Command, args []string) error {
 				Topic:     "restart",
 			})
 
+			// Ensure tmux session environment is set (for gt status-line to read).
+			// Sessions created before this was added may be missing GT_CREW, etc.
+			envVars := config.AgentEnv(config.AgentEnvConfig{
+				Role:             "crew",
+				Rig:              r.Name,
+				AgentName:        name,
+				TownRoot:         townRoot,
+				RuntimeConfigDir: claudeConfigDir,
+				BeadsNoDaemon:    true,
+			})
+			for k, v := range envVars {
+				_ = t.SetEnvironment(sessionID, k, v)
+			}
+
 			// Use respawn-pane to replace shell with runtime directly
-			// Export GT_ROLE and BD_ACTOR since tmux SetEnvironment only affects new panes
+			// Export GT_ROLE and BD_ACTOR in the command since pane inherits from shell, not session env
 			startupCmd, err := config.BuildCrewStartupCommandWithAgentOverride(r.Name, name, r.Path, beacon, crewAgentOverride)
 			if err != nil {
 				return fmt.Errorf("building startup command: %w", err)
@@ -252,7 +274,26 @@ func runCrewAt(cmd *cobra.Command, args []string) error {
 			if runtimeConfig.Session != nil && runtimeConfig.Session.ConfigDirEnv != "" && claudeConfigDir != "" {
 				startupCmd = config.PrependEnv(startupCmd, map[string]string{runtimeConfig.Session.ConfigDirEnv: claudeConfigDir})
 			}
+			// Kill all processes in the pane before respawning to prevent orphan leaks
+			// RespawnPane's -k flag only sends SIGHUP which Claude/Node may ignore
+			if err := t.KillPaneProcesses(paneID); err != nil {
+				// Non-fatal but log the warning
+				style.PrintWarning("could not kill pane processes: %v", err)
+			}
 			if err := t.RespawnPane(paneID, startupCmd); err != nil {
+				// If pane is stale (session exists but pane doesn't), recreate the session
+				if strings.Contains(err.Error(), "can't find pane") {
+					if crewAtRetried {
+						return fmt.Errorf("stale session persists after cleanup: %w", err)
+					}
+					fmt.Printf("Stale session detected, recreating...\n")
+					if killErr := t.KillSession(sessionID); killErr != nil {
+						return fmt.Errorf("failed to kill stale session: %w", killErr)
+					}
+					crewAtRetried = true
+					defer func() { crewAtRetried = false }()
+					return runCrewAt(cmd, args) // Retry with fresh session
+				}
 				return fmt.Errorf("restarting runtime: %w", err)
 			}
 		}

internal/cmd/crew_maintenance.go

@@ -28,11 +28,12 @@ func runCrewRename(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	// Kill any running session for the old name
+	// Kill any running session for the old name.
+	// Use KillSessionWithProcesses to ensure all descendant processes are killed.
 	t := tmux.NewTmux()
 	oldSessionID := crewSessionName(r.Name, oldName)
 	if hasSession, _ := t.HasSession(oldSessionID); hasSession {
-		if err := t.KillSession(oldSessionID); err != nil {
+		if err := t.KillSessionWithProcesses(oldSessionID); err != nil {
 			return fmt.Errorf("killing old session: %w", err)
 		}
 		fmt.Printf("Killed session %s\n", oldSessionID)

internal/cmd/crew_sync.go

@@ -0,0 +1,204 @@
+package cmd
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/beads"
+	"github.com/steveyegge/gastown/internal/config"
+	"github.com/steveyegge/gastown/internal/crew"
+	"github.com/steveyegge/gastown/internal/git"
+	"github.com/steveyegge/gastown/internal/rig"
+	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/workspace"
+)
+
+var crewSyncCmd = &cobra.Command{
+	Use:   "sync",
+	Short: "Create missing crew members from rigs.json config",
+	Long: `Sync crew members from rigs.json configuration.
+
+Creates any crew members defined in rigs.json that don't already exist locally.
+This enables sharing crew configuration across machines.
+
+Configuration in mayor/rigs.json:
+  {
+    "rigs": {
+      "gastown": {
+        "crew": {
+          "theme": "mad-max",
+          "members": ["diesel", "chrome", "nitro"]
+        }
+      }
+    }
+  }
+
+Examples:
+  gt crew sync                    # Sync crew in current rig
+  gt crew sync --rig gastown      # Sync crew in specific rig
+  gt crew sync --dry-run          # Show what would be created`,
+	RunE: runCrewSync,
+}
+
+func init() {
+	crewSyncCmd.Flags().StringVar(&crewRig, "rig", "", "Rig to sync crew in")
+	crewSyncCmd.Flags().BoolVar(&crewDryRun, "dry-run", false, "Show what would be created without creating")
+	crewCmd.AddCommand(crewSyncCmd)
+}
+
+func runCrewSync(cmd *cobra.Command, args []string) error {
+	// Find workspace
+	townRoot, err := workspace.FindFromCwdOrError()
+	if err != nil {
+		return fmt.Errorf("not in a Gas Town workspace: %w", err)
+	}
+
+	// Load rigs config
+	rigsConfigPath := filepath.Join(townRoot, "mayor", "rigs.json")
+	rigsConfig, err := config.LoadRigsConfig(rigsConfigPath)
+	if err != nil {
+		return fmt.Errorf("loading rigs config: %w", err)
+	}
+
+	// Determine rig
+	rigName := crewRig
+	if rigName == "" {
+		rigName, err = inferRigFromCwd(townRoot)
+		if err != nil {
+			return fmt.Errorf("could not determine rig (use --rig flag): %w", err)
+		}
+	}
+
+	// Get rig entry from rigs.json
+	rigEntry, ok := rigsConfig.Rigs[rigName]
+	if !ok {
+		return fmt.Errorf("rig '%s' not found in rigs.json", rigName)
+	}
+
+	// Check if crew config exists
+	if rigEntry.Crew == nil || len(rigEntry.Crew.Members) == 0 {
+		fmt.Printf("No crew members configured for rig '%s' in rigs.json\n", rigName)
+		fmt.Printf("\nTo configure crew, add to mayor/rigs.json:\n")
+		fmt.Printf("  \"crew\": {\n")
+		fmt.Printf("    \"theme\": \"mad-max\",\n")
+		fmt.Printf("    \"members\": [\"diesel\", \"chrome\", \"nitro\"]\n")
+		fmt.Printf("  }\n")
+		return nil
+	}
+
+	// Get rig
+	g := git.NewGit(townRoot)
+	rigMgr := rig.NewManager(townRoot, rigsConfig, g)
+	r, err := rigMgr.GetRig(rigName)
+	if err != nil {
+		return fmt.Errorf("rig '%s' not found", rigName)
+	}
+
+	// Create crew manager
+	crewGit := git.NewGit(r.Path)
+	crewMgr := crew.NewManager(r, crewGit)
+
+	bd := beads.New(beads.ResolveBeadsDir(r.Path))
+
+	// Get existing crew
+	existingCrew, err := crewMgr.List()
+	if err != nil {
+		return fmt.Errorf("listing existing crew: %w", err)
+	}
+	existingNames := make(map[string]bool)
+	for _, c := range existingCrew {
+		existingNames[c.Name] = true
+	}
+
+	// Track results
+	var created []string
+	var skipped []string
+	var failed []string
+
+	// Process each configured member
+	for _, name := range rigEntry.Crew.Members {
+		if existingNames[name] {
+			skipped = append(skipped, name)
+			continue
+		}
+
+		if crewDryRun {
+			fmt.Printf("Would create: %s/%s\n", rigName, name)
+			created = append(created, name)
+			continue
+		}
+
+		// Create crew workspace
+		fmt.Printf("Creating crew workspace %s in %s...\n", name, rigName)
+
+		worker, err := crewMgr.Add(name, false) // No feature branch for synced crew
+		if err != nil {
+			if err == crew.ErrCrewExists {
+				skipped = append(skipped, name)
+				continue
+			}
+			style.PrintWarning("creating crew workspace '%s': %v", name, err)
+			failed = append(failed, name)
+			continue
+		}
+
+		fmt.Printf("%s Created crew workspace: %s/%s\n",
+			style.Bold.Render("\u2713"), rigName, name)
+		fmt.Printf("  Path: %s\n", worker.ClonePath)
+		fmt.Printf("  Branch: %s\n", worker.Branch)
+
+		// Create agent bead for the crew worker
+		prefix := beads.GetPrefixForRig(townRoot, rigName)
+		crewID := beads.CrewBeadIDWithPrefix(prefix, rigName, name)
+		if _, err := bd.Show(crewID); err != nil {
+			// Agent bead doesn't exist, create it
+			fields := &beads.AgentFields{
+				RoleType:   "crew",
+				Rig:        rigName,
+				AgentState: "idle",
+			}
+			desc := fmt.Sprintf("Crew worker %s in %s - synced from rigs.json.", name, rigName)
+			if _, err := bd.CreateAgentBead(crewID, desc, fields); err != nil {
+				style.PrintWarning("could not create agent bead for %s: %v", name, err)
+			} else {
+				fmt.Printf("  Agent bead: %s\n", crewID)
+			}
+		}
+
+		created = append(created, name)
+		fmt.Println()
+	}
+
+	// Summary
+	if crewDryRun {
+		fmt.Printf("\n%s Dry run complete\n", style.Bold.Render("\u2713"))
+		if len(created) > 0 {
+			fmt.Printf("  Would create: %v\n", created)
+		}
+		if len(skipped) > 0 {
+			fmt.Printf("  Already exist: %v\n", skipped)
+		}
+		return nil
+	}
+
+	if len(created) > 0 {
+		fmt.Printf("%s Created %d crew workspace(s): %v\n",
+			style.Bold.Render("\u2713"), len(created), created)
+	}
+	if len(skipped) > 0 {
+		fmt.Printf("%s Skipped %d (already exist): %v\n",
+			style.Dim.Render("-"), len(skipped), skipped)
+	}
+	if len(failed) > 0 {
+		fmt.Printf("%s Failed to create %d: %v\n",
+			style.Warning.Render("!"), len(failed), failed)
+	}
+
+	// Show theme if configured
+	if rigEntry.Crew.Theme != "" {
+		fmt.Printf("\nCrew theme: %s\n", rigEntry.Crew.Theme)
+	}
+
+	return nil
+}

internal/cmd/deacon.go

@@ -264,6 +264,30 @@ Example:
 	RunE: runDeaconCleanupOrphans,
 }
 
+var deaconZombieScanCmd = &cobra.Command{
+	Use:   "zombie-scan",
+	Short: "Find and clean zombie Claude processes not in active tmux sessions",
+	Long: `Find and clean zombie Claude processes not in active tmux sessions.
+
+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
+
+This catches "ghost" processes that have a TTY (from a dead tmux session)
+but are no longer part of any active Gas Town session.
+
+Examples:
+  gt deacon zombie-scan           # Find and kill zombies
+  gt deacon zombie-scan --dry-run # Just list zombies, don't kill`,
+	RunE: runDeaconZombieScan,
+}
+
 var (
 	triggerTimeout time.Duration
 
@@ -282,6 +306,9 @@ var (
 
 	// Pause flags
 	pauseReason string
+
+	// Zombie scan flags
+	zombieScanDryRun bool
 )
 
 func init() {
@@ -299,6 +326,7 @@ func init() {
 	deaconCmd.AddCommand(deaconPauseCmd)
 	deaconCmd.AddCommand(deaconResumeCmd)
 	deaconCmd.AddCommand(deaconCleanupOrphansCmd)
+	deaconCmd.AddCommand(deaconZombieScanCmd)
 
 	// Flags for trigger-pending
 	deaconTriggerPendingCmd.Flags().DurationVar(&triggerTimeout, "timeout", 2*time.Second,
@@ -328,6 +356,10 @@ func init() {
 	deaconPauseCmd.Flags().StringVar(&pauseReason, "reason", "",
 		"Reason for pausing the Deacon")
 
+	// Flags for zombie-scan
+	deaconZombieScanCmd.Flags().BoolVar(&zombieScanDryRun, "dry-run", false,
+		"List zombies without killing them")
+
 	deaconStartCmd.Flags().StringVar(&deaconAgentOverride, "agent", "", "Agent alias to run the Deacon with (overrides town default)")
 	deaconAttachCmd.Flags().StringVar(&deaconAgentOverride, "agent", "", "Agent alias to run the Deacon with (overrides town default)")
 	deaconRestartCmd.Flags().StringVar(&deaconAgentOverride, "agent", "", "Agent alias to run the Deacon with (overrides town default)")
@@ -459,8 +491,9 @@ func runDeaconStop(cmd *cobra.Command, args []string) error {
 	_ = t.SendKeysRaw(sessionName, "C-c")
 	time.Sleep(100 * time.Millisecond)
 
-	// Kill the session
-	if err := t.KillSession(sessionName); err != nil {
+	// Kill the session.
+	// Use KillSessionWithProcesses to ensure all descendant processes are killed.
+	if err := t.KillSessionWithProcesses(sessionName); err != nil {
 		return fmt.Errorf("killing session: %w", err)
 	}
 
@@ -560,8 +593,9 @@ func runDeaconRestart(cmd *cobra.Command, args []string) error {
 	fmt.Println("Restarting Deacon...")
 
 	if running {
-		// Kill existing session
-		if err := t.KillSession(sessionName); err != nil {
+		// Kill existing session.
+		// Use KillSessionWithProcesses to ensure all descendant processes are killed.
+		if err := t.KillSessionWithProcesses(sessionName); err != nil {
 			style.PrintWarning("failed to kill session: %v", err)
 		}
 	}
@@ -844,9 +878,10 @@ func runDeaconForceKill(cmd *cobra.Command, args []string) error {
 	mailBody := fmt.Sprintf("Deacon detected %s as unresponsive.\nReason: %s\nAction: force-killing session", agent, reason)
 	sendMail(townRoot, agent, "FORCE_KILL: unresponsive", mailBody)
 
-	// Step 2: Kill the tmux session
+	// Step 2: Kill the tmux session.
+	// Use KillSessionWithProcesses to ensure all descendant processes are killed.
 	fmt.Printf("%s Killing tmux session %s...\n", style.Dim.Render("2."), sessionName)
-	if err := t.KillSession(sessionName); err != nil {
+	if err := t.KillSessionWithProcesses(sessionName); err != nil {
 		return fmt.Errorf("killing session: %w", err)
 	}
 
@@ -1185,3 +1220,68 @@ func runDeaconCleanupOrphans(cmd *cobra.Command, args []string) error {
 
 	return nil
 }
+
+// runDeaconZombieScan finds and cleans zombie Claude processes not in active tmux sessions.
+func runDeaconZombieScan(cmd *cobra.Command, args []string) error {
+	// Find zombies using tmux verification
+	zombies, err := util.FindZombieClaudeProcesses()
+	if err != nil {
+		return fmt.Errorf("finding zombie processes: %w", err)
+	}
+
+	if len(zombies) == 0 {
+		fmt.Printf("%s No zombie claude processes found\n", style.Dim.Render("○"))
+		return nil
+	}
+
+	fmt.Printf("%s Found %d zombie claude process(es)\n", style.Bold.Render("●"), len(zombies))
+
+	// In dry-run mode, just list them
+	if zombieScanDryRun {
+		for _, z := range zombies {
+			ageStr := fmt.Sprintf("%dm", z.Age/60)
+			fmt.Printf("  %s PID %d (%s) TTY=%s age=%s\n",
+				style.Dim.Render("→"), z.PID, z.Cmd, z.TTY, ageStr)
+		}
+		fmt.Printf("%s Dry run - no processes killed\n", style.Dim.Render("○"))
+		return nil
+	}
+
+	// Process them with signal escalation
+	results, err := util.CleanupZombieClaudeProcesses()
+	if err != nil {
+		style.PrintWarning("cleanup had errors: %v", err)
+	}
+
+	// Report results
+	var terminated, escalated, unkillable int
+	for _, r := range results {
+		switch r.Signal {
+		case "SIGTERM":
+			fmt.Printf("  %s Sent SIGTERM to PID %d (%s) TTY=%s\n",
+				style.Bold.Render("→"), r.Process.PID, r.Process.Cmd, r.Process.TTY)
+			terminated++
+		case "SIGKILL":
+			fmt.Printf("  %s Escalated to SIGKILL for PID %d (%s)\n",
+				style.Bold.Render("!"), r.Process.PID, r.Process.Cmd)
+			escalated++
+		case "UNKILLABLE":
+			fmt.Printf("  %s WARNING: PID %d (%s) survived SIGKILL\n",
+				style.Bold.Render("⚠"), r.Process.PID, r.Process.Cmd)
+			unkillable++
+		}
+	}
+
+	if len(results) > 0 {
+		summary := fmt.Sprintf("Processed %d zombie(s)", len(results))
+		if escalated > 0 {
+			summary += fmt.Sprintf(" (%d escalated to SIGKILL)", escalated)
+		}
+		if unkillable > 0 {
+			summary += fmt.Sprintf(" (%d unkillable)", unkillable)
+		}
+		fmt.Printf("%s %s\n", style.Bold.Render("✓"), summary)
+	}
+
+	return nil
+}

internal/cmd/doctor.go

@@ -134,10 +134,12 @@ func runDoctor(cmd *cobra.Command, args []string) error {
 	d.Register(doctor.NewPrefixMismatchCheck())
 	d.Register(doctor.NewRoutesCheck())
 	d.Register(doctor.NewRigRoutesJSONLCheck())
+	d.Register(doctor.NewRoutingModeCheck())
 	d.Register(doctor.NewOrphanSessionCheck())
 	d.Register(doctor.NewZombieSessionCheck())
 	d.Register(doctor.NewOrphanProcessCheck())
 	d.Register(doctor.NewWispGCCheck())
+	d.Register(doctor.NewCheckMisclassifiedWisps())
 	d.Register(doctor.NewBranchCheck())
 	d.Register(doctor.NewBeadsSyncOrphanCheck())
 	d.Register(doctor.NewCloneDivergenceCheck())

internal/cmd/dog.go

@@ -182,6 +182,22 @@ Examples:
 	RunE: runDogDispatch,
 }
 
+var dogDoneCmd = &cobra.Command{
+	Use:   "done [name]",
+	Short: "Mark a dog as idle (work complete)",
+	Long: `Mark a dog as idle after completing its work.
+
+Dogs call this command after finishing plugin execution to reset their state
+to idle, allowing them to receive new work dispatches.
+
+If no name is provided, attempts to detect the current dog from BD_ACTOR.
+
+Examples:
+  gt dog done alpha     # Explicit dog name
+  gt dog done           # Auto-detect from BD_ACTOR (e.g., "deacon/dogs/alpha")`,
+	RunE: runDogDone,
+}
+
 func init() {
 	// List flags
 	dogListCmd.Flags().BoolVar(&dogListJSON, "json", false, "Output as JSON")
@@ -212,6 +228,7 @@ func init() {
 	dogCmd.AddCommand(dogCallCmd)
 	dogCmd.AddCommand(dogStatusCmd)
 	dogCmd.AddCommand(dogDispatchCmd)
+	dogCmd.AddCommand(dogDoneCmd)
 
 	rootCmd.AddCommand(dogCmd)
 }
@@ -500,6 +517,34 @@ func runDogStatus(cmd *cobra.Command, args []string) error {
 	return showPackStatus(mgr)
 }
 
+func runDogDone(cmd *cobra.Command, args []string) error {
+	mgr, err := getDogManager()
+	if err != nil {
+		return err
+	}
+
+	var name string
+	if len(args) > 0 {
+		name = args[0]
+	} else {
+		// Try to detect from BD_ACTOR (e.g., "deacon/dogs/alpha")
+		actor := os.Getenv("BD_ACTOR")
+		if actor != "" && strings.HasPrefix(actor, "deacon/dogs/") {
+			name = strings.TrimPrefix(actor, "deacon/dogs/")
+		}
+		if name == "" {
+			return fmt.Errorf("no dog name provided and could not detect from BD_ACTOR")
+		}
+	}
+
+	if err := mgr.ClearWork(name); err != nil {
+		return fmt.Errorf("marking dog %s as done: %w", name, err)
+	}
+
+	fmt.Printf("✓ %s marked as idle (ready for new work)\n", name)
+	return nil
+}
+
 func showDogStatus(mgr *dog.Manager, name string) error {
 	d, err := mgr.Get(name)
 	if err != nil {
@@ -791,6 +836,35 @@ func runDogDispatch(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("sending plugin mail to dog: %w", err)
 	}
 
+	// Spawn a session for the dog to execute the work.
+	// Without a session, the dog's mail inbox is never checked.
+	// See: https://github.com/steveyegge/gastown/issues/XXX (dog dispatch doesn't execute)
+	t := tmux.NewTmux()
+	townName, err := workspace.GetTownName(townRoot)
+	if err != nil {
+		townName = "gt" // fallback
+	}
+	dogSessionName := fmt.Sprintf("gt-%s-deacon-%s", townName, targetDog.Name)
+
+	// Kill any stale session first
+	if has, _ := t.HasSession(dogSessionName); has {
+		_ = t.KillSessionWithProcesses(dogSessionName)
+	}
+
+	// Build startup command with initial prompt to check mail and execute plugin
+	// Use BuildDogStartupCommand to properly set BD_ACTOR=deacon/dogs/<name> in the startup command
+	initialPrompt := fmt.Sprintf("I am dog %s. Check my mail inbox with 'gt mail inbox' and execute the plugin instructions I received.", targetDog.Name)
+	startCmd := config.BuildDogStartupCommand(targetDog.Name, townRoot, targetDog.Path, initialPrompt)
+
+	// Create session from dog's directory
+	if err := t.NewSessionWithCommand(dogSessionName, targetDog.Path, startCmd); err != nil {
+		if !dogDispatchJSON {
+			fmt.Printf("  Warning: could not spawn dog session: %v\n", err)
+		}
+		// Non-fatal: mail was sent, dog is marked as working, but no session to execute
+		// The deacon or human can manually start the session later
+	}
+
 	// Success - output result
 	if dogDispatchJSON {
 		return json.NewEncoder(os.Stdout).Encode(result)

internal/cmd/done.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -81,6 +82,14 @@ func init() {
 }
 
 func runDone(cmd *cobra.Command, args []string) error {
+	// Guard: Only polecats should call gt done
+	// Crew, deacons, witnesses etc. don't use gt done - they persist across tasks.
+	// Polecats are ephemeral workers that self-destruct after completing work.
+	actor := os.Getenv("BD_ACTOR")
+	if actor != "" && !isPolecatActor(actor) {
+		return fmt.Errorf("gt done is for polecats only (you are %s)\nPolecats are ephemeral workers that self-destruct after completing work.\nOther roles persist across tasks and don't use gt done.", actor)
+	}
+
 	// Handle --phase-complete flag (overrides --status)
 	var exitType string
 	if donePhaseComplete {
@@ -259,19 +268,29 @@ func runDone(cmd *cobra.Command, args []string) error {
 			return fmt.Errorf("cannot complete: uncommitted changes would be lost\nCommit your changes first, or use --status DEFERRED to exit without completing\nUncommitted: %s", workStatus.String())
 		}
 
-		// Check that branch has commits ahead of origin/default (not local default)
-		// This ensures we compare against the remote, not a potentially stale local copy
+		// Check if branch has commits ahead of origin/default
+		// If not, work may have been pushed directly to main - that's fine, just skip MR
 		originDefault := "origin/" + defaultBranch
 		aheadCount, err := g.CommitsAhead(originDefault, "HEAD")
 		if err != nil {
 			// Fallback to local branch comparison if origin not available
 			aheadCount, err = g.CommitsAhead(defaultBranch, branch)
 			if err != nil {
-				return fmt.Errorf("checking commits ahead of %s: %w", defaultBranch, err)
+				// Can't determine - assume work exists and continue
+				style.PrintWarning("could not check commits ahead of %s: %v", defaultBranch, err)
+				aheadCount = 1
 			}
 		}
+
+		// If no commits ahead, work was likely pushed directly to main (or already merged)
+		// This is valid - skip MR creation but still complete successfully
 		if aheadCount == 0 {
-			return fmt.Errorf("branch '%s' has 0 commits ahead of %s; nothing to merge\nMake and commit changes first, or use --status DEFERRED to exit without completing", branch, originDefault)
+			fmt.Printf("%s Branch has no commits ahead of %s\n", style.Bold.Render("→"), originDefault)
+			fmt.Printf("  Work was likely pushed directly to main or already merged.\n")
+			fmt.Printf("  Skipping MR creation - completing without merge request.\n\n")
+
+			// Skip straight to witness notification (no MR needed)
+			goto notifyWitness
 		}
 
 		// CRITICAL: Push branch BEFORE creating MR bead (hq-6dk53, hq-a4ksk)
@@ -401,6 +420,7 @@ func runDone(cmd *cobra.Command, args []string) error {
 		fmt.Printf("  Branch: %s\n", branch)
 	}
 
+notifyWitness:
 	// Notify Witness about completion
 	// Use town-level beads for cross-agent mail
 	townRouter := mail.NewRouter(townRoot)
@@ -462,27 +482,28 @@ func runDone(cmd *cobra.Command, args []string) error {
 	// This is the self-cleaning model - polecats clean up after themselves
 	// "done means gone" - both worktree and session are terminated
 	selfCleanAttempted := false
-	if exitType == ExitCompleted {
-		if roleInfo, err := GetRoleWithContext(cwd, townRoot); err == nil && roleInfo.Role == RolePolecat {
-			selfCleanAttempted = true
+	if roleInfo, err := GetRoleWithContext(cwd, townRoot); err == nil && roleInfo.Role == RolePolecat {
+		selfCleanAttempted = true
 
-			// Step 1: Nuke the worktree
+		// Step 1: Nuke the worktree (only for COMPLETED - other statuses preserve work)
+		if exitType == ExitCompleted {
 			if err := selfNukePolecat(roleInfo, townRoot); err != nil {
 				// Non-fatal: Witness will clean up if we fail
 				style.PrintWarning("worktree nuke failed: %v (Witness will clean up)", err)
 			} else {
 				fmt.Printf("%s Worktree nuked\n", style.Bold.Render("✓"))
 			}
-
-			// Step 2: Kill our own session (this terminates Claude and the shell)
-			// This is the last thing we do - the process will be killed when tmux session dies
-			fmt.Printf("%s Terminating session (done means gone)\n", style.Bold.Render("→"))
-			if err := selfKillSession(townRoot, roleInfo); err != nil {
-				// If session kill fails, fall through to os.Exit
-				style.PrintWarning("session kill failed: %v", err)
-			}
-			// If selfKillSession succeeds, we won't reach here (process killed by tmux)
 		}
+
+		// Step 2: Kill our own session (this terminates Claude and the shell)
+		// This is the last thing we do - the process will be killed when tmux session dies
+		// All exit types kill the session - "done means gone"
+		fmt.Printf("%s Terminating session (done means gone)\n", style.Bold.Render("→"))
+		if err := selfKillSession(townRoot, roleInfo); err != nil {
+			// If session kill fails, fall through to os.Exit
+			style.PrintWarning("session kill failed: %v", err)
+		}
+		// If selfKillSession succeeds, we won't reach here (process killed by tmux)
 	}
 
 	// Fallback exit for non-polecats or if self-clean failed
@@ -582,6 +603,29 @@ func updateAgentStateOnDone(cwd, townRoot, exitType, _ string) { // issueID unus
 		hookedBeadID := agentBead.HookBead
 		// Only close if the hooked bead exists and is still in "hooked" status
 		if hookedBead, err := bd.Show(hookedBeadID); err == nil && hookedBead.Status == beads.StatusHooked {
+			// BUG FIX: Close attached molecule (wisp) BEFORE closing hooked bead.
+			// When using formula-on-bead (gt sling formula --on bead), the base bead
+			// has attached_molecule pointing to the wisp. Without this fix, gt done
+			// only closed the hooked bead, leaving the wisp orphaned.
+			// Order matters: wisp closes -> unblocks base bead -> base bead closes.
+			//
+			// BUG FIX (gt-zbnr): Close child wisps BEFORE closing the molecule itself.
+			// Deacon patrol molecules have child step wisps that were being orphaned
+			// when the patrol completed. Now we cascade-close all descendants first.
+			attachment := beads.ParseAttachmentFields(hookedBead)
+			if attachment != nil && attachment.AttachedMolecule != "" {
+				moleculeID := attachment.AttachedMolecule
+				// Cascade-close all child wisps before closing the molecule
+				childrenClosed := closeDescendants(bd, moleculeID)
+				if childrenClosed > 0 {
+					fmt.Printf("  Closed %d child step issues\n", childrenClosed)
+				}
+				if err := bd.Close(moleculeID); err != nil {
+					// Non-fatal: warn but continue
+					fmt.Fprintf(os.Stderr, "Warning: couldn't close attached molecule %s: %v\n", moleculeID, err)
+				}
+			}
+
 			if err := bd.Close(hookedBeadID); err != nil {
 				// Non-fatal: warn but continue
 				fmt.Fprintf(os.Stderr, "Warning: couldn't close hooked bead %s: %v\n", hookedBeadID, err)
@@ -611,7 +655,7 @@ func updateAgentStateOnDone(cwd, townRoot, exitType, _ string) { // issueID unus
 		if _, err := bd.Run("agent", "state", agentBeadID, "awaiting-gate"); err != nil {
 			fmt.Fprintf(os.Stderr, "Warning: couldn't set agent %s to awaiting-gate: %v\n", agentBeadID, err)
 		}
-	// ExitCompleted and ExitDeferred don't set state - observable from tmux
+		// ExitCompleted and ExitDeferred don't set state - observable from tmux
 	}
 
 	// ZFC #10: Self-report cleanup status
@@ -706,6 +750,14 @@ func selfNukePolecat(roleInfo RoleInfo, _ string) error {
 	return nil
 }
 
+// isPolecatActor checks if a BD_ACTOR value represents a polecat.
+// Polecat actors have format: rigname/polecats/polecatname
+// Non-polecat actors have formats like: gastown/crew/name, rigname/witness, etc.
+func isPolecatActor(actor string) bool {
+	parts := strings.Split(actor, "/")
+	return len(parts) >= 2 && parts[1] == "polecats"
+}
+
 // selfKillSession terminates the polecat's own tmux session after logging the event.
 // This completes the self-cleaning model: "done means gone" - both worktree and session.
 //
@@ -745,9 +797,12 @@ func selfKillSession(townRoot string, roleInfo RoleInfo) error {
 
 	// Kill our own tmux session with proper process cleanup
 	// This will terminate Claude and all child processes, completing the self-cleaning cycle.
-	// We use KillSessionWithProcesses to ensure no orphaned processes are left behind.
+	// We use KillSessionWithProcessesExcluding to ensure no orphaned processes are left behind,
+	// while excluding our own PID to avoid killing ourselves before cleanup completes.
+	// The tmux kill-session at the end will terminate us along with the session.
 	t := tmux.NewTmux()
-	if err := t.KillSessionWithProcesses(sessionName); err != nil {
+	myPID := strconv.Itoa(os.Getpid())
+	if err := t.KillSessionWithProcessesExcluding(sessionName, []string{myPID}); err != nil {
 		return fmt.Errorf("killing session %s: %w", sessionName, err)
 	}
 

internal/cmd/done_test.go

@@ -341,3 +341,39 @@ func TestGetIssueFromAgentHook(t *testing.T) {
 		})
 	}
 }
+
+// TestIsPolecatActor verifies that isPolecatActor correctly identifies
+// polecat actors vs other roles based on the BD_ACTOR format.
+func TestIsPolecatActor(t *testing.T) {
+	tests := []struct {
+		actor string
+		want  bool
+	}{
+		// Polecats: rigname/polecats/polecatname
+		{"testrig/polecats/furiosa", true},
+		{"testrig/polecats/nux", true},
+		{"myrig/polecats/witness", true}, // even if named "witness", still a polecat
+
+		// Non-polecats
+		{"gastown/crew/george", false},
+		{"gastown/crew/max", false},
+		{"testrig/witness", false},
+		{"testrig/deacon", false},
+		{"testrig/mayor", false},
+		{"gastown/refinery", false},
+
+		// Edge cases
+		{"", false},
+		{"single", false},
+		{"polecats/name", false}, // needs rig prefix
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.actor, func(t *testing.T) {
+			got := isPolecatActor(tt.actor)
+			if got != tt.want {
+				t.Errorf("isPolecatActor(%q) = %v, want %v", tt.actor, got, tt.want)
+			}
+		})
+	}
+}

internal/cmd/down.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"time"
@@ -111,9 +112,6 @@ func runDown(cmd *cobra.Command, args []string) error {
 
 	rigs := discoverRigs(townRoot)
 
-	// Pre-fetch all sessions once for O(1) lookups (avoids N+1 subprocess calls)
-	sessionSet, _ := t.GetSessionSet() // Ignore error - empty set is safe fallback
-
 	// Phase 0.5: Stop polecats if --polecats
 	if downPolecats {
 		if downDryRun {
@@ -170,12 +168,12 @@ func runDown(cmd *cobra.Command, args []string) error {
 	for _, rigName := range rigs {
 		sessionName := fmt.Sprintf("gt-%s-refinery", rigName)
 		if downDryRun {
-			if sessionSet.Has(sessionName) {
+			if running, _ := t.HasSession(sessionName); running {
 				printDownStatus(fmt.Sprintf("Refinery (%s)", rigName), true, "would stop")
 			}
 			continue
 		}
-		wasRunning, err := stopSessionWithCache(t, sessionName, sessionSet)
+		wasRunning, err := stopSession(t, sessionName)
 		if err != nil {
 			printDownStatus(fmt.Sprintf("Refinery (%s)", rigName), false, err.Error())
 			allOK = false
@@ -190,12 +188,12 @@ func runDown(cmd *cobra.Command, args []string) error {
 	for _, rigName := range rigs {
 		sessionName := fmt.Sprintf("gt-%s-witness", rigName)
 		if downDryRun {
-			if sessionSet.Has(sessionName) {
+			if running, _ := t.HasSession(sessionName); running {
 				printDownStatus(fmt.Sprintf("Witness (%s)", rigName), true, "would stop")
 			}
 			continue
 		}
-		wasRunning, err := stopSessionWithCache(t, sessionName, sessionSet)
+		wasRunning, err := stopSession(t, sessionName)
 		if err != nil {
 			printDownStatus(fmt.Sprintf("Witness (%s)", rigName), false, err.Error())
 			allOK = false
@@ -209,12 +207,12 @@ func runDown(cmd *cobra.Command, args []string) error {
 	// Phase 3: Stop town-level sessions (Mayor, Boot, Deacon)
 	for _, ts := range session.TownSessions() {
 		if downDryRun {
-			if sessionSet.Has(ts.SessionID) {
+			if running, _ := t.HasSession(ts.SessionID); running {
 				printDownStatus(ts.Name, true, "would stop")
 			}
 			continue
 		}
-		stopped, err := session.StopTownSessionWithCache(t, ts, downForce, sessionSet)
+		stopped, err := session.StopTownSession(t, ts, downForce)
 		if err != nil {
 			printDownStatus(ts.Name, false, err.Error())
 			allOK = false
@@ -399,23 +397,6 @@ func stopSession(t *tmux.Tmux, sessionName string) (bool, error) {
 	return true, t.KillSessionWithProcesses(sessionName)
 }
 
-// stopSessionWithCache is like stopSession but uses a pre-fetched SessionSet
-// for O(1) existence check instead of spawning a subprocess.
-func stopSessionWithCache(t *tmux.Tmux, sessionName string, cache *tmux.SessionSet) (bool, error) {
-	if !cache.Has(sessionName) {
-		return false, nil // Already stopped
-	}
-
-	// Try graceful shutdown first (Ctrl-C, best-effort interrupt)
-	if !downForce {
-		_ = t.SendKeysRaw(sessionName, "C-c")
-		time.Sleep(100 * time.Millisecond)
-	}
-
-	// Kill the session (with explicit process termination to prevent orphans)
-	return true, t.KillSessionWithProcesses(sessionName)
-}
-
 // acquireShutdownLock prevents concurrent shutdowns.
 // Returns the lock (caller must defer Unlock()) or error if lock held.
 func acquireShutdownLock(townRoot string) (*flock.Flock, error) {
@@ -474,5 +455,65 @@ func verifyShutdown(t *tmux.Tmux, townRoot string) []string {
 		}
 	}
 
+	// Check for orphaned Claude/node processes
+	// These can be left behind if tmux sessions were killed but child processes didn't terminate
+	if pids := findOrphanedClaudeProcesses(townRoot); len(pids) > 0 {
+		respawned = append(respawned, fmt.Sprintf("orphaned Claude processes (PIDs: %v)", pids))
+	}
+
 	return respawned
 }
+
+// findOrphanedClaudeProcesses finds Claude/node processes that are running in the
+// town directory but aren't associated with any active tmux session.
+// This can happen when tmux sessions are killed but child processes don't terminate.
+func findOrphanedClaudeProcesses(townRoot string) []int {
+	// Use pgrep to find all claude/node processes
+	cmd := exec.Command("pgrep", "-l", "node")
+	output, err := cmd.Output()
+	if err != nil {
+		return nil // pgrep found no processes or failed
+	}
+
+	var orphaned []int
+	lines := strings.Split(string(output), "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		// Format: "PID command"
+		parts := strings.Fields(line)
+		if len(parts) < 2 {
+			continue
+		}
+		pidStr := parts[0]
+		var pid int
+		if _, err := fmt.Sscanf(pidStr, "%d", &pid); err != nil {
+			continue
+		}
+
+		// Check if this process is running in the town directory
+		if isProcessInTown(pid, townRoot) {
+			orphaned = append(orphaned, pid)
+		}
+	}
+
+	return orphaned
+}
+
+// isProcessInTown checks if a process is running in the given town directory.
+// Uses ps to check the process's working directory.
+func isProcessInTown(pid int, townRoot string) bool {
+	// Use ps to get the process's working directory
+	cmd := exec.Command("ps", "-o", "command=", "-p", fmt.Sprintf("%d", pid))
+	output, err := cmd.Output()
+	if err != nil {
+		return false
+	}
+
+	// Check if the command line includes the town path
+	command := string(output)
+	return strings.Contains(command, townRoot)
+}
+

internal/cmd/focus.go

@@ -0,0 +1,351 @@
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/workspace"
+)
+
+var focusJSON bool
+var focusAll bool
+var focusLimit int
+
+var focusCmd = &cobra.Command{
+	Use:     "focus",
+	GroupID: GroupWork,
+	Short:   "Show what needs attention (stalest high-priority goals)",
+	Long: `Show what the overseer should focus on next.
+
+Analyzes active epics (goals) and sorts them by staleness × priority.
+Items that haven't moved in a while and have high priority appear first.
+
+Staleness indicators:
+  🔴 stuck  - no movement for 4+ hours (high urgency)
+  🟡 stale  - no movement for 1-4 hours (needs attention)
+  🟢 active - moved within the last hour (probably fine)
+
+Examples:
+  gt focus              # Top 5 suggestions
+  gt focus --all        # All active goals with staleness
+  gt focus --limit=10   # Top 10 suggestions
+  gt focus --json       # Machine-readable output`,
+	RunE: runFocus,
+}
+
+func init() {
+	focusCmd.Flags().BoolVar(&focusJSON, "json", false, "Output as JSON")
+	focusCmd.Flags().BoolVar(&focusAll, "all", false, "Show all active goals (not just top N)")
+	focusCmd.Flags().IntVarP(&focusLimit, "limit", "n", 5, "Number of suggestions to show")
+	rootCmd.AddCommand(focusCmd)
+}
+
+// FocusItem represents a goal that needs attention.
+type FocusItem struct {
+	ID             string  `json:"id"`
+	Title          string  `json:"title"`
+	Priority       int     `json:"priority"`
+	Status         string  `json:"status"`
+	Staleness      string  `json:"staleness"`       // "active", "stale", "stuck"
+	StalenessHours float64 `json:"staleness_hours"` // Hours since last movement
+	Score          float64 `json:"score"`           // priority × staleness_hours
+	UpdatedAt      string  `json:"updated_at"`
+	Assignee       string  `json:"assignee,omitempty"`
+	DrillDown      string  `json:"drill_down"` // Suggested command
+}
+
+func runFocus(cmd *cobra.Command, args []string) error {
+	// Find town root to query both town and rig beads
+	townRoot, err := workspace.FindFromCwdOrError()
+	if err != nil {
+		return fmt.Errorf("not in a Gas Town workspace: %w", err)
+	}
+
+	// Collect epics from town beads and all rig beads
+	items, err := collectFocusItems(townRoot)
+	if err != nil {
+		return err
+	}
+
+	if len(items) == 0 {
+		fmt.Println("No active goals found.")
+		fmt.Println("Goals are epics with open status. Create one with: bd create --type=epic \"Goal name\"")
+		return nil
+	}
+
+	// Sort by score (highest first)
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].Score > items[j].Score
+	})
+
+	// Apply limit
+	if !focusAll && len(items) > focusLimit {
+		items = items[:focusLimit]
+	}
+
+	if focusJSON {
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		return enc.Encode(items)
+	}
+
+	return outputFocusText(items)
+}
+
+// collectFocusItems gathers epics from all beads databases in the town.
+func collectFocusItems(townRoot string) ([]FocusItem, error) {
+	var items []FocusItem
+	seenIDs := make(map[string]bool) // Dedupe across databases
+
+	// 1. Query town beads (hq-* prefix)
+	townBeads := filepath.Join(townRoot, ".beads")
+	if _, err := os.Stat(townBeads); err == nil {
+		townItems := queryEpicsFromBeads(townBeads)
+		for _, item := range townItems {
+			if !seenIDs[item.ID] {
+				items = append(items, item)
+				seenIDs[item.ID] = true
+			}
+		}
+	}
+
+	// 2. Query each rig's beads (gt-*, bd-*, sc-* etc. prefixes)
+	rigDirs, _ := filepath.Glob(filepath.Join(townRoot, "*", "mayor", "rig", ".beads"))
+	for _, rigBeads := range rigDirs {
+		rigItems := queryEpicsFromBeads(rigBeads)
+		for _, item := range rigItems {
+			if !seenIDs[item.ID] {
+				items = append(items, item)
+				seenIDs[item.ID] = true
+			}
+		}
+	}
+
+	return items, nil
+}
+
+// queryEpicsFromBeads queries a beads database for open epics.
+func queryEpicsFromBeads(beadsPath string) []FocusItem {
+	var items []FocusItem
+
+	// Use bd to query epics
+	listCmd := exec.Command("bd", "list", "--type=epic", "--status=open", "--json")
+	listCmd.Dir = beadsPath
+	var stdout bytes.Buffer
+	listCmd.Stdout = &stdout
+
+	if err := listCmd.Run(); err != nil {
+		// Also try in_progress and hooked statuses
+		return items
+	}
+
+	var epics []struct {
+		ID        string   `json:"id"`
+		Title     string   `json:"title"`
+		Status    string   `json:"status"`
+		Priority  int      `json:"priority"`
+		UpdatedAt string   `json:"updated_at"`
+		Assignee  string   `json:"assignee,omitempty"`
+		Labels    []string `json:"labels,omitempty"`
+		Ephemeral bool     `json:"ephemeral,omitempty"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &epics); err != nil {
+		return items
+	}
+
+	now := time.Now()
+
+	for _, epic := range epics {
+		// Skip ephemeral issues (molecules, wisps, etc.) - these aren't real goals
+		if epic.Ephemeral {
+			continue
+		}
+		// Also skip by ID pattern - wisps have "wisp" in the ID
+		if strings.Contains(epic.ID, "wisp") || strings.Contains(epic.ID, "-mol-") {
+			continue
+		}
+
+		item := FocusItem{
+			ID:        epic.ID,
+			Title:     strings.TrimPrefix(epic.Title, "[EPIC] "),
+			Priority:  epic.Priority,
+			Status:    epic.Status,
+			UpdatedAt: epic.UpdatedAt,
+			Assignee:  epic.Assignee,
+		}
+
+		// Calculate staleness
+		if epic.UpdatedAt != "" {
+			if updated, err := time.Parse(time.RFC3339, epic.UpdatedAt); err == nil {
+				staleDuration := now.Sub(updated)
+				item.StalenessHours = staleDuration.Hours()
+
+				// Classify staleness
+				switch {
+				case staleDuration >= 4*time.Hour:
+					item.Staleness = "stuck"
+				case staleDuration >= 1*time.Hour:
+					item.Staleness = "stale"
+				default:
+					item.Staleness = "active"
+				}
+			}
+		}
+		if item.Staleness == "" {
+			item.Staleness = "active"
+		}
+
+		// Calculate score: priority × staleness_hours
+		// P1 = 1, P2 = 2, etc. Lower priority number = higher importance
+		// Invert so P1 has higher score
+		priorityWeight := float64(5 - item.Priority) // P1=4, P2=3, P3=2, P4=1
+		if priorityWeight < 1 {
+			priorityWeight = 1
+		}
+		item.Score = priorityWeight * item.StalenessHours
+
+		// Suggest drill-down command
+		item.DrillDown = fmt.Sprintf("bd show %s", epic.ID)
+
+		items = append(items, item)
+	}
+
+	// Also query in_progress and hooked epics
+	for _, status := range []string{"in_progress", "hooked"} {
+		extraCmd := exec.Command("bd", "list", "--type=epic", "--status="+status, "--json")
+		extraCmd.Dir = beadsPath
+		var extraStdout bytes.Buffer
+		extraCmd.Stdout = &extraStdout
+
+		if err := extraCmd.Run(); err != nil {
+			continue
+		}
+
+		var extraEpics []struct {
+			ID        string `json:"id"`
+			Title     string `json:"title"`
+			Status    string `json:"status"`
+			Priority  int    `json:"priority"`
+			UpdatedAt string `json:"updated_at"`
+			Assignee  string `json:"assignee,omitempty"`
+			Ephemeral bool   `json:"ephemeral,omitempty"`
+		}
+		if err := json.Unmarshal(extraStdout.Bytes(), &extraEpics); err != nil {
+			continue
+		}
+
+		for _, epic := range extraEpics {
+			// Skip ephemeral issues
+			if epic.Ephemeral {
+				continue
+			}
+			if strings.Contains(epic.ID, "wisp") || strings.Contains(epic.ID, "-mol-") {
+				continue
+			}
+
+			item := FocusItem{
+				ID:        epic.ID,
+				Title:     strings.TrimPrefix(epic.Title, "[EPIC] "),
+				Priority:  epic.Priority,
+				Status:    epic.Status,
+				UpdatedAt: epic.UpdatedAt,
+				Assignee:  epic.Assignee,
+			}
+
+			if epic.UpdatedAt != "" {
+				if updated, err := time.Parse(time.RFC3339, epic.UpdatedAt); err == nil {
+					staleDuration := now.Sub(updated)
+					item.StalenessHours = staleDuration.Hours()
+
+					switch {
+					case staleDuration >= 4*time.Hour:
+						item.Staleness = "stuck"
+					case staleDuration >= 1*time.Hour:
+						item.Staleness = "stale"
+					default:
+						item.Staleness = "active"
+					}
+				}
+			}
+			if item.Staleness == "" {
+				item.Staleness = "active"
+			}
+
+			priorityWeight := float64(5 - item.Priority)
+			if priorityWeight < 1 {
+				priorityWeight = 1
+			}
+			item.Score = priorityWeight * item.StalenessHours
+			item.DrillDown = fmt.Sprintf("bd show %s", epic.ID)
+
+			items = append(items, item)
+		}
+	}
+
+	return items
+}
+
+func outputFocusText(items []FocusItem) error {
+	fmt.Printf("%s\n\n", style.Bold.Render("Suggested focus (stalest high-priority first):"))
+
+	for i, item := range items {
+		// Staleness indicator
+		var indicator string
+		switch item.Staleness {
+		case "stuck":
+			indicator = style.Error.Render("🔴")
+		case "stale":
+			indicator = style.Warning.Render("🟡")
+		default:
+			indicator = style.Success.Render("🟢")
+		}
+
+		// Priority display
+		priorityStr := fmt.Sprintf("P%d", item.Priority)
+
+		// Format staleness duration
+		stalenessStr := formatStaleness(item.StalenessHours)
+
+		// Main line
+		fmt.Printf("%d. %s [%s] %s: %s\n", i+1, indicator, priorityStr, item.ID, item.Title)
+
+		// Details
+		if item.Assignee != "" {
+			// Extract short name from assignee path
+			parts := strings.Split(item.Assignee, "/")
+			shortAssignee := parts[len(parts)-1]
+			fmt.Printf("   Last movement: %s  Assignee: %s\n", stalenessStr, shortAssignee)
+		} else {
+			fmt.Printf("   Last movement: %s\n", stalenessStr)
+		}
+
+		// Drill-down hint
+		fmt.Printf("   %s\n\n", style.Dim.Render("→ "+item.DrillDown))
+	}
+
+	return nil
+}
+
+// formatStaleness formats staleness duration as human-readable string.
+func formatStaleness(hours float64) string {
+	if hours < 1.0/60.0 { // Less than 1 minute
+		return "just now"
+	}
+	if hours < 1 {
+		return fmt.Sprintf("%dm ago", int(hours*60))
+	}
+	if hours < 24 {
+		return fmt.Sprintf("%.1fh ago", hours)
+	}
+	days := hours / 24
+	return fmt.Sprintf("%.1fd ago", days)
+}

internal/cmd/gitinit.go

@@ -138,6 +138,11 @@ func runGitInit(cmd *cobra.Command, args []string) error {
 		fmt.Printf("   ✓ Git repository already exists\n")
 	}
 
+	// Install pre-checkout hook to prevent accidental branch switches
+	if err := InstallPreCheckoutHook(hqRoot); err != nil {
+		fmt.Printf("   %s Could not install pre-checkout hook: %v\n", style.Dim.Render("⚠"), err)
+	}
+
 	// Create GitHub repo if requested
 	if gitInitGitHub != "" {
 		if err := createGitHubRepo(hqRoot, gitInitGitHub, !gitInitPublic); err != nil {
@@ -223,6 +228,12 @@ func createGitHubRepo(hqRoot, repo string, private bool) error {
 	}
 	fmt.Printf("   → Creating %s GitHub repository %s...\n", visibility, repo)
 
+	// Ensure there's at least one commit before pushing.
+	// gh repo create --push fails on empty repos with no commits.
+	if err := ensureInitialCommit(hqRoot); err != nil {
+		return fmt.Errorf("creating initial commit: %w", err)
+	}
+
 	// Build gh repo create command
 	args := []string{"repo", "create", repo, "--source", hqRoot}
 	if private {
@@ -247,6 +258,33 @@ func createGitHubRepo(hqRoot, repo string, private bool) error {
 	return nil
 }
 
+// ensureInitialCommit creates an initial commit if the repo has no commits.
+// gh repo create --push requires at least one commit to push.
+func ensureInitialCommit(hqRoot string) error {
+	// Check if commits exist
+	cmd := exec.Command("git", "rev-parse", "HEAD")
+	cmd.Dir = hqRoot
+	if cmd.Run() == nil {
+		return nil
+	}
+
+	// Stage and commit
+	addCmd := exec.Command("git", "add", ".")
+	addCmd.Dir = hqRoot
+	if err := addCmd.Run(); err != nil {
+		return fmt.Errorf("git add: %w", err)
+	}
+
+	commitCmd := exec.Command("git", "commit", "-m", "Initial Gas Town HQ")
+	commitCmd.Dir = hqRoot
+	if output, err := commitCmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("git commit failed: %s", strings.TrimSpace(string(output)))
+	}
+
+	fmt.Printf("   ✓ Created initial commit\n")
+	return nil
+}
+
 // InitGitForHarness is the shared implementation for git initialization.
 // It can be called from both 'gt git-init' and 'gt install --git'.
 // Note: Function name kept for backwards compatibility.

internal/cmd/goals.go

@@ -0,0 +1,651 @@
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/beads"
+	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/workspace"
+)
+
+// Goal command flags
+var (
+	goalsJSON        bool
+	goalsStatus      string
+	goalsPriority    string
+	goalsIncludeWisp bool
+)
+
+var goalsCmd = &cobra.Command{
+	Use:     "goals [goal-id]",
+	GroupID: GroupWork,
+	Short:   "View strategic goals (epics) with staleness indicators",
+	Long: `View strategic goals (epics) across the workspace.
+
+Goals are high-level objectives that organize related work items.
+This command shows goals with staleness indicators to help identify
+stale or neglected strategic initiatives.
+
+Staleness indicators:
+  🟢 active: movement in last hour
+  🟡 stale:  no movement for 1+ hours
+  🔴 stuck:  no movement for 4+ hours
+
+Goals are sorted by staleness × priority (highest attention needed first).
+
+Examples:
+  gt goals              # List all open goals
+  gt goals --json       # Output as JSON
+  gt goals --status=all # Show all goals including closed
+  gt goals gt-abc       # Show details for a specific goal`,
+	RunE: runGoals,
+}
+
+func init() {
+	goalsCmd.Flags().BoolVar(&goalsJSON, "json", false, "Output as JSON")
+	goalsCmd.Flags().StringVar(&goalsStatus, "status", "open", "Filter by status (open, closed, all)")
+	goalsCmd.Flags().StringVar(&goalsPriority, "priority", "", "Filter by priority (e.g., P0, P1, P2)")
+	goalsCmd.Flags().BoolVar(&goalsIncludeWisp, "include-wisp", false, "Include transient wisp molecules (normally hidden)")
+	rootCmd.AddCommand(goalsCmd)
+}
+
+func runGoals(cmd *cobra.Command, args []string) error {
+	// If arg provided, show specific goal
+	if len(args) > 0 {
+		goalID := args[0]
+		return showGoal(goalID)
+	}
+
+	// Otherwise list all goals
+	return listGoals()
+}
+
+// goalInfo holds computed goal data for display and sorting.
+type goalInfo struct {
+	ID            string    `json:"id"`
+	Title         string    `json:"title"`
+	Status        string    `json:"status"`
+	Priority      int       `json:"priority"`
+	Assignee      string    `json:"assignee,omitempty"`
+	ConvoyCount   int       `json:"convoy_count"`
+	LastMovement  time.Time `json:"last_movement,omitempty"`
+	StalenessHrs  float64   `json:"staleness_hours"`
+	StalenessIcon string    `json:"staleness_icon"`
+	Score         float64   `json:"score"` // priority × staleness for sorting
+}
+
+func showGoal(goalID string) error {
+	// Get goal details via bd show
+	showCmd := exec.Command("bd", "show", goalID, "--json")
+	var stdout bytes.Buffer
+	showCmd.Stdout = &stdout
+
+	if err := showCmd.Run(); err != nil {
+		return fmt.Errorf("goal '%s' not found", goalID)
+	}
+
+	var goals []struct {
+		ID          string `json:"id"`
+		Title       string `json:"title"`
+		Description string `json:"description"`
+		Status      string `json:"status"`
+		Priority    int    `json:"priority"`
+		IssueType   string `json:"issue_type"`
+		Assignee    string `json:"assignee"`
+		CreatedAt   string `json:"created_at"`
+		UpdatedAt   string `json:"updated_at"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &goals); err != nil {
+		return fmt.Errorf("parsing goal data: %w", err)
+	}
+
+	if len(goals) == 0 {
+		return fmt.Errorf("goal '%s' not found", goalID)
+	}
+
+	goal := goals[0]
+
+	// Verify it's an epic
+	if goal.IssueType != "epic" {
+		return fmt.Errorf("'%s' is not a goal/epic (type: %s)", goalID, goal.IssueType)
+	}
+
+	// Get linked convoys (no dbPath available for single goal lookup, use fallback)
+	convoys := getLinkedConvoys(goalID, "")
+
+	// Compute staleness
+	lastMovement := computeGoalLastMovement(goal.UpdatedAt, convoys)
+	stalenessHrs := time.Since(lastMovement).Hours()
+	icon := stalenessIcon(stalenessHrs)
+
+	if goalsJSON {
+		out := goalInfo{
+			ID:            goal.ID,
+			Title:         goal.Title,
+			Status:        goal.Status,
+			Priority:      goal.Priority,
+			Assignee:      goal.Assignee,
+			ConvoyCount:   len(convoys),
+			LastMovement:  lastMovement,
+			StalenessHrs:  stalenessHrs,
+			StalenessIcon: icon,
+		}
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		return enc.Encode(out)
+	}
+
+	// Human-readable output
+	fmt.Printf("%s P%d  %s: %s\n\n", icon, goal.Priority, style.Bold.Render(goal.ID), goal.Title)
+	fmt.Printf("  Status:       %s\n", goal.Status)
+	fmt.Printf("  Priority:     P%d\n", goal.Priority)
+	if goal.Assignee != "" {
+		fmt.Printf("  Assignee:     @%s\n", goal.Assignee)
+	}
+	fmt.Printf("  Convoys:      %d\n", len(convoys))
+	fmt.Printf("  Last activity: %s\n", formatLastActivity(lastMovement))
+
+	if goal.Description != "" {
+		fmt.Printf("\n  %s\n", style.Bold.Render("Description:"))
+		// Indent description
+		for _, line := range strings.Split(goal.Description, "\n") {
+			fmt.Printf("  %s\n", line)
+		}
+	}
+
+	if len(convoys) > 0 {
+		fmt.Printf("\n  %s\n", style.Bold.Render("Linked Convoys:"))
+		for _, c := range convoys {
+			statusIcon := "○"
+			if c.Status == "closed" {
+				statusIcon = "✓"
+			}
+			fmt.Printf("    %s %s: %s\n", statusIcon, c.ID, c.Title)
+		}
+	}
+
+	return nil
+}
+
+func listGoals() error {
+	// Collect epics from all rigs (goals are cross-rig strategic objectives)
+	epics, err := collectEpicsFromAllRigs()
+	if err != nil {
+		return err
+	}
+
+	// Filter out wisp molecules by default (transient/operational, not strategic goals)
+	// These have IDs like "gt-wisp-*" and are molecule-tracking beads, not human goals
+	if !goalsIncludeWisp {
+		filtered := make([]epicRecord, 0)
+		for _, e := range epics {
+			if !isWispEpic(e.ID, e.Title) {
+				filtered = append(filtered, e)
+			}
+		}
+		epics = filtered
+	}
+
+	// Filter by priority if specified
+	if goalsPriority != "" {
+		targetPriority := parsePriority(goalsPriority)
+		filtered := make([]epicRecord, 0)
+		for _, e := range epics {
+			if e.Priority == targetPriority {
+				filtered = append(filtered, e)
+			}
+		}
+		epics = filtered
+	}
+
+	// Build goal info with staleness computation
+	var goals []goalInfo
+	for _, epic := range epics {
+		convoys := getLinkedConvoys(epic.ID, epic.dbPath)
+		lastMovement := computeGoalLastMovement(epic.UpdatedAt, convoys)
+		stalenessHrs := time.Since(lastMovement).Hours()
+		icon := stalenessIcon(stalenessHrs)
+
+		// Score = priority_value × staleness_hours
+		// Lower priority number = higher priority, so invert (4 - priority)
+		priorityWeight := float64(4 - epic.Priority)
+		if priorityWeight < 1 {
+			priorityWeight = 1
+		}
+		score := priorityWeight * stalenessHrs
+
+		goals = append(goals, goalInfo{
+			ID:            epic.ID,
+			Title:         epic.Title,
+			Status:        epic.Status,
+			Priority:      epic.Priority,
+			Assignee:      epic.Assignee,
+			ConvoyCount:   len(convoys),
+			LastMovement:  lastMovement,
+			StalenessHrs:  stalenessHrs,
+			StalenessIcon: icon,
+			Score:         score,
+		})
+	}
+
+	// Sort by score (highest attention needed first)
+	sort.Slice(goals, func(i, j int) bool {
+		return goals[i].Score > goals[j].Score
+	})
+
+	if goalsJSON {
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		return enc.Encode(goals)
+	}
+
+	if len(goals) == 0 {
+		fmt.Println("No goals found.")
+		fmt.Println("Create a goal with: bd create --type=epic --title=\"Goal name\"")
+		return nil
+	}
+
+	// Count active (non-closed) goals
+	activeCount := 0
+	for _, g := range goals {
+		if g.Status != "closed" {
+			activeCount++
+		}
+	}
+
+	fmt.Printf("%s\n\n", style.Bold.Render(fmt.Sprintf("Goals (%d active, sorted by staleness × priority)", activeCount)))
+
+	for _, g := range goals {
+		// Format: 🔴 P1  sc-xyz: Title
+		//              3 convoys | stale 6h
+		priorityStr := fmt.Sprintf("P%d", g.Priority)
+
+		fmt.Printf("  %s %s  %s: %s\n", g.StalenessIcon, priorityStr, g.ID, g.Title)
+
+		// Second line with convoy count, staleness, and assignee (if any)
+		activityStr := formatActivityShort(g.StalenessHrs)
+		if g.Assignee != "" {
+			fmt.Printf("         %d convoy(s) | %s | @%s\n\n", g.ConvoyCount, activityStr, g.Assignee)
+		} else {
+			fmt.Printf("         %d convoy(s) | %s\n\n", g.ConvoyCount, activityStr)
+		}
+	}
+
+	return nil
+}
+
+// convoyInfo holds basic convoy info.
+type convoyInfo struct {
+	ID     string
+	Title  string
+	Status string
+}
+
+// getLinkedConvoys finds convoys linked to a goal (via parent-child relation).
+// dbPath is the path to beads.db containing the goal for direct SQLite queries.
+func getLinkedConvoys(goalID, dbPath string) []convoyInfo {
+	var convoys []convoyInfo
+
+	// If no dbPath provided, fall back to bd subprocess (shouldn't happen normally)
+	if dbPath == "" {
+		return getLinkedConvoysFallback(goalID)
+	}
+
+	// Query dependencies directly from SQLite
+	// Children are stored as: depends_on_id = goalID (parent) with type 'blocks'
+	safeGoalID := strings.ReplaceAll(goalID, "'", "''")
+	query := fmt.Sprintf(`
+		SELECT i.id, i.title, i.status
+		FROM dependencies d
+		JOIN issues i ON d.issue_id = i.id
+		WHERE d.depends_on_id = '%s' AND d.type = 'blocks' AND i.issue_type = 'convoy'
+	`, safeGoalID)
+
+	queryCmd := exec.Command("sqlite3", "-json", dbPath, query)
+	var stdout bytes.Buffer
+	queryCmd.Stdout = &stdout
+
+	if err := queryCmd.Run(); err != nil {
+		return convoys
+	}
+
+	if stdout.Len() == 0 {
+		return convoys
+	}
+
+	var results []struct {
+		ID     string `json:"id"`
+		Title  string `json:"title"`
+		Status string `json:"status"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &results); err != nil {
+		return convoys
+	}
+
+	for _, r := range results {
+		convoys = append(convoys, convoyInfo{
+			ID:     r.ID,
+			Title:  r.Title,
+			Status: r.Status,
+		})
+	}
+
+	return convoys
+}
+
+// getLinkedConvoysFallback uses bd subprocess (for when dbPath is unknown).
+func getLinkedConvoysFallback(goalID string) []convoyInfo {
+	var convoys []convoyInfo
+
+	depArgs := []string{"dep", "list", goalID, "--json"}
+	depCmd := exec.Command("bd", depArgs...)
+	var stdout bytes.Buffer
+	depCmd.Stdout = &stdout
+
+	if err := depCmd.Run(); err != nil {
+		return convoys
+	}
+
+	var deps struct {
+		Children []struct {
+			ID   string `json:"id"`
+			Type string `json:"type"`
+		} `json:"children"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &deps); err != nil {
+		return convoys
+	}
+
+	for _, child := range deps.Children {
+		details := getIssueDetails(child.ID)
+		if details != nil && details.IssueType == "convoy" {
+			convoys = append(convoys, convoyInfo{
+				ID:     details.ID,
+				Title:  details.Title,
+				Status: details.Status,
+			})
+		}
+	}
+
+	return convoys
+}
+
+// computeGoalLastMovement computes when the goal last had activity.
+// It looks at:
+// 1. The goal's own updated_at (passed directly to avoid re-querying)
+// 2. The last activity of any linked convoy's tracked issues
+func computeGoalLastMovement(goalUpdatedAt string, convoys []convoyInfo) time.Time {
+	// Start with the goal's own updated_at
+	lastMovement := time.Now().Add(-24 * time.Hour) // Default to 24 hours ago
+	if goalUpdatedAt != "" {
+		if t, err := time.Parse(time.RFC3339, goalUpdatedAt); err == nil {
+			lastMovement = t
+		}
+	}
+
+	// If no convoys, return early (common case - avoids unnecessary work)
+	if len(convoys) == 0 {
+		return lastMovement
+	}
+
+	// Check convoy activity
+	townBeads, err := getTownBeadsDir()
+	if err != nil {
+		return lastMovement
+	}
+
+	for _, convoy := range convoys {
+		tracked := getTrackedIssues(townBeads, convoy.ID)
+		for _, t := range tracked {
+			// Get issue's updated_at
+			details := getIssueDetails(t.ID)
+			if details == nil {
+				continue
+			}
+			showCmd := exec.Command("bd", "show", t.ID, "--json")
+			var out bytes.Buffer
+			showCmd.Stdout = &out
+			showCmd.Run()
+
+			var issues []struct {
+				UpdatedAt string `json:"updated_at"`
+			}
+			json.Unmarshal(out.Bytes(), &issues)
+			if len(issues) > 0 && issues[0].UpdatedAt != "" {
+				if t, err := time.Parse(time.RFC3339, issues[0].UpdatedAt); err == nil {
+					if t.After(lastMovement) {
+						lastMovement = t
+					}
+				}
+			}
+		}
+	}
+
+	return lastMovement
+}
+
+// stalenessIcon returns the appropriate staleness indicator.
+// 🟢 active: moved in last hour
+// 🟡 stale: no movement for 1+ hours
+// 🔴 stuck: no movement for 4+ hours
+func stalenessIcon(hours float64) string {
+	if hours < 1 {
+		return "🟢"
+	}
+	if hours < 4 {
+		return "🟡"
+	}
+	return "🔴"
+}
+
+// formatLastActivity formats the last activity time for display.
+func formatLastActivity(t time.Time) string {
+	if t.IsZero() {
+		return "unknown"
+	}
+	d := time.Since(t)
+	if d < time.Minute {
+		return "just now"
+	}
+	if d < time.Hour {
+		return fmt.Sprintf("%d minutes ago", int(d.Minutes()))
+	}
+	if d < 24*time.Hour {
+		return fmt.Sprintf("%d hours ago", int(d.Hours()))
+	}
+	return fmt.Sprintf("%d days ago", int(d.Hours()/24))
+}
+
+// formatActivityShort returns a short activity string for the list view.
+func formatActivityShort(hours float64) string {
+	if hours < 1 {
+		mins := int(hours * 60)
+		if mins < 1 {
+			return "active just now"
+		}
+		return fmt.Sprintf("active %dm ago", mins)
+	}
+	if hours < 4 {
+		return fmt.Sprintf("stale %.0fh", hours)
+	}
+	return fmt.Sprintf("stuck %.0fh", hours)
+}
+
+// parsePriority converts a priority string (P0, P1, etc.) to an int.
+func parsePriority(s string) int {
+	s = strings.TrimPrefix(strings.ToUpper(s), "P")
+	if p, err := strconv.Atoi(s); err == nil {
+		return p
+	}
+	return 2 // Default to P2
+}
+
+// isWispEpic returns true if the epic is a transient wisp molecule.
+// These are operational/infrastructure beads, not strategic goals that need human attention.
+// Detection criteria:
+// - ID contains "-wisp-" (molecule tracking beads)
+// - Title starts with "mol-" (molecule beads)
+func isWispEpic(id, title string) bool {
+	// Check for wisp ID pattern (e.g., "gt-wisp-abc123")
+	if strings.Contains(id, "-wisp-") {
+		return true
+	}
+	// Check for molecule title pattern
+	if strings.HasPrefix(title, "mol-") {
+		return true
+	}
+	return false
+}
+
+// epicRecord represents an epic from bd list output.
+type epicRecord struct {
+	ID        string `json:"id"`
+	Title     string `json:"title"`
+	Status    string `json:"status"`
+	Priority  int    `json:"priority"`
+	UpdatedAt string `json:"updated_at"`
+	Assignee  string `json:"assignee"`
+	// dbPath is the path to beads.db containing this epic (for direct queries)
+	dbPath string
+}
+
+// collectEpicsFromAllRigs queries all rigs for epics and aggregates them.
+// Goals are cross-rig strategic objectives, so we need to query each rig's beads.
+func collectEpicsFromAllRigs() ([]epicRecord, error) {
+	var allEpics []epicRecord
+	seen := make(map[string]bool) // Deduplicate by ID
+
+	// Find the town root
+	townRoot, err := workspace.FindFromCwdOrError()
+	if err != nil {
+		// Not in a Gas Town workspace, fall back to single query
+		return queryEpicsInDir("")
+	}
+
+	// Also query town-level beads (for hq- prefixed epics)
+	townBeadsDir := filepath.Join(townRoot, ".beads")
+	if _, err := os.Stat(townBeadsDir); err == nil {
+		epics, err := queryEpicsInDir(townRoot)
+		if err == nil {
+			for _, e := range epics {
+				if !seen[e.ID] {
+					seen[e.ID] = true
+					allEpics = append(allEpics, e)
+				}
+			}
+		}
+	}
+
+	// Find all rig directories (they have .beads/ subdirectories)
+	entries, err := os.ReadDir(townRoot)
+	if err != nil {
+		return allEpics, nil // Return what we have
+	}
+
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+		// Skip hidden directories and known non-rig directories
+		name := entry.Name()
+		if strings.HasPrefix(name, ".") || name == "plugins" || name == "docs" {
+			continue
+		}
+
+		rigPath := filepath.Join(townRoot, name)
+		rigBeadsDir := filepath.Join(rigPath, ".beads")
+
+		// Check if this directory has a beads database
+		if _, err := os.Stat(rigBeadsDir); os.IsNotExist(err) {
+			continue
+		}
+
+		// Query this rig for epics
+		epics, err := queryEpicsInDir(rigPath)
+		if err != nil {
+			// Log but continue - one rig failing shouldn't stop the whole query
+			continue
+		}
+
+		for _, e := range epics {
+			if !seen[e.ID] {
+				seen[e.ID] = true
+				allEpics = append(allEpics, e)
+			}
+		}
+	}
+
+	return allEpics, nil
+}
+
+// queryEpicsInDir queries epics directly from SQLite in the specified directory.
+// If dir is empty, uses current working directory.
+func queryEpicsInDir(dir string) ([]epicRecord, error) {
+	beadsDir := dir
+	if beadsDir == "" {
+		var err error
+		beadsDir, err = os.Getwd()
+		if err != nil {
+			return nil, fmt.Errorf("getting working directory: %w", err)
+		}
+	}
+
+	// Resolve redirects to find actual beads.db
+	resolvedBeads := beads.ResolveBeadsDir(beadsDir)
+	dbPath := filepath.Join(resolvedBeads, "beads.db")
+
+	// Check if database exists
+	if _, err := os.Stat(dbPath); os.IsNotExist(err) {
+		return nil, nil // No database, no epics
+	}
+
+	// Build SQL query for epics
+	query := `SELECT id, title, status, priority, updated_at, assignee
+	          FROM issues
+	          WHERE issue_type = 'epic'`
+
+	if goalsStatus == "" || goalsStatus == "open" {
+		query += ` AND status <> 'closed' AND status <> 'tombstone'`
+	} else if goalsStatus != "all" {
+		query += fmt.Sprintf(` AND status = '%s'`, strings.ReplaceAll(goalsStatus, "'", "''"))
+	} else {
+		// --all: exclude tombstones but include everything else
+		query += ` AND status <> 'tombstone'`
+	}
+
+	queryCmd := exec.Command("sqlite3", "-json", dbPath, query)
+	var stdout bytes.Buffer
+	queryCmd.Stdout = &stdout
+
+	if err := queryCmd.Run(); err != nil {
+		// Database might be empty or have no epics - not an error
+		return nil, nil
+	}
+
+	// Handle empty result (sqlite3 -json returns nothing for empty sets)
+	if stdout.Len() == 0 {
+		return nil, nil
+	}
+
+	var epics []epicRecord
+	if err := json.Unmarshal(stdout.Bytes(), &epics); err != nil {
+		return nil, fmt.Errorf("parsing epics: %w", err)
+	}
+
+	// Set dbPath on each epic for direct queries later
+	for i := range epics {
+		epics[i].dbPath = dbPath
+	}
+
+	return epics, nil
+}

internal/cmd/handoff.go

@@ -11,6 +11,7 @@ import (
 	"github.com/steveyegge/gastown/internal/config"
 	"github.com/steveyegge/gastown/internal/constants"
 	"github.com/steveyegge/gastown/internal/events"
+	"github.com/steveyegge/gastown/internal/mail"
 	"github.com/steveyegge/gastown/internal/session"
 	"github.com/steveyegge/gastown/internal/style"
 	"github.com/steveyegge/gastown/internal/tmux"
@@ -203,7 +204,17 @@ func runHandoff(cmd *cobra.Command, args []string) error {
 		_ = os.WriteFile(markerPath, []byte(currentSession), 0644)
 	}
 
-	// Use exec to respawn the pane - this kills us and restarts
+	// NOTE: We intentionally do NOT kill pane processes before respawning (hq-bv7ef).
+	// Previous approach (KillPaneProcessesExcluding) killed the pane's main process,
+	// which caused the pane to close (remain-on-exit is off by default), making
+	// RespawnPane fail because the target pane no longer exists.
+	//
+	// The respawn-pane -k flag handles killing atomically - it kills the old process
+	// and starts the new one in a single operation without closing the pane.
+	// If orphan processes remain (e.g., Claude ignoring SIGHUP), they will be cleaned
+	// up when the new session starts or when the Witness runs periodic cleanup.
+
+	// Use respawn-pane to atomically kill old process and start new one
 	return t.RespawnPane(pane, restartCmd)
 }
 
@@ -383,7 +394,20 @@ func buildRestartCommand(sessionName string) (string, error) {
 	// 3. export Claude-related env vars (not inherited by fresh shell)
 	// 4. run claude with the startup beacon (triggers immediate context loading)
 	// Use exec to ensure clean process replacement.
-	runtimeCmd := config.GetRuntimeCommandWithPrompt("", beacon)
+	//
+	// Check if current session is using a non-default agent (GT_AGENT env var).
+	// If so, preserve it across handoff by using the override variant.
+	currentAgent := os.Getenv("GT_AGENT")
+	var runtimeCmd string
+	if currentAgent != "" {
+		var err error
+		runtimeCmd, err = config.GetRuntimeCommandWithPromptAndAgentOverride("", beacon, currentAgent)
+		if err != nil {
+			return "", fmt.Errorf("resolving agent config: %w", err)
+		}
+	} else {
+		runtimeCmd = config.GetRuntimeCommandWithPrompt("", beacon)
+	}
 
 	// Build environment exports - role vars first, then Claude vars
 	var exports []string
@@ -397,6 +421,15 @@ func buildRestartCommand(sessionName string) (string, error) {
 		}
 	}
 
+	// Propagate GT_ROOT so subsequent handoffs can use it as fallback
+	// when cwd-based detection fails (broken state recovery)
+	exports = append(exports, "GT_ROOT="+townRoot)
+
+	// Preserve GT_AGENT across handoff so agent override persists
+	if currentAgent != "" {
+		exports = append(exports, "GT_AGENT="+currentAgent)
+	}
+
 	// Add Claude-related env vars from current environment
 	for _, name := range claudeEnvVars {
 		if val := os.Getenv(name); val != "" {
@@ -479,14 +512,33 @@ func sessionToGTRole(sessionName string) string {
 }
 
 // detectTownRootFromCwd walks up from the current directory to find the town root.
+// Falls back to GT_TOWN_ROOT or GT_ROOT env vars if cwd detection fails (broken state recovery).
 func detectTownRootFromCwd() string {
 	// Use workspace.FindFromCwd which handles both primary (mayor/town.json)
 	// and secondary (mayor/ directory) markers
 	townRoot, err := workspace.FindFromCwd()
-	if err != nil {
-		return ""
+	if err == nil && townRoot != "" {
+		return townRoot
 	}
-	return townRoot
+
+	// Fallback: try environment variables for town root
+	// GT_TOWN_ROOT is set by shell integration, GT_ROOT is set by session manager
+	// This enables handoff to work even when cwd detection fails due to
+	// detached HEAD, wrong branch, deleted worktree, etc.
+	for _, envName := range []string{"GT_TOWN_ROOT", "GT_ROOT"} {
+		if envRoot := os.Getenv(envName); envRoot != "" {
+			// Verify it's actually a workspace
+			if _, statErr := os.Stat(filepath.Join(envRoot, workspace.PrimaryMarker)); statErr == nil {
+				return envRoot
+			}
+			// Try secondary marker too
+			if info, statErr := os.Stat(filepath.Join(envRoot, workspace.SecondaryMarker)); statErr == nil && info.IsDir() {
+				return envRoot
+			}
+		}
+	}
+
+	return ""
 }
 
 // handoffRemoteSession respawns a different session and optionally switches to it.
@@ -518,13 +570,18 @@ func handoffRemoteSession(t *tmux.Tmux, targetSession, restartCmd string) error
 		return nil
 	}
 
+	// NOTE: We intentionally do NOT kill pane processes before respawning (hq-bv7ef).
+	// Previous approach (KillPaneProcesses) killed the pane's main process, which caused
+	// the pane to close (remain-on-exit is off by default), making RespawnPane fail.
+	// The respawn-pane -k flag handles killing atomically without closing the pane.
+
 	// Clear scrollback history before respawn (resets copy-mode from [0/N] to [0/0])
 	if err := t.ClearHistory(targetPane); err != nil {
 		// Non-fatal - continue with respawn even if clear fails
 		style.PrintWarning("could not clear history: %v", err)
 	}
 
-	// Respawn the remote session's pane
+	// Respawn the remote session's pane - -k flag atomically kills old process and starts new one
 	if err := t.RespawnPane(targetPane, restartCmd); err != nil {
 		return fmt.Errorf("respawning pane: %w", err)
 	}
@@ -577,6 +634,9 @@ func sendHandoffMail(subject, message string) (string, error) {
 		return "", fmt.Errorf("detecting agent identity: %w", err)
 	}
 
+	// Normalize identity to match mailbox query format
+	agentID = mail.AddressToIdentity(agentID)
+
 	// Detect town root for beads location
 	townRoot := detectTownRootFromCwd()
 	if townRoot == "" {

internal/cmd/handoff_test.go

@@ -0,0 +1,124 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/steveyegge/gastown/internal/workspace"
+)
+
+func TestDetectTownRootFromCwd_EnvFallback(t *testing.T) {
+	// Save original env vars and restore after test
+	origTownRoot := os.Getenv("GT_TOWN_ROOT")
+	origRoot := os.Getenv("GT_ROOT")
+	defer func() {
+		os.Setenv("GT_TOWN_ROOT", origTownRoot)
+		os.Setenv("GT_ROOT", origRoot)
+	}()
+
+	// Create a temp directory that looks like a valid town
+	tmpTown := t.TempDir()
+	mayorDir := filepath.Join(tmpTown, "mayor")
+	if err := os.MkdirAll(mayorDir, 0755); err != nil {
+		t.Fatalf("creating mayor dir: %v", err)
+	}
+	townJSON := filepath.Join(mayorDir, "town.json")
+	if err := os.WriteFile(townJSON, []byte(`{"name": "test-town"}`), 0644); err != nil {
+		t.Fatalf("creating town.json: %v", err)
+	}
+
+	// Clear both env vars initially
+	os.Setenv("GT_TOWN_ROOT", "")
+	os.Setenv("GT_ROOT", "")
+
+	t.Run("uses GT_TOWN_ROOT when cwd detection fails", func(t *testing.T) {
+		// Set GT_TOWN_ROOT to our temp town
+		os.Setenv("GT_TOWN_ROOT", tmpTown)
+		os.Setenv("GT_ROOT", "")
+
+		// Save cwd, cd to a non-town directory, and restore after
+		origCwd, _ := os.Getwd()
+		os.Chdir(os.TempDir())
+		defer os.Chdir(origCwd)
+
+		result := detectTownRootFromCwd()
+		if result != tmpTown {
+			t.Errorf("detectTownRootFromCwd() = %q, want %q (should use GT_TOWN_ROOT fallback)", result, tmpTown)
+		}
+	})
+
+	t.Run("uses GT_ROOT when GT_TOWN_ROOT not set", func(t *testing.T) {
+		// Set only GT_ROOT
+		os.Setenv("GT_TOWN_ROOT", "")
+		os.Setenv("GT_ROOT", tmpTown)
+
+		// Save cwd, cd to a non-town directory, and restore after
+		origCwd, _ := os.Getwd()
+		os.Chdir(os.TempDir())
+		defer os.Chdir(origCwd)
+
+		result := detectTownRootFromCwd()
+		if result != tmpTown {
+			t.Errorf("detectTownRootFromCwd() = %q, want %q (should use GT_ROOT fallback)", result, tmpTown)
+		}
+	})
+
+	t.Run("prefers GT_TOWN_ROOT over GT_ROOT", func(t *testing.T) {
+		// Create another temp town for GT_ROOT
+		anotherTown := t.TempDir()
+		anotherMayor := filepath.Join(anotherTown, "mayor")
+		os.MkdirAll(anotherMayor, 0755)
+		os.WriteFile(filepath.Join(anotherMayor, "town.json"), []byte(`{"name": "other-town"}`), 0644)
+
+		// Set both env vars
+		os.Setenv("GT_TOWN_ROOT", tmpTown)
+		os.Setenv("GT_ROOT", anotherTown)
+
+		// Save cwd, cd to a non-town directory, and restore after
+		origCwd, _ := os.Getwd()
+		os.Chdir(os.TempDir())
+		defer os.Chdir(origCwd)
+
+		result := detectTownRootFromCwd()
+		if result != tmpTown {
+			t.Errorf("detectTownRootFromCwd() = %q, want %q (should prefer GT_TOWN_ROOT)", result, tmpTown)
+		}
+	})
+
+	t.Run("ignores invalid GT_TOWN_ROOT", func(t *testing.T) {
+		// Set GT_TOWN_ROOT to non-existent path, GT_ROOT to valid
+		os.Setenv("GT_TOWN_ROOT", "/nonexistent/path/to/town")
+		os.Setenv("GT_ROOT", tmpTown)
+
+		// Save cwd, cd to a non-town directory, and restore after
+		origCwd, _ := os.Getwd()
+		os.Chdir(os.TempDir())
+		defer os.Chdir(origCwd)
+
+		result := detectTownRootFromCwd()
+		if result != tmpTown {
+			t.Errorf("detectTownRootFromCwd() = %q, want %q (should skip invalid GT_TOWN_ROOT and use GT_ROOT)", result, tmpTown)
+		}
+	})
+
+	t.Run("uses secondary marker when primary missing", func(t *testing.T) {
+		// Create a temp town with only mayor/ directory (no town.json)
+		secondaryTown := t.TempDir()
+		mayorOnlyDir := filepath.Join(secondaryTown, workspace.SecondaryMarker)
+		os.MkdirAll(mayorOnlyDir, 0755)
+
+		os.Setenv("GT_TOWN_ROOT", secondaryTown)
+		os.Setenv("GT_ROOT", "")
+
+		// Save cwd, cd to a non-town directory, and restore after
+		origCwd, _ := os.Getwd()
+		os.Chdir(os.TempDir())
+		defer os.Chdir(origCwd)
+
+		result := detectTownRootFromCwd()
+		if result != secondaryTown {
+			t.Errorf("detectTownRootFromCwd() = %q, want %q (should accept secondary marker)", result, secondaryTown)
+		}
+	})
+}

internal/cmd/hook.go

@@ -5,17 +5,18 @@ import (
 	"fmt"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 
 	"github.com/spf13/cobra"
 	"github.com/steveyegge/gastown/internal/beads"
 	"github.com/steveyegge/gastown/internal/events"
-	"github.com/steveyegge/gastown/internal/runtime"
 	"github.com/steveyegge/gastown/internal/style"
 )
 
 var hookCmd = &cobra.Command{
 	Use:     "hook [bead-id]",
+	Aliases: []string{"work"},
 	GroupID: GroupWork,
 	Short:   "Show or attach work on your hook",
 	Long: `Show what's on your hook, or attach new work.
@@ -182,15 +183,8 @@ func runHook(_ *cobra.Command, args []string) error {
 			fmt.Printf("%s Replacing completed bead %s...\n", style.Dim.Render("ℹ"), existing.ID)
 			if !hookDryRun {
 				if hasAttachment {
-					// Close completed molecule bead (use bd close --force for pinned)
-					closeArgs := []string{"close", existing.ID, "--force",
-						"--reason=Auto-replaced by gt hook (molecule complete)"}
-					if sessionID := runtime.SessionIDFromEnv(); sessionID != "" {
-						closeArgs = append(closeArgs, "--session="+sessionID)
-					}
-					closeCmd := exec.Command("bd", closeArgs...)
-					closeCmd.Stderr = os.Stderr
-					if err := closeCmd.Run(); err != nil {
+					// Close completed molecule bead (use force for pinned)
+					if err := b.CloseForced(existing.ID, "Auto-replaced by gt hook (molecule complete)"); err != nil {
 						return fmt.Errorf("closing completed bead %s: %w", existing.ID, err)
 					}
 				} else {
@@ -231,10 +225,9 @@ func runHook(_ *cobra.Command, args []string) error {
 		return nil
 	}
 
-	// Hook the bead using bd update (discovery-based approach)
-	hookCmd := exec.Command("bd", "update", beadID, "--status=hooked", "--assignee="+agentID)
-	hookCmd.Stderr = os.Stderr
-	if err := hookCmd.Run(); err != nil {
+	// Hook the bead using beads package (uses RPC when daemon available)
+	status := beads.StatusHooked
+	if err := b.Update(beadID, beads.UpdateOptions{Status: &status, Assignee: &agentID}); err != nil {
 		return fmt.Errorf("hooking bead: %w", err)
 	}
 
@@ -309,11 +302,30 @@ func runHookShow(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("listing hooked beads: %w", err)
 	}
 
-	// If nothing found, try scanning all rigs for town-level roles
-	if len(hookedBeads) == 0 && isTownLevelRole(target) {
+	// If nothing found in local beads, also check town beads for hooked convoys.
+	// Convoys (hq-cv-*) are stored in town beads (~/gt/.beads) and any agent
+	// can hook them for convoy-driver mode.
+	if len(hookedBeads) == 0 {
 		townRoot, err := findTownRoot()
 		if err == nil && townRoot != "" {
-			hookedBeads = scanAllRigsForHookedBeads(townRoot, target)
+			// Check town beads for hooked items
+			townBeadsDir := filepath.Join(townRoot, ".beads")
+			if _, err := os.Stat(townBeadsDir); err == nil {
+				townBeads := beads.New(townBeadsDir)
+				townHooked, err := townBeads.List(beads.ListOptions{
+					Status:   beads.StatusHooked,
+					Assignee: target,
+					Priority: -1,
+				})
+				if err == nil && len(townHooked) > 0 {
+					hookedBeads = townHooked
+				}
+			}
+
+			// If still nothing found and town-level role, scan all rigs
+			if len(hookedBeads) == 0 && isTownLevelRole(target) {
+				hookedBeads = scanAllRigsForHookedBeads(townRoot, target)
+			}
 		}
 	}
 

internal/cmd/hooks.go

@@ -135,8 +135,14 @@ func discoverHooks(townRoot string) ([]HookInfo, error) {
 			agent string
 		}{filepath.Join(rigPath, ".claude", "settings.json"), fmt.Sprintf("%s/rig", rigName)})
 
-		// Polecats
+		// Polecats-level hooks (inherited by all polecats)
 		polecatsDir := filepath.Join(rigPath, "polecats")
+		locations = append(locations, struct {
+			path  string
+			agent string
+		}{filepath.Join(polecatsDir, ".claude", "settings.json"), fmt.Sprintf("%s/polecats", rigName)})
+
+		// Individual polecat hooks
 		if polecats, err := os.ReadDir(polecatsDir); err == nil {
 			for _, p := range polecats {
 				if p.IsDir() && !strings.HasPrefix(p.Name(), ".") {
@@ -148,11 +154,17 @@ func discoverHooks(townRoot string) ([]HookInfo, error) {
 			}
 		}
 
-		// Crew members
+		// Crew-level hooks (inherited by all crew members)
 		crewDir := filepath.Join(rigPath, "crew")
+		locations = append(locations, struct {
+			path  string
+			agent string
+		}{filepath.Join(crewDir, ".claude", "settings.json"), fmt.Sprintf("%s/crew", rigName)})
+
+		// Individual crew member hooks
 		if crew, err := os.ReadDir(crewDir); err == nil {
 			for _, c := range crew {
-				if c.IsDir() {
+				if c.IsDir() && !strings.HasPrefix(c.Name(), ".") {
 					locations = append(locations, struct {
 						path  string
 						agent string

internal/cmd/hooks_install.go

@@ -0,0 +1,267 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/workspace"
+)
+
+var (
+	installRole    string
+	installAllRigs bool
+	installDryRun  bool
+)
+
+var hooksInstallCmd = &cobra.Command{
+	Use:   "install <hook-name>",
+	Short: "Install a hook from the registry",
+	Long: `Install a hook from the registry to worktrees.
+
+By default, installs to the current worktree. Use --role to install
+to all worktrees of a specific role in the current rig.
+
+Examples:
+  gt hooks install pr-workflow-guard              # Install to current worktree
+  gt hooks install pr-workflow-guard --role crew  # Install to all crew in current rig
+  gt hooks install session-prime --role crew --all-rigs  # Install to all crew everywhere
+  gt hooks install pr-workflow-guard --dry-run    # Preview what would be installed`,
+	Args: cobra.ExactArgs(1),
+	RunE: runHooksInstall,
+}
+
+func init() {
+	hooksCmd.AddCommand(hooksInstallCmd)
+	hooksInstallCmd.Flags().StringVar(&installRole, "role", "", "Install to all worktrees of this role (crew, polecat, witness, refinery)")
+	hooksInstallCmd.Flags().BoolVar(&installAllRigs, "all-rigs", false, "Install across all rigs (requires --role)")
+	hooksInstallCmd.Flags().BoolVar(&installDryRun, "dry-run", false, "Preview changes without writing files")
+}
+
+func runHooksInstall(cmd *cobra.Command, args []string) error {
+	hookName := args[0]
+
+	townRoot, err := workspace.FindFromCwd()
+	if err != nil {
+		return fmt.Errorf("not in a Gas Town workspace: %w", err)
+	}
+
+	// Load registry
+	registry, err := LoadRegistry(townRoot)
+	if err != nil {
+		return err
+	}
+
+	// Find the hook
+	hookDef, ok := registry.Hooks[hookName]
+	if !ok {
+		return fmt.Errorf("hook %q not found in registry", hookName)
+	}
+
+	if !hookDef.Enabled {
+		fmt.Printf("%s Hook %q is disabled in registry. Use --force to install anyway.\n",
+			style.Warning.Render("Warning:"), hookName)
+	}
+
+	// Determine target worktrees
+	targets, err := determineTargets(townRoot, installRole, installAllRigs, hookDef.Roles)
+	if err != nil {
+		return err
+	}
+
+	if len(targets) == 0 {
+		// No role specified, install to current worktree
+		cwd, err := os.Getwd()
+		if err != nil {
+			return err
+		}
+		targets = []string{cwd}
+	}
+
+	// Install to each target
+	installed := 0
+	for _, target := range targets {
+		if err := installHookTo(target, hookDef, installDryRun); err != nil {
+			fmt.Printf("%s Failed to install to %s: %v\n", style.Error.Render("Error:"), target, err)
+			continue
+		}
+		installed++
+	}
+
+	if installDryRun {
+		fmt.Printf("\n%s Would install %q to %d worktree(s)\n", style.Dim.Render("Dry run:"), hookName, installed)
+	} else {
+		fmt.Printf("\n%s Installed %q to %d worktree(s)\n", style.Success.Render("Done:"), hookName, installed)
+	}
+
+	return nil
+}
+
+// determineTargets finds all worktree paths matching the role criteria.
+func determineTargets(townRoot, role string, allRigs bool, allowedRoles []string) ([]string, error) {
+	if role == "" {
+		return nil, nil // Will use current directory
+	}
+
+	// Check if role is allowed for this hook
+	roleAllowed := false
+	for _, r := range allowedRoles {
+		if r == role {
+			roleAllowed = true
+			break
+		}
+	}
+	if !roleAllowed {
+		return nil, fmt.Errorf("hook is not applicable to role %q (allowed: %s)", role, strings.Join(allowedRoles, ", "))
+	}
+
+	var targets []string
+
+	// Find rigs to scan
+	var rigs []string
+	if allRigs {
+		entries, err := os.ReadDir(townRoot)
+		if err != nil {
+			return nil, err
+		}
+		for _, e := range entries {
+			if e.IsDir() && !strings.HasPrefix(e.Name(), ".") && e.Name() != "mayor" && e.Name() != "deacon" && e.Name() != "hooks" {
+				rigs = append(rigs, e.Name())
+			}
+		}
+	} else {
+		// Find current rig from cwd
+		cwd, err := os.Getwd()
+		if err != nil {
+			return nil, err
+		}
+		relPath, err := filepath.Rel(townRoot, cwd)
+		if err != nil {
+			return nil, err
+		}
+		parts := strings.Split(relPath, string(filepath.Separator))
+		if len(parts) > 0 {
+			rigs = []string{parts[0]}
+		}
+	}
+
+	// Find worktrees for the role in each rig
+	for _, rig := range rigs {
+		rigPath := filepath.Join(townRoot, rig)
+
+		switch role {
+		case "crew":
+			crewDir := filepath.Join(rigPath, "crew")
+			if entries, err := os.ReadDir(crewDir); err == nil {
+				for _, e := range entries {
+					if e.IsDir() && !strings.HasPrefix(e.Name(), ".") {
+						targets = append(targets, filepath.Join(crewDir, e.Name()))
+					}
+				}
+			}
+		case "polecat":
+			polecatsDir := filepath.Join(rigPath, "polecats")
+			if entries, err := os.ReadDir(polecatsDir); err == nil {
+				for _, e := range entries {
+					if e.IsDir() && !strings.HasPrefix(e.Name(), ".") {
+						targets = append(targets, filepath.Join(polecatsDir, e.Name()))
+					}
+				}
+			}
+		case "witness":
+			witnessPath := filepath.Join(rigPath, "witness")
+			if _, err := os.Stat(witnessPath); err == nil {
+				targets = append(targets, witnessPath)
+			}
+		case "refinery":
+			refineryPath := filepath.Join(rigPath, "refinery")
+			if _, err := os.Stat(refineryPath); err == nil {
+				targets = append(targets, refineryPath)
+			}
+		}
+	}
+
+	return targets, nil
+}
+
+// installHookTo installs a hook to a specific worktree.
+func installHookTo(worktreePath string, hookDef HookDefinition, dryRun bool) error {
+	settingsPath := filepath.Join(worktreePath, ".claude", "settings.json")
+
+	// Load existing settings or create new
+	var settings ClaudeSettings
+	if data, err := os.ReadFile(settingsPath); err == nil {
+		if err := json.Unmarshal(data, &settings); err != nil {
+			return fmt.Errorf("parsing existing settings: %w", err)
+		}
+	}
+
+	// Initialize maps if needed
+	if settings.Hooks == nil {
+		settings.Hooks = make(map[string][]ClaudeHookMatcher)
+	}
+	if settings.EnabledPlugins == nil {
+		settings.EnabledPlugins = make(map[string]bool)
+	}
+
+	// Build the hook entries
+	for _, matcher := range hookDef.Matchers {
+		hookEntry := ClaudeHookMatcher{
+			Matcher: matcher,
+			Hooks: []ClaudeHook{
+				{Type: "command", Command: hookDef.Command},
+			},
+		}
+
+		// Check if this exact matcher already exists
+		exists := false
+		for _, existing := range settings.Hooks[hookDef.Event] {
+			if existing.Matcher == matcher {
+				exists = true
+				break
+			}
+		}
+
+		if !exists {
+			settings.Hooks[hookDef.Event] = append(settings.Hooks[hookDef.Event], hookEntry)
+		}
+	}
+
+	// Ensure beads plugin is disabled (standard for Gas Town)
+	settings.EnabledPlugins["beads@beads-marketplace"] = false
+
+	// Pretty print relative path
+	relPath := worktreePath
+	if home, err := os.UserHomeDir(); err == nil {
+		if rel, err := filepath.Rel(home, worktreePath); err == nil && !strings.HasPrefix(rel, "..") {
+			relPath = "~/" + rel
+		}
+	}
+
+	if dryRun {
+		fmt.Printf("  %s %s\n", style.Dim.Render("Would install to:"), relPath)
+		return nil
+	}
+
+	// Create directory if needed
+	if err := os.MkdirAll(filepath.Dir(settingsPath), 0755); err != nil {
+		return fmt.Errorf("creating .claude directory: %w", err)
+	}
+
+	// Write settings
+	data, err := json.MarshalIndent(settings, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshaling settings: %w", err)
+	}
+
+	if err := os.WriteFile(settingsPath, data, 0600); err != nil {
+		return fmt.Errorf("writing settings: %w", err)
+	}
+
+	fmt.Printf("  %s %s\n", style.Success.Render("Installed to:"), relPath)
+	return nil
+}

internal/cmd/hooks_registry.go

@@ -0,0 +1,165 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/BurntSushi/toml"
+	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/workspace"
+)
+
+// HookRegistry represents the hooks/registry.toml structure.
+type HookRegistry struct {
+	Hooks map[string]HookDefinition `toml:"hooks"`
+}
+
+// HookDefinition represents a single hook definition in the registry.
+type HookDefinition struct {
+	Description string   `toml:"description"`
+	Event       string   `toml:"event"`
+	Matchers    []string `toml:"matchers"`
+	Command     string   `toml:"command"`
+	Roles       []string `toml:"roles"`
+	Scope       string   `toml:"scope"`
+	Enabled     bool     `toml:"enabled"`
+}
+
+var (
+	hooksListAll bool
+)
+
+var hooksListCmd = &cobra.Command{
+	Use:   "list",
+	Short: "List available hooks from the registry",
+	Long: `List all hooks defined in the hook registry.
+
+The registry is at ~/gt/hooks/registry.toml and defines hooks that can be
+installed for different roles (crew, polecat, witness, etc.).
+
+Examples:
+  gt hooks list           # Show enabled hooks
+  gt hooks list --all     # Show all hooks including disabled`,
+	RunE: runHooksList,
+}
+
+func init() {
+	hooksCmd.AddCommand(hooksListCmd)
+	hooksListCmd.Flags().BoolVarP(&hooksListAll, "all", "a", false, "Show all hooks including disabled")
+	hooksListCmd.Flags().BoolVarP(&hooksVerbose, "verbose", "v", false, "Show hook commands and matchers")
+}
+
+// LoadRegistry loads the hook registry from the town's hooks directory.
+func LoadRegistry(townRoot string) (*HookRegistry, error) {
+	registryPath := filepath.Join(townRoot, "hooks", "registry.toml")
+
+	data, err := os.ReadFile(registryPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("hook registry not found at %s", registryPath)
+		}
+		return nil, fmt.Errorf("reading registry: %w", err)
+	}
+
+	var registry HookRegistry
+	if _, err := toml.Decode(string(data), &registry); err != nil {
+		return nil, fmt.Errorf("parsing registry: %w", err)
+	}
+
+	return &registry, nil
+}
+
+func runHooksList(cmd *cobra.Command, args []string) error {
+	townRoot, err := workspace.FindFromCwd()
+	if err != nil {
+		return fmt.Errorf("not in a Gas Town workspace: %w", err)
+	}
+
+	registry, err := LoadRegistry(townRoot)
+	if err != nil {
+		return err
+	}
+
+	if len(registry.Hooks) == 0 {
+		fmt.Println(style.Dim.Render("No hooks defined in registry"))
+		return nil
+	}
+
+	fmt.Printf("\n%s Hook Registry\n", style.Bold.Render("📋"))
+	fmt.Printf("Source: %s\n\n", style.Dim.Render(filepath.Join(townRoot, "hooks", "registry.toml")))
+
+	// Group by event type
+	byEvent := make(map[string][]struct {
+		name string
+		def  HookDefinition
+	})
+	eventOrder := []string{"PreToolUse", "PostToolUse", "SessionStart", "PreCompact", "UserPromptSubmit", "Stop"}
+
+	for name, def := range registry.Hooks {
+		if !hooksListAll && !def.Enabled {
+			continue
+		}
+		byEvent[def.Event] = append(byEvent[def.Event], struct {
+			name string
+			def  HookDefinition
+		}{name, def})
+	}
+
+	// Add any events not in the predefined order
+	for event := range byEvent {
+		found := false
+		for _, o := range eventOrder {
+			if event == o {
+				found = true
+				break
+			}
+		}
+		if !found {
+			eventOrder = append(eventOrder, event)
+		}
+	}
+
+	count := 0
+	for _, event := range eventOrder {
+		hooks := byEvent[event]
+		if len(hooks) == 0 {
+			continue
+		}
+
+		fmt.Printf("%s %s\n", style.Bold.Render("▸"), event)
+
+		for _, h := range hooks {
+			count++
+			statusIcon := "●"
+			statusColor := style.Success
+			if !h.def.Enabled {
+				statusIcon = "○"
+				statusColor = style.Dim
+			}
+
+			rolesStr := strings.Join(h.def.Roles, ", ")
+			scopeStr := h.def.Scope
+
+			fmt.Printf("  %s %s\n", statusColor.Render(statusIcon), style.Bold.Render(h.name))
+			fmt.Printf("    %s\n", h.def.Description)
+			fmt.Printf("    %s %s  %s %s\n",
+				style.Dim.Render("roles:"), rolesStr,
+				style.Dim.Render("scope:"), scopeStr)
+
+			if hooksVerbose {
+				fmt.Printf("    %s %s\n", style.Dim.Render("command:"), h.def.Command)
+				for _, m := range h.def.Matchers {
+					fmt.Printf("    %s %s\n", style.Dim.Render("matcher:"), m)
+				}
+			}
+		}
+		fmt.Println()
+	}
+
+	fmt.Printf("%s %d hooks in registry\n", style.Dim.Render("Total:"), count)
+
+	return nil
+}

internal/cmd/hooks_test.go

@@ -133,3 +133,82 @@ func TestParseHooksFileEmptyHooks(t *testing.T) {
 		t.Errorf("expected 0 hooks, got %d", len(hooks))
 	}
 }
+
+func TestDiscoverHooksCrewLevel(t *testing.T) {
+	// Create a temp directory structure simulating a Gas Town workspace
+	tmpDir := t.TempDir()
+
+	// Create rig structure with crew-level and polecats-level settings
+	rigName := "testrig"
+	rigDir := filepath.Join(tmpDir, rigName)
+
+	// Create crew-level settings (inherited by all crew members)
+	crewClaudeDir := filepath.Join(rigDir, "crew", ".claude")
+	if err := os.MkdirAll(crewClaudeDir, 0755); err != nil {
+		t.Fatalf("failed to create crew/.claude dir: %v", err)
+	}
+
+	crewSettings := ClaudeSettings{
+		Hooks: map[string][]ClaudeHookMatcher{
+			"SessionStart": {
+				{
+					Matcher: "",
+					Hooks: []ClaudeHook{
+						{Type: "command", Command: "crew-level-hook"},
+					},
+				},
+			},
+		},
+	}
+	crewData, _ := json.Marshal(crewSettings)
+	if err := os.WriteFile(filepath.Join(crewClaudeDir, "settings.json"), crewData, 0644); err != nil {
+		t.Fatalf("failed to write crew settings: %v", err)
+	}
+
+	// Create polecats-level settings (inherited by all polecats)
+	polecatsClaudeDir := filepath.Join(rigDir, "polecats", ".claude")
+	if err := os.MkdirAll(polecatsClaudeDir, 0755); err != nil {
+		t.Fatalf("failed to create polecats/.claude dir: %v", err)
+	}
+
+	polecatsSettings := ClaudeSettings{
+		Hooks: map[string][]ClaudeHookMatcher{
+			"PreToolUse": {
+				{
+					Matcher: "",
+					Hooks: []ClaudeHook{
+						{Type: "command", Command: "polecats-level-hook"},
+					},
+				},
+			},
+		},
+	}
+	polecatsData, _ := json.Marshal(polecatsSettings)
+	if err := os.WriteFile(filepath.Join(polecatsClaudeDir, "settings.json"), polecatsData, 0644); err != nil {
+		t.Fatalf("failed to write polecats settings: %v", err)
+	}
+
+	// Discover hooks
+	hooks, err := discoverHooks(tmpDir)
+	if err != nil {
+		t.Fatalf("discoverHooks failed: %v", err)
+	}
+
+	// Verify crew-level hook was discovered
+	var foundCrewLevel, foundPolecatsLevel bool
+	for _, h := range hooks {
+		if h.Agent == "testrig/crew" && len(h.Commands) > 0 && h.Commands[0] == "crew-level-hook" {
+			foundCrewLevel = true
+		}
+		if h.Agent == "testrig/polecats" && len(h.Commands) > 0 && h.Commands[0] == "polecats-level-hook" {
+			foundPolecatsLevel = true
+		}
+	}
+
+	if !foundCrewLevel {
+		t.Error("expected crew-level hook to be discovered (testrig/crew)")
+	}
+	if !foundPolecatsLevel {
+		t.Error("expected polecats-level hook to be discovered (testrig/polecats)")
+	}
+}

internal/cmd/info.go

@@ -74,9 +74,30 @@ type VersionChange struct {
 
 // versionChanges contains agent-actionable changes for recent versions
 var versionChanges = []VersionChange{
+	{
+		Version: "0.5.0",
+		Date:    "2026-01-22",
+		Changes: []string{
+			"NEW: gt mail read <index> - Read messages by inbox position",
+			"NEW: gt mail hook - Shortcut for gt hook attach from mail",
+			"NEW: --body alias for --message in gt mail send/reply",
+			"NEW: gt bd alias for gt bead, gt work alias for gt hook",
+			"NEW: OpenCode as built-in agent preset (gt config set agent opencode)",
+			"NEW: Config-based role definition system",
+			"NEW: Deacon icon in mayor status line",
+			"NEW: gt hooks - Hook registry and install command",
+			"NEW: Squash merge in refinery for cleaner history",
+			"CHANGED: Parallel mail inbox queries (~6x speedup)",
+			"FIX: Crew session stability - Don't kill pane processes on new sessions",
+			"FIX: Auto-recover from stale tmux pane references",
+			"FIX: KillPaneProcesses now kills pane process itself, not just descendants",
+			"FIX: Convoy ID propagation in refinery and convoy watcher",
+			"FIX: Multi-repo routing for custom types and role slots",
+		},
+	},
 	{
 		Version: "0.4.0",
-		Date:    "2026-01-17",
+		Date:    "2026-01-19",
 		Changes: []string{
 			"FIX: Orphan cleanup skips valid tmux sessions - Prevents false kills of witnesses/refineries/deacon during startup by checking gt-*/hq-* session membership",
 		},

internal/cmd/install.go

@@ -221,6 +221,30 @@ func runInstall(cmd *cobra.Command, args []string) error {
 		fmt.Printf("   ✓ Created deacon/.claude/settings.json\n")
 	}
 
+	// Create boot directory (deacon/dogs/boot/) for Boot watchdog.
+	// This avoids gt doctor warning on fresh install.
+	bootDir := filepath.Join(deaconDir, "dogs", "boot")
+	if err := os.MkdirAll(bootDir, 0755); err != nil {
+		fmt.Printf("   %s Could not create boot directory: %v\n", style.Dim.Render("⚠"), err)
+	}
+
+	// Create plugins directory for town-level patrol plugins.
+	// This avoids gt doctor warning on fresh install.
+	pluginsDir := filepath.Join(absPath, "plugins")
+	if err := os.MkdirAll(pluginsDir, 0755); err != nil {
+		fmt.Printf("   %s Could not create plugins directory: %v\n", style.Dim.Render("⚠"), err)
+	} else {
+		fmt.Printf("   ✓ Created plugins/\n")
+	}
+
+	// Create daemon.json patrol config.
+	// This avoids gt doctor warning on fresh install.
+	if err := config.EnsureDaemonPatrolConfig(absPath); err != nil {
+		fmt.Printf("   %s Could not create daemon.json: %v\n", style.Dim.Render("⚠"), err)
+	} else {
+		fmt.Printf("   ✓ Created mayor/daemon.json\n")
+	}
+
 	// Initialize git BEFORE beads so that bd can compute repository fingerprint.
 	// The fingerprint is required for the daemon to start properly.
 	if installGit || installGitHub != "" {
@@ -234,6 +258,12 @@ func runInstall(cmd *cobra.Command, args []string) error {
 	// Town beads (hq- prefix) stores mayor mail, cross-rig coordination, and handoffs.
 	// Rig beads are separate and have their own prefixes.
 	if !installNoBeads {
+		// Kill any orphaned bd daemons before initializing beads.
+		// Stale daemons can interfere with fresh database creation.
+		if killed, _, _ := beads.StopAllBdProcesses(false, true); killed > 0 {
+			fmt.Printf("   ✓ Stopped %d orphaned bd daemon(s)\n", killed)
+		}
+
 		if err := initTownBeads(absPath); err != nil {
 			fmt.Printf("   %s Could not initialize town beads: %v\n", style.Dim.Render("⚠"), err)
 		} else {
@@ -248,7 +278,7 @@ func runInstall(cmd *cobra.Command, args []string) error {
 			}
 		}
 
-		// Create town-level agent beads (Mayor, Deacon) and role beads.
+		// Create town-level agent beads (Mayor, Deacon).
 		// These use hq- prefix and are stored in town beads for cross-rig coordination.
 		if err := initTownAgentBeads(absPath); err != nil {
 			fmt.Printf("   %s Could not create town-level agent beads: %v\n", style.Dim.Render("⚠"), err)
@@ -369,6 +399,19 @@ func initTownBeads(townPath string) error {
 		}
 	}
 
+	// Verify .beads directory was actually created (bd init can exit 0 without creating it)
+	beadsDir := filepath.Join(townPath, ".beads")
+	if _, statErr := os.Stat(beadsDir); os.IsNotExist(statErr) {
+		return fmt.Errorf("bd init succeeded but .beads directory not created (check bd daemon interference)")
+	}
+
+	// Explicitly set issue_prefix config (bd init --prefix may not persist it in newer versions).
+	prefixSetCmd := exec.Command("bd", "config", "set", "issue_prefix", "hq")
+	prefixSetCmd.Dir = townPath
+	if prefixOutput, prefixErr := prefixSetCmd.CombinedOutput(); prefixErr != nil {
+		return fmt.Errorf("bd config set issue_prefix failed: %s", strings.TrimSpace(string(prefixOutput)))
+	}
+
 	// Configure custom types for Gas Town (agent, role, rig, convoy, slot).
 	// These were extracted from beads core in v0.46.0 and now require explicit config.
 	configCmd := exec.Command("bd", "config", "set", "types.custom", constants.BeadsCustomTypes)
@@ -448,58 +491,30 @@ func ensureCustomTypes(beadsPath string) error {
 	return nil
 }
 
-// initTownAgentBeads creates town-level agent and role beads using hq- prefix.
+// initTownAgentBeads creates town-level agent beads using hq- prefix.
 // This creates:
 //   - hq-mayor, hq-deacon (agent beads for town-level agents)
-//   - hq-mayor-role, hq-deacon-role, hq-witness-role, hq-refinery-role,
-//     hq-polecat-role, hq-crew-role (role definition beads)
 //
 // These beads are stored in town beads (~/gt/.beads/) and are shared across all rigs.
 // Rig-level agent beads (witness, refinery) are created by gt rig add in rig beads.
 //
-// ERROR HANDLING ASYMMETRY:
-// Agent beads (Mayor, Deacon) use hard fail - installation aborts if creation fails.
-// Role beads use soft fail - logs warning and continues if creation fails.
+// Note: Role definitions are now config-based (internal/config/roles/*.toml),
+// not stored as beads. See config-based-roles.md for details.
 //
-// Rationale: Agent beads are identity beads that track agent state, hooks, and
+// Agent beads use hard fail - installation aborts if creation fails.
+// Agent beads are identity beads that track agent state, hooks, and
 // form the foundation of the CV/reputation ledger. Without them, agents cannot
-// be properly tracked or coordinated. Role beads are documentation templates
-// that define role characteristics but are not required for agent operation -
-// agents can function without their role bead existing.
+// be properly tracked or coordinated.
 func initTownAgentBeads(townPath string) error {
 	bd := beads.New(townPath)
 
 	// bd init doesn't enable "custom" issue types by default, but Gas Town uses
-	// agent/role beads during install and runtime. Ensure these types are enabled
+	// agent beads during install and runtime. Ensure these types are enabled
 	// before attempting to create any town-level system beads.
-	if err := ensureBeadsCustomTypes(townPath, []string{"agent", "role", "rig", "convoy", "slot"}); err != nil {
+	if err := ensureBeadsCustomTypes(townPath, constants.BeadsCustomTypesList()); err != nil {
 		return err
 	}
 
-	// Role beads (global templates) - use shared definitions from beads package
-	for _, role := range beads.AllRoleBeadDefs() {
-		// Check if already exists
-		if _, err := bd.Show(role.ID); err == nil {
-			continue // Already exists
-		}
-
-		// Create role bead using the beads API
-		// CreateWithID with Type: "role" automatically adds gt:role label
-		_, err := bd.CreateWithID(role.ID, beads.CreateOptions{
-			Title:       role.Title,
-			Type:        "role",
-			Description: role.Desc,
-			Priority:    -1, // No priority
-		})
-		if err != nil {
-			// Log but continue - role beads are optional
-			fmt.Printf("   %s Could not create role bead %s: %v\n",
-				style.Dim.Render("⚠"), role.ID, err)
-			continue
-		}
-		fmt.Printf("   ✓ Created role bead: %s\n", role.ID)
-	}
-
 	// Town-level agent beads
 	agentDefs := []struct {
 		id       string
@@ -541,7 +556,7 @@ func initTownAgentBeads(townPath string) error {
 			Rig:        "", // Town-level agents have no rig
 			AgentState: "idle",
 			HookBead:   "",
-			RoleBead:   beads.RoleBeadIDTown(agent.roleType),
+			// Note: RoleBead field removed - role definitions are now config-based
 		}
 
 		if _, err := bd.CreateAgentBead(agent.id, agent.title, fields); err != nil {

internal/cmd/install_integration_test.go

@@ -122,46 +122,6 @@ func TestInstallBeadsHasCorrectPrefix(t *testing.T) {
 	}
 }
 
-// TestInstallTownRoleSlots validates that town-level agent beads
-// have their role slot set after install.
-func TestInstallTownRoleSlots(t *testing.T) {
-	// Skip if bd is not available
-	if _, err := exec.LookPath("bd"); err != nil {
-		t.Skip("bd not installed, skipping role slot test")
-	}
-
-	tmpDir := t.TempDir()
-	hqPath := filepath.Join(tmpDir, "test-hq")
-
-	gtBinary := buildGT(t)
-
-	// Run gt install (includes beads init by default)
-	cmd := exec.Command(gtBinary, "install", hqPath)
-	cmd.Env = append(os.Environ(), "HOME="+tmpDir)
-	output, err := cmd.CombinedOutput()
-	if err != nil {
-		t.Fatalf("gt install failed: %v\nOutput: %s", err, output)
-	}
-
-	// Log install output for CI debugging
-	t.Logf("gt install output:\n%s", output)
-
-	// Verify beads directory was created
-	beadsDir := filepath.Join(hqPath, ".beads")
-	if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
-		t.Fatalf("beads directory not created at %s", beadsDir)
-	}
-
-	// List beads for debugging
-	listCmd := exec.Command("bd", "--no-daemon", "list", "--type=agent")
-	listCmd.Dir = hqPath
-	listOutput, _ := listCmd.CombinedOutput()
-	t.Logf("bd list --type=agent output:\n%s", listOutput)
-
-	assertSlotValue(t, hqPath, "hq-mayor", "role", "hq-mayor-role")
-	assertSlotValue(t, hqPath, "hq-deacon", "role", "hq-deacon-role")
-}
-
 // TestInstallIdempotent validates that running gt install twice
 // on the same directory fails without --force flag.
 func TestInstallIdempotent(t *testing.T) {
@@ -327,54 +287,6 @@ func TestInstallNoBeadsFlag(t *testing.T) {
 	}
 }
 
-// buildGT builds the gt binary and returns its path.
-// It caches the build across tests in the same run.
-var cachedGTBinary string
-
-func buildGT(t *testing.T) string {
-	t.Helper()
-
-	if cachedGTBinary != "" {
-		// Verify cached binary still exists
-		if _, err := os.Stat(cachedGTBinary); err == nil {
-			return cachedGTBinary
-		}
-		// Binary was cleaned up, rebuild
-		cachedGTBinary = ""
-	}
-
-	// Find project root (where go.mod is)
-	wd, err := os.Getwd()
-	if err != nil {
-		t.Fatalf("failed to get working directory: %v", err)
-	}
-
-	// Walk up to find go.mod
-	projectRoot := wd
-	for {
-		if _, err := os.Stat(filepath.Join(projectRoot, "go.mod")); err == nil {
-			break
-		}
-		parent := filepath.Dir(projectRoot)
-		if parent == projectRoot {
-			t.Fatal("could not find project root (go.mod)")
-		}
-		projectRoot = parent
-	}
-
-	// Build gt binary to a persistent temp location (not per-test)
-	tmpDir := os.TempDir()
-	tmpBinary := filepath.Join(tmpDir, "gt-integration-test")
-	cmd := exec.Command("go", "build", "-o", tmpBinary, "./cmd/gt")
-	cmd.Dir = projectRoot
-	if output, err := cmd.CombinedOutput(); err != nil {
-		t.Fatalf("failed to build gt: %v\nOutput: %s", err, output)
-	}
-
-	cachedGTBinary = tmpBinary
-	return tmpBinary
-}
-
 // assertDirExists checks that the given path exists and is a directory.
 func assertDirExists(t *testing.T, path, name string) {
 	t.Helper()

internal/cmd/mail.go

@@ -21,6 +21,7 @@ var (
 	mailInboxJSON     bool
 	mailReadJSON      bool
 	mailInboxUnread   bool
+	mailInboxAll      bool
 	mailInboxIdentity string
 	mailCheckInject   bool
 	mailCheckJSON     bool
@@ -41,6 +42,10 @@ var (
 
 	// Clear flags
 	mailClearAll bool
+
+	// Archive flags
+	mailArchiveStale  bool
+	mailArchiveDryRun bool
 )
 
 var mailCmd = &cobra.Command{
@@ -138,8 +143,13 @@ var mailInboxCmd = &cobra.Command{
 If no address is specified, shows the current context's inbox.
 Use --identity for polecats to explicitly specify their identity.
 
+By default, shows all messages. Use --unread to filter to unread only,
+or --all to explicitly show all messages (read and unread).
+
 Examples:
   gt mail inbox                       # Current context (auto-detected)
+  gt mail inbox --all                 # Explicitly show all messages
+  gt mail inbox --unread              # Show only unread messages
   gt mail inbox mayor/                # Mayor's inbox
   gt mail inbox greenplace/Toast         # Polecat's inbox
   gt mail inbox --identity greenplace/Toast  # Explicit polecat identity`,
@@ -148,15 +158,21 @@ Examples:
 }
 
 var mailReadCmd = &cobra.Command{
-	Use:   "read <message-id>",
+	Use:   "read <message-id|index>",
 	Short: "Read a message",
 	Long: `Read a specific message (does not mark as read).
 
-The message ID can be found from 'gt mail inbox'.
+You can specify a message by its ID or by its numeric index from the inbox.
+The index corresponds to the number shown in 'gt mail inbox' (1-based).
+
+Examples:
+  gt mail read hq-abc123    # Read by message ID
+  gt mail read 3            # Read the 3rd message in inbox
+
 Use 'gt mail mark-read' to mark messages as read.`,
 	Aliases: []string{"show"},
-	Args: cobra.ExactArgs(1),
-	RunE: runMailRead,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runMailRead,
 }
 
 var mailPeekCmd = &cobra.Command{
@@ -170,26 +186,36 @@ Exits silently with code 1 if no unread messages.`,
 }
 
 var mailDeleteCmd = &cobra.Command{
-	Use:   "delete <message-id>",
-	Short: "Delete a message",
-	Long: `Delete (acknowledge) a message.
+	Use:   "delete <message-id> [message-id...]",
+	Short: "Delete messages",
+	Long: `Delete (acknowledge) one or more messages.
 
-This closes the message in beads.`,
-	Args: cobra.ExactArgs(1),
+This closes the messages in beads.
+
+Examples:
+  gt mail delete hq-abc123
+  gt mail delete hq-abc123 hq-def456 hq-ghi789`,
+	Args: cobra.MinimumNArgs(1),
 	RunE: runMailDelete,
 }
 
 var mailArchiveCmd = &cobra.Command{
-	Use:   "archive <message-id> [message-id...]",
+	Use:   "archive [message-id...]",
 	Short: "Archive messages",
 	Long: `Archive one or more messages.
 
 Removes the messages from your inbox by closing them in beads.
 
+Use --stale to archive messages sent before your current session started.
+
 Examples:
-  gt mail archive hq-abc123
-  gt mail archive hq-abc123 hq-def456 hq-ghi789`,
-	Args: cobra.MinimumNArgs(1),
+	gt mail archive hq-abc123
+	gt mail archive hq-abc123 hq-def456 hq-ghi789
+	gt mail archive --stale
+	gt mail archive --stale --dry-run`,
+	Args: func(cmd *cobra.Command, args []string) error {
+		return nil
+	},
 	RunE: runMailArchive,
 }
 
@@ -262,7 +288,7 @@ Examples:
 }
 
 var mailReplyCmd = &cobra.Command{
-	Use:   "reply <message-id>",
+	Use:   "reply <message-id> [message]",
 	Short: "Reply to a message",
 	Long: `Reply to a specific message.
 
@@ -271,10 +297,13 @@ This is a convenience command that automatically:
 - Prefixes the subject with "Re: " (if not already present)
 - Sends to the original sender
 
+The message body can be provided as a positional argument or via -m flag.
+
 Examples:
+  gt mail reply msg-abc123 "Thanks, working on it now"
   gt mail reply msg-abc123 -m "Thanks, working on it now"
   gt mail reply msg-abc123 -s "Custom subject" -m "Reply body"`,
-	Args: cobra.ExactArgs(1),
+	Args: cobra.RangeArgs(1, 2),
 	RunE: runMailReply,
 }
 
@@ -418,6 +447,7 @@ func init() {
 	// Send flags
 	mailSendCmd.Flags().StringVarP(&mailSubject, "subject", "s", "", "Message subject (required)")
 	mailSendCmd.Flags().StringVarP(&mailBody, "message", "m", "", "Message body")
+	mailSendCmd.Flags().StringVar(&mailBody, "body", "", "Alias for --message")
 	mailSendCmd.Flags().IntVar(&mailPriority, "priority", 2, "Message priority (0=urgent, 1=high, 2=normal, 3=low, 4=backlog)")
 	mailSendCmd.Flags().BoolVar(&mailUrgent, "urgent", false, "Set priority=0 (urgent)")
 	mailSendCmd.Flags().StringVar(&mailType, "type", "notification", "Message type (task, scavenge, notification, reply)")
@@ -433,6 +463,7 @@ func init() {
 	// Inbox flags
 	mailInboxCmd.Flags().BoolVar(&mailInboxJSON, "json", false, "Output as JSON")
 	mailInboxCmd.Flags().BoolVarP(&mailInboxUnread, "unread", "u", false, "Show only unread messages")
+	mailInboxCmd.Flags().BoolVarP(&mailInboxAll, "all", "a", false, "Show all messages (read and unread)")
 	mailInboxCmd.Flags().StringVar(&mailInboxIdentity, "identity", "", "Explicit identity for inbox (e.g., greenplace/Toast)")
 	mailInboxCmd.Flags().StringVar(&mailInboxIdentity, "address", "", "Alias for --identity")
 
@@ -450,8 +481,8 @@ func init() {
 
 	// Reply flags
 	mailReplyCmd.Flags().StringVarP(&mailReplySubject, "subject", "s", "", "Override reply subject (default: Re: <original>)")
-	mailReplyCmd.Flags().StringVarP(&mailReplyMessage, "message", "m", "", "Reply message body (required)")
-	_ = mailReplyCmd.MarkFlagRequired("message")
+	mailReplyCmd.Flags().StringVarP(&mailReplyMessage, "message", "m", "", "Reply message body")
+	mailReplyCmd.Flags().StringVar(&mailReplyMessage, "body", "", "Reply message body (alias for --message)")
 
 	// Search flags
 	mailSearchCmd.Flags().StringVar(&mailSearchFrom, "from", "", "Filter by sender address")
@@ -466,6 +497,10 @@ func init() {
 	// Clear flags
 	mailClearCmd.Flags().BoolVar(&mailClearAll, "all", false, "Clear all messages (default behavior)")
 
+	// Archive flags
+	mailArchiveCmd.Flags().BoolVar(&mailArchiveStale, "stale", false, "Archive messages sent before session start")
+	mailArchiveCmd.Flags().BoolVarP(&mailArchiveDryRun, "dry-run", "n", false, "Show what would be archived without archiving")
+
 	// Add subcommands
 	mailCmd.AddCommand(mailSendCmd)
 	mailCmd.AddCommand(mailInboxCmd)

internal/cmd/mail_archive_test.go

@@ -0,0 +1,25 @@
+package cmd
+
+import (
+	"testing"
+	"time"
+
+	"github.com/steveyegge/gastown/internal/mail"
+)
+
+func TestStaleMessagesForSession(t *testing.T) {
+	sessionStart := time.Date(2026, 1, 24, 2, 0, 0, 0, time.UTC)
+	messages := []*mail.Message{
+		{ID: "msg-1", Subject: "Older", Timestamp: sessionStart.Add(-2 * time.Minute)},
+		{ID: "msg-2", Subject: "Newer", Timestamp: sessionStart.Add(2 * time.Minute)},
+		{ID: "msg-3", Subject: "Equal", Timestamp: sessionStart},
+	}
+
+	stale := staleMessagesForSession(messages, sessionStart)
+	if len(stale) != 1 {
+		t.Fatalf("expected 1 stale message, got %d", len(stale))
+	}
+	if stale[0].Message.ID != "msg-1" {
+		t.Fatalf("expected msg-1 stale, got %s", stale[0].Message.ID)
+	}
+}

internal/cmd/mail_hook.go

@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// Flags for mail hook command (mirror of hook command flags)
+var (
+	mailHookSubject string
+	mailHookMessage string
+	mailHookDryRun  bool
+	mailHookForce   bool
+)
+
+var mailHookCmd = &cobra.Command{
+	Use:   "hook <mail-id>",
+	Short: "Attach mail to your hook (alias for 'gt hook attach')",
+	Long: `Attach a mail message to your hook.
+
+This is an alias for 'gt hook attach <mail-id>'. It attaches the specified
+mail message to your hook so you can work on it.
+
+The hook is the "durability primitive" - work on your hook survives session
+restarts, context compaction, and handoffs.
+
+Examples:
+  gt mail hook msg-abc123                    # Attach mail to your hook
+  gt mail hook msg-abc123 -s "Fix the bug"   # With subject for handoff
+  gt mail hook msg-abc123 --force            # Replace existing incomplete work
+
+Related commands:
+  gt hook <bead>     # Attach any bead to your hook
+  gt hook status     # Show what's on your hook
+  gt unsling         # Remove work from hook`,
+	Args: cobra.ExactArgs(1),
+	RunE: runMailHook,
+}
+
+func init() {
+	mailHookCmd.Flags().StringVarP(&mailHookSubject, "subject", "s", "", "Subject for handoff mail (optional)")
+	mailHookCmd.Flags().StringVarP(&mailHookMessage, "message", "m", "", "Message for handoff mail (optional)")
+	mailHookCmd.Flags().BoolVarP(&mailHookDryRun, "dry-run", "n", false, "Show what would be done")
+	mailHookCmd.Flags().BoolVarP(&mailHookForce, "force", "f", false, "Replace existing incomplete hooked bead")
+
+	mailCmd.AddCommand(mailHookCmd)
+}
+
+// runMailHook attaches mail to the hook - delegates to the hook command's logic
+func runMailHook(cmd *cobra.Command, args []string) error {
+	// Copy flags to hook command's globals (they share the same functionality)
+	hookSubject = mailHookSubject
+	hookMessage = mailHookMessage
+	hookDryRun = mailHookDryRun
+	hookForce = mailHookForce
+
+	// Delegate to the hook command's run function
+	return runHook(cmd, args)
+}

internal/cmd/mail_identity.go

@@ -129,6 +129,13 @@ func detectSenderFromRole(role string) string {
 			return fmt.Sprintf("%s/refinery", rig)
 		}
 		return detectSenderFromCwd()
+	case "dog":
+		// Dogs use BD_ACTOR directly (set by BuildDogStartupCommand)
+		actor := os.Getenv("BD_ACTOR")
+		if actor != "" {
+			return actor
+		}
+		return detectSenderFromCwd()
 	default:
 		// Unknown role, try cwd detection
 		return detectSenderFromCwd()

internal/cmd/mail_inbox.go

@@ -5,10 +5,13 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"strconv"
 	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
 	"github.com/steveyegge/gastown/internal/mail"
+	"github.com/steveyegge/gastown/internal/session"
 	"github.com/steveyegge/gastown/internal/style"
 )
 
@@ -30,6 +33,11 @@ func getMailbox(address string) (*mail.Mailbox, error) {
 }
 
 func runMailInbox(cmd *cobra.Command, args []string) error {
+	// Check for mutually exclusive flags
+	if mailInboxAll && mailInboxUnread {
+		return errors.New("--all and --unread are mutually exclusive")
+	}
+
 	// Determine which inbox to check (priority: --identity flag, positional arg, auto-detect)
 	address := ""
 	if mailInboxIdentity != "" {
@@ -46,6 +54,8 @@ func runMailInbox(cmd *cobra.Command, args []string) error {
 	}
 
 	// Get messages
+	// --all is the default behavior (shows all messages)
+	// --unread filters to only unread messages
 	var messages []*mail.Message
 	if mailInboxUnread {
 		messages, err = mailbox.ListUnread()
@@ -73,7 +83,7 @@ func runMailInbox(cmd *cobra.Command, args []string) error {
 		return nil
 	}
 
-	for _, msg := range messages {
+	for i, msg := range messages {
 		readMarker := "●"
 		if msg.Read {
 			readMarker = "○"
@@ -91,11 +101,13 @@ func runMailInbox(cmd *cobra.Command, args []string) error {
 			wispMarker = " " + style.Dim.Render("(wisp)")
 		}
 
-		fmt.Printf("  %s %s%s%s%s\n", readMarker, msg.Subject, typeMarker, priorityMarker, wispMarker)
-		fmt.Printf("    %s from %s\n",
+		// Show 1-based index for easy reference with 'gt mail read <n>'
+		indexStr := style.Dim.Render(fmt.Sprintf("%d.", i+1))
+		fmt.Printf("  %s %s %s%s%s%s\n", indexStr, readMarker, msg.Subject, typeMarker, priorityMarker, wispMarker)
+		fmt.Printf("      %s from %s\n",
 			style.Dim.Render(msg.ID),
 			msg.From)
-		fmt.Printf("    %s\n",
+		fmt.Printf("      %s\n",
 			style.Dim.Render(msg.Timestamp.Format("2006-01-02 15:04")))
 	}
 
@@ -104,9 +116,9 @@ func runMailInbox(cmd *cobra.Command, args []string) error {
 
 func runMailRead(cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
-		return errors.New("msgID argument required")
+		return errors.New("message ID or index required")
 	}
-	msgID := args[0]
+	msgRef := args[0]
 
 	// Determine which inbox
 	address := detectSender()
@@ -116,6 +128,22 @@ func runMailRead(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
+	// Check if the argument is a numeric index (1-based)
+	var msgID string
+	if idx, err := strconv.Atoi(msgRef); err == nil && idx > 0 {
+		// Numeric index: resolve to message ID by listing inbox
+		messages, err := mailbox.List()
+		if err != nil {
+			return fmt.Errorf("listing messages: %w", err)
+		}
+		if idx > len(messages) {
+			return fmt.Errorf("index %d out of range (inbox has %d messages)", idx, len(messages))
+		}
+		msgID = messages[idx-1].ID
+	} else {
+		msgID = msgRef
+	}
+
 	msg, err := mailbox.Get(msgID)
 	if err != nil {
 		return fmt.Errorf("getting message: %w", err)
@@ -217,11 +245,6 @@ func runMailPeek(cmd *cobra.Command, args []string) error {
 }
 
 func runMailDelete(cmd *cobra.Command, args []string) error {
-	if len(args) == 0 {
-		return errors.New("msgID argument required")
-	}
-	msgID := args[0]
-
 	// Determine which inbox
 	address := detectSender()
 
@@ -230,11 +253,32 @@ func runMailDelete(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	if err := mailbox.Delete(msgID); err != nil {
-		return fmt.Errorf("deleting message: %w", err)
+	// Delete all specified messages
+	deleted := 0
+	var errors []string
+	for _, msgID := range args {
+		if err := mailbox.Delete(msgID); err != nil {
+			errors = append(errors, fmt.Sprintf("%s: %v", msgID, err))
+		} else {
+			deleted++
+		}
 	}
 
-	fmt.Printf("%s Message deleted\n", style.Bold.Render("✓"))
+	// Report results
+	if len(errors) > 0 {
+		fmt.Printf("%s Deleted %d/%d messages\n",
+			style.Bold.Render("⚠"), deleted, len(args))
+		for _, e := range errors {
+			fmt.Printf("  Error: %s\n", e)
+		}
+		return fmt.Errorf("failed to delete %d messages", len(errors))
+	}
+
+	if len(args) == 1 {
+		fmt.Printf("%s Message deleted\n", style.Bold.Render("✓"))
+	} else {
+		fmt.Printf("%s Deleted %d messages\n", style.Bold.Render("✓"), deleted)
+	}
 	return nil
 }
 
@@ -247,6 +291,23 @@ func runMailArchive(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
+	if mailArchiveStale {
+		if len(args) > 0 {
+			return errors.New("--stale cannot be combined with message IDs")
+		}
+		return runMailArchiveStale(mailbox, address)
+	}
+	if len(args) == 0 {
+		return errors.New("message ID required unless using --stale")
+	}
+	if mailArchiveDryRun {
+		fmt.Printf("%s Would archive %d message(s)\n", style.Dim.Render("(dry-run)"), len(args))
+		for _, msgID := range args {
+			fmt.Printf("  %s\n", style.Dim.Render(msgID))
+		}
+		return nil
+	}
+
 	// Archive all specified messages
 	archived := 0
 	var errors []string
@@ -276,6 +337,87 @@ func runMailArchive(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+type staleMessage struct {
+	Message *mail.Message
+	Reason  string
+}
+
+func runMailArchiveStale(mailbox *mail.Mailbox, address string) error {
+	identity, err := session.ParseAddress(address)
+	if err != nil {
+		return fmt.Errorf("determining session for %s: %w", address, err)
+	}
+
+	sessionName := identity.SessionName()
+	if sessionName == "" {
+		return fmt.Errorf("could not determine session name for %s", address)
+	}
+
+	sessionStart, err := session.SessionCreatedAt(sessionName)
+	if err != nil {
+		return fmt.Errorf("getting session start time for %s: %w", sessionName, err)
+	}
+
+	messages, err := mailbox.List()
+	if err != nil {
+		return fmt.Errorf("listing messages: %w", err)
+	}
+
+	staleMessages := staleMessagesForSession(messages, sessionStart)
+	if mailArchiveDryRun {
+		if len(staleMessages) == 0 {
+			fmt.Printf("%s No stale messages found\n", style.Success.Render("✓"))
+			return nil
+		}
+		fmt.Printf("%s Would archive %d stale message(s):\n", style.Dim.Render("(dry-run)"), len(staleMessages))
+		for _, stale := range staleMessages {
+			fmt.Printf("  %s %s\n", style.Dim.Render(stale.Message.ID), stale.Message.Subject)
+		}
+		return nil
+	}
+
+	if len(staleMessages) == 0 {
+		fmt.Printf("%s No stale messages to archive\n", style.Success.Render("✓"))
+		return nil
+	}
+
+	archived := 0
+	var errors []string
+	for _, stale := range staleMessages {
+		if err := mailbox.Delete(stale.Message.ID); err != nil {
+			errors = append(errors, fmt.Sprintf("%s: %v", stale.Message.ID, err))
+		} else {
+			archived++
+		}
+	}
+
+	if len(errors) > 0 {
+		fmt.Printf("%s Archived %d/%d stale messages\n", style.Bold.Render("⚠"), archived, len(staleMessages))
+		for _, e := range errors {
+			fmt.Printf("  Error: %s\n", e)
+		}
+		return fmt.Errorf("failed to archive %d stale messages", len(errors))
+	}
+
+	if archived == 1 {
+		fmt.Printf("%s Stale message archived\n", style.Bold.Render("✓"))
+	} else {
+		fmt.Printf("%s Archived %d stale messages\n", style.Bold.Render("✓"), archived)
+	}
+	return nil
+}
+
+func staleMessagesForSession(messages []*mail.Message, sessionStart time.Time) []staleMessage {
+	var staleMessages []staleMessage
+	for _, msg := range messages {
+		stale, reason := session.StaleReasonForTimes(msg.Timestamp, sessionStart)
+		if stale {
+			staleMessages = append(staleMessages, staleMessage{Message: msg, Reason: reason})
+		}
+	}
+	return staleMessages
+}
+
 func runMailMarkRead(cmd *cobra.Command, args []string) error {
 	// Determine which inbox
 	address := detectSender()

internal/cmd/mail_thread.go

@@ -80,8 +80,22 @@ func runMailThread(cmd *cobra.Command, args []string) error {
 }
 
 func runMailReply(cmd *cobra.Command, args []string) error {
+	if mailReplyMessage == "" {
+		return fmt.Errorf("required flag \"message\" or \"body\" not set")
+	}
 	msgID := args[0]
 
+	// Get message body from positional arg or flag (positional takes precedence)
+	messageBody := mailReplyMessage
+	if len(args) > 1 {
+		messageBody = args[1]
+	}
+
+	// Validate message is provided
+	if messageBody == "" {
+		return fmt.Errorf("message body required: provide as second argument or use -m flag")
+	}
+
 	// All mail uses town beads (two-level architecture)
 	workDir, err := findMailWorkDir()
 	if err != nil {
@@ -118,7 +132,7 @@ func runMailReply(cmd *cobra.Command, args []string) error {
 		From:     from,
 		To:       original.From, // Reply to sender
 		Subject:  subject,
-		Body:     mailReplyMessage,
+		Body:     messageBody,
 		Type:     mail.TypeReply,
 		Priority: mail.PriorityNormal,
 		ReplyTo:  msgID,

internal/cmd/mayor.go

@@ -200,6 +200,20 @@ func runMayorAttach(cmd *cobra.Command, args []string) error {
 				return fmt.Errorf("building startup command: %w", err)
 			}
 
+			// Set remain-on-exit so the pane survives process death during respawn.
+			// Without this, killing processes causes tmux to destroy the pane.
+			if err := t.SetRemainOnExit(paneID, true); err != nil {
+				style.PrintWarning("could not set remain-on-exit: %v", err)
+			}
+
+			// Kill all processes in the pane before respawning to prevent orphan leaks
+			// RespawnPane's -k flag only sends SIGHUP which Claude/Node may ignore
+			if err := t.KillPaneProcesses(paneID); err != nil {
+				// Non-fatal but log the warning
+				style.PrintWarning("could not kill pane processes: %v", err)
+			}
+
+			// Note: respawn-pane automatically resets remain-on-exit to off
 			if err := t.RespawnPane(paneID, startupCmd); err != nil {
 				return fmt.Errorf("restarting runtime: %w", err)
 			}

internal/cmd/migrate_agents.go

@@ -1,325 +0,0 @@
-package cmd
-
-import (
-	"fmt"
-	"path/filepath"
-	"strings"
-
-	"github.com/spf13/cobra"
-	"github.com/steveyegge/gastown/internal/beads"
-	"github.com/steveyegge/gastown/internal/workspace"
-)
-
-var (
-	migrateAgentsDryRun bool
-	migrateAgentsForce  bool
-)
-
-var migrateAgentsCmd = &cobra.Command{
-	Use:     "migrate-agents",
-	GroupID: GroupDiag,
-	Short:   "Migrate agent beads to two-level architecture",
-	Long: `Migrate agent beads from the old single-tier to the two-level architecture.
-
-This command migrates town-level agent beads (Mayor, Deacon) from rig beads
-with gt-* prefix to town beads with hq-* prefix:
-
-  OLD (rig beads):    gt-mayor, gt-deacon
-  NEW (town beads):   hq-mayor, hq-deacon
-
-Rig-level agents (Witness, Refinery, Polecats) remain in rig beads unchanged.
-
-The migration:
-1. Detects old gt-mayor/gt-deacon beads in rig beads
-2. Creates new hq-mayor/hq-deacon beads in town beads
-3. Copies agent state (hook_bead, agent_state, etc.)
-4. Adds migration note to old beads (preserves them)
-
-Safety:
-- Dry-run mode by default (use --execute to apply changes)
-- Old beads are preserved with migration notes
-- Validates new beads exist before marking migration complete
-- Skips if new beads already exist (idempotent)
-
-Examples:
-  gt migrate-agents              # Dry-run: show what would be migrated
-  gt migrate-agents --execute    # Apply the migration
-  gt migrate-agents --force      # Re-migrate even if new beads exist`,
-	RunE: runMigrateAgents,
-}
-
-func init() {
-	migrateAgentsCmd.Flags().BoolVar(&migrateAgentsDryRun, "dry-run", true, "Show what would be migrated without making changes (default)")
-	migrateAgentsCmd.Flags().BoolVar(&migrateAgentsForce, "force", false, "Re-migrate even if new beads already exist")
-	// Add --execute as inverse of --dry-run for clarity
-	migrateAgentsCmd.Flags().BoolP("execute", "x", false, "Actually apply the migration (opposite of --dry-run)")
-	rootCmd.AddCommand(migrateAgentsCmd)
-}
-
-// migrationResult holds the result of a single bead migration.
-type migrationResult struct {
-	OldID      string
-	NewID      string
-	Status     string // "migrated", "skipped", "error"
-	Message    string
-	OldFields  *beads.AgentFields
-	WasDryRun  bool
-}
-
-func runMigrateAgents(cmd *cobra.Command, args []string) error {
-	// Handle --execute flag
-	if execute, _ := cmd.Flags().GetBool("execute"); execute {
-		migrateAgentsDryRun = false
-	}
-
-	// Find town root
-	townRoot, err := workspace.FindFromCwdOrError()
-	if err != nil {
-		return fmt.Errorf("not in a Gas Town workspace: %w", err)
-	}
-
-	// Get town beads path
-	townBeadsDir := filepath.Join(townRoot, ".beads")
-
-	// Load routes to find rig beads
-	routes, err := beads.LoadRoutes(townBeadsDir)
-	if err != nil {
-		return fmt.Errorf("loading routes.jsonl: %w", err)
-	}
-
-	// Find the first rig with gt- prefix (where global agents are currently stored)
-	var sourceRigPath string
-	for _, r := range routes {
-		if strings.TrimSuffix(r.Prefix, "-") == "gt" && r.Path != "." {
-			sourceRigPath = r.Path
-			break
-		}
-	}
-
-	if sourceRigPath == "" {
-		fmt.Println("No rig with gt- prefix found. Nothing to migrate.")
-		return nil
-	}
-
-	// Source beads (rig beads where old agent beads are)
-	sourceBeadsDir := filepath.Join(townRoot, sourceRigPath, ".beads")
-	sourceBd := beads.New(sourceBeadsDir)
-
-	// Target beads (town beads where new agent beads should go)
-	targetBd := beads.NewWithBeadsDir(townRoot, townBeadsDir)
-
-	// Agents to migrate: town-level agents only
-	agentsToMigrate := []struct {
-		oldID   string
-		newID   string
-		desc    string
-	}{
-		{
-			oldID: beads.MayorBeadID(),  // gt-mayor
-			newID: beads.MayorBeadIDTown(), // hq-mayor
-			desc:  "Mayor - global coordinator, handles cross-rig communication and escalations.",
-		},
-		{
-			oldID: beads.DeaconBeadID(),  // gt-deacon
-			newID: beads.DeaconBeadIDTown(), // hq-deacon
-			desc:  "Deacon (daemon beacon) - receives mechanical heartbeats, runs town plugins and monitoring.",
-		},
-	}
-
-	// Also migrate role beads
-	rolesToMigrate := []string{"mayor", "deacon", "witness", "refinery", "polecat", "crew", "dog"}
-
-	if migrateAgentsDryRun {
-		fmt.Println("🔍 DRY RUN: Showing what would be migrated")
-		fmt.Println("   Use --execute to apply changes")
-		fmt.Println()
-	} else {
-		fmt.Println("🚀 Migrating agent beads to two-level architecture")
-		fmt.Println()
-	}
-
-	var results []migrationResult
-
-	// Migrate agent beads
-	fmt.Println("Agent Beads:")
-	for _, agent := range agentsToMigrate {
-		result := migrateAgentBead(sourceBd, targetBd, agent.oldID, agent.newID, agent.desc, migrateAgentsDryRun, migrateAgentsForce)
-		results = append(results, result)
-		printMigrationResult(result)
-	}
-
-	// Migrate role beads
-	fmt.Println("\nRole Beads:")
-	for _, role := range rolesToMigrate {
-		oldID := "gt-" + role + "-role"
-		newID := beads.RoleBeadIDTown(role) // hq-<role>-role
-		result := migrateRoleBead(sourceBd, targetBd, oldID, newID, role, migrateAgentsDryRun, migrateAgentsForce)
-		results = append(results, result)
-		printMigrationResult(result)
-	}
-
-	// Summary
-	fmt.Println()
-	printMigrationSummary(results, migrateAgentsDryRun)
-
-	return nil
-}
-
-// migrateAgentBead migrates a single agent bead from source to target.
-func migrateAgentBead(sourceBd, targetBd *beads.Beads, oldID, newID, desc string, dryRun, force bool) migrationResult {
-	result := migrationResult{
-		OldID:     oldID,
-		NewID:     newID,
-		WasDryRun: dryRun,
-	}
-
-	// Check if old bead exists
-	oldIssue, oldFields, err := sourceBd.GetAgentBead(oldID)
-	if err != nil {
-		result.Status = "skipped"
-		result.Message = "old bead not found"
-		return result
-	}
-	result.OldFields = oldFields
-
-	// Check if new bead already exists
-	if _, err := targetBd.Show(newID); err == nil {
-		if !force {
-			result.Status = "skipped"
-			result.Message = "new bead already exists (use --force to re-migrate)"
-			return result
-		}
-	}
-
-	if dryRun {
-		result.Status = "would migrate"
-		result.Message = fmt.Sprintf("would copy state from %s", oldIssue.ID)
-		return result
-	}
-
-	// Create new bead in town beads
-	newFields := &beads.AgentFields{
-		RoleType:          oldFields.RoleType,
-		Rig:               oldFields.Rig,
-		AgentState:        oldFields.AgentState,
-		HookBead:          oldFields.HookBead,
-		RoleBead:          beads.RoleBeadIDTown(oldFields.RoleType), // Update to hq- role
-		CleanupStatus:     oldFields.CleanupStatus,
-		ActiveMR:          oldFields.ActiveMR,
-		NotificationLevel: oldFields.NotificationLevel,
-	}
-
-	_, err = targetBd.CreateAgentBead(newID, desc, newFields)
-	if err != nil {
-		result.Status = "error"
-		result.Message = fmt.Sprintf("failed to create: %v", err)
-		return result
-	}
-
-	// Add migration label to old bead
-	migrationLabel := fmt.Sprintf("migrated-to:%s", newID)
-	if err := sourceBd.Update(oldID, beads.UpdateOptions{AddLabels: []string{migrationLabel}}); err != nil {
-		// Non-fatal: just log it
-		result.Message = fmt.Sprintf("created but couldn't add migration label: %v", err)
-	}
-
-	result.Status = "migrated"
-	result.Message = "successfully migrated"
-	return result
-}
-
-// migrateRoleBead migrates a role definition bead.
-func migrateRoleBead(sourceBd, targetBd *beads.Beads, oldID, newID, role string, dryRun, force bool) migrationResult {
-	result := migrationResult{
-		OldID:     oldID,
-		NewID:     newID,
-		WasDryRun: dryRun,
-	}
-
-	// Check if old bead exists
-	oldIssue, err := sourceBd.Show(oldID)
-	if err != nil {
-		result.Status = "skipped"
-		result.Message = "old bead not found"
-		return result
-	}
-
-	// Check if new bead already exists
-	if _, err := targetBd.Show(newID); err == nil {
-		if !force {
-			result.Status = "skipped"
-			result.Message = "new bead already exists (use --force to re-migrate)"
-			return result
-		}
-	}
-
-	if dryRun {
-		result.Status = "would migrate"
-		result.Message = fmt.Sprintf("would copy from %s", oldIssue.ID)
-		return result
-	}
-
-	// Create new role bead in town beads
-	// Role beads are simple - just copy the description
-	_, err = targetBd.CreateWithID(newID, beads.CreateOptions{
-		Title:       fmt.Sprintf("Role: %s", role),
-		Type:        "role",
-		Description: oldIssue.Title, // Use old title as description
-	})
-	if err != nil {
-		result.Status = "error"
-		result.Message = fmt.Sprintf("failed to create: %v", err)
-		return result
-	}
-
-	// Add migration label to old bead
-	migrationLabel := fmt.Sprintf("migrated-to:%s", newID)
-	if err := sourceBd.Update(oldID, beads.UpdateOptions{AddLabels: []string{migrationLabel}}); err != nil {
-		// Non-fatal
-		result.Message = fmt.Sprintf("created but couldn't add migration label: %v", err)
-	}
-
-	result.Status = "migrated"
-	result.Message = "successfully migrated"
-	return result
-}
-
-func getMigrationStatusIcon(status string) string {
-	switch status {
-	case "migrated", "would migrate":
-		return "  ✓"
-	case "skipped":
-		return "  ⊘"
-	case "error":
-		return "  ✗"
-	default:
-		return "  ?"
-	}
-}
-
-func printMigrationResult(r migrationResult) {
-	fmt.Printf("%s %s → %s: %s\n", getMigrationStatusIcon(r.Status), r.OldID, r.NewID, r.Message)
-}
-
-func printMigrationSummary(results []migrationResult, dryRun bool) {
-	var migrated, skipped, errors int
-	for _, r := range results {
-		switch r.Status {
-		case "migrated", "would migrate":
-			migrated++
-		case "skipped":
-			skipped++
-		case "error":
-			errors++
-		}
-	}
-
-	if dryRun {
-		fmt.Printf("Summary (dry-run): %d would migrate, %d skipped, %d errors\n", migrated, skipped, errors)
-		if migrated > 0 {
-			fmt.Println("\nRun with --execute to apply these changes.")
-		}
-	} else {
-		fmt.Printf("Summary: %d migrated, %d skipped, %d errors\n", migrated, skipped, errors)
-	}
-}

internal/cmd/migrate_agents_test.go

@@ -1,87 +0,0 @@
-package cmd
-
-import (
-	"testing"
-
-	"github.com/steveyegge/gastown/internal/beads"
-)
-
-func TestMigrationResultStatus(t *testing.T) {
-	tests := []struct {
-		name     string
-		result   migrationResult
-		wantIcon string
-	}{
-		{
-			name: "migrated shows checkmark",
-			result: migrationResult{
-				OldID:   "gt-mayor",
-				NewID:   "hq-mayor",
-				Status:  "migrated",
-				Message: "successfully migrated",
-			},
-			wantIcon: "  ✓",
-		},
-		{
-			name: "would migrate shows checkmark",
-			result: migrationResult{
-				OldID:   "gt-mayor",
-				NewID:   "hq-mayor",
-				Status:  "would migrate",
-				Message: "would copy state from gt-mayor",
-			},
-			wantIcon: "  ✓",
-		},
-		{
-			name: "skipped shows empty circle",
-			result: migrationResult{
-				OldID:   "gt-mayor",
-				NewID:   "hq-mayor",
-				Status:  "skipped",
-				Message: "already exists",
-			},
-			wantIcon: "  ⊘",
-		},
-		{
-			name: "error shows X",
-			result: migrationResult{
-				OldID:   "gt-mayor",
-				NewID:   "hq-mayor",
-				Status:  "error",
-				Message: "failed to create",
-			},
-			wantIcon: "  ✗",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			icon := getMigrationStatusIcon(tt.result.Status)
-			if icon != tt.wantIcon {
-				t.Errorf("getMigrationStatusIcon(%q) = %q, want %q", tt.result.Status, icon, tt.wantIcon)
-			}
-		})
-	}
-}
-
-func TestTownBeadIDHelpers(t *testing.T) {
-	tests := []struct {
-		name string
-		got  string
-		want string
-	}{
-		{"MayorBeadIDTown", beads.MayorBeadIDTown(), "hq-mayor"},
-		{"DeaconBeadIDTown", beads.DeaconBeadIDTown(), "hq-deacon"},
-		{"DogBeadIDTown", beads.DogBeadIDTown("fido"), "hq-dog-fido"},
-		{"RoleBeadIDTown mayor", beads.RoleBeadIDTown("mayor"), "hq-mayor-role"},
-		{"RoleBeadIDTown witness", beads.RoleBeadIDTown("witness"), "hq-witness-role"},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			if tt.got != tt.want {
-				t.Errorf("%s = %q, want %q", tt.name, tt.got, tt.want)
-			}
-		})
-	}
-}

internal/cmd/molecule_await_signal.go

@@ -160,7 +160,14 @@ func runMoleculeAwaitSignal(cmd *cobra.Command, args []string) error {
 			result.IdleCycles = newIdleCycles
 		}
 	} else if result.Reason == "signal" && awaitSignalAgentBead != "" {
-		// On signal, report current idle cycles (caller should reset)
+		// On signal, update last_activity to prove agent is alive
+		if err := updateAgentHeartbeat(awaitSignalAgentBead, beadsDir); err != nil {
+			if !awaitSignalQuiet {
+				fmt.Printf("%s Failed to update agent heartbeat: %v\n",
+					style.Dim.Render("⚠"), err)
+			}
+		}
+		// Report current idle cycles (caller should reset)
 		result.IdleCycles = idleCycles
 	}
 
@@ -319,6 +326,14 @@ func parseIntSimple(s string) (int, error) {
 	return n, nil
 }
 
+// updateAgentHeartbeat updates the last_activity timestamp on an agent bead.
+// This proves the agent is alive and processing signals.
+func updateAgentHeartbeat(agentBead, beadsDir string) error {
+	cmd := exec.Command("bd", "agent", "heartbeat", agentBead)
+	cmd.Env = append(os.Environ(), "BEADS_DIR="+beadsDir)
+	return cmd.Run()
+}
+
 // setAgentIdleCycles sets the idle:N label on an agent bead.
 // Uses read-modify-write pattern to update only the idle label.
 func setAgentIdleCycles(agentBead, beadsDir string, cycles int) error {

internal/cmd/molecule_lifecycle_test.go

@@ -0,0 +1,595 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// TestSlingFormulaOnBeadHooksBaseBead verifies that when using
+// "gt sling <formula> --on <bead>", the BASE bead is hooked (not the wisp).
+//
+// Current bug: The code hooks the wisp (compound root) instead of the base bead.
+// This causes lifecycle issues:
+// - Base bead stays open after wisp completes
+// - gt done closes wisp, not the actual work item
+// - Orphaned base beads accumulate
+//
+// Expected behavior: Hook the base bead, store attached_molecule pointing to wisp.
+// gt hook/gt prime can follow attached_molecule to find the workflow steps.
+func TestSlingFormulaOnBeadHooksBaseBead(t *testing.T) {
+	townRoot := t.TempDir()
+
+	// Minimal workspace marker
+	if err := os.MkdirAll(filepath.Join(townRoot, "mayor", "rig"), 0755); err != nil {
+		t.Fatalf("mkdir mayor/rig: %v", err)
+	}
+
+	// Create routes
+	if err := os.MkdirAll(filepath.Join(townRoot, ".beads"), 0755); err != nil {
+		t.Fatalf("mkdir .beads: %v", err)
+	}
+	rigDir := filepath.Join(townRoot, "gastown", "mayor", "rig")
+	if err := os.MkdirAll(rigDir, 0755); err != nil {
+		t.Fatalf("mkdir rigDir: %v", err)
+	}
+	routes := strings.Join([]string{
+		`{"prefix":"gt-","path":"gastown/mayor/rig"}`,
+		`{"prefix":"hq-","path":"."}`,
+		"",
+	}, "\n")
+	if err := os.WriteFile(filepath.Join(townRoot, ".beads", "routes.jsonl"), []byte(routes), 0644); err != nil {
+		t.Fatalf("write routes.jsonl: %v", err)
+	}
+
+	// Stub bd to track which bead gets hooked
+	binDir := filepath.Join(townRoot, "bin")
+	if err := os.MkdirAll(binDir, 0755); err != nil {
+		t.Fatalf("mkdir binDir: %v", err)
+	}
+	logPath := filepath.Join(townRoot, "bd.log")
+	bdScript := `#!/bin/sh
+set -e
+echo "$*" >> "${BD_LOG}"
+if [ "$1" = "--no-daemon" ]; then
+  shift
+fi
+if [ "$1" = "--allow-stale" ]; then
+  shift
+fi
+cmd="$1"
+shift || true
+case "$cmd" in
+  show)
+    # Return the base bead info
+    echo '[{"id":"gt-abc123","title":"Bug to fix","status":"open","assignee":"","description":""}]'
+    ;;
+  formula)
+    echo '{"name":"mol-polecat-work"}'
+    ;;
+  cook)
+    exit 0
+    ;;
+  mol)
+    sub="$1"
+    shift || true
+    case "$sub" in
+      wisp)
+        echo '{"new_epic_id":"gt-wisp-xyz"}'
+        ;;
+      bond)
+        echo '{"root_id":"gt-wisp-xyz"}'
+        ;;
+    esac
+    ;;
+  update)
+    # Just succeed
+    exit 0
+    ;;
+esac
+exit 0
+`
+	bdScriptWindows := `@echo off
+setlocal enableextensions
+echo %*>>"%BD_LOG%"
+set "cmd=%1"
+set "sub=%2"
+if "%cmd%"=="--no-daemon" (
+  set "cmd=%2"
+  set "sub=%3"
+)
+if "%cmd%"=="--allow-stale" (
+  set "cmd=%2"
+  set "sub=%3"
+)
+if "%cmd%"=="show" (
+  echo [{^"id^":^"gt-abc123^",^"title^":^"Bug to fix^",^"status^":^"open^",^"assignee^":^"^",^"description^":^"^"}]
+  exit /b 0
+)
+if "%cmd%"=="formula" (
+  echo {^"name^":^"mol-polecat-work^"}
+  exit /b 0
+)
+if "%cmd%"=="cook" exit /b 0
+if "%cmd%"=="mol" (
+  if "%sub%"=="wisp" (
+    echo {^"new_epic_id^":^"gt-wisp-xyz^"}
+    exit /b 0
+  )
+  if "%sub%"=="bond" (
+    echo {^"root_id^":^"gt-wisp-xyz^"}
+    exit /b 0
+  )
+)
+if "%cmd%"=="update" exit /b 0
+exit /b 0
+`
+	_ = writeBDStub(t, binDir, bdScript, bdScriptWindows)
+
+	t.Setenv("BD_LOG", logPath)
+	t.Setenv("PATH", binDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv(EnvGTRole, "mayor")
+	t.Setenv("GT_POLECAT", "")
+	t.Setenv("GT_CREW", "")
+	t.Setenv("TMUX_PANE", "")
+	t.Setenv("GT_TEST_NO_NUDGE", "1")
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(cwd) })
+	if err := os.Chdir(filepath.Join(townRoot, "mayor", "rig")); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+
+	// Save and restore global flag state
+	prevOn := slingOnTarget
+	prevVars := slingVars
+	prevDryRun := slingDryRun
+	prevNoConvoy := slingNoConvoy
+	t.Cleanup(func() {
+		slingOnTarget = prevOn
+		slingVars = prevVars
+		slingDryRun = prevDryRun
+		slingNoConvoy = prevNoConvoy
+	})
+
+	slingDryRun = false
+	slingNoConvoy = true
+	slingVars = nil
+	slingOnTarget = "gt-abc123" // The base bead
+
+	if err := runSling(nil, []string{"mol-polecat-work"}); err != nil {
+		t.Fatalf("runSling: %v", err)
+	}
+
+	logBytes, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatalf("read bd log: %v", err)
+	}
+
+	// Find the update command that sets status=hooked
+	// Expected: should hook gt-abc123 (base bead)
+	// Current bug: hooks gt-wisp-xyz (wisp)
+	logLines := strings.Split(string(logBytes), "\n")
+	var hookedBeadID string
+	for _, line := range logLines {
+		if strings.Contains(line, "update") && strings.Contains(line, "--status=hooked") {
+			// Extract the bead ID being hooked
+			// Format: "update <beadID> --status=hooked ..."
+			parts := strings.Fields(line)
+			for i, part := range parts {
+				if part == "update" && i+1 < len(parts) {
+					hookedBeadID = parts[i+1]
+					break
+				}
+			}
+			break
+		}
+	}
+
+	if hookedBeadID == "" {
+		t.Fatalf("no hooked bead found in log:\n%s", string(logBytes))
+	}
+
+	// The BASE bead (gt-abc123) should be hooked, not the wisp (gt-wisp-xyz)
+	if hookedBeadID != "gt-abc123" {
+		t.Errorf("wrong bead hooked: got %q, want %q (base bead)\n"+
+			"Current behavior hooks the wisp instead of the base bead.\n"+
+			"This causes orphaned base beads when gt done closes only the wisp.\n"+
+			"Log:\n%s", hookedBeadID, "gt-abc123", string(logBytes))
+	}
+}
+
+// TestSlingFormulaOnBeadSetsAttachedMoleculeInBaseBead verifies that when using
+// "gt sling <formula> --on <bead>", the attached_molecule field is set in the
+// BASE bead's description (pointing to the wisp), not in the wisp itself.
+//
+// Current bug: attached_molecule is stored as a self-reference in the wisp.
+// This is semantically meaningless (wisp points to itself) and breaks
+// compound resolution from the base bead.
+//
+// Expected behavior: Store attached_molecule in the base bead pointing to wisp.
+// This enables:
+// - Compound resolution: base bead -> attached_molecule -> wisp
+// - gt hook/gt prime: read base bead, follow attached_molecule to show wisp steps
+func TestSlingFormulaOnBeadSetsAttachedMoleculeInBaseBead(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Windows batch script JSON output causes storeAttachedMoleculeInBead to fail silently")
+	}
+	townRoot := t.TempDir()
+
+	// Minimal workspace marker
+	if err := os.MkdirAll(filepath.Join(townRoot, "mayor", "rig"), 0755); err != nil {
+		t.Fatalf("mkdir mayor/rig: %v", err)
+	}
+
+	// Create routes
+	if err := os.MkdirAll(filepath.Join(townRoot, ".beads"), 0755); err != nil {
+		t.Fatalf("mkdir .beads: %v", err)
+	}
+	rigDir := filepath.Join(townRoot, "gastown", "mayor", "rig")
+	if err := os.MkdirAll(rigDir, 0755); err != nil {
+		t.Fatalf("mkdir rigDir: %v", err)
+	}
+	routes := strings.Join([]string{
+		`{"prefix":"gt-","path":"gastown/mayor/rig"}`,
+		`{"prefix":"hq-","path":"."}`,
+		"",
+	}, "\n")
+	if err := os.WriteFile(filepath.Join(townRoot, ".beads", "routes.jsonl"), []byte(routes), 0644); err != nil {
+		t.Fatalf("write routes.jsonl: %v", err)
+	}
+
+	// Stub bd to track which bead gets attached_molecule set
+	binDir := filepath.Join(townRoot, "bin")
+	if err := os.MkdirAll(binDir, 0755); err != nil {
+		t.Fatalf("mkdir binDir: %v", err)
+	}
+	logPath := filepath.Join(townRoot, "bd.log")
+	bdScript := `#!/bin/sh
+set -e
+echo "$*" >> "${BD_LOG}"
+if [ "$1" = "--no-daemon" ]; then
+  shift
+fi
+if [ "$1" = "--allow-stale" ]; then
+  shift
+fi
+cmd="$1"
+shift || true
+case "$cmd" in
+  show)
+    # Return bead info without attached_molecule initially
+    echo '[{"id":"gt-abc123","title":"Bug to fix","status":"open","assignee":"","description":""}]'
+    ;;
+  formula)
+    echo '{"name":"mol-polecat-work"}'
+    ;;
+  cook)
+    exit 0
+    ;;
+  mol)
+    sub="$1"
+    shift || true
+    case "$sub" in
+      wisp)
+        echo '{"new_epic_id":"gt-wisp-xyz"}'
+        ;;
+      bond)
+        echo '{"root_id":"gt-wisp-xyz"}'
+        ;;
+    esac
+    ;;
+  update)
+    # Just succeed
+    exit 0
+    ;;
+esac
+exit 0
+`
+	bdScriptWindows := `@echo off
+setlocal enableextensions
+echo %*>>"%BD_LOG%"
+set "cmd=%1"
+set "sub=%2"
+if "%cmd%"=="--no-daemon" (
+  set "cmd=%2"
+  set "sub=%3"
+)
+if "%cmd%"=="--allow-stale" (
+  set "cmd=%2"
+  set "sub=%3"
+)
+if "%cmd%"=="show" (
+  echo [{^"id^":^"gt-abc123^",^"title^":^"Bug to fix^",^"status^":^"open^",^"assignee^":^"^",^"description^":^"^"}]
+  exit /b 0
+)
+if "%cmd%"=="formula" (
+  echo {^"name^":^"mol-polecat-work^"}
+  exit /b 0
+)
+if "%cmd%"=="cook" exit /b 0
+if "%cmd%"=="mol" (
+  if "%sub%"=="wisp" (
+    echo {^"new_epic_id^":^"gt-wisp-xyz^"}
+    exit /b 0
+  )
+  if "%sub%"=="bond" (
+    echo {^"root_id^":^"gt-wisp-xyz^"}
+    exit /b 0
+  )
+)
+if "%cmd%"=="update" exit /b 0
+exit /b 0
+`
+	_ = writeBDStub(t, binDir, bdScript, bdScriptWindows)
+
+	t.Setenv("BD_LOG", logPath)
+	t.Setenv("PATH", binDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv(EnvGTRole, "mayor")
+	t.Setenv("GT_POLECAT", "")
+	t.Setenv("GT_CREW", "")
+	t.Setenv("TMUX_PANE", "")
+	t.Setenv("GT_TEST_NO_NUDGE", "1")
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(cwd) })
+	if err := os.Chdir(filepath.Join(townRoot, "mayor", "rig")); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+
+	// Save and restore global flag state
+	prevOn := slingOnTarget
+	prevVars := slingVars
+	prevDryRun := slingDryRun
+	prevNoConvoy := slingNoConvoy
+	t.Cleanup(func() {
+		slingOnTarget = prevOn
+		slingVars = prevVars
+		slingDryRun = prevDryRun
+		slingNoConvoy = prevNoConvoy
+	})
+
+	slingDryRun = false
+	slingNoConvoy = true
+	slingVars = nil
+	slingOnTarget = "gt-abc123" // The base bead
+
+	if err := runSling(nil, []string{"mol-polecat-work"}); err != nil {
+		t.Fatalf("runSling: %v", err)
+	}
+
+	logBytes, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatalf("read bd log: %v", err)
+	}
+
+	// Find update commands that set attached_molecule
+	// Expected: "update gt-abc123 --description=...attached_molecule: gt-wisp-xyz..."
+	// Current bug: "update gt-wisp-xyz --description=...attached_molecule: gt-wisp-xyz..."
+	logLines := strings.Split(string(logBytes), "\n")
+	var attachedMoleculeTarget string
+	for _, line := range logLines {
+		if strings.Contains(line, "update") && strings.Contains(line, "attached_molecule") {
+			// Extract the bead ID being updated
+			parts := strings.Fields(line)
+			for i, part := range parts {
+				if part == "update" && i+1 < len(parts) {
+					attachedMoleculeTarget = parts[i+1]
+					break
+				}
+			}
+			break
+		}
+	}
+
+	if attachedMoleculeTarget == "" {
+		t.Fatalf("no attached_molecule update found in log:\n%s", string(logBytes))
+	}
+
+	// attached_molecule should be set on the BASE bead, not the wisp
+	if attachedMoleculeTarget != "gt-abc123" {
+		t.Errorf("attached_molecule set on wrong bead: got %q, want %q (base bead)\n"+
+			"Current behavior stores attached_molecule in the wisp as a self-reference.\n"+
+			"This breaks compound resolution (base bead has no pointer to wisp).\n"+
+			"Log:\n%s", attachedMoleculeTarget, "gt-abc123", string(logBytes))
+	}
+}
+
+// TestDoneClosesAttachedMolecule verifies that gt done closes both the hooked
+// bead AND its attached molecule (wisp).
+//
+// Current bug: gt done only closes the hooked bead. If base bead is hooked
+// with attached_molecule pointing to wisp, the wisp becomes orphaned.
+//
+// Expected behavior: gt done should:
+// 1. Check for attached_molecule in hooked bead
+// 2. Close the attached molecule (wisp) first
+// 3. Close the hooked bead (base bead)
+//
+// This ensures no orphaned wisps remain after work completes.
+func TestDoneClosesAttachedMolecule(t *testing.T) {
+	townRoot := t.TempDir()
+
+	// Create rig structure - use simple rig name that matches routes lookup
+	rigPath := filepath.Join(townRoot, "gastown")
+	if err := os.MkdirAll(rigPath, 0755); err != nil {
+		t.Fatalf("mkdir rig: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join(townRoot, ".beads"), 0755); err != nil {
+		t.Fatalf("mkdir .beads: %v", err)
+	}
+
+	// Create routes - path first part must match GT_RIG for prefix lookup
+	routes := strings.Join([]string{
+		`{"prefix":"gt-","path":"gastown"}`,
+		"",
+	}, "\n")
+	if err := os.WriteFile(filepath.Join(townRoot, ".beads", "routes.jsonl"), []byte(routes), 0644); err != nil {
+		t.Fatalf("write routes.jsonl: %v", err)
+	}
+
+	// Stub bd to track close calls
+	binDir := filepath.Join(townRoot, "bin")
+	if err := os.MkdirAll(binDir, 0755); err != nil {
+		t.Fatalf("mkdir binDir: %v", err)
+	}
+	closesPath := filepath.Join(townRoot, "closes.log")
+
+	// The stub simulates:
+	// - Agent bead gt-agent-nux with hook_bead = gt-abc123 (base bead)
+	// - Base bead gt-abc123 with attached_molecule: gt-wisp-xyz, status=hooked
+	// - Wisp gt-wisp-xyz (the attached molecule)
+	bdScript := fmt.Sprintf(`#!/bin/sh
+echo "$*" >> "%s/bd.log"
+# Strip --no-daemon and --allow-stale
+while [ "$1" = "--no-daemon" ] || [ "$1" = "--allow-stale" ]; do
+  shift
+done
+cmd="$1"
+shift || true
+case "$cmd" in
+  show)
+    beadID="$1"
+    case "$beadID" in
+      gt-gastown-polecat-nux)
+        echo '[{"id":"gt-gastown-polecat-nux","title":"Polecat nux","status":"open","hook_bead":"gt-abc123","agent_state":"working"}]'
+        ;;
+      gt-abc123)
+        echo '[{"id":"gt-abc123","title":"Bug to fix","status":"hooked","description":"attached_molecule: gt-wisp-xyz"}]'
+        ;;
+      gt-wisp-xyz)
+        echo '[{"id":"gt-wisp-xyz","title":"mol-polecat-work","status":"open","ephemeral":true}]'
+        ;;
+      *)
+        echo '[]'
+        ;;
+    esac
+    ;;
+  close)
+    echo "$1" >> "%s"
+    ;;
+  agent|update|slot)
+    exit 0
+    ;;
+esac
+exit 0
+`, townRoot, closesPath)
+
+	bdScriptWindows := fmt.Sprintf(`@echo off
+setlocal enableextensions
+echo %%*>>"%s\bd.log"
+set "cmd=%%1"
+set "beadID=%%2"
+:strip_flags
+if "%%cmd%%"=="--no-daemon" (
+  set "cmd=%%2"
+  set "beadID=%%3"
+  shift
+  goto strip_flags
+)
+if "%%cmd%%"=="--allow-stale" (
+  set "cmd=%%2"
+  set "beadID=%%3"
+  shift
+  goto strip_flags
+)
+if "%%cmd%%"=="show" (
+  if "%%beadID%%"=="gt-gastown-polecat-nux" (
+    echo [{^"id^":^"gt-gastown-polecat-nux^",^"title^":^"Polecat nux^",^"status^":^"open^",^"hook_bead^":^"gt-abc123^",^"agent_state^":^"working^"}]
+    exit /b 0
+  )
+  if "%%beadID%%"=="gt-abc123" (
+    echo [{^"id^":^"gt-abc123^",^"title^":^"Bug to fix^",^"status^":^"hooked^",^"description^":^"attached_molecule: gt-wisp-xyz^"}]
+    exit /b 0
+  )
+  if "%%beadID%%"=="gt-wisp-xyz" (
+    echo [{^"id^":^"gt-wisp-xyz^",^"title^":^"mol-polecat-work^",^"status^":^"open^",^"ephemeral^":true}]
+    exit /b 0
+  )
+  echo []
+  exit /b 0
+)
+if "%%cmd%%"=="close" (
+  echo %%beadID%%>>"%s"
+  exit /b 0
+)
+if "%%cmd%%"=="agent" exit /b 0
+if "%%cmd%%"=="update" exit /b 0
+if "%%cmd%%"=="slot" exit /b 0
+exit /b 0
+`, townRoot, closesPath)
+
+	if runtime.GOOS == "windows" {
+		bdPath := filepath.Join(binDir, "bd.cmd")
+		if err := os.WriteFile(bdPath, []byte(bdScriptWindows), 0644); err != nil {
+			t.Fatalf("write bd stub: %v", err)
+		}
+	} else {
+		bdPath := filepath.Join(binDir, "bd")
+		if err := os.WriteFile(bdPath, []byte(bdScript), 0755); err != nil {
+			t.Fatalf("write bd stub: %v", err)
+		}
+	}
+
+	t.Setenv("PATH", binDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv("GT_ROLE", "polecat")
+	t.Setenv("GT_RIG", "gastown")
+	t.Setenv("GT_POLECAT", "nux")
+	t.Setenv("GT_CREW", "")
+	t.Setenv("TMUX_PANE", "")
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(cwd) })
+	if err := os.Chdir(rigPath); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+
+	// Call the unexported function directly (same package)
+	// updateAgentStateOnDone(cwd, townRoot, exitType, issueID)
+	updateAgentStateOnDone(rigPath, townRoot, ExitCompleted, "")
+
+	// Read the close log to see what got closed
+	closesBytes, err := os.ReadFile(closesPath)
+	if err != nil {
+		// No closes happened at all - that's a failure
+		t.Fatalf("no beads were closed (closes.log doesn't exist)")
+	}
+	closes := string(closesBytes)
+	closeLines := strings.Split(strings.TrimSpace(closes), "\n")
+
+	// Check that attached molecule gt-wisp-xyz was closed
+	foundWisp := false
+	foundBase := false
+	for _, line := range closeLines {
+		if strings.Contains(line, "gt-wisp-xyz") {
+			foundWisp = true
+		}
+		if strings.Contains(line, "gt-abc123") {
+			foundBase = true
+		}
+	}
+
+	if !foundWisp {
+		t.Errorf("attached molecule gt-wisp-xyz was NOT closed\n"+
+			"gt done should close the attached_molecule before closing the hooked bead.\n"+
+			"This leaves orphaned wisps after work completes.\n"+
+			"Beads closed: %v", closeLines)
+	}
+
+	if !foundBase {
+		t.Errorf("hooked bead gt-abc123 was NOT closed\n"+
+			"Beads closed: %v", closeLines)
+	}
+}

internal/cmd/molecule_status.go

@@ -4,13 +4,13 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
-	"os/exec"
 	"path/filepath"
 	"strings"
 
 	"github.com/spf13/cobra"
 	"github.com/steveyegge/gastown/internal/beads"
 	"github.com/steveyegge/gastown/internal/config"
+	"github.com/steveyegge/gastown/internal/git"
 	"github.com/steveyegge/gastown/internal/style"
 	"github.com/steveyegge/gastown/internal/workspace"
 )
@@ -184,11 +184,25 @@ func runMoleculeProgress(cmd *cobra.Command, args []string) error {
 		}
 	}
 
-	// Build set of closed issue IDs for dependency checking
+	// Build set of closed issue IDs and collect open step IDs for dependency checking
 	closedIDs := make(map[string]bool)
+	var openStepIDs []string
 	for _, child := range children {
 		if child.Status == "closed" {
 			closedIDs[child.ID] = true
+		} else if child.Status == "open" {
+			openStepIDs = append(openStepIDs, child.ID)
+		}
+	}
+
+	// Fetch full details for open steps to get dependency info.
+	// bd list doesn't return dependencies, but bd show does.
+	var openStepsMap map[string]*beads.Issue
+	if len(openStepIDs) > 0 {
+		openStepsMap, err = b.ShowMultiple(openStepIDs)
+		if err != nil {
+			// Non-fatal: continue without dependency info (all open steps will be "ready")
+			openStepsMap = make(map[string]*beads.Issue)
 		}
 	}
 
@@ -202,16 +216,30 @@ func runMoleculeProgress(cmd *cobra.Command, args []string) error {
 		case "in_progress":
 			progress.InProgress++
 		case "open":
-			// Check if all dependencies are closed
+			// Get full step info with dependencies
+			step := openStepsMap[child.ID]
+
+			// Check if all dependencies are closed using Dependencies field
+			// (from bd show), not DependsOn (which is empty from bd list).
+			// Only "blocks" type dependencies block progress - ignore "parent-child".
 			allDepsClosed := true
-			for _, depID := range child.DependsOn {
-				if !closedIDs[depID] {
+			hasBlockingDeps := false
+			var deps []beads.IssueDep
+			if step != nil {
+				deps = step.Dependencies
+			}
+			for _, dep := range deps {
+				if dep.DependencyType != "blocks" {
+					continue // Skip parent-child and other non-blocking relationships
+				}
+				hasBlockingDeps = true
+				if !closedIDs[dep.ID] {
 					allDepsClosed = false
 					break
 				}
 			}
 
-			if len(child.DependsOn) == 0 || allDepsClosed {
+			if !hasBlockingDeps || allDepsClosed {
 				progress.ReadySteps = append(progress.ReadySteps, child.ID)
 			} else {
 				progress.BlockedSteps = append(progress.BlockedSteps, child.ID)
@@ -509,11 +537,25 @@ func getMoleculeProgressInfo(b *beads.Beads, moleculeRootID string) (*MoleculePr
 		}
 	}
 
-	// Build set of closed issue IDs for dependency checking
+	// Build set of closed issue IDs and collect open step IDs for dependency checking
 	closedIDs := make(map[string]bool)
+	var openStepIDs []string
 	for _, child := range children {
 		if child.Status == "closed" {
 			closedIDs[child.ID] = true
+		} else if child.Status == "open" {
+			openStepIDs = append(openStepIDs, child.ID)
+		}
+	}
+
+	// Fetch full details for open steps to get dependency info.
+	// bd list doesn't return dependencies, but bd show does.
+	var openStepsMap map[string]*beads.Issue
+	if len(openStepIDs) > 0 {
+		openStepsMap, err = b.ShowMultiple(openStepIDs)
+		if err != nil {
+			// Non-fatal: continue without dependency info (all open steps will be "ready")
+			openStepsMap = make(map[string]*beads.Issue)
 		}
 	}
 
@@ -527,16 +569,30 @@ func getMoleculeProgressInfo(b *beads.Beads, moleculeRootID string) (*MoleculePr
 		case "in_progress":
 			progress.InProgress++
 		case "open":
-			// Check if all dependencies are closed
+			// Get full step info with dependencies
+			step := openStepsMap[child.ID]
+
+			// Check if all dependencies are closed using Dependencies field
+			// (from bd show), not DependsOn (which is empty from bd list).
+			// Only "blocks" type dependencies block progress - ignore "parent-child".
 			allDepsClosed := true
-			for _, depID := range child.DependsOn {
-				if !closedIDs[depID] {
+			hasBlockingDeps := false
+			var deps []beads.IssueDep
+			if step != nil {
+				deps = step.Dependencies
+			}
+			for _, dep := range deps {
+				if dep.DependencyType != "blocks" {
+					continue // Skip parent-child and other non-blocking relationships
+				}
+				hasBlockingDeps = true
+				if !closedIDs[dep.ID] {
 					allDepsClosed = false
 					break
 				}
 			}
 
-			if len(child.DependsOn) == 0 || allDepsClosed {
+			if !hasBlockingDeps || allDepsClosed {
 				progress.ReadySteps = append(progress.ReadySteps, child.ID)
 			} else {
 				progress.BlockedSteps = append(progress.BlockedSteps, child.ID)
@@ -774,10 +830,10 @@ func runMoleculeCurrent(cmd *cobra.Command, args []string) error {
 
 	info.StepsTotal = len(children)
 
-	// Build set of closed issue IDs for dependency checking
+	// Build set of closed issue IDs and collect open step IDs for dependency checking
 	closedIDs := make(map[string]bool)
 	var inProgressSteps []*beads.Issue
-	var readySteps []*beads.Issue
+	var openStepIDs []string
 
 	for _, child := range children {
 		switch child.Status {
@@ -786,23 +842,47 @@ func runMoleculeCurrent(cmd *cobra.Command, args []string) error {
 			closedIDs[child.ID] = true
 		case "in_progress":
 			inProgressSteps = append(inProgressSteps, child)
+		case "open":
+			openStepIDs = append(openStepIDs, child.ID)
+		}
+	}
+
+	// Fetch full details for open steps to get dependency info.
+	// bd list doesn't return dependencies, but bd show does.
+	var openStepsMap map[string]*beads.Issue
+	if len(openStepIDs) > 0 {
+		openStepsMap, _ = b.ShowMultiple(openStepIDs)
+		if openStepsMap == nil {
+			openStepsMap = make(map[string]*beads.Issue)
 		}
 	}
 
 	// Find ready steps (open with all deps closed)
-	for _, child := range children {
-		if child.Status == "open" {
-			allDepsClosed := true
-			for _, depID := range child.DependsOn {
-				if !closedIDs[depID] {
-					allDepsClosed = false
-					break
-				}
+	var readySteps []*beads.Issue
+	for _, stepID := range openStepIDs {
+		step := openStepsMap[stepID]
+		if step == nil {
+			continue
+		}
+
+		// Check dependencies using Dependencies field (from bd show),
+		// not DependsOn (which is empty from bd list).
+		// Only "blocks" type dependencies block progress - ignore "parent-child".
+		allDepsClosed := true
+		hasBlockingDeps := false
+		for _, dep := range step.Dependencies {
+			if dep.DependencyType != "blocks" {
+				continue // Skip parent-child and other non-blocking relationships
 			}
-			if len(child.DependsOn) == 0 || allDepsClosed {
-				readySteps = append(readySteps, child)
+			hasBlockingDeps = true
+			if !closedIDs[dep.ID] {
+				allDepsClosed = false
+				break
 			}
 		}
+		if !hasBlockingDeps || allDepsClosed {
+			readySteps = append(readySteps, step)
+		}
 	}
 
 	// Determine current step and status
@@ -873,13 +953,9 @@ func outputMoleculeCurrent(info MoleculeCurrentInfo) error {
 }
 
 // getGitRootForMolStatus returns the git root for hook file lookup.
+// Uses cached value to avoid repeated git subprocess calls.
 func getGitRootForMolStatus() (string, error) {
-	cmd := exec.Command("git", "rev-parse", "--show-toplevel")
-	out, err := cmd.Output()
-	if err != nil {
-		return "", err
-	}
-	return strings.TrimSpace(string(out)), nil
+	return git.RepoRoot()
 }
 
 // isTownLevelRole returns true if the agent ID is a town-level role.

internal/cmd/molecule_step.go

@@ -53,13 +53,13 @@ func init() {
 
 // StepDoneResult is the result of a step done operation.
 type StepDoneResult struct {
-	StepID       string `json:"step_id"`
-	MoleculeID   string `json:"molecule_id"`
-	StepClosed   bool   `json:"step_closed"`
-	NextStepID   string `json:"next_step_id,omitempty"`
+	StepID        string `json:"step_id"`
+	MoleculeID    string `json:"molecule_id"`
+	StepClosed    bool   `json:"step_closed"`
+	NextStepID    string `json:"next_step_id,omitempty"`
 	NextStepTitle string `json:"next_step_title,omitempty"`
-	Complete     bool   `json:"complete"`
-	Action       string `json:"action"` // "continue", "done", "no_more_ready"
+	Complete      bool   `json:"complete"`
+	Action        string `json:"action"` // "continue", "done", "no_more_ready"
 }
 
 func runMoleculeStepDone(cmd *cobra.Command, args []string) error {
@@ -162,9 +162,10 @@ func runMoleculeStepDone(cmd *cobra.Command, args []string) error {
 // extractMoleculeIDFromStep extracts the molecule ID from a step ID.
 // Step IDs have format: mol-id.N where N is the step number.
 // Examples:
-//   gt-abc.1 -> gt-abc
-//   gt-xyz.3 -> gt-xyz
-//   bd-mol-abc.2 -> bd-mol-abc
+//
+//	gt-abc.1 -> gt-abc
+//	gt-xyz.3 -> gt-xyz
+//	bd-mol-abc.2 -> bd-mol-abc
 func extractMoleculeIDFromStep(stepID string) string {
 	// Find the last dot
 	lastDot := strings.LastIndex(stepID, ".")
@@ -205,11 +206,11 @@ func findNextReadyStep(b *beads.Beads, moleculeID string) (*beads.Issue, bool, e
 		return nil, true, nil // No steps = complete
 	}
 
-	// Build set of closed step IDs and collect open steps
+	// Build set of closed step IDs and collect open step IDs
 	// Note: "open" means not started. "in_progress" means someone's working on it.
 	// We only consider "open" steps as candidates for the next step.
 	closedIDs := make(map[string]bool)
-	var openSteps []*beads.Issue
+	var openStepIDs []string
 	hasNonClosedSteps := false
 
 	for _, child := range children {
@@ -217,7 +218,7 @@ func findNextReadyStep(b *beads.Beads, moleculeID string) (*beads.Issue, bool, e
 		case "closed":
 			closedIDs[child.ID] = true
 		case "open":
-			openSteps = append(openSteps, child)
+			openStepIDs = append(openStepIDs, child.ID)
 			hasNonClosedSteps = true
 		default:
 			// in_progress or other status - not closed, not available
@@ -230,17 +231,42 @@ func findNextReadyStep(b *beads.Beads, moleculeID string) (*beads.Issue, bool, e
 		return nil, true, nil
 	}
 
+	// No open steps to check
+	if len(openStepIDs) == 0 {
+		return nil, false, nil
+	}
+
+	// Fetch full details for open steps to get dependency info.
+	// bd list doesn't return dependencies, but bd show does.
+	openStepsMap, err := b.ShowMultiple(openStepIDs)
+	if err != nil {
+		return nil, false, fmt.Errorf("fetching step details: %w", err)
+	}
+
 	// Find ready steps (open steps with all dependencies closed)
-	for _, step := range openSteps {
+	for _, stepID := range openStepIDs {
+		step, ok := openStepsMap[stepID]
+		if !ok {
+			continue
+		}
+
+		// Check dependencies using the Dependencies field (from bd show),
+		// not DependsOn (which is empty from bd list).
+		// Only "blocks" type dependencies block progress - ignore "parent-child".
 		allDepsClosed := true
-		for _, depID := range step.DependsOn {
-			if !closedIDs[depID] {
+		hasBlockingDeps := false
+		for _, dep := range step.Dependencies {
+			if dep.DependencyType != "blocks" {
+				continue // Skip parent-child and other non-blocking relationships
+			}
+			hasBlockingDeps = true
+			if !closedIDs[dep.ID] {
 				allDepsClosed = false
 				break
 			}
 		}
 
-		if len(step.DependsOn) == 0 || allDepsClosed {
+		if !hasBlockingDeps || allDepsClosed {
 			return step, false, nil
 		}
 	}
@@ -322,6 +348,12 @@ func handleStepContinue(cwd, townRoot, _ string, nextStep *beads.Issue, dryRun b
 
 	t := tmux.NewTmux()
 
+	// Kill all processes in the pane before respawning to prevent process leaks
+	if err := t.KillPaneProcesses(pane); err != nil {
+		// Non-fatal but log the warning
+		style.PrintWarning("could not kill pane processes: %v", err)
+	}
+
 	// Clear history before respawn
 	if err := t.ClearHistory(pane); err != nil {
 		// Non-fatal
@@ -357,14 +389,26 @@ func handleMoleculeComplete(cwd, townRoot, moleculeID string, dryRun bool) error
 	}
 
 	if dryRun {
+		fmt.Printf("[dry-run] Would close child steps of %s\n", moleculeID)
 		fmt.Printf("[dry-run] Would unpin work for %s\n", agentID)
 		fmt.Printf("[dry-run] Would send POLECAT_DONE to witness\n")
 		return nil
 	}
 
-	// Unpin the molecule bead (set status to open, will be closed by gt done or manually)
+	// BUG FIX (gt-zbnr): Close child steps before unpinning/completing.
+	// Deacon patrol molecules have child step wisps that were being orphaned
+	// when the patrol completed. Now we cascade-close all descendants first.
 	workDir, err := findLocalBeadsDir()
 	if err == nil {
+		b := beads.New(workDir)
+		childrenClosed := closeDescendants(b, moleculeID)
+		if childrenClosed > 0 {
+			fmt.Printf("%s Closed %d child step issues\n", style.Bold.Render("✓"), childrenClosed)
+		}
+	}
+
+	// Unpin the molecule bead (set status to open, will be closed by gt done or manually)
+	if workDir, err := findLocalBeadsDir(); err == nil {
 		b := beads.New(workDir)
 		pinnedBeads, err := b.List(beads.ListOptions{
 			Status:   beads.StatusPinned,

internal/cmd/molecule_step_test.go

@@ -79,7 +79,10 @@ func TestExtractMoleculeIDFromStep(t *testing.T) {
 	}
 }
 
-// mockBeadsForStep extends mockBeads with parent filtering for step tests
+// mockBeadsForStep extends mockBeads with parent filtering for step tests.
+// It simulates the real bd behavior where:
+// - List() returns issues with DependsOn empty (bd list doesn't return deps)
+// - Show()/ShowMultiple() returns issues with Dependencies populated (bd show does)
 type mockBeadsForStep struct {
 	issues map[string]*beads.Issue
 }
@@ -101,6 +104,19 @@ func (m *mockBeadsForStep) Show(id string) (*beads.Issue, error) {
 	return nil, beads.ErrNotFound
 }
 
+// ShowMultiple simulates bd show with multiple IDs - returns full issue data including Dependencies
+func (m *mockBeadsForStep) ShowMultiple(ids []string) (map[string]*beads.Issue, error) {
+	result := make(map[string]*beads.Issue)
+	for _, id := range ids {
+		if issue, ok := m.issues[id]; ok {
+			result[id] = issue
+		}
+	}
+	return result, nil
+}
+
+// List simulates bd list behavior - returns issues but with DependsOn EMPTY.
+// This is the key behavior that caused the bug: bd list doesn't return dependency info.
 func (m *mockBeadsForStep) List(opts beads.ListOptions) ([]*beads.Issue, error) {
 	var result []*beads.Issue
 	for _, issue := range m.issues {
@@ -112,7 +128,11 @@ func (m *mockBeadsForStep) List(opts beads.ListOptions) ([]*beads.Issue, error)
 		if opts.Status != "" && opts.Status != "all" && issue.Status != opts.Status {
 			continue
 		}
-		result = append(result, issue)
+		// CRITICAL: Simulate bd list behavior - DependsOn is NOT populated
+		// Create a copy with empty DependsOn to simulate real bd list output
+		issueCopy := *issue
+		issueCopy.DependsOn = nil // bd list doesn't return this
+		result = append(result, &issueCopy)
 	}
 	return result, nil
 }
@@ -128,19 +148,34 @@ func (m *mockBeadsForStep) Close(ids ...string) error {
 	return nil
 }
 
-// makeStepIssue creates a test step issue
+// makeStepIssue creates a test step issue with both DependsOn and Dependencies set.
+// In real usage:
+// - bd list returns issues with DependsOn empty
+// - bd show returns issues with Dependencies populated (with DependencyType)
+// The mock simulates this: List() clears DependsOn, Show() returns the full issue.
 func makeStepIssue(id, title, parent, status string, dependsOn []string) *beads.Issue {
-	return &beads.Issue{
+	issue := &beads.Issue{
 		ID:        id,
 		Title:     title,
 		Type:      "task",
 		Status:    status,
 		Priority:  2,
 		Parent:    parent,
-		DependsOn: dependsOn,
+		DependsOn: dependsOn, // This gets cleared by mock List() to simulate bd list
 		CreatedAt: "2025-01-01T12:00:00Z",
 		UpdatedAt: "2025-01-01T12:00:00Z",
 	}
+	// Also set Dependencies (what bd show returns) for proper testing.
+	// Use "blocks" dependency type since that's what formula instantiation creates
+	// for inter-step dependencies (vs "parent-child" for parent relationships).
+	for _, depID := range dependsOn {
+		issue.Dependencies = append(issue.Dependencies, beads.IssueDep{
+			ID:             depID,
+			Title:          "Dependency " + depID,
+			DependencyType: "blocks", // Only "blocks" deps should block progress
+		})
+	}
+	return issue
 }
 
 func TestFindNextReadyStep(t *testing.T) {
@@ -232,24 +267,22 @@ func TestFindNextReadyStep(t *testing.T) {
 			m := newMockBeadsForStep()
 			tt.setupFunc(m)
 
-			// Create a real Beads instance but we'll use our mock
-			// For now, we test the logic by calling the actual function with mock data
-			// This requires refactoring findNextReadyStep to accept an interface
-			// For now, we'll test the logic inline
+			// Test the FIXED algorithm that uses ShowMultiple for dependency info
+			// (simulating the real findNextReadyStep behavior after the fix)
 
-			// Get children from mock
+			// Get children from mock (DependsOn will be empty - simulating bd list)
 			children, _ := m.List(beads.ListOptions{Parent: tt.moleculeID, Status: "all"})
 
-			// Build closed IDs set - only "open" steps are candidates
+			// Build closed IDs set and collect open step IDs
 			closedIDs := make(map[string]bool)
-			var openSteps []*beads.Issue
+			var openStepIDs []string
 			hasNonClosedSteps := false
 			for _, child := range children {
 				switch child.Status {
 				case "closed":
 					closedIDs[child.ID] = true
 				case "open":
-					openSteps = append(openSteps, child)
+					openStepIDs = append(openStepIDs, child.ID)
 					hasNonClosedSteps = true
 				default:
 					// in_progress or other - not closed, not available
@@ -268,17 +301,32 @@ func TestFindNextReadyStep(t *testing.T) {
 				return
 			}
 
-			// Find ready step
+			// Fetch full details for open steps (Dependencies will be populated)
+			openStepsMap, _ := m.ShowMultiple(openStepIDs)
+
+			// Find ready step using Dependencies (not DependsOn!)
+			// Only "blocks" type dependencies block progress - ignore "parent-child".
 			var readyStep *beads.Issue
-			for _, step := range openSteps {
+			for _, stepID := range openStepIDs {
+				step := openStepsMap[stepID]
+				if step == nil {
+					continue
+				}
+
+				// Use Dependencies (from bd show), NOT DependsOn (empty from bd list)
 				allDepsClosed := true
-				for _, depID := range step.DependsOn {
-					if !closedIDs[depID] {
+				hasBlockingDeps := false
+				for _, dep := range step.Dependencies {
+					if dep.DependencyType != "blocks" {
+						continue // Skip parent-child and other non-blocking relationships
+					}
+					hasBlockingDeps = true
+					if !closedIDs[dep.ID] {
 						allDepsClosed = false
 						break
 					}
 				}
-				if len(step.DependsOn) == 0 || allDepsClosed {
+				if !hasBlockingDeps || allDepsClosed {
 					readyStep = step
 					break
 				}
@@ -372,18 +420,18 @@ func TestStepDoneScenarios(t *testing.T) {
 				t.Fatalf("failed to close step: %v", err)
 			}
 
-			// Now find next ready step
+			// Now find next ready step using the FIXED algorithm
 			children, _ := m.List(beads.ListOptions{Parent: moleculeID, Status: "all"})
 
 			closedIDs := make(map[string]bool)
-			var openSteps []*beads.Issue
+			var openStepIDs []string
 			hasNonClosedSteps := false
 			for _, child := range children {
 				switch child.Status {
 				case "closed":
 					closedIDs[child.ID] = true
 				case "open":
-					openSteps = append(openSteps, child)
+					openStepIDs = append(openStepIDs, child.ID)
 					hasNonClosedSteps = true
 				default:
 					// in_progress or other - not closed, not available
@@ -399,17 +447,32 @@ func TestStepDoneScenarios(t *testing.T) {
 			if allComplete {
 				action = "done"
 			} else {
-				// Find ready step
+				// Fetch full details for open steps (Dependencies will be populated)
+				openStepsMap, _ := m.ShowMultiple(openStepIDs)
+
+				// Find ready step using Dependencies (not DependsOn!)
+				// Only "blocks" type dependencies block progress - ignore "parent-child".
 				var readyStep *beads.Issue
-				for _, step := range openSteps {
+				for _, stepID := range openStepIDs {
+					step := openStepsMap[stepID]
+					if step == nil {
+						continue
+					}
+
+					// Use Dependencies (from bd show), NOT DependsOn (empty from bd list)
 					allDepsClosed := true
-					for _, depID := range step.DependsOn {
-						if !closedIDs[depID] {
+					hasBlockingDeps := false
+					for _, dep := range step.Dependencies {
+						if dep.DependencyType != "blocks" {
+							continue // Skip parent-child and other non-blocking relationships
+						}
+						hasBlockingDeps = true
+						if !closedIDs[dep.ID] {
 							allDepsClosed = false
 							break
 						}
 					}
-					if len(step.DependsOn) == 0 || allDepsClosed {
+					if !hasBlockingDeps || allDepsClosed {
 						readyStep = step
 						break
 					}
@@ -433,3 +496,224 @@ func TestStepDoneScenarios(t *testing.T) {
 		})
 	}
 }
+
+// TestFindNextReadyStepWithBdListBehavior tests the fix for the bug where
+// bd list doesn't return dependency info (DependsOn is always empty), but
+// bd show returns Dependencies. The old code checked DependsOn (always empty),
+// so all open steps looked "ready" even when blocked.
+//
+// This test simulates real bd behavior and verifies the fix works correctly.
+func TestFindNextReadyStepWithBdListBehavior(t *testing.T) {
+	tests := []struct {
+		name         string
+		moleculeID   string
+		setupFunc    func(*mockBeadsForStep)
+		wantStepID   string // Expected ready step ID, or "" if none ready
+		wantComplete bool
+		wantBlocked  bool // True if all remaining steps are blocked (none ready)
+	}{
+		{
+			name:       "blocked step should NOT be ready - dependency not closed",
+			moleculeID: "gt-mol",
+			setupFunc: func(m *mockBeadsForStep) {
+				// Step 1 is open (first step, no deps)
+				m.addIssue(makeStepIssue("gt-mol.1", "Step 1", "gt-mol", "open", nil))
+				// Step 2 depends on Step 1, which is NOT closed
+				// BUG: Old code would mark Step 2 as ready because DependsOn is empty from bd list
+				// FIX: New code uses Dependencies from bd show
+				m.addIssue(makeStepIssue("gt-mol.2", "Step 2", "gt-mol", "open", []string{"gt-mol.1"}))
+			},
+			wantStepID:   "gt-mol.1", // Only step 1 should be ready
+			wantComplete: false,
+		},
+		{
+			name:       "step becomes ready when dependency closes",
+			moleculeID: "gt-mol",
+			setupFunc: func(m *mockBeadsForStep) {
+				m.addIssue(makeStepIssue("gt-mol.1", "Step 1", "gt-mol", "closed", nil))
+				m.addIssue(makeStepIssue("gt-mol.2", "Step 2", "gt-mol", "open", []string{"gt-mol.1"}))
+			},
+			wantStepID:   "gt-mol.2", // Step 2 is ready now that step 1 is closed
+			wantComplete: false,
+		},
+		{
+			name:       "multiple blocked steps - none ready",
+			moleculeID: "gt-mol",
+			setupFunc: func(m *mockBeadsForStep) {
+				// Step 1 is in_progress (not closed)
+				m.addIssue(makeStepIssue("gt-mol.1", "Step 1", "gt-mol", "in_progress", nil))
+				// Steps 2 and 3 both depend on step 1
+				m.addIssue(makeStepIssue("gt-mol.2", "Step 2", "gt-mol", "open", []string{"gt-mol.1"}))
+				m.addIssue(makeStepIssue("gt-mol.3", "Step 3", "gt-mol", "open", []string{"gt-mol.1"}))
+			},
+			wantBlocked:  true, // No open steps are ready (all blocked by step 1)
+			wantComplete: false,
+		},
+		{
+			name:       "diamond dependency - synthesis blocked until both complete",
+			moleculeID: "gt-mol",
+			setupFunc: func(m *mockBeadsForStep) {
+				m.addIssue(makeStepIssue("gt-mol.1", "Step A", "gt-mol", "closed", nil))
+				m.addIssue(makeStepIssue("gt-mol.2", "Step B", "gt-mol", "open", nil))
+				// Synthesis depends on BOTH A and B
+				m.addIssue(makeStepIssue("gt-mol.3", "Synthesis", "gt-mol", "open", []string{"gt-mol.1", "gt-mol.2"}))
+			},
+			wantStepID:   "gt-mol.2", // B is ready (no deps), synthesis is blocked
+			wantComplete: false,
+		},
+		{
+			name:       "diamond dependency - synthesis ready when both complete",
+			moleculeID: "gt-mol",
+			setupFunc: func(m *mockBeadsForStep) {
+				m.addIssue(makeStepIssue("gt-mol.1", "Step A", "gt-mol", "closed", nil))
+				m.addIssue(makeStepIssue("gt-mol.2", "Step B", "gt-mol", "closed", nil))
+				// Synthesis depends on BOTH A and B, both are now closed
+				m.addIssue(makeStepIssue("gt-mol.3", "Synthesis", "gt-mol", "open", []string{"gt-mol.1", "gt-mol.2"}))
+			},
+			wantStepID:   "gt-mol.3", // Synthesis is now ready
+			wantComplete: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			m := newMockBeadsForStep()
+			tt.setupFunc(m)
+
+			// Simulate the FIXED algorithm that uses ShowMultiple for dependency info
+			// Step 1: List children (DependsOn will be empty - simulating bd list)
+			children, _ := m.List(beads.ListOptions{Parent: tt.moleculeID, Status: "all"})
+
+			// Build closed IDs and collect open step IDs
+			closedIDs := make(map[string]bool)
+			var openStepIDs []string
+			hasNonClosedSteps := false
+
+			for _, child := range children {
+				switch child.Status {
+				case "closed":
+					closedIDs[child.ID] = true
+				case "open":
+					openStepIDs = append(openStepIDs, child.ID)
+					hasNonClosedSteps = true
+				default:
+					hasNonClosedSteps = true
+				}
+			}
+
+			allComplete := !hasNonClosedSteps
+			if allComplete != tt.wantComplete {
+				t.Errorf("allComplete = %v, want %v", allComplete, tt.wantComplete)
+			}
+
+			if tt.wantComplete {
+				return
+			}
+
+			// Step 2: Fetch full details for open steps (Dependencies will be populated)
+			openStepsMap, _ := m.ShowMultiple(openStepIDs)
+
+			// Step 3: Find ready step using Dependencies (not DependsOn!)
+			// Only "blocks" type dependencies block progress - ignore "parent-child".
+			var readyStep *beads.Issue
+			for _, stepID := range openStepIDs {
+				step := openStepsMap[stepID]
+				if step == nil {
+					continue
+				}
+
+				// Use Dependencies (from bd show), NOT DependsOn (empty from bd list)
+				allDepsClosed := true
+				hasBlockingDeps := false
+				for _, dep := range step.Dependencies {
+					if dep.DependencyType != "blocks" {
+						continue // Skip parent-child and other non-blocking relationships
+					}
+					hasBlockingDeps = true
+					if !closedIDs[dep.ID] {
+						allDepsClosed = false
+						break
+					}
+				}
+
+				if !hasBlockingDeps || allDepsClosed {
+					readyStep = step
+					break
+				}
+			}
+
+			// Verify results
+			if tt.wantBlocked {
+				if readyStep != nil {
+					t.Errorf("expected no ready steps (all blocked), got %s", readyStep.ID)
+				}
+				return
+			}
+
+			if tt.wantStepID == "" {
+				if readyStep != nil {
+					t.Errorf("expected no ready step, got %s", readyStep.ID)
+				}
+				return
+			}
+
+			if readyStep == nil {
+				t.Errorf("expected ready step %s, got nil", tt.wantStepID)
+				return
+			}
+
+			if readyStep.ID != tt.wantStepID {
+				t.Errorf("ready step = %s, want %s", readyStep.ID, tt.wantStepID)
+			}
+		})
+	}
+}
+
+// TestOldBuggyBehavior demonstrates what the old buggy code would have done.
+// With the old code, since DependsOn was always empty from bd list,
+// ALL open steps would appear "ready" regardless of actual dependencies.
+// This test verifies the bug exists when using the old approach.
+func TestOldBuggyBehavior(t *testing.T) {
+	m := newMockBeadsForStep()
+
+	// Setup: Step 2 depends on Step 1, but Step 1 is NOT closed
+	m.addIssue(makeStepIssue("gt-mol.1", "Step 1", "gt-mol", "open", nil))
+	m.addIssue(makeStepIssue("gt-mol.2", "Step 2", "gt-mol", "open", []string{"gt-mol.1"}))
+
+	// Get children via List (simulates bd list - DependsOn is empty)
+	children, _ := m.List(beads.ListOptions{Parent: "gt-mol", Status: "all"})
+
+	// OLD BUGGY CODE: Check DependsOn (which is empty from bd list)
+	closedIDs := make(map[string]bool)
+	var openSteps []*beads.Issue
+	for _, child := range children {
+		if child.Status == "closed" {
+			closedIDs[child.ID] = true
+		} else if child.Status == "open" {
+			openSteps = append(openSteps, child)
+		}
+	}
+
+	// Count how many steps the OLD buggy code thinks are "ready"
+	readyCount := 0
+	for _, step := range openSteps {
+		allDepsClosed := true
+		for _, depID := range step.DependsOn { // BUG: This is always empty!
+			if !closedIDs[depID] {
+				allDepsClosed = false
+				break
+			}
+		}
+		if len(step.DependsOn) == 0 || allDepsClosed { // Always true since DependsOn is empty
+			readyCount++
+		}
+	}
+
+	// The bug: OLD code thinks BOTH steps are ready (2 ready)
+	// Correct behavior: Only Step 1 should be ready (1 ready)
+	if readyCount != 2 {
+		t.Errorf("Expected old buggy code to mark 2 steps as ready, got %d", readyCount)
+	}
+
+	t.Log("Old buggy behavior confirmed: both steps marked ready when only step 1 should be")
+}

internal/cmd/mq_list.go

@@ -48,9 +48,9 @@ func runMQList(cmd *cobra.Command, args []string) error {
 		if err != nil {
 			return fmt.Errorf("querying ready MRs: %w", err)
 		}
-		// Filter to only merge-request type
+		// Filter to only merge-request label (issue_type field is deprecated)
 		for _, issue := range allReady {
-			if issue.Type == "merge-request" {
+			if beads.HasLabel(issue, "gt:merge-request") {
 				issues = append(issues, issue)
 			}
 		}

internal/cmd/mq_test.go

@@ -740,3 +740,64 @@ func TestPolecatCleanupTimeoutConstant(t *testing.T) {
 		t.Errorf("expectedMaxCleanupWait = %v, want 5m", expectedMaxCleanupWait)
 	}
 }
+
+// TestMRFilteringByLabel verifies that MRs are identified by their gt:merge-request
+// label rather than the deprecated issue_type field. This is the fix for #816 where
+// MRs created by `gt done` have issue_type='task' but correct gt:merge-request label.
+func TestMRFilteringByLabel(t *testing.T) {
+	tests := []struct {
+		name     string
+		issue    *beads.Issue
+		wantIsMR bool
+	}{
+		{
+			name: "MR with correct label and wrong type (bug #816 scenario)",
+			issue: &beads.Issue{
+				ID:     "mr-1",
+				Title:  "Merge: test-branch",
+				Type:   "task", // Wrong type (default from bd create)
+				Labels: []string{"gt:merge-request"}, // Correct label
+			},
+			wantIsMR: true,
+		},
+		{
+			name: "MR with correct label and correct type",
+			issue: &beads.Issue{
+				ID:     "mr-2",
+				Title:  "Merge: another-branch",
+				Type:   "merge-request",
+				Labels: []string{"gt:merge-request"},
+			},
+			wantIsMR: true,
+		},
+		{
+			name: "Task without MR label",
+			issue: &beads.Issue{
+				ID:     "task-1",
+				Title:  "Regular task",
+				Type:   "task",
+				Labels: []string{"other-label"},
+			},
+			wantIsMR: false,
+		},
+		{
+			name: "Issue with no labels",
+			issue: &beads.Issue{
+				ID:    "issue-1",
+				Title: "No labels",
+				Type:  "task",
+			},
+			wantIsMR: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := beads.HasLabel(tt.issue, "gt:merge-request")
+			if got != tt.wantIsMR {
+				t.Errorf("HasLabel(%q, \"gt:merge-request\") = %v, want %v",
+					tt.issue.ID, got, tt.wantIsMR)
+			}
+		})
+	}
+}

internal/cmd/namepool.go

@@ -83,8 +83,25 @@ func runNamepool(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("not in a rig directory")
 	}
 
-	// Load pool
-	pool := polecat.NewNamePool(rigPath, rigName)
+	// Load settings for namepool config
+	settingsPath := filepath.Join(rigPath, "settings", "config.json")
+	var pool *polecat.NamePool
+
+	settings, err := config.LoadRigSettings(settingsPath)
+	if err == nil && settings.Namepool != nil {
+		// Use configured namepool settings
+		pool = polecat.NewNamePoolWithConfig(
+			rigPath,
+			rigName,
+			settings.Namepool.Style,
+			settings.Namepool.Names,
+			settings.Namepool.MaxBeforeNumbering,
+		)
+	} else {
+		// Use defaults
+		pool = polecat.NewNamePool(rigPath, rigName)
+	}
+
 	if err := pool.Load(); err != nil {
 		// Pool doesn't exist yet, show defaults
 		fmt.Printf("Rig: %s\n", rigName)
@@ -104,9 +121,8 @@ func runNamepool(cmd *cobra.Command, args []string) error {
 		fmt.Printf("In use: %s\n", strings.Join(activeNames, ", "))
 	}
 
-	// Check if configured
-	settingsPath := filepath.Join(rigPath, "settings", "config.json")
-	if settings, err := config.LoadRigSettings(settingsPath); err == nil && settings.Namepool != nil {
+	// Check if configured (already loaded above)
+	if settings.Namepool != nil {
 		fmt.Printf("(configured in settings/config.json)\n")
 	}
 

internal/cmd/orphans.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/spf13/cobra"
 	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/util"
 	"github.com/steveyegge/gastown/internal/workspace"
 )
 
@@ -48,7 +49,8 @@ var (
 	orphansKillForce  bool
 
 	// Process orphan flags
-	orphansProcsForce bool
+	orphansProcsForce      bool
+	orphansProcsAggressive bool
 )
 
 // Commit orphan kill command
@@ -89,10 +91,16 @@ var orphansProcsCmd = &cobra.Command{
 These are processes that survived session termination and are now
 parented to init/launchd. They consume resources and should be killed.
 
+Use --aggressive to detect ALL orphaned Claude processes by cross-referencing
+against active tmux sessions. Any Claude process NOT in a gt-* or hq-* session
+is considered an orphan. This catches processes that have been reparented to
+something other than init (PPID != 1).
+
 Examples:
-  gt orphans procs        # List orphaned Claude processes
-  gt orphans procs list   # Same as above
-  gt orphans procs kill   # Kill orphaned processes`,
+  gt orphans procs              # List orphaned Claude processes (PPID=1 only)
+  gt orphans procs list         # Same as above
+  gt orphans procs --aggressive # List ALL orphaned processes (tmux verification)
+  gt orphans procs kill         # Kill orphaned processes`,
 	RunE: runOrphansListProcesses, // Default to list
 }
 
@@ -104,12 +112,17 @@ var orphansProcsListCmd = &cobra.Command{
 These are processes that survived session termination and are now
 parented to init/launchd. They consume resources and should be killed.
 
+Use --aggressive to detect ALL orphaned Claude processes by cross-referencing
+against active tmux sessions. Any Claude process NOT in a gt-* or hq-* session
+is considered an orphan.
+
 Excludes:
 - tmux server processes
 - Claude.app desktop application processes
 
 Examples:
-  gt orphans procs list      # Show all orphan Claude processes`,
+  gt orphans procs list             # Show orphans with PPID=1
+  gt orphans procs list --aggressive # Show ALL orphans (tmux verification)`,
 	RunE: runOrphansListProcesses,
 }
 
@@ -120,10 +133,12 @@ var orphansProcsKillCmd = &cobra.Command{
 
 Without flags, prompts for confirmation before killing.
 Use -f/--force to kill without confirmation.
+Use --aggressive to kill ALL orphaned processes (not just PPID=1).
 
 Examples:
-  gt orphans procs kill      # Kill with confirmation
-  gt orphans procs kill -f   # Force kill without confirmation`,
+  gt orphans procs kill             # Kill with confirmation
+  gt orphans procs kill -f          # Force kill without confirmation
+  gt orphans procs kill --aggressive # Kill ALL orphans (tmux verification)`,
 	RunE: runOrphansKillProcesses,
 }
 
@@ -140,6 +155,9 @@ func init() {
 	// Process orphan kill command flags
 	orphansProcsKillCmd.Flags().BoolVarP(&orphansProcsForce, "force", "f", false, "Kill without confirmation")
 
+	// Aggressive flag for all procs commands (persistent so it applies to subcommands)
+	orphansProcsCmd.PersistentFlags().BoolVar(&orphansProcsAggressive, "aggressive", false, "Use tmux session verification to find ALL orphans (not just PPID=1)")
+
 	// Wire up subcommands
 	orphansProcsCmd.AddCommand(orphansProcsListCmd)
 	orphansProcsCmd.AddCommand(orphansProcsKillCmd)
@@ -449,6 +467,12 @@ func runOrphansKill(cmd *cobra.Command, args []string) error {
 	// Kill orphaned processes
 	if len(procOrphans) > 0 {
 		fmt.Printf("\nKilling orphaned processes...\n")
+		// Use SIGKILL with --force for immediate termination, SIGTERM otherwise
+		signal := syscall.SIGTERM
+		if orphansKillForce {
+			signal = syscall.SIGKILL
+		}
+
 		var killed, failed int
 		for _, o := range procOrphans {
 			proc, err := os.FindProcess(o.PID)
@@ -458,7 +482,7 @@ func runOrphansKill(cmd *cobra.Command, args []string) error {
 				continue
 			}
 
-			if err := proc.Signal(syscall.SIGTERM); err != nil {
+			if err := proc.Signal(signal); err != nil {
 				if err == os.ErrProcessDone {
 					fmt.Printf("  %s PID %d: already terminated\n", style.Dim.Render("○"), o.PID)
 					continue
@@ -579,17 +603,22 @@ func isExcludedProcess(args string) bool {
 
 // runOrphansListProcesses lists orphaned Claude processes
 func runOrphansListProcesses(cmd *cobra.Command, args []string) error {
+	if orphansProcsAggressive {
+		return runOrphansListProcessesAggressive()
+	}
+
 	orphans, err := findOrphanProcesses()
 	if err != nil {
 		return fmt.Errorf("finding orphan processes: %w", err)
 	}
 
 	if len(orphans) == 0 {
-		fmt.Printf("%s No orphaned Claude processes found\n", style.Bold.Render("✓"))
+		fmt.Printf("%s No orphaned Claude processes found (PPID=1)\n", style.Bold.Render("✓"))
+		fmt.Printf("%s Use --aggressive to find orphans via tmux session verification\n", style.Dim.Render("Hint:"))
 		return nil
 	}
 
-	fmt.Printf("%s Found %d orphaned Claude process(es):\n\n", style.Warning.Render("⚠"), len(orphans))
+	fmt.Printf("%s Found %d orphaned Claude process(es) with PPID=1:\n\n", style.Warning.Render("⚠"), len(orphans))
 
 	for _, o := range orphans {
 		// Truncate args for display
@@ -601,24 +630,72 @@ func runOrphansListProcesses(cmd *cobra.Command, args []string) error {
 	}
 
 	fmt.Printf("\n%s\n", style.Dim.Render("Use 'gt orphans procs kill' to terminate these processes"))
+	fmt.Printf("%s\n", style.Dim.Render("Use --aggressive to find more orphans via tmux session verification"))
 
 	return nil
 }
 
+// runOrphansListProcessesAggressive lists orphans using tmux session verification.
+// This finds ALL Claude processes not in any gt-* or hq-* tmux session.
+func runOrphansListProcessesAggressive() error {
+	zombies, err := util.FindZombieClaudeProcesses()
+	if err != nil {
+		return fmt.Errorf("finding zombie processes: %w", err)
+	}
+
+	if len(zombies) == 0 {
+		fmt.Printf("%s No orphaned Claude processes found (aggressive mode)\n", style.Bold.Render("✓"))
+		return nil
+	}
+
+	fmt.Printf("%s Found %d orphaned Claude process(es) not in any tmux session:\n\n", style.Warning.Render("⚠"), len(zombies))
+
+	for _, z := range zombies {
+		ageStr := formatProcessAge(z.Age)
+		fmt.Printf("  %s %s (age: %s, tty: %s)\n",
+			style.Bold.Render(fmt.Sprintf("PID %d", z.PID)),
+			z.Cmd,
+			style.Dim.Render(ageStr),
+			z.TTY)
+	}
+
+	fmt.Printf("\n%s\n", style.Dim.Render("Use 'gt orphans procs kill --aggressive' to terminate these processes"))
+
+	return nil
+}
+
+// formatProcessAge formats seconds into a human-readable age string
+func formatProcessAge(seconds int) string {
+	if seconds < 60 {
+		return fmt.Sprintf("%ds", seconds)
+	}
+	if seconds < 3600 {
+		return fmt.Sprintf("%dm%ds", seconds/60, seconds%60)
+	}
+	hours := seconds / 3600
+	mins := (seconds % 3600) / 60
+	return fmt.Sprintf("%dh%dm", hours, mins)
+}
+
 // runOrphansKillProcesses kills orphaned Claude processes
 func runOrphansKillProcesses(cmd *cobra.Command, args []string) error {
+	if orphansProcsAggressive {
+		return runOrphansKillProcessesAggressive()
+	}
+
 	orphans, err := findOrphanProcesses()
 	if err != nil {
 		return fmt.Errorf("finding orphan processes: %w", err)
 	}
 
 	if len(orphans) == 0 {
-		fmt.Printf("%s No orphaned Claude processes found\n", style.Bold.Render("✓"))
+		fmt.Printf("%s No orphaned Claude processes found (PPID=1)\n", style.Bold.Render("✓"))
+		fmt.Printf("%s Use --aggressive to find orphans via tmux session verification\n", style.Dim.Render("Hint:"))
 		return nil
 	}
 
 	// Show what we're about to kill
-	fmt.Printf("%s Found %d orphaned Claude process(es):\n\n", style.Warning.Render("⚠"), len(orphans))
+	fmt.Printf("%s Found %d orphaned Claude process(es) with PPID=1:\n\n", style.Warning.Render("⚠"), len(orphans))
 	for _, o := range orphans {
 		displayArgs := o.Args
 		if len(displayArgs) > 80 {
@@ -641,6 +718,12 @@ func runOrphansKillProcesses(cmd *cobra.Command, args []string) error {
 	}
 
 	// Kill the processes
+	// Use SIGKILL with --force for immediate termination, SIGTERM otherwise
+	signal := syscall.SIGTERM
+	if orphansProcsForce {
+		signal = syscall.SIGKILL
+	}
+
 	var killed, failed int
 	for _, o := range orphans {
 		proc, err := os.FindProcess(o.PID)
@@ -650,8 +733,7 @@ func runOrphansKillProcesses(cmd *cobra.Command, args []string) error {
 			continue
 		}
 
-		// Send SIGTERM first for graceful shutdown
-		if err := proc.Signal(syscall.SIGTERM); err != nil {
+		if err := proc.Signal(signal); err != nil {
 			// Process may have already exited
 			if err == os.ErrProcessDone {
 				fmt.Printf("  %s PID %d: already terminated\n", style.Dim.Render("○"), o.PID)
@@ -674,3 +756,80 @@ func runOrphansKillProcesses(cmd *cobra.Command, args []string) error {
 
 	return nil
 }
+
+// runOrphansKillProcessesAggressive kills orphans using tmux session verification.
+// This kills ALL Claude processes not in any gt-* or hq-* tmux session.
+func runOrphansKillProcessesAggressive() error {
+	zombies, err := util.FindZombieClaudeProcesses()
+	if err != nil {
+		return fmt.Errorf("finding zombie processes: %w", err)
+	}
+
+	if len(zombies) == 0 {
+		fmt.Printf("%s No orphaned Claude processes found (aggressive mode)\n", style.Bold.Render("✓"))
+		return nil
+	}
+
+	// Show what we're about to kill
+	fmt.Printf("%s Found %d orphaned Claude process(es) not in any tmux session:\n\n", style.Warning.Render("⚠"), len(zombies))
+	for _, z := range zombies {
+		ageStr := formatProcessAge(z.Age)
+		fmt.Printf("  %s %s (age: %s, tty: %s)\n",
+			style.Bold.Render(fmt.Sprintf("PID %d", z.PID)),
+			z.Cmd,
+			style.Dim.Render(ageStr),
+			z.TTY)
+	}
+	fmt.Println()
+
+	// Confirm unless --force
+	if !orphansProcsForce {
+		fmt.Printf("Kill these %d process(es)? [y/N] ", len(zombies))
+		var response string
+		_, _ = fmt.Scanln(&response)
+		response = strings.ToLower(strings.TrimSpace(response))
+		if response != "y" && response != "yes" {
+			fmt.Println("Aborted")
+			return nil
+		}
+	}
+
+	// Kill the processes
+	// Use SIGKILL with --force for immediate termination, SIGTERM otherwise
+	signal := syscall.SIGTERM
+	if orphansProcsForce {
+		signal = syscall.SIGKILL
+	}
+
+	var killed, failed int
+	for _, z := range zombies {
+		proc, err := os.FindProcess(z.PID)
+		if err != nil {
+			fmt.Printf("  %s PID %d: %v\n", style.Error.Render("✗"), z.PID, err)
+			failed++
+			continue
+		}
+
+		if err := proc.Signal(signal); err != nil {
+			// Process may have already exited
+			if err == os.ErrProcessDone {
+				fmt.Printf("  %s PID %d: already terminated\n", style.Dim.Render("○"), z.PID)
+				continue
+			}
+			fmt.Printf("  %s PID %d: %v\n", style.Error.Render("✗"), z.PID, err)
+			failed++
+			continue
+		}
+
+		fmt.Printf("  %s PID %d killed\n", style.Bold.Render("✓"), z.PID)
+		killed++
+	}
+
+	fmt.Printf("\n%s %d killed", style.Bold.Render("Summary:"), killed)
+	if failed > 0 {
+		fmt.Printf(", %d failed", failed)
+	}
+	fmt.Println()
+
+	return nil
+}

internal/cmd/patrol_helpers.go

@@ -103,7 +103,7 @@ func findActivePatrol(cfg PatrolConfig) (patrolID, patrolLine string, found bool
 // Returns the patrol ID or an error.
 func autoSpawnPatrol(cfg PatrolConfig) (string, error) {
 	// Find the proto ID for the patrol molecule
-	cmdCatalog := exec.Command("bd", "--no-daemon", "mol", "catalog")
+	cmdCatalog := exec.Command("gt", "formula", "list")
 	cmdCatalog.Dir = cfg.BeadsDir
 	var stdoutCatalog, stderrCatalog bytes.Buffer
 	cmdCatalog.Stdout = &stdoutCatalog
@@ -112,20 +112,20 @@ func autoSpawnPatrol(cfg PatrolConfig) (string, error) {
 	if err := cmdCatalog.Run(); err != nil {
 		errMsg := strings.TrimSpace(stderrCatalog.String())
 		if errMsg != "" {
-			return "", fmt.Errorf("failed to list molecule catalog: %s", errMsg)
+			return "", fmt.Errorf("failed to list formulas: %s", errMsg)
 		}
-		return "", fmt.Errorf("failed to list molecule catalog: %w", err)
+		return "", fmt.Errorf("failed to list formulas: %w", err)
 	}
 
-	// Find patrol molecule in catalog
+	// Find patrol molecule in formula list
+	// Format: "formula-name         description"
 	var protoID string
 	catalogLines := strings.Split(stdoutCatalog.String(), "\n")
 	for _, line := range catalogLines {
 		if strings.Contains(line, cfg.PatrolMolName) {
 			parts := strings.Fields(line)
 			if len(parts) > 0 {
-				// Strip trailing colon from ID (catalog format: "gt-xxx: title")
-				protoID = strings.TrimSuffix(parts[0], ":")
+				protoID = parts[0]
 				break
 			}
 		}
@@ -196,7 +196,7 @@ func outputPatrolContext(cfg PatrolConfig) {
 				fmt.Printf("⚠ %s\n", err.Error())
 			} else {
 				fmt.Println(style.Dim.Render(err.Error()))
-				fmt.Println(style.Dim.Render(fmt.Sprintf("Run `bd mol catalog` to troubleshoot.")))
+				fmt.Println(style.Dim.Render(fmt.Sprintf("Run `gt formula list` to troubleshoot.")))
 				return
 			}
 		} else {

internal/cmd/plugin.go

@@ -433,19 +433,10 @@ func runPluginRun(cmd *cobra.Command, args []string) error {
 	fmt.Printf("%s\n", style.Bold.Render("Instructions:"))
 	fmt.Println(p.Instructions)
 
-	// Record the run
-	recorder := plugin.NewRecorder(townRoot)
-	beadID, err := recorder.RecordRun(plugin.PluginRunRecord{
-		PluginName: p.Name,
-		RigName:    p.RigName,
-		Result:     plugin.ResultSuccess, // Manual runs are marked success
-		Body:       "Manual run via gt plugin run",
-	})
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "Warning: failed to record run: %v\n", err)
-	} else {
-		fmt.Printf("\n%s Recorded run: %s\n", style.Dim.Render("●"), beadID)
-	}
+	// NOTE: We intentionally do NOT record a run here. This command only prints
+	// instructions for an agent/user to execute - it doesn't actually run the plugin.
+	// Recording "success" here would poison the cooldown gate, preventing real executions.
+	// The actual execution (by whatever follows these instructions) should record the result.
 
 	return nil
 }

internal/cmd/polecat.go

@@ -18,6 +18,7 @@ import (
 	"github.com/steveyegge/gastown/internal/runtime"
 	"github.com/steveyegge/gastown/internal/style"
 	"github.com/steveyegge/gastown/internal/tmux"
+	"github.com/steveyegge/gastown/internal/util"
 )
 
 // Polecat command flags
@@ -1268,6 +1269,12 @@ func runPolecatNuke(cmd *cobra.Command, args []string) error {
 		fmt.Printf("\n%s Nuked %d polecat(s).\n", style.SuccessPrefix, nuked)
 	}
 
+	// Final cleanup: Kill any orphaned Claude processes that escaped the session termination.
+	// This catches processes that called setsid() or were reparented during session shutdown.
+	if !polecatNukeDryRun {
+		cleanupOrphanedProcesses()
+	}
+
 	if len(nukeErrors) > 0 {
 		return fmt.Errorf("%d nuke(s) failed", len(nukeErrors))
 	}
@@ -1275,6 +1282,39 @@ func runPolecatNuke(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// cleanupOrphanedProcesses kills Claude processes that survived session termination.
+// Uses aggressive zombie detection via tmux session verification.
+func cleanupOrphanedProcesses() {
+	results, err := util.CleanupZombieClaudeProcesses()
+	if err != nil {
+		// Non-fatal: log and continue
+		fmt.Printf("  %s orphan cleanup check failed: %v\n", style.Dim.Render("○"), err)
+		return
+	}
+
+	if len(results) == 0 {
+		return
+	}
+
+	// Report what was cleaned up
+	var killed, escalated int
+	for _, r := range results {
+		switch r.Signal {
+		case "SIGTERM", "SIGKILL":
+			killed++
+		case "UNKILLABLE":
+			escalated++
+		}
+	}
+
+	if killed > 0 {
+		fmt.Printf("  %s cleaned up %d orphaned process(es)\n", style.Success.Render("✓"), killed)
+	}
+	if escalated > 0 {
+		fmt.Printf("  %s %d process(es) survived SIGKILL (unkillable)\n", style.Warning.Render("⚠"), escalated)
+	}
+}
+
 func runPolecatStale(cmd *cobra.Command, args []string) error {
 	rigName := args[0]
 	mgr, r, err := getPolecatManager(rigName)

internal/cmd/polecat_identity.go

@@ -591,10 +591,13 @@ func runPolecatIdentityRename(cmd *cobra.Command, args []string) error {
 
 	// Create new identity bead with inherited fields
 	newFields := &beads.AgentFields{
-		RoleType:      "polecat",
-		Rig:           rigName,
-		AgentState:    oldFields.AgentState,
-		CleanupStatus: oldFields.CleanupStatus,
+		RoleType:          "polecat",
+		Rig:               rigName,
+		AgentState:        oldFields.AgentState,
+		HookBead:          oldFields.HookBead,
+		CleanupStatus:     oldFields.CleanupStatus,
+		ActiveMR:          oldFields.ActiveMR,
+		NotificationLevel: oldFields.NotificationLevel,
 	}
 
 	newTitle := fmt.Sprintf("Polecat %s in %s", newName, rigName)

internal/cmd/prime.go

@@ -2,7 +2,6 @@ package cmd
 
 import (
 	"bytes"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"os"
@@ -12,6 +11,7 @@ import (
 
 	"github.com/spf13/cobra"
 	"github.com/steveyegge/gastown/internal/beads"
+	"github.com/steveyegge/gastown/internal/git"
 	"github.com/steveyegge/gastown/internal/lock"
 	"github.com/steveyegge/gastown/internal/state"
 	"github.com/steveyegge/gastown/internal/style"
@@ -340,29 +340,13 @@ func detectRole(cwd, townRoot string) RoleInfo {
 	return ctx
 }
 
-// runBdPrime runs `bd prime` and outputs the result.
-// This provides beads workflow context to the agent.
+// runBdPrime outputs beads workflow context directly.
+// This replaces the bd subprocess call to eliminate ~40ms startup overhead.
 func runBdPrime(workDir string) {
-	cmd := exec.Command("bd", "prime")
-	cmd.Dir = workDir
-
-	var stdout, stderr bytes.Buffer
-	cmd.Stdout = &stdout
-	cmd.Stderr = &stderr
-
-	if err := cmd.Run(); err != nil {
-		// Skip if bd prime fails (beads might not be available)
-		// But log stderr if present for debugging
-		if errMsg := strings.TrimSpace(stderr.String()); errMsg != "" {
-			fmt.Fprintf(os.Stderr, "bd prime: %s\n", errMsg)
-		}
-		return
-	}
-
-	output := strings.TrimSpace(stdout.String())
-	if output != "" {
+	content := beads.GetPrimeContent(workDir)
+	if content != "" {
 		fmt.Println()
-		fmt.Println(output)
+		fmt.Println(content)
 	}
 }
 
@@ -433,6 +417,11 @@ func checkSlungWork(ctx RoleContext) bool {
 	// Build the role announcement string
 	roleAnnounce := buildRoleAnnouncement(ctx)
 
+	// Check for attached molecule FIRST - this determines the instruction flow
+	// With formula-on-bead, the base bead is hooked with attached_molecule pointing to wisp.
+	attachment := beads.ParseAttachmentFields(hookedBead)
+	hasMolecule := attachment != nil && attachment.AttachedMolecule != ""
+
 	// Found hooked work! Display AUTONOMOUS MODE prominently
 	fmt.Println()
 	fmt.Printf("%s\n\n", style.Bold.Render("## 🚨 AUTONOMOUS WORK MODE 🚨"))
@@ -447,14 +436,25 @@ func checkSlungWork(ctx RoleContext) bool {
 	fmt.Println("a track record that proves autonomous execution works at scale.")
 	fmt.Println()
 	fmt.Println("1. Announce: \"" + roleAnnounce + "\" (ONE line, no elaboration)")
-	fmt.Printf("2. Then IMMEDIATELY run: `bd show %s`\n", hookedBead.ID)
-	fmt.Println("3. Begin execution - no waiting for user input")
+
+	// Instructions differ based on whether molecule is attached
+	if hasMolecule {
+		fmt.Println("2. This bead has an ATTACHED MOLECULE (formula workflow)")
+		fmt.Println("3. Work through molecule steps in order - see CURRENT STEP below")
+		fmt.Println("4. Close each step with `bd close <step-id>`, then check `bd ready`")
+	} else {
+		fmt.Printf("2. Then IMMEDIATELY run: `bd show %s`\n", hookedBead.ID)
+		fmt.Println("3. Begin execution - no waiting for user input")
+	}
 	fmt.Println()
 	fmt.Println("**DO NOT:**")
 	fmt.Println("- Wait for user response after announcing")
 	fmt.Println("- Ask clarifying questions")
 	fmt.Println("- Describe what you're going to do")
 	fmt.Println("- Check mail first (hook takes priority)")
+	if hasMolecule {
+		fmt.Println("- Skip molecule steps or work on the base bead directly")
+	}
 	fmt.Println()
 
 	// Show the hooked work details
@@ -476,30 +476,48 @@ func checkSlungWork(ctx RoleContext) bool {
 	}
 	fmt.Println()
 
-	// Show bead preview using bd show
-	fmt.Println("**Bead details:**")
-	cmd := exec.Command("bd", "show", hookedBead.ID)
-	var stdout, stderr bytes.Buffer
-	cmd.Stdout = &stdout
-	cmd.Stderr = &stderr
-	if err := cmd.Run(); err != nil {
-		if errMsg := strings.TrimSpace(stderr.String()); errMsg != "" {
-			fmt.Fprintf(os.Stderr, "  bd show %s: %s\n", hookedBead.ID, errMsg)
-		} else {
-			fmt.Fprintf(os.Stderr, "  bd show %s: %v\n", hookedBead.ID, err)
+	// If molecule attached, show molecule context prominently INSTEAD of bd show
+	if hasMolecule {
+		fmt.Printf("%s\n\n", style.Bold.Render("## 🧬 ATTACHED MOLECULE (FORMULA WORKFLOW)"))
+		fmt.Printf("Molecule ID: %s\n", attachment.AttachedMolecule)
+		if attachment.AttachedArgs != "" {
+			fmt.Printf("\n%s\n", style.Bold.Render("📋 ARGS (use these to guide execution):"))
+			fmt.Printf("  %s\n", attachment.AttachedArgs)
 		}
+		fmt.Println()
+
+		// Show current step from molecule - THIS IS THE PRIMARY INSTRUCTION
+		showMoleculeExecutionPrompt(ctx.WorkDir, attachment.AttachedMolecule)
+
+		fmt.Println()
+		fmt.Printf("%s\n", style.Bold.Render("⚠️  IMPORTANT: Follow the molecule steps above, NOT the base bead."))
+		fmt.Println("The base bead is just a container. The molecule steps define your workflow.")
 	} else {
-		lines := strings.Split(stdout.String(), "\n")
-		maxLines := 15
-		if len(lines) > maxLines {
-			lines = lines[:maxLines]
-			lines = append(lines, "...")
-		}
-		for _, line := range lines {
-			fmt.Printf("  %s\n", line)
+		// No molecule - show bead preview using bd show
+		fmt.Println("**Bead details:**")
+		cmd := exec.Command("bd", "show", hookedBead.ID)
+		var stdout, stderr bytes.Buffer
+		cmd.Stdout = &stdout
+		cmd.Stderr = &stderr
+		if err := cmd.Run(); err != nil {
+			if errMsg := strings.TrimSpace(stderr.String()); errMsg != "" {
+				fmt.Fprintf(os.Stderr, "  bd show %s: %s\n", hookedBead.ID, errMsg)
+			} else {
+				fmt.Fprintf(os.Stderr, "  bd show %s: %v\n", hookedBead.ID, err)
+			}
+		} else {
+			lines := strings.Split(stdout.String(), "\n")
+			maxLines := 15
+			if len(lines) > maxLines {
+				lines = lines[:maxLines]
+				lines = append(lines, "...")
+			}
+			for _, line := range lines {
+				fmt.Printf("  %s\n", line)
+			}
 		}
+		fmt.Println()
 	}
-	fmt.Println()
 
 	return true
 }
@@ -527,13 +545,9 @@ func buildRoleAnnouncement(ctx RoleContext) string {
 }
 
 // getGitRoot returns the root of the current git repository.
+// Uses cached value to avoid repeated git subprocess calls.
 func getGitRoot() (string, error) {
-	cmd := exec.Command("git", "rev-parse", "--show-toplevel")
-	out, err := cmd.Output()
-	if err != nil {
-		return "", err
-	}
-	return strings.TrimSpace(string(out)), nil
+	return git.RepoRoot()
 }
 
 // getAgentIdentity returns the agent identity string for hook lookup.
@@ -672,34 +686,20 @@ func ensureBeadsRedirect(ctx RoleContext) {
 
 // checkPendingEscalations queries for open escalation beads and displays them prominently.
 // This is called on Mayor startup to surface issues needing human attention.
+// Uses beads package which leverages RPC when daemon is available.
 func checkPendingEscalations(ctx RoleContext) {
-	// Query for open escalations using bd list with tag filter
-	cmd := exec.Command("bd", "list", "--status=open", "--tag=escalation", "--json")
-	cmd.Dir = ctx.WorkDir
-
-	var stdout, stderr bytes.Buffer
-	cmd.Stdout = &stdout
-	cmd.Stderr = &stderr
-
-	if err := cmd.Run(); err != nil {
+	// Query for open escalations using beads package (uses RPC when available)
+	b := beads.New(ctx.WorkDir)
+	escalations, err := b.List(beads.ListOptions{
+		Status:   "open",
+		Label:    "escalation",
+		Priority: -1,
+	})
+	if err != nil || len(escalations) == 0 {
 		// Silently skip - escalation check is best-effort
 		return
 	}
 
-	// Parse JSON output
-	var escalations []struct {
-		ID          string `json:"id"`
-		Title       string `json:"title"`
-		Priority    int    `json:"priority"`
-		Description string `json:"description"`
-		Created     string `json:"created"`
-	}
-
-	if err := json.Unmarshal(stdout.Bytes(), &escalations); err != nil || len(escalations) == 0 {
-		// No escalations or parse error
-		return
-	}
-
 	// Count by severity
 	critical := 0
 	high := 0

internal/cmd/prime_molecule.go

@@ -88,9 +88,9 @@ func showMoleculeExecutionPrompt(workDir, moleculeID string) {
 		fmt.Println(style.Bold.Render("→ EXECUTE THIS STEP NOW."))
 		fmt.Println()
 		fmt.Println("When complete:")
-		fmt.Printf("  1. Close the step: bd close %s\n", step.ID)
-		fmt.Println("  2. Check for next step: bd ready")
-		fmt.Println("  3. Continue until molecule complete")
+		fmt.Printf("  gt mol step done %s\n", step.ID)
+		fmt.Println()
+		fmt.Println("This closes the step and respawns your session with fresh context for the next step.")
 	} else {
 		// No next step - molecule may be complete
 		fmt.Println(style.Bold.Render("✓ MOLECULE COMPLETE"))
@@ -162,11 +162,10 @@ func outputMoleculeContext(ctx RoleContext) {
 		showMoleculeProgress(b, rootID)
 
 		fmt.Println()
-		fmt.Println("**Molecule Work Loop:**")
-		fmt.Println("1. Complete current step, then `bd close " + issue.ID + "`")
-		fmt.Println("2. Check for next steps: `bd ready --parent " + rootID + "`")
-		fmt.Println("3. Work on next ready step(s)")
-		fmt.Println("4. When all steps done, run `gt done`")
+		fmt.Println("**When step complete:**")
+		fmt.Println("  `gt mol step done " + issue.ID + "`")
+		fmt.Println()
+		fmt.Println("This closes the step and respawns with fresh context for the next step.")
 		break // Only show context for first molecule step found
 	}
 }

internal/cmd/prime_output.go

@@ -113,6 +113,7 @@ func outputMayorContext(ctx RoleContext) {
 	fmt.Println("- `gt status` - Show overall town status")
 	fmt.Println("- `gt rig list` - List all rigs")
 	fmt.Println("- `bd ready` - Issues ready to work")
+	fmt.Println("- `bd tree <issue>` - View ancestry, siblings, dependencies")
 	fmt.Println()
 	fmt.Println("## Hookable Mail")
 	fmt.Println("Mail can be hooked for ad-hoc instructions: `gt hook attach <mail-id>`")
@@ -176,6 +177,7 @@ func outputPolecatContext(ctx RoleContext) {
 	fmt.Println("## Key Commands")
 	fmt.Println("- `gt mail inbox` - Check your inbox for work assignments")
 	fmt.Println("- `bd show <issue>` - View your assigned issue")
+	fmt.Println("- `bd tree <issue>` - View ancestry, siblings, dependencies")
 	fmt.Println("- `bd close <issue>` - Mark issue complete")
 	fmt.Println("- `gt done` - Signal work ready for merge")
 	fmt.Println()
@@ -200,6 +202,7 @@ func outputCrewContext(ctx RoleContext) {
 	fmt.Println("- `gt mail inbox` - Check your inbox")
 	fmt.Println("- `bd ready` - Available issues")
 	fmt.Println("- `bd show <issue>` - View issue details")
+	fmt.Println("- `bd tree <issue>` - View ancestry, siblings, dependencies")
 	fmt.Println("- `bd close <issue>` - Mark issue complete")
 	fmt.Println()
 	fmt.Println("## Hookable Mail")

internal/cmd/ready.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"bufio"
 	"encoding/json"
 	"fmt"
 	"os"
@@ -132,7 +133,10 @@ func runReady(cmd *cobra.Command, args []string) error {
 			} else {
 				// Filter out formula scaffolds (gt-579)
 				formulaNames := getFormulaNames(townBeadsPath)
-				src.Issues = filterFormulaScaffolds(issues, formulaNames)
+				filtered := filterFormulaScaffolds(issues, formulaNames)
+				// Defense-in-depth: also filter wisps that shouldn't appear in ready work
+				wispIDs := getWispIDs(townBeadsPath)
+				src.Issues = filterWisps(filtered, wispIDs)
 			}
 			sources = append(sources, src)
 		}()
@@ -143,8 +147,10 @@ func runReady(cmd *cobra.Command, args []string) error {
 		wg.Add(1)
 		go func(r *rig.Rig) {
 			defer wg.Done()
-			// Use mayor/rig path where rig-level beads are stored
-			rigBeadsPath := constants.RigMayorPath(r.Path)
+			// Use rig root path - ResolveBeadsDir follows redirects to find actual beads.
+			// For tracked beads: <rig>/.beads/redirect -> mayor/rig/.beads
+			// For rig-local beads: <rig>/.beads directly
+			rigBeadsPath := r.Path
 			rigBeads := beads.New(rigBeadsPath)
 			issues, err := rigBeads.Ready()
 
@@ -156,7 +162,10 @@ func runReady(cmd *cobra.Command, args []string) error {
 			} else {
 				// Filter out formula scaffolds (gt-579)
 				formulaNames := getFormulaNames(rigBeadsPath)
-				src.Issues = filterFormulaScaffolds(issues, formulaNames)
+				filtered := filterFormulaScaffolds(issues, formulaNames)
+				// Defense-in-depth: also filter wisps that shouldn't appear in ready work
+				wispIDs := getWispIDs(rigBeadsPath)
+				src.Issues = filterWisps(filtered, wispIDs)
 			}
 			sources = append(sources, src)
 		}(r)
@@ -346,3 +355,56 @@ func filterFormulaScaffolds(issues []*beads.Issue, formulaNames map[string]bool)
 	}
 	return filtered
 }
+
+// getWispIDs reads the issues.jsonl and returns a set of IDs that are wisps.
+// Wisps are ephemeral issues (wisp: true flag) that shouldn't appear in ready work.
+// This is a defense-in-depth exclusion - bd ready should already filter wisps,
+// but we double-check at the display layer to ensure operational work doesn't leak.
+func getWispIDs(beadsPath string) map[string]bool {
+	beadsDir := beads.ResolveBeadsDir(beadsPath)
+	issuesPath := filepath.Join(beadsDir, "issues.jsonl")
+	file, err := os.Open(issuesPath)
+	if err != nil {
+		return nil // No issues file
+	}
+	defer file.Close()
+
+	wispIDs := make(map[string]bool)
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if line == "" {
+			continue
+		}
+
+		var issue struct {
+			ID   string `json:"id"`
+			Wisp bool   `json:"wisp"`
+		}
+		if err := json.Unmarshal([]byte(line), &issue); err != nil {
+			continue
+		}
+
+		if issue.Wisp {
+			wispIDs[issue.ID] = true
+		}
+	}
+
+	return wispIDs
+}
+
+// filterWisps removes wisp issues from the list.
+// Wisps are ephemeral operational work that shouldn't appear in ready work.
+func filterWisps(issues []*beads.Issue, wispIDs map[string]bool) []*beads.Issue {
+	if wispIDs == nil || len(wispIDs) == 0 {
+		return issues
+	}
+
+	filtered := make([]*beads.Issue, 0, len(issues))
+	for _, issue := range issues {
+		if !wispIDs[issue.ID] {
+			filtered = append(filtered, issue)
+		}
+	}
+	return filtered
+}

internal/cmd/refinery.go

@@ -337,6 +337,14 @@ func runRefineryStop(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// RefineryStatusOutput is the JSON output format for refinery status.
+type RefineryStatusOutput struct {
+	Running     bool   `json:"running"`
+	RigName     string `json:"rig_name"`
+	Session     string `json:"session,omitempty"`
+	QueueLength int    `json:"queue_length"`
+}
+
 func runRefineryStatus(cmd *cobra.Command, args []string) error {
 	rigName := ""
 	if len(args) > 0 {
@@ -348,58 +356,42 @@ func runRefineryStatus(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	ref, err := mgr.Status()
-	if err != nil {
-		return fmt.Errorf("getting status: %w", err)
-	}
+	// ZFC: tmux is source of truth for running state
+	running, _ := mgr.IsRunning()
+	sessionInfo, _ := mgr.Status() // may be nil if not running
+
+	// Get queue from beads
+	queue, _ := mgr.Queue()
+	queueLen := len(queue)
 
 	// JSON output
 	if refineryStatusJSON {
+		output := RefineryStatusOutput{
+			Running:     running,
+			RigName:     rigName,
+			QueueLength: queueLen,
+		}
+		if sessionInfo != nil {
+			output.Session = sessionInfo.Name
+		}
 		enc := json.NewEncoder(os.Stdout)
 		enc.SetIndent("", "  ")
-		return enc.Encode(ref)
+		return enc.Encode(output)
 	}
 
 	// Human-readable output
 	fmt.Printf("%s Refinery: %s\n\n", style.Bold.Render("⚙"), rigName)
 
-	stateStr := string(ref.State)
-	switch ref.State {
-	case refinery.StateRunning:
-		stateStr = style.Bold.Render("● running")
-	case refinery.StateStopped:
-		stateStr = style.Dim.Render("○ stopped")
-	case refinery.StatePaused:
-		stateStr = style.Dim.Render("⏸ paused")
-	}
-	fmt.Printf("  State: %s\n", stateStr)
-
-	if ref.StartedAt != nil {
-		fmt.Printf("  Started: %s\n", ref.StartedAt.Format("2006-01-02 15:04:05"))
-	}
-
-	if ref.CurrentMR != nil {
-		fmt.Printf("\n  %s\n", style.Bold.Render("Currently Processing:"))
-		fmt.Printf("    Branch: %s\n", ref.CurrentMR.Branch)
-		fmt.Printf("    Worker: %s\n", ref.CurrentMR.Worker)
-		if ref.CurrentMR.IssueID != "" {
-			fmt.Printf("    Issue:  %s\n", ref.CurrentMR.IssueID)
+	if running {
+		fmt.Printf("  State: %s\n", style.Bold.Render("● running"))
+		if sessionInfo != nil {
+			fmt.Printf("  Session: %s\n", sessionInfo.Name)
 		}
+	} else {
+		fmt.Printf("  State: %s\n", style.Dim.Render("○ stopped"))
 	}
 
-	// Get queue length
-	queue, _ := mgr.Queue()
-	pendingCount := 0
-	for _, item := range queue {
-		if item.Position > 0 { // Not currently processing
-			pendingCount++
-		}
-	}
-	fmt.Printf("\n  Queue: %d pending\n", pendingCount)
-
-	if ref.LastMergeAt != nil {
-		fmt.Printf("  Last merge: %s\n", ref.LastMergeAt.Format("2006-01-02 15:04:05"))
-	}
+	fmt.Printf("\n  Queue: %d pending\n", queueLen)
 
 	return nil
 }

internal/cmd/rig.go

@@ -505,6 +505,12 @@ func runRigRemove(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("loading rigs config: %w", err)
 	}
 
+	// Get the rig's beads prefix before removing (needed for route cleanup)
+	var beadsPrefix string
+	if entry, ok := rigsConfig.Rigs[name]; ok && entry.BeadsConfig != nil {
+		beadsPrefix = entry.BeadsConfig.Prefix
+	}
+
 	// Create rig manager
 	g := git.NewGit(townRoot)
 	mgr := rig.NewManager(townRoot, rigsConfig, g)
@@ -518,6 +524,14 @@ func runRigRemove(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("saving rigs config: %w", err)
 	}
 
+	// Remove route from routes.jsonl (issue #899)
+	if beadsPrefix != "" {
+		if err := beads.RemoveRoute(townRoot, beadsPrefix+"-"); err != nil {
+			// Non-fatal: log warning but continue
+			fmt.Printf("  %s Could not remove route from routes.jsonl: %v\n", style.Warning.Render("!"), err)
+		}
+	}
+
 	fmt.Printf("%s Rig %s removed from registry\n", style.Success.Render("✓"), name)
 	fmt.Printf("\nNote: Files at %s were NOT deleted.\n", filepath.Join(townRoot, name))
 	fmt.Printf("To delete: %s\n", style.Dim.Render(fmt.Sprintf("rm -rf %s", filepath.Join(townRoot, name))))
@@ -977,8 +991,7 @@ func runRigShutdown(cmd *cobra.Command, args []string) error {
 
 	// 2. Stop the refinery
 	refMgr := refinery.NewManager(r)
-	refStatus, err := refMgr.Status()
-	if err == nil && refStatus.State == refinery.StateRunning {
+	if running, _ := refMgr.IsRunning(); running {
 		fmt.Printf("  Stopping refinery...\n")
 		if err := refMgr.Stop(); err != nil {
 			errors = append(errors, fmt.Sprintf("refinery: %v", err))
@@ -987,8 +1000,7 @@ func runRigShutdown(cmd *cobra.Command, args []string) error {
 
 	// 3. Stop the witness
 	witMgr := witness.NewManager(r)
-	witStatus, err := witMgr.Status()
-	if err == nil && witStatus.State == witness.StateRunning {
+	if running, _ := witMgr.IsRunning(); running {
 		fmt.Printf("  Stopping witness...\n")
 		if err := witMgr.Stop(); err != nil {
 			errors = append(errors, fmt.Sprintf("witness: %v", err))
@@ -1075,16 +1087,10 @@ func runRigStatus(cmd *cobra.Command, args []string) error {
 
 	// Witness status
 	fmt.Printf("%s\n", style.Bold.Render("Witness"))
-	witnessSession := fmt.Sprintf("gt-%s-witness", rigName)
-	witnessRunning, _ := t.HasSession(witnessSession)
 	witMgr := witness.NewManager(r)
-	witStatus, _ := witMgr.Status()
+	witnessRunning, _ := witMgr.IsRunning()
 	if witnessRunning {
-		fmt.Printf("  %s running", style.Success.Render("●"))
-		if witStatus != nil && witStatus.StartedAt != nil {
-			fmt.Printf(" (uptime: %s)", formatDuration(time.Since(*witStatus.StartedAt)))
-		}
-		fmt.Printf("\n")
+		fmt.Printf("  %s running\n", style.Success.Render("●"))
 	} else {
 		fmt.Printf("  %s stopped\n", style.Dim.Render("○"))
 	}
@@ -1092,16 +1098,10 @@ func runRigStatus(cmd *cobra.Command, args []string) error {
 
 	// Refinery status
 	fmt.Printf("%s\n", style.Bold.Render("Refinery"))
-	refinerySession := fmt.Sprintf("gt-%s-refinery", rigName)
-	refineryRunning, _ := t.HasSession(refinerySession)
 	refMgr := refinery.NewManager(r)
-	refStatus, _ := refMgr.Status()
+	refineryRunning, _ := refMgr.IsRunning()
 	if refineryRunning {
-		fmt.Printf("  %s running", style.Success.Render("●"))
-		if refStatus != nil && refStatus.StartedAt != nil {
-			fmt.Printf(" (uptime: %s)", formatDuration(time.Since(*refStatus.StartedAt)))
-		}
-		fmt.Printf("\n")
+		fmt.Printf("  %s running\n", style.Success.Render("●"))
 		// Show queue size
 		queue, err := refMgr.Queue()
 		if err == nil && len(queue) > 0 {
@@ -1254,8 +1254,7 @@ func runRigStop(cmd *cobra.Command, args []string) error {
 
 		// 2. Stop the refinery
 		refMgr := refinery.NewManager(r)
-		refStatus, err := refMgr.Status()
-		if err == nil && refStatus.State == refinery.StateRunning {
+		if running, _ := refMgr.IsRunning(); running {
 			fmt.Printf("  Stopping refinery...\n")
 			if err := refMgr.Stop(); err != nil {
 				errors = append(errors, fmt.Sprintf("refinery: %v", err))
@@ -1264,8 +1263,7 @@ func runRigStop(cmd *cobra.Command, args []string) error {
 
 		// 3. Stop the witness
 		witMgr := witness.NewManager(r)
-		witStatus, err := witMgr.Status()
-		if err == nil && witStatus.State == witness.StateRunning {
+		if running, _ := witMgr.IsRunning(); running {
 			fmt.Printf("  Stopping witness...\n")
 			if err := witMgr.Stop(); err != nil {
 				errors = append(errors, fmt.Sprintf("witness: %v", err))
@@ -1387,8 +1385,7 @@ func runRigRestart(cmd *cobra.Command, args []string) error {
 
 		// 2. Stop the refinery
 		refMgr := refinery.NewManager(r)
-		refStatus, err := refMgr.Status()
-		if err == nil && refStatus.State == refinery.StateRunning {
+		if running, _ := refMgr.IsRunning(); running {
 			fmt.Printf("    Stopping refinery...\n")
 			if err := refMgr.Stop(); err != nil {
 				stopErrors = append(stopErrors, fmt.Sprintf("refinery: %v", err))
@@ -1397,8 +1394,7 @@ func runRigRestart(cmd *cobra.Command, args []string) error {
 
 		// 3. Stop the witness
 		witMgr := witness.NewManager(r)
-		witStatus, err := witMgr.Status()
-		if err == nil && witStatus.State == witness.StateRunning {
+		if running, _ := witMgr.IsRunning(); running {
 			fmt.Printf("    Stopping witness...\n")
 			if err := witMgr.Stop(); err != nil {
 				stopErrors = append(stopErrors, fmt.Sprintf("witness: %v", err))

internal/cmd/rig_detect.go

@@ -30,10 +30,11 @@ for fast lookups by the shell hook.
 
 Output format (to stdout):
   export GT_TOWN_ROOT=/path/to/town
+  export GT_ROOT=/path/to/town
   export GT_RIG=rigname
 
 Or if not in a rig:
-  unset GT_TOWN_ROOT GT_RIG`,
+  unset GT_TOWN_ROOT GT_ROOT GT_RIG`,
 	Args: cobra.MaximumNArgs(1),
 	RunE: runRigDetect,
 }
@@ -63,9 +64,11 @@ func runRigDetect(cmd *cobra.Command, args []string) error {
 
 	if rigName != "" {
 		fmt.Printf("export GT_TOWN_ROOT=%q\n", townRoot)
+		fmt.Printf("export GT_ROOT=%q\n", townRoot)
 		fmt.Printf("export GT_RIG=%q\n", rigName)
 	} else {
 		fmt.Printf("export GT_TOWN_ROOT=%q\n", townRoot)
+		fmt.Printf("export GT_ROOT=%q\n", townRoot)
 		fmt.Println("unset GT_RIG")
 	}
 
@@ -105,7 +108,7 @@ func detectRigFromPath(townRoot, absPath string) string {
 }
 
 func outputNotInRig() error {
-	fmt.Println("unset GT_TOWN_ROOT GT_RIG")
+	fmt.Println("unset GT_TOWN_ROOT GT_ROOT GT_RIG")
 	return nil
 }
 
@@ -129,11 +132,11 @@ func updateRigCache(repoRoot, townRoot, rigName string) error {
 
 	var value string
 	if rigName != "" {
-		value = fmt.Sprintf("export GT_TOWN_ROOT=%q; export GT_RIG=%q", townRoot, rigName)
+		value = fmt.Sprintf("export GT_TOWN_ROOT=%q; export GT_ROOT=%q; export GT_RIG=%q", townRoot, townRoot, rigName)
 	} else if townRoot != "" {
-		value = fmt.Sprintf("export GT_TOWN_ROOT=%q; unset GT_RIG", townRoot)
+		value = fmt.Sprintf("export GT_TOWN_ROOT=%q; export GT_ROOT=%q; unset GT_RIG", townRoot, townRoot)
 	} else {
-		value = "unset GT_TOWN_ROOT GT_RIG"
+		value = "unset GT_TOWN_ROOT GT_ROOT GT_RIG"
 	}
 
 	existing[repoRoot] = value

internal/cmd/rig_dock.go

@@ -66,6 +66,18 @@ func init() {
 func runRigDock(cmd *cobra.Command, args []string) error {
 	rigName := args[0]
 
+	// Check we're on main branch - docking on other branches won't persist
+	branchCmd := exec.Command("git", "branch", "--show-current")
+	branchOutput, err := branchCmd.Output()
+	if err == nil {
+		currentBranch := string(branchOutput)
+		currentBranch = currentBranch[:len(currentBranch)-1] // trim newline
+		if currentBranch != "main" && currentBranch != "master" {
+			return fmt.Errorf("cannot dock: must be on main branch (currently on %s)\n"+
+				"Docking on other branches won't persist. Run: git checkout main", currentBranch)
+		}
+	}
+
 	// Get rig
 	_, r, err := getRig(rigName)
 	if err != nil {
@@ -166,6 +178,18 @@ func runRigDock(cmd *cobra.Command, args []string) error {
 func runRigUndock(cmd *cobra.Command, args []string) error {
 	rigName := args[0]
 
+	// Check we're on main branch - undocking on other branches won't persist
+	branchCmd := exec.Command("git", "branch", "--show-current")
+	branchOutput, err := branchCmd.Output()
+	if err == nil {
+		currentBranch := string(branchOutput)
+		currentBranch = currentBranch[:len(currentBranch)-1] // trim newline
+		if currentBranch != "main" && currentBranch != "master" {
+			return fmt.Errorf("cannot undock: must be on main branch (currently on %s)\n"+
+				"Undocking on other branches won't persist. Run: git checkout main", currentBranch)
+		}
+	}
+
 	// Get rig and town root
 	_, r, err := getRig(rigName)
 	if err != nil {

internal/cmd/rig_quick_add.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 
 	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/git"
 	"github.com/steveyegge/gastown/internal/style"
 	"github.com/steveyegge/gastown/internal/workspace"
 )
@@ -138,13 +139,7 @@ func runRigQuickAdd(cmd *cobra.Command, args []string) error {
 }
 
 func findGitRoot(path string) (string, error) {
-	cmd := exec.Command("git", "rev-parse", "--show-toplevel")
-	cmd.Dir = path
-	out, err := cmd.Output()
-	if err != nil {
-		return "", err
-	}
-	return strings.TrimSpace(string(out)), nil
+	return git.RepoRootFrom(path)
 }
 
 func findGitRemoteURL(gitRoot string) (string, error) {
@@ -165,6 +160,19 @@ func sanitizeRigName(name string) string {
 }
 
 func findOrCreateTown() (string, error) {
+	// Priority 1: GT_TOWN_ROOT env var (explicit user preference)
+	if townRoot := os.Getenv("GT_TOWN_ROOT"); townRoot != "" {
+		if isValidTown(townRoot) {
+			return townRoot, nil
+		}
+	}
+
+	// Priority 2: Try to find from cwd (supports multiple town installations)
+	if townRoot, err := workspace.FindFromCwd(); err == nil && townRoot != "" {
+		return townRoot, nil
+	}
+
+	// Priority 3: Fall back to well-known locations
 	home, err := os.UserHomeDir()
 	if err != nil {
 		return "", err
@@ -176,11 +184,17 @@ func findOrCreateTown() (string, error) {
 	}
 
 	for _, path := range candidates {
-		mayorDir := filepath.Join(path, "mayor")
-		if _, err := os.Stat(mayorDir); err == nil {
+		if isValidTown(path) {
 			return path, nil
 		}
 	}
 
 	return "", fmt.Errorf("no Gas Town found - run 'gt install ~/gt' first")
 }
+
+// isValidTown checks if a path is a valid Gas Town installation.
+func isValidTown(path string) bool {
+	mayorDir := filepath.Join(path, "mayor")
+	_, err := os.Stat(mayorDir)
+	return err == nil
+}

internal/cmd/rig_quick_add_test.go

@@ -0,0 +1,113 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestFindOrCreateTown(t *testing.T) {
+	// Save original env and restore after test
+	origTownRoot := os.Getenv("GT_TOWN_ROOT")
+	defer os.Setenv("GT_TOWN_ROOT", origTownRoot)
+
+	t.Run("respects GT_TOWN_ROOT when set", func(t *testing.T) {
+		// Create a valid town in temp dir
+		tmpTown := t.TempDir()
+		mayorDir := filepath.Join(tmpTown, "mayor")
+		if err := os.MkdirAll(mayorDir, 0755); err != nil {
+			t.Fatalf("mkdir mayor: %v", err)
+		}
+
+		os.Setenv("GT_TOWN_ROOT", tmpTown)
+
+		result, err := findOrCreateTown()
+		if err != nil {
+			t.Fatalf("findOrCreateTown() error = %v", err)
+		}
+		if result != tmpTown {
+			t.Errorf("findOrCreateTown() = %q, want %q", result, tmpTown)
+		}
+	})
+
+	t.Run("ignores invalid GT_TOWN_ROOT", func(t *testing.T) {
+		// Set GT_TOWN_ROOT to a non-existent path
+		os.Setenv("GT_TOWN_ROOT", "/nonexistent/path/to/town")
+
+		// Create a valid town at ~/gt for fallback
+		home, err := os.UserHomeDir()
+		if err != nil {
+			t.Skip("cannot get home dir")
+		}
+
+		gtPath := filepath.Join(home, "gt")
+		mayorDir := filepath.Join(gtPath, "mayor")
+
+		// Skip if ~/gt doesn't exist (don't want to create it in user's home)
+		if _, err := os.Stat(mayorDir); os.IsNotExist(err) {
+			t.Skip("~/gt/mayor does not exist, skipping fallback test")
+		}
+
+		result, err := findOrCreateTown()
+		if err != nil {
+			t.Fatalf("findOrCreateTown() error = %v", err)
+		}
+		// Should fall back to ~/gt since GT_TOWN_ROOT is invalid
+		if result != gtPath {
+			t.Logf("findOrCreateTown() = %q (fell back to valid town)", result)
+		}
+	})
+
+	t.Run("GT_TOWN_ROOT takes priority over fallback", func(t *testing.T) {
+		// Create two valid towns
+		tmpTown1 := t.TempDir()
+		tmpTown2 := t.TempDir()
+
+		if err := os.MkdirAll(filepath.Join(tmpTown1, "mayor"), 0755); err != nil {
+			t.Fatalf("mkdir mayor1: %v", err)
+		}
+		if err := os.MkdirAll(filepath.Join(tmpTown2, "mayor"), 0755); err != nil {
+			t.Fatalf("mkdir mayor2: %v", err)
+		}
+
+		// Set GT_TOWN_ROOT to tmpTown1
+		os.Setenv("GT_TOWN_ROOT", tmpTown1)
+
+		result, err := findOrCreateTown()
+		if err != nil {
+			t.Fatalf("findOrCreateTown() error = %v", err)
+		}
+		// Should use GT_TOWN_ROOT, not any other valid town
+		if result != tmpTown1 {
+			t.Errorf("findOrCreateTown() = %q, want %q (GT_TOWN_ROOT should take priority)", result, tmpTown1)
+		}
+	})
+}
+
+func TestIsValidTown(t *testing.T) {
+	t.Run("valid town has mayor directory", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		mayorDir := filepath.Join(tmpDir, "mayor")
+		if err := os.MkdirAll(mayorDir, 0755); err != nil {
+			t.Fatalf("mkdir: %v", err)
+		}
+
+		if !isValidTown(tmpDir) {
+			t.Error("isValidTown() = false, want true")
+		}
+	})
+
+	t.Run("invalid town missing mayor directory", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		if isValidTown(tmpDir) {
+			t.Error("isValidTown() = true, want false")
+		}
+	})
+
+	t.Run("nonexistent path is invalid", func(t *testing.T) {
+		if isValidTown("/nonexistent/path") {
+			t.Error("isValidTown() = true, want false")
+		}
+	})
+}

internal/cmd/role.go

@@ -100,6 +100,23 @@ Examples:
 	RunE: runRoleEnv,
 }
 
+var roleDefCmd = &cobra.Command{
+	Use:   "def <role>",
+	Short: "Display role definition (session, health, env config)",
+	Long: `Display the effective role definition after all overrides are applied.
+
+Role configuration is layered:
+  1. Built-in defaults (embedded in binary)
+  2. Town-level overrides (~/.gt/roles/<role>.toml)
+  3. Rig-level overrides (<rig>/roles/<role>.toml)
+
+Examples:
+  gt role def witness    # Show witness role definition
+  gt role def crew       # Show crew role definition`,
+	Args: cobra.ExactArgs(1),
+	RunE: runRoleDef,
+}
+
 // Flags for role home command
 var (
 	roleRig     string
@@ -113,6 +130,7 @@ func init() {
 	roleCmd.AddCommand(roleDetectCmd)
 	roleCmd.AddCommand(roleListCmd)
 	roleCmd.AddCommand(roleEnvCmd)
+	roleCmd.AddCommand(roleDefCmd)
 
 	// Add --rig and --polecat flags to home command for overrides
 	roleHomeCmd.Flags().StringVar(&roleRig, "rig", "", "Rig name (required for rig-specific roles)")
@@ -526,3 +544,83 @@ func runRoleEnv(cmd *cobra.Command, args []string) error {
 
 	return nil
 }
+
+func runRoleDef(cmd *cobra.Command, args []string) error {
+	roleName := args[0]
+
+	// Validate role name
+	validRoles := config.AllRoles()
+	isValid := false
+	for _, r := range validRoles {
+		if r == roleName {
+			isValid = true
+			break
+		}
+	}
+	if !isValid {
+		return fmt.Errorf("unknown role %q - valid roles: %s", roleName, strings.Join(validRoles, ", "))
+	}
+
+	// Determine town root and rig path
+	townRoot, _ := workspace.FindFromCwd()
+	rigPath := ""
+	if townRoot != "" {
+		// Try to get rig path if we're in a rig directory
+		if rigInfo, err := GetRole(); err == nil && rigInfo.Rig != "" {
+			rigPath = filepath.Join(townRoot, rigInfo.Rig)
+		}
+	}
+
+	// Load role definition with overrides
+	def, err := config.LoadRoleDefinition(townRoot, rigPath, roleName)
+	if err != nil {
+		return fmt.Errorf("loading role definition: %w", err)
+	}
+
+	// Display role info
+	fmt.Printf("%s %s\n", style.Bold.Render("Role:"), def.Role)
+	fmt.Printf("%s %s\n", style.Bold.Render("Scope:"), def.Scope)
+	fmt.Println()
+
+	// Session config
+	fmt.Println(style.Bold.Render("[session]"))
+	fmt.Printf("  pattern        = %q\n", def.Session.Pattern)
+	fmt.Printf("  work_dir       = %q\n", def.Session.WorkDir)
+	fmt.Printf("  needs_pre_sync = %v\n", def.Session.NeedsPreSync)
+	if def.Session.StartCommand != "" {
+		fmt.Printf("  start_command  = %q\n", def.Session.StartCommand)
+	}
+	fmt.Println()
+
+	// Environment variables
+	if len(def.Env) > 0 {
+		fmt.Println(style.Bold.Render("[env]"))
+		envKeys := make([]string, 0, len(def.Env))
+		for k := range def.Env {
+			envKeys = append(envKeys, k)
+		}
+		sort.Strings(envKeys)
+		for _, k := range envKeys {
+			fmt.Printf("  %s = %q\n", k, def.Env[k])
+		}
+		fmt.Println()
+	}
+
+	// Health config
+	fmt.Println(style.Bold.Render("[health]"))
+	fmt.Printf("  ping_timeout         = %q\n", def.Health.PingTimeout.String())
+	fmt.Printf("  consecutive_failures = %d\n", def.Health.ConsecutiveFailures)
+	fmt.Printf("  kill_cooldown        = %q\n", def.Health.KillCooldown.String())
+	fmt.Printf("  stuck_threshold      = %q\n", def.Health.StuckThreshold.String())
+	fmt.Println()
+
+	// Prompts
+	if def.Nudge != "" {
+		fmt.Printf("%s %s\n", style.Bold.Render("Nudge:"), def.Nudge)
+	}
+	if def.PromptTemplate != "" {
+		fmt.Printf("%s %s\n", style.Bold.Render("Template:"), def.PromptTemplate)
+	}
+
+	return nil
+}

internal/cmd/root.go

@@ -8,7 +8,9 @@ import (
 	"strings"
 
 	"github.com/spf13/cobra"
+	"github.com/steveyegge/gastown/internal/config"
 	"github.com/steveyegge/gastown/internal/style"
+	"github.com/steveyegge/gastown/internal/ui"
 	"github.com/steveyegge/gastown/internal/version"
 	"github.com/steveyegge/gastown/internal/workspace"
 )
@@ -25,11 +27,32 @@ across distributed teams of AI agents working on shared codebases.`,
 }
 
 // Commands that don't require beads to be installed/checked.
-// These are basic utility commands that should work without beads.
+// NOTE: Gas Town has migrated to Dolt for beads storage. The bd version
+// check is obsolete. Exempt all common commands.
 var beadsExemptCommands = map[string]bool{
 	"version":    true,
 	"help":       true,
 	"completion": true,
+	"crew":       true,
+	"polecat":    true,
+	"witness":    true,
+	"refinery":   true,
+	"status":     true,
+	"mail":       true,
+	"hook":       true,
+	"prime":      true,
+	"nudge":      true,
+	"seance":     true,
+	"doctor":     true,
+	"dolt":       true,
+	"handoff":    true,
+	"costs":      true,
+	"feed":       true,
+	"rig":        true,
+	"config":     true,
+	"install":    true,
+	"tap":        true,
+	"dnd":        true,
 }
 
 // Commands exempt from the town root branch warning.
@@ -45,9 +68,28 @@ var branchCheckExemptCommands = map[string]bool{
 
 // persistentPreRun runs before every command.
 func persistentPreRun(cmd *cobra.Command, args []string) error {
+	// Check if binary was built properly (via make build, not raw go build).
+	// Raw go build produces unsigned binaries that macOS will kill.
+	if BuiltProperly == "" {
+		fmt.Fprintln(os.Stderr, "ERROR: This binary was built with 'go build' directly.")
+		fmt.Fprintln(os.Stderr, "       Use 'make build' to create a properly signed binary.")
+		if gtRoot := os.Getenv("GT_ROOT"); gtRoot != "" {
+			fmt.Fprintf(os.Stderr, "       Run from: %s\n", gtRoot)
+		}
+		os.Exit(1)
+	}
+
+	// Initialize CLI theme (dark/light mode support)
+	initCLITheme()
+
 	// Get the root command name being run
 	cmdName := cmd.Name()
 
+	// Check for stale binary (warning only, doesn't block)
+	if !beadsExemptCommands[cmdName] {
+		checkStaleBinaryWarning()
+	}
+
 	// Check town root branch (warning only, non-blocking)
 	if !branchCheckExemptCommands[cmdName] {
 		warnIfTownRootOffMain()
@@ -62,6 +104,22 @@ func persistentPreRun(cmd *cobra.Command, args []string) error {
 	return CheckBeadsVersion()
 }
 
+// initCLITheme initializes the CLI color theme based on settings and environment.
+func initCLITheme() {
+	// Try to load town settings for CLITheme config
+	var configTheme string
+	if townRoot, err := workspace.FindFromCwd(); err == nil && townRoot != "" {
+		settingsPath := config.TownSettingsPath(townRoot)
+		if settings, err := config.LoadOrCreateTownSettings(settingsPath); err == nil {
+			configTheme = settings.CLITheme
+		}
+	}
+
+	// Initialize theme with config value (env var takes precedence inside InitTheme)
+	ui.InitTheme(configTheme)
+	ui.ApplyThemeMode()
+}
+
 // warnIfTownRootOffMain prints a warning if the town root is not on main branch.
 // This is a non-blocking warning to help catch accidental branch switches.
 func warnIfTownRootOffMain() {