P7-T2: Implement a broker doctor command for cross-black-box diagnostics

[SoundBlaster]

Description

Implements P7-T2 by adding a dedicated --doctor diagnostics mode for the broker workflow.

Changes in this PR:

• add --doctor CLI wiring in src/mcpbridge_wrapper/__main__.py
• add src/mcpbridge_wrapper/doctor.py to inspect Python/runtime identity, local broker files and processes, dashboard ownership, and broker-backed runtime health
• classify actionable diagnosis states such as healthy runtime, version mismatch, stale local state, broker without dashboard, wrong dashboard service, occupied dashboard port, and degraded broker-backed runtime
• add focused unit coverage in tests/unit/test_doctor.py and tests/unit/test_main_doctor.py
• archive validation evidence in SPECS/ARCHIVE/P7-T2_Implement_a_broker_doctor_command_for_cross-black-box_diagnostics/P7-T2_Validation_Report.md

Validation executed locally:

• pytest
• pytest --cov=src --cov-report=term
• ruff check src/ tests/
• mypy src/
• make format-check
• python -m mcpbridge_wrapper --doctor

Non-blocking note: the test suite still emits the pre-existing websockets / uvicorn deprecation warnings already present on main.

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]

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.