P1-T12: Improve troubleshooting docs for Zed broker startup timeouts

SPECS/ARCHIVE/INDEX.md

@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-03-06 (P5-T2 archived)
+**Last Updated:** 2026-03-07 (P1-T12 archived)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P1-T12 | [P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts/](P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts/) | 2026-03-07 | PASS |
 | P5-T2 | [P5-T2_Release_0.4.1_to_PyPI_and_MCP_Registry/](P5-T2_Release_0.4.1_to_PyPI_and_MCP_Registry/) | 2026-03-06 | PASS |
 | BUG-T9 | [BUG-T9_Fix_broker_daemon_not_sending_notifications_initialized_before_tools_list_probe/](BUG-T9_Fix_broker_daemon_not_sending_notifications_initialized_before_tools_list_probe/) | 2026-03-06 | PASS |
 | P5-T1 | [P5-T1_release_0.4.0/](P5-T1_release_0.4.0/) | 2026-03-06 | PASS |
@@ -192,6 +193,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_p1_t12_zed_timeout_docs.md](_Historical/REVIEW_p1_t12_zed_timeout_docs.md) | Review report for P1-T12 |
 | [REVIEW_P4-T2_broker_readiness_cache.md](_Historical/REVIEW_P4-T2_broker_readiness_cache.md) | Review report for P4-T2 |
 | [REVIEW_P1-T11_readme_coverage_badge.md](_Historical/REVIEW_P1-T11_readme_coverage_badge.md) | Review report for P1-T11 |
 | [REVIEW_P1-T10_xcode_first_approval_docs.md](_Historical/REVIEW_P1-T10_xcode_first_approval_docs.md) | Review report for P1-T10 |
@@ -327,6 +329,7 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-03-07 | P1-T12 | Archived task artifacts and validation report |
 | 2026-03-06 | P5-T2 | Archived Release_0.4.1_to_PyPI_and_MCP_Registry (PASS) |
 | 2026-03-06 | P5-T2 | Archived REVIEW_release-0.4.1 report |
 | 2026-03-06 | P1-T11 | Archived REVIEW_P1-T11_readme_coverage_badge report |

SPECS/ARCHIVE/P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts/P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts.md

