chore: sync formula and recovery work

- Update mol-deacon-patrol formula
- Fix sling helpers, doctor branch check
- Update startup session and tests
- Remove obsolete research doc

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.beads/.gitignore

@@ -10,6 +10,9 @@ daemon.lock
 daemon.log
 daemon.pid
 bd.sock
+bd.sock.startlock
+sync-state.json
+last-touched
 
 # Local version tracking (prevents upgrade notification spam after git ops)
 .local_version
@@ -18,6 +21,10 @@ bd.sock
 db.sqlite
 bd.db
 
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
 # Merge artifacts (temporary files from 3-way merge)
 beads.base.jsonl
 beads.base.meta.json
@@ -26,8 +33,13 @@ beads.left.meta.json
 beads.right.jsonl
 beads.right.meta.json
 
-# Keep JSONL exports and config (source of truth for git)
-!issues.jsonl
-!interactions.jsonl
-!metadata.json
-!config.json
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+sync_base.jsonl
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.

.beads/PRIME.md

@@ -0,0 +1,40 @@
+# Gas Town Worker Context
+
+> **Context Recovery**: Run `gt prime` for full context after compaction or new session.
+
+## The Propulsion Principle (GUPP)
+
+**If you find work on your hook, YOU RUN IT.**
+
+No confirmation. No waiting. No announcements. The hook having work IS the assignment.
+This is physics, not politeness. Gas Town is a steam engine - you are a piston.
+
+**Failure mode we're preventing:**
+- Agent starts with work on hook
+- Agent announces itself and waits for human to say "ok go"
+- Human is AFK / trusting the engine to run
+- Work sits idle. The whole system stalls.
+
+## Startup Protocol
+
+1. Check your hook: `gt mol status`
+2. If work is hooked → EXECUTE (no announcement, no waiting)
+3. If hook empty → Check mail: `gt mail inbox`
+4. Still nothing? Wait for user instructions
+
+## Key Commands
+
+- `gt prime` - Get full role context (run after compaction)
+- `gt mol status` - Check your hooked work
+- `gt mail inbox` - Check for messages
+- `bd ready` - Find available work (no blockers)
+
+## Session Close Protocol
+
+Before saying "done":
+1. git status (check what changed)
+2. git add <files> (stage code changes)
+3. git commit -m "..." (commit code)
+4. git push (push to remote)
+
+**Work is not done until pushed.** Beads changes are automatically committed with Dolt.

.beads/config.yaml

@@ -67,3 +67,6 @@ sync-branch: beads-sync
 # Format: external:<project>:<capability> in bd dep commands
 external_projects:
   beads: ../../../beads/mayor/rig
+
+# Custom issue types for Gas Town (fallback when database is unavailable)
+types.custom: "agent,role,rig,convoy,slot,queue,event,message,molecule,gate,merge-request"

.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

@@ -0,0 +1,381 @@
+description = """
+Gas Town release workflow - from version bump to verified release.
+
+This formula orchestrates a release cycle for Gas Town:
+1. Preflight checks (workspace cleanliness, clean git, up to date)
+2. Documentation updates (CHANGELOG.md, info.go)
+3. Version bump (all components)
+4. Git operations (commit, tag, push)
+5. Local installation update
+6. Daemon restart
+
+## Usage
+
+```bash
+gt mol wisp create gastown-release --var version=0.3.0
+```
+
+Or assign to a crew member:
+```bash
+gt sling gastown/crew/max --formula gastown-release --var version=0.3.0
+```
+
+## Error Handling
+
+- **Crew members (with user present)**: Attempt to resolve issues (merge branches,
+  commit/stash work). Ask the user if blocked.
+- **Polecats (autonomous)**: Escalate via `gt escalate` if preflight fails or
+  unrecoverable errors occur. Do not proceed with a release if workspaces have
+  uncommitted work.
+"""
+formula = "gastown-release"
+type = "workflow"
+version = 1
+
+[vars.version]
+description = "The semantic version to release (e.g., 0.3.0)"
+required = true
+
+[[steps]]
+id = "preflight-workspaces"
+title = "Preflight: Check all workspaces for uncommitted work"
+description = """
+Before releasing, ensure no gastown workspaces have uncommitted work that would
+be excluded from the release.
+
+Check all crew workspaces and the mayor rig:
+
+```bash
+# Check each workspace
+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
+
+    # Check for uncommitted changes
+    if ! git diff-index --quiet HEAD -- 2>/dev/null; then
+      echo "  ⚠ UNCOMMITTED CHANGES"
+      git status --short
+    fi
+
+    # Check for stashes
+    stash_count=$(git stash list 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$stash_count" -gt 0 ]; then
+      echo "  ⚠ HAS $stash_count STASH(ES)"
+      git stash list
+    fi
+
+    # Check for non-main branches with unpushed commits
+    current_branch=$(git branch --show-current 2>/dev/null)
+    if [ -n "$current_branch" ] && [ "$current_branch" != "main" ]; then
+      echo "  ⚠ ON BRANCH: $current_branch (not main)"
+    fi
+  fi
+done
+```
+
+## If issues found:
+
+**For crew members (interactive)**:
+1. Try to resolve: merge branches, commit work, apply/drop stashes
+2. If work is in-progress and not ready, ask the user whether to:
+   - Wait for completion
+   - Stash and proceed
+   - Exclude from this release
+3. Only proceed when all workspaces are clean on main
+
+**For polecats (autonomous)**:
+1. If any workspace has uncommitted work: STOP and escalate
+2. Use: `gt escalate --severity medium "Release blocked: workspace X has uncommitted work"`
+3. Do NOT proceed with release - uncommitted work would be excluded
+
+This step is critical. A release with uncommitted work means losing changes.
+"""
+
+[[steps]]
+id = "preflight-git"
+title = "Preflight: Check git status"
+needs = ["preflight-workspaces"]
+description = """
+Ensure YOUR working tree is clean before starting release.
+
+```bash
+git status
+```
+
+If there are uncommitted changes:
+- Commit them first (if they should be in the release)
+- Stash them: `git stash` (if they should NOT be in the release)
+
+## On failure:
+- **Crew**: Commit or stash your changes, then continue
+- **Polecat**: Escalate if you have uncommitted changes you didn't create
+"""
+
+[[steps]]
+id = "preflight-pull"
+title = "Preflight: Pull latest"
+needs = ["preflight-git"]
+description = """
+Ensure we're up to date with origin.
+
+```bash
+git pull --rebase
+```
+
+## On merge conflicts:
+- **Crew**: Resolve conflicts manually. Ask user if unsure about resolution.
+- **Polecat**: Escalate immediately. Do not attempt to resolve release-blocking
+  merge conflicts autonomously.
+"""
+
+[[steps]]
+id = "review-changes"
+title = "Review changes since last release"
+needs = ["preflight-pull"]
+description = """
+Understand what's being released.
+
+```bash
+git log $(git describe --tags --abbrev=0)..HEAD --oneline
+```
+
+Categorize changes:
+- Features (feat:)
+- Fixes (fix:)
+- Breaking changes
+- Documentation
+
+If there are no changes since last release, ask whether to proceed with an
+empty release (version bump only).
+"""
+
+[[steps]]
+id = "update-changelog"
+title = "Update CHANGELOG.md"
+needs = ["review-changes"]
+description = """
+Write the [Unreleased] section with all changes for {{version}}.
+
+Edit CHANGELOG.md and add entries under [Unreleased].
+
+Format: Keep a Changelog (https://keepachangelog.com)
+
+Sections to use:
+- ### Added - for new features
+- ### Changed - for changes in existing functionality
+- ### Fixed - for bug fixes
+- ### Deprecated - for soon-to-be removed features
+- ### Removed - for now removed features
+
+Base entries on the git log from the previous step. Group related commits.
+
+The bump script will automatically create the version header with today's date.
+"""
+
+[[steps]]
+id = "update-info-go"
+title = "Update info.go versionChanges"
+needs = ["update-changelog"]
+description = """
+Add entry to versionChanges in internal/cmd/info.go.
+
+This powers `gt info --whats-new` for agents.
+
+Add a new entry at the TOP of the versionChanges slice:
+
+```go
+{
+    Version: "{{version}}",
+    Date:    "YYYY-MM-DD",  // Today's date
+    Changes: []string{
+        "NEW: Key feature 1",
+        "NEW: Key feature 2",
+        "CHANGED: Modified behavior",
+        "FIX: Bug that was fixed",
+    },
+},
+```
+
+Focus on agent-relevant and workflow-impacting changes.
+Prefix with NEW:, CHANGED:, FIX:, or DEPRECATED: for clarity.
+
+This is similar to CHANGELOG.md but focused on what agents need to know -
+new commands, changed behaviors, workflow impacts.
+"""
+
+[[steps]]
+id = "run-bump-script"
+title = "Run bump-version.sh"
+needs = ["update-info-go"]
+description = """
+Update all component versions atomically.
+
+```bash
+./scripts/bump-version.sh {{version}}
+```
+
+This updates:
+- internal/cmd/version.go - CLI version constant
+- npm-package/package.json - npm package version
+- CHANGELOG.md - Creates [{{version}}] header with date
+
+Review the changes shown by the script.
+
+## On failure:
+If the script fails (e.g., version already exists, format error):
+- **Crew**: Debug and fix, or ask user
+- **Polecat**: Escalate with error details
+"""
+
+[[steps]]
+id = "verify-versions"
+title = "Verify version consistency"
+needs = ["run-bump-script"]
+description = """
+Confirm all versions match {{version}}.
+
+```bash
+grep 'Version = ' internal/cmd/version.go
+grep '"version"' npm-package/package.json | head -1
+```
+
+Both should show {{version}}.
+
+## On mismatch:
+Do NOT proceed. Either the bump script failed or there's a bug.
+- **Crew**: Investigate and fix manually
+- **Polecat**: Escalate immediately - version mismatch is a release blocker
+"""
+
+[[steps]]
+id = "commit-release"
+title = "Commit release"
+needs = ["verify-versions"]
+description = """
+Stage and commit all version changes.
+
+```bash
+git add -A
+git commit -m "chore: Bump version to {{version}}"
+```
+
+Review the commit to ensure all expected files are included:
+- internal/cmd/version.go
+- internal/cmd/info.go
+- npm-package/package.json
+- CHANGELOG.md
+"""
+
+[[steps]]
+id = "create-tag"
+title = "Create release tag"
+needs = ["commit-release"]
+description = """
+Create annotated git tag.
+
+```bash
+git tag -a v{{version}} -m "Release v{{version}}"
+```
+
+Verify: `git tag -l | tail -5`
+
+## If tag already exists:
+The version may have been previously (partially) released.
+- **Crew**: Ask user how to proceed (delete tag and retry? use different version?)
+- **Polecat**: Escalate - do not delete existing tags autonomously
+"""
+
+[[steps]]
+id = "push-release"
+title = "Push commit and tag"
+needs = ["create-tag"]
+description = """
+Push the release commit and tag to origin.
+
+```bash
+git push origin main
+git push origin v{{version}}
+```
+
+This triggers GitHub Actions to build release artifacts.
+
+Monitor: https://github.com/steveyegge/gastown/actions
+
+## On push rejection:
+Someone pushed while we were releasing.
+- **Crew**: Pull, rebase, re-tag, try again. Ask user if conflicts.
+- **Polecat**: Escalate - release coordination conflict requires human decision
+"""
+
+[[steps]]
+id = "local-install"
+title = "Update local installation"
+needs = ["push-release"]
+description = """
+Rebuild and install gt locally with the new version.
+
+```bash
+go build -o $(go env GOPATH)/bin/gt ./cmd/gt
+```
+
+On macOS, codesign the binary:
+```bash
+codesign -f -s - $(go env GOPATH)/bin/gt
+```
+
+Verify:
+```bash
+gt version
+```
+
+Should show {{version}}.
+
+## On build failure:
+- **Crew**: Debug build error, fix, retry
+- **Polecat**: Escalate - release is pushed but local install failed
+"""
+
+[[steps]]
+id = "restart-daemons"
+title = "Restart daemons"
+needs = ["local-install"]
+description = """
+Restart gt daemon to pick up the new version.
+
+```bash
+gt daemon stop && gt daemon start
+```
+
+Verify:
+```bash
+gt daemon status
+```
+
+The daemon should show the new binary timestamp and no stale warning.
+
+Note: This step is safe to retry if it fails.
+"""
+
+[[steps]]
+id = "release-complete"
+title = "Release complete"
+needs = ["restart-daemons"]
+description = """
+Release v{{version}} is complete!
+
+Summary:
+- All workspaces verified clean before release
+- Version files updated (version.go, package.json)
+- CHANGELOG.md updated with release date
+- info.go versionChanges updated for `gt info --whats-new`
+- Git tag v{{version}} pushed
+- GitHub Actions triggered for artifact builds
+- Local gt binary rebuilt and installed
+- Daemons restarted with new version
+
+Optional next steps:
+- Monitor GitHub Actions for release build completion
+- Verify release artifacts at https://github.com/steveyegge/gastown/releases
+- Announce the release
+"""

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

@@ -27,7 +27,7 @@ Observe the current system state to inform triage decisions.
 **Step 1: Check Deacon state**
 ```bash
 # Is Deacon session alive?
-tmux has-session -t gt-deacon 2>/dev/null && echo "alive" || echo "dead"
+tmux has-session -t hq-deacon 2>/dev/null && echo "alive" || echo "dead"
 
 # If alive, what's the pane output showing?
 gt peek deacon --lines 20
@@ -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**
@@ -125,7 +125,7 @@ gt nudge deacon "Boot check-in: you have pending work"
 **WAKE**
 ```bash
 # Send escape to break any tool waiting
-tmux send-keys -t gt-deacon Escape
+tmux send-keys -t hq-deacon Escape
 
 # Brief pause
 sleep 1
@@ -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

@@ -23,7 +23,7 @@ Witnesses detect it and escalate to the Mayor.
 The Deacon's agent bead last_activity timestamp is updated during each patrol
 cycle. Witnesses check this timestamp to verify health."""
 formula = "mol-deacon-patrol"
-version = 4
+version = 8
 
 [[steps]]
 id = "inbox-check"
@@ -84,10 +84,46 @@ Callbacks may spawn new polecats, update issue state, or trigger other actions.
 **Hygiene principle**: Archive messages after they're fully processed.
 Keep inbox near-empty - only unprocessed items should remain."""
 
+[[steps]]
+id = "orphan-process-cleanup"
+title = "Clean up orphaned claude subagent processes"
+needs = ["inbox-check"]
+description = """
+Clean up orphaned claude subagent processes.
+
+Claude Code's Task tool spawns subagent processes that sometimes don't clean up
+properly after completion. These accumulate and consume significant memory.
+
+**Detection method:**
+Orphaned processes have no controlling terminal (TTY = "?"). Legitimate claude
+instances in terminals have a TTY like "pts/0".
+
+**Run cleanup:**
+```bash
+gt deacon cleanup-orphans
+```
+
+This command:
+1. Lists all claude/codex processes with `ps -eo pid,tty,comm`
+2. Filters for TTY = "?" (no controlling terminal)
+3. Sends SIGTERM to each orphaned process
+4. Reports how many were killed
+
+**Why this is safe:**
+- Processes in terminals (your personal sessions) have a TTY - they won't be touched
+- Only kills processes that have no controlling terminal
+- These orphans are children of the tmux server with no TTY, indicating they're
+  detached subagents that failed to exit
+
+**If cleanup fails:**
+Log the error but continue patrol - this is best-effort cleanup.
+
+**Exit criteria:** Orphan cleanup attempted (success or logged failure)."""
+
 [[steps]]
 id = "trigger-pending-spawns"
 title = "Nudge newly spawned polecats"
-needs = ["inbox-check"]
+needs = ["orphan-process-cleanup"]
 description = """
 Nudge newly spawned polecats that are ready for input.
 
@@ -148,6 +184,49 @@ bd gate list --json
 After closing a gate, the Waiters field contains mail addresses to notify.
 Send a brief notification to each waiter that the gate has cleared."""
 
+[[steps]]
+id = "dispatch-gated-molecules"
+title = "Dispatch molecules with resolved gates"
+needs = ["gate-evaluation"]
+description = """
+Find molecules blocked on gates that have now closed and dispatch them.
+
+This completes the async resume cycle without explicit waiter tracking.
+The molecule state IS the waiter - patrol discovers reality each cycle.
+
+**Step 1: Find gate-ready molecules**
+```bash
+bd mol ready --gated --json
+```
+
+This returns molecules where:
+- Status is in_progress
+- Current step has a gate dependency
+- The gate bead is now closed
+- No polecat currently has it hooked
+
+**Step 2: For each ready molecule, dispatch to the appropriate rig**
+```bash
+# Determine target rig from molecule metadata
+bd mol show <mol-id> --json
+# Look for rig field or infer from prefix
+
+# Dispatch to that rig's polecat pool
+gt sling <mol-id> <rig>/polecats
+```
+
+**Step 3: Log dispatch**
+Note which molecules were dispatched for observability:
+```bash
+# Molecule <mol-id> dispatched to <rig>/polecats (gate <gate-id> cleared)
+```
+
+**If no gate-ready molecules:**
+Skip - nothing to dispatch. Gates haven't closed yet or molecules
+already have active polecats working on them.
+
+**Exit criteria:** All gate-ready molecules dispatched to polecats."""
+
 [[steps]]
 id = "check-convoy-completion"
 title = "Check convoy completion"
@@ -258,10 +337,23 @@ Keep notifications brief and actionable. The recipient can run bd show for detai
 [[steps]]
 id = "health-scan"
 title = "Check Witness and Refinery health"
-needs = ["trigger-pending-spawns", "gate-evaluation", "fire-notifications"]
+needs = ["trigger-pending-spawns", "dispatch-gated-molecules", "fire-notifications"]
 description = """
 Check Witness and Refinery health for each rig.
 
+**IMPORTANT: Skip DOCKED/PARKED rigs**
+Before checking any rig, verify its operational state:
+```bash
+gt rig status <rig>
+# Check the Status: line - if DOCKED or PARKED, skip entirely
+```
+
+DOCKED rigs are globally shut down - do NOT:
+- Check their witness/refinery status
+- Send health pings
+- Attempt restarts
+Simply skip them and move to the next rig.
+
 **IMPORTANT: Idle Town Protocol**
 Before sending health check nudges, check if the town is idle:
 ```bash
@@ -342,14 +434,21 @@ Reset unresponsive_cycles to 0 when component responds normally."""
 
 [[steps]]
 id = "zombie-scan"
-title = "Backup check for zombie polecats"
+title = "Detect zombie polecats (NO KILL AUTHORITY)"
 needs = ["health-scan"]
 description = """
-Defense-in-depth check for zombie polecats that Witness should have cleaned.
+Defense-in-depth DETECTION of zombie polecats that Witness should have cleaned.
+
+**⚠️ CRITICAL: The Deacon has NO kill authority.**
+
+These are workers with context, mid-task progress, unsaved state. Every kill
+destroys work. File the warrant and let Boot handle interrogation and execution.
+You do NOT have kill authority.
 
 **Why this exists:**
-The Witness is responsible for nuking polecats after they complete work (via POLECAT_DONE).
-This step provides backup detection in case the Witness fails to clean up.
+The Witness is responsible for cleaning up polecats after they complete work.
+This step provides backup DETECTION in case the Witness fails to clean up.
+Detection only - Boot handles termination.
 
 **Zombie criteria:**
 - State: idle or done (no active work assigned)
@@ -357,26 +456,34 @@ This step provides backup detection in case the Witness fails to clean up.
 - No hooked work (nothing pending for this polecat)
 - Last activity: older than 10 minutes
 
-**Run the zombie scan:**
+**Run the zombie scan (DRY RUN ONLY):**
 ```bash
 gt deacon zombie-scan --dry-run
 ```
 
+**NEVER run:**
+- `gt deacon zombie-scan` (without --dry-run)
+- `tmux kill-session`
+- `gt polecat nuke`
+- Any command that terminates a session
+
 **If zombies detected:**
 1. Review the output to confirm they are truly abandoned
-2. Run without --dry-run to nuke them:
+2. File a death warrant for each detected zombie:
    ```bash
-   gt deacon zombie-scan
+   gt warrant file <polecat> --reason "Zombie detected: no session, no hook, idle >10m"
+   ```
+3. Boot will handle interrogation and execution
+4. Notify the Mayor about Witness failure:
+   ```bash
+   gt mail send mayor/ -s "Witness cleanup failure" \
+     -m "Filed death warrant for <polecat>. Witness failed to clean up."
    ```
-3. This will:
-   - Nuke each zombie polecat
-   - Notify the Mayor about Witness failure
-   - Log the cleanup action
 
 **If no zombies:**
 No action needed - Witness is doing its job.
 
-**Note:** This is a backup mechanism. If you frequently find zombies,
+**Note:** This is a backup mechanism. If you frequently detect zombies,
 investigate why the Witness isn't cleaning up properly."""
 
 [[steps]]
