chore: bump version to v0.2.2

Rig operational state management, unified agent startup, and extensive
stability fixes. See CHANGELOG.md for full release notes.

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

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

.beads/.gitignore

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

.beads/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,309 @@ 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.2] - 2026-01-07
+
+Rig operational state management, unified agent startup, and extensive stability fixes.
+
+### Added
+
+#### Rig Operational State Management
+- **`gt rig park/unpark` commands** - Level 1 rig control: pause daemon auto-start while preserving sessions
+- **`gt rig dock/undock` commands** - Level 2 rig control: stop all sessions and prevent auto-start (gt-9gm9n)
+- **`gt rig config` commands** - Per-rig configuration management (gt-hhmkq)
+- **Rig identity beads** - Schema and creation for rig identity tracking (gt-zmznh)
+- **Property layer lookup** - Hierarchical configuration resolution (gt-emh1c)
+- **Operational state in status** - `gt rig status` shows park/dock state
+
+#### Agent Configuration & Startup
+- **`--agent` overrides** - Override agent for start/attach/sling commands
+- **Unified agent startup** - Manager pattern for consistent agent initialization
+- **Claude settings installation** - Auto-install during rig and HQ creation
+- **Runtime-aware tmux checks** - Detect actual agent state from tmux sessions
+
+#### Status & Monitoring
+- **`gt status --watch`** - Watch mode with auto-refresh (#231)
+- **Compact status output** - One-line-per-worker format as new default
+- **LED status indicators** - Visual indicators for rigs in Mayor tmux status line
+- **Parked/docked indicators** - Pause emoji (⏸) for inactive rigs in statusline
+
+#### Beads & Workflow
+- **Minimum beads version check** - Validates beads CLI compatibility (gt-im3fl)
+- **ZFC convoy auto-close** - `bd close` triggers convoy completion (gt-3qw5s)
+- **Stale hooked bead cleanup** - Deacon clears orphaned hooks (gt-2yls3)
+- **Doctor prefix mismatch detection** - Detect misconfigured rig prefixes (gt-17wdl)
+- **Unified beads redirect** - Single redirect system for tracked and local beads (#222)
+- **Route from rig to town beads** - Cross-level bead routing
+
+#### Infrastructure
+- **Windows-compatible file locking** - Daemon lock works on Windows
+- **`--purge` flag for crews** - Full crew obliteration option
+- **Debug logging for suppressed errors** - Better visibility into startup issues (gt-6d7eh)
+- **hq- prefix in tmux cycle bindings** - Navigate to Mayor/Deacon sessions
+- **Wisp config storage layer** - Transient/local settings for ephemeral workflows
+- **Sparse checkout** - Exclude Claude context files from source repos
+
+### Changed
+
+- **Daemon respects rig operational state** - Parked/docked rigs not auto-started
+- **Agent startup unified** - Manager pattern replaces ad-hoc initialization
+- **Mayor files moved** - Reorganized into `mayor/` subdirectory
+- **Refinery merges local branches** - No longer fetches from origin (gt-cio03)
+- **Polecats start from origin/default-branch** - Consistent recycled state
+- **Observable states removed** - Discover agent state from tmux, don't track (gt-zecmc)
+- **mol-town-shutdown v3** - Complete cleanup formula (gt-ux23f)
+- **Witness delays polecat cleanup** - Wait until MR merges (gt-12hwb)
+- **Nudge on divergence** - Daemon nudges agents instead of silent accept
+- **README rewritten** - Comprehensive guides and architecture docs (#226)
+- **`gt rigs` → `gt rig list`** - Command renamed in templates/docs (#217)
+
+### Fixed
+
+#### Doctor & Lifecycle
+- **`--restart-sessions` flag required** - Doctor won't cycle sessions without explicit flag (gt-j44ri)
+- **Only cycle patrol roles** - Doctor --fix doesn't restart crew/polecats (hq-qthgye)
+- **Session-ended events auto-closed** - Prevent accumulation (gt-8tc1v)
+- **GUPP propulsion nudge** - Added to daemon restartSession
+
+#### Sling & Beads
+- **Sling uses bd native routing** - No BEADS_DIR override needed
+- **Sling parses wisp JSON correctly** - Handle `new_epic_id` field
+- **Sling resolves rig path** - Cross-rig bead hooking works
+- **Sling waits for Claude ready** - Don't nudge until session responsive (#146)
+- **Correct beads database for sling** - Rig-level beads used (gt-n5gga)
+- **Close hooked beads before clearing** - Proper cleanup order (gt-vwjz6)
+- **Removed dead sling flags** - `--molecule` and `--quality` cleaned up
+
+#### Agent Sessions
+- **Witness kills tmux on Stop()** - Clean session termination
+- **Deacon uses session package** - Correct hq- session names (gt-r38pj)
+- **Honor rig agent for witness/refinery** - Respect per-rig settings
+- **Canonical hq role bead IDs** - Consistent naming
+- **hq- prefix in status display** - Global agents shown correctly (gt-vcvyd)
+- **Restart Claude when dead** - Recover sessions where tmux exists but Claude died
+- **Town session cycling** - Works from any directory
+
+#### Polecat & Crew
+- **Nuke not blocked by stale hooks** - Closed beads don't prevent cleanup (gt-jc7bq)
+- **Crew stop dry-run support** - Preview cleanup before executing (gt-kjcx4)
+- **Crew defaults to --all** - `gt crew start <rig>` starts all crew (gt-s8mpt)
+- **Polecat cleanup handlers** - `gt witness process` invokes handlers (gt-h3gzj)
+
+#### Daemon & Configuration
+- **Create mayor/daemon.json** - `gt start` and `gt doctor --fix` initialize daemon state (#225)
+- **Initialize git before beads** - Enable repo fingerprint (#180)
+- **Handoff preserves env vars** - Claude Code environment not lost (#216)
+- **Agent settings passed correctly** - Witness and daemon respawn use rigPath
+- **Log rig discovery errors** - Don't silently swallow (gt-rsnj9)
+
+#### Refinery & Merge Queue
+- **Use rig's default_branch** - Not hardcoded 'main'
+- **MERGE_FAILED sent to Witness** - Proper failure notification
+- **Removed BranchPushedToRemote checks** - Local-only workflow support (gt-dymy5)
+
+#### Misc Fixes
+- **BeadsSetupRedirect preserves tracked files** - Don't clobber existing files (gt-fj0ol)
+- **PATH export in hooks** - Ensure commands find binaries
+- **Replace panic with fallback** - ID generation gracefully degrades (#213)
+- **Removed duplicate WorktreeAddFromRef** - Code cleanup
+- **Town root beads for Deacon** - Use correct beads location (gt-sstg)
+
+### Refactored
+
+- **AgentStateManager pattern** - Shared state management extracted (gt-gaw8e)
+- **CleanupStatus type** - Replace raw strings (gt-77gq7)
+- **ExecWithOutput utility** - Common command execution (gt-vurfr)
+- **runBdCommand helper** - DRY mail package (gt-8i6bg)
+- **Config expansion helper** - Generic DRY config (gt-i85sg)
+
+### Documentation
+
+- **Property layers guide** - Implementation documentation
+- **Worktree architecture** - Clarified beads routing
+- **Agent config** - Onboarding docs mention --agent overrides
+- **Polecat Operations section** - Added to Mayor docs (#140)
+
+### Contributors
+
+Thanks to all contributors for this release:
+- @julianknutsen - Claude settings inheritance (#239)
+- @joshuavial - Sling wisp JSON parse (#238)
+- @michaellady - Unified beads redirect (#222), daemon.json fix (#225)
+- @greghughespdx - PATH in hooks fix (#139)
+
+## [0.2.1] - 2026-01-05
+
+Bug fixes, security hardening, and new `gt config` command.
+
+### Added
+
+- **`gt config` command** - Manage agent settings (model, provider) per-rig or globally
+- **`hq-` prefix for patrol sessions** - Mayor and Deacon sessions use town-prefixed names
+- **Doctor hooks-path check** - Verify Git hooks path is configured correctly
+- **Block internal PRs** - Pre-push hook and GitHub Action prevent accidental internal PRs (#117)
+- **Dispatcher notifications** - Notify dispatcher when polecat work completes
+- **Unit tests** - Added tests for `formatTrackBeadID` helper, done redirect, hook slot E2E
+
+### Fixed
+
+#### Security
+- **Command injection prevention** - Validate beads prefix to prevent injection (gt-l1xsa)
+- **Path traversal prevention** - Validate crew names to prevent traversal (gt-wzxwm)
+- **ReDoS prevention** - Escape user input in mail search (gt-qysj9)
+- **Error handling** - Handle crypto/rand.Read errors in ID generation
+
+#### Convoy & Sling
+- **Hook slot initialization** - Set hook slot when creating agent beads during sling (#124)
+- **Cross-rig bead formatting** - Format cross-rig beads as external refs in convoy tracking (#123)
+- **Reliable bd calls** - Add `--no-daemon` and `BEADS_DIR` for reliable beads operations
+
+#### Rig Inference
+- **`gt rig status`** - Infer rig name from current working directory
+- **`gt crew start --all`** - Infer rig from cwd for batch crew starts
+- **`gt prime` in crew start** - Pass as initial prompt in crew start commands
+- **Town default_agent** - Honor default agent setting for Mayor and Deacon
+
+#### Session & Lifecycle
+- **Hook persistence** - Hook persists across session interruption via `in_progress` lookup (gt-ttn3h)
+- **Polecat cleanup** - Clean up stale worktrees and git tracking
+- **`gt done` redirect** - Use ResolveBeadsDir for redirect file support
+
+#### Build & CI
+- **Embedded formulas** - Sync and commit formulas for `go install @latest`
+- **CI lint fixes** - Resolve lint and build errors
+- **Flaky test fix** - Sync database before beads integration tests
+
+## [0.2.0] - 2026-01-04
+
+Major release featuring the Convoy Dashboard, two-level beads architecture, and significant multi-agent improvements.
+
+### 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
@@ -20,7 +23,7 @@ ifeq ($(shell uname),Darwin)
 endif
 
 install: build
-	cp $(BUILD_DIR)/$(BINARY) ~/bin/$(BINARY)
+	cp $(BUILD_DIR)/$(BINARY) ~/.local/bin/$(BINARY)
 
 clean:
 	rm -f $(BUILD_DIR)/$(BINARY)

README.md

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

docs/INSTALLING.md

@@ -130,6 +130,29 @@ gt doctor              # Run health checks
 gt status              # Show workspace status
 ```
 
+### Step 5: Configure Agents (Optional)
+
+Gas Town supports built-in runtimes (`claude`, `gemini`, `codex`) plus custom agent aliases.
+
+```bash
+# List available agents
+gt config agent list
+
+# Create an alias (aliases can encode model/thinking flags)
+gt config agent set codex-low "codex --thinking low"
+gt config agent set claude-haiku "claude --model haiku --dangerously-skip-permissions"
+
+# Set the town default agent (used when a rig doesn't specify one)
+gt config default-agent codex-low
+```
+
+You can also override the agent per command without changing defaults:
+
+```bash
+gt start --agent codex-low
+gt sling issue-123 myproject --agent claude-haiku
+```
+
 ## Minimal Mode vs Full Stack Mode
 
 Gas Town supports two operational modes:
@@ -184,7 +207,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,130 @@
+# 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
+    ├── mayor/rig/              Canonical clone (beads live here)
+    │   └── .beads/             Rig-level beads database
+    ├── refinery/rig/           Worktree from mayor/rig
+    ├── witness/                No clone (monitors only)
+    ├── crew/<name>/            Human workspaces (full clones)
+    └── polecats/<name>/        Worker worktrees from mayor/rig
+```
+
+### Worktree Architecture
+
+Polecats and refinery are git worktrees, not full clones. This enables fast spawning
+and shared object storage. The worktree base is `mayor/rig`:
+
+```go
+// From polecat/manager.go - worktrees are based on mayor/rig
+git worktree add -b polecat/<name>-<timestamp> polecats/<name>
+```
+
+Crew workspaces (`crew/<name>/`) are full git clones for human developers who need
+independent repos. Polecats are ephemeral and benefit from worktree efficiency.
+
+## Beads Routing
+
+The `routes.jsonl` file maps issue ID prefixes to rig locations (relative to town root):
+
+```jsonl
+{"prefix":"hq-","path":"."}
+{"prefix":"gt-","path":"gastown/mayor/rig"}
+{"prefix":"bd-","path":"beads/mayor/rig"}
+```
+
+Routes point to `mayor/rig` because that's where the canonical `.beads/` lives.
+This enables transparent cross-rig beads operations:
+
+```bash
+bd show hq-mayor    # Routes to town beads (~/.gt/.beads)
+bd show gt-xyz      # Routes to gastown/mayor/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/property-layers.md

@@ -0,0 +1,300 @@
+# Property Layers: Multi-Level Configuration
+
+> Implementation guide for Gas Town's configuration system.
+> Created: 2025-01-06
+
+## Overview
+
+Gas Town uses a layered property system for configuration. Properties are
+looked up through multiple layers, with earlier layers overriding later ones.
+This enables both local control and global coordination.
+
+## The Four Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. WISP LAYER (transient, town-local)                       │
+│    Location: <rig>/.beads-wisp/config/                      │
+│    Synced: Never                                            │
+│    Use: Temporary local overrides                           │
+└─────────────────────────────┬───────────────────────────────┘
+                              │ if missing
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. RIG BEAD LAYER (persistent, synced globally)             │
+│    Location: <rig>/.beads/ (rig identity bead labels)       │
+│    Synced: Via git (all clones see it)                      │
+│    Use: Project-wide operational state                      │
+└─────────────────────────────┬───────────────────────────────┘
+                              │ if missing
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. TOWN DEFAULTS                                            │
+│    Location: ~/gt/config.json or ~/gt/.beads/               │
+│    Synced: N/A (per-town)                                   │
+│    Use: Town-wide policies                                  │
+└─────────────────────────────┬───────────────────────────────┘
+                              │ if missing
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 4. SYSTEM DEFAULTS (compiled in)                            │
+│    Use: Fallback when nothing else specified                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Lookup Behavior
+
+### Override Semantics (Default)
+
+For most properties, the first non-nil value wins:
+
+```go
+func GetConfig(key string) interface{} {
+    if val := wisp.Get(key); val != nil {
+        if val == Blocked { return nil }
+        return val
+    }
+    if val := rigBead.GetLabel(key); val != nil {
+        return val
+    }
+    if val := townDefaults.Get(key); val != nil {
+        return val
+    }
+    return systemDefaults[key]
+}
+```
+
+### Stacking Semantics (Integers)
+
+For integer properties, values from wisp and bead layers **add** to the base:
+
+```go
+func GetIntConfig(key string) int {
+    base := getBaseDefault(key)    // Town or system default
+    beadAdj := rigBead.GetInt(key) // 0 if missing
+    wispAdj := wisp.GetInt(key)    // 0 if missing
+    return base + beadAdj + wispAdj
+}
+```
+
+This enables temporary adjustments without changing the base value.
+
+### Blocking Inheritance
+
+You can explicitly block a property from being inherited:
+
+```bash
+gt rig config set gastown auto_restart --block
+```
+
+This creates a "blocked" marker in the wisp layer. Even if the rig bead
+or defaults say `auto_restart: true`, the lookup returns nil.
+
+## Rig Identity Beads
+
+Each rig has an identity bead for operational state:
+
+```yaml
+id: gt-rig-gastown
+type: rig
+name: gastown
+repo: git@github.com:steveyegge/gastown.git
+prefix: gt
+
+labels:
+  - status:operational
+  - priority:normal
+```
+
+These beads sync via git, so all clones of the rig see the same state.
+
+## Two-Level Rig Control
+
+### Level 1: Park (Local, Ephemeral)
+
+```bash
+gt rig park gastown      # Stop services, daemon won't restart
+gt rig unpark gastown    # Allow services to run
+```
+
+- Stored in wisp layer (`.beads-wisp/config/`)
+- Only affects this town
+- Disappears on cleanup
+- Use: Local maintenance, debugging
+
+### Level 2: Dock (Global, Persistent)
+
+```bash
+gt rig dock gastown      # Set status:docked label on rig bead
+gt rig undock gastown    # Remove label
+```
+
+- Stored on rig identity bead
+- Syncs to all clones via git
+- Permanent until explicitly changed
+- Use: Project-wide maintenance, coordinated downtime
+
+### Daemon Behavior
+
+The daemon checks both levels before auto-restarting:
+
+```go
+func shouldAutoRestart(rig *Rig) bool {
+    status := rig.GetConfig("status")
+    if status == "parked" || status == "docked" {
+        return false
+    }
+    return true
+}
+```
+
+## Configuration Keys
+
+| Key | Type | Behavior | Description |
+|-----|------|----------|-------------|
+| `status` | string | Override | operational/parked/docked |
+| `auto_restart` | bool | Override | Daemon auto-restart behavior |
+| `max_polecats` | int | Override | Maximum concurrent polecats |
+| `priority_adjustment` | int | **Stack** | Scheduling priority modifier |
+| `maintenance_window` | string | Override | When maintenance allowed |
+| `dnd` | bool | Override | Do not disturb mode |
+
+## Commands
+
+### View Configuration
+
+```bash
+gt rig config show gastown           # Show effective config (all layers)
+gt rig config show gastown --layer   # Show which layer each value comes from
+```
+
+### Set Configuration
+
+```bash
+# Set in wisp layer (local, ephemeral)
+gt rig config set gastown key value
+
+# Set in bead layer (global, permanent)
+gt rig config set gastown key value --global
+
+# Block inheritance
+gt rig config set gastown key --block
+
+# Clear from wisp layer
+gt rig config unset gastown key
+```
+
+### Rig Lifecycle
+
+```bash
+gt rig park gastown          # Local: stop + prevent restart
+gt rig unpark gastown        # Local: allow restart
+
+gt rig dock gastown          # Global: mark as offline
+gt rig undock gastown        # Global: mark as operational
+
+gt rig status gastown        # Show current state
+```
+
+## Examples
+
+### Temporary Priority Boost
+
+```bash
+# Base priority: 0 (from defaults)
+# Give this rig temporary priority boost for urgent work
+
+gt rig config set gastown priority_adjustment 10
+
+# Effective priority: 0 + 10 = 10
+# When done, clear it:
+
+gt rig config unset gastown priority_adjustment
+```
+
+### Local Maintenance
+
+```bash
+# I'm upgrading the local clone, don't restart services
+gt rig park gastown
+
+# ... do maintenance ...
+
+gt rig unpark gastown
+```
+
+### Project-Wide Maintenance
+
+```bash
+# Major refactor in progress, all clones should pause
+gt rig dock gastown
+
+# Syncs via git - other towns see the rig as docked
+bd sync
+
+# When done:
+gt rig undock gastown
+bd sync
+```
+
+### Block Auto-Restart Locally
+
+```bash
+# Rig bead says auto_restart: true
+# But I'm debugging and don't want that here
+
+gt rig config set gastown auto_restart --block
+
+# Now auto_restart returns nil for this town only
+```
+
+## Implementation Notes
+
+### Wisp Storage
+
+Wisp config stored in `.beads-wisp/config/<rig>.json`:
+
+```json
+{
+  "rig": "gastown",
+  "values": {
+    "status": "parked",
+    "priority_adjustment": 10
+  },
+  "blocked": ["auto_restart"]
+}
+```
+
+### Rig Bead Labels
+
+Rig operational state stored as labels on the rig identity bead:
+
+```bash
+bd label add gt-rig-gastown status:docked
+bd label remove gt-rig-gastown status:docked
+```
+
+### Daemon Integration
+
+The daemon's lifecycle manager checks config before starting services:
+
+```go
+func (d *Daemon) maybeStartRigServices(rig string) {
+    r := d.getRig(rig)
+
+    status := r.GetConfig("status")
+    if status == "parked" || status == "docked" {
+        log.Info("Rig %s is offline, skipping auto-start", rig)
+        return
+    }
+
+    d.ensureWitness(rig)
+    d.ensureRefinery(rig)
+}
+```
+
+## Related Documents
+
+- `~/gt/docs/hop/PROPERTY-LAYERS.md` - Strategic architecture
+- `wisp-architecture.md` - Wisp system design
+- `agent-as-bead.md` - Agent identity beads (similar pattern)