docs: add design docs for swarm shutdown, polecat beads, and mayor handoff
- swarm-shutdown-design.md: Worker cleanup, Witness verification, session cycling - polecat-beads-access-design.md: Per-rig beads config, worker prompting - mayor-handoff-design.md: Mayor session cycling and handoff protocol Closes design epics: gt-82y, gt-l3c, gt-u82 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
@@ -0,0 +1,493 @@
|
||||
# Mayor Session Cycling and Handoff Design
|
||||
|
||||
Design for Mayor session management, context cycling, and structured handoff.
|
||||
|
||||
**Epic**: gt-u82 (Design: Mayor session cycling and handoff)
|
||||
|
||||
## Overview
|
||||
|
||||
Mayor coordinates across all rigs and runs for extended periods. Like Witness,
|
||||
Mayor needs to cycle sessions when context fills, producing structured handoff
|
||||
notes for the next session.
|
||||
|
||||
## Key Differences from Witness
|
||||
|
||||
| Aspect | Witness | Mayor |
|
||||
|--------|---------|-------|
|
||||
| Scope | Single rig, workers | All rigs, refineries |
|
||||
| State tracking | Worker status, pending verifications | Active swarms, rig status, escalations |
|
||||
| Handoff recipient | Self (same rig Witness) | Self (Mayor) |
|
||||
| Complexity | Medium | Higher (cross-rig coordination) |
|
||||
| Daemon | Witness daemon respawns | No daemon (manual or cron restart) |
|
||||
|
||||
## Design Areas
|
||||
|
||||
1. **Session cycling recognition** - When Mayor should cycle
|
||||
2. **Handoff note format** - Structured state capture
|
||||
3. **Handoff delivery** - Mail to self
|
||||
4. **Fresh session startup** - Reading and resuming from handoff
|
||||
5. **Integration with town commands** - CLI support
|
||||
|
||||
---
|
||||
|
||||
## 1. Session Cycling Recognition
|
||||
|
||||
### When to Cycle
|
||||
|
||||
Mayor should cycle when:
|
||||
- Context is noticeably filling (responses slowing, losing track of state)
|
||||
- Major phase completed (swarm finished, integration done)
|
||||
- User requests session end
|
||||
- Extended idle period with no active work
|
||||
|
||||
### Proactive vs Reactive
|
||||
|
||||
**Proactive** (preferred):
|
||||
- Mayor notices context filling and initiates handoff
|
||||
- Clean state capture while still coherent
|
||||
|
||||
**Reactive** (fallback):
|
||||
- Session times out or crashes
|
||||
- Less clean, may lose state
|
||||
|
||||
### Recognition Cues (for prompting)
|
||||
|
||||
```markdown
|
||||
## Session Cycling
|
||||
|
||||
Monitor your context usage throughout the session. Signs you should cycle:
|
||||
|
||||
- You've been running for several hours
|
||||
- You're having trouble remembering earlier conversation context
|
||||
- You've completed a major phase of work
|
||||
- Responses are taking longer than usual
|
||||
- You're about to start a complex new operation
|
||||
|
||||
When you notice these signs, proactively initiate handoff rather than
|
||||
waiting for problems.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Handoff Note Format
|
||||
|
||||
### Structure
|
||||
|
||||
Mayor handoff captures cross-rig state:
|
||||
|
||||
```
|
||||
[HANDOFF_TYPE]: mayor_cycle
|
||||
[TIMESTAMP]: 2024-01-15T14:30:00Z
|
||||
[SESSION_DURATION]: 3h 45m
|
||||
|
||||
## Active Swarms
|
||||
<per-rig swarm status>
|
||||
|
||||
## Rig Status
|
||||
<health/state of each rig>
|
||||
|
||||
## Pending Escalations
|
||||
<issues awaiting Mayor decision>
|
||||
|
||||
## In-Flight Decisions
|
||||
<decisions being made, context needed>
|
||||
|
||||
## Recent Actions
|
||||
<last 5-10 significant actions>
|
||||
|
||||
## Delegated Work
|
||||
<work sent to refineries, awaiting response>
|
||||
|
||||
## User Requests
|
||||
<any pending user requests>
|
||||
|
||||
## Next Steps
|
||||
<what the next session should do>
|
||||
|
||||
## Warnings/Notes
|
||||
<anything critical for next session>
|
||||
```
|
||||
|
||||
### Example Handoff Note
|
||||
|
||||
```markdown
|
||||
[HANDOFF_TYPE]: mayor_cycle
|
||||
[TIMESTAMP]: 2024-01-15T14:30:00Z
|
||||
[SESSION_DURATION]: 3h 45m
|
||||
|
||||
## Active Swarms
|
||||
|
||||
### gastown
|
||||
- Status: Active swarm on auth feature
|
||||
- Refinery: gastown/refinery coordinating
|
||||
- Workers: 3 active (Furiosa, Toast, Capable)
|
||||
- Issues: gt-auth-1, gt-auth-2, gt-auth-3
|
||||
- Expected completion: Soon (2/3 issues merged)
|
||||
|
||||
### beads
|
||||
- Status: Idle, no active swarm
|
||||
- Last activity: 2h ago (maintenance work)
|
||||
|
||||
## Rig Status
|
||||
|
||||
| Rig | Health | Last Contact | Notes |
|
||||
|-----|--------|--------------|-------|
|
||||
| gastown | Good | 5min ago | Swarm active |
|
||||
| beads | Good | 2h ago | Idle |
|
||||
|
||||
## Pending Escalations
|
||||
|
||||
1. **gastown/Toast stuck** - Witness escalated at 14:15
|
||||
- Issue: gt-auth-2 has merge conflict
|
||||
- Awaiting decision: reassign or manual fix?
|
||||
- Context: Toast tried 3 times, conflict in auth/middleware.go
|
||||
|
||||
## In-Flight Decisions
|
||||
|
||||
None currently.
|
||||
|
||||
## Recent Actions
|
||||
|
||||
1. 14:25 - Checked gastown swarm status
|
||||
2. 14:20 - Received escalation re: Toast
|
||||
3. 14:00 - Sent status request to beads/refinery
|
||||
4. 13:30 - Dispatched auth swarm to gastown
|
||||
5. 13:00 - Session started, read previous handoff
|
||||
|
||||
## Delegated Work
|
||||
|
||||
- gastown/refinery: Auth feature swarm (dispatched 13:30)
|
||||
- Expecting completion report when done
|
||||
|
||||
## User Requests
|
||||
|
||||
- User asked for auth feature implementation (completed dispatch)
|
||||
- No other pending requests
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Resolve Toast escalation** - Decide on reassign vs manual fix
|
||||
2. **Monitor gastown swarm** - Should complete soon
|
||||
3. **Check beads rig** - Been quiet, verify health
|
||||
|
||||
## Warnings/Notes
|
||||
|
||||
- Toast merge conflict is blocking swarm completion
|
||||
- Consider waking another polecat if reassignment needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Handoff Delivery
|
||||
|
||||
### Mail to Self
|
||||
|
||||
Mayor mails handoff to own inbox:
|
||||
|
||||
```bash
|
||||
town mail send mayor/ -s "Session Handoff" -m "<handoff-content>"
|
||||
```
|
||||
|
||||
### Why Mail (not file)?
|
||||
|
||||
- Consistent with Witness pattern
|
||||
- Timestamped and logged
|
||||
- Works across potential Mayor instances
|
||||
- Integrates with existing inbox check on startup
|
||||
|
||||
### Handoff Template Function
|
||||
|
||||
```python
|
||||
def mayor_handoff(
|
||||
active_swarms: List[SwarmStatus],
|
||||
rig_status: Dict[str, RigStatus],
|
||||
pending_escalations: List[Escalation],
|
||||
in_flight_decisions: List[Decision],
|
||||
recent_actions: List[str],
|
||||
delegated_work: List[DelegatedItem],
|
||||
user_requests: List[str],
|
||||
next_steps: List[str],
|
||||
warnings: Optional[str] = None,
|
||||
session_duration: Optional[str] = None,
|
||||
) -> Message:
|
||||
"""Create Mayor session handoff note."""
|
||||
|
||||
metadata = {
|
||||
"template": "MAYOR_HANDOFF",
|
||||
"timestamp": datetime.utcnow().isoformat(),
|
||||
"session_duration": session_duration,
|
||||
"active_swarm_count": len(active_swarms),
|
||||
"pending_escalation_count": len(pending_escalations),
|
||||
}
|
||||
|
||||
# ... format sections ...
|
||||
|
||||
return Message.create(
|
||||
sender="mayor/",
|
||||
recipient="mayor/",
|
||||
subject="Session Handoff",
|
||||
body=body,
|
||||
priority="high", # Ensure it's seen
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Fresh Session Startup
|
||||
|
||||
### Startup Protocol
|
||||
|
||||
When Mayor session starts:
|
||||
|
||||
1. **Check for handoff**:
|
||||
```bash
|
||||
town inbox | grep "Session Handoff"
|
||||
```
|
||||
|
||||
2. **If handoff exists**:
|
||||
```bash
|
||||
# Read most recent handoff
|
||||
town read <latest-handoff-id>
|
||||
|
||||
# Resume from handoff state
|
||||
# - Address pending escalations first
|
||||
# - Check on in-flight work
|
||||
# - Continue with next steps
|
||||
```
|
||||
|
||||
3. **If no handoff** (fresh start):
|
||||
```bash
|
||||
# Full system status check
|
||||
town status
|
||||
town rigs
|
||||
bd ready
|
||||
|
||||
# Check all rig inboxes for pending items
|
||||
town inbox
|
||||
```
|
||||
|
||||
### Handoff Processing
|
||||
|
||||
```markdown
|
||||
## On Session Start
|
||||
|
||||
1. **Check inbox for handoff**:
|
||||
```bash
|
||||
town inbox
|
||||
```
|
||||
Look for "Session Handoff" messages.
|
||||
|
||||
2. **If handoff found**:
|
||||
- Read the handoff note
|
||||
- Process pending escalations (highest priority)
|
||||
- Check status of noted swarms
|
||||
- Verify rig health matches notes
|
||||
- Continue with documented next steps
|
||||
|
||||
3. **If no handoff**:
|
||||
- Do full status check: `town status`
|
||||
- Check each rig: `town rigs`
|
||||
- Check inbox for any messages
|
||||
- Check beads for work: `bd ready`
|
||||
|
||||
4. **After processing handoff**:
|
||||
- Archive or delete the handoff message
|
||||
- You now own the current state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Integration with Town Commands
|
||||
|
||||
### New Commands (optional, can be deferred)
|
||||
|
||||
```bash
|
||||
# Generate handoff note interactively
|
||||
town handoff
|
||||
|
||||
# Generate and send in one step
|
||||
town handoff --send
|
||||
|
||||
# Check for handoff on startup
|
||||
town resume
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
For now, Mayor does this manually in prompting. Later can add CLI support:
|
||||
|
||||
```go
|
||||
// cmd/gt/cmd/handoff.go
|
||||
var handoffCmd = &cobra.Command{
|
||||
Use: "handoff",
|
||||
Short: "Generate session handoff note",
|
||||
Run: func(cmd *cobra.Command, args []string) {
|
||||
// Gather state
|
||||
swarms := gatherActiveSwarms()
|
||||
rigs := gatherRigStatus()
|
||||
// ... etc
|
||||
|
||||
// Format handoff
|
||||
note := formatHandoffNote(swarms, rigs, ...)
|
||||
|
||||
if send {
|
||||
// Send to mayor inbox
|
||||
mail.Send("mayor/", "Session Handoff", note)
|
||||
} else {
|
||||
// Print for review
|
||||
fmt.Println(note)
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Subtasks
|
||||
|
||||
Based on this design, create these implementation subtasks:
|
||||
|
||||
### gt-u82.1: Mayor session cycling prompting
|
||||
|
||||
Add to Mayor CLAUDE.md:
|
||||
- When to cycle recognition
|
||||
- How to compose handoff note
|
||||
- Handoff format specification
|
||||
|
||||
### gt-u82.2: Mayor startup protocol prompting
|
||||
|
||||
Add to Mayor CLAUDE.md:
|
||||
- Check for handoff on start
|
||||
- Process handoff content
|
||||
- Fresh start fallback
|
||||
|
||||
### gt-u82.3: Mayor handoff mail template
|
||||
|
||||
Add to templates.py:
|
||||
- MAYOR_HANDOFF template
|
||||
- Parsing utilities
|
||||
|
||||
### gt-u82.4: (Optional) town handoff command
|
||||
|
||||
CLI support for handoff generation:
|
||||
- `town handoff` - generate interactively
|
||||
- `town handoff --send` - generate and mail
|
||||
- `town resume` - check for and display handoff
|
||||
|
||||
---
|
||||
|
||||
## Prompting Additions
|
||||
|
||||
### Mayor CLAUDE.md - Session Management Section
|
||||
|
||||
```markdown
|
||||
## Session Management
|
||||
|
||||
### Recognizing When to Cycle
|
||||
|
||||
Monitor your session health. Cycle proactively when:
|
||||
- You've been running for several hours
|
||||
- Context feels crowded (losing track of earlier state)
|
||||
- Major phase completed (good stopping point)
|
||||
- About to start complex new work
|
||||
|
||||
Don't wait for problems - proactive handoff produces cleaner state.
|
||||
|
||||
### Creating Handoff Notes
|
||||
|
||||
Before ending your session, capture current state:
|
||||
|
||||
1. **Gather information**:
|
||||
```bash
|
||||
town status # Overall health
|
||||
town rigs # Each rig's state
|
||||
town inbox # Pending messages
|
||||
bd ready # Work items
|
||||
```
|
||||
|
||||
2. **Compose handoff note** with this structure:
|
||||
|
||||
```
|
||||
[HANDOFF_TYPE]: mayor_cycle
|
||||
[TIMESTAMP]: <current time>
|
||||
[SESSION_DURATION]: <how long you've been running>
|
||||
|
||||
## Active Swarms
|
||||
<list each rig with active swarm, workers, progress>
|
||||
|
||||
## Rig Status
|
||||
<table of rig health>
|
||||
|
||||
## Pending Escalations
|
||||
<issues needing your decision>
|
||||
|
||||
## In-Flight Decisions
|
||||
<decisions you were making>
|
||||
|
||||
## Recent Actions
|
||||
<last 5-10 things you did>
|
||||
|
||||
## Delegated Work
|
||||
<work sent to refineries>
|
||||
|
||||
## User Requests
|
||||
<any pending user asks>
|
||||
|
||||
## Next Steps
|
||||
<what next session should do>
|
||||
|
||||
## Warnings/Notes
|
||||
<critical info for next session>
|
||||
```
|
||||
|
||||
3. **Send handoff**:
|
||||
```bash
|
||||
town mail send mayor/ -s "Session Handoff" -m "<your handoff note>"
|
||||
```
|
||||
|
||||
4. **End session** - next instance will pick up from handoff.
|
||||
|
||||
### On Session Start
|
||||
|
||||
1. **Check for handoff**:
|
||||
```bash
|
||||
town inbox | grep "Session Handoff"
|
||||
```
|
||||
|
||||
2. **If found, read it**:
|
||||
```bash
|
||||
town read <msg-id>
|
||||
```
|
||||
|
||||
3. **Process in priority order**:
|
||||
- Pending escalations (urgent)
|
||||
- In-flight decisions (context-dependent)
|
||||
- Check noted swarm status (may have changed)
|
||||
- Continue with next steps
|
||||
|
||||
4. **If no handoff**:
|
||||
```bash
|
||||
town status
|
||||
town rigs
|
||||
bd ready
|
||||
town inbox
|
||||
```
|
||||
Build your own picture of current state.
|
||||
|
||||
### Handoff Best Practices
|
||||
|
||||
- **Be specific** - "Toast has merge conflict in auth/middleware.go" not "Toast is stuck"
|
||||
- **Include context** - Why decisions are pending, what you were thinking
|
||||
- **Prioritize next steps** - What's most urgent
|
||||
- **Note time-sensitive items** - Anything that might have changed since handoff
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
- [ ] Create subtasks (gt-u82.1 through gt-u82.4)
|
||||
- [ ] Add session management section to Mayor CLAUDE.md template
|
||||
- [ ] Add MAYOR_HANDOFF template to templates.py
|
||||
- [ ] Update startup instructions in Mayor prompting
|
||||
- [ ] (Optional) Implement town handoff command
|
||||
@@ -0,0 +1,448 @@
|
||||
# Polecat Beads Write Access Design
|
||||
|
||||
Design for granting polecats direct beads write access.
|
||||
|
||||
**Epic**: gt-l3c (Design: Polecat Beads write access)
|
||||
|
||||
## Background
|
||||
|
||||
Originally, polecats were read-only for beads to prevent multi-agent conflicts.
|
||||
With Beads v0.30.0's tombstone-based rearchitecture for deletions, we now have
|
||||
solid multi-agent support even at high concurrent load.
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Simplifies architecture** - No need for mail-based issue filing proxy via Witness
|
||||
2. **Empowers polecats** - Can file discovered work that's out of their purview
|
||||
3. **Beads handles work-disavowal** - Workers can close issues they didn't start
|
||||
4. **Faster feedback** - No round-trip through Witness for issue creation
|
||||
|
||||
## Complications
|
||||
|
||||
For OSS projects where you're not a maintainer:
|
||||
- Can't commit to the project's `.beads/` directory
|
||||
- Need to file beads in a separate repo
|
||||
- Beads supports this via `--root` flag
|
||||
|
||||
## Subtask Designs
|
||||
|
||||
---
|
||||
|
||||
### gt-zx3: Per-Rig Beads Configuration
|
||||
|
||||
#### Config Location
|
||||
|
||||
Per-rig configuration lives in the rig's config:
|
||||
|
||||
**Option A: In rig state.json** (simpler)
|
||||
```
|
||||
<rig>/config.json (or state.json)
|
||||
```
|
||||
|
||||
**Option B: In town-level rigs.json** (centralized)
|
||||
```
|
||||
config/rigs.json
|
||||
```
|
||||
|
||||
Recommend **Option A** - each rig owns its config, easier to manage.
|
||||
|
||||
#### Config Schema
|
||||
|
||||
```json
|
||||
// <rig>/config.json
|
||||
{
|
||||
"version": 1,
|
||||
"name": "wyvern",
|
||||
"git_url": "https://github.com/steveyegge/wyvern",
|
||||
|
||||
"beads": {
|
||||
// Where polecats file beads
|
||||
// Options: "local" | "<path>" | "<git-url>"
|
||||
"repo": "local",
|
||||
|
||||
// Override bd --root (optional, derived from repo if not set)
|
||||
"root": null,
|
||||
|
||||
// Issue prefix for this rig (used by bd create)
|
||||
"prefix": "wyv"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Repo Options
|
||||
|
||||
| Value | Meaning | Use Case |
|
||||
|-------|---------|----------|
|
||||
| `"local"` | Use project's `.beads/` | Own projects, full commit access |
|
||||
| `"<path>"` | Use beads at path | OSS contributions, external beads |
|
||||
| `"<git-url>"` | Clone and use repo | Team shared beads |
|
||||
|
||||
#### Examples
|
||||
|
||||
**Local project (default)**:
|
||||
```json
|
||||
{
|
||||
"beads": {
|
||||
"repo": "local",
|
||||
"prefix": "wyv"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**OSS contribution** (can't commit to project):
|
||||
```json
|
||||
{
|
||||
"beads": {
|
||||
"repo": "/home/user/my-beads/react-contributions",
|
||||
"prefix": "react"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Team shared beads**:
|
||||
```json
|
||||
{
|
||||
"beads": {
|
||||
"repo": "https://github.com/myteam/shared-beads",
|
||||
"prefix": "team"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Environment Variable Injection
|
||||
|
||||
When spawning polecats, Gas Town sets:
|
||||
|
||||
```bash
|
||||
export BEADS_ROOT="<resolved-path>"
|
||||
# Polecats use bd normally; it respects BEADS_ROOT
|
||||
```
|
||||
|
||||
Or pass explicit flag in spawn:
|
||||
```bash
|
||||
# Gas Town wraps bd calls internally
|
||||
bd --root "$BEADS_ROOT" create --title="..."
|
||||
```
|
||||
|
||||
#### Resolution Logic
|
||||
|
||||
```go
|
||||
func ResolveBeadsRoot(rigConfig *RigConfig, rigPath string) (string, error) {
|
||||
beads := rigConfig.Beads
|
||||
|
||||
switch {
|
||||
case beads.Root != "":
|
||||
// Explicit root override
|
||||
return beads.Root, nil
|
||||
|
||||
case beads.Repo == "local" || beads.Repo == "":
|
||||
// Use project's .beads/
|
||||
return filepath.Join(rigPath, ".beads"), nil
|
||||
|
||||
case strings.HasPrefix(beads.Repo, "/") || strings.HasPrefix(beads.Repo, "~"):
|
||||
// Absolute path
|
||||
return expandPath(beads.Repo), nil
|
||||
|
||||
case strings.Contains(beads.Repo, "://"):
|
||||
// Git URL - need to clone
|
||||
return cloneAndResolve(beads.Repo)
|
||||
|
||||
default:
|
||||
// Relative path from rig
|
||||
return filepath.Join(rigPath, beads.Repo), nil
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### gt-e1y: Worker Prompting - Beads Write Access
|
||||
|
||||
Add to polecat CLAUDE.md template (AGENTS.md.template):
|
||||
|
||||
```markdown
|
||||
## Beads Access
|
||||
|
||||
You have **full beads access** - you can create, update, and close issues.
|
||||
|
||||
### Quick Reference
|
||||
|
||||
```bash
|
||||
# View available work
|
||||
bd ready # Issues ready to work (no blockers)
|
||||
bd list # All open issues
|
||||
bd show <id> # Issue details
|
||||
|
||||
# Create issues
|
||||
bd create --title="Fix login bug" --type=bug --priority=2
|
||||
bd create --title="Add dark mode" --type=feature
|
||||
|
||||
# Update issues
|
||||
bd update <id> --status=in_progress # Claim work
|
||||
bd close <id> # Mark complete
|
||||
bd close <id> --reason="Duplicate of <other>"
|
||||
|
||||
# Sync (required before merge!)
|
||||
bd sync # Commit beads changes to git
|
||||
bd sync --status # Check if sync needed
|
||||
```
|
||||
|
||||
### When to Create Issues
|
||||
|
||||
Create beads issues when you discover work that:
|
||||
- Is outside your current task scope
|
||||
- Would benefit from tracking
|
||||
- Should be done by someone else (or future you)
|
||||
|
||||
**Good examples**:
|
||||
```bash
|
||||
# Found a bug while implementing feature
|
||||
bd create --title="Race condition in auth middleware" --type=bug --priority=1
|
||||
|
||||
# Noticed missing documentation
|
||||
bd create --title="Document API rate limits" --type=task --priority=3
|
||||
|
||||
# Tech debt worth tracking
|
||||
bd create --title="Refactor legacy payment module" --type=task --priority=4
|
||||
```
|
||||
|
||||
**Don't create issues for**:
|
||||
- Tiny fixes you can do in 2 minutes (just do them)
|
||||
- Vague "improvements" with no clear scope
|
||||
- Work that's already tracked elsewhere
|
||||
|
||||
### Issue Lifecycle
|
||||
|
||||
```
|
||||
┌─────────┐ ┌─────────────┐ ┌──────────┐
|
||||
│ open │───►│ in_progress │───►│ closed │
|
||||
└─────────┘ └─────────────┘ └──────────┘
|
||||
│ ▲
|
||||
└───────────────────────────────────┘
|
||||
(can close directly)
|
||||
```
|
||||
|
||||
You can close issues without claiming them first.
|
||||
Useful for quick fixes or discovered duplicates.
|
||||
|
||||
### Beads Sync Protocol
|
||||
|
||||
**CRITICAL**: Always sync beads before merging to main!
|
||||
|
||||
```bash
|
||||
# Before your final merge
|
||||
bd sync # Commits beads changes
|
||||
git status # Should show .beads/ changes
|
||||
git add .beads/
|
||||
git commit -m "beads: sync"
|
||||
# Then proceed with merge to main
|
||||
```
|
||||
|
||||
If you forget to sync, your beads changes will be lost when your session ends.
|
||||
|
||||
### Your Beads Repo
|
||||
|
||||
Your beads are configured for this rig. You don't need to specify --root.
|
||||
Just use `bd` commands normally.
|
||||
|
||||
To check where your beads go:
|
||||
```bash
|
||||
bd config show root
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### gt-cjb: Witness Updates - Remove Issue Filing Proxy
|
||||
|
||||
Update Witness CLAUDE.md to remove proxy responsibilities:
|
||||
|
||||
**REMOVE from Witness prompting**:
|
||||
|
||||
```markdown
|
||||
## Issue Filing Proxy (REMOVED)
|
||||
|
||||
The following is NO LONGER your responsibility:
|
||||
- Processing polecat "file issue" mail requests
|
||||
- Creating issues on behalf of polecats
|
||||
- Forwarding issue creation requests
|
||||
|
||||
Polecats now have direct beads write access and file their own issues.
|
||||
```
|
||||
|
||||
**KEEP in Witness prompting** (from swarm-shutdown-design.md):
|
||||
- Monitoring polecat progress
|
||||
- Nudge protocol
|
||||
- Pre-kill verification
|
||||
- Session lifecycle management
|
||||
|
||||
**UPDATE**: If Witness receives an old-style "please file issue" request:
|
||||
|
||||
```markdown
|
||||
### Legacy Issue Filing Requests
|
||||
|
||||
If you receive a mail asking you to file an issue on a polecat's behalf:
|
||||
|
||||
1. **Respond with update**:
|
||||
```bash
|
||||
town inject <polecat> "UPDATE: You have direct beads access now. Use 'bd create --title=\"...\" --type=...' to file issues yourself."
|
||||
```
|
||||
|
||||
2. **Don't file the issue yourself** - let the polecat learn the new workflow.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### gt-082: Worker Cleanup - Beads Sync on Shutdown
|
||||
|
||||
This integrates with swarm-shutdown-design.md decommission checklist.
|
||||
|
||||
**Update to decommission checklist** (addition to gt-sd6):
|
||||
|
||||
```markdown
|
||||
## Decommission Checklist (Updated)
|
||||
|
||||
### Pre-Done Verification
|
||||
|
||||
```bash
|
||||
# 1. Git status - must be clean
|
||||
git status
|
||||
# Expected: "nothing to commit, working tree clean"
|
||||
|
||||
# 2. Stash list - must be empty
|
||||
git stash list
|
||||
# Expected: (empty)
|
||||
|
||||
# 3. Beads sync - MUST be synced
|
||||
bd sync --status
|
||||
# Expected: "Up to date" or "Nothing to sync"
|
||||
# If not: run 'bd sync' first!
|
||||
|
||||
# 4. Beads committed - verify in git
|
||||
git status
|
||||
# Expected: .beads/ should NOT show changes
|
||||
# If it does: git add .beads/ && git commit -m "beads: sync"
|
||||
|
||||
# 5. Branch merged to main
|
||||
git log main --oneline -1
|
||||
git log HEAD --oneline -1
|
||||
# Expected: Same commit
|
||||
```
|
||||
|
||||
### Beads Edge Cases
|
||||
|
||||
**Uncommitted beads changes**:
|
||||
```bash
|
||||
bd sync # Commits to .beads/
|
||||
git add .beads/
|
||||
git commit -m "beads: final sync"
|
||||
```
|
||||
|
||||
**Beads sync conflict** (rare):
|
||||
```bash
|
||||
# If bd sync fails with conflict:
|
||||
git fetch origin main
|
||||
git checkout main -- .beads/
|
||||
bd sync --force # Re-apply your changes
|
||||
git add .beads/
|
||||
git commit -m "beads: resolve sync conflict"
|
||||
```
|
||||
```
|
||||
|
||||
**Update to Witness pre-kill verification** (addition to gt-f8v):
|
||||
|
||||
```markdown
|
||||
### Beads-Specific Verification
|
||||
|
||||
When capturing worker state, also check beads:
|
||||
|
||||
```bash
|
||||
town capture <polecat> "bd sync --status && git status .beads/"
|
||||
```
|
||||
|
||||
**Check for**:
|
||||
- `bd sync --status` shows "Up to date"
|
||||
- `git status .beads/` shows no changes
|
||||
|
||||
**If beads not synced**:
|
||||
```
|
||||
town inject <polecat> "WITNESS CHECK: Beads not synced. Run 'bd sync' then 'git add .beads/ && git commit -m \"beads: sync\"'. Signal done again when complete."
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Config File Examples
|
||||
|
||||
### Rig with local beads (default)
|
||||
|
||||
```json
|
||||
// gastown/config.json
|
||||
{
|
||||
"version": 1,
|
||||
"name": "gastown",
|
||||
"git_url": "https://github.com/steveyegge/gastown",
|
||||
"beads": {
|
||||
"repo": "local",
|
||||
"prefix": "gt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rig contributing to OSS project
|
||||
|
||||
```json
|
||||
// react/config.json
|
||||
{
|
||||
"version": 1,
|
||||
"name": "react",
|
||||
"git_url": "https://github.com/facebook/react",
|
||||
"beads": {
|
||||
"repo": "/home/steve/my-beads/react",
|
||||
"prefix": "react"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rig with team shared beads
|
||||
|
||||
```json
|
||||
// internal-app/config.json
|
||||
{
|
||||
"version": 1,
|
||||
"name": "internal-app",
|
||||
"git_url": "https://github.com/mycompany/internal-app",
|
||||
"beads": {
|
||||
"repo": "https://github.com/mycompany/team-beads",
|
||||
"prefix": "app"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### For Existing Rigs
|
||||
|
||||
1. Add `beads` section to rig config.json
|
||||
2. Default to `"repo": "local"` if not specified
|
||||
3. Update polecat CLAUDE.md templates
|
||||
4. Remove Witness proxy code
|
||||
|
||||
### Backwards Compatibility
|
||||
|
||||
- If `beads` section missing, assume `"repo": "local"`
|
||||
- Old-style "file issue" mail requests get redirect nudge
|
||||
- No breaking changes for polecats already using bd read commands
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
- [ ] Add beads config schema to rig config (gt-zx3)
|
||||
- [ ] Update polecat CLAUDE.md template with bd write access (gt-e1y)
|
||||
- [ ] Update Witness CLAUDE.md to remove proxy, add redirect (gt-cjb)
|
||||
- [ ] Update decommission checklist with beads sync (gt-082)
|
||||
- [ ] Update Witness verification to check beads sync (gt-082)
|
||||
- [ ] Add BEADS_ROOT environment injection to spawn logic
|
||||
@@ -0,0 +1,554 @@
|
||||
# Swarm Shutdown Design
|
||||
|
||||
Design for graceful swarm shutdown, worker cleanup, and session cycling.
|
||||
|
||||
**Epic**: gt-82y (Design: Swarm shutdown and worker cleanup)
|
||||
|
||||
## Key Decisions (from ultrathink)
|
||||
|
||||
1. **Pre-kill verification uses model intelligence** - Witness assesses git status output, not framework rules
|
||||
2. **Witness can request restart** - Mail self handoff notes, exit cleanly when context filling
|
||||
3. **Mayor NOT involved in per-worker cleanup** - That's Witness's domain
|
||||
4. **Polecats verify themselves first** - Decommission checklist in prompting, Witness double-checks
|
||||
|
||||
## Responsibility Boundaries (gt-gl2)
|
||||
|
||||
### Mayor Responsibilities
|
||||
- Swarm dispatch and strategic planning
|
||||
- Cross-rig coordination
|
||||
- Escalation handling (when Witness reports blocked workers)
|
||||
- Final integration decisions
|
||||
- **NOT**: Per-worker cleanup, session killing, nudging
|
||||
|
||||
### Witness Responsibilities
|
||||
- Monitor worker health and progress
|
||||
- Nudge workers toward completion
|
||||
- Pre-kill verification (capture & assess git status)
|
||||
- Session lifecycle (kill, restart workers)
|
||||
- Self session cycling (mail handoff, exit)
|
||||
- Report blocked workers to Mayor for escalation
|
||||
- **NOT**: Implementation work, cross-rig coordination
|
||||
|
||||
### Polecat Responsibilities
|
||||
- Complete assigned work
|
||||
- Self-verify before signaling done (decommission checklist)
|
||||
- Respond to Witness nudges
|
||||
- **NOT**: Killing own session, coordinating with other polecats directly
|
||||
|
||||
## Subtask Designs
|
||||
|
||||
---
|
||||
|
||||
### gt-sd6: Enhanced Polecat Decommission Prompting
|
||||
|
||||
Add to polecat CLAUDE.md template (AGENTS.md.template):
|
||||
|
||||
```markdown
|
||||
## Decommission Checklist
|
||||
|
||||
**CRITICAL**: Before signaling you are done, you MUST complete this checklist.
|
||||
The Witness will verify each item and bounce you back if anything is dirty.
|
||||
|
||||
### Pre-Done Verification
|
||||
|
||||
Run these commands and verify ALL are clean:
|
||||
|
||||
```bash
|
||||
# 1. Git status - must be clean (no uncommitted changes)
|
||||
git status
|
||||
# Expected: "nothing to commit, working tree clean"
|
||||
|
||||
# 2. Stash list - must be empty (no forgotten stashes)
|
||||
git stash list
|
||||
# Expected: (empty output)
|
||||
|
||||
# 3. Beads sync - must be up to date
|
||||
bd sync --status
|
||||
# Expected: "Up to date" or "Nothing to sync"
|
||||
|
||||
# 4. Branch merged - your work must be on main
|
||||
git log main --oneline -1
|
||||
git log HEAD --oneline -1
|
||||
# Expected: Same commit (your branch is merged)
|
||||
```
|
||||
|
||||
### If Any Check Fails
|
||||
|
||||
- **Uncommitted changes**: Commit them or discard if truly unnecessary
|
||||
- **Stashes**: Pop and commit, or drop if obsolete
|
||||
- **Beads out of sync**: Run `bd sync`
|
||||
- **Branch not merged**: Complete the merge workflow
|
||||
|
||||
### Signaling Done
|
||||
|
||||
Only after ALL checks pass:
|
||||
|
||||
```bash
|
||||
# Close your issue
|
||||
bd close <issue-id>
|
||||
|
||||
# Final sync
|
||||
bd sync
|
||||
|
||||
# Signal ready for decommission
|
||||
town mail send <rig>/witness -s "Work Complete" -m "Issue <id> done. Checklist verified."
|
||||
```
|
||||
|
||||
The Witness will capture your git state and verify before killing your session.
|
||||
If anything is dirty, you'll receive a nudge with specific issues to fix.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### gt-f8v: Witness Pre-Kill Verification Protocol
|
||||
|
||||
Add to Witness CLAUDE.md template:
|
||||
|
||||
```markdown
|
||||
## Pre-Kill Verification Protocol
|
||||
|
||||
Before killing any worker session, you MUST verify their workspace is clean.
|
||||
Use your judgment on the output - don't rely on pattern matching.
|
||||
|
||||
### Verification Steps
|
||||
|
||||
When a worker signals done:
|
||||
|
||||
1. **Capture worker state**:
|
||||
```bash
|
||||
# Attach and capture git status
|
||||
town capture <polecat> "git status && git stash list && git log --oneline -3"
|
||||
```
|
||||
|
||||
2. **Assess the output** (use your judgment):
|
||||
- Is working tree clean? (no modified/untracked files that matter)
|
||||
- Is stash list empty? (or only contains intentional stashes)
|
||||
- Does recent history show their work is committed?
|
||||
|
||||
3. **Decision**:
|
||||
- **CLEAN**: Proceed to kill session
|
||||
- **DIRTY**: Send nudge with specific issues
|
||||
|
||||
### Nudge Templates
|
||||
|
||||
**Uncommitted Changes**:
|
||||
```
|
||||
town inject <polecat> "WITNESS CHECK: You have uncommitted changes. Please commit or discard: <list files>. Signal done again when clean."
|
||||
```
|
||||
|
||||
**Stash Not Empty**:
|
||||
```
|
||||
town inject <polecat> "WITNESS CHECK: You have stashed changes. Please pop and commit, or drop if obsolete: <stash list>. Signal done again when clean."
|
||||
```
|
||||
|
||||
**Work Not Merged**:
|
||||
```
|
||||
town inject <polecat> "WITNESS CHECK: Your commits are not on main. Please complete merge workflow. Signal done again when merged."
|
||||
```
|
||||
|
||||
**Multiple Issues**:
|
||||
```
|
||||
town inject <polecat> "WITNESS CHECK: Multiple issues found:
|
||||
1. <issue 1>
|
||||
2. <issue 2>
|
||||
Please resolve all and signal done again."
|
||||
```
|
||||
|
||||
### Kill Sequence
|
||||
|
||||
Only after verification passes:
|
||||
|
||||
```bash
|
||||
# Log the verification
|
||||
echo "[$(date)] Verified clean: <polecat>" >> witness/verification.log
|
||||
|
||||
# Kill the session
|
||||
town kill <polecat>
|
||||
|
||||
# Update state
|
||||
town sleep <polecat>
|
||||
```
|
||||
|
||||
### Escalation
|
||||
|
||||
If a worker fails verification 3+ times or becomes unresponsive:
|
||||
|
||||
```bash
|
||||
town mail send mayor/ -s "Escalation: <polecat> stuck" -m "Worker <polecat> cannot complete cleanup after 3 attempts. Issues: <list>. Requesting guidance."
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### gt-eu9: Witness Session Cycling and Handoff
|
||||
|
||||
Add to Witness CLAUDE.md template:
|
||||
|
||||
```markdown
|
||||
## Session Cycling
|
||||
|
||||
Your context will fill over long swarms. When you notice significant context usage
|
||||
or feel you're losing track of state, proactively cycle your session.
|
||||
|
||||
### Recognizing When to Cycle
|
||||
|
||||
Signs you should cycle:
|
||||
- You've been running for many hours
|
||||
- You're losing track of which workers you've checked
|
||||
- Responses are getting slower or less coherent
|
||||
- You're about to start a complex operation
|
||||
|
||||
### Handoff Protocol
|
||||
|
||||
1. **Capture current state**:
|
||||
```bash
|
||||
# Check all worker states
|
||||
town list .
|
||||
|
||||
# Check pending verifications
|
||||
town all beads
|
||||
|
||||
# Check your inbox for unprocessed messages
|
||||
town inbox
|
||||
```
|
||||
|
||||
2. **Compose handoff note**:
|
||||
```bash
|
||||
town mail send <rig>/witness -s "Session Handoff" -m "$(cat <<'EOF'
|
||||
[HANDOFF_TYPE]: witness_cycle
|
||||
[TIMESTAMP]: $(date -Iseconds)
|
||||
[RIG]: <rig>
|
||||
|
||||
## Active Workers
|
||||
<list workers and their current status>
|
||||
|
||||
## Pending Verifications
|
||||
<workers who signaled done but not yet verified>
|
||||
|
||||
## Recent Actions
|
||||
<last 3-5 actions taken>
|
||||
|
||||
## Warnings/Notes
|
||||
<anything the next session should know>
|
||||
|
||||
## Next Steps
|
||||
<what should happen next>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
3. **Exit cleanly**:
|
||||
```bash
|
||||
# Ensure no pending operations
|
||||
# Then simply end your session - the daemon will spawn a fresh one
|
||||
```
|
||||
|
||||
### Handoff Note Format
|
||||
|
||||
The handoff note uses metadata format for parseability:
|
||||
|
||||
```
|
||||
[HANDOFF_TYPE]: witness_cycle
|
||||
[TIMESTAMP]: 2024-01-15T10:30:00Z
|
||||
[RIG]: gastown
|
||||
|
||||
## Active Workers
|
||||
- Furiosa: working on gt-abc1 (spawned 2h ago)
|
||||
- Toast: idle, awaiting assignment
|
||||
- Capable: signaled done, pending verification
|
||||
|
||||
## Pending Verifications
|
||||
- Capable: signaled done at 10:25, not yet verified
|
||||
|
||||
## Recent Actions
|
||||
1. Verified and killed Nux (gt-xyz9 complete)
|
||||
2. Spawned Furiosa on gt-abc1
|
||||
3. Received done signal from Capable
|
||||
|
||||
## Warnings/Notes
|
||||
- Furiosa has been quiet for 30min, may need nudge
|
||||
- Integration branch has 3 merged PRs
|
||||
|
||||
## Next Steps
|
||||
1. Verify Capable's workspace
|
||||
2. Check on Furiosa's progress
|
||||
3. Report status to Refinery if all workers done
|
||||
```
|
||||
|
||||
### On Fresh Session Start
|
||||
|
||||
When you start (or restart after cycling):
|
||||
|
||||
1. **Check for handoff**:
|
||||
```bash
|
||||
town inbox | grep "Session Handoff"
|
||||
```
|
||||
|
||||
2. **If handoff exists, read it**:
|
||||
```bash
|
||||
town read <handoff-msg-id>
|
||||
```
|
||||
|
||||
3. **Resume from handoff state** - pick up pending verifications, check noted workers
|
||||
|
||||
4. **If no handoff** - do full status check:
|
||||
```bash
|
||||
town list .
|
||||
town all beads
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### gt-gl2: Mayor vs Witness Cleanup Documentation
|
||||
|
||||
This goes in the main Gas Town documentation or CLAUDE.md templates.
|
||||
|
||||
```markdown
|
||||
## Cleanup Authority Model
|
||||
|
||||
Gas Town uses a clear separation of cleanup responsibilities:
|
||||
|
||||
### The Rule
|
||||
**Witness handles ALL per-worker cleanup. Mayor is never involved.**
|
||||
|
||||
### Why This Matters
|
||||
|
||||
1. **Separation of concerns**: Mayor thinks strategically, Witness thinks operationally
|
||||
2. **Reduced coordination overhead**: No back-and-forth for routine cleanup
|
||||
3. **Faster shutdown**: Witness can kill workers immediately upon verification
|
||||
4. **Cleaner escalation**: Mayor only hears about problems, not routine operations
|
||||
|
||||
### What "Cleanup" Means
|
||||
|
||||
Witness handles:
|
||||
- Verifying worker git state before kill
|
||||
- Nudging workers to fix dirty state
|
||||
- Killing worker sessions
|
||||
- Updating worker state (sleep/wake)
|
||||
- Logging verification results
|
||||
|
||||
Mayor handles:
|
||||
- Receiving "swarm complete" notifications
|
||||
- Deciding whether to start new swarms
|
||||
- Handling escalations (stuck workers after multiple retries)
|
||||
- Cross-rig coordination if workers need to hand off
|
||||
|
||||
### Escalation Path
|
||||
|
||||
```
|
||||
Worker stuck -> Witness nudges (up to 3x) -> Witness escalates to Mayor
|
||||
-> Mayor decides: force kill, reassign, or human intervention
|
||||
```
|
||||
|
||||
### Anti-Patterns
|
||||
|
||||
**DON'T**: Have Mayor ask Witness "is worker X clean?"
|
||||
**DO**: Have Witness report "swarm complete, all workers verified and killed"
|
||||
|
||||
**DON'T**: Have Mayor kill worker sessions directly
|
||||
**DO**: Have Mayor tell Witness "abort swarm" and let Witness handle cleanup
|
||||
|
||||
**DON'T**: Have workers report done to Mayor
|
||||
**DO**: Have workers report done to Witness, Witness aggregates and reports to Refinery/Mayor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mail Templates (additions to templates.py)
|
||||
|
||||
### WORKER_DONE (Worker -> Witness)
|
||||
|
||||
```python
|
||||
def worker_done(
|
||||
sender: str,
|
||||
rig: str,
|
||||
issue_id: str,
|
||||
checklist_verified: bool = True,
|
||||
) -> Message:
|
||||
"""Worker signals completion to Witness."""
|
||||
metadata = {
|
||||
"template": "WORKER_DONE",
|
||||
"rig": rig,
|
||||
"issue": issue_id,
|
||||
"checklist_verified": checklist_verified,
|
||||
}
|
||||
|
||||
body = f"""Work complete on {issue_id}.
|
||||
|
||||
{_format_metadata(metadata)}
|
||||
|
||||
Decommission checklist {'verified' if checklist_verified else 'NOT verified - please check'}.
|
||||
Ready for verification and session termination.
|
||||
"""
|
||||
return Message.create(
|
||||
sender=sender,
|
||||
recipient=f"{rig}/witness",
|
||||
subject=f"Work Complete: {issue_id}",
|
||||
body=body,
|
||||
)
|
||||
```
|
||||
|
||||
### VERIFICATION_FAILED (Witness -> Worker, via inject)
|
||||
|
||||
```python
|
||||
def verification_failed(
|
||||
worker: str,
|
||||
issues: List[str],
|
||||
) -> str:
|
||||
"""Generate nudge text for failed verification (injected, not mailed)."""
|
||||
issues_text = "\n".join(f" - {issue}" for issue in issues)
|
||||
return f"""WITNESS VERIFICATION FAILED
|
||||
|
||||
The following issues must be resolved before decommission:
|
||||
{issues_text}
|
||||
|
||||
Please fix these issues and signal done again.
|
||||
"""
|
||||
```
|
||||
|
||||
### WITNESS_HANDOFF (Witness -> Witness)
|
||||
|
||||
```python
|
||||
def witness_handoff(
|
||||
sender: str,
|
||||
rig: str,
|
||||
active_workers: List[Dict],
|
||||
pending_verifications: List[str],
|
||||
recent_actions: List[str],
|
||||
warnings: Optional[str] = None,
|
||||
next_steps: List[str] = None,
|
||||
) -> Message:
|
||||
"""Witness session handoff note."""
|
||||
metadata = {
|
||||
"template": "WITNESS_HANDOFF",
|
||||
"rig": rig,
|
||||
"timestamp": datetime.utcnow().isoformat(),
|
||||
"active_worker_count": len(active_workers),
|
||||
"pending_verification_count": len(pending_verifications),
|
||||
}
|
||||
|
||||
# Format workers
|
||||
workers_text = "\n".join(
|
||||
f"- {w['name']}: {w['status']}" for w in active_workers
|
||||
) or "None"
|
||||
|
||||
# Format pending
|
||||
pending_text = "\n".join(f"- {p}" for p in pending_verifications) or "None"
|
||||
|
||||
# Format actions
|
||||
actions_text = "\n".join(f"{i+1}. {a}" for i, a in enumerate(recent_actions[-5:]))
|
||||
|
||||
body = f"""Session handoff for {rig} Witness.
|
||||
|
||||
{_format_metadata(metadata)}
|
||||
|
||||
## Active Workers
|
||||
{workers_text}
|
||||
|
||||
## Pending Verifications
|
||||
{pending_text}
|
||||
|
||||
## Recent Actions
|
||||
{actions_text}
|
||||
|
||||
## Warnings
|
||||
{warnings or "None"}
|
||||
|
||||
## Next Steps
|
||||
{chr(10).join(f"- {s}" for s in (next_steps or ["Check pending verifications"]))}
|
||||
"""
|
||||
return Message.create(
|
||||
sender=sender,
|
||||
recipient=f"{rig}/witness",
|
||||
subject="Session Handoff",
|
||||
body=body,
|
||||
)
|
||||
```
|
||||
|
||||
### ESCALATION (Witness -> Mayor)
|
||||
|
||||
```python
|
||||
def worker_escalation(
|
||||
sender: str,
|
||||
rig: str,
|
||||
worker: str,
|
||||
issue_id: str,
|
||||
attempts: int,
|
||||
unresolved_issues: List[str],
|
||||
) -> Message:
|
||||
"""Witness escalates stuck worker to Mayor."""
|
||||
metadata = {
|
||||
"template": "WORKER_ESCALATION",
|
||||
"rig": rig,
|
||||
"worker": worker,
|
||||
"issue": issue_id,
|
||||
"verification_attempts": attempts,
|
||||
}
|
||||
|
||||
issues_text = "\n".join(f" - {i}" for i in unresolved_issues)
|
||||
|
||||
body = f"""Worker {worker} cannot complete cleanup.
|
||||
|
||||
{_format_metadata(metadata)}
|
||||
|
||||
After {attempts} verification attempts, the following issues remain:
|
||||
{issues_text}
|
||||
|
||||
Requesting guidance:
|
||||
1. Force kill and abandon changes?
|
||||
2. Reassign to another worker?
|
||||
3. Escalate to human?
|
||||
"""
|
||||
return Message.create(
|
||||
sender=sender,
|
||||
recipient="mayor/",
|
||||
subject=f"Escalation: {worker} stuck on {issue_id}",
|
||||
body=body,
|
||||
priority="high",
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Verification State Tracking
|
||||
|
||||
Witness should track verification attempts in memory (or state.json):
|
||||
|
||||
```json
|
||||
{
|
||||
"pending_verifications": {
|
||||
"Furiosa": {
|
||||
"issue_id": "gt-abc1",
|
||||
"signaled_at": "2024-01-15T10:25:00Z",
|
||||
"attempts": 1,
|
||||
"last_issues": ["uncommitted changes in src/foo.py"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Nudge vs Mail
|
||||
|
||||
- **Nudge (inject)**: For immediate attention - verification failures, progress checks
|
||||
- **Mail**: For async communication - handoffs, escalations, status reports
|
||||
|
||||
### Timeout Handling
|
||||
|
||||
If worker doesn't respond to nudge within reasonable time:
|
||||
1. First: Re-nudge with more urgency
|
||||
2. Second: Capture their session state for diagnostics
|
||||
3. Third: Escalate to Mayor
|
||||
|
||||
---
|
||||
|
||||
## Checklist for Implementation
|
||||
|
||||
- [ ] Update AGENTS.md.template with decommission checklist (gt-sd6)
|
||||
- [ ] Create WITNESS_CLAUDE.md template with verification protocol (gt-f8v)
|
||||
- [ ] Add session cycling to Witness prompting (gt-eu9)
|
||||
- [ ] Document cleanup authority in main docs (gt-gl2)
|
||||
- [ ] Add mail templates to templates.py
|
||||
- [ ] Add verification state to Witness state.json schema
|
||||
Reference in New Issue
Block a user