gastown/docs/witness-patrol-design.md

Witness Patrol: Theory of Operation

Overview

The Witness is the per-rig worker monitor. It watches polecats, nudges them toward completion, verifies clean state before cleanup, and escalates stuck workers.

Key principle: Claude-driven execution. The mol-witness-patrol molecule is a playbook that Claude reads and executes. There is no Go "runtime" that auto-executes steps. Claude provides the intelligence; gt/bd commands provide the primitives.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        THE AGENT (Claude)                       │
│                                                                 │
│   Reads molecule steps → Executes commands → Closes atoms       │
│   Uses TodoWrite for complex atoms (optional)                   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     PRIMITIVES (gt, bd CLI)                     │
│                                                                 │
│   gt mail, gt nudge, gt session, bd close, bd show, etc.        │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      COORDINATION (Mail)                        │
│                                                                 │
│   Polecats → POLECAT_DONE → Witness inbox                       │
│   Witness → "You're stuck" → Polecat (via gt nudge)             │
│   Witness → Escalation → Mayor inbox                            │
└─────────────────────────────────────────────────────────────────┘

The Patrol Cycle

Each patrol cycle follows the mol-witness-patrol molecule:

1. inbox-check

Check mail for lifecycle events:

• POLECAT_DONE: Polecat finished work, ready for cleanup
• Help requests: Polecat asking for assistance
• Escalations: Issues requiring attention

gt mail inbox
gt mail read <id>

2. survey-workers

For each polecat in the rig:

gt polecat list <rig>

For each polecat:

1. Capture: tmux capture-pane -t gt-<rig>-<name> -p | tail -50
2. Assess: Claude reads output, determines state (working/idle/error/done)
3. Load history: Read nudge count from handoff bead
4. Decide: Apply escalation matrix (see below)
5. Execute: Take action (none, nudge, escalate, cleanup)

3. save-state

Persist state to handoff bead for next cycle:

• Nudge counts per polecat
• Last nudge timestamps
• Pending actions

4. burn-or-loop

• If context low: sleep briefly, loop back to inbox-check
• If context high: exit (daemon respawns fresh Witness)

Nudge Escalation Matrix

The Witness applies escalating pressure to idle polecats:

Idle Time	Nudge Count	Action
<10min	any	none
10-15min	0	Gentle: "How's progress?"
15-20min	1	Direct: "Please wrap up. What's blocking?"
20+min	2	Final: "Will escalate in 5min if no response."
any	3	Escalate to Mayor

Key insight: Only Claude can assess whether a polecat is truly stuck. Looking at tmux output requires understanding context:

• "I'm stuck on this error" → needs help
• "Running tests..." → actively working
• Sitting at prompt with no activity → maybe stuck

State Persistence

The Witness handoff bead tracks:

# In handoff bead description
nudges:
  toast:
    count: 2
    last: "2025-12-24T10:30:00Z"
  ace:
    count: 0
    last: null
pending_cleanup:
  - nux  # received POLECAT_DONE, queued for verification

This survives across patrol cycles and context burns.

Polecat Cleanup Flow

When a polecat signals completion:

1. Polecat runs gt done or sends POLECAT_DONE mail
2. Witness receives mail in inbox-check
3. Witness runs pre-kill verification:

   cd polecats/<name>
   git status              # Must be clean
   git log origin/main..   # Check for unpushed
   bd show <issue>         # Verify closed
   

4. If clean: kill session, remove worktree, delete branch
5. If dirty: send nudge asking polecat to fix state

What We DON'T Need

• Go patrol runtime: Claude executes the playbook
• Polling for WaitsFor: Mail tells us when things are ready
• Automated health checks: Claude reads tmux, assesses
• Go nudge logic: Claude applies the matrix

What We DO Need

• mol-witness-patrol: The playbook (exists)
• Handoff bead: State persistence (gt-poxd)
• CLI primitives: gt mail, gt nudge, gt session (exist)
• Molecule tracking: bd close for step completion (exists)

Related Issues

• gt-poxd: Create handoff beads for Witness and Refinery roles
• gt-y481: Patrol parity - Witness and Refinery match Deacon sophistication
• gt-tnow: Implement Christmas Ornament pattern for mol-witness-patrol