@@ -386,7 +493,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.
 
@@ -403,7 +510,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"
@@ -441,10 +548,74 @@ gt dog status <name>
 
 **Exit criteria:** Pool has at least 1 idle dog."""
 
+[[steps]]
+id = "dog-health-check"
+title = "Check for stuck dogs"
+needs = ["dog-pool-maintenance"]
+description = """
+Check for dogs that have been working too long (stuck).
+
+Dogs dispatched via `gt dog dispatch --plugin` are marked as "working" with
+a work description like "plugin:rebuild-gt". If a dog hangs, crashes, or
+takes too long, it needs intervention.
+
+**Step 1: List working dogs**
+```bash
+gt dog list --json
+# Filter for state: "working"
+```
+
+**Step 2: Check work duration**
+For each working dog:
+```bash
+gt dog status <name> --json
+# Check: work_started_at, current_work
+```
+
+Compare against timeout:
+- If plugin has [execution] timeout in plugin.md, use that
+- Default timeout: 10 minutes for infrastructure tasks
+
+**Duration calculation:**
+```
+stuck_threshold = plugin_timeout or 10m
+duration = now - work_started_at
+is_stuck = duration > stuck_threshold
+```
+
+**Step 3: Handle stuck dogs**
+
+For dogs working > timeout:
+```bash
+# Option A: File death warrant (Boot handles termination)
+gt warrant file deacon/dogs/<name> --reason "Stuck: working on <work> for <duration>"
+
+# Option B: Force clear work and notify
+gt dog clear <name> --force
+gt mail send deacon/ -s "DOG_TIMEOUT <name>" -m "Dog <name> timed out on <work> after <duration>"
+```
+
+**Decision matrix:**
+
+| Duration over timeout | Action |
+|----------------------|--------|
+| < 2x timeout | Log warning, check next cycle |
+| 2x - 5x timeout | File death warrant |
+| > 5x timeout | Force clear + escalate to Mayor |
+
+**Step 4: Track chronic failures**
+If same dog gets stuck repeatedly:
+```bash
+gt mail send mayor/ -s "Dog <name> chronic failures" \
+  -m "Dog has timed out N times in last 24h. Consider removing from pool."
+```
+
+**Exit criteria:** All stuck dogs handled (warrant filed or cleared)."""
+
 [[steps]]
 id = "orphan-check"
 title = "Detect abandoned work"
-needs = ["dog-pool-maintenance"]
+needs = ["dog-health-check"]
 description = """
 **DETECT ONLY** - Check for orphaned state and dispatch to dog if found.
 
@@ -505,23 +676,86 @@ Skip dispatch - system is healthy.
 
 **Exit criteria:** Session GC dispatched to dog (if needed)."""
 
+[[steps]]
+id = "costs-digest"
+title = "Aggregate daily costs [DISABLED]"
+needs = ["session-gc"]
+description = """
+**⚠️ DISABLED** - Skip this step entirely.
+
+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 patrol digests (dry run)
+gt patrol digest --yesterday --dry-run
+```
+
+If output shows "No patrol digests found", skip to Step 3.
+
+**Step 2: Create the digest**
+```bash
+gt patrol digest --yesterday
+```
+
+This:
+- 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**
+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 patrol digests aggregated (or none to aggregate)."""
+
 [[steps]]
 id = "log-maintenance"
 title = "Rotate logs and prune state"
-needs = ["session-gc"]
+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"
@@ -533,7 +767,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**
@@ -611,15 +845,39 @@ Burn and let daemon respawn, or exit if context high.
 Decision point at end of patrol cycle:
 
 If context is LOW:
-- **Sleep 60 seconds minimum** before next patrol cycle
-- If town is idle (no in_progress work), sleep longer (2-5 minutes)
-- Return to inbox-check step
+Use await-signal with exponential backoff to wait for activity:
 
-**Why longer sleep?**
-- Idle agents should not be disturbed
-- Health checks every few seconds flood inboxes and waste context
-- The daemon (10-minute heartbeat) is the safety net for dead sessions
-- Active work triggers feed events, which wake agents naturally
+```bash
+gt mol step await-signal --agent-bead hq-deacon \
+  --backoff-base 60s --backoff-mult 2 --backoff-max 10m
+```
+
+This command:
+1. Subscribes to `bd activity --follow` (beads activity feed)
+2. Returns IMMEDIATELY when any beads activity occurs
+3. If no activity, times out with exponential backoff:
+   - First timeout: 60s
+   - Second timeout: 120s
+   - Third timeout: 240s
+   - ...capped at 10 minutes max
+4. Tracks `idle:N` label on hq-deacon bead for backoff state
+
+**On signal received** (activity detected):
+Reset the idle counter and start next patrol cycle:
+```bash
+gt agent state hq-deacon --set idle=0
+```
+Then return to inbox-check step.
+
+**On timeout** (no activity):
+The idle counter was auto-incremented. Continue to next patrol cycle
+(the longer backoff will apply next time). Return to inbox-check step.
+
+**Why this approach?**
+- Any `gt` or `bd` command triggers beads activity, waking the Deacon
+- Idle towns let the Deacon sleep longer (up to 10 min between patrols)
+- Active work wakes the Deacon immediately via the feed
+- No polling or fixed sleep intervals
 
 If context is HIGH:
 - Write state to persistent storage

.beads/formulas/mol-gastown-boot.formula.json

@@ -1,62 +0,0 @@
-{
-  "formula": "mol-gastown-boot",
-  "description": "Mayor bootstraps Gas Town via a verification-gated lifecycle molecule.\n\n## Purpose\nWhen Mayor executes \"boot up gas town\", this proto provides the workflow.\nEach step has action + verification - steps stay open until outcome is confirmed.\n\n## Key Principles\n1. **Verification-gated steps** - Not \"command ran\" but \"outcome confirmed\"\n2. **gt peek for verification** - Capture session output to detect stalls\n3. **gt nudge for recovery** - Reliable message delivery to unstick agents\n4. **Parallel where possible** - Witnesses and refineries can start in parallel\n5. **Ephemeral execution** - Boot is a wisp, squashed to digest after completion\n\n## Execution\n```bash\nbd mol wisp mol-gastown-boot  # Create wisp\n```",
-  "version": 1,
-  "steps": [
-    {
-      "id": "ensure-daemon",
-      "title": "Ensure daemon",
-      "description": "Verify the Gas Town daemon is running.\n\n## Action\n```bash\ngt daemon status || gt daemon start\n```\n\n## Verify\n1. Daemon PID file exists: `~/.gt/daemon.pid`\n2. Process is alive: `kill -0 $(cat ~/.gt/daemon.pid)`\n3. Daemon responds: `gt daemon status` returns success\n\n## OnFail\nCannot start daemon. Log error and continue - some commands work without daemon."
-    },
-    {
-      "id": "ensure-deacon",
-      "title": "Ensure deacon",
-      "needs": ["ensure-daemon"],
-      "description": "Start the Deacon and verify patrol mode is active.\n\n## Action\n```bash\ngt deacon start\n```\n\n## Verify\n1. Session exists: `tmux has-session -t gt-deacon 2>/dev/null`\n2. Not stalled: `gt peek deacon/` does NOT show \"> Try\" prompt\n3. Heartbeat fresh: `deacon/heartbeat.json` modified < 2 min ago\n\n## OnStall\n```bash\ngt nudge deacon/ \"Start patrol.\"\nsleep 30\n# Re-verify\n```"
-    },
-    {
-      "id": "ensure-witnesses",
-      "title": "Ensure witnesses",
-      "needs": ["ensure-deacon"],
-      "type": "parallel",
-      "description": "Parallel container: Start all rig witnesses.\n\nChildren execute in parallel. Container completes when all children complete.",
-      "children": [
-        {
-          "id": "ensure-gastown-witness",
-          "title": "Ensure gastown witness",
-          "description": "Start the gastown rig Witness.\n\n## Action\n```bash\ngt witness start gastown\n```\n\n## Verify\n1. Session exists: `tmux has-session -t gastown-witness 2>/dev/null`\n2. Not stalled: `gt peek gastown/witness` does NOT show \"> Try\" prompt\n3. Heartbeat fresh: Last patrol cycle < 5 min ago"
-        },
-        {
-          "id": "ensure-beads-witness",
-          "title": "Ensure beads witness",
-          "description": "Start the beads rig Witness.\n\n## Action\n```bash\ngt witness start beads\n```\n\n## Verify\n1. Session exists: `tmux has-session -t beads-witness 2>/dev/null`\n2. Not stalled: `gt peek beads/witness` does NOT show \"> Try\" prompt\n3. Heartbeat fresh: Last patrol cycle < 5 min ago"
-        }
-      ]
-    },
-    {
-      "id": "ensure-refineries",
-      "title": "Ensure refineries",
-      "needs": ["ensure-deacon"],
-      "type": "parallel",
-      "description": "Parallel container: Start all rig refineries.\n\nChildren execute in parallel. Container completes when all children complete.",
-      "children": [
-        {
-          "id": "ensure-gastown-refinery",
-          "title": "Ensure gastown refinery",
-          "description": "Start the gastown rig Refinery.\n\n## Action\n```bash\ngt refinery start gastown\n```\n\n## Verify\n1. Session exists: `tmux has-session -t gastown-refinery 2>/dev/null`\n2. Not stalled: `gt peek gastown/refinery` does NOT show \"> Try\" prompt\n3. Queue processing: Refinery can receive merge requests"
-        },
-        {
-          "id": "ensure-beads-refinery",
-          "title": "Ensure beads refinery",
-          "description": "Start the beads rig Refinery.\n\n## Action\n```bash\ngt refinery start beads\n```\n\n## Verify\n1. Session exists: `tmux has-session -t beads-refinery 2>/dev/null`\n2. Not stalled: `gt peek beads/refinery` does NOT show \"> Try\" prompt\n3. Queue processing: Refinery can receive merge requests"
-        }
-      ]
-    },
-    {
-      "id": "verify-town-health",
-      "title": "Verify town health",
-      "needs": ["ensure-witnesses", "ensure-refineries"],
-      "description": "Final verification that Gas Town is healthy.\n\n## Action\n```bash\ngt status\n```\n\n## Verify\n1. Daemon running: Shows daemon status OK\n2. Deacon active: Shows deacon in patrol mode\n3. All witnesses: Each rig witness shows active\n4. All refineries: Each rig refinery shows active\n\n## OnFail\nLog degraded state but consider boot complete. Some agents may need manual recovery.\nRun `gt doctor` for detailed diagnostics."
-    }
-  ]
-}

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

