Merge pull request #210 from ScriptedAlchemy/codex/cursor-integration-hardening

Harden Cursor MCP integration: degraded serve mode + doctor log diagnostics

Author: ScriptedAlchemy

CHANGELOG.md

@@ -9,8 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **`serve` no longer exits when project resolution fails at startup** — MCP hosts (Cursor especially) never retry a failed server spawn, so one startup exit over a recoverable config problem (uninitialized project, ambiguous global fallback, bad `--path`) turned every later tool call in the session into "Timed out waiting for connection". `serve` now stays alive in a degraded mode: it completes the MCP handshake, lists the real tools, and answers each tool call with an actionable error naming the failure, the fix, and the `tracedecay tool …` CLI fallback. It rechecks the project on every tool call and recovers in-session once `tracedecay init` (or a corrected path) makes resolution succeed — no server toggle or window reload needed.
 - **`serve` now tolerates a literal unexpanded `--path ${workspaceFolder}`** — Cursor's headless agent-session MCP scopes spawn the plugin's serve command without expanding the template variable and never retry the failed scope, which surfaced as "Timed out waiting for connection" on every tool call. `serve` now discards an unexpanded `${...}` template value with a stderr warning and falls back to project discovery where possible, requiring a unique registered project when discovery reaches the global registry in this mode. Rationale and details in `cursor-plugin/README.md`.
 
+### Added
+
+- **`tracedecay doctor --agent cursor` now diagnoses dead Cursor MCP scopes** — best-effort scan of Cursor's recent MCP logs for tracedecay spawn failures (literal unexpanded `${workspaceFolder}` paths, `Connection failed: MCP error -32000`, degraded-mode notices) with concrete remediation ("toggle the MCP server in Cursor Settings → MCP or reload the window"), plus a plugin-bundle-version-vs-binary-version staleness check that points at `tracedecay update-plugin`.
+
 ## [0.0.23](https://github.com/ScriptedAlchemy/tracedecay/compare/v0.0.22...v0.0.23) - 2026-07-02
 
 ### Other

cursor-plugin/README.md

@@ -180,6 +180,34 @@ Notes:
 - Entries from per-user and per-repo files are concatenated; allowlists are a
   convenience, not a security boundary.
 
+## Troubleshooting a dead MCP scope
+
+Cursor spawns MCP servers with the user home directory as the working
+directory, and it **never retries a failed MCP server**: if the `tracedecay
+serve` process exits at startup (for example when a headless agent scope
+passes a literal, unexpanded `${workspaceFolder}`), every later tool call in
+that session reports "Timed out waiting for connection" until you toggle the
+server or reload the window.
+
+Two layers of defense ship with this plugin:
+
+- `tracedecay serve` does not exit when project resolution fails at startup.
+  It completes the MCP handshake and answers tool calls with an actionable
+  error naming the failure and the fix; it rechecks the project on every tool
+  call and recovers automatically once `tracedecay init` (or a corrected
+  `--path`) makes resolution succeed.
+- `tracedecay doctor --agent cursor` scans Cursor's recent MCP logs
+  (`~/.config/Cursor/logs` on Linux, `~/Library/Application Support/Cursor/logs`
+  on macOS, `%APPDATA%\Cursor\logs` on Windows) for tracedecay spawn failures —
+  literal `${workspaceFolder}` errors, `Connection failed: MCP error -32000`,
+  degraded-mode notices — and checks that the installed plugin bundle version
+  matches the binary.
+
+If a scope has already failed: fix the cause (usually `tracedecay init` in the
+project, or upgrading a stale plugin with `tracedecay update-plugin`), then
+toggle the tracedecay MCP server in Cursor Settings → MCP or reload the Cursor
+window.
+
 ## Known limitations
 
 - **Cloud agents:** plugin `sessionStart`, `sessionEnd`, `beforeSubmitPrompt`,

src/agents/cursor.rs

@@ -109,6 +109,7 @@ impl AgentIntegration for CursorIntegration {
             );
         }
         doctor_check_session_ingest(dc, &ctx.project_path);
+        super::cursor_diagnostics::report_cursor_mcp_log_findings(dc, &ctx.home);
     }
 
     fn is_detected(&self, home: &Path) -> bool {
@@ -828,6 +829,11 @@ fn doctor_check_plugin(dc: &mut DoctorCounters, home: &Path) {
             manifest_path.display()
         ));
     }
+    if let Some(message) =
+        super::cursor_diagnostics::plugin_version_staleness(&manifest, env!("CARGO_PKG_VERSION"))
+    {
+        dc.warn(&message);
+    }
     doctor_check_plugin_mcp(dc, &plugin_dir.join("mcp.json"));
     doctor_check_plugin_hooks(dc, &plugin_dir.join("hooks/hooks.json"));
     doctor_check_plugin_rule(dc, &plugin_dir.join("rules/tracedecay.mdc"));