Merge pull request #36 from SoundBlaster/codex/fu-p9-t2-2-stale-uvx-troubleshooting

FU-P9-T2-2 Stale `uvx` troubleshooting

Author: SoundBlaster

README.md

@@ -77,6 +77,21 @@ With Web UI dashboard (optional — adds real-time monitoring at http://localhos
 }
 ```
 
+If you upgrade and want to confirm the currently running dashboard process version:
+
+```bash
+PORT=8080
+PID=$(lsof -tiTCP:$PORT -sTCP:LISTEN | head -n1)
+PY=$(ps -p "$PID" -o command= | awk '{print $1}')
+"$PY" -c 'import importlib.metadata as m; print(m.version("mcpbridge-wrapper"))'
+```
+
+If needed, do a one-time refresh start:
+
+```bash
+uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
+```
+
 Restart Cursor and you're done. For other clients or installation methods, read on.
 
 ### Python Environment Setup (Development)

SPECS/ARCHIVE/FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions.md

@@ -0,0 +1,40 @@
+# FU-P9-T2-2 — Add troubleshooting guidance for stale uvx cache/process versions
+
+**Priority:** P1  
+**Dependencies:** P9-T2, FU-P9-T2-1  
+**Phase:** Phase 9 Follow-up Backlog
+
+## Objective
+Document and validate the stale-runtime failure mode where users still run an older `uvx` environment/process after a release, resulting in unchanged behavior (for example uptime stuck at `1h 0m 0s`) even though updated packages exist.
+
+## Deliverables
+1. Add a dedicated troubleshooting section in `docs/troubleshooting.md` for stale `uvx` cache/process diagnosis.
+2. Add a recovery note in `docs/cursor-setup.md` explaining one-time use of `--refresh` after releases and restart behavior.
+3. Add a quick runtime-version verification snippet in `README.md` for Web UI users.
+4. Include concrete commands to:
+   - identify process listening on Web UI port,
+   - inspect active runtime package version for that process,
+   - restart with `uvx --refresh --from mcpbridge-wrapper[webui] ...`.
+5. Produce validation evidence in `SPECS/INPROGRESS/FU-P9-T2-2_Validation_Report.md`.
+
+## Acceptance Criteria
+1. Troubleshooting docs include symptom/cause/fix for stale behavior after upgrade.
+2. Docs include explicit diagnostic commands for port/PID/version validation.
+3. Recovery guidance includes `uvx --refresh --from mcpbridge-wrapper[webui] ...` and restart instructions.
+4. Docs clearly mention multiple concurrent wrapper processes can mask upgrades.
+5. Validation report records local repro and confirms refreshed process resolves stale behavior.
+
+## Execution Plan
+1. Update `docs/troubleshooting.md` with symptom, root cause, diagnosis workflow, and recovery flow.
+2. Update `docs/cursor-setup.md` with post-upgrade refresh guidance for `uvx` + Web UI usage.
+3. Update `README.md` with a concise runtime-version verification snippet.
+4. Run required quality gates per FLOW:
+   - `pytest`
+   - `ruff check src/`
+   - `mypy src/`
+   - `pytest --cov` (>= 90%)
+5. Capture outcomes and acceptance mapping in validation report.
+
+---
+**Archived:** 2026-02-13
+**Verdict:** PASS

SPECS/ARCHIVE/FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/FU-P9-T2-2_Validation_Report.md

@@ -0,0 +1,52 @@
+# FU-P9-T2-2 Validation Report
+
+**Task:** FU-P9-T2-2 — Add troubleshooting guidance for stale uvx cache/process versions  
+**Date:** 2026-02-14  
+**Verdict:** PASS
+
+## Summary
+Implemented troubleshooting and setup documentation updates for stale `uvx` runtime/process scenarios after upgrades, including concrete diagnosis commands, explicit `--refresh` recovery path, and warning about concurrent wrapper processes masking upgrades.
+
+## Deliverables Completed
+- Updated `docs/troubleshooting.md` with a dedicated stale-runtime section including:
+  - symptom/cause/fix narrative,
+  - port/PID/version diagnostics,
+  - `uvx --refresh --from 'mcpbridge-wrapper[webui]' ...` recovery,
+  - explicit note about multiple concurrent wrapper processes.
+- Updated `docs/cursor-setup.md` with a one-time `--refresh` config pattern for post-upgrade recovery.
+- Updated `README.md` with runtime process version verification snippet and refresh command.
+
+## Acceptance Criteria Validation
+1. Troubleshooting docs include symptom/cause/fix for stale behavior after upgrade.
+   - **PASS** — Added section: `"Uptime still shows 1h 0m 0s" or behavior is unchanged after upgrade` in `docs/troubleshooting.md`.
+2. Docs include explicit diagnostic commands for port/PID/version validation.
+   - **PASS** — Added `lsof`, `ps`, and interpreter-based `importlib.metadata` version checks.
+3. Recovery guidance includes `uvx --refresh --from mcpbridge-wrapper[webui] ...` and restart instructions.
+   - **PASS** — Added exact command and restart/reload guidance in troubleshooting and Cursor setup docs.
+4. Docs clearly mention multiple concurrent wrapper processes can mask upgrades.
+   - **PASS** — Added explicit warning in troubleshooting section.
+5. Validation report records local repro and confirms refreshed process resolves stale behavior.
+   - **PASS** — Local repro captured below with stale vs refreshed runtime evidence.
+
+## Local Reproduction Evidence
+```text
+stale_pid=8069
+stale_version=0.3.2
+stale_uptime_samples=3600,3600
+refresh_pid=53176
+refresh_version=0.3.3
+refresh_uptime_samples=0.4,2.4
+```
+
+Interpretation:
+- Stale listener on port 8080 remained on `0.3.2` and returned fixed uptime.
+- Refreshed start used `0.3.3` and returned increasing uptime.
+
+## Quality Gates
+- `pytest` — **PASS** (345 passed, 5 skipped)
+- `ruff check src/` — **PASS**
+- `mypy src/` — **PASS**
+- `pytest --cov` — **PASS** (96.62% total, threshold 90%)
+
+## Notes
+- Test runs reported non-fatal warnings about occupied local ports (`8080`/`9090`) in background Web UI thread tests; suite still passed and coverage remained above threshold.

SPECS/ARCHIVE/FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting.md

@@ -0,0 +1,31 @@
+## REVIEW REPORT — FU-P9-T2-2 stale uvx troubleshooting docs
+
+**Scope:** origin/main..HEAD
+**Files:** 8
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- The troubleshooting updates correctly target runtime-process diagnosis rather than package-install assumptions.
+- Guidance aligns with observed failure mode where older `uvx` environments continue serving active ports.
+
+### Tests
+- Quality gates executed during EXECUTE:
+  - `pytest` (pass)
+  - `ruff check src/` (pass)
+  - `mypy src/` (pass)
+  - `pytest --cov` (pass, 96.62% >= 90%)
+- No source-code behavior changes; docs-only updates validated with local stale-vs-refresh repro evidence.
+
+### Next Steps
+- FOLLOW-UP skipped: no actionable review findings.

SPECS/ARCHIVE/INDEX.md

@@ -82,6 +82,7 @@
 | BUG-T0 | [BUG-T0_Uptime_Widget_Fix/](BUG-T0_Uptime_Widget_Fix/) | 2026-02-13 | PASS |
 | P9-T4 | [P9-T4_Create_the_publishing_helper/](P9-T4_Create_the_publishing_helper/) | 2026-02-13 | PASS |
 | FU-P9-T4-1 | [FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/](FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/) | 2026-02-13 | PASS |
+| FU-P9-T2-2 | [FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/](FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/) | 2026-02-13 | PASS |
 
 ## Historical Artifacts
 
@@ -129,6 +130,7 @@
 | [REVIEW_BUG-T0_Uptime_Widget.md](BUG-T0_Uptime_Widget_Fix/REVIEW_BUG-T0_Uptime_Widget.md) | Review report for BUG-T0 |
 | [REVIEW_p9_t4_publishing_helper.md](P9-T4_Create_the_publishing_helper/REVIEW_p9_t4_publishing_helper.md) | Review report for P9-T4 |
 | [REVIEW_fu_p9_t4_1_publish_helper_protected_main.md](FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/REVIEW_fu_p9_t4_1_publish_helper_protected_main.md) | Review report for FU-P9-T4-1 |
+| [REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting.md](FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting.md) | Review report for FU-P9-T2-2 |
 
 ## Archive Log
 
@@ -211,4 +213,6 @@
 | 2026-02-13 | P9-T4 | Archived Create_the_publishing_helper (PASS) |
 | 2026-02-13 | P9-T4 | Archived REVIEW_p9_t4_publishing_helper report |
 | 2026-02-13 | FU-P9-T4-1 | Archived Align_publish_helper_output_with_protected_main_branch_workflow (PASS) |
+| 2026-02-13 | FU-P9-T2-2 | Archived Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions (PASS) |
+| 2026-02-13 | FU-P9-T2-2 | Archived REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting report |
 | 2026-02-13 | FU-P9-T4-1 | Archived REVIEW_fu_p9_t4_1_publish_helper_protected_main report |

SPECS/INPROGRESS/next.md

@@ -4,11 +4,11 @@ The previously selected task has been archived.
 
 ## Recently Archived
 
+- 2026-02-13 — FU-P9-T2-2: Add troubleshooting guidance for stale uvx cache/process versions (PASS)
 - 2026-02-13 — FU-P9-T4-1: Align publish_helper output with protected main branch workflow (PASS)
 - 2026-02-13 — P9-T4: Create the publishing helper (PASS)
 - 2026-02-13 — BUG-T0: Uptime widget on Web UI always shows 1h 0m 0s (PASS)
 - 2026-02-13 — FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (PASS)
-- 2026-02-13 — FU-REBUILD-P10-T1-7: Include Web UI static assets in published package artifacts (PASS)
 
 ## Suggested Next Tasks
 

SPECS/Workplan.md

@@ -1215,6 +1215,7 @@ Main branch is currently unstable after an accidental merge of the Phase 10 Web
 Phase 9 Follow-up Backlog
 - [x] FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (P1)
 - [x] FU-P9-T4-1: Align publish_helper output with protected main branch workflow (P1)
+- [x] FU-P9-T2-2: Add troubleshooting guidance for stale uvx cache/process versions (P1)
 
 #### ✅ FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras
 - **Description:** Resolve documentation/config mismatch where examples use `uvx --from mcpbridge-wrapper ... --web-ui` without optional dependencies. Update all uvx Web UI examples to install extras via `--from mcpbridge-wrapper[webui]`, and align troubleshooting/runtime guidance with the correct uvx command.
@@ -1254,6 +1255,26 @@ Phase 9 Follow-up Backlog
 
 ---
 
+#### ✅ FU-P9-T2-2: Add troubleshooting guidance for stale uvx cache/process versions
+- **Description:** Document the failure mode where Cursor or manual Web UI sessions keep running an older `uvx` environment (for example `mcpbridge-wrapper==0.3.2`) after a fix is released, causing stale behavior such as uptime stuck at `1h 0m 0s`. Add explicit verification and recovery steps using port/PID inspection, version checks, process restart, and `uvx --refresh`.
+- **Priority:** P1
+- **Dependencies:** P9-T2, FU-P9-T2-1
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - Updated `docs/troubleshooting.md` with a dedicated section for stale `uvx` cache/process diagnosis
+  - Updated setup docs (at minimum `docs/cursor-setup.md`) with a one-time `--refresh` guidance note after new releases
+  - Optional quick-check snippet in `README.md` for confirming active runtime package version on a dashboard port
+- **Acceptance Criteria:**
+  - [x] Troubleshooting docs include symptom/cause/fix for: uptime or behavior unchanged after upgrade
+  - Docs provide concrete commands to:
+    - [x] identify process listening on Web UI port
+    - [x] inspect active runtime version from that process
+    - [x] restart with `uvx --refresh --from mcpbridge-wrapper[webui] ...`
+  - [x] Recovery steps explicitly mention that multiple wrapper processes can coexist and mask upgrades
+  - [x] Guidance is validated against a local repro where an old process serves stale behavior and a refreshed process resolves it
+
+---
+
 ### Phase 11: Web UI UX Improvements
 
 **Intent:** Enhance the dashboard with better debugging tools, session awareness, theming, and keyboard-driven workflows.

Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md

@@ -148,3 +148,28 @@ Make sure Xcode Tools MCP is enabled in Xcode:
 2. Select **Intelligence**
 3. Toggle **Xcode Tools** ON
 4. Restart Cursor
+
+**"Web UI still shows old behavior after an upgrade"**
+
+If Cursor is configured with Web UI args and behavior looks stale after upgrading, force a one-time uvx refresh:
+
+```json
+{
+  "mcpServers": {
+    "xcode-tools": {
+      "command": "uvx",
+      "args": [
+        "--refresh",
+        "--from",
+        "mcpbridge-wrapper[webui]",
+        "mcpbridge-wrapper",
+        "--web-ui",
+        "--web-ui-port",
+        "8080"
+      ]
+    }
+  }
+}
+```
+
+Restart Cursor after saving config. Once verified, you can remove `--refresh` from args.

Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md

@@ -143,6 +143,49 @@ Then restart your MCP client.
 
 If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args.
 
+## Error: "Uptime still shows 1h 0m 0s" or behavior is unchanged after upgrade
+
+**Symptom:** You upgraded to a newer release, but dashboard behavior still matches an older version (for example uptime stays `1h 0m 0s`).
+
+**Cause:** A previously started wrapper process is still running from an older `uvx` cache environment. New installs do not replace already-running processes.
+
+**Diagnosis:**
+
+```bash
+# 1) Find the process serving your Web UI port
+PORT=8080
+PID=$(lsof -tiTCP:$PORT -sTCP:LISTEN | head -n1)
+ps -p "$PID" -o command=
+
+# 2) Print the mcpbridge-wrapper version used by that exact process
+PY=$(ps -p "$PID" -o command= | awk '{print $1}')
+"$PY" -c 'import importlib.metadata as m; print(m.version("mcpbridge-wrapper"))'
+```
+
+If the reported version is older than expected, you are connected to a stale runtime.
+
+**Recovery:**
+
+```bash
+# Stop the stale process
+kill "$PID"
+
+# Start with a refreshed uvx environment
+uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
+```
+
+Then reload the dashboard and verify uptime increases:
+
+```bash
+curl -s http://127.0.0.1:8080/api/metrics | jq .uptime_seconds
+sleep 2
+curl -s http://127.0.0.1:8080/api/metrics | jq .uptime_seconds
+```
+
+The second value should be larger.
+
+**Important:** Multiple wrapper processes can run at the same time (for different ports or restarts), which can mask upgrades. Always verify the version for the process bound to the port you are viewing.
+
 ## Tool Returns Empty Results
 
 **Symptom:** Tools execute but return no data.

Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md

@@ -66,6 +66,21 @@ With Web UI dashboard (optional — adds real-time monitoring at http://localhos
 }
 ```
 
+If you upgrade and want to confirm the currently running dashboard process version:
+
+```bash
+PORT=8080
+PID=$(lsof -tiTCP:$PORT -sTCP:LISTEN | head -n1)
+PY=$(ps -p "$PID" -o command= | awk '{print $1}')
+"$PY" -c 'import importlib.metadata as m; print(m.version("mcpbridge-wrapper"))'
+```
+
+If needed, do a one-time refresh start:
+
+```bash
+uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
+```
+
 Restart Cursor and you're done. For other clients or installation methods, read on.
 
 ### Python Environment Setup (Development)