The Execution Layer: How JiuwenSwarm Keeps a Task Moving
For JiuwenSwarm, the central execution question is not how a model generates a plausible next sentence. It is how a model's proposed actions become a task that can continue across rounds, use tools, respond to new direction, and stop under explicit conditions. The Harness is the layer that answers that question. Understanding its control flow lets a reader locate responsibility when a run succeeds, stalls, changes direction, or produces an action that should have been blocked.
The repository describes this relationship as Agent = Model + Harness. The model supplies reasoning and action intent; the Harness supplies the task loop, tools, context, permissions, state, delegation, verification, and completion logic around it. This is an architectural distinction, not a slogan. A model may decide that it wants to edit a file, search the web, or ask a teammate for help. The Harness determines how that intention enters the runtime, which tool is exposed, what state is carried into the next round, and what event ends the run.
Two loops, two jobs
JiuwenSwarm's underlying Harness uses two nested forms of control. The inner loop is a ReAct loop: the agent reasons about the current situation, takes an action such as a tool call, observes the result, and reasons again. This loop is close to the familiar picture of an agent. It is where model output meets tools and observations.
The outer layer is the Task Loop. It turns an open-ended request into a sequence of task iterations. Each iteration can update the task plan, consume tool results, receive new guidance, and contribute evidence about whether the goal has been reached. The outer loop is what makes a long task different from a series of unrelated chat responses. It preserves the distinction between the current action and the larger question of whether the work should continue.
That separation also provides a useful failure model. If the model misunderstands a document, the problem may be inside the reasoning loop or its context. If the task never terminates, the problem may be in completion conditions or state transitions. If a dangerous command appears, the relevant question is not only what the model wanted, but whether the permission and safety layers intercepted the tool call before execution. The Harness gives these concerns different places to act instead of asking one prompt to solve all of them.
The runtime extends both loops through lifecycle Rails. A Rail is an extension that runs at a defined point in the process rather than a separate application bolted onto the side. Rails can act before or after an invocation, around a task iteration, before or after a model call, and before or after a tool call. That timing matters. A context rail can assemble information before the model reasons. A permission rail can inspect a tool call before it runs. A completion rail can evaluate the task after an iteration has produced a result.
This arrangement lets JiuwenSwarm add capabilities without turning the main loop into a single undifferentiated procedure. Planning, memory, Skills, permissions, context processing, and evolution can each participate at the point where their decision is meaningful. The mechanism is compositional, but it is not consequence-free: the more Rails influence a run, the more important their ordering, state, and failure behavior become.
From invocation to observation and state
A run begins when a caller invokes the agent with a user request and a session. The Harness initializes the workspace and runtime objects, loads session state, and performs the pre-invocation lifecycle work. In a short request, the system may use the inner ReAct path directly. In a long-running task, the request enters the outer controller, which submits a round for execution.
Inside that round, the model receives the effective prompt and available tools. It may answer directly, or it may call a tool. The tool result becomes an observation for the ReAct loop. After the iteration finishes, the outer layer runs its post-iteration work and asks whether another round is needed. This gives the task a rhythm:
- establish the current state and instructions;
- reason and act within the current round;
- observe tool or model results;
- update task state and completion signals;
- continue, pause for input, or stop.
The important point is that the model does not own this entire rhythm. The session stores runtime facts such as the current iteration, task plan, stop-condition state, pending follow-ups, and plan-mode state. The saved state does not make every model conclusion true, but it gives later rounds and external runtimes something more durable than an unstructured conversation transcript.
The nesting also clarifies where a decision can be changed. A tool result belongs first to the inner loop: it becomes an observation that may alter the model's next action. The outer loop sees the completed iteration and can decide that the task needs another round, a follow-up, a change of direction, or a stop. A Rail around the model call can shape the context presented for that action; a Rail around the tool call can check the action before it crosses the execution boundary; a Rail after the iteration can record progress or test completion. These are different intervention points. Treating them as interchangeable would make it difficult to tell whether a failure came from missing context, an unauthorized action, a malformed observation, or a bad completion judgment.
This design is particularly important for tasks that mix different kinds of work. A research run may need several rounds of retrieval and synthesis, while a file operation may need only one tool call but a stricter permission decision. The same outer machinery can represent both, yet the relevant Rails, tools, and stop conditions need not be identical. The Harness therefore provides a common control surface without claiming that every task should follow the same procedure.
The diagram shows control ownership rather than an implementation inventory. The ReAct loop handles the immediate interaction between reasoning and action. The Task Loop decides whether another iteration is warranted. Session state carries the information needed to resume or inspect progress. The tool boundary is where other governance mechanisms can intervene before a proposed action becomes an external effect.
Stopping is part of the mechanism
An agent that can keep acting is not necessarily an agent that can finish. JiuwenSwarm's Task Completion Rail supports several stop evaluators, including maximum rounds, timeouts, token budgets, completion promises, and custom predicates. The documented semantics are OR-based: the task stops when any configured condition is met. That is useful because a task may finish normally, reach a resource limit, or need to stop after an external predicate becomes true.
These conditions serve different purposes. A completion promise expresses what a successful result must contain. A maximum-round or timeout limit bounds an otherwise open-ended run. A token budget limits resource use. A custom predicate can represent an application-specific definition of completion. Treating them as separate evaluators makes the stopping decision inspectable, but it also means that a task can stop for a reason other than success. “The loop ended” and “the user goal was fully achieved” are not identical statements.
The outer loop also supports runtime interaction. A follow-up queues a new user request for a later round. Steer injects guidance into a running task, such as prioritizing factual accuracy or adding a risk assessment. Abort asks the controller to cancel the outer loop and try to interrupt the inner ReAct loop. These actions change the trajectory without pretending that a tool call already in progress has been retroactively erased.
That boundary is important in practical use. Suppose a user realizes that a task is operating under the wrong assumption. Steering can change what the agent should prioritize next; it does not make an earlier observation disappear. If a user aborts after a tool has completed, the abort can stop future iterations but cannot undo an external side effect by itself. The system's state and the outside world must therefore be considered separately.
The same principle applies to recovery. Persisted task state can make a long run resumable and can let a runtime inspect pending work. It cannot guarantee that every external service, file, or model will present the same state when the run continues. A controller can preserve an iteration count; it cannot reconstruct an unavailable network response. Reliable execution requires both state persistence and explicit handling of the dependencies that state refers to.
Staging autonomy before accepting change
JiuwenSwarm's Harness also separates planning, mutation, and verification. In normal mode, the agent can perform regular task execution subject to its tools and permissions. Plan mode is read-only for the real workspace: it filters tools and blocks shell or Git writes, while file writes are limited to the plan file. This gives the agent a place to explore and formulate a solution without silently changing the target workspace.
Worktree support adds a different boundary. When an agent enters an isolated Git worktree, it can make experimental changes without immediately polluting the main workspace. That is useful for code modification, refactoring, parallel experimentation, and any action that benefits from a rollback boundary. Isolation does not make a change correct; it makes the consequences easier to inspect and discard.
Verification is the third stage. The Harness can require a verification agent after non-trivial implementation. The verification rail restricts that agent to reading changes, searching, running checks, and reporting conclusions rather than editing the project. This separation protects the independence of the check: the verifier is less able to make a failing result disappear by changing the subject under inspection.
Together, plan mode, worktrees, and verification create a staged form of autonomy:
- Plan determines what should happen without changing the real workspace.
- Execute makes changes inside the permitted boundary.
- Verify examines the result and reports what the checks establish.
The stages are not a universal safety guarantee. A verifier can only test what its checks cover. A worktree protects a code workspace but does not prevent an external service call. A plan can be incomplete or based on a false assumption. The value lies in separating decisions that are often conflated and making the points of failure easier to see.
What the Harness can and cannot own
The Harness is powerful precisely because it owns more than a prompt, but its boundaries should remain explicit. It can organize task rounds, expose tools, preserve selected state, accept intervention, and apply completion or verification gates. It cannot supply missing domain facts merely because a task loop exists. It cannot make an external dependency reliable by saving a plan. It cannot turn a passed check into proof of universal correctness.
The architecture also depends on the underlying openJiuwen SDK. The JiuwenSwarm repository documents and integrates the Harness, but the SDK supplies part of the implementation. That means the repository is strong evidence for the intended control model and its integration points, while claims about every internal SDK behavior require the appropriate dependency version and deployment context.
The practical lesson is straightforward: when a JiuwenSwarm run behaves unexpectedly, inspect the layer that owns the transition. Was the goal misread by the model? Did the Task Loop lack a suitable completion condition? Did a Rail alter the context or intercept a tool? Did a follow-up arrive after an irreversible action? Did the verifier check the relevant property? This ownership-based diagnosis is more useful than describing the whole system as either “the model” or “the agent.”
A governed single-agent loop can handle substantial work. The next boundary appears when one loop must cover many specialties, independent perspectives, or parallel phases. At that point, the question is no longer only how one task iterates, but how several agents divide responsibility and hand results back without losing control.