NEEDLE

NEEDLE is a headless orchestrator that treats AI agents as interchangeable components in a deterministic state machine. The thesis is simple: if an outcome can happen, it has a handler. If it doesn't have a handler, it cannot happen. This constraint—no implicit fallbacks, no wildcards, no 'swallow the error and hope'—is what makes unattended multi-agent fleets actually runnable. When a worker crashes mid-task, when a rate-limit kicks in, when two workers race for the same task, NEEDLE already knows what happens next because every possible outcome has an explicit handler.

A NEEDLE worker runs a six-step loop in a tight cycle. SELECT queries the shared bead queue for the next claimable task in deterministic priority order. CLAIM atomically reserves the task via a SQLite transaction—exactly one worker wins, the loser continues to the next candidate. BUILD constructs the prompt from the task definition, ensuring the same task always produces the same prompt. DISPATCH loads the agent adapter and invokes it. EXECUTE waits for the agent to exit, collecting only the exit code and what was written to disk. OUTCOME classifies what happened and routes to the appropriate handler, then loops back to SELECT.

The outcome table is where the discipline pays off. Success means exit code zero with valid output—close the task, log effort, continue. Failure means exit code one—log the reason, release the task, increment retry count. Timeout means the agent ran too long—release and mark deferred. Crash means the agent died without saying anything—release and create an alert task. Race lost means the SQLite claim returned no rows—exclude that candidate and retry. Queue empty triggers strand escalation: search other workspaces, do cleanup, propose alternatives. Six outcomes, six handlers. Every row exists because the absence of a handler caused a real bug.

Atomic claims on a shared SQLite queue are what make twenty concurrent workers possible without chaos. Each bead (task) is claimed via a transaction that guarantees exactly one worker wins. The loser doesn't fail—it simply moves to the next candidate. This treats race conditions as first-class outcomes rather than failures, preventing workers from retrying endlessly on tasks they'll never claim or crashing with cryptic SQLite errors. The queue is the coordination primitive; the state machine is the execution logic.

Agent-agnostic design means NEEDLE doesn't care whether the worker is Claude Code, OpenCode, Codex, or Aider. Each agent is a YAML adapter file—no code changes required. Drop in a better agent, remove a worse one, swap models for cost optimization—the state machine remains unchanged. The contract is: takes a prompt, produces an exit code. That's it. This modularity lets fleets optimize continuously without rebuilding the orchestration layer.

Running twenty headless workers on the same workspace is where the cattle model proves itself. These are stateless, replaceable processes identified by NATO-alphabet callsigns—alpha, bravo, charlie—not cherished names. When a worker fails, you don't debug that worker. You investigate the task it was working on, then dispatch another worker. The unit of analysis is the herd, not the cow. Fleet metrics—tasks completed per hour, cost per task, failure rate by category—are what matter. Individual session quality is irrelevant.

Strand escalation is what happens when the queue is empty. Rather than spinning uselessly, workers enter a fallback sequence: search other workspaces for claimable work, perform cleanup tasks, propose alternatives for blocked tasks, and only alert if all strands are exhausted. Queue empty is a signal, not idle time. It tells the orchestrator that this workspace is exhausted and it's time to look elsewhere—turning a non-event into actionable intelligence.

The Kubernetes-native deployment model means NEEDLE fleets scale horizontally with infrastructure. Each worker is a pod in a deployment; horizontal pod autoscaling adjusts worker count based on queue depth and throughput. The SQLite bead queue lives on a persistent volume claim, surviving pod restarts. The orchestrator, the workers, and the queue are all declarative Kuberentes resources—no pet servers, no hand-managed processes. The cattle model applies to infrastructure as well as agents.

Cost governance integrates via claude-governor, a Rust proxy that sits between workers and model providers. It caps spend, throttles concurrency, and gates against quota limits—enforcing policies at the request layer so workers don't need to know about budgets. The orchestrator asks for work; the proxy decides whether that work is affordable. This separation of concerns keeps the state machine focused on execution while the governor focuses on economics.

The combination of deterministic state machine, atomic queue coordination, agent-agnostic adapters, and explicit outcome handlers is what makes autonomous fleets runnable. Workers fail predictably. The state machine is the contract; agents are the implementation. You stop debugging individual workers and start debugging the outcome distribution—which outcome is firing more often than it should? That shift in perspective is what separates twenty unmanageable pet agents from twenty manageable cattle workers.