Agent Loops: Multi-Stage Orchestration

Agent Loops are the core engine of Zenborg. A loop is an automated, multi-stage workflow where several AI agents plan, implement, critique, and correct software tasks together.

The 7-Stage Pipeline

When you click "Start Orchestration Loop", Zenborg runs a structured series of stages:

[ plan_draft ]
      │
      ├───────────────────────┐
      ▼                       ▼
[ plan_review_1 ]       [ plan_review_2 ]
      │                       │
      └───────────┬───────────┘
                  ▼
          [ plan_synthesis ]
                  │
                  ▼
             [ execution ]
                  │
                  ▼
              [ review ]
                  │
                  ▼ (optional)
           [ cross_review ]
                  │
                  ▼
        [ fix_1 ... fix_N ]

plan_draft: The Manager Agent reads the task goal and repository context, then drafts an initial implementation plan.
plan_review_1 & plan_review_2: Two concurrent Worker Agent sessions review the draft plan in parallel, analyzing architectural risks, edge cases, and missing steps.
plan_synthesis: The Manager Agent reviews the draft and both worker critiques, resolving contradictions into a finalized, approved specification.
execution: The Worker Agent executes the synthesized plan inside an isolated Git worktree, modifying files and running local test suites.
review: The Manager Agent inspects the resulting Git diff and test output to confirm all requirements are met.
cross_review: If "Cross-Agent Code Review (Independent Second Opinion)" is checked, a second independent agent audits the diff after the Manager approves to catch blind spots.
fix rounds: If any review identifies defects, the Worker Agent implements fixes in the worktree. Zenborg repeats the review-fix cycle up to the configured limit (Max Correction Rounds, default 4, range 0–10).

Understanding Agent Roles in Zenborg

Zenborg organizes multi-agent collaboration with distinct, complementary responsibilities:

1. Manager Agent (Planning, Synthesis, and Code Review)

