docs: add caution note to v0.2.3 changelog

Adds the missing github-gate-check step that runs `bd gate discover` and
`bd gate check --type=gh` to evaluate GitHub CI gates. Updates
dispatch-gated-molecules to depend on both gate-evaluation and
github-gate-check.

Fixes: gt-sfxpr

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

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

.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-deacon-patrol.formula.toml

@@ -23,7 +23,7 @@ Witnesses detect it and escalate to the Mayor.
 The Deacon's agent bead last_activity timestamp is updated during each patrol
 cycle. Witnesses check this timestamp to verify health."""
 formula = "mol-deacon-patrol"
-version = 4
+version = 6
 
 [[steps]]
 id = "inbox-check"
@@ -148,6 +148,49 @@ bd gate list --json
 After closing a gate, the Waiters field contains mail addresses to notify.
 Send a brief notification to each waiter that the gate has cleared."""
 
+[[steps]]
+id = "dispatch-gated-molecules"
+title = "Dispatch molecules with resolved gates"
+needs = ["gate-evaluation"]
+description = """
+Find molecules blocked on gates that have now closed and dispatch them.
+
+This completes the async resume cycle without explicit waiter tracking.
+The molecule state IS the waiter - patrol discovers reality each cycle.
+
+**Step 1: Find gate-ready molecules**
+```bash
+bd mol ready --gated --json
+```
+
+This returns molecules where:
+- Status is in_progress
+- Current step has a gate dependency
+- The gate bead is now closed
+- No polecat currently has it hooked
+
+**Step 2: For each ready molecule, dispatch to the appropriate rig**
+```bash
+# Determine target rig from molecule metadata
+bd mol show <mol-id> --json
+# Look for rig field or infer from prefix
+
+# Dispatch to that rig's polecat pool
+gt sling <mol-id> <rig>/polecats
+```
+
+**Step 3: Log dispatch**
+Note which molecules were dispatched for observability:
+```bash
+# Molecule <mol-id> dispatched to <rig>/polecats (gate <gate-id> cleared)
+```
+
+**If no gate-ready molecules:**
+Skip - nothing to dispatch. Gates haven't closed yet or molecules
+already have active polecats working on them.
+
+**Exit criteria:** All gate-ready molecules dispatched to polecats."""
+
 [[steps]]
 id = "check-convoy-completion"
 title = "Check convoy completion"
@@ -258,7 +301,7 @@ Keep notifications brief and actionable. The recipient can run bd show for detai
 [[steps]]
 id = "health-scan"
 title = "Check Witness and Refinery health"
-needs = ["trigger-pending-spawns", "gate-evaluation", "fire-notifications"]
+needs = ["trigger-pending-spawns", "dispatch-gated-molecules", "fire-notifications"]
 description = """
 Check Witness and Refinery health for each rig.
 
@@ -342,14 +385,21 @@ Reset unresponsive_cycles to 0 when component responds normally."""
 
 [[steps]]
 id = "zombie-scan"
-title = "Backup check for zombie polecats"
+title = "Detect zombie polecats (NO KILL AUTHORITY)"
 needs = ["health-scan"]
 description = """
-Defense-in-depth check for zombie polecats that Witness should have cleaned.
+Defense-in-depth DETECTION of zombie polecats that Witness should have cleaned.
+
+**⚠️ CRITICAL: The Deacon has NO kill authority.**
+
+These are workers with context, mid-task progress, unsaved state. Every kill
+destroys work. File the warrant and let Boot handle interrogation and execution.
+You do NOT have kill authority.
 
 **Why this exists:**
-The Witness is responsible for nuking polecats after they complete work (via POLECAT_DONE).
-This step provides backup detection in case the Witness fails to clean up.
+The Witness is responsible for cleaning up polecats after they complete work.
+This step provides backup DETECTION in case the Witness fails to clean up.
+Detection only - Boot handles termination.
 
 **Zombie criteria:**
 - State: idle or done (no active work assigned)
@@ -357,26 +407,34 @@ This step provides backup detection in case the Witness fails to clean up.
 - No hooked work (nothing pending for this polecat)
 - Last activity: older than 10 minutes
 
-**Run the zombie scan:**
+**Run the zombie scan (DRY RUN ONLY):**
 ```bash
 gt deacon zombie-scan --dry-run
 ```
 
+**NEVER run:**
+- `gt deacon zombie-scan` (without --dry-run)
+- `tmux kill-session`
+- `gt polecat nuke`
+- Any command that terminates a session
+
 **If zombies detected:**
 1. Review the output to confirm they are truly abandoned
-2. Run without --dry-run to nuke them:
+2. File a death warrant for each detected zombie:
    ```bash
-   gt deacon zombie-scan
+   gt warrant file <polecat> --reason "Zombie detected: no session, no hook, idle >10m"
+   ```
+3. Boot will handle interrogation and execution
+4. Notify the Mayor about Witness failure:
+   ```bash
+   gt mail send mayor/ -s "Witness cleanup failure" \
+     -m "Filed death warrant for <polecat>. Witness failed to clean up."
    ```
-3. This will:
-   - Nuke each zombie polecat
-   - Notify the Mayor about Witness failure
-   - Log the cleanup action
 
 **If no zombies:**
 No action needed - Witness is doing its job.
 
-**Note:** This is a backup mechanism. If you frequently find zombies,
+**Note:** This is a backup mechanism. If you frequently detect zombies,
 investigate why the Witness isn't cleaning up properly."""
 
 [[steps]]
