Subagents can spawn duplicate MCP servers for same project, causing lock conflicts and orphaned codanna serve processes

[jasantunes]

Summary

When an AI tool spawns subagents, each subagent may automatically start its own Codanna MCP server for the same project.

That can lead to several concurrent codanna serve --watch processes in one workspace, even when a parent agent already started Codanna and the subagent should have reused it.

In practice, this also interacts badly with tools that do not fully terminate subagents after they finish, leaving orphaned codanna serve processes running and consuming memory.

Why this matters

Codanna's docs recommend:

• MCP Persistent for continuous AI assistant use
• MCP Network for multiple clients

Relevant docs:

• https://docs.codanna.sh/reference/mcp-quick
• https://docs.codanna.sh/installation

From MCP Quick, the "When to Use" table says:

• "Continuous AI assistant use" -> MCP Persistent
• "Multiple clients" -> MCP Network

This suggests that multiple independent stdio-spawned MCP server instances against the same project are not the intended setup.

Also, Codanna's integration guidance mentions index-lock conflict risk. In agent/subagent workflows, duplicate codanna serve --watch instances make those conflicts much more likely.

Observed behavior

Example process list from a single project after spawning a subagent:

$ ps aux | grep codanna
jantunes         17498   0.0  0.0 416946048    848 s001  R+    3:46PM   0:00.00 /opt/homebrew/bin/ggrep codanna
jantunes         14613   0.0  0.1 443314000  12416 s000  S     3:40PM   0:00.94 codanna serve --watch
jantunes         14244   0.0  0.1 443196992  12464 s000  S     3:40PM   0:00.93 codanna serve --watch

Parent agent already had Codanna available.
Subagent still started another instance.

After the subagent completed, the extra process remained alive instead of being cleaned up.

Reproduction

1. Configure an AI tool to use Codanna via MCP for a project.
2. Start a parent agent in that project so Codanna is already active.
3. Ask the tool to spawn a subagent for a simple task.
4. Inspect running processes with ps.
5. Observe that another codanna serve --watch process may be started for the same project.
6. Finish the subagent task.
7. Observe that the extra Codanna process may remain running if the tool does not tear down subagents cleanly.

Expected behavior

One of these should happen:

1. Subagents should reuse the parent's already-running Codanna connection/server instead of spawning a second one.
2. If a new process must be started, it should be project-safe and fully cleaned up when the subagent exits.
3. If concurrent same-project servers are unsupported, Codanna should fail fast with a clearer warning and recommended integration pattern.

Actual behavior

• Multiple codanna serve --watch processes can be started for the same project.
• This can trigger index lock conflicts.
• Orphaned Codanna processes can remain after subagent completion.
• Memory usage grows over time in agent-heavy workflows.

Possible improvements

• Document a recommended pattern for parent/subagent agent systems.
• Detect and warn on duplicate same-project serve --watch processes.
• Offer a shared/singleton server mode that subagents can attach to.
• Improve lock-conflict messaging with explicit guidance for AI orchestration environments.

Environment

• macOS
• AI tool with parent/subagent workflow
• Same local project used by both parent and subagent

[bartolli]

Thanks for the writeup and process trace. v0.9.20 adds a PID lockfile at .codanna/index/serve.lock. A second codanna serve against the same index now exits fast with guidance to use HTTP mode for multi-client setups. Upgrade and let me know if subagents still spawn duplicates.