SoundBlaster · SoundBlaster · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-03-07 (P7-T1 review archived)
+**Last Updated:** 2026-03-07 (P7-T2 review archived)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P7-T2 | [P7-T2_Implement_a_broker_doctor_command_for_cross-black-box_diagnostics/](P7-T2_Implement_a_broker_doctor_command_for_cross-black-box_diagnostics/) | 2026-03-07 | PASS |
 | P7-T1 | [P7-T1_Add_one-command_broker_host_startup_with_attached_frontend/](P7-T1_Add_one-command_broker_host_startup_with_attached_frontend/) | 2026-03-07 | PASS |
 | P6-T3 | [P6-T3_Document_the_explicit_dedicated-host_frontend_workflow/](P6-T3_Document_the_explicit_dedicated-host_frontend_workflow/) | 2026-03-07 | PASS |
 | P6-T2 | [P6-T2_Build_a_terminal_frontend_for_broker_daemon_monitoring_and_control/](P6-T2_Build_a_terminal_frontend_for_broker_daemon_monitoring_and_control/) | 2026-03-07 | PASS |
@@ -197,6 +198,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_broker_doctor_diagnostics.md](_Historical/REVIEW_broker_doctor_diagnostics.md) | Review report for P7-T2 |
 | [REVIEW_broker_console_startup.md](_Historical/REVIEW_broker_console_startup.md) | Review report for P7-T1 |
 | [REVIEW_dedicated_host_frontend_docs.md](_Historical/REVIEW_dedicated_host_frontend_docs.md) | Review report for P6-T3 |
 | [REVIEW_broker_terminal_frontend.md](_Historical/REVIEW_broker_terminal_frontend.md) | Review report for P6-T2 |
@@ -605,3 +607,5 @@
 | 2026-03-06 | BUG-T9 | Archived Fix_broker_daemon_not_sending_notifications_initialized_before_tools_list_probe (PASS) |
 | 2026-03-06 | BUG-T9 | Archived REVIEW_BUG-T9 report |
 | 2026-03-07 | P6-T2 | Archived REVIEW_broker_terminal_frontend report |