@@ -505,10 +563,48 @@ Skip dispatch - system is healthy.
 
 **Exit criteria:** Session GC dispatched to dog (if needed)."""
 
+[[steps]]
+id = "costs-digest"
+title = "Aggregate daily costs"
+needs = ["session-gc"]
+description = """
+**DAILY DIGEST** - Aggregate yesterday's session cost wisps.
+
+Session costs are recorded as ephemeral wisps (not exported to JSONL) to avoid
+log-in-database pollution. This step aggregates them into a permanent daily
+"Cost Report YYYY-MM-DD" bead for audit purposes.
+
+**Step 1: Check if digest is needed**
+```bash
+# Preview yesterday's costs (dry run)
+gt costs digest --yesterday --dry-run
+```
+
+If output shows "No session cost wisps found", skip to Step 3.
+
+**Step 2: Create the digest**
+```bash
+gt costs digest --yesterday
+```
+
+This:
+- Queries all session.ended wisps from yesterday
+- Creates a single "Cost Report YYYY-MM-DD" bead with aggregated data
+- Deletes the source wisps
+
+**Step 3: Verify**
+The digest appears in `gt costs --week` queries.
+Daily digests preserve audit trail without per-session pollution.
+
+**Timing**: Run once per morning patrol cycle. The --yesterday flag ensures
+we don't try to digest today's incomplete data.
+
+**Exit criteria:** Yesterday's costs digested (or no wisps to digest)."""
+
 [[steps]]
 id = "log-maintenance"
 title = "Rotate logs and prune state"