@@ -0,0 +1,91 @@
+# P1-T12 — Improve Troubleshooting Docs for Zed Broker Startup Timeouts
+
+**Task ID:** P1-T12
+**Priority:** P1
+**Phase:** Phase 1 — Documentation
+**Status:** In Progress
+
+## Objective Summary
+
+Extend the broker troubleshooting guidance with the Zed-specific failure mode observed during live
+testing: after approving the first `mcpbridge-broker` Xcode dialog, Zed can briefly show a green
+context-server indicator with 0 tools and later fail on reconnect with `Context server request timeout`.
+The current docs explain the first-approval race in general terms, but they do not give Zed users a
+clear recovery path once the broker state becomes stale or once Zed starts timing out on `initialize`
+or `tools/list`.
+
+This task should document the practical recovery that worked in session:
+- stop the stale broker daemon
+- start a dedicated `--broker-daemon` host manually
+- re-enable the Zed context server after the host is already available
+
+It should also clarify that multiple inactive `mcpbridge-broker` rows in Xcode Agent Activity usually
+represent historical broker sessions or retries, not multiple live broker daemons competing at once.
+
+## Success Criteria and Acceptance Tests
+
+- `docs/troubleshooting.md` explicitly describes the Zed sequence of `0 tools` after approval followed
+  by `Context server request timeout` on subsequent reconnects.
+- `docs/troubleshooting.md` includes a dedicated-host recovery sequence using:
+  - `mcpbridge-wrapper --broker-stop`
+  - manual `--broker-daemon` startup
+  - re-enabling the Zed context server after the daemon is healthy
+- `docs/troubleshooting.md` explains how to interpret inactive `mcpbridge-broker` entries in Xcode
+  Agent Activity.
+- `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` mirrors the same guidance.
+- Documentation sync check passes.
+
+Acceptance test procedure:
+1. Read the updated troubleshooting entry and confirm a Zed user can recover without guessing.
+2. Verify the dedicated-host commands are correct for the wrapper CLI.
+3. Run `make doccheck` to ensure the markdown and DocC mirror stay aligned.
+
+## Test-First Plan
+
+Before editing docs:
+1. Inspect the current troubleshooting sections for broker cold-start and Zed references.
+2. Confirm the exact command forms already documented for `--broker-stop` and `--broker-daemon`.
+3. Identify the matching DocC section so the prose can be mirrored without drift.
+
+After editing docs:
+1. Run `make doccheck`.
+2. Run the repository quality gates required by FLOW:
+   - `pytest`
+   - `ruff check src/`
+   - `mypy src/`
+   - `pytest --cov`
+3. Capture outcomes in `SPECS/INPROGRESS/P1-T12_Validation_Report.md`.
+
+## TODO Plan
+
+### Phase 1 — Analyze Current Gaps
+- **Inputs:** existing `docs/troubleshooting.md`, DocC troubleshooting mirror, Zed/Xcode behavior observed during debugging
+- **Outputs:** exact insertion points and missing recovery details
+- **Verification:** the gap list covers timeout recovery, dedicated-host guidance, and Xcode Agent Activity interpretation
+
+### Phase 2 — Update User-Facing Documentation
+- **Inputs:** approved task scope and verified commands
+- **Outputs:** updated troubleshooting markdown plus synced DocC mirror
+- **Verification:** both files describe the same Zed recovery path and use correct command examples
+
+### Phase 3 — Validate and Record
+- **Inputs:** changed docs and repository quality commands
+- **Outputs:** validation report with doccheck and quality gate results
+- **Verification:** checks complete successfully and acceptance criteria are marked with evidence
+
+## Decision Points and Constraints
+
+- Keep this task focused on troubleshooting and recovery, not on broker code changes.
+- Prefer recovery steps that reduce Zed startup timing sensitivity; dedicated-host mode is the key
+  recommendation for this scenario.
+- Mirror the docs faithfully in DocC rather than introducing diverging wording or extra claims.
+
+## Notes
+
+- Update only the troubleshooting docs unless another file is necessary to avoid ambiguity.
+- Preserve existing first-approval guidance from P1-T10 and add the Zed timeout recovery as an
+  extension of that known issue rather than a conflicting explanation.
+
+---
+**Archived:** 2026-03-07
+**Verdict:** PASS

SPECS/ARCHIVE/P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts/P1-T12_Validation_Report.md

@@ -0,0 +1,59 @@
+# P1-T12 Validation Report
+
+**Task:** Improve troubleshooting docs for Zed broker startup timeouts
+**Date:** 2026-03-07
+**Verdict:** PASS
+
+## Acceptance Criteria Checklist
+
+- [x] `docs/troubleshooting.md` documents the Zed sequence of green/0 tools after approval followed by `Context server request timeout` on restart
+  - Added a Zed-specific escalation subsection under the existing broker first-approval troubleshooting entry
+  - The new text explains why Zed can move from green/0 tools to a red timeout state after the initial approval race
+
+- [x] `docs/troubleshooting.md` includes a step-by-step dedicated-host recovery flow using `mcpbridge-wrapper --broker-stop` and manual `--broker-daemon` startup
+  - Recovery steps now instruct users to disable Zed, stop the stale broker, start a dedicated broker host manually, verify with `--broker-status`, then re-enable Zed
+
+- [x] `docs/troubleshooting.md` explains that inactive `mcpbridge-broker` entries in Xcode Agent Activity are usually historical sessions, not proof of multiple live brokers
+  - Added an explicit Xcode Agent Activity note describing inactive broker rows as previous sessions or reconnect attempts
+
+- [x] `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` mirrors the new guidance
+  - Added the matching DocC section `Zed reconnects with "Context server request timeout" after first approval`
+
+## Quality Gates
+
+- [x] `make doccheck`
+- [x] `ruff check src/`
+- [x] `mypy src/`
+- [x] `pytest`
+- [x] `pytest tests/ -v --cov=src --cov-report=term --cov-report=xml`
+- [x] `make doccheck-all`
+
+## Command Results
+
+| Command | Result |
+|---------|--------|
+| `make doccheck` | PASS |
+| `ruff check src/` | PASS |
+| `mypy src/` | PASS |
+| `pytest` | PASS in repo `.venv` (`785 passed, 5 skipped`) |
+| `pytest tests/ -v --cov=src --cov-report=term --cov-report=xml` | PASS, coverage `90.81%` |
+| `make doccheck-all` | PASS |
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `docs/troubleshooting.md` | Added Zed-specific timeout recovery and Xcode Agent Activity clarification |
+| `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` | Mirrored the new Zed recovery guidance |
+
+## Notes
+
+- The shell-global `pytest` invocation initially failed because the package was not importable outside
+  an editable install. Validation was rerun in the repository's existing `.venv` after:
+
+```bash
+source .venv/bin/activate
+python -m pip install -e '.[webui]'
+```
+
+- This task changed documentation only. No application source or test files required modification.

