P2-T3: Fix double-spawn race condition when MCP client toggles rapidly

[SoundBlaster]

Description

Fixes the double-spawn race condition that occurs when an MCP client (e.g. Zed) toggles its connection off/on rapidly. Two proxy processes could simultaneously detect no broker running and each spawn a daemon — two competing daemons then race for the Unix socket, one crashes, and the losing proxy's client shows 0 tools.

Fix: wrap _spawn_broker_if_needed in a fcntl.flock(LOCK_EX) critical section on a broker.lock file co-located with broker.pid. The second proxy waiter blocks on flock, then re-checks liveness under the lock and short-circuits to the connect path if the first spawner succeeded. The lock is automatically released on process exit (including crash) by the OS.

Changes:

• src/mcpbridge_wrapper/broker/proxy.py — added import fcntl; _spawn_broker_if_needed now acquires LOCK_EX via run_in_executor before the spawn decision
• tests/unit/test_broker_proxy.py — added TestBrokerProxySpawnLock (4 tests): lock file location, LOCK_EX acquisition, second-proxy skip, lock release on timeout

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactoring
• CI/CD improvement

Quality Gates

• make test - All tests pass with ≥90% coverage (682 passed, 91.43% coverage)
• make lint - No linting errors (ruff check src/ passed)
• make format - Code is properly formatted
• make typecheck - Type checking passes
• make doccheck - Documentation is synced with DocC (if docs changed)

Documentation Sync

• Documentation changes are synced with DocC catalog (or N/A) — no docs changed

Testing

• Added/updated tests for new functionality (4 new tests in TestBrokerProxySpawnLock)
• All tests pass locally (682 passed, 0 failures)
• Manually tested the changes

Checklist

• Code follows the project's style guidelines
• Self-review completed
• Comments added for complex code
• Documentation updated (if needed)
• No new warnings generated
• PR title is descriptive

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.