Integration Guard: Safely Merging Parallel Concurrent AI Agents from Git Worktrees into Main

The Integration Guard subsystem, implemented in the Vibe Kanban Alternative project, coordinates parallel AI agents working in separate Git worktrees and safely integrates their changes into a shared target branch. It uses soft reservations, a database-backed lease, and a three-way merge based on the original branch point to avoid unnecessary rebases and prevent silent overwrites or semantic conflicts. The system separates observation, reservation, and integration to manage concurrent agent workflows effectively.

Modern coding-agent workflows often run several agents in parallel. Each agent works in its own Git worktree and branch, while all changes eventually need to land on a shared target branch such as main. This model provides isolation and speed, but introduces a difficult question: How can multiple agents work concurrently without losing commits, overwriting changes, or silently creating a semantically broken integration? This article presents the design of the Integration Guard, the subsystem implemented in Vibe Kanban Alternative https://github.com/flashlan/vibe-kanban-alternative , an independent, self-hosted fork of Vibe Kanban, to coordinate parallel agents and safely integrate their work. A typical setup looks like this: Each agent has its own isolated filesystem and branch. This prevents agents from directly modifying each other’s working directories. However, the target branch can change while an agent is still working: Agent A starts at main = H0 Agent B completes and updates main = H1 Agent A finishes using its original branch Agent A now needs to integrate into H1 A naïve implementation usually chooses one of these approaches: Each approach has weaknesses. A rebase is not always necessary. If Agent A changes auth.rs and Agent B changes billing.rs, their work can usually be integrated safely even though main advanced. A temporary lock such as /tmp/vk-merge-lock does not coordinate separate backend processes reliably. A blind reference update can silently overwrite another agent’s commit. And Git does not detect every semantic conflict. Two agents can modify different lines in the same function and still produce incompatible behavior. The system separates three responsibilities: The observer exposes which agents are currently active, what they intend to change, and which workspaces they belong to. A declaration can include: The UI can then show information such as: Agent A — implementing merge changes in crates/git/src/lib.rs Agent B — updating complete workspace card in crates/mcp/src/... This information is available through the backend and MCP, rather than relying on Mem0 or an agent’s conversation history. 2. Soft reservations Agent declarations are intentionally soft reservations. If Agent A declares auth.rs and Agent B declares auth.rs, Agent B is warned, but is not automatically blocked. This is important because the developer may know that the two agents are working on independent sections of the same file. The system therefore separates: Agents can continue working in parallel. The Integration Guard performs the final validation before writing to the shared target branch. The Integration Guard is responsible for the short critical section where a branch is validated and integrated. It uses a database-backed lease scoped to the repository. This serializes the validation and Git write across backend processes. The lease prevents two independent backend requests from simultaneously validating the same target and then racing to update it. The central idea is to use the task’s original branch point as the common ancestor. Let: The Integration Guard computes: task diff = diff H0, Ha target diff = diff H0, Ht The complete flow is: The important detail is that an advanced target branch does not automatically force a rebase. Suppose: H0: initial project state Agent A: changes auth.rs Agent B: changes billing.rs Ht: includes Agent B's changes Ha: includes Agent A's changes The three-way merge can combine both changes: H0 ├── target diff: billing.rs └── task diff: auth.rs Result: ├── billing.rs └── auth.rs Agent A does not need to rewrite its branch history merely because Agent B finished first. If both agents modify the same lines or incompatible hunks, Git reports a conflict. The Integration Guard then: The operator can then decide whether to resolve the conflict manually, rebase intentionally, or change the task scope. Git detects textual overlap. It does not understand contracts, APIs, or behavior. For example: Agent A changes: UserService::create user Agent B changes: API code that depends on the return value of create user These changes may touch different files and different lines, yet still be incompatible. The current semantic detector uses declared dependencies: This is intentionally conservative. It is not a full AST or behavioral analysis system, but it catches a class of conflicts that file-level comparison cannot. A semantic conflict is reported before Git writes to the target branch. Mem0 is useful for durable project knowledge: “The merge API now requires a validation step.” “This module owns the authentication contract.” But it is not suitable for real-time coordination because it can be: The system therefore uses: Mem0 stores semantic memory. The database stores current state. Previously, a pipeline could instruct an agent to manually: That approach put repository coordination logic inside an agent prompt. The new pipeline contract is simpler: Agent completes implementation and verification ↓ Agent calls complete workspace card ↓ Backend invokes Integration Guard ↓ Guard validates and integrates safely ↓ Card moves to Done only after success The agent no longer needs to know how the target branch is updated. The pipeline stage is now named: Integration Guard → Done The agent is explicitly instructed not to manually rebase, update refs, or use temporary locks. The technical result may still be a single integration commit, but the responsibility belongs to the backend integration layer rather than the agent. The database lease protects the critical integration sequence: This prevents the classic race: Request A reads main = H1 Request B reads main = H1 Request A writes main = H2 Request B writes main = H3 Without serialization, the second operation may be based on stale state. The Integration Guard follows a strict rule: A card is marked Done only after the target branch has been successfully updated. integration in progress . Done .This makes failure visible instead of silently converting an incomplete integration into a completed card. The implementation includes automated Git safety tests for: The repository also contains a manual acceptance runbook for testing with two real agents: This manual test is important because it crosses real process boundaries: The system is intentionally conservative and local-first. The semantic detector currently relies on declared files, symbols, and dependencies. It does not replace: The UI currently presents active work through a polling activity panel. Future improvements could include: Parallel coding agents are valuable only if their work can be integrated safely. The Integration Guard addresses this by combining: The key design decision is simple: An advanced target branch is not automatically a reason to rebase. Compare the task against its original branch point, let Git perform a three-way integration, and require review only when there is a real textual or semantic conflict. This allows multiple agents to work independently while keeping the shared target branch protected, predictable, and auditable. crates/server/src/routes/workspaces/git.rs crates/git/src/lib.rs crates/db/src/models/agent work.rs crates/db/src/models/integration guard.rs The complete implementation is available on GitHub https://github.com/flashlan/vibe-kanban-alternative . Feedback and technical discussion are welcome in the repository issues.