+| 2026-03-07 | P7-T2 | Archived Implement_a_broker_doctor_command_for_cross-black-box_diagnostics (PASS) |
+| 2026-03-07 | P7-T2 | Archived REVIEW_broker_doctor_diagnostics report |
diff --git a/...tics/P7-T2_Implement_a_broker_doctor_command_for_cross-black-box_diagnostics.md b/...tics/P7-T2_Implement_a_broker_doctor_command_for_cross-black-box_diagnostics.md
@@ -0,0 +1,145 @@
+# P7-T2 — Implement a broker doctor command for cross-black-box diagnostics
+
+## Objective Summary
+
+The new broker-console flow reduced startup friction, but users still hit
+multi-layer failures that are hard to interpret: Python environment mismatch,
+stale broker files, a live broker without dashboard, a dashboard port owned by
+the wrong process, or a reachable dashboard that is not the dedicated
+broker-hosted runtime. `P7-T2` should provide one explicit doctor command that
+explains those states in user-facing language and points to the single next
+action instead of sending users to `lsof`, `curl`, or raw logs.
+
+The doctor command should build on the status surfaces already introduced for
+the TUI and broker daemon rather than inventing a parallel diagnostics stack.
+It should classify the visible runtime into actionable buckets, report the
+evidence behind that classification, and expose enough detail to help users
+understand whether the broken box is Xcode, the IDE-side MCP config, or the
+local Python/broker host.
+
+## Deliverables
+
+- Add a dedicated user-facing diagnostics mode such as `--doctor` wired through
+  `src/mcpbridge_wrapper/__main__.py`.
+- Introduce a reusable diagnostics module that inspects:
+  - package/runtime identity and local executable context
+  - broker PID/socket/version files and live process state
+  - dashboard endpoint health, ownership, and broker-backed status
+  - broker runtime payload when the endpoint is broker-backed
+- Print concise diagnosis output with one primary status, supporting evidence,
+  and the most likely next action.
+- Add tests for healthy, broker-without-dashboard, foreign-dashboard-owner,
+  and stale-runtime scenarios.
+
+## Success Criteria
+
+- Users can run one command and immediately learn whether broker mode is healthy
+  and, if not, what exact remediation step to take next.
+- The doctor output distinguishes at least these cases:
+  - broker not running
+  - broker running without dashboard
+  - dashboard alive but not broker-backed
+  - port occupied by another listener before broker startup
+  - broker/dashboard version or runtime mismatch when observable
+- The implementation reuses existing runtime probes where possible so TUI and
+  future UX tasks can share the same diagnosis logic.
+
+## Test-First Plan
+
+1. Add CLI tests that pin `--doctor` flag parsing, incompatibilities with
+   bridge-only arguments, and exit-code behavior for healthy vs degraded
+   diagnoses.
+2. Add diagnostics-unit tests that feed mocked local files, PID checks, port
+   listeners, and HTTP probe results into the doctor classifier for the core
+   runtime buckets.
+3. Add rendering tests that ensure output stays actionable and names the exact
+   recommended next action for each major failure class.
+4. Only after the behavior is pinned, implement the diagnostics module and wire
+   it into `main()`.
+5. Run required quality gates: `pytest`, `ruff check src/`, `mypy src/`, and
+   `pytest --cov`.
+
+## Execution Plan
+
+### Phase 1: Doctor contract and classification model
+
+Inputs:
+- `src/mcpbridge_wrapper/__main__.py`
+- existing broker/TUI helpers for local PID and dashboard probes
+
+Outputs:
+- a stable command shape for doctor mode
+- diagnosis categories and exit-code policy
+- reusable data structures for findings, summary, and next-action guidance
+
+Verification:
+- healthy and degraded states map to deterministic summary strings
+- the model can represent both local-file evidence and HTTP-probe evidence
+
+### Phase 2: Local and remote probe implementation
+
+Inputs:
+- `BrokerConfig.default()` state files
+- local PID/port ownership probes
+- dashboard `/api/control`, `/api/health`, and `/api/broker/status`
+
+Outputs:
+- consolidated probe helpers for local broker state
+- dashboard ownership checks that distinguish “wrong service” from
+  “broker-backed but degraded”
+- Xcode/upstream status surfaced when the broker-backed dashboard is reachable
+
+Verification:
+- no-shell-debugging scenarios from the workplan can be distinguished from one
+  another by the probe results alone
+- endpoint failures include enough detail for direct user remediation
+
+### Phase 3: User-facing rendering, CLI wiring, and regression tests
+
+Inputs:
+- doctor probe/classification results
+- `__main__.py` mode validation rules
+- existing unit test suites for main and TUI flows
+
+Outputs:
+- final text output for `--doctor`
+- CLI integration in `main()`
+- regression tests covering the core scenarios and exit codes
+- validation report with required quality-gate results
+
+Verification:
+- output stays concise but actionable in every failure mode
+- doctor mode does not regress existing broker/TUI/web-ui entrypoints
+
+## Acceptance Tests
+
+- `pytest tests/unit/test_main.py`
+- `pytest tests/unit/test_main_tui.py`
+- `pytest tests/unit/test_tui.py`
+- `pytest tests/unit/test_doctor.py`
+- `pytest`
+- `ruff check src/`
+- `mypy src/`
+- `pytest --cov`
+
+## Decision Points
+
+- Prefer a flag-based entrypoint (`--doctor`) to match the current CLI style and
+  avoid introducing a separate subcommand parser mid-stream.
+- Treat doctor as a shared diagnostics surface, not as a TUI-only helper, so
+  later tasks can reuse the same findings in TUI fallback and docs.
+- Keep the primary output human-readable first; structured export can remain a
+  future enhancement if needed.
+
+## Notes
+
+- Minimize duplication with `tui.py` and current broker-console probes; if local
+  status helpers must move into a shared module, do that now instead of growing
+  another copy.
+- Any new remediation text should align with the recommended dedicated-host
+  workflow introduced in `P7-T1`.
+- Review subject name for this task: `broker_doctor_diagnostics`.
+
+---
+**Archived:** 2026-03-07
+**Verdict:** PASS
diff --git a/...roker_doctor_command_for_cross-black-box_diagnostics/P7-T2_Validation_Report.md b/...roker_doctor_command_for_cross-black-box_diagnostics/P7-T2_Validation_Report.md
@@ -0,0 +1,94 @@
+# P7-T2 Validation Report
+
+**Task:** P7-T2 — Implement a broker doctor command for cross-black-box diagnostics
+**Date:** 2026-03-07
+**Verdict:** PASS
+
+## Summary
+
+Implemented a user-facing broker diagnostics command by:
+
+- adding `--doctor` as a dedicated CLI mode in
+  `src/mcpbridge_wrapper/__main__.py`
+- introducing `src/mcpbridge_wrapper/doctor.py` to collect and classify Python
+  runtime identity, local broker files/processes, dashboard ownership, and
+  broker-backed runtime state
+- distinguishing actionable diagnosis buckets such as healthy runtime,
+  version mismatch, stale local state, broker without dashboard, wrong
+  dashboard service, occupied dashboard port, and degraded broker-backed state
+- rendering one concise user-facing report with summary, next action, and
+  supporting evidence instead of requiring manual `lsof` / `curl` debugging
+- adding focused unit coverage for helper probes, classification branches,
+  CLI wiring, and output rendering
+
+## Files Validated
+
+- `src/mcpbridge_wrapper/__main__.py`
+- `src/mcpbridge_wrapper/doctor.py`
+- `tests/unit/test_doctor.py`
+- `tests/unit/test_main_doctor.py`
+
+## Targeted Verification
+
+```bash
+pytest tests/unit/test_doctor.py tests/unit/test_main_doctor.py
+```
+
+- Result: `30 passed`
+
+```bash
+pytest tests/unit/test_doctor.py tests/unit/test_main_doctor.py --cov=mcpbridge_wrapper.doctor --cov-report=term-missing --no-cov-on-fail
+```
+
+- Result: `30 passed`
+- Doctor module coverage: `90.68%`
+
+```bash
+python -m mcpbridge_wrapper --doctor
+```
+
+- Result: command executed successfully in the local dedicated-host setup
+- Observed summary: `Status: OK`
+- Observed diagnosis: broker daemon and broker-backed dashboard were reported healthy
+
+## Required Quality Gates
+
+```bash
+pytest
+```
+
+- Result: `884 passed, 5 skipped in 7.98s`
+
+```bash
+ruff check src/ tests/
+```
+
+- Result: `All checks passed!`
+
+```bash
+mypy src/
+```
+
+- Result: `Success: no issues found in 20 source files`
+
+```bash
+make format-check
+```
+
+- Result: `55 files already formatted`
+
+```bash
+pytest --cov=src --cov-report=term
+```
+
+- Result: `884 passed, 5 skipped in 8.90s`
+- Coverage: `91.72%`
+
+## Notes
+
+- The new doctor output is human-readable first and optimized for the
+  dedicated-host broker workflow introduced in `P7-T1`.
+- The CLI smoke test used the current local runtime and confirmed that doctor
+  can identify a healthy broker-backed dashboard without requiring extra flags.
+- Remaining warnings are the pre-existing `websockets` / `uvicorn`
+  deprecations already seen in the repository test suite.
diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_broker_doctor_diagnostics.md b/SPECS/ARCHIVE/_Historical/REVIEW_broker_doctor_diagnostics.md
@@ -0,0 +1,47 @@
+## REVIEW REPORT — broker_doctor_diagnostics
+
+**Scope:** origin/main..HEAD
+**Files:** 9
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+
+None.
+
+### Secondary Issues
+
+None.
+
+### Architectural Notes
+
+- The new `doctor.py` module cleanly centralizes broker diagnostics instead of
+  burying them in `__main__.py` or the TUI layer, which keeps `P7-T4` and
+  `P7-T5` unblocked.
+- Reusing `build_tui_runtime()` and `BrokerTUIClient` keeps endpoint resolution
+  aligned with the existing frontend surface and avoids introducing another
+  dashboard-targeting contract.
+- The diagnosis buckets cover the user-visible failure modes called out in the
+  workplan: stale local runtime, missing dashboard, wrong service, occupied
+  port, degraded broker-backed state, and healthy runtime.
+
+### Tests
+
+- `pytest tests/unit/test_doctor.py tests/unit/test_main_doctor.py` passed
+- `python -m mcpbridge_wrapper --doctor` produced a healthy diagnosis against
+  the current local dedicated-host runtime
+- Full quality gates passed:
+  - `pytest`
+  - `ruff check src/ tests/`
+  - `mypy src/`
+  - `make format-check`
+  - `pytest --cov=src --cov-report=term`
+- Repository coverage remains above threshold at `91.72%`
+
+### Next Steps
+
+- No actionable review findings. FOLLOW-UP is skipped for `P7-T2`.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -1,23 +1,24 @@
-# Next Task: P7-T2 — Implement a broker doctor command for cross-black-box diagnostics
+# Next Task: P7-T3 — Auto-recover or guide on dashboard port ownership conflicts
 
 **Priority:** P0
 **Phase:** Phase 7: Broker UX and Diagnostics
