The Harness as a Control Plane
In Ruflo, the control plane is the part that decides what should happen before a model call is counted as work. This chapter follows a task through hooks, routing, agent state, queues, messages, topology, consensus, and health monitoring. The practical payoff is a way to distinguish scheduling from execution: Ruflo can organize a job, but organization becomes useful only when the assigned work produces an observable result and can recover from failure.
A task becomes state before it becomes output
A request enters Ruflo as a task description, not as a fully formed execution plan. Lifecycle hooks can inspect the event, identify the kind of work, estimate complexity, suggest agents, and surface risks. A router can use task language, file context, semantic patterns, or learned outcomes to recommend a worker or a small group. Those signals answer a narrow question: who appears suitable, and what kind of handling may be proportionate?
The answer is not yet an assignment. The coordinator owns the transition from recommendation to task state. It keeps records for agents and tasks, including statuses such as idle, busy, queued, completed, failed, or timed out. An agent record carries capabilities, health, workload, and recent metrics. A task record carries type, priority, dependencies, retries, timestamps, and eventual output. These fields are not clerical decoration. They are the information needed to make a later decision different from the previous one.
Consider a security review of a login flow. The router may identify security and review responsibilities. The coordinator can then choose an available specialist, put the task in a queue if the relevant pool is busy, and send an assignment message with an acknowledgement requirement. The worker’s status changes to busy, and the task moves from created to assigned or running. When a result arrives, the coordinator can mark the task completed and return the worker to idle. If the message fails, the task does not have to vanish into an ambiguous “AI error”; it can be retried, re-queued, cancelled, or reported as failed.
This is the first important control-plane distinction. Routing is a decision about suitability. Assignment is a state transition that creates responsibility. Execution is the operation that performs the work. Reporting is the evidence that closes—or fails to close—the loop. Ruflo’s design gives each transition a place to live, which makes a long-running process more inspectable than a conversation that contains only a final sentence.
The coordinator’s agent selection is also more grounded than a fixed role list. The unified implementation scores available agents using type and capability fit, current workload, health, historical success, and execution-time metrics. A worker with the right label but poor health may lose to a less obvious worker that is available and reliable. Conversely, a high historical success rate should not erase a current busy state or a missing capability. The point is not that the score is perfect; it is that the choice has explicit inputs that can be measured and challenged.
The same state makes backpressure possible. If no suitable worker is free, a task can remain queued instead of creating unlimited work. If a worker fails before exhausting its retry allowance, the coordinator can release the assignment and try again. If heartbeats stop, the coordinator marks the agent unhealthy, reduces its health, and can reassign its current task when automatic recovery is enabled. These mechanisms do not repair a bad result, but they prevent an unavailable worker from being treated as an invisible success.
The control plane is a set of cooperating owners
Ruflo’s architecture is easier to understand if each component owns a different kind of state.
The hook layer owns lifecycle observations and recommendations. It can run before or after an edit, command, or task; record outcomes; and feed information into routing or learning. It is close to the host tool, so it can see events that a remote scheduler may never see. But the marketplace hook bridge is intentionally best-effort and fail-open. Its job is to preserve host compatibility and telemetry, not to become the sole authority that blocks a command.
The router owns selection signals. It may prefer a deterministic handler for a mechanical transformation, a cheaper model for a simple request, or a more capable worker for a complex one. It can combine static patterns with learned outcomes. A route is therefore a recommendation with a reason and confidence, not a guarantee that the chosen agent will succeed.
The agent registry and pools own identity and availability. Pools group workers by type or domain and expose acquisition and release operations. The named domains in the unified coordinator—such as security, core, integration, and support—are a way to organize capabilities and queues. They should not be mistaken for proof that a corresponding number of independent model processes is alive. A registry can contain an idle record even when no provider is configured to execute its next task.
The task and message state owns delivery and progress. The message bus sends assignment, completion, failure, heartbeat, status, and consensus messages. Time-to-live, acknowledgement, retry, and queue settings make messages operational objects rather than informal notes. A message can be delivered while the task still fails; a task can be queued while the worker pool remains healthy; and a heartbeat can keep an agent alive without saying anything about the quality of its output.
The health and metrics layer owns observation of the control plane itself. It tracks active agents, completed and failed tasks, coordination latency, queue depth, message rates, and agent utilization. The Queen coordinator can turn these values into domain health, bottleneck alerts, and recommendations such as scaling a busy pool or investigating error agents. This is useful operational feedback, but health is not correctness. A system can be fast, responsive, and consistently wrong.
The executor is a separate owner. It is where a task is eventually translated into a provider call, a tool action, or another concrete operation. Ruflo’s swarm coordinator can assign a task and wait for completion, but the provider-backed execution wire has its own credentials, model selection, usage, timeout, and error behavior. Keeping this boundary visible prevents an especially common misunderstanding: a successful call to “spawn” or “assign” does not mean that a model has reasoned about the task.
The arrows describe responsibility, not a promise of a single implementation path. Hooks can be absent or unable to reach the CLI. A task can be queued rather than executed. A provider can reject a call. A result can be recorded without being accepted. The value of the diagram is precisely that it leaves room for those states.
Topology changes the shape of coordination
A topology is the pattern by which agents and coordinators communicate. Ruflo’s swarm types include mesh, hierarchical, centralized, and hybrid arrangements. These labels matter because communication shape changes who owns decisions, how many messages are needed, and what happens when a coordinator or link fails.
In a hierarchical arrangement, a higher-level coordinator can decompose a goal, route subtasks to domains, collect results, and integrate them. This is a natural fit for work such as architecture, implementation, testing, and review, where someone must reconcile outputs. Its strength is clarity: there is a recognizable place to resolve conflict. Its weakness is concentration. A coordinator can become a bottleneck, and a mistake in decomposition can be propagated to every worker.
In a mesh, agents can communicate as peers. That can reduce dependence on one central path and suit collaboration where workers already hold complementary context. The cost is more difficult coordination: peers need a way to find one another, avoid duplicate work, agree on shared state, and decide what happens when messages arrive late or not at all. Mesh connectivity does not automatically create consensus, and it does not automatically create a network connection between machines.
A centralized arrangement makes the decision path even more explicit. It can be appropriate when one authority must control access, ordering, or resource use, but it offers a narrow failure surface around that authority. A hybrid arrangement can keep strategic decisions centralized while allowing selected peer or domain-level communication. The appropriate choice depends on the task’s dependency graph and failure tolerance, not on the attractiveness of the topology name.
Consensus is another layer, and it answers a different question from topology. Topology describes who can communicate with whom. Consensus describes how participants accept or reject a proposal. Ruflo exposes Raft, Byzantine/PBFT-style, and Gossip implementations behind a common engine; Paxos currently falls back to Raft in that factory. A majority-based decision, a Byzantine fault-tolerant quorum, and an eventually propagated gossip state make different assumptions about failure and timing.
Transport is the layer that makes a protocol’s messages travel. Ruflo’s newer consensus code separates protocol events from an injected ConsensusTransport. The default LocalTransport registers nodes inside one process and delivers messages through an in-process registry. It can add Ed25519 signatures and monotonic sequence checks, and the test suite exercises tampering, missing signatures, unreachable peers, timeouts, and replay ordering. A FederationTransport adapter exists for a federation wire, but it must be supplied and configured. Therefore a protocol module plus a local test is evidence of a mechanism, not evidence that every user’s hive-mind is a cross-host cluster.
This distinction becomes concrete in failure injection. Tests can silence selected local nodes and check whether a Raft candidate still reaches a majority or whether a Byzantine proposal reaches the expected quorum. That is valuable because it tests the arithmetic and message handling under controlled faults. It does not test the quality of the proposal, the behavior of a real network, credential rotation, provider failures, or the operational work required to connect two installations. The test proves a bounded property of a path; it does not promote the whole system to a distributed guarantee.
Recovery is useful only if it ends in a check
Ruflo’s recovery behavior is designed around keeping control state coherent. Heartbeats reveal that an agent is still responsive. Health checks update active counts and topology state. Queues preserve tasks for which no worker is currently available. Retries give a failed task another attempt within a limit. Reassignment prevents one dead worker from owning work forever. Metrics reveal whether these mechanisms are relieving pressure or merely creating a loop.
Each mechanism also has a failure mode. A heartbeat can be alive while a worker is producing low-quality output. Retrying an invalid prompt can repeat the same mistake. Reassigning work can duplicate side effects if the first worker actually completed them before its status was lost. A consensus result can show agreement among agents that all saw the same incomplete evidence. Ruflo’s control plane can expose these conditions, but it cannot infer acceptance from status alone.
That is why a robust task contract needs more than an agent type. It should state what input the worker receives, what output it must return, what evidence closes the task, how many retries are allowed, and what happens at timeout. For a login review, “security agent completed” is weaker than “findings identify the affected flow, proposed changes are reviewable, and the relevant tests pass.” The control plane can carry that contract; the evaluator or human owner must decide whether it was met.
The control plane therefore earns its name not by making the model autonomous, but by keeping decisions and transitions legible. It says who was selected, what state the task occupies, which messages moved it, which failures triggered recovery, and whether the coordination layer itself is healthy. The next question is the one the scheduler cannot answer on its own: how does Ruflo turn an assignment into a real provider-backed operation, and how do workflows preserve that operation’s progress without pretending that unsupported steps ran?