-needs = ["session-gc"]
+needs = ["costs-digest"]
 description = """
 Maintain daemon logs and state files.
 

.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-gastown-boot.formula.json

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

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

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

.beads/formulas/mol-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-shutdown-dance.formula.toml

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

.beads/formulas/mol-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,11 +33,43 @@ jobs:
           fi
           echo "No .beads/issues.jsonl changes detected"
 
+  # Verify committed formulas allow build without go:generate
+  # This catches issues where go install @latest would fail
+  check-embedded-formulas:
+    name: Check embedded formulas
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+
+      - name: Build without go:generate
+        run: |
+          # This must succeed with committed formulas only
+          # If this fails, run: go generate ./... && git add -A && git commit
+          go build -v ./cmd/gt
+
+      - name: Verify formulas are in sync
+        run: |
+          # Regenerate and check for differences
+          go generate ./internal/formula/...
+          if ! git diff --exit-code internal/formula/formulas/; then
+            echo ""
+            echo "ERROR: Committed formulas are out of sync with .beads/formulas/"
+            echo "Run: go generate ./... && git add -A && git commit"
+            exit 1
+          fi
+
   test:
     name: Test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -52,8 +84,122 @@ jobs:
       - name: Build
         run: go build -v ./cmd/gt
 
-      - name: Test
-        run: go test -v -race -short ./...
+      - name: Test with Coverage
+        run: |
+          go test -race -short -coverprofile=coverage.out ./... 2>&1 | tee test-output.txt
+
+      - name: Upload Coverage Data
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-data
+          path: |
+            coverage.out
+            test-output.txt
+
+  # Separate job to process coverage after ALL tests complete
+  coverage:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    needs: [test, integration]
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+
+      - name: Download Coverage Data
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-data
+
+      - name: Generate Coverage Report
+        run: |
+          # Parse per-package coverage from test output
+          echo "## Code Coverage Report" > coverage-report.md
+          echo "" >> coverage-report.md
+
+          # Get overall coverage
+          TOTAL=$(go tool cover -func=coverage.out | grep total | awk '{print $3}')
+          echo "**Overall Coverage: ${TOTAL}**" >> coverage-report.md
+          echo "" >> coverage-report.md
+
+          # Create per-package table
+          echo "| Package | Coverage |" >> coverage-report.md
+          echo "|---------|----------|" >> coverage-report.md
+
+          # Extract package coverage from all test output lines
+          grep -E "github.com/steveyegge/gastown.*coverage:" test-output.txt | \
+            sed 's/.*github.com\/steveyegge\/gastown\///' | \
+            awk '{
+              pkg = $1
+              for (i=2; i<=NF; i++) {
+                if ($i == "coverage:") {
+                  cov = $(i+1)
+                  break
+                }
+              }
+              printf "| %s | %s |\n", pkg, cov
+            }' | sort -u >> coverage-report.md
+
+          echo "" >> coverage-report.md
+          echo "---" >> coverage-report.md
+          echo "_Generated by CI_" >> coverage-report.md
+
+          # Show in logs
+          cat coverage-report.md
+
+      - name: Upload Coverage Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage-report.md
+          retention-days: 30
+
+      - name: Comment Coverage on PR
+        # Only for internal PRs - fork PRs can't write comments
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('coverage-report.md', 'utf8');
+
+            // Find existing coverage comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
+              comment.body.includes('## Code Coverage Report')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: report
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: report
+              });
+            }
+
+      - name: Coverage Note for Fork PRs
+        if: github.event.pull_request.head.repo.full_name != github.repository
+        run: |
+          echo "::notice::Coverage report uploaded as artifact (fork PRs cannot post comments). Download from Actions tab."
 
   lint:
     name: Lint
@@ -71,3 +217,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,363 @@ 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.3] - 2026-01-09
+
+Worker safety release - prevents accidental termination of active agents.
+
+> **Note**: The Deacon safety improvements are believed to be correct but have not
+> yet been extensively tested in production. We recommend running with
+> `gt deacon pause` initially and monitoring behavior before enabling full patrol.
+> Please report any issues. A 0.3.0 release will follow once these changes are
+> battle-tested.
+
+### Critical Safety Improvements
+
+- **Kill authority removed from Deacon** - Deacon patrol now only detects zombies via `--dry-run`, never kills directly. Death warrants are filed for Boot to handle interrogation/execution. This prevents destruction of worker context, mid-task progress, and unsaved state (#gt-vhaej)
+- **Bulletproof pause mechanism** - Multi-layer pause for Deacon with file-based state, `gt deacon pause/resume` commands, and guards in `gt prime` and heartbeat (#265)
+- **Doctor warns instead of killing** - `gt doctor` now warns about stale town-root settings rather than killing sessions (#243)
+- **Orphan process check informational** - Doctor's orphan process detection is now informational only, not actionable (#272)
+
+### Added
+
+- **`gt account switch` command** - Switch between Claude Code accounts with `gt account switch <handle>`. Manages `~/.claude` symlinks and updates default account
+- **`gt crew list --all`** - Show all crew members across all rigs (#276)
+- **Rig-level custom agent support** - Configure different agents per-rig (#12)
+- **Rig identity beads check** - Doctor validates rig identity beads exist
+- **GT_ROOT env var** - Set for all agent sessions for consistent environment
+- **New agent presets** - Added Cursor, Auggie (Augment Code), and Sourcegraph AMP as built-in agent presets (#247)
+- **Context Management docs** - Added to Witness template for better context handling (gt-jjama)
+
+### Fixed
+
+- **`gt prime --hook` recognized** - Doctor now recognizes `gt prime --hook` as valid session hook config (#14)
+- **Integration test reliability** - Improved test stability (#13)
+- **IsClaudeRunning detection** - Now detects 'claude' and version patterns correctly (#273)
+- **Deacon heartbeat restored** - `ensureDeaconRunning` restored to heartbeat using Manager pattern (#271)
+- **Deacon session names** - Correct session name references in formulas (#270)
+- **Hidden directory scanning** - Ignore `.claude` and other dot directories when enumerating polecats (#258, #279)
+- **SetupRedirect tracked beads** - Works correctly with tracked beads architecture where canonical location is `mayor/rig/.beads`
+- **Tmux shell ready** - Wait for shell ready before sending keys (#264)
+- **Gastown prefix derivation** - Correctly derive `gt-` prefix for gastown compound words (gt-m46bb)
+- **Custom beads types** - Register custom beads types during install (#250)
+
+### Changed
+
+- **Refinery Manager pattern** - Replaced `ensureRefinerySession` with `refinery.Manager.Start()` for consistency
+
+### Removed
+
+- **Unused formula JSON** - Removed unused JSON formula file (cleanup)
+
+### Contributors
+
+Thanks to all contributors for this release:
+- @julianknutsen - Doctor fixes (#14, #271, #272, #273), formula fixes (#270), GT_ROOT env (#268)
+- @joshuavial - Hidden directory scanning (#258, #279), crew list --all (#276)
+
+## [0.2.2] - 2026-01-07
+
+Rig operational state management, unified agent startup, and extensive stability fixes.
+
+### Added
+
+#### Rig Operational State Management
+- **`gt rig park/unpark` commands** - Level 1 rig control: pause daemon auto-start while preserving sessions
+- **`gt rig dock/undock` commands** - Level 2 rig control: stop all sessions and prevent auto-start (gt-9gm9n)
+- **`gt rig config` commands** - Per-rig configuration management (gt-hhmkq)
+- **Rig identity beads** - Schema and creation for rig identity tracking (gt-zmznh)
+- **Property layer lookup** - Hierarchical configuration resolution (gt-emh1c)
+- **Operational state in status** - `gt rig status` shows park/dock state
+
+#### Agent Configuration & Startup
+- **`--agent` overrides** - Override agent for start/attach/sling commands
+- **Unified agent startup** - Manager pattern for consistent agent initialization
+- **Claude settings installation** - Auto-install during rig and HQ creation
+- **Runtime-aware tmux checks** - Detect actual agent state from tmux sessions
+
+#### Status & Monitoring
+- **`gt status --watch`** - Watch mode with auto-refresh (#231)
+- **Compact status output** - One-line-per-worker format as new default
+- **LED status indicators** - Visual indicators for rigs in Mayor tmux status line
+- **Parked/docked indicators** - Pause emoji (⏸) for inactive rigs in statusline
+
+#### Beads & Workflow
+- **Minimum beads version check** - Validates beads CLI compatibility (gt-im3fl)
+- **ZFC convoy auto-close** - `bd close` triggers convoy completion (gt-3qw5s)
+- **Stale hooked bead cleanup** - Deacon clears orphaned hooks (gt-2yls3)
+- **Doctor prefix mismatch detection** - Detect misconfigured rig prefixes (gt-17wdl)
+- **Unified beads redirect** - Single redirect system for tracked and local beads (#222)
+- **Route from rig to town beads** - Cross-level bead routing
+
+#### Infrastructure
+- **Windows-compatible file locking** - Daemon lock works on Windows
+- **`--purge` flag for crews** - Full crew obliteration option
+- **Debug logging for suppressed errors** - Better visibility into startup issues (gt-6d7eh)
+- **hq- prefix in tmux cycle bindings** - Navigate to Mayor/Deacon sessions
+- **Wisp config storage layer** - Transient/local settings for ephemeral workflows
+- **Sparse checkout** - Exclude Claude context files from source repos
+
+### Changed
+
+- **Daemon respects rig operational state** - Parked/docked rigs not auto-started
+- **Agent startup unified** - Manager pattern replaces ad-hoc initialization
+- **Mayor files moved** - Reorganized into `mayor/` subdirectory
+- **Refinery merges local branches** - No longer fetches from origin (gt-cio03)
+- **Polecats start from origin/default-branch** - Consistent recycled state
+- **Observable states removed** - Discover agent state from tmux, don't track (gt-zecmc)
+- **mol-town-shutdown v3** - Complete cleanup formula (gt-ux23f)
+- **Witness delays polecat cleanup** - Wait until MR merges (gt-12hwb)
+- **Nudge on divergence** - Daemon nudges agents instead of silent accept
+- **README rewritten** - Comprehensive guides and architecture docs (#226)
+- **`gt rigs` → `gt rig list`** - Command renamed in templates/docs (#217)
+
+### Fixed
+
+#### Doctor & Lifecycle
+- **`--restart-sessions` flag required** - Doctor won't cycle sessions without explicit flag (gt-j44ri)
+- **Only cycle patrol roles** - Doctor --fix doesn't restart crew/polecats (hq-qthgye)
+- **Session-ended events auto-closed** - Prevent accumulation (gt-8tc1v)
+- **GUPP propulsion nudge** - Added to daemon restartSession
+
+#### Sling & Beads
+- **Sling uses bd native routing** - No BEADS_DIR override needed
+- **Sling parses wisp JSON correctly** - Handle `new_epic_id` field
+- **Sling resolves rig path** - Cross-rig bead hooking works
+- **Sling waits for Claude ready** - Don't nudge until session responsive (#146)
+- **Correct beads database for sling** - Rig-level beads used (gt-n5gga)
+- **Close hooked beads before clearing** - Proper cleanup order (gt-vwjz6)
+- **Removed dead sling flags** - `--molecule` and `--quality` cleaned up
+
+#### Agent Sessions
+- **Witness kills tmux on Stop()** - Clean session termination
+- **Deacon uses session package** - Correct hq- session names (gt-r38pj)
+- **Honor rig agent for witness/refinery** - Respect per-rig settings
+- **Canonical hq role bead IDs** - Consistent naming
+- **hq- prefix in status display** - Global agents shown correctly (gt-vcvyd)
+- **Restart Claude when dead** - Recover sessions where tmux exists but Claude died
+- **Town session cycling** - Works from any directory
+
+#### Polecat & Crew
+- **Nuke not blocked by stale hooks** - Closed beads don't prevent cleanup (gt-jc7bq)
+- **Crew stop dry-run support** - Preview cleanup before executing (gt-kjcx4)
+- **Crew defaults to --all** - `gt crew start <rig>` starts all crew (gt-s8mpt)
+- **Polecat cleanup handlers** - `gt witness process` invokes handlers (gt-h3gzj)
+
+#### Daemon & Configuration
+- **Create mayor/daemon.json** - `gt start` and `gt doctor --fix` initialize daemon state (#225)
+- **Initialize git before beads** - Enable repo fingerprint (#180)
+- **Handoff preserves env vars** - Claude Code environment not lost (#216)
+- **Agent settings passed correctly** - Witness and daemon respawn use rigPath
+- **Log rig discovery errors** - Don't silently swallow (gt-rsnj9)
+
+#### Refinery & Merge Queue
+- **Use rig's default_branch** - Not hardcoded 'main'
+- **MERGE_FAILED sent to Witness** - Proper failure notification
+- **Removed BranchPushedToRemote checks** - Local-only workflow support (gt-dymy5)
+
+#### Misc Fixes
+- **BeadsSetupRedirect preserves tracked files** - Don't clobber existing files (gt-fj0ol)
+- **PATH export in hooks** - Ensure commands find binaries
+- **Replace panic with fallback** - ID generation gracefully degrades (#213)
+- **Removed duplicate WorktreeAddFromRef** - Code cleanup
+- **Town root beads for Deacon** - Use correct beads location (gt-sstg)
+
+### Refactored
+
+- **AgentStateManager pattern** - Shared state management extracted (gt-gaw8e)
+- **CleanupStatus type** - Replace raw strings (gt-77gq7)
+- **ExecWithOutput utility** - Common command execution (gt-vurfr)
+- **runBdCommand helper** - DRY mail package (gt-8i6bg)
+- **Config expansion helper** - Generic DRY config (gt-i85sg)
+
+### Documentation
+
+- **Property layers guide** - Implementation documentation
+- **Worktree architecture** - Clarified beads routing
+- **Agent config** - Onboarding docs mention --agent overrides
+- **Polecat Operations section** - Added to Mayor docs (#140)
+
+### Contributors
+
+Thanks to all contributors for this release:
+- @julianknutsen - Claude settings inheritance (#239)
+- @joshuavial - Sling wisp JSON parse (#238)
+- @michaellady - Unified beads redirect (#222), daemon.json fix (#225)
+- @greghughespdx - PATH in hooks fix (#139)
+
+## [0.2.1] - 2026-01-05
+
+Bug fixes, security hardening, and new `gt config` command.
+
+### Added
+
+- **`gt config` command** - Manage agent settings (model, provider) per-rig or globally
+- **`hq-` prefix for patrol sessions** - Mayor and Deacon sessions use town-prefixed names
+- **Doctor hooks-path check** - Verify Git hooks path is configured correctly
+- **Block internal PRs** - Pre-push hook and GitHub Action prevent accidental internal PRs (#117)
+- **Dispatcher notifications** - Notify dispatcher when polecat work completes
+- **Unit tests** - Added tests for `formatTrackBeadID` helper, done redirect, hook slot E2E
+
+### Fixed
+
+#### Security
+- **Command injection prevention** - Validate beads prefix to prevent injection (gt-l1xsa)
+- **Path traversal prevention** - Validate crew names to prevent traversal (gt-wzxwm)
+- **ReDoS prevention** - Escape user input in mail search (gt-qysj9)
+- **Error handling** - Handle crypto/rand.Read errors in ID generation
+
+#### Convoy & Sling
+- **Hook slot initialization** - Set hook slot when creating agent beads during sling (#124)
+- **Cross-rig bead formatting** - Format cross-rig beads as external refs in convoy tracking (#123)
+- **Reliable bd calls** - Add `--no-daemon` and `BEADS_DIR` for reliable beads operations
+
+#### Rig Inference
+- **`gt rig status`** - Infer rig name from current working directory
+- **`gt crew start --all`** - Infer rig from cwd for batch crew starts
+- **`gt prime` in crew start** - Pass as initial prompt in crew start commands
+- **Town default_agent** - Honor default agent setting for Mayor and Deacon
+
+#### Session & Lifecycle
+- **Hook persistence** - Hook persists across session interruption via `in_progress` lookup (gt-ttn3h)
+- **Polecat cleanup** - Clean up stale worktrees and git tracking
+- **`gt done` redirect** - Use ResolveBeadsDir for redirect file support
+
+#### Build & CI
+- **Embedded formulas** - Sync and commit formulas for `go install @latest`
+- **CI lint fixes** - Resolve lint and build errors
+- **Flaky test fix** - Sync database before beads integration tests
+
+## [0.2.0] - 2026-01-04
+
+Major release featuring the Convoy Dashboard, two-level beads architecture, and significant multi-agent improvements.
+
+### 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,481 @@
 # 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 🎩
+
+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.
+
+### Town 🏘️
+
+Your workspace directory (e.g., `~/gt/`). Contains all projects, agents, and configuration.
+
+### Rigs 🏗️
+
+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.
+
+> **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts.
+
+## Installation
+
+### Prerequisites
+
+- **Go 1.23+** - [go.dev/dl](https://go.dev/dl/)
+- **Git 2.25+** - for worktree support
+- **beads (bd) 0.44.0+** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads) (required for custom type support)
+- **tmux 3.0+** - recommended for full experience
+- **Claude Code CLI** (default runtime) - [claude.ai/code](https://claude.ai/code)
+- **Codex CLI** (optional runtime) - [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli)
+
+### Setup
+
+```bash
+# 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
 ```
 
-**Hook**: Each agent has a hook where work hangs. On wake, run what's on your hook.
+## Quick Start Guide
 
-**Beads**: Git-backed issue tracker. All work state lives here. [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+### Basic Workflow
 
-## Workflows
+```mermaid
+sequenceDiagram
+    participant You
+    participant Mayor
+    participant Convoy
+    participant Agent
+    participant Hook
 
-### Minimal (No Tmux)
+    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
+```
 
-Run individual Claude Code instances manually. Gas Town just tracks state.
+### Example: Feature Development
+
+```bash
+# 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
+```
+
+## Common Workflows
+
+### Mayor Workflow (Recommended)
+
+**Best for:** Coordinating complex, multi-issue work
+
+```mermaid
+flowchart LR
+    Start([Start Mayor]) --> Tell[Tell Mayor<br/>what to build]
+    Tell --> Creates[Mayor creates<br/>convoy + agents]
+    Creates --> Monitor[Monitor progress<br/>via convoy list]
+    Monitor --> Done{All done?}
+    Done -->|No| Monitor
+    Done -->|Yes| Review[Review work]
+```
+
+**Commands:**
+
+```bash
+# Attach to Mayor
+gt mayor attach
+
+# In Mayor, create convoy and let it orchestrate
+gt convoy create "Auth System" issue-101 issue-102 --notify
+
+# Track progress
+gt convoy list
+```
+
+### Minimal Mode (No Tmux)
+
+Run individual runtime instances manually. Gas Town just tracks state.
 
 ```bash
 gt convoy create "Fix bugs" issue-123  # Create convoy (sling auto-creates if skipped)
 gt sling issue-123 myproject           # Assign to worker
-claude --resume                        # Agent reads mail, runs work
+claude --resume                        # Agent reads mail, runs work (Claude)
+# or: codex                            # Start Codex in the workspace
 gt convoy list                         # Check progress
 ```
 
-### Full Stack (Tmux)
+### Beads Formula Workflow
 
-Agents run in tmux sessions. Daemon manages lifecycle.
+**Best for:** Predefined, repeatable processes
 
-```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
-```
+Formulas are TOML-defined workflows stored in `.beads/formulas/`.
 
-### Pick Your Roles
-
-Gas Town is modular. Run what you need:
-
-- **Polecats only**: Manual spawning, no monitoring
-- **+ Witness**: Automatic worker lifecycle, stuck detection
-- **+ Refinery**: Merge queue, code review
-- **+ Mayor**: Cross-project coordination
-
-## Cooking Formulas
-
-Formulas define structured workflows. Cook them, sling them to agents.
-
-### Basic Example
+**Example Formula** (`.beads/formulas/release.formula.toml`):
 
 ```toml
-# .beads/formulas/shiny.formula.toml
-formula = "shiny"
-description = "Design before code, review before ship"
+description = "Standard release process"
+formula = "release"
+version = 1
 
-[[steps]]
-id = "design"
-description = "Think about architecture"
-
-[[steps]]
-id = "implement"
-needs = ["design"]
-
-[[steps]]
-id = "test"
-needs = ["implement"]
-
-[[steps]]
-id = "submit"
-needs = ["test"]
-```
-
-### Using Formulas
-
-```bash
-bd formula list                    # See available formulas
-bd cook shiny                      # Cook into a protomolecule
-bd mol pour shiny --var feature=auth   # Create runnable molecule
-gt convoy create "Auth feature" gt-xyz  # Track with convoy
-gt sling gt-xyz myproject          # Assign to worker
-gt convoy list                     # Monitor progress
-```
-
-### What Happens
-
-1. **Cook** expands the formula into a protomolecule (frozen template)
-2. **Pour** creates a molecule (live workflow) with steps as beads
-3. **Worker executes** each step, closing beads as it goes
-4. **Crash recovery**: Worker restarts, reads molecule, continues from last step
-
-### Example: Beads Release Molecule
-
-A real workflow for releasing a new beads version:
-
-```toml
-formula = "beads-release"
-description = "Version bump and release workflow"
+[vars.version]
+description = "The semantic version to release (e.g., 1.2.0)"
+required = true
 
 [[steps]]
 id = "bump-version"
-description = "Update version in version.go and CHANGELOG"
-
-[[steps]]
-id = "update-deps"
-needs = ["bump-version"]
-description = "Run go mod tidy, update go.sum"
+title = "Bump version"
+description = "Run ./scripts/bump-version.sh {{version}}"
 
 [[steps]]
 id = "run-tests"
-needs = ["update-deps"]
-description = "Full test suite, check for regressions"
+title = "Run tests"
+description = "Run make test"
+needs = ["bump-version"]
 
 [[steps]]
-id = "build-binaries"
+id = "build"
+title = "Build"
+description = "Run make build"
 needs = ["run-tests"]
-description = "Cross-compile for all platforms"
 
 [[steps]]
 id = "create-tag"
-needs = ["build-binaries"]
-description = "Git tag with version, push to origin"
+title = "Create release tag"
+description = "Run git tag -a v{{version}} -m 'Release v{{version}}'"
+needs = ["build"]
 
 [[steps]]
-id = "publish-release"
+id = "publish"
+title = "Publish"
+description = "Run ./scripts/publish.sh"
 needs = ["create-tag"]
-description = "Create GitHub release with binaries"
 ```
 
-Cook it, pour it, sling it. The polecat runs through each step, and if it crashes
-after `run-tests`, a new polecat picks up at `build-binaries`.
+**Execute:**
 
-### Formula Composition
+```bash
+# List available formulas
+bd formula list
 
-```toml
-# Extend an existing formula
-formula = "shiny-enterprise"
-extends = ["shiny"]
+# Run a formula with variables
+bd cook release --var version=1.2.0
 
-[compose]
-aspects = ["security-audit"]  # Add cross-cutting concerns
+# Create formula instance for tracking
+bd mol pour release --var version=1.2.0
 ```
 
+### Manual Convoy Workflow
+
+**Best for:** Direct control over work distribution
+
+```bash
+# Create convoy manually
+gt convoy create "Bug Fixes" --human
+
+# Add issues
+gt convoy add-issue bug-101 bug-102
+
+# Assign to specific agents
+gt sling bug-101 myproject/my-agent
+
+# Check status
+gt convoy show
+```
+
+## Runtime Configuration
+
+Gas Town supports multiple AI coding runtimes. Per-rig runtime settings are in `settings/config.json`.
+
+```json
+{
+  "runtime": {
+    "provider": "codex",
+    "command": "codex",
+    "args": [],
+    "prompt_mode": "none"
+  }
+}
+```
+
+**Notes:**
+
+- Claude uses hooks in `.claude/settings.json` for mail injection and startup.
+- For Codex, set `project_doc_fallback_filenames = ["CLAUDE.md"]` in
+  `~/.codex/config.toml` so role instructions are picked up.
+- For runtimes without hooks (e.g., Codex), Gas Town sends a startup fallback
+  after the session is ready: `gt prime`, optional `gt mail check --inject`
+  for autonomous roles, and `gt nudge deacon session-started`.
+
 ## Key Commands
 
-### For Humans (Overseer)
+### Workspace Management
 
 ```bash
-gt start                          # Start Gas Town (daemon + agents)
-gt shutdown                       # Graceful shutdown
-gt status                         # Town overview
-gt <role> attach                  # Jump into any agent session
-                                  # e.g., gt mayor attach, gt witness attach
+gt install <path>           # Initialize workspace
+gt rig add <name> <repo>    # Add project
+gt rig list                 # List projects
+gt crew add <name> --rig <rig>  # Create crew workspace
 ```
 
-Most other work happens through agents - just ask them.
-
-### For Agents
+### Agent Operations
 
 ```bash
-# Convoy (primary dashboard)
-gt convoy list                    # Active work across all rigs
-gt convoy status <id>             # Detailed convoy progress
-gt convoy create "name" <issues>  # Create new convoy
-
-# Work assignment
-gt sling <bead> <rig>             # Assign work to polecat
-bd ready                          # Show available work
-bd list --status=in_progress      # Active work
-
-# Communication
-gt mail inbox                     # Check messages
-gt mail send <addr> -s "..." -m "..."
-
-# Lifecycle
-gt handoff                        # Request session cycle
-gt peek <agent>                   # Check agent health
-
-# Diagnostics
-gt doctor                         # Health check
-gt doctor --fix                   # Auto-repair
+gt agents                   # List active agents
+gt sling <issue> <rig>      # Assign work to agent
+gt sling <issue> <rig> --agent cursor   # Override runtime for this sling/spawn
+gt mayor attach             # Start Mayor session
+gt mayor start --agent auggie           # Run Mayor with a specific agent alias
+gt prime                    # Alternative to mayor attach
 ```
 
-## Roles
+**Built-in agent presets**: `claude`, `gemini`, `codex`, `cursor`, `auggie`, `amp`
 
-| 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 |
+### Convoy (Work Tracking)
 
-## The Propulsion Principle
+```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
+```
 
-> If your hook has work, RUN IT.
+### Configuration
 
-Agents wake up, check their hook, execute the molecule. No waiting for commands.
-Molecules survive crashes - any agent can continue where another left off.
+```bash
+# Set custom agent command
+gt config agent set claude-glm "claude-glm --model glm-4"
+gt config agent set codex-low "codex --thinking low"
 
----
+# Set default agent
+gt config default-agent claude-glm
 
-## Optional: MEOW Deep Dive
+# View config
+gt config show
+```
 
-**M**olecular **E**xpression **O**f **W**ork - the full algebra.
+### Beads Integration
 
-### States of Matter
+```bash
+bd formula list             # List formulas
+bd cook <formula>           # Execute formula
+bd mol pour <formula>       # Create trackable instance
+bd mol list                 # List active instances
+```
 
-| 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 |
+## Cooking Formulas
 
-*(Protomolecules are an homage to The Expanse. Ice-9 is a nod to Vonnegut.)*
+Gas Town includes built-in formulas for common workflows. See `.beads/formulas/` for available recipes.
 
-### Operators
+## Dashboard
 
-| 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 |
+Gas Town includes a web dashboard for monitoring:
 
----
+```bash
+# Start dashboard
+gt dashboard --port 8080
+
+# Open in browser
+open http://localhost:8080
+```
+
+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

@@ -17,7 +17,9 @@ Complete setup guide for Gas Town multi-agent orchestrator.
 | Tool | Version | Check | Install |
 |------|---------|-------|---------|
 | **tmux** | 3.0+ | `tmux -V` | See below |
-| **Claude Code** | latest | `claude --version` | See [claude.ai/claude-code](https://claude.ai/claude-code) |
+| **Claude Code** (default) | latest | `claude --version` | See [claude.ai/claude-code](https://claude.ai/claude-code) |
+| **Codex CLI** (optional) | latest | `codex --version` | See [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli) |
+| **OpenCode CLI** (optional) | latest | `opencode --version` | See [opencode.ai](https://opencode.ai) |
 
 ## Installing Prerequisites
 
@@ -130,22 +132,46 @@ gt doctor              # Run health checks
 gt status              # Show workspace status
 ```
 
+### Step 5: Configure Agents (Optional)
+
+Gas Town supports built-in runtimes (`claude`, `gemini`, `codex`) plus custom agent aliases.
+
+```bash
+# List available agents
+gt config agent list
+
+# Create an alias (aliases can encode model/thinking flags)
+gt config agent set codex-low "codex --thinking low"
+gt config agent set claude-haiku "claude --model haiku --dangerously-skip-permissions"
+
+# Set the town default agent (used when a rig doesn't specify one)
+gt config default-agent codex-low
+```
+
+You can also override the agent per command without changing defaults:
+
+```bash
+gt start --agent codex-low
+gt sling issue-123 myproject --agent claude-haiku
+```
+
 ## Minimal Mode vs Full Stack Mode
 
 Gas Town supports two operational modes:
 
 ### Minimal Mode (No Daemon)
 
-Run individual Claude Code instances manually. Gas Town only tracks state.
+Run individual runtime instances manually. Gas Town only tracks state.
 
 ```bash
 # Create and assign work
 gt convoy create "Fix bugs" issue-123
 gt sling issue-123 myproject
 
-# Run Claude manually
+# Run runtime manually
 cd ~/gt/myproject/polecats/<worker>
-claude --resume
+claude --resume          # Claude Code
+# or: codex              # Codex CLI
 
 # Check progress
 gt convoy list
@@ -184,7 +210,7 @@ Gas Town is modular. Enable only what you need:
 |--------------|-------|----------|
 | **Polecats only** | Workers | Manual spawning, no monitoring |
 | **+ Witness** | + Monitor | Automatic lifecycle, stuck detection |
-| **+ Refinery** | + Merge queue | PR review, code integration |
+| **+ Refinery** | + Merge queue | MR review, code integration |
 | **+ Mayor** | + Coordinator | Cross-project coordination |
 
 ## Troubleshooting

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/glossary.md

@@ -0,0 +1,94 @@
+# Gas Town Glossary
+
+Gas Town is an agentic development environment for managing multiple Claude Code instances simultaneously using the `gt` and `bd` (Beads) binaries, coordinated with tmux in git-managed directories.
+
+## Core Principles
+
+### MEOW (Molecular Expression of Work)
+Breaking large goals into detailed instructions for agents. Supported by Beads, Epics, Formulas, and Molecules. MEOW ensures work is decomposed into trackable, atomic units that agents can execute autonomously.
+
+### GUPP (Gas Town Universal Propulsion Principle)
+"If there is work on your Hook, YOU MUST RUN IT." This principle ensures agents autonomously proceed with available work without waiting for external input. GUPP is the heartbeat of autonomous operation.
+
+### NDI (Nondeterministic Idempotence)
+The overarching goal ensuring useful outcomes through orchestration of potentially unreliable processes. Persistent Beads and oversight agents (Witness, Deacon) guarantee eventual workflow completion even when individual operations may fail or produce varying results.
+
+## Environments
+
+### Town
+The management headquarters (e.g., `~/gt/`). The Town coordinates all workers across multiple Rigs and houses town-level agents like Mayor and Deacon.
+
+### Rig
+A project-specific Git repository under Gas Town management. Each Rig has its own Polecats, Refinery, Witness, and Crew members. Rigs are where actual development work happens.
+
+## Town-Level Roles
+
+### Mayor
+Chief-of-staff agent responsible for initiating Convoys, coordinating work distribution, and notifying users of important events. The Mayor operates from the town level and has visibility across all Rigs.
+
+### Deacon
+Daemon beacon running continuous Patrol cycles. The Deacon ensures worker activity, monitors system health, and triggers recovery when agents become unresponsive. Think of the Deacon as the system's watchdog.
+
+### Dogs
+The Deacon's crew of maintenance agents handling background tasks like cleanup, health checks, and system maintenance.
+
+### Boot (the Dog)
+A special Dog that checks the Deacon every 5 minutes, ensuring the watchdog itself is still watching. This creates a chain of accountability.
+
+## Rig-Level Roles
+
+### Polecat
+Ephemeral worker agents that produce Merge Requests. Polecats are spawned for specific tasks, complete their work, and are then cleaned up. They work in isolated git worktrees to avoid conflicts.
+
+### Refinery
+Manages the Merge Queue for a Rig. The Refinery intelligently merges changes from Polecats, handling conflicts and ensuring code quality before changes reach the main branch.
+
+### Witness
+Patrol agent that oversees Polecats and the Refinery within a Rig. The Witness monitors progress, detects stuck agents, and can trigger recovery actions.
+
+### Crew
+Long-lived, named agents for persistent collaboration. Unlike ephemeral Polecats, Crew members maintain context across sessions and are ideal for ongoing work relationships.
+
+## Work Units
+
+### Bead
+Git-backed atomic work unit stored in JSONL format. Beads are the fundamental unit of work tracking in Gas Town. They can represent issues, tasks, epics, or any trackable work item.
+
+### Formula
+TOML-based workflow source template. Formulas define reusable patterns for common operations like patrol cycles, code review, or deployment.
+
+### Protomolecule
+A template class for instantiating Molecules. Protomolecules define the structure and steps of a workflow without being tied to specific work items.
+
+### Molecule
+Durable chained Bead workflows. Molecules represent multi-step processes where each step is tracked as a Bead. They survive agent restarts and ensure complex workflows complete.
+
+### Wisp
+Ephemeral Beads destroyed after runs. Wisps are lightweight work items used for transient operations that don't need permanent tracking.
+
+### Hook
+A special pinned Bead for each agent. The Hook is an agent's primary work queue - when work appears on your Hook, GUPP dictates you must run it.
+
+## Workflow Commands
+
+### Convoy
+Primary work-order wrapping related Beads. Convoys group related tasks together and can be assigned to multiple workers. Created with `gt convoy create`.
+
+### Slinging
+Assigning work to agents via `gt sling`. When you sling work to a Polecat or Crew member, you're putting it on their Hook for execution.
+
+### Nudging
+Real-time messaging between agents with `gt nudge`. Nudges allow immediate communication without going through the mail system.
+
+### Handoff
+Agent session refresh via `/handoff`. When context gets full or an agent needs a fresh start, handoff transfers work state to a new session.
+
+### Seance
+Communicating with previous sessions via `gt seance`. Allows agents to query their predecessors for context and decisions from earlier work.
+
+### Patrol
+Ephemeral loop maintaining system heartbeat. Patrol agents (Deacon, Witness) continuously cycle through health checks and trigger actions as needed.
+
+---
+
+*This glossary was contributed by [Clay Shirky](https://github.com/cshirky) in [Issue #80](https://github.com/steveyegge/gastown/issues/80).*

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.