-**Dependencies:** P6-T1
-**Status:** Ready after `P7-T1` CI clears
+**Effort:** 4-6 hours
+**Dependencies:** P6-T1, P7-T2
+**Status:** Ready after `P7-T2` CI clears
 
 ## Description
 
-Add a `doctor`-style diagnostic command that inspects the full user-visible
-chain: Python runtime, local broker files and processes, dashboard endpoint
-ownership, and common failure modes such as stale ports, missing dashboard, or
-wrong endpoint. The output should help users debug without needing to infer the
-internal broker architecture first.
+Improve the broker-hosted dashboard startup path so users do not get stranded
+when the desired Web UI port is occupied by a stale or unrelated process.
+Prefer deterministic recovery or one explicit remediation path over the current
+partial state where the broker can stay alive without the dashboard/frontend
+required by the recommended UX flow.
 
 ## Recently Archived
 
-- `2026-03-07` — `P7-T1` archived with verdict `PASS`
+- `2026-03-07` — `P7-T2` archived with verdict `PASS`
 
 ## Next Step
 
-Wait for the `P7-T1` pull request to clear CI, then run FLOW again to select
-and plan `P7-T2`.
+Wait for the `P7-T2` pull request to clear CI, then run FLOW again to select
+and plan `P7-T3`.
diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -497,7 +497,8 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [ ] `--broker-console` returns exit code `0` on `KeyboardInterrupt` whether it spawns a host or reuses an existing broker-backed dashboard
   - [ ] Unit tests cover the reuse-existing-dashboard interrupt path
 
