Status Polling Pattern

Proactive orchestrator monitoring for swarm health and conflict detection.

Overview

Instead of fire-and-forget agent launching, the orchestrator periodically spawns lightweight "status checker" agents to monitor swarm progress and identify issues early.

Why Polling Matters

Without polling:

• Orchestrator has no visibility into agent progress
• Conflicts discovered only after damage is done
• Stuck agents waste time until final timeout
• No opportunity for mid-execution corrections

With polling:

• Real-time visibility into agent status
• Conflicts detected and resolved quickly
• Stuck agents identified and reassigned
• Dynamic load balancing possible

Polling Schedule

Recommended Intervals

Phase	Interval	Reason
Initial launch	30 seconds	Catch early failures fast
Active execution	45-60 seconds	Balance visibility vs overhead
Near completion	30 seconds	Ensure clean handoffs
Post-completion	Immediate	Verify success, launch next batch

Adaptive Polling

Adjust frequency based on:

• More frequent: High-conflict swarms, many parallel agents
• Less frequent: Simple tasks, sequential execution
• Immediate: After any agent reports an issue

Status Checker Agent

The status-checker agent is designed for fast, lightweight execution:

model: haiku  # Fast and cheap
tools: Read, Glob, Grep  # Read-only, no edits

What It Checks

1. Agent Status
2. Last update timestamp
3. Current task progress
4. Reported errors or warnings

1. File Claims
2. Ownership conflicts
3. Stale claims from completed agents
4. Unclaimed files being edited

1. Overall Health
2. Completion percentage
3. Estimated time remaining
4. Bottlenecks and blockers

Output Format

{
  "timestamp": "2025-01-15T10:35:00Z",
  "overall_health": "warning",
  "completion_percentage": 65,
  "issues": {
    "conflicts": [{
      "file": "src/api/handler.ts",
      "agents": ["agent-1", "agent-3"],
      "severity": "critical"
    }],
    "stuck_agents": [{
      "id": "agent-2",
      "last_update": "2025-01-15T10:30:00Z",
      "duration_seconds": 300
    }]
  },
  "recommendations": [
    {"action": "pause", "target": "agent-3", "reason": "resolve conflict"}
  ]
}

Responding to Status Reports

Healthy Status

{"overall_health": "healthy"}

• Continue execution
• Schedule next poll at normal interval

Warning Status

{"overall_health": "warning", "issues": {...}}

• Review specific issues
• Take corrective action if needed
• Increase polling frequency temporarily

Critical Status

{"overall_health": "critical", "issues": {...}}

• Pause affected agents immediately
• Resolve conflicts before continuing
• Consider notifying user for input

Implementation Example

## During Implementation Phase

1. Launch batch 1 agents (agent-1, agent-2)
2. Wait 30 seconds
3. Launch status-checker agent
4. If healthy: continue, schedule next check in 45 seconds
5. If issues:
   - Conflicts: Pause later agent, let first complete
   - Stuck: Check logs, consider timeout or reassignment
   - Failed: Report to user, decide on retry/skip
6. Repeat until all agents complete

Polling vs Event-Driven

Approach	Pros	Cons
Polling	Simple, no agent modification needed	Some latency in detection
Events	Immediate detection	Requires agent cooperation

This plugin uses polling because:

• Works with any agent without modification
• Orchestrator maintains full control
• Simpler implementation
• Haiku model makes polling cheap

Best Practices

1. Use haiku for status checks - Fast and cheap
2. Don't poll too frequently - 30 seconds minimum
3. Act on issues promptly - Don't just log and continue
4. Track polling history - Useful for debugging
5. Combine with file claims - Polling detects, claims prevent