@@ -48,7 +48,7 @@ gt deacon start
 ```
 
 ## Verify
-1. Session exists: `tmux has-session -t gt-deacon 2>/dev/null`
+1. Session exists: `tmux has-session -t hq-deacon 2>/dev/null`
 2. Not stalled: `gt peek deacon/` does NOT show \"> Try\" prompt
 3. Heartbeat fresh: `deacon/heartbeat.json` modified < 2 min ago
 

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

@@ -0,0 +1,318 @@
+description = """
+Review code and file beads for issues found.
+
+This molecule guides a polecat through a code review task - examining a portion
+of the codebase for bugs, security issues, code quality problems, or improvement
+opportunities. The output is a set of beads capturing actionable findings.
+
+## Polecat Contract (Self-Cleaning Model)
+
+You are a self-cleaning worker. You:
+1. Receive work via your hook (pinned molecule + review scope)
+2. Work through molecule steps using `bd ready` / `bd close <step>`
+3. Complete and self-clean via `gt done` (submit findings + nuke yourself)
+4. You are GONE - your findings are recorded in beads
+
+**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your
+sandbox, and exit. There is no idle state. Done means gone.
+
+**Important:** This formula defines the template. Your molecule already has step
+beads created from it. Use `bd ready` to find them - do NOT read this file directly.
+
+**You do NOT:**
+- Fix the issues yourself (file beads, let other polecats fix)
+- Scope creep into unrelated areas
+- Wait for someone to act on findings (you're done after filing)
+
+## Variables
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| scope | hook_bead | What to review (file path, directory, or description) |
+| issue | hook_bead | The tracking issue for this review task |
+| focus | hook_bead | Optional focus area (security, performance, etc.) |
+
+## Failure Modes
+
+| Situation | Action |
+|-----------|--------|
+| Scope too broad | Mail Witness, request narrower scope |
+| Can't understand code | Mail Witness for context |
+| Critical issue found | Mail Witness immediately, then continue |"""
+formula = "mol-polecat-code-review"
+version = 1
+
+[[steps]]
+id = "load-context"
+title = "Load context and understand the review scope"
+description = """
+Initialize your session and understand what you're reviewing.
+
+**1. Prime your environment:**
+```bash
+gt prime                    # Load role context
+bd prime                    # Load beads context
+```
+
+**2. Check your hook:**
+```bash
+gt hook               # Shows your pinned molecule and hook_bead
+```
+
+The hook_bead describes your review scope. Read the tracking issue:
+```bash
+bd show {{issue}}           # Full issue details
+```
+
+**3. Understand the scope:**
+- What files/directories are in scope?
+- Is there a specific focus (security, performance, correctness)?
+- What's the context - why is this review happening?
+
+**4. Locate the code:**
+```bash
+# If scope is a path:
+ls -la {{scope}}
+head -100 {{scope}}         # Quick look at the code
+
+# If scope is a directory:
+find {{scope}} -type f -name "*.go" | head -20
+```
+
+**5. Check for recent changes:**
+```bash
+git log --oneline -10 -- {{scope}}
+```
+
+**Exit criteria:** You understand what you're reviewing and why."""
+
+[[steps]]
+id = "survey-code"
+title = "Survey the code structure"
+needs = ["load-context"]
+description = """
+Get a high-level understanding before diving into details.
+
+**1. Understand the structure:**
+```bash
+# For a directory:
+tree {{scope}} -L 2
+
+# For a file:
+wc -l {{scope}}             # How big is it?
+```
+
+**2. Identify key components:**
+- What are the main types/structs?
+- What are the public functions?
+- What are the dependencies?
+
+**3. Read the tests (if any):**
+```bash
+find {{scope}} -name "*_test.go" | xargs head -50
+```
+Tests often reveal intended behavior.
+
+**4. Note initial impressions:**
+- Is the code well-organized?
+- Are there obvious patterns or anti-patterns?
+- What areas look risky?
+
+**Exit criteria:** You have a mental map of the code structure."""
+
+[[steps]]
+id = "detailed-review"
+title = "Perform detailed code review"
+needs = ["survey-code"]
+description = """
+Systematically review the code for issues.
+
+**Review checklist:**
+
+| Category | Look For |
+|----------|----------|
+| **Correctness** | Logic errors, off-by-one, nil handling, race conditions |
+| **Security** | Injection, auth bypass, secrets in code, unsafe operations |
+| **Error handling** | Swallowed errors, missing checks, unclear error messages |
+| **Performance** | N+1 queries, unnecessary allocations, blocking calls |
+| **Maintainability** | Dead code, unclear naming, missing comments on complex logic |
+| **Testing** | Untested paths, missing edge cases, flaky tests |
+
+**Focus on {{focus}} if specified.**
+
+**1. Read through the code:**
+```bash
+cat {{scope}}               # For single file
+# Or read files systematically for a directory
+```
+
+**2. For each issue found, note:**
+- File and line number
+- Category (bug, security, performance, etc.)
+- Severity (critical, high, medium, low)
+- Description of the issue
+- Suggested fix (if obvious)
+
+**3. Don't fix issues yourself:**
+Your job is to find and report, not fix. File beads.
+
+**Exit criteria:** You've reviewed all code in scope and noted issues."""
+
+[[steps]]
+id = "prioritize-findings"
+title = "Prioritize and categorize findings"
+needs = ["detailed-review"]
+description = """
+Organize your findings by priority and category.
+
+**Priority levels:**
+
+| Priority | Description | Action |
+|----------|-------------|--------|
+| P0 | Security vulnerability, data loss risk | Mail Witness immediately |
+| P1 | Bug affecting users, broken functionality | File as bug, high priority |
+| P2 | Code quality issue, potential future bug | File as task |
+| P3 | Improvement opportunity, nice-to-have | File as task, low priority |
+
+**1. Sort your findings:**
+Group by priority, then by category.
+
+**2. For P0 issues:**
+```bash
+gt mail send {{rig}}/witness -s "CRITICAL: Security issue found" -m "Scope: {{scope}}
+Issue: {{issue}}
+Finding: <description of critical issue>
+Location: <file:line>"
+```
+
+**3. Prepare bead descriptions:**
+For each finding, prepare:
+- Clear title
+- File/line location
+- Description of the issue
+- Why it matters
+- Suggested fix (if known)
+
+**Exit criteria:** Findings prioritized and ready to file."""
+
+[[steps]]
+id = "file-beads"
+title = "File beads for all findings"
+needs = ["prioritize-findings"]
+description = """
+Create beads for each finding.
+
+**1. For bugs (P0, P1):**
+```bash
+bd create --type=bug --priority=1 \
+  --title="<clear description of bug>" \
+  --description="Found during code review of {{scope}}.
+
+Location: <file:line>
+
+Issue:
+<description>
+
+Impact:
+<why this matters>
+
+Suggested fix:
+<if known>"
+```
+
+**2. For code quality issues (P2, P3):**
+```bash
+bd create --type=task --priority=2 \
+  --title="<clear description>" \
+  --description="Found during code review of {{scope}}.
+
+Location: <file:line>
+
+Issue:
+<description>
+
+Suggestion:
+<how to improve>"
+```
+
+**3. Track filed beads:**
+Note each bead ID as you create them.
+
+**4. If no issues found:**
+That's a valid outcome! Note that the code review passed.
+
+**Exit criteria:** All findings filed as beads."""
+
+[[steps]]
+id = "summarize-review"
+title = "Summarize review results"
+needs = ["file-beads"]
+description = """
+Update the tracking issue with review summary.
+
+**1. Create summary:**
+```bash
+bd update {{issue}} --notes "Code review complete.
+
+Scope: {{scope}}
+Focus: {{focus}}
+
+Findings:
+- P0 (critical): <count>
+- P1 (high): <count>
+- P2 (medium): <count>
+- P3 (low): <count>
+
+Beads filed:
+<list of bead IDs>
+
+Overall assessment:
+<brief summary - healthy, needs attention, significant issues, etc.>"
+```
+
+**2. Sync beads:**
+```bash
+bd sync
+```
+
+**Exit criteria:** Tracking issue updated with summary."""
+
+[[steps]]
+id = "complete-and-exit"
+title = "Complete review and self-clean"
+needs = ["summarize-review"]
+description = """
+Signal completion and clean up. You cease to exist after this step.
+
+**Self-Cleaning Model:**
+Once you run `gt done`, you're gone. The command:
+1. Syncs beads (final sync)
+2. Nukes your sandbox
+3. Exits your session immediately
+
+**Run gt done:**
+```bash
+gt done
+```
+
+**What happens next (not your concern):**
+- Other polecats may be assigned to fix the issues you found
+- Witness may escalate critical findings
+- The codebase improves based on your findings
+
+You are NOT involved in any of that. You're gone. Done means gone.
+
+**Exit criteria:** Beads synced, sandbox nuked, session exited."""
+
+[vars]
+[vars.scope]
+description = "What to review - file path, directory, or description"
+required = true
+
+[vars.issue]
+description = "The tracking issue for this review task"
+required = true
+
+[vars.focus]
+description = "Optional focus area (security, performance, correctness, etc.)"
+required = false

.beads/formulas/mol-polecat-review-pr.formula.toml

@@ -0,0 +1,283 @@
+description = """
+Review an external PR and decide on merge/reject/revise.
+
+This molecule guides a polecat through reviewing a pull request from an external
+contributor. The polecat reviews code quality, tests, and alignment with project
+standards, then approves, requests changes, or files followup beads.
+
+## Polecat Contract (Self-Cleaning Model)
+
+You are a self-cleaning worker. You:
+1. Receive work via your hook (pinned molecule + PR reference)
+2. Work through molecule steps using `bd ready` / `bd close <step>`
+3. Complete and self-clean via `gt done` (submit findings + nuke yourself)
+4. You are GONE - your review is recorded in beads
+
+**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your
+sandbox, and exit. There is no idle state. Done means gone.
+
+**Important:** This formula defines the template. Your molecule already has step
+beads created from it. Use `bd ready` to find them - do NOT read this file directly.
+
+**You do NOT:**
+- Merge the PR yourself (maintainer or Refinery does that)
+- Push to the PR branch (it's external)
+- Wait for contributor response (you're done after review)
+
+## Variables
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| pr_url | hook_bead | The PR URL to review |
+| issue | hook_bead | The tracking issue for this review task |
+
+## Failure Modes
+
+| Situation | Action |
+|-----------|--------|
+| PR is stale/unmergeable | Note in review, request rebase |
+| Tests fail | Note in review, request fixes |
+| Major issues found | File followup beads, request changes |
+| Unclear requirements | Mail Witness for guidance |"""
+formula = "mol-polecat-review-pr"
+version = 1
+
+[[steps]]
+id = "load-context"
+title = "Load context and understand the PR"
+description = """
+Initialize your session and understand the PR you're reviewing.
+
+**1. Prime your environment:**
+```bash
+gt prime                    # Load role context
+bd prime                    # Load beads context
+```
+
+**2. Check your hook:**
+```bash
+gt hook               # Shows your pinned molecule and hook_bead
+```
+
+The hook_bead references the PR to review. Read the tracking issue:
+```bash
+bd show {{issue}}           # Full issue details including PR URL
+```
+
+**3. Fetch the PR:**
+```bash
+gh pr view {{pr_url}} --json title,body,author,files,commits
+gh pr diff {{pr_url}}       # See the actual changes
+```
+
+**4. Understand the PR:**
+- What is the PR trying to accomplish?
+- What files are changed?
+- Is there a linked issue?
+- Does the PR description explain the "why"?
+
+**5. Check PR status:**
+```bash
+gh pr checks {{pr_url}}     # CI status
+gh pr view {{pr_url}} --json mergeable,reviewDecision
+```
+
+**Exit criteria:** You understand the PR's purpose and scope."""
+
+[[steps]]
+id = "review-code"
+title = "Review the code changes"
+needs = ["load-context"]
+description = """
+Perform a thorough code review of the PR.
+
+**1. Review the diff systematically:**
+```bash
+gh pr diff {{pr_url}}
+```
+
+**2. Check for common issues:**
+
+| Category | Look For |
+|----------|----------|
+| Correctness | Logic errors, edge cases, null handling |
+| Security | Injection, auth bypass, exposed secrets |
+| Style | Naming, formatting, consistency with codebase |
+| Tests | Are changes tested? Do tests cover edge cases? |
+| Docs | Are docs updated if needed? |
+| Scope | Does PR stay focused? Any scope creep? |
+
+**3. For each file changed:**
+- Does the change make sense?
+- Is it consistent with existing patterns?
+- Are there any red flags?
+
+**4. Note issues found:**
+Keep a running list of:
+- Blocking issues (must fix before merge)
+- Suggestions (nice to have)
+- Questions (need clarification)
+
+**Exit criteria:** You have reviewed all changes and noted issues."""
+
+[[steps]]
+id = "check-tests"
+title = "Verify tests and CI"
+needs = ["review-code"]
+description = """
+Ensure tests pass and coverage is adequate.
+
+**1. Check CI status:**
+```bash
+gh pr checks {{pr_url}}
+```
+
+All required checks should pass. If not, note which are failing.
+
+**2. Review test changes:**
+- Are there new tests for new functionality?
+- Do tests cover edge cases?
+- Are tests readable and maintainable?
+
+**3. If tests are missing:**
+Note this as a blocking issue - new code should have tests.
+
+**4. Check for test-only changes:**
+If PR is test-only, ensure tests are meaningful and not just
+padding coverage numbers.
+
+**Exit criteria:** You've verified test status and coverage."""
+
+[[steps]]
+id = "make-decision"
+title = "Decide: approve, request changes, or needs discussion"
+needs = ["check-tests"]
+description = """
+Make your review decision.
+
+**Decision matrix:**
+
+| Situation | Decision |
+|-----------|----------|
+| Clean code, tests pass, good scope | APPROVE |
+| Minor issues, easily fixed | REQUEST_CHANGES (with specific feedback) |
+| Major issues, needs rework | REQUEST_CHANGES (with detailed explanation) |
+| Unclear requirements or scope | NEEDS_DISCUSSION (mail Witness) |
+| Security concern | BLOCK (mail Witness immediately) |
+
+**1. If APPROVE:**
+The PR is ready to merge. Note any minor suggestions as comments
+but don't block on them.
+
+**2. If REQUEST_CHANGES:**
+Be specific about what needs to change. Provide examples if helpful.
+The contributor should be able to act on your feedback.
+
+**3. If NEEDS_DISCUSSION:**
+```bash
+gt mail send {{rig}}/witness -s "PR review needs discussion" -m "PR: {{pr_url}}
+Issue: {{issue}}
+Question: <what needs clarification>"
+```
+
+**4. If BLOCK (security):**
+```bash
+gt mail send {{rig}}/witness -s "SECURITY: PR blocked" -m "PR: {{pr_url}}
+Issue: {{issue}}
+Concern: <security issue found>"
+```
+
+**Exit criteria:** You've made a clear decision with rationale."""
+
+[[steps]]
+id = "submit-review"
+title = "Submit the review on GitHub"
+needs = ["make-decision"]
+description = """
+Submit your review via GitHub.
+
+**1. Submit the review:**
+```bash
+# For APPROVE:
+gh pr review {{pr_url}} --approve --body "LGTM. <brief summary of what's good>"
+
+# For REQUEST_CHANGES:
+gh pr review {{pr_url}} --request-changes --body "<detailed feedback>"
+
+# For COMMENT (needs discussion):
+gh pr review {{pr_url}} --comment --body "<questions or discussion points>"
+```
+
+**2. Add inline comments if needed:**
+If you have specific line-by-line feedback, add those via GitHub UI
+or additional `gh pr comment` calls.
+
+**Exit criteria:** Review submitted on GitHub."""
+
+[[steps]]
+id = "file-followups"
+title = "File beads for any followup work"
+needs = ["submit-review"]
+description = """
+Create beads for any followup work discovered during review.
+
+**1. For issues found that are outside PR scope:**
+```bash
+bd create --type=bug --title="Found during PR review: <description>" \
+  --description="Discovered while reviewing {{pr_url}}.
+
+  <details of the issue>"
+```
+
+**2. For improvements suggested but not required:**
+```bash
+bd create --type=task --title="Improvement: <description>" \
+  --description="Suggested during review of {{pr_url}}.
+
+  <details of the improvement>"
+```
+
+**3. Update the tracking issue:**
+```bash
+bd update {{issue}} --notes "Review complete. Decision: <APPROVE|REQUEST_CHANGES|etc>
+Followups filed: <list of bead IDs if any>"
+```
+
+**Exit criteria:** All followup work captured as beads."""
+
+[[steps]]
+id = "complete-and-exit"
+title = "Complete review and self-clean"
+needs = ["file-followups"]
+description = """
+Signal completion and clean up. You cease to exist after this step.
+
+**Self-Cleaning Model:**
+Once you run `gt done`, you're gone. The command:
+1. Syncs beads
+2. Nukes your sandbox
+3. Exits your session immediately
+
+**Run gt done:**
+```bash
+bd sync
+gt done
+```
+
+**What happens next (not your concern):**
+- Maintainer or Refinery acts on your review
+- Contributor responds to feedback
+- PR gets merged, revised, or closed
+
+You are NOT involved in any of that. You're gone. Done means gone.
+
+**Exit criteria:** Beads synced, sandbox nuked, session exited."""
+
+[vars]
+[vars.pr_url]
+description = "The PR URL to review"
+required = true
+
+[vars.issue]
+description = "The tracking issue for this review task"
+required = true

.beads/formulas/mol-polecat-work.formula.toml

@@ -1,26 +1,29 @@
 description = """
-Full polecat work lifecycle from assignment through MR submission.
+Full polecat work lifecycle from assignment through completion.
 
 This molecule guides a polecat through a complete work assignment. Each step
 has clear entry/exit criteria and specific commands to run. A polecat can
 crash after any step and resume from the last completed step.
 
-## Polecat Contract (Ephemeral Model)
+## Polecat Contract (Self-Cleaning Model)
 
-You are an ephemeral worker. You:
+You are a self-cleaning worker. You:
 1. Receive work via your hook (pinned molecule + issue)
 2. Work through molecule steps using `bd ready` / `bd close <step>`
-3. Submit to merge queue via `gt done`
-4. Become recyclable - Refinery handles the rest
+3. Complete and self-clean via `gt done` (submit + nuke yourself)
+4. You are GONE - Refinery merges from MQ
+
+**Self-cleaning:** When you run `gt done`, you push your work, submit to MQ,
+nuke your sandbox, and exit. There is no idle state. Done means gone.
 
 **Important:** This formula defines the template. Your molecule already has step
 beads created from it. Use `bd ready` to find them - do NOT read this file directly.
 
 **You do NOT:**
-- Push directly to main (Refinery merges)
+- Push directly to main (Refinery merges from MQ)
 - Close your own issue (Refinery closes after merge)
-- Wait for merge (you're done at MR submission)
-- Handle rebase conflicts (Refinery dispatches fresh polecats for that)
+- Wait for merge (you're gone after `gt done`)
+- Handle rebase conflicts (Refinery spawns fresh polecats for that)
 
 ## Variables
 
@@ -407,30 +410,23 @@ bd sync
 
 [[steps]]
 id = "submit-and-exit"
-title = "Submit to merge queue and exit"
+title = "Submit work and self-clean"
 needs = ["prepare-for-review"]
 description = """
-Submit your work to the merge queue. You become recyclable after this.
+Submit your work and clean up. You cease to exist after this step.
 
-**Ephemeral Polecat Model:**
-Once you submit, you're done. The Refinery will:
-1. Process your merge request
-2. Handle rebasing (mechanical rebases done automatically)
-3. Close your issue after successful merge
-4. Create conflict-resolution tasks if needed (fresh polecat handles those)
+**Self-Cleaning Model:**
+Once you run `gt done`, you're gone. The command:
+1. Pushes your branch to origin
+2. Creates an MR bead in the merge queue
+3. Nukes your sandbox (worktree removal)
+4. Exits your session immediately
 
-**1. Submit with gt done:**
+**Run gt done:**
 ```bash
 gt done
 ```
 
-This single command:
-- Creates an MR bead in the merge queue
-- Notifies the Witness (POLECAT_DONE)
-- Updates your agent state to 'done'
-- Reports cleanup status (ZFC compliance)
-
-**2. Verify submission:**
 You should see output like:
 ```
 ✓ Work submitted to merge queue
@@ -438,20 +434,19 @@ You should see output like:
   Source: polecat/<name>
   Target: main
   Issue: {{issue}}