-#### ⬜️ P7-T2: Implement a broker doctor command for cross-black-box diagnostics
+#### ✅ P7-T2: Implement a broker doctor command for cross-black-box diagnostics
+- **Status:** ✅ Completed (2026-03-07)
 - **Description:** Add a `doctor`-style diagnostic command that inspects the full chain visible to the user: Python package/runtime, local broker files and processes, dashboard endpoint ownership, upstream Xcode bridge state when observable, and common failure modes such as stale ports, missing dashboard, version mismatch, or wrong endpoint. The output should help users debug without needing to understand the internal architecture first.
 - **Priority:** P0
 - **Dependencies:** P6-T1
@@ -507,9 +508,9 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - new diagnostics module that checks broker PID/socket/version files, HTTP endpoints, occupied ports, and current package/runtime identity
   - unit/integration tests covering healthy, missing-dashboard, wrong-port, and stale-runtime scenarios
 - **Acceptance Criteria:**
-  - [ ] A single command prints a concise diagnosis of broker health and the most likely next action when startup failed
-  - [ ] The diagnostics distinguish between “broker alive but no dashboard”, “dashboard alive but wrong service”, “port already occupied”, and “broker not running”
-  - [ ] Output is user-facing and actionable without requiring users to manually run `lsof`, `curl`, or inspect raw log files first
+  - [x] A single command prints a concise diagnosis of broker health and the most likely next action when startup failed
+  - [x] The diagnostics distinguish between “broker alive but no dashboard”, “dashboard alive but wrong service”, “port already occupied”, and “broker not running”
+  - [x] Output is user-facing and actionable without requiring users to manually run `lsof`, `curl`, or inspect raw log files first
 
 #### ⬜️ P7-T3: Auto-recover or guide on dashboard port ownership conflicts
 - **Description:** Improve the broker-hosted dashboard startup path so users do not get stranded when the desired Web UI port is occupied by a stale or unrelated process. Prefer deterministic recovery or explicit guided remediation over the current “skip dashboard startup and keep broker alive” behavior, which leaves TUI and browser UX in a confusing partial state.