{"slug": "integration-guard-safely-merging-parallel-concurrent-ai-agents-from-git-into", "title": "Integration Guard: Safely Merging Parallel Concurrent AI Agents from Git Worktrees into Main", "summary": "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.", "body_md": "Modern coding-agent workflows often run several agents in parallel. Each\n\nagent works in its own Git worktree and branch, while all changes eventually\n\nneed to land on a shared target branch such as main.\n\nThis model provides isolation and speed, but introduces a difficult question:\n\nHow can multiple agents work concurrently without losing commits,\n\noverwriting changes, or silently creating a semantically broken\n\nintegration?\n\nThis 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.\n\nA typical setup looks like this:\n\nEach agent has its own isolated filesystem and branch. This prevents agents\n\nfrom directly modifying each other’s working directories.\n\nHowever, the target branch can change while an agent is still working:\n\nAgent A starts at main = H0\n\nAgent B completes and updates main = H1\n\nAgent A finishes using its original branch\n\nAgent A now needs to integrate into H1\n\nA naïve implementation usually chooses one of these approaches:\n\nEach approach has weaknesses.\n\nA rebase is not always necessary. If Agent A changes auth.rs and Agent B\n\nchanges billing.rs, their work can usually be integrated safely even though\n\nmain advanced.\n\nA temporary lock such as /tmp/vk-merge-lock does not coordinate separate\n\nbackend processes reliably.\n\nA blind reference update can silently overwrite another agent’s commit.\n\nAnd Git does not detect every semantic conflict. Two agents can modify\n\ndifferent lines in the same function and still produce incompatible behavior.\n\nThe system separates three responsibilities:\n\nThe observer exposes which agents are currently active, what they intend to\n\nchange, and which workspaces they belong to.\n\nA declaration can include:\n\nThe UI can then show information such as:\n\nAgent A — implementing merge_changes in crates/git/src/lib.rs\n\nAgent B — updating complete_workspace_card in crates/mcp/src/...\n\nThis information is available through the backend and MCP, rather than\n\nrelying on Mem0 or an agent’s conversation history.\n\n### 2. Soft reservations\n\nAgent declarations are intentionally soft reservations.\n\nIf Agent A declares auth.rs and Agent B declares auth.rs, Agent B is warned,\n\nbut is not automatically blocked.\n\nThis is important because the developer may know that the two agents are\n\nworking on independent sections of the same file.\n\nThe system therefore separates:\n\nAgents can continue working in parallel. The Integration Guard performs the\n\nfinal validation before writing to the shared target branch.\n\nThe Integration Guard is responsible for the short critical section where a\n\nbranch is validated and integrated.\n\nIt uses a database-backed lease scoped to the repository. This serializes the\n\nvalidation and Git write across backend processes.\n\nThe lease prevents two independent backend requests from simultaneously\n\nvalidating the same target and then racing to update it.\n\nThe central idea is to use the task’s original branch point as the common\n\nancestor.\n\nLet:\n\nThe Integration Guard computes:\n\ntask_diff = diff(H0, Ha)\n\ntarget_diff = diff(H0, Ht)\n\nThe complete flow is:\n\nThe important detail is that an advanced target branch does not automatically\n\nforce a rebase.\n\nSuppose:\n\nH0: initial project state\n\nAgent A: changes auth.rs\n\nAgent B: changes billing.rs\n\nHt: includes Agent B's changes\n\nHa: includes Agent A's changes\n\nThe three-way merge can combine both changes:\n\nH0\n\n├── target_diff: billing.rs\n\n└── task_diff: auth.rs\n\nResult:\n\n├── billing.rs\n\n└── auth.rs\n\nAgent A does not need to rewrite its branch history merely because Agent B\n\nfinished first.\n\nIf both agents modify the same lines or incompatible hunks, Git reports a\n\nconflict.\n\nThe Integration Guard then:\n\nThe operator can then decide whether to resolve the conflict manually, rebase\n\nintentionally, or change the task scope.\n\nGit detects textual overlap. It does not understand contracts, APIs, or\n\nbehavior.\n\nFor example:\n\nAgent A changes:\n\nUserService::create_user()\n\nAgent B changes:\n\nAPI code that depends on the return value of create_user()\n\nThese changes may touch different files and different lines, yet still be\n\nincompatible.\n\nThe current semantic detector uses declared dependencies:\n\nThis is intentionally conservative. It is not a full AST or behavioral\n\nanalysis system, but it catches a class of conflicts that file-level\n\ncomparison cannot.\n\nA semantic conflict is reported before Git writes to the target branch.\n\nMem0 is useful for durable project knowledge:\n\n“The merge API now requires a validation step.”\n\n“This module owns the authentication contract.”\n\nBut it is not suitable for real-time coordination because it can be:\n\nThe system therefore uses:\n\nMem0 stores semantic memory. The database stores current state.\n\nPreviously, a pipeline could instruct an agent to manually:\n\nThat approach put repository coordination logic inside an agent prompt.\n\nThe new pipeline contract is simpler:\n\nAgent completes implementation and verification\n\n↓\n\nAgent calls complete_workspace_card\n\n↓\n\nBackend invokes Integration Guard\n\n↓\n\nGuard validates and integrates safely\n\n↓\n\nCard moves to Done only after success\n\nThe agent no longer needs to know how the target branch is updated.\n\nThe pipeline stage is now named:\n\nIntegration Guard → Done\n\nThe agent is explicitly instructed not to manually rebase, update refs, or\n\nuse temporary locks.\n\nThe technical result may still be a single integration commit, but the\n\nresponsibility belongs to the backend integration layer rather than the\n\nagent.\n\nThe database lease protects the critical integration sequence:\n\nThis prevents the classic race:\n\nRequest A reads main = H1\n\nRequest B reads main = H1\n\nRequest A writes main = H2\n\nRequest B writes main = H3\n\nWithout serialization, the second operation may be based on stale state.\n\nThe Integration Guard follows a strict rule:\n\nA card is marked Done only after the target branch has been successfully updated.\n\n`integration_in_progress`\n\n.`Done`\n\n.This makes failure visible instead of silently converting an incomplete\n\nintegration into a completed card.\n\nThe implementation includes automated Git safety tests for:\n\nThe repository also contains a manual acceptance runbook for testing with two\n\nreal agents:\n\nThis manual test is important because it crosses real process boundaries:\n\nThe system is intentionally conservative and local-first.\n\nThe semantic detector currently relies on declared files, symbols, and\n\ndependencies. It does not replace:\n\nThe UI currently presents active work through a polling activity panel.\n\nFuture improvements could include:\n\nParallel coding agents are valuable only if their work can be integrated\n\nsafely.\n\nThe Integration Guard addresses this by combining:\n\nThe key design decision is simple:\n\nAn 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.\n\nThis allows multiple agents to work independently while keeping the shared\n\ntarget branch protected, predictable, and auditable.\n\n`crates/server/src/routes/workspaces/git.rs`\n\n`crates/git/src/lib.rs`\n\n`crates/db/src/models/agent_work.rs`\n\n`crates/db/src/models/integration_guard.rs`\n\nThe complete implementation is available on [GitHub](https://github.com/flashlan/vibe-kanban-alternative).\n\nFeedback and technical discussion are welcome in the repository issues.", "url": "https://wpnews.pro/news/integration-guard-safely-merging-parallel-concurrent-ai-agents-from-git-into", "canonical_source": "https://dev.to/evertonkozloski/integration-guard-safely-merging-parallel-concurrent-ai-agents-from-git-worktrees-into-main-4l7m", "published_at": "2026-08-26 15:01:41+00:00", "updated_at": "2026-08-26 15:14:49.033196+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["Vibe Kanban Alternative", "Integration Guard", "Git"], "alternates": {"html": "https://wpnews.pro/news/integration-guard-safely-merging-parallel-concurrent-ai-agents-from-git-into", "markdown": "https://wpnews.pro/news/integration-guard-safely-merging-parallel-concurrent-ai-agents-from-git-into.md", "text": "https://wpnews.pro/news/integration-guard-safely-merging-parallel-concurrent-ai-agents-from-git-into.txt", "jsonld": "https://wpnews.pro/news/integration-guard-safely-merging-parallel-concurrent-ai-agents-from-git-into.jsonld"}}