Cross-Process Write Serialization

When multiple codescout MCP server instances run against the same project directory simultaneously (e.g. two IDE windows, two Claude Code sessions, or a background indexer alongside an active session), write-tool calls are now serialized so they cannot corrupt each other.

How It Works

Two lock layers protect each write:

1. In-process mutex — tokio::sync::Mutex<()> per ActiveProject. Acquired first. Serializes concurrent write-tool calls within a single codescout process.
2. Cross-process flock — fs4 advisory lock on .codescout/write.lock. Acquired second. Serializes writes across all codescout instances on the same project.

The lock is held for the full duration of the tool call and released on drop (WriteGuard RAII).

Behavior on Contention

If a write-tool call cannot acquire the cross-process lock within the timeout, it returns a RecoverableError (MCP isError: false). The agent receives a message:

another codescout instance is writing to this project
Retry in a moment — the holder should release shortly.

Because isError is false, sibling tool calls in the same MCP batch continue normally.

Configuration

Set write_lock_timeout_secs in .codescout/config.toml under [security]:

[security]
write_lock_timeout_secs = 10  # default: 5

Covered Write Tools

The following tools acquire the write lock: create_file, edit_file, edit_markdown, edit_code, and memory write actions (write, remember, forget, delete, refresh_anchors).

Read tools (read_file, symbols, symbols, etc.) skip the lock entirely — no overhead on reads.

Lock File

The lock file lives at .codescout/write.lock inside the project root. It is created automatically on workspace(action: activate) and is gitignored.