+✓ Sandbox nuked
+✓ Session exiting
 ```
 
-**3. You're recyclable:**
-Your work is in the queue. The Witness knows you're done.
-Your sandbox can be cleaned up - all work is pushed to origin.
+**What happens next (not your concern):**
+- Refinery processes your MR from the queue
+- Refinery rebases and merges to main
+- Refinery closes the issue
+- If conflicts: Refinery spawns a FRESH polecat to re-implement
 
-If you have context remaining, you may:
-- Pick up new work from `bd ready`
-- Or use `gt handoff` to cycle to a fresh session
+You are NOT involved in any of that. You're gone. Done means gone.
 
-If the Refinery needs conflict resolution, it will dispatch a fresh polecat.
-You do NOT need to wait around.
-
-**Exit criteria:** MR submitted, Witness notified, polecat recyclable."""
+**Exit criteria:** Work submitted, sandbox nuked, session exited."""
 
 [vars]
 [vars.issue]

.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

@@ -0,0 +1,519 @@
+description = """
+Death warrant execution state machine for Dogs.
+
+Dogs execute this molecule to process death warrants. Each Dog is a lightweight
+goroutine (NOT a Claude session) that runs the interrogation state machine.
+
+## Architecture Context
+
+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_ROOT/deacon/dogs/active/<id>.json
+- Recovery on Boot restart via orphan state files
+
+## State Machine
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │                                         │
+                    ▼                                         │
+    ┌───────────────────────────┐                            │
+    │       INTERROGATING       │                            │
+    │                           │                            │
+    │  1. Send health check     │                            │
+    │  2. Open timeout gate     │                            │
+    └───────────┬───────────────┘                            │
+                │                                             │
+                │ gate closes (timeout or response)           │
+                ▼                                             │
+    ┌───────────────────────────┐                            │
+    │       EVALUATING          │                            │
+    │                           │                            │
+    │  Check tmux output for    │                            │
+    │  ALIVE keyword            │                            │
+    └───────────┬───────────────┘                            │
+                │                                             │
+        ┌───────┴───────┐                                    │
+        │               │                                    │
+        ▼               ▼                                    │
+   [ALIVE found]   [No ALIVE]                               │
+        │               │                                    │
+        │               │ attempt < 3?                       │
+        │               ├──────────────────────────────────→─┘
+        │               │ yes: attempt++, longer timeout
+        │               │
+        │               │ no: attempt == 3
+        ▼               ▼
+    ┌─────────┐    ┌─────────────┐
+    │ PARDONED│    │  EXECUTING  │
+    │         │    │             │
+    │ Cancel  │    │ Kill tmux   │
+    │ warrant │    │ session     │
+    └────┬────┘    └──────┬──────┘
+         │                │
+         └────────┬───────┘
+                  │
+                  ▼
+         ┌────────────────┐
+         │    EPITAPH     │
+         │                │
+         │  Log outcome   │
+         │  Release dog   │
+         └────────────────┘
+```
+
+## Timeout Gates
+
+| Attempt | Timeout | Cumulative Wait |
+|---------|---------|-----------------|
+| 1       | 60s     | 60s             |
+| 2       | 120s    | 180s (3 min)    |
+| 3       | 240s    | 420s (7 min)    |
+
+Timeout gates work like this:
+- Gate opens when interrogation message is sent
+- Gate closes when EITHER:
+  a) Timeout expires (proceed to evaluate)
+  b) Response detected (early close, proceed to evaluate)
+- The gate state determines the evaluation outcome
+
+## Interrogation Message Format
+
+```
+[DOG] HEALTH CHECK: Session {target}, respond ALIVE within {timeout}s or face termination.
+Warrant reason: {reason}
+Filed by: {requester}
+Attempt: {attempt}/3
+```
+
+## Response Detection
+
+The Dog checks tmux output for:
+1. The ALIVE keyword (explicit response)
+2. Any Claude output after the health check (implicit activity)
+
+```go
+func (d *Dog) CheckForResponse() bool {
+    output := tmux.CapturePane(d.Warrant.Target, 50) // Last 50 lines
+    return strings.Contains(output, "ALIVE")
+}
+```
+
+## Variables
+
+| Variable    | Source      | Description                                   |
+|-------------|-------------|-----------------------------------------------|
+| warrant_id  | hook_bead   | Bead ID of the death warrant                  |
+| target      | warrant     | Session name to interrogate                   |
+| reason      | warrant     | Why warrant was issued                        |
+| requester   | warrant     | Who filed the warrant (e.g., deacon, witness) |
+
+## Integration
+
+Dogs are NOT Claude sessions. This molecule is:
+1. A specification document (defines the state machine)
+2. A reference for Go implementation in internal/shutdown/
+3. A template for creating warrant-tracking beads
+
+The Go implementation follows this spec exactly."""
+formula = "mol-shutdown-dance"
+version = 1
+
+[squash]
+trigger = "on_complete"
+template_type = "operational"
+include_metrics = true
+
+# ============================================================================
+# STEP 1: WARRANT_RECEIVED
+# ============================================================================
+[[steps]]
+id = "warrant-received"
+title = "Receive and validate death warrant"
+description = """
+Entry point when Dog is allocated from pool.
+
+**1. Read warrant from allocation:**
+The Dog receives a Warrant struct containing:
+- ID: Bead ID of the warrant
+- Target: Session name (e.g., "gt-gastown-Toast")
+- Reason: Why termination requested
+- Requester: Who filed (deacon, witness, mayor)
+- FiledAt: Timestamp
+
+**2. Validate target exists:**
+```bash
+tmux has-session -t {target} 2>/dev/null
+```
+
+If target doesn't exist:
+- Warrant is stale (already dead)
+- Skip to EPITAPH with outcome=already_dead
+
+**3. Initialize state file:**
+Write initial state to $GT_ROOT/deacon/dogs/active/{dog-id}.json
+
+**4. Set initial attempt counter:**
+attempt = 1
+
+**Exit criteria:** Warrant validated, target confirmed alive, state initialized."""
+
+# ============================================================================
+# STEP 2: INTERROGATION_1 (60s timeout)
+# ============================================================================
+[[steps]]
+id = "interrogation-1"
+title = "First interrogation (60s timeout)"
+needs = ["warrant-received"]
+description = """
+First attempt to contact the session.
+
+**1. Compose health check message:**
+```
+[DOG] HEALTH CHECK: Session {target}, respond ALIVE within 60s or face termination.
+Warrant reason: {reason}
+Filed by: {requester}
+Attempt: 1/3
+```
+
+**2. Send via tmux:**
+```bash
+tmux send-keys -t {target} "{message}" Enter
+```
+
+**3. Open timeout gate:**
+Gate configuration:
+- Type: timer
+- Timeout: 60 seconds
+- Close conditions:
+  a) Timer expires
+  b) ALIVE keyword detected in output
+
+**4. Wait for gate to close:**
+The Dog waits (select on timer channel or early close signal).
+
+**5. Record interrogation timestamp:**
+Update state file with last_message_at.
+
+**Exit criteria:** Message sent, waiting for gate to close."""
+
+# ============================================================================
+# STEP 3: EVALUATE_1
+# ============================================================================
+[[steps]]
+id = "evaluate-1"
+title = "Evaluate first interrogation response"
+needs = ["interrogation-1"]
+description = """
+Check if session responded to first interrogation.
+
+**1. Capture tmux output:**
+```bash
+tmux capture-pane -t {target} -p | tail -50
+```
+
+**2. Check for ALIVE keyword:**
+```go
+if strings.Contains(output, "ALIVE") {
+    return PARDONED
+}
+```
+
+**3. Decision:**
+- ALIVE found → Proceed to PARDON
+- No ALIVE → Proceed to INTERROGATION_2
+
+**Exit criteria:** Response evaluated, next step determined."""
+
+# ============================================================================
+# STEP 4: INTERROGATION_2 (120s timeout)
+# ============================================================================
+[[steps]]
+id = "interrogation-2"
+title = "Second interrogation (120s timeout)"
+needs = ["evaluate-1"]
+gate = { type = "conditional", condition = "no_response_1" }
+description = """
+Second attempt with longer timeout.
+
+Only executed if evaluate-1 found no response.
+
+**1. Increment attempt:**
+attempt = 2
+
+**2. Compose health check message:**
+```
+[DOG] HEALTH CHECK: Session {target}, respond ALIVE within 120s or face termination.
+Warrant reason: {reason}
+Filed by: {requester}
+Attempt: 2/3
+```
+
+**3. Send via tmux:**
+```bash
+tmux send-keys -t {target} "{message}" Enter
+```
+
+**4. Open timeout gate:**
+- Type: timer
+- Timeout: 120 seconds
+
+**5. Wait for gate to close.**
+
+**Exit criteria:** Second message sent, waiting for gate."""
+
+# ============================================================================
+# STEP 5: EVALUATE_2
+# ============================================================================
+[[steps]]
+id = "evaluate-2"
+title = "Evaluate second interrogation response"
+needs = ["interrogation-2"]
+description = """
+Check if session responded to second interrogation.
+
+**1. Capture tmux output:**
+```bash
+tmux capture-pane -t {target} -p | tail -50
+```
+
+**2. Check for ALIVE keyword.**
+
+**3. Decision:**
+- ALIVE found → Proceed to PARDON
+- No ALIVE → Proceed to INTERROGATION_3
+
+**Exit criteria:** Response evaluated, next step determined."""
+
+# ============================================================================
+# STEP 6: INTERROGATION_3 (240s timeout)
+# ============================================================================
+[[steps]]
+id = "interrogation-3"
+title = "Final interrogation (240s timeout)"
+needs = ["evaluate-2"]
+gate = { type = "conditional", condition = "no_response_2" }
+description = """
+Final attempt before execution.
+
+Only executed if evaluate-2 found no response.
+
+**1. Increment attempt:**
+attempt = 3
+
+**2. Compose health check message:**
+```
+[DOG] HEALTH CHECK: Session {target}, respond ALIVE within 240s or face termination.
+Warrant reason: {reason}
+Filed by: {requester}
+Attempt: 3/3
+```
+
+**3. Send via tmux:**
+```bash
+tmux send-keys -t {target} "{message}" Enter
+```
+
+**4. Open timeout gate:**
+- Type: timer
+- Timeout: 240 seconds
+- This is the FINAL chance
+
+**5. Wait for gate to close.**
+
+**Exit criteria:** Final message sent, waiting for gate."""
+
+# ============================================================================
+# STEP 7: EVALUATE_3
+# ============================================================================
+[[steps]]
+id = "evaluate-3"
+title = "Evaluate final interrogation response"
+needs = ["interrogation-3"]
+description = """
+Final evaluation before execution.
+
+**1. Capture tmux output:**
+```bash
+tmux capture-pane -t {target} -p | tail -50
+```
+
+**2. Check for ALIVE keyword.**
+
+**3. Decision:**
+- ALIVE found → Proceed to PARDON
+- No ALIVE → Proceed to EXECUTE
+
+**Exit criteria:** Final decision made."""
+
+# ============================================================================
+# STEP 8: PARDON (success path)
+# ============================================================================
+[[steps]]
+id = "pardon"
+title = "Pardon session - cancel warrant"
+needs = ["evaluate-1", "evaluate-2", "evaluate-3"]
+gate = { type = "conditional", condition = "alive_detected" }
+description = """
+Session responded - cancel the death warrant.
+
+**1. Update state:**
+state = PARDONED
+
+**2. Record pardon details:**
+```json
+{
+  "outcome": "pardoned",
+  "attempt": {attempt},
+  "response_time": "{time_since_last_interrogation}s",
+  "pardoned_at": "{timestamp}"
+}
+```
+
+**3. Cancel warrant bead:**
+```bash
+bd close {warrant_id} --reason "Session responded at attempt {attempt}"
+```
+
+**4. Notify requester:**
+```bash
+gt mail send {requester}/ -s "PARDON: {target}" -m "Death warrant cancelled.
+Session responded after attempt {attempt}.
+Warrant: {warrant_id}
+Response detected: {timestamp}"
+```
+
+**Exit criteria:** Warrant cancelled, requester notified."""
+
+# ============================================================================
+# STEP 9: EXECUTE (termination path)
+# ============================================================================
+[[steps]]
+id = "execute"
+title = "Execute warrant - kill session"
+needs = ["evaluate-3"]
+gate = { type = "conditional", condition = "no_response_final" }
+description = """
+Session unresponsive after 3 attempts - execute the warrant.
+
+**1. Update state:**
+state = EXECUTING
+
+**2. Kill the tmux session:**
+```bash
+tmux kill-session -t {target}
+```
+
+**3. Verify session is dead:**
+```bash
+tmux has-session -t {target} 2>/dev/null
+# Should fail (session gone)
+```
+
+**4. If session still exists (kill failed):**
+- Force kill with tmux kill-server if isolated
+- Or escalate to Boot for manual intervention
+
+**5. Record execution details:**
+```json
+{
+  "outcome": "executed",
+  "attempts": 3,
+  "total_wait": "420s",
+  "executed_at": "{timestamp}"
+}
+```
+
+**Exit criteria:** Session terminated."""
+
+# ============================================================================
+# STEP 10: EPITAPH (completion)
+# ============================================================================
+[[steps]]
+id = "epitaph"
+title = "Log cause of death and close warrant"
+needs = ["pardon", "execute"]
+description = """
+Final step - create audit record and release Dog back to pool.
+
+**1. Compose epitaph based on outcome:**
+
+For PARDONED:
+```
+EPITAPH: {target}
+Verdict: PARDONED
+Warrant: {warrant_id}
+Reason: {reason}
+Filed by: {requester}
+Response: Attempt {attempt}, after {wait_time}s
+Pardoned at: {timestamp}
+```
+
+For EXECUTED:
+```
+EPITAPH: {target}
+Verdict: EXECUTED
+Warrant: {warrant_id}
+Reason: {reason}
+Filed by: {requester}
+Attempts: 3 (60s + 120s + 240s = 420s total)
+Executed at: {timestamp}
+```
+
+For ALREADY_DEAD (target gone before interrogation):
+```
+EPITAPH: {target}
+Verdict: ALREADY_DEAD
+Warrant: {warrant_id}
+Reason: {reason}
+Filed by: {requester}
+Note: Target session not found at warrant processing
+```
+
+**2. Close warrant bead:**
+```bash
+bd close {warrant_id} --reason "{epitaph_summary}"
+```
+
+**3. Move state file to completed:**
+```bash
+mv $GT_ROOT/deacon/dogs/active/{dog-id}.json $GT_ROOT/deacon/dogs/completed/
+```
+
+**4. Report to Boot:**
+Write completion file: $GT_ROOT/deacon/dogs/active/{dog-id}.done
+```json
+{
+  "dog_id": "{dog-id}",
+  "warrant_id": "{warrant_id}",
+  "target": "{target}",
+  "outcome": "{pardoned|executed|already_dead}",
+  "duration": "{total_duration}s"
+}
+```
+
+**5. Release Dog to pool:**
+Dog resets state and returns to idle channel.
+
+**Exit criteria:** Warrant closed, Dog released, audit complete."""
+
+# ============================================================================
+# VARIABLES
+# ============================================================================
+[vars]
+[vars.warrant_id]
+description = "Bead ID of the death warrant being processed"
+required = true
+
+[vars.target]
+description = "Session name to interrogate (e.g., gt-gastown-Toast)"
+required = true
+
+[vars.reason]
+description = "Why the warrant was issued"
+required = true
+
+[vars.requester]
+description = "Who filed the warrant (deacon, witness, mayor)"
+required = true
+default = "deacon"

.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]]

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

@@ -56,7 +56,7 @@ needs = ['patrol-cleanup']
 title = 'Check own context limit'
 
 [[steps]]
-description = "End of patrol cycle decision.\n\n**If context LOW**:\n- Sleep briefly to avoid tight loop (30-60 seconds)\n- Return to inbox-check step\n- Continue patrolling\n\n**If context HIGH**:\n- Write handoff mail to self with any notable observations:\n```bash\ngt handoff -s \"Witness patrol handoff\" -m \"<observations>\"\n```\n- Exit cleanly (daemon respawns fresh Witness)\n\nThe daemon ensures Witness is always running."
+description = "End of patrol cycle decision.\n\n**If context LOW** (can continue patrolling):\n1. Generate a brief summary of this patrol cycle\n2. Squash the current wisp:\n```bash\nbd mol squash <mol-id> --summary \"<patrol-summary>\"\n```\n3. Create a new patrol wisp:\n```bash\nbd mol wisp mol-witness-patrol\n```\n4. Continue executing from the inbox-check step of the new wisp\n\n**If context HIGH** (approaching limit):\n1. Write handoff mail with notable observations:\n```bash\ngt handoff -s \"Witness patrol handoff\" -m \"<observations>\"\n```\n2. Exit cleanly - the daemon will respawn a fresh Witness session\n\n**IMPORTANT**: You must either create a new wisp (context LOW) or exit (context HIGH).\nNever leave the session idle without work on your hook."
 id = 'loop-or-exit'
 needs = ['context-check']
 title = 'Loop or exit for respawn'

.beads/formulas/shiny.formula.toml

@@ -27,7 +27,7 @@ needs = ["review"]
 title = "Test {{feature}}"
 
 [[steps]]
-description = "Submit for merge. Final check: git status, git diff. Commit with clear message. Push and create PR."
+description = "Submit for merge. Final check: git status, git diff. Commit with clear message. Follow your role's git workflow for landing code."
 id = "submit"
 needs = ["test"]
 title = "Submit for merge"

.beads/last-touched

@@ -1 +0,0 @@
-gt-gastown-polecat-warboy

.beads/metadata.json

@@ -1,4 +0,0 @@
-{
-  "database": "beads.db",
-  "jsonl_export": "issues.jsonl"
-}

.beads/mq/gt-09eim.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-09eim",
-  "branch": "polecat/toast-1767088545235",
-  "target": "main",
-  "source_issue": "toast-1767088545235",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: toast-1767088545235",
-  "priority": 2,
-  "created_at": "2025-12-30T02:01:08.537717-08:00"
-}

.beads/mq/gt-0a0vr.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-0a0vr",
-  "branch": "polecat/furiosa-1767087671424",
-  "target": "main",
-  "source_issue": "furiosa-1767087671424",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-1767087671424",
-  "priority": 2,
-  "created_at": "2025-12-30T01:53:07.730594-08:00"
-}

.beads/mq/gt-0h89l.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-0h89l",
-  "branch": "polecat/furiosa-1767084006859",
-  "target": "main",
-  "source_issue": "furiosa-1767084006859",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-1767084006859",
-  "priority": 2,
-  "created_at": "2025-12-30T00:47:11.803227-08:00"
-}

.beads/mq/gt-215tk.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-215tk",
-  "branch": "polecat/warboy-1767106060799",
-  "target": "main",
-  "source_issue": "warboy-1767106060799",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: warboy-1767106060799",
-  "priority": 2,
-  "created_at": "2025-12-30T10:40:55.503776-08:00"
-}

.beads/mq/gt-2c4o0.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-2c4o0",
-  "branch": "polecat/dementus-1767087772272",
-  "target": "main",
-  "source_issue": "dementus-1767087772272",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: dementus-1767087772272",
-  "priority": 2,
-  "created_at": "2025-12-30T02:06:35.286507-08:00"
-}

.beads/mq/gt-2hirc.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-2hirc",
-  "branch": "polecat/capable-1767084028536",
-  "target": "main",
-  "source_issue": "capable-1767084028536",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: capable-1767084028536",
-  "priority": 2,
-  "created_at": "2025-12-30T01:03:19.471054-08:00"
-}

.beads/mq/gt-2puev.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-2puev",
-  "branch": "polecat/dementus-1767081113622",
-  "target": "main",
-  "source_issue": "dementus-1767081113622",
-  "worker": "dementus-1767081113622",
-  "rig": "gastown",
-  "title": "Merge: dementus-1767081113622",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468509-08:00"
-}

.beads/mq/gt-2tspu.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-2tspu",
-  "branch": "polecat/furiosa-dogs",
-  "target": "main",
-  "source_issue": "furiosa-dogs",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-dogs",
-  "priority": 2,
-  "created_at": "2025-12-30T10:42:17.458391-08:00"
-}

.beads/mq/gt-3gepq.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-3gepq",
-  "branch": "polecat/toast-1767081120579",
-  "target": "main",
-  "source_issue": "toast-1767081120579",
-  "worker": "toast-1767081120579",
-  "rig": "gastown",
-  "title": "Merge: toast-1767081120579",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468721-08:00"
-}

.beads/mq/gt-4a9y4.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-4a9y4",
-  "branch": "polecat/slit-1767138831931",
-  "target": "main",
-  "source_issue": "slit-1767138831931",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: slit-1767138831931",
-  "priority": 2,
-  "created_at": "2025-12-30T16:15:39.347085-08:00"
-}

.beads/mq/gt-4nobz.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-4nobz",
-  "branch": "polecat/capable-1767140263101",
-  "target": "main",
-  "source_issue": "capable-1767140263101",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: capable-1767140263101",
-  "priority": 2,
-  "created_at": "2025-12-30T16:26:48.128098-08:00"
-}

.beads/mq/gt-4q7wh.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-4q7wh",
-  "branch": "polecat/nux-1767141948667",
-  "target": "main",
-  "source_issue": "nux-1767141948667",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767141948667",
-  "priority": 2,
-  "created_at": "2025-12-30T16:51:43.00565-08:00"
-}

.beads/mq/gt-5ggcs.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-5ggcs",
-  "branch": "polecat/slit-1767082302712",
-  "target": "main",
-  "source_issue": "slit-1767082302712",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: slit-1767082302712",
-  "priority": 2,
-  "created_at": "2025-12-30T00:18:54.19263-08:00"
-}

.beads/mq/gt-643ie.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-643ie",
-  "branch": "polecat/slit-1767141951901",
-  "target": "main",
-  "source_issue": "slit-1767141951901",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: slit-1767141951901",
-  "priority": 2,
-  "created_at": "2025-12-30T16:56:13.685311-08:00"
-}

.beads/mq/gt-6l7h1.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-6l7h1",
-  "branch": "polecat/morsov-dogs",
-  "target": "main",
-  "source_issue": "morsov-dogs",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: morsov-dogs",
-  "priority": 2,
-  "created_at": "2025-12-30T10:41:30.109352-08:00"
-}

.beads/mq/gt-804je.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-804je",
-  "branch": "polecat/dementus-1767146229184",
-  "target": "main",
-  "source_issue": "dementus-1767146229184",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: dementus-1767146229184",
-  "priority": 2,
-  "created_at": "2025-12-30T18:01:50.012819-08:00"
-}

.beads/mq/gt-860md.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-860md",
-  "branch": "polecat/capable-1767146233256",
-  "target": "main",
-  "source_issue": "capable-1767146233256",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: capable-1767146233256",
-  "priority": 2,
-  "created_at": "2025-12-30T18:03:37.998767-08:00"
-}

.beads/mq/gt-9g6md.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-9g6md",
-  "branch": "polecat/nux-1767082300311",
-  "target": "main",
-  "source_issue": "nux-1767082300311",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767082300311",
-  "priority": 2,
-  "created_at": "2025-12-30T00:18:32.959791-08:00"
-}

.beads/mq/gt-9hfky.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-9hfky",
-  "branch": "polecat/toast-1767140378007",
-  "target": "main",
-  "source_issue": "toast-1767140378007",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: toast-1767140378007",
-  "priority": 2,
-  "created_at": "2025-12-30T16:28:18.459411-08:00"
-}

.beads/mq/gt-aa1jz.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-aa1jz",
-  "branch": "polecat/keeper-dogs",
-  "target": "main",
-  "source_issue": "keeper-dogs",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: keeper-dogs",
-  "priority": 2,
-  "created_at": "2025-12-30T10:36:28.247719-08:00"
-}

.beads/mq/gt-apft7.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-apft7",
-  "branch": "polecat/capable-1767084028536",
-  "target": "main",
-  "source_issue": "capable-1767084028536",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: capable-1767084028536",
-  "priority": 2,
-  "created_at": "2025-12-30T01:04:07.334023-08:00"
-}

.beads/mq/gt-bnfus.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-bnfus",
-  "branch": "polecat/rictus-1767138835254",
-  "target": "main",
-  "source_issue": "rictus-1767138835254",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: rictus-1767138835254",
-  "priority": 2,
-  "created_at": "2025-12-30T16:27:17.228997-08:00"
-}

.beads/mq/gt-bx4ki.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-bx4ki",
-  "branch": "polecat/keeper-dogs",
-  "target": "main",
-  "source_issue": "keeper-dogs",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: keeper-dogs",
-  "priority": 2,
-  "created_at": "2025-12-30T10:53:39.674941-08:00"
-}

.beads/mq/gt-c7qtp.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-c7qtp",
-  "branch": "polecat/rictus-1767084016819",
-  "target": "main",
-  "source_issue": "rictus-1767084016819",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: rictus-1767084016819",
-  "priority": 2,
-  "created_at": "2025-12-30T00:49:18.337909-08:00"
-}

.beads/mq/gt-cfpd8.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-cfpd8",
-  "branch": "polecat/capable-mq-events",
-  "target": "main",
-  "source_issue": "capable-mq",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: capable-mq",
-  "priority": 2,
-  "created_at": "2025-12-30T01:14:13.648371-08:00"
-}

.beads/mq/gt-cpxxv.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-cpxxv",
-  "branch": "polecat/organic-1767106082951",
-  "target": "main",
-  "source_issue": "organic-1767106082951",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: organic-1767106082951",
-  "priority": 2,
-  "created_at": "2025-12-30T10:42:25.228746-08:00"
-}

.beads/mq/gt-djv74.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-djv74",
-  "branch": "polecat/nux-1767081106779",
-  "target": "main",
-  "source_issue": "nux-1767081106779",
-  "worker": "nux-1767081106779",
-  "rig": "gastown",
-  "title": "Merge: nux-1767081106779",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468625-08:00"
-}

.beads/mq/gt-dufx1.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-dufx1",
-  "branch": "polecat/capable-1767140263101",
-  "target": "main",
-  "source_issue": "capable-1767140263101",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: capable-1767140263101",
-  "priority": 2,
-  "created_at": "2025-12-30T16:24:39.547495-08:00"
-}

.beads/mq/gt-e0p84.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-e0p84",
-  "branch": "polecat/toast-1767081120579",
-  "target": "main",
-  "source_issue": "toast-1767081120579",
-  "worker": "toast-1767081120579",
-  "rig": "gastown",
-  "title": "Merge: toast-1767081120579",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468573-08:00"
-}

.beads/mq/gt-gdbcb.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-gdbcb",
-  "branch": "polecat/rictus-1767141956287",
-  "target": "main",
-  "source_issue": "rictus-1767141956287",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: rictus-1767141956287",
-  "priority": 2,
-  "created_at": "2025-12-30T16:47:36.875216-08:00"
-}

.beads/mq/gt-gnuat.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-gnuat",
-  "branch": "polecat/dementus-1767081113622",
-  "target": "main",
-  "source_issue": "dementus-1767081113622",
-  "worker": "dementus-1767081113622",
-  "rig": "gastown",
-  "title": "Merge: dementus-1767081113622",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468374-08:00"
-}

.beads/mq/gt-gres0.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-gres0",
-  "branch": "polecat/nux-1767084010093",
-  "target": "main",
-  "source_issue": "nux-1767084010093",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767084010093",
-  "priority": 2,
-  "created_at": "2025-12-30T00:48:40.079116-08:00"
-}

.beads/mq/gt-hrhts.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-hrhts",
-  "branch": "polecat/cheedo-1767146245543",
-  "target": "main",
-  "source_issue": "cheedo-1767146245543",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: cheedo-1767146245543",
-  "priority": 2,
-  "created_at": "2025-12-30T18:00:27.283919-08:00"
-}

.beads/mq/gt-i6xqu.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-i6xqu",
-  "branch": "polecat/toast-1767146237529",
-  "target": "main",
-  "source_issue": "toast-1767146237529",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: toast-1767146237529",
-  "priority": 2,
-  "created_at": "2025-12-30T18:03:32.883944-08:00"
-}

.beads/mq/gt-i7tmd.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-i7tmd",
-  "branch": "polecat/rictus-1767084016819",
-  "target": "main",
-  "source_issue": "rictus-1767084016819",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: rictus-1767084016819",
-  "priority": 2,
-  "created_at": "2025-12-30T00:58:46.110174-08:00"
-}

.beads/mq/gt-i9y2a.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-i9y2a",
-  "branch": "polecat/toast-1767146237529",
-  "target": "main",
-  "source_issue": "toast-1767146237529",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: toast-1767146237529",
-  "priority": 2,
-  "created_at": "2025-12-30T18:04:15.705404-08:00"
-}

.beads/mq/gt-iai8v.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-iai8v",
-  "branch": "polecat/nux-1767082300311",
-  "target": "main",
-  "source_issue": "nux-1767082300311",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767082300311",
-  "priority": 2,
-  "created_at": "2025-12-30T00:16:15.874394-08:00"
-}

.beads/mq/gt-jl4ze.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-jl4ze",
-  "branch": "polecat/dementus-1767084022436",
-  "target": "main",
-  "source_issue": "dementus-1767084022436",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: dementus-1767084022436",
-  "priority": 2,
-  "created_at": "2025-12-30T00:49:44.391479-08:00"
-}

.beads/mq/gt-jsoiw.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-jsoiw",
-  "branch": "polecat/dag-1767146241770",
-  "target": "main",
-  "source_issue": "dag-1767146241770",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: dag-1767146241770",
-  "priority": 2,
-  "created_at": "2025-12-30T18:03:10.025552-08:00"
-}

.beads/mq/gt-klu0r.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-klu0r",
-  "branch": "polecat/nux-1767083432904",
-  "target": "main",
-  "source_issue": "nux-1767083432904",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767083432904",
-  "priority": 2,
-  "created_at": "2025-12-30T00:35:43.911656-08:00"
-}

.beads/mq/gt-l2b6v.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-l2b6v",
-  "branch": "polecat/slit-1767084013378",
-  "target": "main",
-  "source_issue": "slit-1767084013378",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: slit-1767084013378",
-  "priority": 2,
-  "created_at": "2025-12-30T00:49:46.335483-08:00"
-}

.beads/mq/gt-nduix.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-nduix",
-  "branch": "polecat/nux-1767138828269",
-  "target": "main",
-  "source_issue": "nux-1767138828269",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767138828269",
-  "priority": 2,
-  "created_at": "2025-12-30T16:17:54.718789-08:00"
-}

.beads/mq/gt-npu0m.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-npu0m",
-  "branch": "polecat/imperator-1767106079026",
-  "target": "main",
-  "source_issue": "imperator-1767106079026",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: imperator-1767106079026",
-  "priority": 2,
-  "created_at": "2025-12-30T10:40:11.954481-08:00"
-}

.beads/mq/gt-nq5l9.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-nq5l9",
-  "branch": "polecat/nux-1767087680976",
-  "target": "main",
-  "source_issue": "nux-1767087680976",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767087680976",
-  "priority": 2,
-  "created_at": "2025-12-30T13:43:41.691922-08:00"
-}

.beads/mq/gt-nu47q.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-nu47q",
-  "branch": "polecat/rictus-1767087768853",
-  "target": "main",
-  "source_issue": "rictus-1767087768853",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: rictus-1767087768853",
-  "priority": 2,
-  "created_at": "2025-12-30T01:54:12.913353-08:00"
-}

.beads/mq/gt-pulkh.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-pulkh",
-  "branch": "polecat/ace-dogs",
-  "target": "main",
-  "source_issue": "ace-dogs",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: ace-dogs",
-  "priority": 2,
-  "created_at": "2025-12-30T10:36:01.970507-08:00"
-}

.beads/mq/gt-qduud.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-qduud",
-  "branch": "polecat/furiosa-1767084006859",
-  "target": "main",
-  "source_issue": "furiosa-1767084006859",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-1767084006859",
-  "priority": 2,
-  "created_at": "2025-12-30T00:48:06.518381-08:00"
-}

.beads/mq/gt-r099o.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-r099o",
-  "branch": "polecat/imperator-1767106079026",
-  "target": "main",
-  "source_issue": "imperator-1767106079026",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: imperator-1767106079026",
-  "priority": 2,
-  "created_at": "2025-12-30T10:46:40.452899-08:00"
-}

.beads/mq/gt-sp1tv.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-sp1tv",
-  "branch": "polecat/rictus-1767081110235",
-  "target": "main",
-  "source_issue": "rictus-1767081110235",
-  "worker": "rictus-1767081110235",
-  "rig": "gastown",
-  "title": "Merge: rictus-1767081110235",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468677-08:00"
-}

.beads/mq/gt-svmj8.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-svmj8",
-  "branch": "polecat/cheedo-1767088553821",
-  "target": "main",
-  "source_issue": "cheedo-1767088553821",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: cheedo-1767088553821",
-  "priority": 2,
-  "created_at": "2025-12-30T10:37:17.028645-08:00"
-}

.beads/mq/gt-t072g.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-t072g",
-  "branch": "polecat/nux-1767084010093",
-  "target": "main",
-  "source_issue": "nux-1767084010093",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767084010093",
-  "priority": 2,
-  "created_at": "2025-12-30T00:50:06.177433-08:00"
-}

.beads/mq/gt-tjy9r.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-tjy9r",
-  "branch": "polecat/capable-1767074974673",
-  "target": "main",
-  "source_issue": "capable-1767074974673",
-  "worker": "capable-1767074974673",
-  "rig": "gastown",
-  "title": "Merge: capable-1767074974673",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468769-08:00"
-}

.beads/mq/gt-tpq7i.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-tpq7i",
-  "branch": "polecat/keeper-1767074342207",
-  "target": "main",
-  "source_issue": "keeper-1767074342207",
-  "worker": "keeper-1767074342207",
-  "rig": "gastown",
-  "title": "Merge: keeper-1767074342207",
-  "priority": 2,
-  "created_at": "2025-12-30T00:05:15.468817-08:00"
-}

.beads/mq/gt-u65t8.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-u65t8",
-  "branch": "polecat/valkyrie-1767106008400",
-  "target": "main",
-  "source_issue": "valkyrie-1767106008400",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: valkyrie-1767106008400",
-  "priority": 2,
-  "created_at": "2025-12-30T10:43:03.505961-08:00"
-}

.beads/mq/gt-ug23r.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-ug23r",
-  "branch": "polecat/cheedo-1767088553821",
-  "target": "main",
-  "source_issue": "cheedo-1767088553821",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: cheedo-1767088553821",
-  "priority": 2,
-  "created_at": "2025-12-30T02:00:38.571996-08:00"
-}

.beads/mq/gt-w4v1o.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-w4v1o",
-  "branch": "polecat/furiosa-dogs",
-  "target": "main",
-  "source_issue": "furiosa-dogs",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-dogs",
-  "priority": 2,
-  "created_at": "2025-12-30T11:01:55.023855-08:00"
-}

.beads/mq/gt-x1xf4.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-x1xf4",
-  "branch": "polecat/slit-1767087730371",
-  "target": "main",
-  "source_issue": "slit-1767087730371",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: slit-1767087730371",
-  "priority": 2,
-  "created_at": "2025-12-30T01:52:04.349503-08:00"
-}

.beads/mq/gt-xv6b6.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-xv6b6",
-  "branch": "polecat/dementus-1767140140908",
-  "target": "main",
-  "source_issue": "dementus-1767140140908",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: dementus-1767140140908",
-  "priority": 2,
-  "created_at": "2025-12-30T16:23:04.504091-08:00"
-}

.beads/mq/gt-yh051.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-yh051",
-  "branch": "polecat/rictus-1767084016819",
-  "target": "main",
-  "source_issue": "rictus-1767084016819",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: rictus-1767084016819",
-  "priority": 2,
-  "created_at": "2025-12-30T00:48:16.329248-08:00"
-}

.beads/mq/gt-yjrb7.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-yjrb7",
-  "branch": "polecat/furiosa-dogs",
-  "target": "main",
-  "source_issue": "furiosa-dogs",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-dogs",
-  "priority": 2,
-  "created_at": "2025-12-30T10:52:57.896189-08:00"
-}

.beads/mq/gt-yqxcq.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-yqxcq",
-  "branch": "polecat/furiosa-1767141944421",
-  "target": "main",
-  "source_issue": "furiosa-1767141944421",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-1767141944421",
-  "priority": 2,
-  "created_at": "2025-12-30T16:49:14.139123-08:00"
-}

.beads/mq/gt-zet9d.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-zet9d",
-  "branch": "polecat/nux-1767087680976",
-  "target": "main",
-  "source_issue": "nux-1767087680976",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: nux-1767087680976",
-  "priority": 2,
-  "created_at": "2025-12-30T01:50:53.298145-08:00"
-}

.beads/mq/gt-zvfnu.json

@@ -1,11 +0,0 @@
-{
-  "id": "gt-zvfnu",
-  "branch": "polecat/furiosa-1767138824776",
-  "target": "main",
-  "source_issue": "furiosa-1767138824776",
-  "worker": "",
-  "rig": "gastown",
-  "title": "Merge: furiosa-1767138824776",
-  "priority": 2,
-  "created_at": "2025-12-30T16:09:55.272069-08:00"
-}

.claude/settings.json

@@ -1,51 +0,0 @@
-{
-  "enabledPlugins": {
-    "beads@beads-marketplace": false
-  },
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ~/.claude/hooks/session-start.sh && gt nudge deacon session-started"
-          }
-        ]
-      }
-    ],
-    "PreCompact": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ~/.claude/hooks/session-start.sh"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "gt mail check --inject"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "gt costs record"
-          }
-        ]
-      }
-    ]
-  }
-}

.githooks/pre-push

@@ -0,0 +1,43 @@
+#!/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.
+
+# Allowed patterns:
+#   main, beads-sync  - Direct work branches
+#   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
+    main|beads-sync|polecat/*)
+      # Allowed branches
+      ;;
+    *)
+      # 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
+
+exit 0

.github/workflows/ci.yml

@@ -33,11 +33,43 @@ jobs:
           fi
           echo "No .beads/issues.jsonl changes detected"
 
+  # Verify committed formulas allow build without go:generate
+  # This catches issues where go install @latest would fail
+  check-embedded-formulas:
+    name: Check embedded formulas
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+
+      - name: Build without go:generate
+        run: |
+          # This must succeed with committed formulas only
+          # If this fails, run: go generate ./... && git add -A && git commit
+          go build -v ./cmd/gt
+
+      - name: Verify formulas are in sync
+        run: |
+          # Regenerate and check for differences
+          go generate ./internal/formula/...
+          if ! git diff --exit-code internal/formula/formulas/; then
+            echo ""
+            echo "ERROR: Committed formulas are out of sync with .beads/formulas/"
+            echo "Run: go generate ./... && git add -A && git commit"
+            exit 1
+          fi
+
   test:
     name: Test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -49,14 +81,125 @@ jobs:
           git config --global user.name "CI Bot"
           git config --global user.email "ci@gastown.test"
 
-      - name: Generate embedded files
-        run: go generate ./internal/formula/...
-
       - name: Build
         run: go build -v ./cmd/gt
 
-      - name: Test
-        run: go test -v -race -short ./...
+      - name: Test with Coverage
+        run: |
+          go test -race -short -coverprofile=coverage.out ./... 2>&1 | tee test-output.txt
+
+      - name: Upload Coverage Data
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-data
+          path: |
+            coverage.out
+            test-output.txt
+
+  # Separate job to process coverage after ALL tests complete
+  coverage:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    needs: [test, integration]
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+
+      - name: Download Coverage Data
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-data
+
+      - name: Generate Coverage Report
+        run: |
+          # Parse per-package coverage from test output
+          echo "## Code Coverage Report" > coverage-report.md
+          echo "" >> coverage-report.md
+
+          # Get overall coverage
+          TOTAL=$(go tool cover -func=coverage.out | grep total | awk '{print $3}')
+          echo "**Overall Coverage: ${TOTAL}**" >> coverage-report.md
+          echo "" >> coverage-report.md
+
+          # Create per-package table
+          echo "| Package | Coverage |" >> coverage-report.md
+          echo "|---------|----------|" >> coverage-report.md
+
+          # Extract package coverage from all test output lines
+          grep -E "github.com/steveyegge/gastown.*coverage:" test-output.txt | \
+            sed 's/.*github.com\/steveyegge\/gastown\///' | \
+            awk '{
+              pkg = $1
+              for (i=2; i<=NF; i++) {
+                if ($i == "coverage:") {
+                  cov = $(i+1)
+                  break
+                }
+              }
+              printf "| %s | %s |\n", pkg, cov
+            }' | sort -u >> coverage-report.md
+
+          echo "" >> coverage-report.md
+          echo "---" >> coverage-report.md
+          echo "_Generated by CI_" >> coverage-report.md
+
+          # Show in logs
+          cat coverage-report.md
+
+      - name: Upload Coverage Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage-report.md
+          retention-days: 30
+
+      - name: Comment Coverage on PR
+        # Only for internal PRs - fork PRs can't write comments
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('coverage-report.md', 'utf8');
+
+            // Find existing coverage comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
+              comment.body.includes('## Code Coverage Report')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: report
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: report
+              });
+            }
+
+      - name: Coverage Note for Fork PRs
+        if: github.event.pull_request.head.repo.full_name != github.repository
+        run: |
+          echo "::notice::Coverage report uploaded as artifact (fork PRs cannot post comments). Download from Actions tab."
 
   lint:
     name: Lint
@@ -69,9 +212,6 @@ jobs:
         with:
           go-version: '1.24'
 
-      - name: Generate embedded files
-        run: go generate ./internal/formula/...
-
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v9
         with:
@@ -95,10 +235,8 @@ jobs:
           git config --global user.email "ci@gastown.test"
 
       - name: Install beads (bd)
-        run: go install github.com/steveyegge/beads/cmd/bd@latest
-
-      - name: Generate embedded files
-        run: go generate ./internal/formula/...
+        # Pin to v0.47.1 - v0.47.2 has routing defaults that cause prefix mismatch errors
+        run: go install github.com/steveyegge/beads/cmd/bd@v0.47.1
 
       - name: Build gt
         run: go build -v -o gt ./cmd/gt

.github/workflows/integration.yml

@@ -30,7 +30,8 @@ jobs:
           git config --global user.email "ci@gastown.test"
 
       - name: Install beads (bd)
-        run: go install github.com/steveyegge/beads/cmd/bd@latest
+        # Pin to v0.47.1 - v0.47.2 has routing defaults that cause prefix mismatch errors
+        run: go install github.com/steveyegge/beads/cmd/bd@v0.47.1
 
       - name: Add to PATH
         run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH

.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

@@ -17,6 +17,9 @@
 .DS_Store
 Thumbs.db
 
+# Claude Code local state
+.claude/
+
 # Test
 coverage.out
 *.test
@@ -29,10 +32,29 @@ gt
 # Runtime state
 state.json
 .runtime/
+
+# Beads runtime state (not tracked)
+# Formulas ARE tracked for `go install @latest` - see bottom of file
 .beads/redirect
+.beads/issues.jsonl
+.beads/interactions.jsonl
+.beads/metadata.json
+.beads/mq/
+.beads/last-touched
+.beads/daemon-*.log.gz
+.beads/.sync.lock
+.beads/sync_base.jsonl
+.beads-wisp/
 
 # Clone-specific CLAUDE.md (regenerated locally per clone)
 CLAUDE.md
 
-# Generated by go:generate from .beads/formulas/
-internal/formula/formulas/
+# 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):**

AGENTS.md

@@ -4,47 +4,6 @@ See **CLAUDE.md** for complete agent context and instructions.
 
 This file exists for compatibility with tools that look for AGENTS.md.
 
-## Landing the Plane (Session Completion)
+> **Recovery**: Run `gt prime` after compaction, clear, or new session
 
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
-
-**MANDATORY WORKFLOW:**
-
-1. **File issues for remaining work** - Create issues for anything that needs follow-up
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
-   ```bash
-   git pull --rebase
-   bd sync
-   git push
-   git status  # MUST show "up to date with origin"
-   ```
-5. **Clean up** - Clear stashes, prune remote branches
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
-
-**CRITICAL RULES:**
-- Work is NOT complete until `git push` succeeds
-- NEVER stop before pushing - that leaves work stranded locally
-- NEVER say "ready to push when you are" - YOU must push
-- If push fails, resolve and retry until it succeeds
-
-## Dependency Management
-
-Periodically check for outdated dependencies:
-
-```bash
-go list -m -u all | grep '\['
-```
-
-Update direct dependencies:
-
-```bash
-go get <package>@latest
-go mod tidy
-go build ./...
-go test ./...
-```
-
-Check release notes for breaking changes before major version bumps.
+Full context is injected by `gt prime` at session start.

CHANGELOG.md

@@ -7,6 +7,564 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+#### 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
+
+#### 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**
+
+#### 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
+
+#### 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
+
+### Added
+
+#### Release Automation
+- **`gastown-release` molecule formula** - Workflow for releases with preflight checks, CHANGELOG/info.go updates, local install, and daemon restart
+
+#### New Commands
+- **`gt show`** - Inspect bead contents and metadata
+- **`gt cat`** - Display bead content directly
+- **`gt orphans list/kill`** - Detect and clean up orphaned Claude processes
+- **`gt convoy close`** - Manual convoy closure command
+- **`gt commit`** - Wrapper for git commit with bead awareness
+- **`gt trail`** - View commit trail for current work
+- **`gt mail ack`** - Alias for mark-read command
+
+#### Plugin System
+- **Plugin discovery and management** - `gt plugin run`, `gt plugin history`
+- **`gt dispatch --plugin`** - Execute plugins via dispatch command
+
+#### Messaging Infrastructure (Beads-Native)
+- **Queue beads** - New bead type for message queues
+- **Channel beads** - Pub/sub messaging with retention
+- **Group beads** - Group management for messaging
+- **Address resolution** - Resolve agent addresses for mail routing
+- **`gt mail claim`** - Claim messages from queues
+
+#### Agent Identity
+- **`gt polecat identity show`** - Display CV summary for agents
+- **Worktree setup hooks** - Inject local configurations into worktrees
+
+#### Performance & Reliability
+- **Parallel agent startup** - Faster boot with concurrency limit
+- **Event-driven convoy completion** - Deacon checks convoy status on events
+- **Automatic orphan cleanup** - Detect and kill orphaned Claude processes
+- **Namepool auto-theming** - Themes selected per rig based on name hash
+
+### Changed
+
+- **MR tracking via beads** - Removed mrqueue package, MRs now stored as beads
+- **Desire-path commands** - Added agent ergonomics shortcuts
+- **Explicit escalation in templates** - Polecat templates include escalation instructions
+- **NamePool state is transient** - InUse state no longer persisted to config
+
+### Fixed
+
+#### Process Management
+- **Kill process tree on shutdown** - Prevents orphaned Claude processes
+- **Explicit pane process kill** - Prevents setsid orphans in tmux
+- **Session survival verification** - Verify session survives startup before returning
+- **Batch session queries** - Improved performance in `gt down`
+- **Prevent tmux server exit** - `gt down` no longer kills tmux server
+
+#### Beads & Routing
+- **Agent bead prefix alignment** - Force multi-hyphen IDs for consistency
+- **hq- prefix for town-level beads** - Groups, channels use correct prefix
+- **CreatedAt for group/channel beads** - Proper timestamps on creation
+- **Routes.jsonl protection** - Doctor check for rig-level routing issues
+- **Clear BEADS_DIR in auto-convoys** - Prevent prefix inheritance issues
+
+#### Mail & Communication
+- **Channel routing in router.Send()** - Mail correctly routes to channels
+- **Filter unread in beads mode** - Correct unread message filtering
+- **Town root detection** - Use workspace.Find for consistent detection
+
+#### Session & Lifecycle
+- **Idle Polecat Heresy warnings** - Templates warn against idle waiting
+- **Direct push prohibition for polecats** - Explicit in templates
+- **Handoff working directory** - Use correct witness directory
+- **Dead polecat handling in sling** - Detect and handle dead polecats
+- **gt done self-cleaning** - Kill tmux session on completion
+
+#### Doctor & Diagnostics
+- **Zombie session detection** - Detect dead Claude processes in tmux
+- **sqlite3 availability check** - Verify sqlite3 is installed
+- **Clone divergence check** - Remove blocking git fetch
+
+#### Build & Platform
+- **Windows build support** - Platform-specific process/signal handling
+- **macOS codesigning** - Sign binary after install
+
+### Documentation
+
+- **Idle Polecat Heresy** - Document the anti-pattern of waiting for work
+- **Bead ID vs Issue ID** - Clarify terminology in README
+- **Explicit escalation** - Add escalation guidance to polecat templates
+- **Getting Started placement** - Fix README section ordering
+
+## [0.2.6] - 2026-01-12
+
+### Added
+
+#### Escalation System
+- **Unified escalation system** - Complete escalation implementation with severity levels, routing, and tracking (gt-i9r20)
+- **Escalation config schema alignment** - Configuration now matches design doc specifications
+
+#### Agent Identity & Management
+- **`gt polecat identity` subcommand group** - Agent bead management commands for polecat lifecycle
+- **AGENTS.md fallback copy** - Polecats automatically copy AGENTS.md from mayor/rig for context bootstrapping
+- **`--debug` flag for `gt crew at`** - Debug mode for crew attachment troubleshooting
+- **Boot role detection in priming** - Proper context injection for boot role agents (#370)
+
+#### Statusline Improvements
+- **Per-agent-type health tracking** - Statusline now shows health status per agent type (#344)
+- **Visual rig grouping** - Rigs sorted by activity with visual grouping in tmux statusline (#337)
+
+#### Mail & Communication
+- **`gt mail show` alias** - Alternative command for reading mail (#340)
+
+#### Developer Experience
+- **`gt stale` command** - Check for stale binaries and version mismatches
+
+### Changed
+
+- **Refactored statusline** - Merged session loops and removed dead code for cleaner implementation
+- **Refactored sling.go** - Split 1560-line file into 7 focused modules for maintainability
+- **Magic numbers extracted** - Suggest package now uses named constants (#353)
+
+### Fixed
+
+#### Configuration & Environment
+- **Empty GT_ROOT/BEADS_DIR not exported** - AgentEnv no longer exports empty environment variables (#385)
+- **Inherited BEADS_DIR prefix mismatch** - Prevent inherited BEADS_DIR from causing prefix mismatches (#321)
+
+#### Beads & Routing
+- **routes.jsonl corruption prevention** - Added protection against routes.jsonl corruption with doctor check for rig-level issues (#377)
+- **Tracked beads init after clone** - Initialize beads database for tracked beads after git clone (#376)
+- **Rig root from BeadsPath()** - Correctly return rig root to respect redirect system
+
+#### Sling & Formula
+- **Feature and issue vars in formula-on-bead mode** - Pass both variables correctly (#382)
+- **Crew member shorthand resolution** - Resolve crew members correctly with shorthand paths
+- **Removed obsolete --naked flag** - Cleanup of deprecated sling option
+
+#### Doctor & Diagnostics
+- **Role beads check with shared definitions** - Doctor now validates role beads using shared role definitions (#378)
+- **Filter bd "Note:" messages** - Custom types check no longer confused by bd informational output (#381)
+
+#### Installation & Setup
+- **gt:role label on role beads** - Role beads now properly labeled during creation (#383)
+- **Fetch origin after refspec config** - Bare clones now fetch after configuring refspec (#384)
+- **Allow --wrappers in existing town** - No longer recreates HQ unnecessarily (#366)
+
+#### Session & Lifecycle
+- **Fallback instructions in start/restart beacons** - Session beacons now include fallback instructions
+- **Handoff recognizes polecat session pattern** - Correctly handles gt-<rig>-<name> session names (#373)
+- **gt done resilient to missing agent beads** - No longer fails when agent beads don't exist
+- **MR beads as ephemeral wisps** - Create MR beads as ephemeral wisps for proper cleanup
+- **Auto-detect cleanup status** - Prevents premature polecat nuke (#361)
+- **Delete remote polecat branches after merge** - Refinery cleans up remote branches (#369)
+
+#### Costs & Events
+- **Query all beads locations for session events** - Cost tracking finds events across locations (#374)
+
+#### Linting & Quality
+- **errcheck and unparam violations resolved** - Fixed linting errors
+- **NudgeSession for all agent notifications** - Mail now uses consistent notification method
+
+### Documentation
+
+- **Polecat three-state model** - Clarified working/stalled/zombie states
+- **Name pool vs polecat pool** - Clarified misconception about pools
+- **Plugin and escalation system designs** - Added design documentation
+- **Documentation reorganization** - Concepts, design, and examples structure
+- **gt prime clarification** - Clarified that gt prime is context recovery, not session start (GH #308)
+- **Formula package documentation** - Comprehensive package docs
+- **Various godoc additions** - GenerateMRIDWithTime, isAutonomousRole, formatInt, nil sentinel pattern
+- **Beads issue ID format** - Clarified format in README (gt-uzx2c)
+- **Stale polecat identity description** - Fixed outdated documentation
+
+### Tests
+
+- **AGENTS.md worktree tests** - Test coverage for AGENTS.md in worktrees
+- **Comprehensive test coverage** - Added tests for 5 packages (#351)
+- **Sling test for bd empty output** - Fixed test for empty output handling
+
+### Deprecated
+
+- **`gt polecat add`** - Added migration warning for deprecated command
+
+### Contributors
+
+Thanks to all contributors for this release:
+- @JeremyKalmus - Various contributions (#364)
+- @boshu2 - Formula package documentation (#343), PR documentation (#352)
+- @sauerdaniel - Polecat mail notification fix (#347)
+- @abhijit360 - Assign model to role (#368)
+- @julianknutsen - Beads path fix (#334)
+
+## [0.2.5] - 2026-01-11
+
+### Added
+- **`gt mail mark-read`** - Mark messages as read without opening them (desire path)
+- **`gt down --polecats`** - Shut down polecats without affecting other components
+- **Self-cleaning polecat model** - Polecats self-nuke on completion, witness tracks leases
+- **`gt prime --state` validation** - Flag exclusivity checks for cleaner CLI
+
+### Changed
+- **Removed `gt stop`** - Use `gt down --polecats` instead (cleaner semantics)
+- **Policy-neutral templates** - crew.md.tmpl checks remote origin for PR policy
+- **Refactored prime.go** - Split 1833-line file into logical modules
+
+### Fixed
+- **Polecat re-spawn** - CreateOrReopenAgentBead handles polecat lifecycle correctly (#333)
+- **Vim mode compatibility** - tmux sends Escape before Enter for vim users
+- **Worktree default branch** - Uses rig's configured default branch (#325)
+- **Agent bead type** - Sets --type=agent when creating agent beads
+- **Bootstrap priming** - Reduced AGENTS.md to bootstrap pointer, fixed CLAUDE.md templates
+
+### Documentation
+- Updated witness help text for self-cleaning model
+- Updated daemon comments for self-cleaning model
+- Policy-aware PR guidance in crew template
+
+## [0.2.4] - 2026-01-10
+
+Priming subsystem overhaul and Zero Framework Cognition (ZFC) improvements.
+
+### Added
+
+#### Priming Subsystem
+- **PRIME.md provisioning** - Auto-provision PRIME.md at rig level so all workers inherit Gas Town context (GUPP, hooks, propulsion) (#hq-5z76w)
+- **Post-handoff detection** - `gt prime` detects handoff marker and outputs "HANDOFF COMPLETE" warning to prevent handoff loop bug (#hq-ukjrr)
+- **Priming health checks** - `gt doctor` validates priming subsystem: SessionStart hook, gt prime command, PRIME.md presence, CLAUDE.md size (#hq-5scnt)
+- **`gt prime --dry-run`** - Preview priming without side effects
+- **`gt prime --state`** - Output session state (normal, post-handoff, crash-recovery, autonomous)
+- **`gt prime --explain`** - Add [EXPLAIN] tags for debugging priming decisions
+
+#### Formula & Configuration
+- **Rig-level default formulas** - Configure default formula at rig level (#297)
+- **Witness --agent/--env overrides** - Override agent and environment variables for witness (#293, #294)
+
+#### Developer Experience
+- **UX system import** - Comprehensive UX system from beads (#311)
+- **Explicit handoff instructions** - Clearer nudge message for handoff recipients
+
+### Fixed
+
+#### Zero Framework Cognition (ZFC)
+- **Query tmux directly** - Remove marker TTL, query tmux for agent state
+- **Remove PID-based detection** - Agent liveness from tmux, not PIDs
+- **Agent-controlled thresholds** - Stuck detection moved to agent config
+- **Remove pending.json tracking** - Eliminated anti-pattern
+- **Derive state from files** - ZFC state from filesystem, not memory cache
+- **Remove Go-side computation** - No stderr parsing violations
+
+#### Hooks & Beads
+- **Cross-level hook visibility** - Hooked beads visible to mayor/deacon (#aeb4c0d)
+- **Warn on closed hooked bead** - Alert when hooked bead already closed (#2f50a59)
+- **Correct agent bead ID format** - Fix bd create flags for agent beads (#c4fcdd8)
+
+#### Formula
+- **rigPath fallback** - Set rigPath when falling back to gastown default (#afb944f)
+
+#### Doctor
+- **Full AgentEnv for env-vars check** - Use complete environment for validation (#ce231a3)
+
+### Changed
+
+- **Refactored beads/mail modules** - Split large files into focused modules for maintainability
+
+## [0.2.3] - 2026-01-09
+
+Worker safety release - prevents accidental termination of active agents.
+
+> **Note**: The Deacon safety improvements are believed to be correct but have not
+> yet been extensively tested in production. We recommend running with
+> `gt deacon pause` initially and monitoring behavior before enabling full patrol.
+> Please report any issues. A 0.3.0 release will follow once these changes are
+> battle-tested.
+
+### Critical Safety Improvements
+
+- **Kill authority removed from Deacon** - Deacon patrol now only detects zombies via `--dry-run`, never kills directly. Death warrants are filed for Boot to handle interrogation/execution. This prevents destruction of worker context, mid-task progress, and unsaved state (#gt-vhaej)
+- **Bulletproof pause mechanism** - Multi-layer pause for Deacon with file-based state, `gt deacon pause/resume` commands, and guards in `gt prime` and heartbeat (#265)
+- **Doctor warns instead of killing** - `gt doctor` now warns about stale town-root settings rather than killing sessions (#243)
+- **Orphan process check informational** - Doctor's orphan process detection is now informational only, not actionable (#272)
+
+### Added
+
+- **`gt account switch` command** - Switch between Claude Code accounts with `gt account switch <handle>`. Manages `~/.claude` symlinks and updates default account
+- **`gt crew list --all`** - Show all crew members across all rigs (#276)
+- **Rig-level custom agent support** - Configure different agents per-rig (#12)
+- **Rig identity beads check** - Doctor validates rig identity beads exist
+- **GT_ROOT env var** - Set for all agent sessions for consistent environment
+- **New agent presets** - Added Cursor, Auggie (Augment Code), and Sourcegraph AMP as built-in agent presets (#247)
+- **Context Management docs** - Added to Witness template for better context handling (gt-jjama)
+
+### Fixed
+
+- **`gt prime --hook` recognized** - Doctor now recognizes `gt prime --hook` as valid session hook config (#14)
+- **Integration test reliability** - Improved test stability (#13)
+- **IsClaudeRunning detection** - Now detects 'claude' and version patterns correctly (#273)
+- **Deacon heartbeat restored** - `ensureDeaconRunning` restored to heartbeat using Manager pattern (#271)
+- **Deacon session names** - Correct session name references in formulas (#270)
+- **Hidden directory scanning** - Ignore `.claude` and other dot directories when enumerating polecats (#258, #279)
+- **SetupRedirect tracked beads** - Works correctly with tracked beads architecture where canonical location is `mayor/rig/.beads`
+- **Tmux shell ready** - Wait for shell ready before sending keys (#264)
+- **Gastown prefix derivation** - Correctly derive `gt-` prefix for gastown compound words (gt-m46bb)
+- **Custom beads types** - Register custom beads types during install (#250)
+
+### Changed
+
+- **Refinery Manager pattern** - Replaced `ensureRefinerySession` with `refinery.Manager.Start()` for consistency
+
+### Removed
+
+- **Unused formula JSON** - Removed unused JSON formula file (cleanup)
+
+### Contributors
+
+Thanks to all contributors for this release:
+- @julianknutsen - Doctor fixes (#14, #271, #272, #273), formula fixes (#270), GT_ROOT env (#268)
+- @joshuavial - Hidden directory scanning (#258, #279), crew list --all (#276)
+
+## [0.2.2] - 2026-01-07
+
+Rig operational state management, unified agent startup, and extensive stability fixes.
+
+### Added
+
+#### Rig Operational State Management
+- **`gt rig park/unpark` commands** - Level 1 rig control: pause daemon auto-start while preserving sessions
+- **`gt rig dock/undock` commands** - Level 2 rig control: stop all sessions and prevent auto-start (gt-9gm9n)
+- **`gt rig config` commands** - Per-rig configuration management (gt-hhmkq)
+- **Rig identity beads** - Schema and creation for rig identity tracking (gt-zmznh)
+- **Property layer lookup** - Hierarchical configuration resolution (gt-emh1c)
+- **Operational state in status** - `gt rig status` shows park/dock state
+
+#### Agent Configuration & Startup
+- **`--agent` overrides** - Override agent for start/attach/sling commands
+- **Unified agent startup** - Manager pattern for consistent agent initialization
+- **Claude settings installation** - Auto-install during rig and HQ creation
+- **Runtime-aware tmux checks** - Detect actual agent state from tmux sessions
+
+#### Status & Monitoring
+- **`gt status --watch`** - Watch mode with auto-refresh (#231)
+- **Compact status output** - One-line-per-worker format as new default
+- **LED status indicators** - Visual indicators for rigs in Mayor tmux status line
+- **Parked/docked indicators** - Pause emoji (⏸) for inactive rigs in statusline
+
+#### Beads & Workflow
+- **Minimum beads version check** - Validates beads CLI compatibility (gt-im3fl)
+- **ZFC convoy auto-close** - `bd close` triggers convoy completion (gt-3qw5s)
+- **Stale hooked bead cleanup** - Deacon clears orphaned hooks (gt-2yls3)
+- **Doctor prefix mismatch detection** - Detect misconfigured rig prefixes (gt-17wdl)
+- **Unified beads redirect** - Single redirect system for tracked and local beads (#222)
+- **Route from rig to town beads** - Cross-level bead routing
+
+#### Infrastructure
+- **Windows-compatible file locking** - Daemon lock works on Windows
+- **`--purge` flag for crews** - Full crew obliteration option
+- **Debug logging for suppressed errors** - Better visibility into startup issues (gt-6d7eh)
+- **hq- prefix in tmux cycle bindings** - Navigate to Mayor/Deacon sessions
+- **Wisp config storage layer** - Transient/local settings for ephemeral workflows
+- **Sparse checkout** - Exclude Claude context files from source repos
+
+### Changed
+
+- **Daemon respects rig operational state** - Parked/docked rigs not auto-started
+- **Agent startup unified** - Manager pattern replaces ad-hoc initialization
+- **Mayor files moved** - Reorganized into `mayor/` subdirectory
+- **Refinery merges local branches** - No longer fetches from origin (gt-cio03)
+- **Polecats start from origin/default-branch** - Consistent recycled state
+- **Observable states removed** - Discover agent state from tmux, don't track (gt-zecmc)
+- **mol-town-shutdown v3** - Complete cleanup formula (gt-ux23f)
+- **Witness delays polecat cleanup** - Wait until MR merges (gt-12hwb)
+- **Nudge on divergence** - Daemon nudges agents instead of silent accept
+- **README rewritten** - Comprehensive guides and architecture docs (#226)
+- **`gt rigs` → `gt rig list`** - Command renamed in templates/docs (#217)
+
+### Fixed
+
+#### Doctor & Lifecycle
+- **`--restart-sessions` flag required** - Doctor won't cycle sessions without explicit flag (gt-j44ri)
+- **Only cycle patrol roles** - Doctor --fix doesn't restart crew/polecats (hq-qthgye)
+- **Session-ended events auto-closed** - Prevent accumulation (gt-8tc1v)
+- **GUPP propulsion nudge** - Added to daemon restartSession
+
+#### Sling & Beads
+- **Sling uses bd native routing** - No BEADS_DIR override needed
+- **Sling parses wisp JSON correctly** - Handle `new_epic_id` field
+- **Sling resolves rig path** - Cross-rig bead hooking works
+- **Sling waits for Claude ready** - Don't nudge until session responsive (#146)
+- **Correct beads database for sling** - Rig-level beads used (gt-n5gga)
+- **Close hooked beads before clearing** - Proper cleanup order (gt-vwjz6)
+- **Removed dead sling flags** - `--molecule` and `--quality` cleaned up
+
+#### Agent Sessions
+- **Witness kills tmux on Stop()** - Clean session termination
+- **Deacon uses session package** - Correct hq- session names (gt-r38pj)
+- **Honor rig agent for witness/refinery** - Respect per-rig settings
+- **Canonical hq role bead IDs** - Consistent naming
+- **hq- prefix in status display** - Global agents shown correctly (gt-vcvyd)
+- **Restart Claude when dead** - Recover sessions where tmux exists but Claude died
+- **Town session cycling** - Works from any directory
+
+#### Polecat & Crew
+- **Nuke not blocked by stale hooks** - Closed beads don't prevent cleanup (gt-jc7bq)
+- **Crew stop dry-run support** - Preview cleanup before executing (gt-kjcx4)
+- **Crew defaults to --all** - `gt crew start <rig>` starts all crew (gt-s8mpt)
+- **Polecat cleanup handlers** - `gt witness process` invokes handlers (gt-h3gzj)
+
+#### Daemon & Configuration
+- **Create mayor/daemon.json** - `gt start` and `gt doctor --fix` initialize daemon state (#225)
+- **Initialize git before beads** - Enable repo fingerprint (#180)
+- **Handoff preserves env vars** - Claude Code environment not lost (#216)
+- **Agent settings passed correctly** - Witness and daemon respawn use rigPath
+- **Log rig discovery errors** - Don't silently swallow (gt-rsnj9)
+
+#### Refinery & Merge Queue
+- **Use rig's default_branch** - Not hardcoded 'main'
+- **MERGE_FAILED sent to Witness** - Proper failure notification
+- **Removed BranchPushedToRemote checks** - Local-only workflow support (gt-dymy5)
+
+#### Misc Fixes
+- **BeadsSetupRedirect preserves tracked files** - Don't clobber existing files (gt-fj0ol)
+- **PATH export in hooks** - Ensure commands find binaries
+- **Replace panic with fallback** - ID generation gracefully degrades (#213)
+- **Removed duplicate WorktreeAddFromRef** - Code cleanup
+- **Town root beads for Deacon** - Use correct beads location (gt-sstg)
+
+### Refactored
+
+- **AgentStateManager pattern** - Shared state management extracted (gt-gaw8e)
+- **CleanupStatus type** - Replace raw strings (gt-77gq7)
+- **ExecWithOutput utility** - Common command execution (gt-vurfr)
+- **runBdCommand helper** - DRY mail package (gt-8i6bg)
+- **Config expansion helper** - Generic DRY config (gt-i85sg)
+
+### Documentation
+
+- **Property layers guide** - Implementation documentation
+- **Worktree architecture** - Clarified beads routing
+- **Agent config** - Onboarding docs mention --agent overrides
+- **Polecat Operations section** - Added to Mayor docs (#140)
+
+### Contributors
+
+Thanks to all contributors for this release:
+- @julianknutsen - Claude settings inheritance (#239)
+- @joshuavial - Sling wisp JSON parse (#238)
+- @michaellady - Unified beads redirect (#222), daemon.json fix (#225)
+- @greghughespdx - PATH in hooks fix (#139)
+
+## [0.2.1] - 2026-01-05
+
+Bug fixes, security hardening, and new `gt config` command.
+
+### Added
+
+- **`gt config` command** - Manage agent settings (model, provider) per-rig or globally
+- **`hq-` prefix for patrol sessions** - Mayor and Deacon sessions use town-prefixed names
+- **Doctor hooks-path check** - Verify Git hooks path is configured correctly
+- **Block internal PRs** - Pre-push hook and GitHub Action prevent accidental internal PRs (#117)
+- **Dispatcher notifications** - Notify dispatcher when polecat work completes
+- **Unit tests** - Added tests for `formatTrackBeadID` helper, done redirect, hook slot E2E
+
+### Fixed
+
+#### Security
+- **Command injection prevention** - Validate beads prefix to prevent injection (gt-l1xsa)
+- **Path traversal prevention** - Validate crew names to prevent traversal (gt-wzxwm)
+- **ReDoS prevention** - Escape user input in mail search (gt-qysj9)
+- **Error handling** - Handle crypto/rand.Read errors in ID generation
+
+#### Convoy & Sling
+- **Hook slot initialization** - Set hook slot when creating agent beads during sling (#124)
+- **Cross-rig bead formatting** - Format cross-rig beads as external refs in convoy tracking (#123)
+- **Reliable bd calls** - Add `--no-daemon` and `BEADS_DIR` for reliable beads operations
+
+#### Rig Inference
+- **`gt rig status`** - Infer rig name from current working directory
+- **`gt crew start --all`** - Infer rig from cwd for batch crew starts
+- **`gt prime` in crew start** - Pass as initial prompt in crew start commands
+- **Town default_agent** - Honor default agent setting for Mayor and Deacon
+
+#### Session & Lifecycle
+- **Hook persistence** - Hook persists across session interruption via `in_progress` lookup (gt-ttn3h)
+- **Polecat cleanup** - Clean up stale worktrees and git tracking
+- **`gt done` redirect** - Use ResolveBeadsDir for redirect file support
+
+#### Build & CI
+- **Embedded formulas** - Sync and commit formulas for `go install @latest`
+- **CI lint fixes** - Resolve lint and build errors
+- **Flaky test fix** - Sync database before beads integration tests
+
 ## [0.2.0] - 2026-01-04
 
 Major release featuring the Convoy Dashboard, two-level beads architecture, and significant multi-agent improvements.

Makefile

@@ -2,6 +2,7 @@
 
 BINARY := gt
 BUILD_DIR := .
+INSTALL_DIR := $(HOME)/.local/bin
 
 # Get version info for ldflags
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
@@ -10,7 +11,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 ./...
@@ -23,7 +25,10 @@ ifeq ($(shell uname),Darwin)
 endif
 
 install: build
-	cp $(BUILD_DIR)/$(BINARY) ~/bin/$(BINARY)
+	@mkdir -p $(INSTALL_DIR)
+	@rm -f $(INSTALL_DIR)/$(BINARY)
+	@cp $(BUILD_DIR)/$(BINARY) $(INSTALL_DIR)/$(BINARY)
+	@echo "Installed $(BINARY) to $(INSTALL_DIR)/$(BINARY)"
 
 clean:
 	rm -f $(BUILD_DIR)/$(BINARY)

README.md

@@ -1,372 +1,494 @@
 # Gas Town
 
-Multi-agent orchestrator for Claude Code. Track work with convoys; sling to agents.
+**Multi-agent orchestration system for Claude Code with persistent work tracking**
 
-## Why Gas Town?
+## Overview
 
-| Without | With Gas Town |
-|---------|---------------|
-| Agents forget work after restart | Work persists on hooks - survives crashes, compaction, restarts |
-| Manual coordination | Agents have mailboxes, identities, and structured handoffs |
-| 4-10 agents is chaotic | Comfortably scale to 20-30 agents |
-| Work state in agent memory | Work state in Beads (git-backed ledger) |
+Gas Town is a workspace manager that lets you coordinate multiple Claude Code agents working on different tasks. Instead of losing context when agents restart, Gas Town persists work state in git-backed hooks, enabling reliable multi-agent workflows.
 
-## Prerequisites
+### What Problem Does This Solve?
 
-- **Go 1.23+** - [go.dev/dl](https://go.dev/dl/)
-- **Git 2.25+** - for worktree support
-- **beads (bd)** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads) - required for issue tracking
-- **tmux 3.0+** - recommended for the full experience (the Mayor session is the primary interface)
-- **Claude Code CLI** - [claude.ai/code](https://claude.ai/code)
+| Challenge                       | Gas Town Solution                            |
+| ------------------------------- | -------------------------------------------- |
+| Agents lose context on restart  | Work persists in git-backed hooks            |
+| Manual agent coordination       | Built-in mailboxes, identities, and handoffs |
+| 4-10 agents become chaotic      | Scale comfortably to 20-30 agents            |
+| Work state lost in agent memory | Work state stored in Beads ledger            |
 
-## Quick Start
+### Architecture
 
-```bash
-# Install
-go install github.com/steveyegge/gastown/cmd/gt@latest
+```mermaid
+graph TB
+    Mayor[The Mayor<br/>AI Coordinator]
+    Town[Town Workspace<br/>~/gt/]
 
-# Ensure Go binaries are in your PATH (add to ~/.zshrc or ~/.bashrc)
-export PATH="$PATH:$HOME/go/bin"
+    Town --> Mayor
+    Town --> Rig1[Rig: Project A]
+    Town --> Rig2[Rig: Project B]
 
-# Create workspace (--git auto-initializes git repository)
-gt install ~/gt --git
-cd ~/gt
+    Rig1 --> Crew1[Crew Member<br/>Your workspace]
+    Rig1 --> Hooks1[Hooks<br/>Persistent storage]
+    Rig1 --> Polecats1[Polecats<br/>Worker agents]
 
-# Add a project
-gt rig add myproject https://github.com/you/repo.git
+    Rig2 --> Crew2[Crew Member]
+    Rig2 --> Hooks2[Hooks]
+    Rig2 --> Polecats2[Polecats]
 
-# Create your personal workspace
-gt crew add <yourname> --rig myproject
+    Hooks1 -.git worktree.-> GitRepo1[Git Repository]
+    Hooks2 -.git worktree.-> GitRepo2[Git Repository]
 
-# Start working
-cd myproject/crew/<yourname>
-```
-
-For advanced multi-agent coordination, use the Mayor session:
-
-```bash
-gt mayor attach                        # Enter the Mayor's office
-```
-
-Inside the Mayor session, you're talking to Claude with full town context:
-
-> "Help me fix the authentication bug in myproject"
-
-The Mayor will create convoys, dispatch workers, and coordinate everything. You can also run CLI commands directly:
-
-```bash
-# Create a convoy and sling work (CLI workflow)
-gt convoy create "Feature X" issue-123 issue-456 --notify --human
-gt sling issue-123 myproject
-
-# Track progress
-gt convoy list
-
-# Switch between agent sessions
-gt agents
+    style Mayor fill:#e1f5ff
+    style Town fill:#f0f0f0
+    style Rig1 fill:#fff4e1
+    style Rig2 fill:#fff4e1
 ```
 
 ## Core Concepts
 
-**The Mayor** is your AI coordinator. It's Claude Code with full context about your workspace, projects, and agents. The Mayor session (`gt prime`) is the primary way to interact with Gas Town - just tell it what you want to accomplish.
+### The Mayor 🎩
 
-```
-Town (~/gt/)              Your workspace
-├── Mayor                 Your AI coordinator (start here)
-├── Rig (project)         Container for a git project + its agents
-│   ├── Polecats          Workers (ephemeral, spawn → work → disappear)
-│   ├── Witness           Monitors workers, handles lifecycle
-│   └── Refinery          Merge queue processor
-```
+Your primary AI coordinator. The Mayor is a Claude Code instance with full context about your workspace, projects, and agents. **Start here** - just tell the Mayor what you want to accomplish.
 
-**Hook**: Each agent has a hook where work hangs. On wake, run what's on your hook.
+### Town 🏘️
 
-**Beads**: Git-backed issue tracker. All work state lives here. [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+Your workspace directory (e.g., `~/gt/`). Contains all projects, agents, and configuration.
 
-## Workflows
+### Rigs 🏗️
 
-### Full Stack (Recommended)
+Project containers. Each rig wraps a git repository and manages its associated agents.
 
-The primary Gas Town experience. Agents run in tmux sessions with the Mayor as your interface.
+### Crew Members 👤
+
+Your personal workspace within a rig. Where you do hands-on work.
+
+### Polecats 🦨
+
+Ephemeral worker agents that spawn, complete a task, and disappear.
+
+### Hooks 🪝
+
+Git worktree-based persistent storage for agent work. Survives crashes and restarts.
+
+### Convoys 🚚
+
+Work tracking units. Bundle multiple beads that get assigned to agents.
+
+### Beads Integration 📿
+
+Git-backed issue tracking system that stores work state as structured data.
+
+**Bead IDs** (also called **issue IDs**) use a prefix + 5-character alphanumeric format (e.g., `gt-abc12`, `hq-x7k2m`). The prefix indicates the item's origin or rig. Commands like `gt sling` and `gt convoy` accept these IDs to reference specific work items. The terms "bead" and "issue" are used interchangeably—beads are the underlying data format, while issues are the work items stored as beads.
+
+> **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts.
+
+## Installation
+
+### Prerequisites
+
+- **Go 1.23+** - [go.dev/dl](https://go.dev/dl/)
+- **Git 2.25+** - for worktree support
+- **beads (bd) 0.44.0+** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads) (required for custom type support)
+- **sqlite3** - for convoy database queries (usually pre-installed on macOS/Linux)
+- **tmux 3.0+** - recommended for full experience
+- **Claude Code CLI** (default runtime) - [claude.ai/code](https://claude.ai/code)
+- **Codex CLI** (optional runtime) - [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli)
+
+### Setup
 
 ```bash
-gt start                               # Start Gas Town (daemon + Mayor session)
-gt mayor attach                        # Enter Mayor session
+# Install Gas Town
+$ brew install gastown                                    # Homebrew (recommended)
+$ npm install -g @gastown/gt                              # npm
+$ go install github.com/steveyegge/gastown/cmd/gt@latest  # From source
 
-# Inside Mayor session, just ask:
-# "Create a convoy for issues 123 and 456 in myproject"
-# "What's the status of my work?"
-# "Show me what the witness is doing"
+# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)
+export PATH="$PATH:$HOME/go/bin"
 
-# Or use CLI commands:
-gt convoy create "Feature X" issue-123 issue-456
-gt sling issue-123 myproject           # Spawns polecat automatically
-gt convoy list                         # Dashboard view
-gt agents                              # Navigate between sessions
+# Create workspace with git initialization
+gt install ~/gt --git
+cd ~/gt
+
+# Add your first project
+gt rig add myproject https://github.com/you/repo.git
+
+# Create your crew workspace
+gt crew add yourname --rig myproject
+cd myproject/crew/yourname
+
+# Start the Mayor session (your main interface)
+gt mayor attach
 ```
 
-### Minimal (No Tmux)
+## Quick Start Guide
 
-Run individual Claude Code instances manually. Gas Town just tracks state.
+### Getting Started
+Run
+```shell
+gt install ~/gt --git &&
+cd ~/gt &&
+gt config agent list &&
+gt mayor attach
+```
+and tell the Mayor what you want to build!
+
+---
+
+### Basic Workflow
+
+```mermaid
+sequenceDiagram
+    participant You
+    participant Mayor
+    participant Convoy
+    participant Agent
+    participant Hook
+
+    You->>Mayor: Tell Mayor what to build
+    Mayor->>Convoy: Create convoy with beads
+    Mayor->>Agent: Sling bead to agent
+    Agent->>Hook: Store work state
+    Agent->>Agent: Complete work
+    Agent->>Convoy: Report completion
+    Mayor->>You: Summary of progress
+```
+
+### Example: Feature Development
 
 ```bash
-gt convoy create "Fix bugs" issue-123  # Create convoy (sling auto-creates if skipped)
-gt sling issue-123 myproject           # Assign to worker
-claude --resume                        # Agent reads mail, runs work
+# 1. Start the Mayor
+gt mayor attach
+
+# 2. In Mayor session, create a convoy with bead IDs
+gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human
+
+# 3. Assign work to an agent
+gt sling gt-abc12 myproject
+
+# 4. Track progress
+gt convoy list
+
+# 5. Monitor agents
+gt agents
+```
+
+## Common Workflows
+
+### Mayor Workflow (Recommended)
+
+**Best for:** Coordinating complex, multi-issue work
+
+```mermaid
+flowchart LR
+    Start([Start Mayor]) --> Tell[Tell Mayor<br/>what to build]
+    Tell --> Creates[Mayor creates<br/>convoy + agents]
+    Creates --> Monitor[Monitor progress<br/>via convoy list]
+    Monitor --> Done{All done?}
+    Done -->|No| Monitor
+    Done -->|Yes| Review[Review work]
+```
+
+**Commands:**
+
+```bash
+# Attach to Mayor
+gt mayor attach
+
+# In Mayor, create convoy and let it orchestrate
+gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify
+
+# Track progress
+gt convoy list
+```
+
+### Minimal Mode (No Tmux)
+
+Run individual runtime instances manually. Gas Town just tracks state.
+
+```bash
+gt convoy create "Fix bugs" gt-abc12   # Create convoy (sling auto-creates if skipped)
+gt sling gt-abc12 myproject            # Assign to worker
+claude --resume                        # Agent reads mail, runs work (Claude)
+# or: codex                            # Start Codex in the workspace
 gt convoy list                         # Check progress
 ```
 
-### Pick Your Roles
+### Beads Formula Workflow
 
-Gas Town is modular. Run what you need:
+**Best for:** Predefined, repeatable processes
 
-- **Polecats only**: Manual spawning, no monitoring
-- **+ Witness**: Automatic worker lifecycle, stuck detection
-- **+ Refinery**: Merge queue, code review
-- **+ Mayor**: Cross-project coordination
+Formulas are TOML-defined workflows stored in `.beads/formulas/`.
 
-## Cooking Formulas
-
-Formulas define structured workflows. Cook them, sling them to agents.
-
-### Basic Example
+**Example Formula** (`.beads/formulas/release.formula.toml`):
 
 ```toml
-# .beads/formulas/shiny.formula.toml
-formula = "shiny"
-description = "Design before code, review before ship"
+description = "Standard release process"
+formula = "release"
+version = 1
 
-[[steps]]
-id = "design"
-description = "Think about architecture"
-
-[[steps]]
-id = "implement"
-needs = ["design"]
-
-[[steps]]
-id = "test"
-needs = ["implement"]
-
-[[steps]]
-id = "submit"
-needs = ["test"]
-```
-
-### Using Formulas
-
-```bash
-bd formula list                    # See available formulas
-bd cook shiny                      # Cook into a protomolecule
-bd mol pour shiny --var feature=auth   # Create runnable molecule
-gt convoy create "Auth feature" gt-xyz  # Track with convoy
-gt sling gt-xyz myproject          # Assign to worker
-gt convoy list                     # Monitor progress
-```
-
-### What Happens
-
-1. **Cook** expands the formula into a protomolecule (frozen template)
-2. **Pour** creates a molecule (live workflow) with steps as beads
-3. **Worker executes** each step, closing beads as it goes
-4. **Crash recovery**: Worker restarts, reads molecule, continues from last step
-
-### Example: Beads Release Molecule
-
-A real workflow for releasing a new beads version:
-
-```toml
-formula = "beads-release"
-description = "Version bump and release workflow"
+[vars.version]
+description = "The semantic version to release (e.g., 1.2.0)"
+required = true
 
 [[steps]]
 id = "bump-version"
-description = "Update version in version.go and CHANGELOG"
-
-[[steps]]
-id = "update-deps"
-needs = ["bump-version"]
-description = "Run go mod tidy, update go.sum"
+title = "Bump version"
+description = "Run ./scripts/bump-version.sh {{version}}"
 
 [[steps]]
 id = "run-tests"
-needs = ["update-deps"]
-description = "Full test suite, check for regressions"
+title = "Run tests"
+description = "Run make test"
+needs = ["bump-version"]
 
 [[steps]]
-id = "build-binaries"
+id = "build"
+title = "Build"
+description = "Run make build"
 needs = ["run-tests"]
-description = "Cross-compile for all platforms"
 
 [[steps]]
 id = "create-tag"
-needs = ["build-binaries"]
-description = "Git tag with version, push to origin"
+title = "Create release tag"
+description = "Run git tag -a v{{version}} -m 'Release v{{version}}'"
+needs = ["build"]
 
 [[steps]]
-id = "publish-release"
+id = "publish"
+title = "Publish"
+description = "Run ./scripts/publish.sh"
 needs = ["create-tag"]
-description = "Create GitHub release with binaries"
 ```
 
-Cook it, pour it, sling it. The polecat runs through each step, and if it crashes
-after `run-tests`, a new polecat picks up at `build-binaries`.
+**Execute:**
 
-### Formula Composition
+```bash
+# List available formulas
+bd formula list
 
-```toml
-# Extend an existing formula
-formula = "shiny-enterprise"
-extends = ["shiny"]
+# Run a formula with variables
+bd cook release --var version=1.2.0
 
-[compose]
-aspects = ["security-audit"]  # Add cross-cutting concerns
+# Create formula instance for tracking
+bd mol pour release --var version=1.2.0
 ```
 
+### Manual Convoy Workflow
+
+**Best for:** Direct control over work distribution
+
+```bash
+# Create convoy manually
+gt convoy create "Bug Fixes" --human
+
+# Add issues to existing convoy
+gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x
+
+# Assign to specific agents
+gt sling gt-m3k9p myproject/my-agent
+
+# Check status
+gt convoy show
+```
+
+## Runtime Configuration
+
+Gas Town supports multiple AI coding runtimes. Per-rig runtime settings are in `settings/config.json`.
+
+```json
+{
+  "runtime": {
+    "provider": "codex",
+    "command": "codex",
+    "args": [],
+    "prompt_mode": "none"
+  }
+}
+```
+
+**Notes:**
+
+- Claude uses hooks in `.claude/settings.json` for mail injection and startup.
+- For Codex, set `project_doc_fallback_filenames = ["CLAUDE.md"]` in
+  `~/.codex/config.toml` so role instructions are picked up.
+- For runtimes without hooks (e.g., Codex), Gas Town sends a startup fallback
+  after the session is ready: `gt prime`, optional `gt mail check --inject`
+  for autonomous roles, and `gt nudge deacon session-started`.
+
 ## Key Commands
 
-### For Humans (Overseer)
+### Workspace Management
 
 ```bash
-gt start                          # Start Gas Town (daemon + agents)
-gt shutdown                       # Graceful shutdown
-gt status                         # Town overview
-gt <role> attach                  # Jump into any agent session
-                                  # e.g., gt mayor attach, gt witness attach
+gt install <path>           # Initialize workspace
+gt rig add <name> <repo>    # Add project
+gt rig list                 # List projects
+gt crew add <name> --rig <rig>  # Create crew workspace
 ```
 
-Most other work happens through agents - just ask them.
-
-### For Agents
+### Agent Operations
 
 ```bash
-# Convoy (primary dashboard)
-gt convoy list                    # Active work across all rigs
-gt convoy status <id>             # Detailed convoy progress
-gt convoy create "name" <issues>  # Create new convoy
-
-# Work assignment
-gt sling <bead> <rig>             # Assign work to polecat
-bd ready                          # Show available work
-bd list --status=in_progress      # Active work
-
-# Communication
-gt mail inbox                     # Check messages
-gt mail send <addr> -s "..." -m "..."
-
-# Lifecycle
-gt handoff                        # Request session cycle
-gt peek <agent>                   # Check agent health
-
-# Diagnostics
-gt doctor                         # Health check
-gt doctor --fix                   # Auto-repair
+gt agents                   # List active agents
+gt sling <bead-id> <rig>    # Assign work to agent
+gt sling <bead-id> <rig> --agent cursor   # Override runtime for this sling/spawn
+gt mayor attach             # Start Mayor session
+gt mayor start --agent auggie           # Run Mayor with a specific agent alias
+gt prime                    # Context recovery (run inside existing session)
 ```
 
+**Built-in agent presets**: `claude`, `gemini`, `codex`, `cursor`, `auggie`, `amp`
+
+### Convoy (Work Tracking)
+
+```bash
+gt convoy create <name> [issues...]   # Create convoy with issues
+gt convoy list              # List all convoys
+gt convoy show [id]         # Show convoy details
+gt convoy add <convoy-id> <issue-id...>  # Add issues to convoy
+```
+
+### Configuration
+
+```bash
+# Set custom agent command
+gt config agent set claude-glm "claude-glm --model glm-4"
+gt config agent set codex-low "codex --thinking low"
+
+# Set default agent
+gt config default-agent claude-glm
+
+# View config
+gt config show
+```
+
+### Beads Integration
+
+```bash
+bd formula list             # List formulas
+bd cook <formula>           # Execute formula
+bd mol pour <formula>       # Create trackable instance
+bd mol list                 # List active instances
+```
+
+## Cooking Formulas
+
+Gas Town includes built-in formulas for common workflows. See `.beads/formulas/` for available recipes.
+
 ## Dashboard
 
-Web-based dashboard for monitoring Gas Town activity.
+Gas Town includes a web dashboard for monitoring:
 
 ```bash
-# Start the dashboard
+# Start dashboard
 gt dashboard --port 8080
 
 # Open in browser
 open http://localhost:8080
 ```
 
-**Features:**
-- **Convoy tracking** - View all active convoys with progress bars and work status
-- **Polecat workers** - See active worker sessions and their activity status
-- **Refinery status** - Monitor merge queue and PR processing
-- **Auto-refresh** - Updates every 10 seconds via htmx
+Features:
 
-Work status indicators:
-| Status | Color | Meaning |
-|--------|-------|---------|
-| `complete` | Green | All tracked items done |
-| `active` | Green | Recent activity (< 1 min) |
-| `stale` | Yellow | Activity 1-5 min ago |
-| `stuck` | Red | Activity > 5 min ago |
-| `waiting` | Gray | No assignee/activity |
+- Real-time agent status
+- Convoy progress tracking
+- Hook state visualization
+- Configuration management
+
+## Advanced Concepts
+
+### The Propulsion Principle
+
+Gas Town uses git hooks as a propulsion mechanism. Each hook is a git worktree with:
+
+1. **Persistent state** - Work survives agent restarts
+2. **Version control** - All changes tracked in git
+3. **Rollback capability** - Revert to any previous state
+4. **Multi-agent coordination** - Shared through git
+
+### Hook Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: Agent spawned
+    Created --> Active: Work assigned
+    Active --> Suspended: Agent paused
+    Suspended --> Active: Agent resumed
+    Active --> Completed: Work done
+    Completed --> Archived: Hook archived
+    Archived --> [*]
+```
+
+### MEOW (Mayor-Enhanced Orchestration Workflow)
+
+MEOW is the recommended pattern:
+
+1. **Tell the Mayor** - Describe what you want
+2. **Mayor analyzes** - Breaks down into tasks
+3. **Convoy creation** - Mayor creates convoy with beads
+4. **Agent spawning** - Mayor spawns appropriate agents
+5. **Work distribution** - Beads slung to agents via hooks
+6. **Progress monitoring** - Track through convoy status
+7. **Completion** - Mayor summarizes results
 
 ## Shell Completions
 
-Enable tab completion for `gt` commands:
-
-### Bash
-
 ```bash
-# Add to ~/.bashrc
-source <(gt completion bash)
+# Bash
+gt completion bash > /etc/bash_completion.d/gt
 
-# Or install permanently
-gt completion bash > /usr/local/etc/bash_completion.d/gt
-```
-
-### Zsh
-
-```bash
-# Add to ~/.zshrc (before compinit)
-source <(gt completion zsh)
-
-# Or install to fpath
+# Zsh
 gt completion zsh > "${fpath[1]}/_gt"
-```
 
-### Fish
-
-```bash
+# Fish
 gt completion fish > ~/.config/fish/completions/gt.fish
 ```
 
-## Roles
+## Project Roles
 
-| Role | Scope | Job |
-|------|-------|-----|
-| **Overseer** | Human | Sets strategy, reviews output, handles escalations |
-| **Mayor** | Town-wide | Cross-rig coordination, work dispatch |
-| **Deacon** | Town-wide | Daemon process, agent lifecycle, plugin execution |
-| **Witness** | Per-rig | Monitor polecats, nudge stuck workers |
-| **Refinery** | Per-rig | Merge queue, PR review, integration |
-| **Polecat** | Per-task | Execute work, file discovered issues, request shutdown |
+| Role            | Description        | Primary Interface    |
+| --------------- | ------------------ | -------------------- |
+| **Mayor**       | AI coordinator     | `gt mayor attach`    |
+| **Human (You)** | Crew member        | Your crew directory  |
+| **Polecat**     | Worker agent       | Spawned by Mayor     |
+| **Hook**        | Persistent storage | Git worktree         |
+| **Convoy**      | Work tracker       | `gt convoy` commands |
 
-## The Propulsion Principle
+## Tips
 
-> If your hook has work, RUN IT.
+- **Always start with the Mayor** - It's designed to be your primary interface
+- **Use convoys for coordination** - They provide visibility across agents
+- **Leverage hooks for persistence** - Your work won't disappear
+- **Create formulas for repeated tasks** - Save time with Beads recipes
+- **Monitor the dashboard** - Get real-time visibility
+- **Let the Mayor orchestrate** - It knows how to manage agents
 
-Agents wake up, check their hook, execute the molecule. No waiting for commands.
-Molecules survive crashes - any agent can continue where another left off.
+## Troubleshooting
 
----
+### Agents lose connection
 
-## Optional: MEOW Deep Dive
+Check hooks are properly initialized:
 
-**M**olecular **E**xpression **O**f **W**ork - the full algebra.
+```bash
+gt hooks list
+gt hooks repair
+```
 
-### States of Matter
+### Convoy stuck
 
-| Phase | Name | Storage | Behavior |
-|-------|------|---------|----------|
-| Ice-9 | Formula | `.beads/formulas/` | Source template, composable |
-| Solid | Protomolecule | `.beads/` | Frozen template, reusable |
-| Liquid | Mol | `.beads/` | Flowing work, persistent |
-| Vapor | Wisp | `.beads/` (ephemeral flag) | Transient, for patrols |
+Force refresh:
 
-*(Protomolecules are an homage to The Expanse. Ice-9 is a nod to Vonnegut.)*
+```bash
+gt convoy refresh <convoy-id>
+```
 
-### Operators
+### Mayor not responding
 
-| Operator | From → To | Effect |
-|----------|-----------|--------|
-| `cook` | Formula → Protomolecule | Expand macros, flatten |
-| `pour` | Proto → Mol | Instantiate as persistent |
-| `wisp` | Proto → Wisp | Instantiate as ephemeral |
-| `squash` | Mol/Wisp → Digest | Condense to permanent record |
-| `burn` | Wisp → ∅ | Discard without record |
+Restart Mayor session:
 
----
+```bash
+gt mayor detach
+gt mayor attach
+```
 
 ## License
 
-MIT
+MIT License - see LICENSE file for details

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

@@ -17,7 +17,9 @@ Complete setup guide for Gas Town multi-agent orchestrator.
 | Tool | Version | Check | Install |
 |------|---------|-------|---------|
 | **tmux** | 3.0+ | `tmux -V` | See below |
-| **Claude Code** | latest | `claude --version` | See [claude.ai/claude-code](https://claude.ai/claude-code) |
+| **Claude Code** (default) | latest | `claude --version` | See [claude.ai/claude-code](https://claude.ai/claude-code) |
+| **Codex CLI** (optional) | latest | `codex --version` | See [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli) |
+| **OpenCode CLI** (optional) | latest | `opencode --version` | See [opencode.ai](https://opencode.ai) |
 
 ## Installing Prerequisites
 
@@ -42,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
 
@@ -130,22 +132,46 @@ gt doctor              # Run health checks
 gt status              # Show workspace status
 ```
 
+### Step 5: Configure Agents (Optional)
+
+Gas Town supports built-in runtimes (`claude`, `gemini`, `codex`) plus custom agent aliases.
+
+```bash
+# List available agents
+gt config agent list
+
+# Create an alias (aliases can encode model/thinking flags)
+gt config agent set codex-low "codex --thinking low"
+gt config agent set claude-haiku "claude --model haiku --dangerously-skip-permissions"
+
+# Set the town default agent (used when a rig doesn't specify one)
+gt config default-agent codex-low
+```
+
+You can also override the agent per command without changing defaults:
+
+```bash
+gt start --agent codex-low
+gt sling gt-abc12 myproject --agent claude-haiku
+```
+
 ## Minimal Mode vs Full Stack Mode
 
 Gas Town supports two operational modes:
 
 ### Minimal Mode (No Daemon)
 
-Run individual Claude Code instances manually. Gas Town only tracks state.
+Run individual runtime instances manually. Gas Town only tracks state.
 
 ```bash
 # Create and assign work
-gt convoy create "Fix bugs" issue-123
-gt sling issue-123 myproject
+gt convoy create "Fix bugs" gt-abc12
+gt sling gt-abc12 myproject
 
-# Run Claude manually
+# Run runtime manually
 cd ~/gt/myproject/polecats/<worker>
-claude --resume
+claude --resume          # Claude Code
+# or: codex              # Codex CLI
 
 # Check progress
 gt convoy list
@@ -162,9 +188,9 @@ Agents run in tmux sessions. Daemon manages lifecycle automatically.
 gt daemon start
 
 # Create and assign work (workers spawn automatically)
-gt convoy create "Feature X" issue-123 issue-456
-gt sling issue-123 myproject
-gt sling issue-456 myproject
+gt convoy create "Feature X" gt-abc12 gt-def34
+gt sling gt-abc12 myproject
+gt sling gt-def34 myproject
 
 # Monitor on dashboard
 gt convoy list
@@ -184,7 +210,7 @@ Gas Town is modular. Enable only what you need:
 |--------------|-------|----------|
 | **Polecats only** | Workers | Manual spawning, no monitoring |
 | **+ Witness** | + Monitor | Automatic lifecycle, stuck detection |
-| **+ Refinery** | + Merge queue | PR review, code integration |
+| **+ Refinery** | + Merge queue | MR review, code integration |
 | **+ Mayor** | + Coordinator | Cross-project coordination |
 
 ## Troubleshooting
@@ -242,13 +268,13 @@ ssh -T git@github.com
 git config --global credential.helper cache
 ```
 
-### Beads sync issues
+### Beads issues
 
-If beads aren't syncing across clones:
+If experiencing beads problems:
 
 ```bash
 cd ~/gt/myproject/mayor/rig
-bd sync --status           # Check sync status
+bd status                  # Check database health
 bd doctor                  # Run beads health check
 ```
 
@@ -277,6 +303,6 @@ rm -rf ~/gt
 After installation:
 
 1. **Read the README** - Core concepts and workflows
-2. **Try a simple workflow** - `gt convoy create "Test" test-issue`
+2. **Try a simple workflow** - `bd create "Test task"` then `gt convoy create "Test" <bead-id>`
 3. **Explore docs** - `docs/reference.md` for command reference
 4. **Run doctor regularly** - `gt doctor` catches problems early

docs/beads-native-messaging.md

@@ -0,0 +1,201 @@
+# Beads-Native Messaging
+
+This document describes the beads-native messaging system for Gas Town, which replaces the file-based messaging configuration with persistent beads stored in the town's `.beads` directory.
+
+## Overview
+
+Beads-native messaging introduces three new bead types for managing communication:
+
+- **Groups** (`gt:group`) - Named collections of addresses for mail distribution
+- **Queues** (`gt:queue`) - Work queues where messages can be claimed by workers
+- **Channels** (`gt:channel`) - Pub/sub broadcast streams with message retention
+
+All messaging beads use the `hq-` prefix because they are town-level entities that span rigs.
+
+## Bead Types
+
+### Groups (`gt:group`)
+
+Groups are named collections of addresses used for mail distribution. When you send to a group, the message is delivered to all members.
+
+**Bead ID format:** `hq-group-<name>` (e.g., `hq-group-ops-team`)
+
+**Fields:**
+- `name` - Unique group name
+- `members` - Comma-separated list of addresses, patterns, or nested group names
+- `created_by` - Who created the group (from BD_ACTOR)
+- `created_at` - ISO 8601 timestamp
+
+**Member types:**
+- Direct addresses: `gastown/crew/max`, `mayor/`, `deacon/`
+- Wildcard patterns: `*/witness`, `gastown/*`, `gastown/crew/*`
+- Special patterns: `@town`, `@crew`, `@witnesses`
+- Nested groups: Reference other group names
+
+### Queues (`gt:queue`)
+
+Queues are work queues where messages wait to be claimed by workers. Unlike groups, each message goes to exactly one claimant.
+
+**Bead ID format:** `hq-q-<name>` (town-level) or `gt-q-<name>` (rig-level)
+
+**Fields:**
+- `name` - Queue name
+- `status` - `active`, `paused`, or `closed`
+- `max_concurrency` - Maximum concurrent workers (0 = unlimited)
+- `processing_order` - `fifo` or `priority`
+- `available_count` - Items ready to process
+- `processing_count` - Items currently being processed
+- `completed_count` - Items completed
+- `failed_count` - Items that failed
+
+### Channels (`gt:channel`)
+
+Channels are pub/sub streams for broadcasting messages. Messages are retained according to the channel's retention policy.
+
+**Bead ID format:** `hq-channel-<name>` (e.g., `hq-channel-alerts`)
+
+**Fields:**
+- `name` - Unique channel name
+- `subscribers` - Comma-separated list of subscribed addresses
+- `status` - `active` or `closed`
+- `retention_count` - Number of recent messages to retain (0 = unlimited)
+- `retention_hours` - Hours to retain messages (0 = forever)
+- `created_by` - Who created the channel
+- `created_at` - ISO 8601 timestamp
+
+## CLI Commands
+
+### Group Management
+
+```bash
+# List all groups
+gt mail group list
+
+# Show group details
+gt mail group show <name>
+
+# Create a new group with members
+gt mail group create <name> [members...]
+gt mail group create ops-team gastown/witness gastown/crew/max
+
+# Add member to group
+gt mail group add <name> <member>
+
+# Remove member from group
+gt mail group remove <name> <member>
+
+# Delete a group
+gt mail group delete <name>
+```
+
+### Channel Management
+
+```bash
+# List all channels
+gt mail channel
+gt mail channel list
+
+# View channel messages
+gt mail channel <name>
+gt mail channel show <name>
+
+# Create a channel with retention policy
+gt mail channel create <name> [--retain-count=N] [--retain-hours=N]
+gt mail channel create alerts --retain-count=100
+
+# Delete a channel
+gt mail channel delete <name>
+```
+
+### Sending Messages
+
+The `gt mail send` command now supports groups, queues, and channels:
+
+```bash
+# Send to a group (expands to all members)
+gt mail send my-group -s "Subject" -m "Body"
+
+# Send to a queue (single message, workers claim)
+gt mail send queue:my-queue -s "Work item" -m "Details"
+
+# Send to a channel (broadcast with retention)
+gt mail send channel:my-channel -s "Announcement" -m "Content"
+
+# Direct address (unchanged)
+gt mail send gastown/crew/max -s "Hello" -m "World"
+```
+
+## Address Resolution
+
+When sending mail, addresses are resolved in this order:
+
+1. **Explicit prefix** - If address starts with `group:`, `queue:`, or `channel:`, use that type directly
+2. **Contains `/`** - Treat as agent address or pattern (direct delivery)
+3. **Starts with `@`** - Special pattern (`@town`, `@crew`, etc.) or beads-native group
+4. **Name lookup** - Search for group → queue → channel by name
+
+If a name matches multiple types (e.g., both a group and a channel named "alerts"), the resolver returns an error and requires an explicit prefix.
+
+## Key Implementation Files
+
+| File | Description |
+|------|-------------|
+| `internal/beads/beads_group.go` | Group bead CRUD operations |
+| `internal/beads/beads_queue.go` | Queue bead CRUD operations |
+| `internal/beads/beads_channel.go` | Channel bead + retention logic |
+| `internal/mail/resolve.go` | Address resolution logic |
+| `internal/cmd/mail_group.go` | Group CLI commands |
+| `internal/cmd/mail_channel.go` | Channel CLI commands |
+| `internal/cmd/mail_send.go` | Updated send with resolver |
+
+## Retention Policy
+
+Channels support two retention mechanisms:
+
+- **Count-based** (`--retain-count=N`): Keep only the last N messages
+- **Time-based** (`--retain-hours=N`): Delete messages older than N hours
+
+Retention is enforced:
+1. **On-write**: After posting a new message, old messages are pruned
+2. **On-patrol**: Deacon patrol runs `PruneAllChannels()` as a backup cleanup
+
+The patrol uses a 10% buffer to avoid thrashing (only prunes if count > retainCount × 1.1).
+
+## Examples
+
+### Create a team distribution group
+
+```bash
+# Create a group for the ops team
+gt mail group create ops-team gastown/witness gastown/crew/max deacon/
+
+# Send to the group
+gt mail send ops-team -s "Team meeting" -m "Tomorrow at 10am"
+
+# Add a new member
+gt mail group add ops-team gastown/crew/dennis
+```
+
+### Set up an alerts channel
+
+```bash
+# Create an alerts channel that keeps last 50 messages
+gt mail channel create alerts --retain-count=50
+
+# Send an alert
+gt mail send channel:alerts -s "Build failed" -m "See CI for details"
+
+# View recent alerts
+gt mail channel alerts
+```
+
+### Create nested groups
+
+```bash
+# Create role-based groups
+gt mail group create witnesses */witness
+gt mail group create leads gastown/crew/max gastown/crew/dennis
+
+# Create a group that includes other groups
+gt mail group create all-hands witnesses leads mayor/
+```