{"name":"Parallel Coding Agent Failure Taxonomy","version":"1.0.0","updated":"2026-07-17","canonical":"https://www.jasonsuhari.com/research/parallel-coding-agents","creator":"Jason Matthew Suhari","methodology":"First-hand operational classification of failure modes observed while running coding agents concurrently. The taxonomy records categories and controls, not incident frequency.","fields":["id","phase","failure","detection","prevention"],"records":[{"id":"shared-working-tree","phase":"implementation","failure":"Two agents edit the same working tree","detection":"Unexplained dirty files, overwritten edits, or diffs containing another task","prevention":"Give every editing agent its own branch and Git worktree"},{"id":"shared-port","phase":"validation","failure":"Multiple previews or test servers claim the same port","detection":"Address-in-use errors or one agent testing another agent's server","prevention":"Reuse one known server or allocate a documented port per worktree"},{"id":"shared-database","phase":"validation","failure":"Parallel tests mutate the same database or cache namespace","detection":"Nondeterministic tests, disappearing fixtures, or cross-task state","prevention":"Use a per-worktree database, schema, tenant, or namespace"},{"id":"shared-generated-state","phase":"implementation","failure":"Agents share generated files, caches, credentials, or local state","detection":"Lockfile churn, stale build output, authentication drift, or cache-only failures","prevention":"Document which state is shared, isolate mutable state, and never copy secrets into commits"},{"id":"duplicate-heavy-validation","phase":"validation","failure":"Several agents launch the same compiler, browser suite, or container build","detection":"CPU, memory, or I/O saturation with duplicate commands in the process tree","prevention":"Run cheap focused checks in parallel and serialize expensive validation"},{"id":"integration-race","phase":"integration","failure":"Two agents merge or validate different snapshots at the same time","detection":"A supposedly tested commit is not the commit being merged","prevention":"Publish immutable ready commits and allow one short-lived integration lease"},{"id":"late-arrival-restart-loop","phase":"integration","failure":"Every new ready change restarts a broad validation run","detection":"The integration batch never reaches a stable testable snapshot","prevention":"Refresh the queue once before broad validation; defer later arrivals to the next batch"},{"id":"silent-handoff","phase":"integration","failure":"An agent stops without recording what changed or what remains","detection":"A dirty worktree or branch exists with no trustworthy status","prevention":"Require a handoff containing branch, commit, dirty files, checks, blockers, and next action"},{"id":"orphan-process","phase":"cleanup","failure":"A completed agent leaves a watcher, browser, server, or child process running","detection":"Ports remain occupied or resource use continues after the task ends","prevention":"Track process ownership and stop only processes started by the finishing agent"},{"id":"unsafe-cleanup","phase":"cleanup","failure":"One agent resets, cleans, moves, or deletes another agent's work","detection":"Missing branches, worktrees, uncommitted files, or unexplained history changes","prevention":"Resolve exact targets first and make every agent clean up only its own worktree"}],"sources":[{"title":"Git worktree documentation","publisher":"Git","url":"https://git-scm.com/docs/git-worktree"},{"title":"Run parallel sessions with worktrees","publisher":"Claude Code documentation","url":"https://code.claude.com/docs/en/worktrees"},{"title":"GridBash source and documentation","publisher":"GitHub","url":"https://github.com/jasonsuhari/gridbash"},{"title":"Optimize high-load runtime throughput and latency","publisher":"GridBash engineering log","url":"https://github.com/jasonsuhari/gridbash/blob/main/docs/devlogs/2026-07-15-optimize-high-load-runtime-throughput-and-latency.md"},{"title":"Building a Windows PTY Grid for Coding Agents in Rust","publisher":"GridBash engineering article","url":"https://github.com/jasonsuhari/gridbash/blob/main/docs/articles/building-a-windows-pty-grid-in-rust.md"}]}