P2-T8: Gate broker tools/list on warmed tool catalog

[SoundBlaster]

Description

Fixes the broker startup race behind the repeated Cursor/Zed ON/OFF workaround.

Root cause: the broker exposed client tools/list as soon as upstream initialize completed, but strict MCP clients can cache that first successful response before the broker has finished its own notifications/initialized + tools/list warm-up. On cold start that could leak an empty or invalid catalog and leave Xcode tools partially discovered.

This PR:

• adds a dedicated tools_catalog_ready gate so external tools/list waits for a warmed non-empty cache;
• retries the broker-internal tools/list warm-up probe after empty/invalid results so the catalog can recover without reconnect/restart;
• keeps non-tools/list broker traffic gated only on upstream initialization;
• adds daemon/transport/integration regression coverage for the new contract;
• makes pytest prefer the checkout-local src path so worktree validation does not accidentally import a sibling editable install.

Validation artifacts:

• SPECS/ARCHIVE/P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/P2-T8_Validation_Report.md
• SPECS/ARCHIVE/_Historical/REVIEW_p2_t8_tools_catalog_gate.md
• local checks run: pytest, ruff check src/, mypy src/, pytest --cov

Type of Change

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

Quality Gates

Before submitting, ensure all quality gates pass:

make check

Or run individually:

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

Documentation Sync

If you modified files in docs/, ensure corresponding DocC files are also updated:

docs/ file	DocC file
docs/installation.md	mcpbridge-wrapper.docc/Installation.md
docs/cursor-setup.md	mcpbridge-wrapper.docc/CursorSetup.md
docs/claude-setup.md	mcpbridge-wrapper.docc/ClaudeCodeSetup.md
docs/codex-setup.md	mcpbridge-wrapper.docc/CodexCLISetup.md
docs/troubleshooting.md	mcpbridge-wrapper.docc/Troubleshooting.md
docs/architecture.md	mcpbridge-wrapper.docc/Architecture.md
docs/environment-variables.md	mcpbridge-wrapper.docc/EnvironmentVariables.md
README.md	mcpbridge-wrapper.docc/mcpbridge-wrapper.md

• Documentation changes are synced with DocC catalog (or N/A)

Testing

• Added/updated tests for new functionality
• All tests pass locally
• 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]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62a7df7349

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR fixes a broker cold-start race where strict MCP clients can cache an early, incomplete tools/list response before the broker finishes its internal warm-up, leading to partially discovered tools until users reconnect/restart.

Changes:

• Add a dedicated tools_catalog_ready readiness gate so external tools/list waits for a warmed, non-empty cached catalog (while other methods remain gated only on upstream initialization).
• Add retry behavior for the broker-internal tools/list warm-up probe when results are empty/invalid, allowing recovery without reconnect/restart.
• Update unit/integration tests and pytest configuration (pythonpath = ["src"]) to validate the new contract and ensure local checkout imports.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/mcpbridge_wrapper/broker/transport.py	Gate client tools/list on tools_catalog_ready, preserving previous gating for other methods.
src/mcpbridge_wrapper/broker/daemon.py	Introduce tools_catalog_ready, cache validation (non-empty tools), and warm-up probe retry scheduling/cancellation.
tests/unit/test_broker_transport.py	Add coverage for tools/list gating/TTL behavior and adjust existing cache-hit/miss tests for the new gate.
tests/unit/test_broker_daemon.py	Add/extend coverage for catalog readiness, empty/invalid probe handling, retry behavior, and reconnect clearing.
tests/integration/test_broker_multi_client.py	Adjust concurrent-load test to use a forwarded method (tools/call) rather than the now-special-cased cached tools/list path.
pyproject.toml	Configure pytest to prefer checkout-local src on sys.path.
SPECS/Workplan.md	Record P2-T8 completion and acceptance criteria.
SPECS/INPROGRESS/next.md	Update “next task” status and archive note.
SPECS/ARCHIVE/INDEX.md	Add P2-T8 to the archive index and update “Last Updated”.
SPECS/ARCHIVE/_Historical/REVIEW_p2_t8_tools_catalog_gate.md	Add historical review report artifact.
SPECS/ARCHIVE/P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/P2-T8_Validation_Report.md	Add validation report artifact.
SPECS/ARCHIVE/P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog.md	Archive the task spec describing the race and fix.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.