chore: Bump version to 0.2.1

Town-level services (Mayor, Deacon) now use hq- prefix instead of gt-:
- hq-mayor (was gt-mayor)
- hq-deacon (was gt-deacon)

This distinguishes town-level sessions from rig-level sessions which
continue to use gt- prefix (gt-gastown-witness, gt-gastown-crew-max, etc).

Changes:
- session.MayorSessionName() returns "hq-mayor"
- session.DeaconSessionName() returns "hq-deacon"
- ParseSessionName() handles both hq- and gt- prefixes
- categorizeSession() handles both prefixes
- categorizeSessions() accepts both prefixes
- Updated all tests and documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

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

@@ -35,7 +35,7 @@ gt peek deacon --lines 20
 
 **Step 2: Check agent bead state**
 ```bash
-bd show gt-deacon 2>/dev/null
+bd show hq-deacon 2>/dev/null
 # Look for:
 # - state: running/working/idle
 # - last_activity: when was last update?

.beads/formulas/mol-convoy-cleanup.formula.toml

@@ -1,7 +1,7 @@
 description = """
 Archive completed convoys and notify overseer.
 
-Dogs execute this formula when convoys complete. The Deacon detects completed
+Dogs work through molecules (poured from this formula) when convoys complete. The Deacon detects completed
 convoys (all tracked issues closed) and slings this work to a dog for:
 - Generating convoy summary
 - Archiving convoy state

.beads/formulas/mol-convoy-feed.formula.toml

@@ -0,0 +1,259 @@
+description = """
+Feed stranded convoys by dispatching ready work to available polecats.
+
+Dogs execute this formula when the Deacon detects a stranded convoy. A convoy
+is stranded when it has ready issues (open, unblocked, no assignee) but no
+workers are processing them.
+
+## Dog Contract
+
+This is infrastructure work. You:
+1. Receive convoy ID via variable
+2. Load convoy and find ready issues
+3. Check idle polecat capacity across rigs
+4. Dispatch min(ready_issues, idle_polecats) using gt sling
+5. Report actions taken
+6. Return to kennel
+
+## Variables
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| convoy | --var | The stranded convoy ID to feed |
+
+## Single Pass Design
+
+Dog doesn't babysit or wait for completion. The workflow is:
+1. Find ready issues in convoy
+2. Dispatch each to an available polecat
+3. Exit immediately
+
+If convoy is still stranded next Deacon patrol cycle, another dog will be
+dispatched. This keeps the system stateless and batch-oriented.
+
+## Failure Modes
+
+| Situation | Action |
+|-----------|--------|
+| Convoy not found | Exit with error, notify Deacon |
+| No ready issues | Exit success (false positive, convoy is fine) |
+| No idle polecats | Exit success, note in report (will retry next cycle) |
+| Sling fails | Continue with remaining issues, note failures |"""
+formula = "mol-convoy-feed"
+version = 1
+
+[squash]
+trigger = "on_complete"
+template_type = "work"
+include_metrics = true
+
+[[steps]]
+id = "load-convoy"
+title = "Load convoy and identify ready issues"
+description = """
+Load the convoy and find issues ready for dispatch.
+
+**1. Check assignment:**
+```bash
+gt hook               # Shows convoy in hook_bead or vars
+```
+
+**2. Load convoy details:**
+```bash
+gt convoy status {{convoy}} --json
+```
+
+**3. Identify ready issues:**
+
+For each tracked issue in the convoy:
+```bash
+bd show <issue-id> --json
+```
+
+An issue is "ready" if ALL of these are true:
+- status = "open" (NOT in_progress, closed, or hooked)
+- not in blocked list (check: bd blocked --json)
+- assignee is empty OR assignee session is dead
+
+Check blocked status:
+```bash
+bd blocked --json
+# If issue ID appears here, it's blocked (skip it)
+```
+
+Check assignee session if set:
+```bash
+# If assignee like "gastown/polecats/nux"
+tmux has-session -t gt-gastown-polecat-nux 2>/dev/null && echo "alive" || echo "dead"
+```
+
+**4. Build ready list:**
+Collect all ready issues with their metadata:
+- Issue ID
+- Title
+- Priority
+- Rig (extracted from prefix)
+
+Sort by priority (P0 first) for dispatch order.
+
+**Exit criteria:** Ready issues identified and prioritized."""
+
+[[steps]]
+id = "check-capacity"
+title = "Check polecat capacity across rigs"
+needs = ["load-convoy"]
+description = """
+Determine how many polecats are available for dispatch.
+
+**1. For each rig that has ready issues:**
+```bash
+gt polecats <rig>
+# Shows polecat status: idle, working, etc.
+```
+
+**2. Count available capacity:**
+Available polecats are those that:
+- Exist in the rig's polecat pool
+- Currently idle (no hooked work)
+- Session is running
+
+**3. Calculate dispatch count:**
+```
+dispatch_count = min(ready_issues, available_polecats)
+```
+
+If dispatch_count = 0:
+- Log: "No capacity available, will retry next cycle"
+- Proceed to report step (no dispatches to make)
+
+**4. Match issues to rigs:**
+For each ready issue, determine target rig from issue prefix:
+- gt-* issues → gastown rig
+- bd-* issues → beads rig
+- etc.
+
+**Exit criteria:** Dispatch plan created with issue→rig mappings."""
+
+[[steps]]
+id = "dispatch-work"
+title = "Dispatch ready issues to polecats"
+needs = ["check-capacity"]
+description = """
+Sling each ready issue to an available polecat.
+
+**For each issue in dispatch plan:**
+
+```bash
+# Dispatch issue to the appropriate rig
+# This spawns a fresh polecat or assigns to idle one
+gt sling <issue-id> <rig>
+
+# Example:
+gt sling gt-abc123 gastown
+gt sling bd-xyz789 beads
+```
+
+**Track results:**
+For each dispatch:
+- Success: Note issue ID, target rig, polecat assigned
+- Failure: Note issue ID, error message
+
+**Important notes:**
+- `gt sling` handles polecat selection automatically
+- It will spawn a new polecat if none available
+- The polecat gets the issue hooked and starts immediately
+- Don't wait for polecat to complete - fire and forget
+
+**If sling fails:**
+- Continue with remaining issues
+- Note the failure for the report
+- Don't escalate individual failures (will retry next cycle)
+
+**Exit criteria:** All dispatchable issues have been slung."""
+
+[[steps]]
+id = "report-results"
+title = "Generate and send feeding report"
+needs = ["dispatch-work"]
+description = """
+Create summary report of convoy feeding actions.
+
+**1. Generate report:**
+```markdown
+## Convoy Feed Report: {{convoy}}
+
+**Ready issues found**: {{ready_count}}
+**Polecats available**: {{available_count}}
+**Issues dispatched**: {{dispatch_count}}
+
+### Dispatched Work
+{{#each dispatched}}
+- {{issue_id}}: {{title}} → {{rig}}/{{polecat}}
+{{/each}}
+
+### Skipped (no capacity)
+{{#if skipped}}
+{{#each skipped}}
+- {{issue_id}}: {{title}} (will retry next cycle)
+{{/each}}
+{{else}}
+(none)
+{{/if}}
+
+### Errors
+{{#if errors}}
+{{#each errors}}
+- {{issue_id}}: {{error}}
+{{/each}}
+{{else}}
+(none)
+{{/if}}
+```
+
+**2. Send to Deacon:**
+```bash
+gt mail send deacon/ -s "Convoy fed: {{convoy}}" -m "$(cat <<EOF
+Convoy {{convoy}} feeding complete.
+
+Dispatched: {{dispatch_count}}/{{ready_count}} issues
+{{#if errors}}Errors: {{error_count}}{{/if}}
+
+{{report_summary}}
+EOF
+)"
+```
+
+**3. Update convoy (optional):**
+If convoy has a notify field, could add a note about feeding activity.
+Not required - the dispatch tracking handles visibility.
+
+**Exit criteria:** Report generated and sent."""
+
+[[steps]]
+id = "return-to-kennel"
+title = "Signal completion and return to kennel"
+needs = ["report-results"]
+description = """
+Signal work complete and return to available pool.
+
+**1. Signal completion to Deacon:**
+```bash
+gt mail send deacon/ -s "DOG_DONE $(hostname)" -m "Task: convoy-feed
+Convoy: {{convoy}}
+Ready: {{ready_count}}
+Dispatched: {{dispatch_count}}
+Status: COMPLETE
+
+Ready for next assignment."
+```
+
+**2. Return to kennel:**
+Dog returns to available state in the pool. Deacon will assign next work
+or retire the dog if pool is oversized.
+
+**Exit criteria:** Deacon notified, dog ready for next work or retirement."""
+
+[vars]
+[vars.convoy]
+description = "The convoy ID to feed"
+required = true

.beads/formulas/mol-dep-propagate.formula.toml

@@ -1,7 +1,7 @@
 description = """
 Propagate cross-rig dependency resolution.
 
-Dogs execute this formula when dependencies resolve across rig boundaries.
+Dogs work through molecules (poured from this formula) when dependencies resolve across rig boundaries.
 When an issue in one rig closes, dependent issues in other rigs may unblock.
 This formula handles:
 - Finding cross-rig dependents

.beads/formulas/mol-digest-generate.formula.toml

@@ -1,7 +1,7 @@
 description = """
 Generate daily digest for overseer (Mayor).
 
-Dogs execute this formula on a scheduled basis (daily, or triggered by plugin)
+Dogs work through molecules (poured from this formula) on a scheduled basis (daily, or triggered by plugin)
 to create summary digests of Gas Town activity. This aggregates:
 - Work completed across all rigs
 - Issues filed and closed

.beads/formulas/mol-orphan-scan.formula.toml

@@ -1,7 +1,7 @@
 description = """
 Find and reassign orphaned work.
 
-Dogs execute this formula to scan for orphaned state across the town:
+Dogs work through molecules (poured from this formula) to scan for orphaned state:
 - Issues marked in_progress with no active polecat
 - Molecules attached but worker gone
 - Merge queue entries with dead owners

.beads/formulas/mol-polecat-conflict-resolve.formula.toml

@@ -0,0 +1,385 @@
+description = """
+Conflict resolution workflow for polecats handling merge conflicts.
+
+This molecule guides a polecat through resolving merge conflicts for a previously
+submitted MR that failed to rebase. The workflow uses the merge-slot gate to
+serialize conflict resolution and prevent racing.
+
+## Task Recognition
+
+Conflict resolution tasks are created by the Refinery when a mechanical rebase
+fails. They are identified by:
+- Title prefix: "Resolve merge conflicts:"
+- Metadata fields in description: Original MR, Branch, Conflict SHA
+
+## Key Differences from Regular Polecat Work
+
+| Aspect | Regular Work | Conflict Resolution |
+|--------|--------------|---------------------|
+| Branch source | Create new branch | Checkout existing MR branch |
+| Merge path | Submit to queue via `gt done` | Push directly to main |
+| Issue closure | Refinery closes after merge | Close MR bead yourself |
+| Serialization | None | Merge-slot gate required |
+
+## Variables
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| task | hook_bead | The conflict-resolution task ID |
+| original_mr | task metadata | The MR bead that had conflicts |
+| branch | task metadata | The branch to rebase |
+| conflict_sha | task metadata | Main SHA when conflict occurred |
+
+## Failure Modes
+
+| Situation | Action |
+|-----------|--------|
+| Merge slot held | Wait (--wait flag adds you to queue) |
+| Complex conflicts | Use judgment; escalate if unsure |
+| Tests fail after resolve | Fix them before pushing |
+| Resolution unclear | Read original issue for context |"""
+formula = "mol-polecat-conflict-resolve"
+version = 1
+
+[[steps]]
+id = "load-task"
+title = "Load task and extract metadata"
+description = """
+Initialize your session and understand the conflict resolution task.
+
+**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
+```
+
+**3. Read the conflict resolution task:**
+```bash
+bd show {{task}}
+```
+
+**4. Extract metadata from the task description:**
+
+The task description contains structured metadata:
+```
+## Metadata
+- Original MR: <mr-id>
+- Branch: <branch>
+- Conflict with: <target>@<main-sha>
+- Original issue: <source-issue>
+- Retry count: <count>
+```
+
+Parse and note:
+- **original_mr**: The MR bead ID (you'll close this after merge)
+- **branch**: The branch to checkout and rebase
+- **source_issue**: The original work issue (read for context if needed)
+- **retry_count**: How many times this has been attempted
+
+**5. Understand the context:**
+
+If the conflict seems complex, read the original issue:
+```bash
+bd show <source-issue>      # What was the original work?
+```
+
+**Exit criteria:** You have all metadata and understand the conflict context."""
+
+[[steps]]
+id = "acquire-slot"
+title = "Acquire merge slot"
+needs = ["load-task"]
+description = """
+Acquire exclusive access to the merge slot before proceeding.
+
+The merge slot prevents multiple conflict-resolution polecats from racing
+to push to main simultaneously (the "Monkey Knife Fight" problem).
+
+**1. Check slot availability:**
+```bash
+bd merge-slot check --json
+```
+
+**2. Acquire the slot:**
+```bash
+bd merge-slot acquire --holder=$(whoami) --wait --json
+```
+
+The `--wait` flag adds you to the waiters queue if the slot is held.
+You'll proceed when the current holder releases.
+
+**3. Verify acquisition:**
+The output should show:
+```json
+{"available": false, "holder": "your-name", ...}
+```
+
+If you're in the waiters list, wait for the holder to release. Check
+periodically:
+```bash
+bd merge-slot check --json
+```
+
+**Important:** Once you have the slot, complete the workflow promptly.
+Other polecats may be waiting.
+
+**Exit criteria:** You hold the merge slot exclusively."""
+
+[[steps]]
+id = "checkout-branch"
+title = "Checkout and prepare the conflicting branch"
+needs = ["acquire-slot"]
+description = """
+Fetch and checkout the branch that needs conflict resolution.
+
+**1. Ensure clean workspace:**
+```bash
+git status                  # Should be clean
+git stash list              # Should be empty
+```
+
+If dirty, clean up first (stash or discard).
+
+**2. Fetch latest state:**
+```bash
+git fetch origin
+git fetch origin {{branch}}:refs/remotes/origin/{{branch}}
+```
+
+**3. Checkout the branch:**
+```bash
+git checkout -b temp-resolve origin/{{branch}}
+```
+
+Using `temp-resolve` as the local branch name keeps things clear.
+
+**4. Verify the branch state:**
+```bash
+git log --oneline -5        # Recent commits
+git log origin/main..HEAD   # Commits not on main
+```
+
+**Exit criteria:** On temp-resolve branch, ready to rebase."""
+
+[[steps]]
+id = "rebase-resolve"
+title = "Rebase onto main and resolve conflicts"
+needs = ["checkout-branch"]
+description = """
+Perform the rebase and resolve any conflicts.
+
+**1. Start the rebase:**
+```bash
+git rebase origin/main
+```
+
+**2. If conflicts occur:**
+
+For each conflicted file:
+```bash
+git status                  # See conflicted files
+git diff                    # See conflict markers
+```
+
+**Resolve using your judgment:**
+- Read both versions carefully
+- Consider the original intent (from source issue)
+- If the MR was adding a feature, preserve that addition
+- If the MR was fixing a bug, ensure the fix remains
+
+**After resolving each file:**
+```bash
+git add <resolved-file>
+git rebase --continue
+```
+
+**3. If stuck on a conflict:**
+- Read the original issue for context: `bd show <source-issue>`
+- If still unclear, escalate to Witness:
+  ```bash
+  gt mail send <rig>/witness -s "HELP: Complex conflict" -m "Task: {{task}}
+  File: <conflicted-file>
+  Issue: Cannot determine correct resolution"
+  ```
+
+**4. Verify rebase success:**
+```bash
+git log --oneline origin/main..HEAD   # Your commits rebased
+git status                            # Clean working tree
+```
+
+**Exit criteria:** Branch successfully rebased onto origin/main."""
+
+[[steps]]
+id = "run-tests"
+title = "Run tests to verify resolution"
+needs = ["rebase-resolve"]
+description = """
+Verify the resolution doesn't break anything.
+
+**1. Run the test suite:**
+```bash
+go test ./...               # Or appropriate test command
+```
+
+**ALL TESTS MUST PASS.** Do not push with failures.
+
+**2. If tests fail:**
+- Determine if it's a resolution error or pre-existing
+- If your resolution broke something: fix it
+- If pre-existing: file a bead, but still must fix before pushing
+
+```bash
+# Quick check: does main pass?
+git stash
+git checkout origin/main
+go test ./...
+git checkout temp-resolve
+git stash pop
+```
+
+**3. Run build check:**
+```bash
+go build ./...
+```
+
+**Exit criteria:** All tests pass, build succeeds."""
+
+[[steps]]
+id = "push-to-main"
+title = "Push resolved changes directly to main"
+needs = ["run-tests"]
+description = """
+Push the resolved branch directly to main.
+
+**Important:** Unlike normal polecat work, conflict resolution pushes directly
+to main. This is because:
+1. The original MR was already reviewed/approved by being in the queue
+2. We're just resolving conflicts, not adding new functionality
+3. Going back through the queue would create an infinite loop
+
+**1. Rebase one more time (in case main moved):**
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+If new conflicts: resolve them (return to rebase-resolve step).
+
+**2. Push to main:**
+```bash
+git push origin temp-resolve:main
+```
+
+**3. Verify the push:**
+```bash
+git log origin/main --oneline -3    # Your commits should be there
+```
+
+**Exit criteria:** Changes are on origin/main."""
+
+[[steps]]
+id = "close-beads"
+title = "Close the original MR bead and this task"
+needs = ["push-to-main"]
+description = """
+Close the beads to complete the work chain.
+
+**1. Close the original MR bead:**
+```bash
+bd close {{original_mr}} --reason="merged after conflict resolution"
+```
+
+This completes the MR that was blocked on conflicts.
+
+**2. Close the source issue (if not already closed):**
+```bash
+bd show <source-issue>      # Check status
+bd close <source-issue> --reason="merged via conflict resolution"
+```
+
+The Refinery normally closes issues after merge, but since we pushed
+directly to main, we handle it here.
+
+**3. Sync beads:**
+```bash
+bd sync
+```
+
+**Exit criteria:** Original MR and source issue are closed."""
+
+[[steps]]
+id = "release-slot"
+title = "Release merge slot"
+needs = ["close-beads"]
+description = """
+Release the merge slot so other polecats can proceed.
+
+**1. Release the slot:**
+```bash
+bd merge-slot release --holder=$(whoami) --json
+```
+
+**2. Verify release:**
+```bash
+bd merge-slot check --json
+```
+
+Should show either:
+- `available: true` (no one waiting)
+- `holder: <next-waiter>` (slot passed to next in queue)
+
+**Exit criteria:** Merge slot released."""
+
+[[steps]]
+id = "cleanup-and-exit"
+title = "Clean up and close task"
+needs = ["release-slot"]
+description = """
+Clean up workspace and close the conflict resolution task.
+
+**1. Clean up local branch:**
+```bash
+git checkout main
+git branch -D temp-resolve
+git fetch origin
+git reset --hard origin/main
+```
+
+**2. Verify clean state:**
+```bash
+git status                  # Clean
+git stash list              # Empty
+```
+
+**3. Close this task:**
+```bash
+bd close {{task}} --reason="Conflicts resolved and merged to main"
+```
+
+**4. Signal completion:**
+```bash
+gt done
+```
+
+You're now recyclable. The Witness knows you've completed conflict resolution.
+
+**Exit criteria:** Task closed, workspace clean, polecat recyclable."""
+
+[vars]
+[vars.task]
+description = "The conflict resolution task ID assigned to this polecat"
+required = true
+
+[vars.original_mr]
+description = "The original MR bead ID (extracted from task metadata)"
+required = true
+
+[vars.branch]
+description = "The branch to rebase (extracted from task metadata)"
+required = true

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

@@ -1,22 +1,26 @@
 description = """
-Full polecat work lifecycle from assignment through merge-ready handoff.
+Full polecat work lifecycle from assignment through MR submission.
 
 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
+## Polecat Contract (Ephemeral Model)
 
-You are an autonomous worker. You:
+You are an ephemeral worker. You:
 1. Receive work via your hook (pinned molecule + issue)
-2. Execute the work following this formula
-3. Signal completion to Witness (who verifies and merges)
-4. Wait for Witness to terminate your session
+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
+
+**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)
-- Kill your own session (Witness does cleanup)
-- Skip verification steps (quality gates exist for a reason)
+- 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)
 
 ## Variables
 
@@ -33,7 +37,7 @@ You are an autonomous worker. You:
 | Context filling | Use gt handoff to cycle to fresh session |
 | Unsure what to do | Mail Witness, don't guess |"""
 formula = "mol-polecat-work"
-version = 3
+version = 4
 
 [[steps]]
 id = "load-context"
@@ -374,21 +378,24 @@ git diff origin/main...HEAD # Your changes (expected)
 **Exit criteria:** Branch pushed, workspace clean, no cruft."""
 
 [[steps]]
-id = "close-issue"
-title = "Close the assigned issue"
+id = "prepare-for-review"
+title = "Prepare work for review"
 needs = ["cleanup-workspace"]
 description = """
-Mark the issue as complete in beads.
+Verify work is complete and ready for merge queue.
 
-**1. Close with a summary:**
-```bash
-bd close {{issue}} --reason "Implemented: <brief summary of what was done>"
-```
+**Note:** Do NOT close the issue. The Refinery will close it after successful merge.
+This enables conflict-resolution retries without reopening closed issues.
 
-**2. Verify closure:**
+**1. Verify the issue shows your work:**
 ```bash
 bd show {{issue}}
-# Status should show 'closed'
+# Status should still be 'in_progress' (you're working on it)
+```
+
+**2. Add completion notes:**
+```bash
+bd update {{issue}} --notes "Implemented: <brief summary of what was done>"
 ```
 
 **3. Sync beads:**
@@ -396,44 +403,55 @@ bd show {{issue}}
 bd sync
 ```
 
-**Exit criteria:** Issue closed in beads, synced to remote."""
+**Exit criteria:** Issue updated with completion notes, beads synced."""
 
 [[steps]]
-id = "signal-complete"
-title = "Signal completion to Witness"
-needs = ["close-issue"]
+id = "submit-and-exit"
+title = "Submit to merge queue and exit"
+needs = ["prepare-for-review"]
 description = """
-Notify Witness you're done and wait for termination.
+Submit your work to the merge queue. You become recyclable after this.
 
-**1. Update your agent state:**
+**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)
+
+**1. Submit with gt done:**
 ```bash
-# Your agent bead should reflect completion
-gt mol done                 # Or equivalent command
+gt done
 ```
 
-**2. Send POLECAT_DONE mail:**
-```bash
-gt mail send <rig>/witness -s "POLECAT_DONE $(hostname)" -m "Exit: MERGED
-Issue: {{issue}}
-Branch: $(git branch --show-current)
-Commits: $(git log --oneline origin/main..HEAD | wc -l | tr -d ' ')
+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)
 
-Work complete. Ready for merge queue."
+**2. Verify submission:**
+You should see output like:
+```
+✓ Work submitted to merge queue
+  MR ID: gt-xxxxx
+  Source: polecat/<name>
+  Target: main
+  Issue: {{issue}}
 ```
 
-**3. WAIT FOR WITNESS:**
-Do NOT exit or kill your session. The Witness will:
-1. Verify your git state is clean
-2. Send MERGE_READY to Refinery
-3. Wait for MERGED confirmation
-4. Kill your session
+**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.
 
-You may see a ~30-60 second delay while this happens.
-If you don't get killed within 5 minutes, mail Witness again.
+If you have context remaining, you may:
+- Pick up new work from `bd ready`
+- Or use `gt handoff` to cycle to a fresh session
 
-**CRITICAL:** Do not exit yourself. Do not run `exit`. Just wait.
+If the Refinery needs conflict resolution, it will dispatch a fresh polecat.
+You do NOT need to wait around.
 
-**Exit criteria:** Witness terminates your session (you won't reach this)."""
+**Exit criteria:** MR submitted, Witness notified, polecat recyclable."""
 
 [vars]
 [vars.issue]

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

@@ -1,7 +1,7 @@
 description = """
 Clean stale sessions and garbage collect.
 
-Dogs execute this formula to clean up dead sessions, orphaned processes, and
+Dogs work through molecules (poured from this formula) to clean up dead sessions, orphaned processes, and
 other system cruft. This is the garbage collector for Gas Town's runtime:
 - Dead tmux sessions (no Claude process)
 - Orphaned Claude processes (no tmux parent)

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

@@ -1,14 +1,14 @@
-description = "Per-rig worker monitor patrol loop.\n\nThe Witness is the Pit Boss for your rig. You watch polecats, nudge them toward\ncompletion, verify clean git state before kills, and escalate stuck workers.\n\n**You do NOT do implementation work.** Your job is oversight, not coding.\n\n## Design Philosophy\n\nThis patrol follows Gas Town principles:\n- **Discovery over tracking**: Observe reality each cycle, don't maintain state\n- **Events over state**: POLECAT_DONE mail triggers cleanup wisps\n- **Cleanup wisps as finalizers**: Pending cleanups are wisps, not queue entries\n- **Task tool for parallelism**: Subagents inspect polecats, not molecule arms\n\n## Patrol Shape (Linear, Deacon-style)\n\n```\ninbox-check ─► process-cleanups ─► check-refinery ─► survey-workers\n                                                            │\n         ┌──────────────────────────────────────────────────┘\n         ▼\n  check-swarm ─► ping-deacon ─► patrol-cleanup ─► context-check ─► loop-or-exit\n```\n\nNo dynamic arms. No fanout gates. No persistent nudge counters.\nState is discovered each cycle from reality (tmux, beads, mail)."
+description = "Per-rig worker monitor patrol loop.\n\nThe Witness is the Pit Boss for your rig. You watch polecats, nudge them toward\ncompletion, verify clean git state before kills, and escalate stuck workers.\n\n**You do NOT do implementation work.** Your job is oversight, not coding.\n\n## Ephemeral Polecat Model\n\nPolecats are truly ephemeral - done at MR submission, recyclable immediately:\n\n```\nPolecat lifecycle: spawning → working → mr_submitted → nuked\nMR lifecycle:      created → queued → processed → merged (Refinery handles)\n```\n\nOnce a polecat's branch is pushed (cleanup_status=clean), the polecat can be\nnuked immediately. The MR continues independently in the Refinery. If conflicts\narise, Refinery creates a NEW conflict-resolution task for a NEW polecat.\n\n**Key principle**: Polecat lifecycle is separate from MR lifecycle.\n\n## Design Philosophy\n\nThis patrol follows Gas Town principles:\n- **Discovery over tracking**: Observe reality each cycle, don't maintain state\n- **Events over state**: POLECAT_DONE mail triggers immediate cleanup\n- **Ephemeral by default**: Clean polecats are nuked immediately, no waiting\n- **Cleanup wisps for exceptions**: Only created when intervention needed\n- **Task tool for parallelism**: Subagents inspect polecats, not molecule arms\n\n## Patrol Shape (Linear, Deacon-style)\n\n```\ninbox-check ─► process-cleanups ─► check-refinery ─► survey-workers\n                                                            │\n         ┌──────────────────────────────────────────────────┘\n         ▼\n  check-timer-gates ─► check-swarm ─► ping-deacon ─► patrol-cleanup ─► context-check ─► loop-or-exit\n```\n\nNo dynamic arms. No fanout gates. No persistent nudge counters.\nState is discovered each cycle from reality (tmux, beads, mail)."
 formula = 'mol-witness-patrol'
 version = 2
 
 [[steps]]
-description = "Check inbox and handle messages.\n\n```bash\ngt mail inbox\n```\n\nFor each message:\n\n**POLECAT_STARTED**:\nA new polecat has started working. Acknowledge and archive.\n```bash\n# Acknowledge startup (optional: log for activity tracking)\ngt mail archive <message-id>\n```\nNo action needed beyond acknowledgment - archive immediately.\n\n**POLECAT_DONE / LIFECYCLE:Shutdown**:\nCreate a cleanup wisp for this polecat:\n```bash\nbd create --wisp --title \"cleanup:<polecat>\" --description \"Verify and cleanup polecat <name>\" --labels cleanup,polecat:<name>,state:pending\n```\nThe wisp's existence IS the pending cleanup. Process in next step.\n**Do NOT archive yet** - archive after cleanup completes (in MERGED handling).\n\n**MERGED**:\nA branch was merged successfully. Complete the cleanup.\n```bash\n# Find the cleanup wisp for this polecat\nbd list --wisp --labels=polecat:<name>,state:merge-requested --status=open\n\n# If found, proceed with full polecat nuke:\n# - Kill Claude session\n# - Delete worktree\n# - Delete branch\n# - Remove agent bead\ngt polecat nuke <name>\n\n# Burn the cleanup wisp\nbd close <wisp-id>\n\n# NOW archive both the MERGED mail and the original POLECAT_DONE mail\n# (The POLECAT_DONE message ID should be tracked in the cleanup wisp or MR bead)\ngt mail archive <merged-message-id>\ngt mail archive <polecat-done-message-id>  # If tracked\n```\nArchive after cleanup is complete.\n\n**HELP / Blocked**:\nAssess the request. Can you help? If not, escalate to Mayor:\n```bash\ngt mail send mayor/ -s \"Escalation: <polecat> needs help\" -m \"<details>\"\n```\nArchive after handling (escalated or resolved):\n```bash\ngt mail archive <message-id>\n```\n\n**HANDOFF**:\nRead predecessor context. Continue from where they left off.\nArchive after absorbing context:\n```bash\ngt mail archive <message-id>\n```\n\n**SWARM_START**:\nMayor initiating batch polecat work. Initialize swarm tracking.\n```bash\n# Parse swarm info from mail body: {\"swarm_id\": \"batch-123\", \"beads\": [\"bd-a\", \"bd-b\"]}\nbd create --wisp --title \"swarm:<swarm_id>\" --description \"Tracking batch: <swarm_id>\" --labels swarm,swarm_id:<swarm_id>,total:<N>,completed:0,start:<timestamp>\n```\nArchive after creating swarm tracking wisp:\n```bash\ngt mail archive <message-id>\n```\n\n**Hygiene principle**: Archive messages after they're fully processed.\nKeep only: active work, unprocessed requests. Inbox should be near-empty."
+description = "Check inbox and handle messages.\n\n```bash\ngt mail inbox\n```\n\nFor each message:\n\n**POLECAT_STARTED**:\nA new polecat has started working. Acknowledge and archive.\n```bash\n# Acknowledge startup (optional: log for activity tracking)\ngt mail archive <message-id>\n```\nNo action needed beyond acknowledgment - archive immediately.\n\n**POLECAT_DONE / LIFECYCLE:Shutdown**:\n\n*EPHEMERAL MODEL*: Polecats are truly ephemeral - done at MR submission,\nrecyclable immediately. Once the branch is pushed (cleanup_status=clean),\nthe polecat can be nuked. The MR lifecycle continues independently in the\nRefinery. If conflicts arise, Refinery creates a NEW conflict-resolution\ntask for a NEW polecat.\n\nPolecat lifecycle: spawning → working → mr_submitted → nuked\nMR lifecycle: created → queued → processed → merged (handled by Refinery)\n\nThe handler (HandlePolecatDone) will:\n1. Check cleanup_status from agent bead\n2. If \"clean\" (branch pushed): AUTO-NUKE immediately, archive mail\n3. If dirty: Create cleanup wisp for manual intervention\n\n```bash\n# The handler does this automatically:\n# - For clean state: gt polecat nuke <name> → archive mail\n# - For dirty state: create wisp → process in next step\n```\n\nCleanup wisps are only created when something is wrong (uncommitted changes,\nunpushed commits). Most POLECAT_DONE messages result in immediate nuke.\n\n**MERGED**:\nA branch was merged successfully. This is informational in the ephemeral model\nsince the polecat was already nuked after MR submission.\n\nIf a cleanup wisp exists (dirty state), complete the cleanup:\n```bash\n# Find the cleanup wisp for this polecat\nbd list --wisp --labels=polecat:<name>,state:merge-requested --status=open\n\n# If found, proceed with full polecat nuke:\ngt polecat nuke <name>\n\n# Burn the cleanup wisp\nbd close <wisp-id>\n```\nArchive after cleanup is complete.\n\n**HELP / Blocked**:\nAssess the request. Can you help? If not, escalate to Mayor:\n```bash\ngt mail send mayor/ -s \"Escalation: <polecat> needs help\" -m \"<details>\"\n```\nArchive after handling (escalated or resolved):\n```bash\ngt mail archive <message-id>\n```\n\n**HANDOFF**:\nRead predecessor context. Continue from where they left off.\nArchive after absorbing context:\n```bash\ngt mail archive <message-id>\n```\n\n**SWARM_START**:\nMayor initiating batch polecat work. Initialize swarm tracking.\n```bash\n# Parse swarm info from mail body: {\"swarm_id\": \"batch-123\", \"beads\": [\"bd-a\", \"bd-b\"]}\nbd create --wisp --title \"swarm:<swarm_id>\" --description \"Tracking batch: <swarm_id>\" --labels swarm,swarm_id:<swarm_id>,total:<N>,completed:0,start:<timestamp>\n```\nArchive after creating swarm tracking wisp:\n```bash\ngt mail archive <message-id>\n```\n\n**Hygiene principle**: Archive messages after they're fully processed.\nKeep only: active work, unprocessed requests. Inbox should be near-empty."
 id = 'inbox-check'
 title = 'Process witness mail'
 
 [[steps]]
-description = "Find and process cleanup wisps (the finalizer pattern).\n\n```bash\n# Find all cleanup wisps\nbd list --wisp --labels=cleanup --status=open\n```\n\nFor each cleanup wisp, check its state label:\n\n## State: pending (needs verification → MERGE_READY)\n\n1. **Extract polecat name** from wisp title/labels\n\n2. **Pre-kill verification**:\n```bash\ncd polecats/<name>\ngit status                    # Must be clean\ngit log origin/main..HEAD     # Commits should be pushed\nbd show <assigned-issue>      # Issue closed or deferred\n```\n\n3. **Get branch and issue info**:\n```bash\n# Get current branch\ngit rev-parse --abbrev-ref HEAD\n\n# Get the hook_bead from agent bead\nbd show <agent-bead>   # Look for hook_bead field\n```\n\n4. **Verify productive work** (ZFC - you make the call):\n   - Check git log for commits mentioning the issue\n   - Legitimate exceptions: already fixed, duplicate, deferred\n   - If closing as 'done' with no commits, flag for review\n\n5. **If clean**: Send MERGE_READY to refinery\n```bash\ngt mail send <rig>/refinery -s \"MERGE_READY <polecat>\" -m \"Branch: <branch>\nIssue: <issue-id>\nPolecat: <polecat>\nVerified: clean git state, issue closed\"\n```\nThen update the wisp to merge-requested state:\n```bash\nbd update <wisp-id> --labels cleanup,polecat:<name>,state:merge-requested\n```\n**Do NOT kill the polecat yet** - wait for MERGED confirmation from refinery.\n\n6. **If dirty**: Leave wisp open, log the issue, retry next cycle.\n\n## State: merge-requested (waiting for refinery)\n\nSkip - waiting for MERGED mail from refinery. The inbox-check step handles\nMERGED messages and completes these cleanup wisps.\n\n**Parallelism**: Use Task tool subagents to process multiple cleanups concurrently.\nEach cleanup is independent - perfect for parallel execution."
+description = "Process cleanup wisps (exception handling for dirty polecats).\n\nIn the ephemeral model, cleanup wisps are only created when a polecat has\ndirty state (uncommitted changes, unpushed commits) that prevented immediate\nnuke. Most polecats are nuked immediately on POLECAT_DONE and never create wisps.\n\n```bash\n# Find all cleanup wisps\nbd list --wisp --labels=cleanup --status=open\n```\n\nIf no wisps, skip this step (most common case in ephemeral model).\n\nFor each cleanup wisp, investigate and resolve the dirty state:\n\n## State: pending (needs investigation)\n\n1. **Extract polecat name** from wisp title/labels\n\n2. **Diagnose the problem**:\n```bash\ncd polecats/<name>\ngit status                    # What's uncommitted?\ngit stash list                # Any stashed work?\ngit log origin/main..HEAD     # Any unpushed commits?\n```\n\n3. **Resolution options**:\n   - **Uncommitted changes**: Commit and push, then nuke\n   - **Stashed work**: Pop and commit, or discard if not valuable\n   - **Unpushed commits**: Push to origin, then nuke\n   - **All valuable work lost**: Escalate to Mayor for recovery\n\n4. **If resolvable locally**: Fix and nuke\n```bash\n# Example: push unpushed commits\ngit push origin HEAD\n\n# Then nuke\ngt polecat nuke <name>\n\n# Close the wisp\nbd close <wisp-id> --reason \"Resolved: pushed commits, nuked\"\n```\n\n5. **If needs escalation**: Send RECOVERY_NEEDED to Mayor\n```bash\ngt mail send mayor/ -s \"RECOVERY_NEEDED <rig>/<polecat>\" \\\n  -m \"Cleanup Status: <status>\nBranch: <branch>\nIssue: <issue-id>\n\nCannot auto-resolve. Please advise.\"\n```\nLeave wisp open until Mayor resolves.\n\n## State: merge-requested (legacy, rare)\n\nThis state was used before the ephemeral model. If found, the polecat is\nwaiting for a MERGED signal. The inbox-check step handles these.\n\n**Parallelism**: Use Task tool subagents to process multiple cleanups concurrently.\nEach cleanup is independent - perfect for parallel execution."
 id = 'process-cleanups'
 needs = ['inbox-check']
 title = 'Process pending cleanup wisps'
@@ -20,15 +20,21 @@ needs = ['process-cleanups']
 title = 'Ensure refinery is alive'
 
 [[steps]]
-description = "Survey all polecats using agent beads (ZFC: trust what agents report).\n\n**Step 1: List polecat agent beads**\n\n```bash\nbd list --type=agent --json\n```\n\nFilter the JSON output for entries where description contains `role_type: polecat`.\nEach polecat agent bead has fields in its description:\n- `role_type: polecat`\n- `rig: <rig-name>`\n- `agent_state: running|idle|stuck|done`\n- `hook_bead: <current-work-id>`\n\n**Step 2: For each polecat, check agent_state**\n\n| agent_state | Meaning | Action |\n|-------------|---------|--------|\n| running | Actively working | Check progress (Step 3) |\n| idle | No work assigned | Auto-nuke if clean (Step 3a) |\n| stuck | Self-reported stuck | Handle stuck protocol |\n| done | Work complete | Verify cleanup triggered (see Step 4a) |\n\n**Step 3: For running polecats, assess progress**\n\nCheck the hook_bead field to see what they're working on:\n```bash\nbd show <hook_bead>  # See current step/issue\n```\n\nYou can also verify they're responsive:\n```bash\ntmux capture-pane -t gt-<rig>-<name> -p | tail -20\n```\n\nLook for:\n- Recent tool activity → making progress\n- Idle at prompt → may need nudge\n- Error messages → may need help\n\n**Step 3a: For idle polecats, auto-nuke if clean**\n\nWhen agent_state=idle, the polecat has no work assigned. Check if it's safe to nuke:\n\n```bash\n# Check git status in the polecat's worktree\ncd polecats/<name>\ngit status --porcelain         # Should be empty (clean)\ngit log origin/main..HEAD      # Should have no unpushed commits\n```\n\n**If clean** (no uncommitted changes, no unpushed commits):\n```bash\n# Safe to nuke - no work to lose\ngt polecat nuke <name>\n```\nLog the auto-nuke for audit purposes. No escalation needed.\n\n**If dirty** (uncommitted or unpushed work):\n```bash\n# Escalate to Mayor - polecat has work that might be valuable\ngt mail send mayor/ -s \\\"IDLE_DIRTY: <polecat> has uncommitted work\\\" \\\n  -m \\\"Polecat: <name>\nState: idle (no hook_bead)\nGit status: <uncommitted-files>\nUnpushed commits: <count>\n\nPlease advise: recover work or discard?\\\"\n```\n\n**Rationale**: Idle polecats with clean git state are pure overhead. They have\nno work and no state worth preserving. Nuking them immediately frees resources\nand reduces noise. Only escalate when there's actual work at risk.\n\n**Step 4: Decide action**\n\n| Observation | Action |\n|-------------|--------|\n| agent_state=running, recent activity | None |\n| agent_state=running, idle 5-15 min | Gentle nudge |\n| agent_state=running, idle 15+ min | Direct nudge with deadline |\n| agent_state=stuck | Assess and help or escalate |\n| agent_state=done | Verify cleanup triggered (see Step 4a) |\n\n**Step 4a: Handle agent_state=done**\n\nCheck if a cleanup wisp exists for this polecat:\n```bash\nbd list --wisp --labels=polecat:<name> --status=open\n```\n\nIf cleanup wisp exists:\n- state:pending → Will be processed in process-cleanups\n- state:merge-requested → Waiting for refinery MERGED response\n\nIf NO cleanup wisp exists (POLECAT_DONE mail missed):\nCreate one to trigger the cleanup flow:\n```bash\nbd create --wisp --title \"cleanup:<polecat>\" --description \"Discovered done polecat without cleanup wisp\" --labels cleanup,polecat:<name>,state:pending\n```\nThis ensures done polecats eventually get cleaned up even if mail was lost.\n\n**Step 5: Execute nudges**\n```bash\ngt nudge <rig>/polecats/<name> \"How's progress? Need help?\"\n```\n\n**Step 6: Escalate if needed**\n```bash\ngt mail send mayor/ -s \"Escalation: <polecat> stuck\" \\\n  -m \"Polecat <name> reports stuck. Please intervene.\"\n```\n\n**Parallelism**: Use Task tool subagents to inspect multiple polecats concurrently.\n\n**ZFC Principle**: Trust agent_state from beads. Don't infer state from PID/tmux."
+description = "Survey all polecats using agent beads (ZFC: trust what agents report).\n\n**Step 1: List polecat agent beads**\n\n```bash\nbd list --type=agent --json\n```\n\nFilter the JSON output for entries where description contains `role_type: polecat`.\nEach polecat agent bead has fields in its description:\n- `role_type: polecat`\n- `rig: <rig-name>`\n- `agent_state: running|idle|stuck|done`\n- `hook_bead: <current-work-id>`\n\n**Step 2: For each polecat, check agent_state**\n\n| agent_state | Meaning | Action |\n|-------------|---------|--------|\n| running | Actively working | Check progress (Step 3) |\n| idle | No work assigned | Auto-nuke if clean (Step 3a) |\n| stuck | Self-reported stuck | Handle stuck protocol |\n| done | Work complete | Verify cleanup triggered (see Step 4a) |\n\n**Step 3: For running polecats, assess progress**\n\nCheck the hook_bead field to see what they're working on:\n```bash\nbd show <hook_bead>  # See current step/issue\n```\n\nYou can also verify they're responsive:\n```bash\ntmux capture-pane -t gt-<rig>-<name> -p | tail -20\n```\n\nLook for:\n- Recent tool activity → making progress\n- Idle at prompt → may need nudge\n- Error messages → may need help\n\n**Step 3a: For idle polecats, auto-nuke if clean**\n\nWhen agent_state=idle, the polecat has no work assigned. Check if it's safe to nuke:\n\n```bash\n# Check git status in the polecat's worktree\ncd polecats/<name>\ngit status --porcelain         # Should be empty (clean)\ngit log origin/main..HEAD      # Should have no unpushed commits\n```\n\n**If clean** (no uncommitted changes, no unpushed commits):\n```bash\n# Safe to nuke - no work to lose\ngt polecat nuke <name>\n```\nLog the auto-nuke for audit purposes. No escalation needed.\n\n**If dirty** (uncommitted or unpushed work):\n```bash\n# Escalate to Mayor - polecat has work that might be valuable\ngt mail send mayor/ -s \\\"IDLE_DIRTY: <polecat> has uncommitted work\\\" \\\n  -m \\\"Polecat: <name>\nState: idle (no hook_bead)\nGit status: <uncommitted-files>\nUnpushed commits: <count>\n\nPlease advise: recover work or discard?\\\"\n```\n\n**Rationale**: Idle polecats with clean git state are pure overhead. They have\nno work and no state worth preserving. Nuking them immediately frees resources\nand reduces noise. Only escalate when there's actual work at risk.\n\n**Step 4: Decide action**\n\n| Observation | Action |\n|-------------|--------|\n| agent_state=running, recent activity | None |\n| agent_state=running, idle 5-15 min | Gentle nudge |\n| agent_state=running, idle 15+ min | Direct nudge with deadline |\n| agent_state=stuck | Assess and help or escalate |\n| agent_state=done | Verify cleanup triggered (see Step 4a) |\n\n**Step 4a: Handle agent_state=done**\n\nIn the ephemeral model, polecats with agent_state=done and cleanup_status=clean\nshould already be nuked by HandlePolecatDone. Finding one here indicates:\n\n1. **Stale agent bead** - polecat was nuked but bead remains\n   ```bash\n   # Verify polecat doesn't exist anymore\n   ls polecats/<name> 2>/dev/null || echo \"Already nuked\"\n   ```\n   If nuked, the agent bead is stale. Clean it up or ignore.\n\n2. **Cleanup wisp exists** - polecat has dirty state needing intervention\n   ```bash\n   bd list --wisp --labels=polecat:<name> --status=open\n   ```\n   Process in process-cleanups step.\n\n3. **No wisp, polecat exists** - POLECAT_DONE mail was missed\n   Try auto-nuke directly (ephemeral model):\n   ```bash\n   # Check cleanup_status and nuke if clean\n   gt polecat nuke <name>  # Will fail if dirty\n   ```\n   If nuke fails (dirty state), create cleanup wisp for investigation.\n\n**Step 5: Execute nudges**\n```bash\ngt nudge <rig>/polecats/<name> \"How's progress? Need help?\"\n```\n\n**Step 6: Escalate if needed**\n```bash\ngt mail send mayor/ -s \"Escalation: <polecat> stuck\" \\\n  -m \"Polecat <name> reports stuck. Please intervene.\"\n```\n\n**Parallelism**: Use Task tool subagents to inspect multiple polecats concurrently.\n\n**ZFC Principle**: Trust agent_state from beads. Don't infer state from PID/tmux."
 id = 'survey-workers'
 needs = ['check-refinery']
 title = 'Inspect all active polecats'
 
+[[steps]]
+description = "Check for expired timer gates and escalate as needed.\n\nTimer gates are async wait conditions with a timeout. When the timeout expires,\nthe gate should be escalated to the overseer for human intervention.\n\n**Step 1: Run timer gate check**\n```bash\nbd gate check --type=timer --escalate\n```\n\nThis command:\n1. Finds all open gate issues with await_type=timer\n2. Checks if `now > created_at + timeout`\n3. Escalates expired gates via `gt escalate` (HIGH severity)\n4. Reports summary of gate status\n\n**Step 2: Review output**\n\nIf expired gates were found and escalated:\n- The escalation creates an audit trail bead\n- Overseer will be notified via mail\n- Gate remains open until manually resolved\n\nIf no expired gates:\n- Continue patrol normally\n\n**Note**: Timer gates do NOT auto-close on expiration. They escalate.\nThis ensures human oversight of timeout conditions.\n\n**Parallelism**: This is a single command, no parallel execution needed."
+id = 'check-timer-gates'
+needs = ['survey-workers']
+title = 'Check timer gates for expiration'
+
 [[steps]]
 description = "If Mayor started a batch (SWARM_START), check if all polecats have completed.\n\n**Step 1: Find active swarm tracking wisps**\n```bash\nbd list --wisp --labels=swarm --status=open\n```\nIf no active swarm, skip this step.\n\n**Step 2: Count completed polecats for this swarm**\n\nExtract from wisp labels: swarm_id, total, completed, start timestamp.\nCheck how many cleanup wisps have been closed for this swarm's polecats.\n\n**Step 3: If all complete, notify Mayor**\n```bash\ngt mail send mayor/ -s \"SWARM_COMPLETE: <swarm_id>\" -m \"All <total> polecats merged.\nDuration: <minutes> minutes\nSwarm: <swarm_id>\"\n\n# Close the swarm tracking wisp\nbd close <swarm-wisp-id> --reason \"All polecats merged\"\n```\n\nNote: Runs every patrol cycle. Notification sent exactly once when all complete."
 id = 'check-swarm-completion'
-needs = ['survey-workers']
+needs = ['check-timer-gates']
 title = 'Check if active swarm is complete'
 
 [[steps]]
@@ -38,7 +44,7 @@ needs = ['check-swarm-completion']
 title = 'Ping Deacon for health check'
 
 [[steps]]
-description = "Verify inbox hygiene before ending patrol cycle.\n\n**Step 1: Check inbox state**\n```bash\ngt mail inbox\n```\n\nInbox should contain ONLY:\n- Unprocessed messages (just arrived, will handle next cycle)\n- Active work markers (POLECAT_DONE waiting for MERGED confirmation)\n\n**Step 2: Archive any stale messages**\n\nLook for messages that were processed but not archived:\n- POLECAT_STARTED older than this cycle → archive\n- HELP/Blocked that was escalated → archive\n- SWARM_START that created tracking wisp → archive\n\n```bash\n# For each stale message found:\ngt mail archive <message-id>\n```\n\n**Step 3: Verify cleanup wisp hygiene**\n\nCheck that all cleanup wisps are in valid states:\n```bash\nbd list --wisp --labels=cleanup --status=open\n```\n\n- state:pending → Will be processed next cycle\n- state:merge-requested → Waiting for refinery\n\nIf any cleanup wisp is older than expected (>1 hour in merge-requested state),\nthe refinery may be stuck. This was checked in check-refinery step.\n\n**Goal**: Inbox should have ≤5 active messages at end of cycle."
+description = "Verify inbox hygiene before ending patrol cycle.\n\n**Step 1: Check inbox state**\n```bash\ngt mail inbox\n```\n\nIn the ephemeral model, most POLECAT_DONE messages are handled immediately\n(auto-nuke) and archived. Inbox should contain ONLY:\n- Unprocessed messages (just arrived, will handle next cycle)\n- MERGED notifications (informational, archive after reading)\n\n**Step 2: Archive any stale messages**\n\nLook for messages that were processed but not archived:\n- POLECAT_STARTED older than this cycle → archive\n- POLECAT_DONE that was auto-nuked → should be archived already\n- MERGED notifications → archive after acknowledging\n- HELP/Blocked that was escalated → archive\n- SWARM_START that created tracking wisp → archive\n\n```bash\n# For each stale message found:\ngt mail archive <message-id>\n```\n\n**Step 3: Verify cleanup wisp hygiene**\n\nIn the ephemeral model, cleanup wisps should be rare (only for dirty polecats):\n```bash\nbd list --wisp --labels=cleanup --status=open\n```\n\n- state:pending → Needs investigation in process-cleanups\n- state:merge-requested → Legacy state, handle in inbox-check\n\nIf cleanup wisps are accumulating, investigate why polecats aren't clean.\n\n**Goal**: Inbox should be nearly empty. Cleanup wisps should be rare."
 id = 'patrol-cleanup'
 needs = ['ping-deacon']
 title = 'End-of-cycle inbox hygiene'
@@ -50,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/last-touched

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

.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

@@ -35,6 +35,17 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "gt costs record"
+          }
+        ]
+      }
     ]
   }
 }

.claude/skills/handoff/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: handoff
+description: >
+  Hand off to a fresh Claude session. Use when context is full, you've finished
+  a logical chunk of work, or need a fresh perspective. Work continues from hook.
+allowed-tools: "Bash(gt handoff:*),Bash(gt mail send:*)"
+version: "1.0.0"
+author: "Gas Town"
+---
+
+# Handoff - Session Cycling for Gas Town Agents
+
+Hand off your current session to a fresh Claude instance while preserving work context.
+
+## When to Use
+
+- Context getting full (approaching token limit)
+- Finished a logical chunk of work
+- Need a fresh perspective on a problem
+- Human requests session cycling
+
+## Usage
+
+```
+/handoff [optional message]
+```
+
+## How It Works
+
+1. If you provide a message, it's sent as handoff mail to yourself
+2. `gt handoff` respawns your session with a fresh Claude
+3. New session auto-primes via SessionStart hook
+4. Work continues from your hook (pinned molecule persists)
+
+## Examples
+
+```bash
+# Simple handoff (molecule persists, fresh context)
+/handoff
+
+# Handoff with context notes
+/handoff "Found the bug in token refresh - check line 145 in auth.go first"
+```
+
+## What Persists
+
+- **Hooked molecule**: Your work assignment stays on your hook
+- **Beads state**: All issues, dependencies, progress
+- **Git state**: Commits, branches, staged changes
+
+## What Resets
+
+- **Conversation context**: Fresh Claude instance
+- **TodoWrite items**: Ephemeral, session-scoped
+- **In-memory state**: Any uncommitted analysis
+
+## Implementation
+
+When invoked, execute:
+
+1. If user provided a message, send handoff mail:
+   ```bash
+   gt mail send <your-address> -s "HANDOFF: Session cycling" -m "<message>"
+   ```
+
+2. Run the handoff command:
+   ```bash
+   gt handoff
+   ```
+
+The new session will find your handoff mail and hooked work automatically.

.githooks/pre-push

@@ -0,0 +1,33 @@
+#!/bin/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
+  branch="${remote_ref#refs/heads/}"
+
+  case "$branch" in
+    main|beads-sync|polecat/*)
+      # Allowed branches
+      ;;
+    *)
+      echo "ERROR: Invalid branch for Gas Town agents."
+      echo ""
+      echo "Blocked push to: $branch"
+      echo ""
+      echo "Allowed branches:"
+      echo "  main        - Crew workers push here directly"
+      echo "  polecat/*   - Polecat working branches"
+      echo "  beads-sync  - Beads synchronization"
+      echo ""
+      echo "Do NOT create PRs. Push to main or let Refinery merge polecat work."
+      exit 1
+      ;;
+  esac
+done
+
+exit 0

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

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

.github/workflows/ci.yml

@@ -33,6 +33,36 @@ 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
@@ -71,3 +101,31 @@ jobs:
         with:
           version: latest
           args: --timeout=5m
+
+  integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - 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: Install beads (bd)
+        run: go install github.com/steveyegge/beads/cmd/bd@latest
+
+      - name: Build gt
+        run: go build -v -o gt ./cmd/gt
+
+      - name: Add to PATH
+        run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+
+      - name: Integration Tests
+        run: go test -tags=integration -timeout=5m -v ./internal/cmd/...

.github/workflows/integration.yml

@@ -0,0 +1,45 @@
+name: Integration Tests
+
+on:
+  pull_request:
+    paths:
+      - 'internal/cmd/install.go'
+      - 'internal/cmd/rig.go'
+      - 'internal/config/**'
+      - 'internal/routing/**'
+      - 'internal/cmd/*_integration_test.go'
+      - '.github/workflows/integration.yml'
+
+jobs:
+  integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+          cache: true
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "CI Bot"
+          git config --global user.email "ci@gastown.test"
+
+      - name: Install beads (bd)
+        run: go install github.com/steveyegge/beads/cmd/bd@latest
+
+      - name: Add to PATH
+        run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+
+      - name: Generate embedded files
+        run: go generate ./internal/formula/...
+
+      - name: Build
+        run: go build -v ./cmd/gt
+
+      - name: Run integration tests
+        run: go test -v -tags=integration -timeout=4m ./internal/cmd/...

.gitignore

@@ -17,6 +17,9 @@
 .DS_Store
 Thumbs.db
 
+# Claude Code local state
+.claude/
+
 # Test
 coverage.out
 *.test
@@ -29,7 +32,20 @@ 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-wisp/
 
 # Clone-specific CLAUDE.md (regenerated locally per clone)
 CLAUDE.md
+
+# Embedded formulas are committed so `go install @latest` works
+# Run `go generate ./...` after modifying .beads/formulas/

.golangci.yml

@@ -29,6 +29,11 @@ linters:
         - (os).Chdir
         - (os).MkdirAll
         - (fmt).Sscanf
+        # fmt.Fprintf/Fprintln errors are typically safe to ignore for logging
+        - fmt.Fprintf
+        - fmt.Fprintln
+        - (fmt).Fprintf
+        - (fmt).Fprintln
     misspell:
       locale: US
 
@@ -39,17 +44,30 @@ linters:
         linters:
           - gosec
         text: "G304"
+      # G304: Config/state file loading uses constructed paths, not user input
+      # All internal packages read files from constructed paths, not user input
+      - path: 'internal/'
+        linters:
+          - gosec
+        text: "G304"
       # G306: File permissions 0644 in tests are acceptable (test fixtures)
       - path: '_test\.go'
         linters:
           - gosec
         text: "G306"
+      # G302/G306: Non-sensitive operational files (state, config, logs) can use 0644
+      # Internal packages write non-sensitive operational data files
+      - path: 'internal/'
+        linters:
+          - gosec
+        text: "G306|G302"
       # G302/G306: Directory/file permissions 0700/0750 are acceptable
       - linters:
           - gosec
         text: "G302.*0700|G301.*0750"
-      # G204: Safe subprocess launches with validated arguments (tmux, git, etc.)
-      - path: 'internal/tmux/|internal/git/|internal/cmd/'
+      # G204: Safe subprocess launches with validated arguments (internal tools)
+      # All internal packages use subprocess calls for trusted internal tools
+      - path: 'internal/'
         linters:
           - gosec
         text: 'G204'

AGENTS.md

@@ -29,3 +29,22 @@ This file exists for compatibility with tools that look for AGENTS.md.
 - 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.

CHANGELOG.md

@@ -5,6 +5,179 @@ All notable changes to the Gas Town project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [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.
+
+### Added
+
+#### Convoy Dashboard (Web UI)
+- **`gt dashboard` command** - Launch web-based monitoring UI for Gas Town (#71)
+- **Polecat Workers section** - Real-time activity monitoring with tmux session timestamps
+- **Refinery Merge Queue display** - Always-visible MR queue status
+- **Dynamic work status** - Convoy status columns with live updates
+- **HTMX auto-refresh** - 10-second refresh interval for real-time monitoring
+
+#### Two-Level Beads Architecture
+- **Town-level beads** (`~/gt/.beads/`) - `hq-*` prefix for Mayor mail and cross-rig coordination
+- **Rig-level beads** - Project-specific issues with rig prefixes (e.g., `gt-*`)
+- **`gt migrate-agents` command** - Migration tool for two-level architecture (#nnub1)
+- **TownBeadsPrefix constant** - Centralized `hq-` prefix handling
+- **Prefix-based routing** - Commands auto-route to correct rig via `routes.jsonl`
+
+#### Multi-Agent Support
+- **Pluggable agent registry** - Multi-agent support with configurable providers (#107)
+- **Multi-rig management** - `gt rig start/stop/restart/status` for batch operations (#11z8l)
+- **`gt crew stop` command** - Stop crew sessions cleanly
+- **`spawn` alias** - Alternative to `start` for all role subcommands
+- **Batch slinging** - `gt sling` supports multiple beads to a rig in one command (#l9toz)
+
+#### Ephemeral Polecat Model
+- **Immediate recycling** - Polecats recycled after each work unit (#81)
+- **Updated patrol formula** - Witness formula adapted for ephemeral model
+- **`mol-polecat-work` formula** - Updated for ephemeral polecat lifecycle (#si8rq.4)
+
+#### Cost Tracking
+- **`gt costs` command** - Session cost tracking and reporting
+- **Beads-based storage** - Costs stored in beads instead of JSONL (#f7jxr)
+- **Stop hook integration** - Auto-record costs on session end
+- **Tmux session auto-detection** - Costs hook finds correct session
+
+#### Conflict Resolution
+- **Conflict resolution workflow** - Formula-based conflict handling for polecats (#si8rq.5)
+- **Merge-slot gate** - Refinery integration for ordered conflict resolution
+- **`gt done --phase-complete`** - Gate-based phase handoffs (#si8rq.7)
+
+#### Communication & Coordination
+- **`gt mail archive` multi-ID** - Archive multiple messages at once (#82)
+- **`gt mail --all` flag** - Clear all mail for agent ergonomics (#105q3)
+- **Convoy stranded detection** - Detect and feed stranded convoys (#8otmd)
+- **`gt convoy --tree`** - Show convoy + child status tree
+- **`gt convoy check`** - Cross-rig auto-close for completed convoys (#00qjk)
+
+#### Developer Experience
+- **Shell completion** - Installation instructions for bash/zsh/fish (#pdrh0)
+- **`gt prime --hook`** - LLM runtime session handling flag
+- **`gt doctor` enhancements** - Session-hooks check, repo-fingerprint validation (#nrgm5)
+- **Binary age detection** - `gt status` shows stale binary warnings (#42whv)
+- **Circuit breaker** - Automatic handling for stuck agents (#72cqu)
+
+#### Infrastructure
+- **SessionStart hooks** - Deployed during `gt install` for Mayor role
+- **`hq-dog-role` beads** - Town-level dog role initialization (#2jjry)
+- **Watchdog chain docs** - Boot/Deacon lifecycle documentation (#1847v)
+- **Integration tests** - CI workflow for `gt install` and `gt rig add` (#htlmp)
+- **Local repo reference clones** - Save disk space with `--reference` cloning
+
+### Changed
+
+- **Handoff migrated to skills** - `gt handoff` now uses skills format (#nqtqp)
+- **Crew workers push to main** - Documentation clarifies no PR workflow for crew
+- **Session names include town** - Mayor/Deacon sessions use town-prefixed names
+- **Formula semantics clarified** - Formulas are templates, not instructions
+- **Witness reports stopped** - No more routine Mayor reports (saves tokens)
+
+### Fixed
+
+#### Daemon & Session Stability
+- **Thread-safety** - Added locks for agent session resume support
+- **Orphan daemon prevention** - File locking prevents duplicate daemons (#108)
+- **Zombie tmux cleanup** - Kill zombie sessions before recreating (#vve6k)
+- **Tmux exact matching** - `HasSession` uses exact match to prevent prefix collisions
+- **Health check fallback** - Prevents killing healthy sessions on tmux errors
+
+#### Beads Integration
+- **Mayor/rig path** - Use correct path for beads to prevent prefix mismatch (#38)
+- **Agent bead creation** - Fixed during `gt rig add` (#32)
+- **bd daemon startup** - Circuit breaker and restart logic (#2f0p3)
+- **BEADS_DIR environment** - Correctly set for polecat hooks and cross-rig work
+
+#### Agent Workflows
+- **Default branch detection** - `gt done` no longer hardcodes 'main' (#42)
+- **Enter key retry** - Reliable Enter key delivery with retry logic (#53)
+- **SendKeys debounce** - Increased to 500ms for reliability
+- **MR bead closure** - Close beads after successful merge from queue (#52)
+
+#### Installation & Setup
+- **Embedded formulas** - Copy formulas to new installations (#86)
+- **Vestigial cleanup** - Remove `rigs/` directory and `state.json` files
+- **Symlink preservation** - Workspace detection preserves symlink paths (#3, #75)
+- **Golangci-lint errors** - Resolved errcheck and gosec issues (#76)
+
+### Contributors
+
+Thanks to all contributors for this release:
+- @kiwiupover - README updates (#109)
+- @michaellady - Convoy dashboard (#71), ResolveBeadsDir fix (#54)
+- @jsamuel1 - Dependency updates (#83)
+- @dannomayernotabot - Witness fixes (#87), daemon race condition (#64)
+- @markov-kernel - Mayor session hooks (#93), daemon init recommendation (#95)
+- @rawwerks - Multi-agent support (#107)
+- @jakehemmerle - Daemon orphan race condition (#108)
+- @danshapiro - Install role slots (#106), rig beads dir (#61)
+- @vessenes - Town session helpers (#91), install copy formulas (#86)
+- @kustrun - Init bugs (#34)
+- @austeane - README quickstart fix (#44)
+- @Avyukth - Patrol roles per-rig check (#26)
+
+## [0.1.1] - 2026-01-02
+
+### Fixed
+
+- **Tmux keybindings scoped to Gas Town sessions** - C-b n/p no longer override default tmux behavior in non-GT sessions (#13)
+
+### Added
+
+- **OSS project files** - CHANGELOG.md, .golangci.yml, RELEASING.md
+- **Version bump script** - `scripts/bump-version.sh` for releases
+- **Documentation fixes** - Corrected `gt rig add` and `gt crew add` CLI syntax (#6)
+- **Rig prefix routing** - Agent beads now use correct rig-specific prefixes (#11)
+- **Beads init fix** - Rig beads initialization targets correct database (#9)
+
 ## [0.1.0] - 2026-01-02
 
 ### Added

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build install clean test
+.PHONY: build install clean test generate
 
 BINARY := gt
 BUILD_DIR := .
@@ -12,7 +12,10 @@ 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)
 
-build:
+generate:
+	go generate ./...
+
+build: generate
 	go build -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY) ./cmd/gt
 ifeq ($(shell uname),Darwin)
 	@codesign -s - -f $(BUILD_DIR)/$(BINARY) 2>/dev/null || true

README.md

@@ -16,7 +16,7 @@ Multi-agent orchestrator for Claude Code. Track work with convoys; sling to agen
 - **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+** - for full stack mode (optional for minimal mode)
+- **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)
 
 ## Quick Start
@@ -25,30 +25,58 @@ Multi-agent orchestrator for Claude Code. Track work with convoys; sling to agen
 # Install
 go install github.com/steveyegge/gastown/cmd/gt@latest
 
-# Create workspace
-gt install ~/gt
+# Ensure Go binaries are in your PATH (add to ~/.zshrc or ~/.bashrc)
+export PATH="$PATH:$HOME/go/bin"
+
+# Create workspace (--git auto-initializes git repository)
+gt install ~/gt --git
+cd ~/gt
 
 # Add a project
 gt rig add myproject https://github.com/you/repo.git
 
-# Create a convoy and sling work (standard workflow)
+# Create your personal workspace
+gt crew add <yourname> --rig myproject
+
+# 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
-gt sling issue-456 myproject
 
-# Track progress on dashboard
+# Track progress
 gt convoy list
+
+# Switch between agent sessions
+gt agents
 ```
 
 ## 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.
+
 ```
 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
-└── Mayor                 Global coordinator
 ```
 
 **Hook**: Each agent has a hook where work hangs. On wake, run what's on your hook.
@@ -57,6 +85,26 @@ Town (~/gt/)              Your workspace
 
 ## Workflows
 
+### Full Stack (Recommended)
+
+The primary Gas Town experience. Agents run in tmux sessions with the Mayor as your interface.
+
+```bash
+gt start                               # Start Gas Town (daemon + Mayor session)
+gt mayor attach                        # Enter Mayor session
+
+# 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"
+
+# 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
+```
+
 ### Minimal (No Tmux)
 
 Run individual Claude Code instances manually. Gas Town just tracks state.
@@ -68,18 +116,6 @@ claude --resume                        # Agent reads mail, runs work
 gt convoy list                         # Check progress
 ```
 
-### Full Stack (Tmux)
-
-Agents run in tmux sessions. Daemon manages lifecycle.
-
-```bash
-gt daemon start                        # Start lifecycle manager
-gt convoy create "Feature X" issue-123 issue-456
-gt sling issue-123 myproject           # Spawns polecat automatically
-gt sling issue-456 myproject           # Another worker
-gt convoy list                         # Dashboard view
-```
-
 ### Pick Your Roles
 
 Gas Town is modular. Run what you need:
@@ -199,6 +235,22 @@ gt <role> attach                  # Jump into any agent session
                                   # e.g., gt mayor attach, gt witness attach
 ```
 
+### Configuration
+
+```bash
+gt config agent list [--json]     # List all agents (built-in + custom)
+gt config agent get <name>        # Show agent configuration
+gt config agent set <name> <cmd>  # Create or update custom agent
+gt config agent remove <name>     # Remove custom agent (built-ins protected)
+gt config default-agent [name]    # Get or set town default agent
+```
+
+**Example**: Use a cheaper model for most work:
+```bash
+gt config agent set claude-glm "claude-glm --model glm-4"
+gt config default-agent claude-glm
+```
+
 Most other work happens through agents - just ask them.
 
 ### For Agents
@@ -227,6 +279,63 @@ gt doctor                         # Health check
 gt doctor --fix                   # Auto-repair
 ```
 
+## Dashboard
+
+Web-based dashboard for monitoring Gas Town activity.
+
+```bash
+# Start the 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
+
+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 |
+
+## Shell Completions
+
+Enable tab completion for `gt` commands:
+
+### Bash
+
+```bash
+# Add to ~/.bashrc
+source <(gt completion bash)
+
+# 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
+gt completion zsh > "${fpath[1]}/_gt"
+```
+
+### Fish
+
+```bash
+gt completion fish > ~/.config/fish/completions/gt.fish
+```
+
 ## Roles
 
 | Role | Scope | Job |

docs/INSTALLING.md

@@ -184,7 +184,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

docs/architecture.md

@@ -0,0 +1,116 @@
+# Gas Town Architecture
+
+Technical architecture for Gas Town multi-agent workspace management.
+
+## Two-Level Beads Architecture
+
+Gas Town uses a two-level beads architecture to separate organizational coordination
+from project implementation work.
+
+| Level | Location | Prefix | Purpose |
+|-------|----------|--------|---------|
+| **Town** | `~/gt/.beads/` | `hq-*` | Cross-rig coordination, Mayor mail, agent identity |
+| **Rig** | `<rig>/mayor/rig/.beads/` | project prefix | Implementation work, MRs, project issues |
+
+### Town-Level Beads (`~/gt/.beads/`)
+
+Organizational chain for cross-rig coordination:
+- Mayor mail and messages
+- Convoy coordination (batch work across rigs)
+- Strategic issues and decisions
+- **Town-level agent beads** (Mayor, Deacon)
+- **Role definition beads** (global templates)
+
+### Rig-Level Beads (`<rig>/mayor/rig/.beads/`)
+
+Project chain for implementation work:
+- Bugs, features, tasks for the project
+- Merge requests and code reviews
+- Project-specific molecules
+- **Rig-level agent beads** (Witness, Refinery, Polecats)
+
+## Agent Bead Storage
+
+Agent beads track lifecycle state for each agent. Storage location depends on
+the agent's scope.
+
+| Agent Type | Scope | Bead Location | Bead ID Format |
+|------------|-------|---------------|----------------|
+| Mayor | Town | `~/gt/.beads/` | `hq-mayor` |
+| Deacon | Town | `~/gt/.beads/` | `hq-deacon` |
+| Dogs | Town | `~/gt/.beads/` | `hq-dog-<name>` |
+| Witness | Rig | `<rig>/.beads/` | `<prefix>-<rig>-witness` |
+| Refinery | Rig | `<rig>/.beads/` | `<prefix>-<rig>-refinery` |
+| Polecats | Rig | `<rig>/.beads/` | `<prefix>-<rig>-polecat-<name>` |
+
+### Role Beads
+
+Role beads are global templates stored in town beads with `hq-` prefix:
+- `hq-mayor-role` - Mayor role definition
+- `hq-deacon-role` - Deacon role definition
+- `hq-witness-role` - Witness role definition
+- `hq-refinery-role` - Refinery role definition
+- `hq-polecat-role` - Polecat role definition
+
+Each agent bead references its role bead via the `role_bead` field.
+
+## Agent Taxonomy
+
+### Town-Level Agents (Cross-Rig)
+
+| Agent | Role | Persistence |
+|-------|------|-------------|
+| **Mayor** | Global coordinator, handles cross-rig communication and escalations | Persistent |
+| **Deacon** | Daemon beacon - receives heartbeats, runs plugins and monitoring | Persistent |
+| **Dogs** | Long-running workers for cross-rig batch work | Variable |
+
+### Rig-Level Agents (Per-Project)
+
+| Agent | Role | Persistence |
+|-------|------|-------------|
+| **Witness** | Monitors polecat health, handles nudging and cleanup | Persistent |
+| **Refinery** | Processes merge queue, runs verification | Persistent |
+| **Polecats** | Ephemeral workers assigned to specific issues | Ephemeral |
+
+## Directory Structure
+
+```
+~/gt/                           Town root
+├── .beads/                     Town-level beads (hq-* prefix)
+│   ├── config.yaml             Beads configuration
+│   ├── issues.jsonl            Town issues (mail, agents, convoys)
+│   └── routes.jsonl            Prefix → rig routing table
+├── mayor/                      Mayor config
+│   └── town.json               Town configuration
+└── <rig>/                      Project container (NOT a git clone)
+    ├── config.json             Rig identity and beads prefix
+    ├── .beads/ → mayor/rig/.beads  Symlink to canonical beads
+    ├── .repo.git/              Bare repo (shared by worktrees)
+    ├── mayor/rig/              Mayor's clone (canonical beads)
+    ├── refinery/rig/           Worktree on main
+    ├── witness/                No clone (monitors only)
+    ├── crew/<name>/            Human workspaces
+    └── polecats/<name>/        Worker worktrees
+```
+
+## Beads Routing
+
+The `routes.jsonl` file maps issue ID prefixes to their storage locations:
+
+```jsonl
+{"prefix":"hq","path":"/Users/stevey/gt/.beads"}
+{"prefix":"gt","path":"/Users/stevey/gt/gastown/mayor/rig/.beads"}
+```
+
+This enables transparent cross-rig beads operations:
+
+```bash
+bd show hq-mayor    # Routes to town beads
+bd show gt-xyz      # Routes to gastown rig beads
+```
+
+## See Also
+
+- [reference.md](reference.md) - Command reference
+- [molecules.md](molecules.md) - Workflow molecules
+- [identity.md](identity.md) - Agent identity and BD_ACTOR

docs/escalation.md

@@ -225,7 +225,7 @@ EOF
 gt escalate --type decision --issue $ISSUE "Caching approach needs decision"
 
 # 3. Exit cleanly
-gt done --exit ESCALATED
+gt done --status ESCALATED
 ```
 
 ## Mayor Startup Check

docs/mail-protocol.md

@@ -25,7 +25,7 @@ MR: <mr-id>          # if exit=MERGED
 Branch: <branch>
 ```
 
-**Trigger**: `gt polecat done` command generates this automatically.
+**Trigger**: `gt done` command generates this automatically.
 
 **Handler**: Witness creates a cleanup wisp for the polecat.
 

docs/molecules.md

@@ -26,6 +26,31 @@ Protomolecule (frozen template) ─── Solid
 | **Wisp** | Ephemeral molecule for patrol cycles (never synced) |
 | **Digest** | Squashed summary of completed molecule |
 
+## Common Mistake: Reading Formulas Directly
+
+**WRONG:**
+```bash
+# Reading a formula file and manually creating beads for each step
+cat .beads/formulas/mol-polecat-work.formula.toml
+bd create --title "Step 1: Load context" --type task
+bd create --title "Step 2: Branch setup" --type task
+# ... creating beads from formula prose
+```
+
+**RIGHT:**
+```bash
+# Cook the formula into a proto, pour into a molecule
+bd cook mol-polecat-work
+bd mol pour mol-polecat-work --var issue=gt-xyz
+# Now work through the step beads that were created
+bd ready                    # Find next step
+bd close <step-id>          # Complete it
+```
+
+**Key insight:** Formulas are source templates (like source code). You never read
+them directly during work. The `cook` → `pour` pipeline creates step beads for you.
+Your molecule already has steps - use `bd ready` to find them.
+
 ## Navigating Molecules
 
 Molecules help you track where you are in multi-step workflows.

docs/operational-state.md

@@ -102,6 +102,9 @@ bd list --type=role --label=mode:degraded
 
 ## Boot: The Deacon's Watchdog
 
+> See [Watchdog Chain](watchdog-chain.md) for the complete Daemon/Boot/Deacon
+> architecture and design rationale.
+
 Boot is a dog (Deacon helper) that triages the Deacon's health. The daemon pokes
 Boot instead of the Deacon directly, centralizing the "when to wake" decision in
 an agent that can reason about it.
@@ -171,7 +174,7 @@ task nature matters.
 ~/gt/deacon/dogs/boot/
 ```
 
-Session name: `gt-deacon-boot`
+Session name: `gt-boot`
 
 Created/maintained by `bd doctor`.
 

docs/polecat-lifecycle.md

@@ -0,0 +1,225 @@
+# Polecat Lifecycle
+
+> Understanding the three-layer architecture of polecat workers
+
+## Overview
+
+Polecats have three distinct lifecycle layers that operate independently. Confusing
+these layers leads to heresies like "idle polecats" and misunderstanding when
+recycling occurs.
+
+## The Three Layers
+
+| Layer | Component | Lifecycle | Persistence |
+|-------|-----------|-----------|-------------|
+| **Session** | Claude (tmux pane) | Ephemeral | Cycles per step/handoff |
+| **Sandbox** | Git worktree | Persistent | Until nuke |
+| **Slot** | Name from pool | Persistent | Until nuke |
+
+### Session Layer
+
+The Claude session is **ephemeral**. It cycles frequently:
+
+- After each molecule step (via `gt handoff`)
+- On context compaction
+- On crash/timeout
+- After extended work periods
+
+**Key insight:** Session cycling is **normal operation**, not failure. The polecat
+continues working—only the Claude context refreshes.
+
+```
+Session 1: Steps 1-2 → handoff
+Session 2: Steps 3-4 → handoff
+Session 3: Step 5 → gt done
+```
+
+All three sessions are the **same polecat**. The sandbox and slot persist throughout.
+
+### Sandbox Layer
+
+The sandbox is the **git worktree**—the polecat's working directory:
+
+```
+~/gt/gastown/polecats/Toast/
+```
+
+This worktree:
+- Exists from `gt sling` until `gt polecat nuke`
+- Survives all session cycles
+- Contains uncommitted work, staged changes, branch state
+- Is independent of other polecat sandboxes
+
+The Witness never destroys sandboxes mid-work. Only `nuke` removes them.
+
+### Slot Layer
+
+The slot is the **name allocation** from the polecat pool:
+
+```bash
+# Pool: [Toast, Shadow, Copper, Ash, Storm...]
+# Toast is allocated to work gt-abc
+```
+
+The slot:
+- Determines the sandbox path (`polecats/Toast/`)
+- Maps to a tmux session (`gt-gastown-Toast`)
+- Appears in attribution (`gastown/polecats/Toast`)
+- Is released only on nuke
+
+## Correct Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        gt sling                             │
+│  → Allocate slot from pool (Toast)                         │
+│  → Create sandbox (worktree on new branch)                 │
+│  → Start session (Claude in tmux)                          │
+│  → Hook molecule to polecat                                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Work Happens                            │
+│                                                             │
+│  Session cycles happen here:                               │
+│  - gt handoff between steps                                │
+│  - Compaction triggers respawn                             │
+│  - Crash → Witness respawns                                │
+│                                                             │
+│  Sandbox persists through ALL session cycles               │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                        gt done                              │
+│  → Polecat signals completion to Witness                   │
+│  → Session exits (no idle waiting)                         │
+│  → Witness receives POLECAT_DONE event                     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│               Witness: gt polecat nuke                      │
+│  → Verify work landed (merged or in MQ)                    │
+│  → Delete sandbox (remove worktree)                        │
+│  → Kill tmux session                                       │
+│  → Release slot back to pool                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## What "Recycle" Means
+
+**Session cycling**: Normal. Claude restarts, sandbox stays, slot stays.
+
+```bash
+gt handoff  # Session cycles, polecat continues
+```
+
+**Sandbox recreation**: Repair only. Should be rare.
+
+```bash
+gt polecat repair Toast  # Emergency: recreate corrupted worktree
+```
+
+Session cycling happens constantly. Sandbox recreation should almost never happen
+during normal operation.
+
+## Anti-Patterns
+
+### Idle Polecats
+
+**Myth:** Polecats wait between tasks in an idle state.
+
+**Reality:** Polecats don't exist without work. The lifecycle is:
+1. Work assigned → polecat spawned
+2. Work done → polecat nuked
+3. There is no idle state
+
+If you see a polecat without work, something is broken. Either:
+- The hook was lost (bug)
+- The session crashed before loading context
+- Manual intervention corrupted state
+
+### Manual State Transitions
+
+**Anti-pattern:**
+```bash
+gt polecat done Toast    # DON'T: external state manipulation
+gt polecat reset Toast   # DON'T: manual lifecycle control
+```
+
+**Correct:**
+```bash
+# Polecat signals its own completion:
+gt done  # (from inside the polecat session)
+
+# Only Witness nukes polecats:
+gt polecat nuke Toast  # (from Witness, after verification)
+```
+
+Polecats manage their own session lifecycle. The Witness manages sandbox lifecycle.
+External manipulation bypasses verification.
+
+### Sandboxes Without Work
+
+**Anti-pattern:** A sandbox exists but no molecule is hooked.
+
+This means:
+- The polecat was spawned incorrectly
+- The hook was lost during crash
+- State corruption occurred
+
+**Recovery:**
+```bash
+# From Witness:
+gt polecat nuke Toast        # Clean slate
+gt sling gt-abc gastown      # Respawn with work
+```
+
+### Confusing Session with Sandbox
+
+**Anti-pattern:** Thinking session restart = losing work.
+
+```bash
+# Session ends (handoff, crash, compaction)
+# Work is NOT lost because:
+# - Git commits persist in sandbox
+# - Staged changes persist in sandbox
+# - Molecule state persists in beads
+# - Hook persists across sessions
+```
+
+The new session picks up where the old one left off via `gt prime`.
+
+## Session Lifecycle Details
+
+Sessions cycle for these reasons:
+
+| Trigger | Action | Result |
+|---------|--------|--------|
+| `gt handoff` | Voluntary | Clean cycle to fresh context |
+| Context compaction | Automatic | Forced by Claude Code |
+| Crash/timeout | Failure | Witness respawns |
+| `gt done` | Completion | Session exits, Witness takes over |
+
+All except `gt done` result in continued work. Only `gt done` signals completion.
+
+## Witness Responsibilities
+
+The Witness monitors polecats but does NOT:
+- Force session cycles (polecats self-manage via handoff)
+- Interrupt mid-step (unless truly stuck)
+- Recycle sandboxes between steps
+
+The Witness DOES:
+- Respawn crashed sessions
+- Nudge stuck polecats
+- Nuke completed polecats (after verification)
+- Handle escalations
+
+## Related Documentation
+
+- [Understanding Gas Town](understanding-gas-town.md) - Role taxonomy and architecture
+- [Polecat Wisp Architecture](polecat-wisp-architecture.md) - Molecule execution
+- [Propulsion Principle](propulsion-principle.md) - Why work triggers immediate execution

docs/polecat-wisp-architecture.md

@@ -12,7 +12,7 @@ They execute molecule steps sequentially, closing each step as they complete it.
 | Type | Storage | Use Case |
 |------|---------|----------|
 | **Regular Molecule** | `.beads/` (synced) | Discrete deliverables, audit trail |
-| **Wisp** | `.beads-wisp/` (ephemeral) | Patrol cycles, operational loops |
+| **Wisp** | `.beads/` (ephemeral, type=wisp) | Patrol cycles, operational loops |
 
 Polecats typically use **regular molecules** because each assignment has audit value.
 Patrol agents (Witness, Refinery, Deacon) use **wisps** to prevent accumulation.

docs/reference.md

@@ -215,6 +215,28 @@ gt doctor                    # Health check
 gt doctor --fix              # Auto-repair
 ```
 
+### Configuration
+
+```bash
+# Agent management
+gt config agent list [--json]     # List all agents (built-in + custom)
+gt config agent get <name>        # Show agent configuration
+gt config agent set <name> <cmd>  # Create or update custom agent
+gt config agent remove <name>     # Remove custom agent (built-ins protected)
+
+# Default agent
+gt config default-agent [name]    # Get or set town default agent
+```
+
+**Built-in agents**: `claude`, `gemini`, `codex`
+
+**Custom agents**: Define per-town in `mayor/town.json`:
+```bash
+gt config agent set claude-glm "claude-glm --model glm-4"
+gt config agent set claude "claude-opus"  # Override built-in
+gt config default-agent claude-glm       # Set default
+```
+
 ### Rig Management
 
 ```bash
@@ -323,7 +345,7 @@ Deacon, Witness, and Refinery run continuous patrol loops using wisps:
 |-------|-----------------|----------------|
 | **Deacon** | `mol-deacon-patrol` | Agent lifecycle, plugin execution, health checks |
 | **Witness** | `mol-witness-patrol` | Monitor polecats, nudge stuck workers |
-| **Refinery** | `mol-refinery-patrol` | Process merge queue, review PRs |
+| **Refinery** | `mol-refinery-patrol` | Process merge queue, review MRs |
 
 ```
 1. bd mol wisp mol-<role>-patrol

docs/test-coverage-review.md

@@ -0,0 +1,154 @@
+# Test Coverage and Quality Review
+
+**Reviewed by**: polecat/gus
+**Date**: 2026-01-04
+**Issue**: gt-a02fj.9
+
+## Executive Summary
+
+- **80 test files** covering **32 out of 42 packages** (76% package coverage)
+- **631 test functions** with 192 subtests (30% use table-driven pattern)
+- **10 packages** with **0 test coverage** (2,452 lines)
+- **1 confirmed flaky test** candidate
+- Test quality is generally good with moderate mocking
+
+---
+
+## Coverage Gap Inventory
+
+### Packages Without Tests (Priority Order)
+
+| Priority | Package | Lines | Risk | Notes |
+|----------|---------|-------|------|-------|
+| **P0** | `internal/lock` | 402 | **CRITICAL** | Multi-agent lock management. Bugs cause worker collisions. Already has `execCommand` mockable for testing. |
+| **P1** | `internal/events` | 295 | HIGH | Event bus for audit trail. Mutex-protected writes. Core observability. |
+| **P1** | `internal/boot` | 242 | HIGH | Boot watchdog lifecycle. Spawns tmux sessions. |
+| **P1** | `internal/checkpoint` | 216 | HIGH | Session crash recovery. Critical for polecat continuity. |
+| **P2** | `internal/tui/convoy` | 601 | MEDIUM | TUI component. Harder to test but user-facing. |
+| **P2** | `internal/constants` | 221 | LOW | Mostly configuration constants. Low behavioral risk. |
+| **P3** | `internal/style` | 331 | LOW | Output formatting. Visual only. |
+| **P3** | `internal/claude` | 80 | LOW | Claude settings parsing. |
+| **P3** | `internal/wisp` | 52 | LOW | Ephemeral molecule I/O. Small surface. |
+| **P4** | `cmd/gt` | 12 | TRIVIAL | Main entry point. Minimal code. |
+
+**Total untested lines**: 2,452
+
+---
+
+## Flaky Test Candidates
+
+### Confirmed: `internal/feed/curator_test.go`
+
+**Issue**: Uses `time.Sleep()` for synchronization (lines 59, 71, 119, 138)
+
+```go
+// Give curator time to start
+time.Sleep(50 * time.Millisecond)
+...
+// Wait for processing
+time.Sleep(300 * time.Millisecond)
+```
+
+**Risk**: Flaky under load, CI delays, or slow machines.
+
+**Fix**: Replace with channel-based synchronization or polling with timeout:
+```go
+// Wait for condition with timeout
+deadline := time.Now().Add(time.Second)
+for time.Now().Before(deadline) {
+    if conditionMet() {
+        break
+    }
+    time.Sleep(10 * time.Millisecond)
+}
+```
+
+---
+
+## Test Quality Analysis
+
+### Strengths
+
+1. **Table-driven tests**: 30% of tests use `t.Run()` (192/631)
+2. **Good isolation**: Only 2 package-level test variables
+3. **Dedicated integration tests**: 15 files with explicit integration/e2e naming
+4. **Error handling**: 316 uses of `if err != nil` in tests
+5. **No random data**: No `rand.` usage in tests (deterministic)
+6. **Environment safety**: Uses `t.Setenv()` for clean env var handling
+
+### Areas for Improvement
+
+1. **`testing.Short()`**: Only 1 usage. Long-running tests should check this.
+2. **External dependencies**: 26 tests skip when `bd` or `tmux` unavailable - consider mocking more.
+3. **time.Sleep usage**: Found in `curator_test.go` - should be eliminated.
+
+---
+
+## Test Smells (Minor)
+
+| Smell | Location | Severity | Notes |
+|-------|----------|----------|-------|
+| Sleep-based sync | `feed/curator_test.go` | HIGH | See flaky section |
+| External dep skips | Multiple files | LOW | Reasonable for integration tests |
+| Skip-heavy file | `tmux/tmux_test.go` | LOW | Acceptable - tmux not always available |
+
+---
+
+## Priority List for New Tests
+
+### Immediate (P0)
+
+1. **`internal/lock`** - Critical path
+   - Test `Acquire()` with stale lock cleanup
+   - Test `Check()` with live/dead PIDs
+   - Test `CleanStaleLocks()` with mock tmux sessions
+   - Test `DetectCollisions()`
+   - Test concurrent lock acquisition (race detection)
+
+### High Priority (P1)
+
+2. **`internal/events`**
+   - Test `Log()` file creation and append
+   - Test `write()` mutex behavior
+   - Test payload helpers
+   - Test graceful handling when not in workspace
+
+3. **`internal/boot`**
+   - Test `IsRunning()` with stale markers
+   - Test `AcquireLock()` / `ReleaseLock()` cycle
+   - Test `SaveStatus()` / `LoadStatus()` round-trip
+   - Test degraded mode path
+
+4. **`internal/checkpoint`**
+   - Test `Read()` / `Write()` round-trip
+   - Test `Capture()` git state extraction
+   - Test `IsStale()` with various durations
+   - Test `Summary()` output
+
+### Medium Priority (P2)
+
+5. **`internal/tui/convoy`** - Consider golden file tests for view output
+6. **`internal/constants`** - Test any validation logic
+
+---
+
+## Missing Test Types
+
+| Type | Current State | Recommendation |
+|------|--------------|----------------|
+| Unit tests | Good coverage where present | Add for P0-P1 packages |
+| Integration tests | 15 dedicated files | Adequate |
+| E2E tests | `browser_e2e_test.go` | Consider more CLI E2E |
+| Fuzz tests | None | Consider for parsers (`formula/parser.go`) |
+| Benchmark tests | None visible | Add for hot paths (`lock`, `events`) |
+
+---
+
+## Actionable Next Steps
+
+1. **Fix flaky test**: Refactor `feed/curator_test.go` to use channels/polling
+2. **Add lock tests**: Highest priority - bugs here break multi-agent
+3. **Add events tests**: Core observability must be tested
+4. **Add checkpoint tests**: Session recovery is critical path
+5. **Run with race detector**: `go test -race ./...` to catch data races
+6. **Consider `-short` flag**: Add `testing.Short()` checks to slow tests