SPECS/ARCHIVE/_Historical/REVIEW_p1_t12_zed_timeout_docs.md

@@ -0,0 +1,39 @@
+## REVIEW REPORT — P1-T12 Zed Timeout Docs
+
+**Scope:** `origin/main..HEAD`
+**Files:** 7
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+
+No actionable critical issues found.
+
+### Secondary Issues
+
+No actionable secondary issues found.
+
+### Architectural Notes
+
+- The new troubleshooting guidance extends the existing first-approval race section instead of
+  introducing a second competing explanation, which keeps the broker failure narrative coherent.
+- The DocC mirror stays aligned with the markdown troubleshooting guide and preserves the
+  repository's documentation-sync contract.
+
+### Tests
+
+- `make doccheck` passed.
+- `ruff check src/` passed.
+- `mypy src/` passed.
+- `pytest` passed in the repository `.venv` (`785 passed, 5 skipped`).
+- `pytest tests/ -v --cov=src --cov-report=term --cov-report=xml` passed with `90.81%` coverage.
+- `make doccheck-all` passed.
+
+### Next Steps
+
+- No follow-up tasks required.
+- FOLLOW-UP is skipped because the review found no actionable issues.

SPECS/INPROGRESS/next.md

@@ -8,10 +8,10 @@
 
 ## Recently Archived
 
+- **P1-T12** (2026-03-07): Improve troubleshooting docs for Zed broker startup timeouts — PASS
 - **P5-T2** (2026-03-06): Release 0.4.1 to PyPI and MCP Registry — PASS
 - **BUG-T9** (2026-03-06): Fix broker daemon not sending notifications/initialized before tools/list probe — PASS
 - **P5-T1** (2026-03-06): Release 0.4.0 to PyPI and MCP Registry — PASS
-- **P1-T11** (2026-03-06): Update test coverage badge in README.md with actual numbers — PASS
 
 ## Description
 

SPECS/Workplan.md

@@ -170,6 +170,22 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [x] `README.md` coverage badge value matches the coverage percentage recorded in the task validation report
   - [x] `README.md` Performance section coverage value matches the badge and the same validation result
 
+#### ✅ P1-T12: Improve troubleshooting docs for Zed broker startup timeouts
+- **Status:** ✅ Completed (2026-03-07)
+- **Description:** Extended the broker troubleshooting guidance with the Zed-specific first-approval failure pattern where Zed can briefly show 0 tools and then fail with `Context server request timeout`. The docs now capture the dedicated-host recovery sequence and explain how to interpret inactive `mcpbridge-broker` rows in Xcode Agent Activity.
+- **Priority:** P1
+- **Dependencies:** P1-T10
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - `docs/troubleshooting.md` updated with a Zed-specific timeout recovery subsection
+  - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` synced with the same Zed guidance
+  - `SPECS/ARCHIVE/P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts/` archived task artifacts
+- **Acceptance Criteria:**
+  - [x] `docs/troubleshooting.md` documents the Zed sequence of green/0 tools after approval followed by `Context server request timeout` on restart
+  - [x] `docs/troubleshooting.md` includes a step-by-step dedicated-host recovery flow using `mcpbridge-wrapper --broker-stop` and manual `--broker-daemon` startup
+  - [x] `docs/troubleshooting.md` explains that inactive `mcpbridge-broker` entries in Xcode Agent Activity are usually historical sessions, not proof of multiple live brokers
+  - [x] `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` mirrors the new guidance
+
 ### Phase 2: Broker Robustness
 
 #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag

Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md

@@ -70,6 +70,43 @@ claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]'
 tail -50 "$HOME/.mcpbridge_wrapper/broker.log" | grep -E "EOF|reconnect|ready|tools"
 ```
 