UI Field: Manager Agent (#planner-agent-input)
Responsibilities:
- Analyzes the codebase and drafts the architectural plan (plan_draft).
- Synthesizes the two worker plan reviews into the final specification (plan_synthesis).
- Conducts the primary code review (review) over the Git diff and test results after execution.
Recommended Tools: Choose a reasoning-focused agent such as Claude Code or Google Antigravity.

2. Worker Agent (Execution and Plan Reviews)

UI Field: Worker Agent (#worker-agent-input)
Responsibilities:
- Runs the two concurrent plan review sessions (plan_review_1 and plan_review_2) to pressure-test the manager’s proposal.
- Implements the code changes and executes local tests inside the isolated Git worktree (execution).
- Implements all necessary code corrections during fix rounds (fix_1 … fix_N).
Recommended Tools: Use a fast CLI agent (like Gemini CLI or Claude Code) or a zero-token Browser Worker (such as Gemini or ChatGPT running in the automated browser profile).

3. Smart Worker (Optional Automatic Fallback)

UI Field: Smart worker (optional) (#smart-worker-agent-input), default: None
Responsibilities:
- Acts as an automatic safety net when the primary Worker Agent encounters obstacles.
- Takes over execution if the Worker fails or gets rejected $N$ consecutive times (default 2, configured via #smart-worker-after-failures-input).
- Automatically takes over if a Browser Worker encounters a CAPTCHA challenge, login session timeout, or provider API outage.
- Once the current stage is successfully completed, Zenborg automatically returns execution back to the primary Worker Agent for subsequent tasks.
Recommended Tools: Another CLI agent installed on your machine.

4. Cross-Agent Code Reviewer (Optional Independent Audit)

UI Field: Cross-Agent Code Review (Independent Second Opinion) (#cross-review-checkbox)
Responsibilities:
- Provides a second, completely independent evaluation of the Git diff after the Manager Agent approves the code.
- Flags security vulnerabilities, concurrency flaws, or unhandled edge cases that might escape a single reviewer.
Recommended Tools: A different connected CLI assistant.

Git Worktree Safety

Zenborg never edits your primary project directory or checked-out branch directly.

When a loop begins:

Zenborg creates an isolated temporary Git worktree for the loop.
A dedicated branch named maiox/loop-<id> is created from your current commit.
All file edits, builds, and test runs execute exclusively inside this isolated worktree.
If a loop fails or an agent produces bad code, your original workspace remains untouched.
Once a loop succeeds, you can review the clean diff and merge the branch at your convenience.

To prevent agents from modifying system files outside the repository, path access is strictly bounded by default unless you explicitly check "Allow outside project folder".

Agent Power and Machine Concurrency

Zenborg includes three pre-configured machine profiles in the Agent Power settings:

Profile	Max Concurrent Loops	Max Concurrent Tasks	Max Browser Tabs	CPU Load Factor
Low	`1` loop	`1` task	`1` tab	`0.6`
Medium (Default)	`2` loops	`2` tasks	`3` tabs	`0.8`
High	the larger of 2 or cores ÷ 4 loops	`3` tasks	`6` tabs	`1.0`

Low: Keeps your computer responsive while you do heavy local development or video calls.
Medium: Balanced background processing for modern quad-core or 8-core workstations.
High: Maximizes parallel execution on multi-core systems (such as Apple Silicon Pro/Max/Ultra or high-core desktop workstations).

Memory Guards and Safety Limits

Autonomous coding agents can occasionally run infinite loops or memory-heavy test suites. Zenborg enforces strict runtime limits:

Stage Memory Limit: MAX_STAGE_RSS_MB = 6144 (6 GB). If an agent and its subprocesses exceed 6 GB of resident memory, Zenborg stops the stage to prevent machine freezes.
Agent Node Heap: AGENT_NODE_HEAP_MB = 3072 (3 GB) max old space size allocated to Node.js agent runners.
System Memory Safeguard: MIN_SYSTEM_FREE_PERCENT = 8. If overall free system memory drops below 8% for two consecutive checks, stages pause.
Stage Execution Budget: Each individual agent stage has a hard timeout of 3 hours (MAIOX_STAGE_BUDGET_MS).
Inactivity Watchdog: If an agent starts working but produces no terminal or log output for 25 minutes (MAIOX_STAGE_INACTIVITY_MS), Zenborg marks the stage as stalled (STAGE_INACTIVE).
Stage Quiet Warning: If an agent produces no output for 5 minutes, the interface status turns amber and indicates "quiet · last activity ... ago".

Error Handling, Fallbacks, and Smart Worker

API providers can experience outages or rate limits. Zenborg monitors agent outputs for specific error signatures:

HTTP 400 Bad Request
HTTP 429 Rate Limits / Quotas
HTTP 5xx Server Errors
Provider rejection messages ("overloaded", "Bad Request")

Fallback Behavior

Smart Worker: If the Worker Agent fails with consecutive rejections (default 2 failures in a row), or if a browser worker hits a CAPTCHA or provider outage, Zenborg automatically switches the task to the configured Smart Worker. Once that task succeeds, Zenborg hands subsequent tasks back to the primary Worker.
Custom Fallback Chains: You can check "Custom fallback chain for this loop" to define loop-specific agent priorities (for example: try your preferred agent first, fall back to another CLI assistant).

Resuming Failed Loops

If a loop stops due to a network interruption or transient provider failure, you do not have to restart from scratch.

The button labeled "Resume Loop" becomes visible in the loop detail panel when all of the following conditions are met:

The loop status is currently failed or cancelled.
The plan_draft stage completed successfully and produced non-empty output.
The failure occurred during plan reviews (plan_review_1, plan_review_2) or during execution (with plan_synthesis already completed).

Clicking "Resume Loop" re-uses the already completed stages and resumes the workflow from the point of failure.

Worked Example: “Add a dark mode toggle”

Here is how Zenborg executes a typical feature request:

Goal Input: In the Task Scope input field, you enter:

"Add an accessible dark mode toggle button to the top navbar with persistent localStorage state."
Plan Draft: The Manager Agent (such as Claude Code or Antigravity) examines your navbar component, your CSS custom properties, and existing test setup. It drafts a plan specifying HTML attributes, CSS variables, and unit test files.
Plan Reviews: Two Worker Agent sessions review the plan in parallel. One review points out that system preferences (prefers-color-scheme) should be respected on first visit, while the second verifies accessibility attributes (aria-pressed).
Plan Synthesis: The Manager Agent incorporates the prefers-color-scheme logic and accessibility feedback into the final plan.
Execution: The Worker Agent checks out the isolated Git worktree, creates the toggle element, writes CSS rules, updates local storage helpers, and runs the test suite.
Code Review: The Manager Agent inspects the diff. If configured, a Cross-Reviewer conducts an independent second audit. They approve the implementation with zero critical findings.
Completion: Zenborg marks the loop finished. You open the worktree diff, review the commit, and merge it into your main branch.

Honest Time and Practical Benefits

Using Agent Loops provides tangible development benefits without exaggerated claims:

Unattended Execution: You define the goal and let Zenborg run the plan, implementation, and review in the background while you focus on other work.
Fewer Self-Correction Loops: When an agent checks its own code, it frequently repeats the same mistake. Using a different model for code review spots errors on the first pass.
Protected Master Branch: Because all work executes in disposable Git worktrees, you never have to clean up partially modified workspaces or broken builds.