+## Zed reconnects with "Context server request timeout" after first approval
+
+If Zed first shows a green connection with 0 tools and later turns red with
+`Context server request timeout`, the broker usually never reached a stable upstream session
+within Zed's startup timeout window. In practice, the most reliable recovery is to reconnect
+Zed to an already-running dedicated broker host instead of relying on broker auto-spawn.
+
+**Recovery sequence:**
+
+1. Disable the `xcode-tools` context server in Zed or quit Zed.
+2. Stop the current broker daemon:
+
+```bash
+uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-stop
+```
+
+3. Start a dedicated broker host manually:
+
+```bash
+nohup uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-daemon \
+  > "$HOME/.mcpbridge_wrapper/broker.log" 2>&1 &
+```
+
+4. Verify the daemon is healthy:
+
+```bash
+uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-status
+```
+
+5. Re-enable the Zed context server or relaunch Zed.
+
+If Xcode already approved `mcpbridge-broker`, no new prompt should appear for the same binary path.
+
+**Xcode Agent Activity note:** Multiple `mcpbridge-broker` rows with only one `Active` entry
+usually represent previous sessions or approval/reconnect retries, not multiple live broker
+daemons. Use `--broker-status` to confirm the active daemon.
+
 ## Error: "Tool XcodeListWindows has an output schema but did not return structured content"
 
 **Symptom:** MCP client shows this error when trying to use Xcode tools.

docs/troubleshooting.md

@@ -102,6 +102,46 @@ tail -50 "$HOME/.mcpbridge_wrapper/broker.log" | grep -E "EOF|reconnect|ready|to
 After a successful approval and client reload you should see no new EOF entries and the
 upstream should remain stable.
 
+**Zed-specific escalation — green `0 tools` becomes red `Context server request timeout`:**
+
+If Zed first shows a green connection with 0 tools and later turns red with
+`Context server request timeout`, the broker daemon usually never reached a stable upstream
+session within Zed's 60-second startup window. In that state, auto-spawn can leave Zed waiting
+on a broker session that is still recovering from the first approval race.
+
+The most reliable recovery is to switch that reconnect through a dedicated broker host:
+
+1. Disable the `xcode-tools` context server in Zed (or quit Zed completely).
+2. Stop the current broker daemon:
+
+```bash
+uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-stop
+```
+
+3. Start a dedicated broker host manually:
+
+```bash
+nohup uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-daemon \
+  > "$HOME/.mcpbridge_wrapper/broker.log" 2>&1 &
+```
+
+4. Wait a few seconds, then verify the daemon is healthy:
+
+```bash
+uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-status
+```
+
+5. Re-enable the `xcode-tools` context server in Zed (or relaunch Zed).
+
+If Xcode already approved `mcpbridge-broker`, the prompt should not reappear for the same binary
+path. Zed now connects to an already-running broker instead of waiting for auto-spawn during its
+startup timeout window.
+
+**Xcode Agent Activity note:** Seeing several `mcpbridge-broker` rows with only one `Active`
+status usually means Xcode is showing previous broker sessions or reconnect attempts. It does
+**not** by itself mean multiple live broker daemons are running. Use `--broker-status` (or the
+PID file under `~/.mcpbridge_wrapper/`) to confirm which daemon is actually alive.
+
 ---
 
 ### "Tool has output schema but did not return structured content"