feat(048): eliminate remaining tray /api/v1/servers refetches

Spec 047 (PR #450, v0.29.4) eliminated the burst-storm refetch path
(servers.changed -> refetch). This PR addresses the residual: 5 other
call sites in the Swift tray that still hit /api/v1/servers, totaling
~8 GETs per 60 s at idle on a 30-server config.

All 5 sites now read SSE-driven appState.servers in place of fetching:

- CoreProcessManager case "status": no longer refetches on
  connected_count change. Inline stats are merged unconditionally;
  per-server state arrives via the spec 047 servers.changed payload
  within ~50 ms of any actual transition.

- refreshState (30 s periodic) drops the refreshServers() call.
  refreshActivity / refreshSessions / refreshTokenMetrics /
  refreshSecurityStatus stay (SSE doesn't cover those domains).

- refreshSecurityStatus's Docker fallback now reads
  appState.servers synchronously instead of issuing another GET.

- MCPProxyApp's 10 s server-refresh Timer is removed entirely.

- menuWillOpen no longer refetches on every tray click. The menu
  rebuilds from in-memory state only.

In their place: a single 5-minute Combine timer in MCPProxyApp.swift
calls a new CoreProcessManager.refreshServersForSafetyNet() — pure
defense-in-depth in case SSE drops events past the 256-event buffer.

Verification (specs/048-tray-refetch-elimination/verification/report.md)
on the same MCPProxy.app + 30-server scenario as spec 047:
  - 0 GETs / 60 s at idle (was ~8)
  - context7 disable propagates to tray menu in 1 s
  - context7 enable propagates in 2 s
  - 0 GETs during the entire toggle window

Spec, plan, research, data-model, quickstart, tasks all under
specs/048-tray-refetch-elimination/. No core / Go changes.
Backward-compatible with older cores (spec 047 fallback path retained).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: claude

CLAUDE.md

@@ -768,6 +768,8 @@ See `docs/prerelease-builds.md` for download instructions.
 - Paperclip's embedded Postgres (existing, port 54329); Synapbus DB (existing); no new storage in mcpproxy-go (045-paperclip-cockpit)
 - Go 1.24 (toolchain go1.24.10); Swift 5.9 (macOS 13+); TypeScript 5.9 / Vue 3.5 (frontend) + `go.etcd.io/bbolt` (existing), `go.uber.org/zap` (existing), `github.com/mark3labs/mcp-go` (existing). No new deps. (047-cpu-hotpath-fix)
 - BBolt (`~/.mcpproxy/config.db`) — read-only on the hot path; no schema change. (047-cpu-hotpath-fix)
+- Swift 5.9 (macOS 13+); Go 1.24 only for the verification harness, no Go changes in scope. + SwiftUI/AppKit (existing), Combine (existing for the periodic timer pattern). No new deps. (048-tray-refetch-elimination)
+- None. Pure in-memory state. (048-tray-refetch-elimination)
 
 ## Recent Changes
 - 001-update-version-display: Added Go 1.24 (toolchain go1.24.10)

native/macos/MCPProxy/MCPProxy/Core/CoreProcessManager.swift

@@ -500,24 +500,19 @@ actor CoreProcessManager {
     private func handleSSEEvent(_ event: SSEEvent) async {
         switch event.event {
         case "status":
-            // Status events contain inline stats.
-            // When connected count changes, re-fetch the full server list
-            // to get accurate counts (SSE stats can lag behind actual state).
+            // Status events contain inline stats. Spec 048: any change that
+            // would also flip connected_count emits a `servers.changed`
+            // event (delivered within ~50 ms by spec 047's coalescer) which
+            // already updates the per-server appState. Stat aggregates are
+            // updated unconditionally from the inline payload — no refetch.
             if let data = event.data.data(using: .utf8),
                let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
                let stats = json["upstream_stats"] as? [String: Any] {
-                let connected = stats["connected_servers"] as? Int ?? 0
                 let total = stats["total_servers"] as? Int ?? 0
                 let tools = stats["total_tools"] as? Int ?? 0
-                let oldConnected = await MainActor.run { appState.connectedCount }
-                // If counts changed, do a full server refresh for accuracy
-                if connected != oldConnected {
-                    await refreshServers()
-                } else {
-                    await MainActor.run {
-                        if appState.totalServers != total { appState.totalServers = total }
-                        if appState.totalTools != tools { appState.totalTools = tools }
-                    }
+                await MainActor.run {
+                    if appState.totalServers != total { appState.totalServers = total }
+                    if appState.totalTools != tools { appState.totalTools = tools }
                 }
             }
 
@@ -613,8 +608,10 @@ actor CoreProcessManager {
     }
 
     /// Fetch full state from the core and update appState.
+    /// Spec 048: dropped the per-tick refreshServers() call. The server list
+    /// is now SSE-driven (spec 047 servers.changed payload). MCPProxyApp
+    /// installs a separate 5-min safety-net timer for missed-event recovery.
     private func refreshState() async {
-        await refreshServers()
         await refreshActivity()
         await refreshSessions()
         await refreshTokenMetrics()
@@ -635,10 +632,12 @@ actor CoreProcessManager {
                 // if docker_isolation.enabled is true in the running config, treat as available.
                 let configEnabled = await MainActor.run { appState.totalServers > 0 }
                 if configEnabled {
-                    // Servers are connected — Docker must be working if isolation is enabled
-                    // Check via the status endpoint which shows connected servers in containers
-                    let servers = try? await apiClient.servers()
-                    let hasStdioServers = servers?.contains(where: { $0.connected && $0.protocol == "stdio" }) ?? false
+                    // Servers are connected — Docker must be working if isolation is enabled.
+                    // Spec 048: appState.servers is SSE-fed, so read it directly instead
+                    // of issuing another GET /api/v1/servers on every periodic refresh.
+                    let hasStdioServers = await MainActor.run {
+                        appState.servers.contains(where: { $0.connected && $0.protocol == "stdio" })
+                    }
                     await MainActor.run {
                         appState.dockerAvailable = hasStdioServers || dockerOK
                     }
@@ -678,6 +677,14 @@ actor CoreProcessManager {
         }
     }
 
+    /// Spec 048: long-cadence safety-net wrapper around `refreshServers`.
+    /// Called by a 5-minute Combine timer in `MCPProxyApp` to guard against
+    /// missed `servers.changed` SSE events. Separate name documents intent —
+    /// this is *not* the on-demand refresh path (that's been retired).
+    func refreshServersForSafetyNet() async {
+        await refreshServers()
+    }
+
     /// Fetch recent activity and update appState.
     private func refreshActivity() async {
         guard let apiClient else { return }

native/macos/MCPProxy/MCPProxy/MCPProxyApp.swift

@@ -97,16 +97,15 @@ final class AppController: NSObject, NSApplicationDelegate, NSWindowDelegate, NS
             }
             .store(in: &cancellables)
 
-        // Periodic server refresh every 10s to keep health/action data current
-        Timer.publish(every: 10, on: .main, in: .common)
+        // Spec 048: dropped the 10 s server-refresh timer. The server list is
+        // now SSE-driven via the spec 047 `servers.changed` payload — appState
+        // updates within ~50 ms of any state transition with zero round trip.
+        // The safety-net below covers the rare case where SSE drops events.
+        Timer.publish(every: 300, on: .main, in: .common)   // 5 minutes
             .autoconnect()
             .sink { [weak self] _ in
-                guard let self, let client = self.appState.apiClient else { return }
-                Task {
-                    if let servers = try? await client.servers() {
-                        await self.appState.updateServers(servers)
-                    }
-                }
+                guard let self, let core = self.coreManager else { return }
+                Task { await core.refreshServersForSafetyNet() }
             }
             .store(in: &cancellables)
 
@@ -166,17 +165,9 @@ final class AppController: NSObject, NSApplicationDelegate, NSWindowDelegate, NS
     // MARK: - NSMenuDelegate
 
     func menuWillOpen(_ menu: NSMenu) {
-        // Fetch fresh server data before building the menu
-        // This ensures health.action (login/restart) is current
-        if let client = appState.apiClient {
-            Task {
-                if let servers = try? await client.servers() {
-                    await appState.updateServers(servers)
-                    await MainActor.run { rebuildMenu() }
-                }
-            }
-        }
-        // Build with current data immediately (async fetch updates it shortly after)
+        // Spec 048: dropped the per-click `client.servers()` fetch. appState
+        // is fed by SSE (spec 047), so it's already current within ~50 ms of
+        // the last upstream state change. Rebuild from in-memory state only.
         rebuildMenu()
     }
 

specs/048-tray-refetch-elimination/data-model.md

@@ -0,0 +1,43 @@
+# Data Model — Tray Refetch Elimination
+
+No persistent storage changes. No new `appState` fields. No new types. Pure refactor of existing methods.
+
+## Existing types touched
+
+| Type | File | Change |
+|---|---|---|
+| `CoreProcessManager` | `Core/CoreProcessManager.swift` | Modify `handleSSEEvent` (case `"status"`), `refreshState`, `refreshSecurityStatus`. Add nothing. |
+| `AppDelegate` (or whatever holds the Combine cancellables in `MCPProxyApp.swift`) | `MCPProxyApp.swift` | Drop the 10 s server-refresh timer. Drop the `menuWillOpen` server fetch. Add a 5 min safety-net timer. |
+| `AppState` | `State/AppState.swift` | No change. `appState.servers` is already the canonical state and is fed by SSE. |
+
+## New: safety-net timer
+
+Lives on the same `cancellables: Set<AnyCancellable>` set already used by the app-level coordinator (`MCPProxyApp.swift`):
+
+```swift
+// MCPProxyApp.swift — replaces the existing 10 s timer block
+//
+// Spec 048: SSE-driven appState.servers is authoritative. We keep one
+// long-cadence safety-net refresh in case SSE drops events past the
+// 256-event buffer or the runtime momentarily forgets to emit.
+Timer.publish(every: 300, on: .main, in: .common)   // 5 minutes
+    .autoconnect()
+    .sink { [weak self] _ in
+        guard let self, let core = self.coreManager else { return }
+        Task { await core.refreshServersForSafetyNet() }
+    }
+    .store(in: &cancellables)
+```
+
+`refreshServersForSafetyNet()` is a tiny new method on `CoreProcessManager` that does exactly what the existing private `refreshServers()` does — separate name purely so future readers don't confuse the safety-net path with the on-demand path. Internally it just calls `refreshServers()`.
+
+## Removed lifecycle hooks
+
+- `MCPProxyApp.swift:101-110` — the 10 s `Timer.publish` that called `client.servers()`. Replaced by the safety-net above.
+- `MCPProxyApp.swift:172-178` — the inline `client.servers()` fetch inside `menuWillOpen`. The function reduces to `rebuildMenu()`.
+
+## Modified lifecycle hooks
+
+- `CoreProcessManager.swift:514-515` — `case "status":` no longer calls `refreshServers()`. The branch becomes a stat-update only.
+- `CoreProcessManager.swift:617` — `refreshState()` drops the `await refreshServers()` call. The other periodic refreshes stay.
+- `CoreProcessManager.swift:640` — `refreshSecurityStatus()` reads `appState.servers` instead of fetching.

specs/048-tray-refetch-elimination/plan.md

@@ -0,0 +1,102 @@
+# Implementation Plan: Eliminate Remaining `/api/v1/servers` Refetches in macOS Tray
+
+**Branch**: `048-tray-refetch-elimination` | **Date**: 2026-05-08 | **Spec**: [`spec.md`](./spec.md)
+**Input**: [`specs/048-tray-refetch-elimination/spec.md`](./spec.md)
+
+## Summary
+
+Remove the 5 remaining `/api/v1/servers` refetch sites in the macOS tray. SSE-driven `appState.servers` (delivered by spec 047) is already authoritative; replace each refetch with an in-memory read or drop it entirely. Add one long-cadence (5 min) safety-net timer for missed-event resilience. Net result: tray-driven `/api/v1/servers` GETs at idle drop from ~8 / 60 s to ≤ 1 / 60 s.
+
+## Technical Context
+
+**Language/Version**: Swift 5.9 (macOS 13+); Go 1.24 only for the verification harness, no Go changes in scope.
+**Primary Dependencies**: SwiftUI/AppKit (existing), Combine (existing for the periodic timer pattern). No new deps.
+**Storage**: None. Pure in-memory state.
+**Testing**: XCTest (Swift). Live reproduction harness from spec 047 (`/Applications/MCPProxy.app` swap-in).
+**Target Platform**: macOS 13+ (Personal edition).
+**Project Type**: Native macOS tray app subtree of the multi-target repo.
+**Performance Goals**: ≤ 1 `/api/v1/servers` GET per 60 s wall at idle (down from ~8). UI reactivity unchanged (≤ 50 ms from SSE event to visible update).
+**Constraints**: No core / Go changes. No SSE contract change. No user-visible behavior change. Must remain backward-compatible with older cores (notify-only `servers.changed` fallback already handled by spec 047).
+**Scale/Scope**: 5 call sites across 2 Swift files (`CoreProcessManager.swift`, `MCPProxyApp.swift`). One new Combine timer.
+
+## Constitution Check
+
+| Principle | Status | Notes |
+|---|---|---|
+| **I. Performance at Scale** | Reinforced | Drops residual idle CPU drag from the macOS client side; complements spec 047 server-side wins. |
+| **II. Actor-Based Concurrency** | Aligned | All refactors stay within existing `MainActor` / `Task` patterns. No new shared mutable state. |
+| **III. Configuration-Driven Architecture** | Aligned | The 5-minute safety-net cadence can be hard-coded; if user feedback ever asks for tuning, surface as a config key in a follow-up. |
+| **IV. Security by Default** | No regression | No auth surface change. No new permissions. No data crossing trust boundaries. |
+| **V. TDD** | Required | One failing XCTest per site change; see `tasks.md`. |
+| **VI. Documentation Hygiene** | Aligned | Spec, plan, tasks, research, quickstart, verification all committed under `specs/048-tray-refetch-elimination/`. |
+
+No violations. Complexity Tracking is empty.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/048-tray-refetch-elimination/
+├── spec.md
+├── plan.md                 ← this file
+├── research.md             ← Phase 0
+├── data-model.md           ← Phase 1
+├── quickstart.md           ← Phase 1
+├── tasks.md                ← Phase 2 (speckit.tasks)
+└── verification/
+    ├── http_log_idle.txt   ← /api/v1/servers GETs over 60 s idle
+    └── report.md
+```
+
+(No `contracts/` directory — this is a client-only refactor with no API change.)
+
+### Source Code
+
+```text
+native/macos/MCPProxy/MCPProxy/
+├── Core/CoreProcessManager.swift   ← sites 1, 2, 3 + the safety-net hook
+└── MCPProxyApp.swift               ← sites 4, 5
+
+native/macos/MCPProxy/MCPProxyTests/
+└── SSEHandlerTests.swift           ← extend with 6 new tests (one per site + safety-net)
+
+specs/048-tray-refetch-elimination/
+└── verification/                   ← post-fix http.log GET counts
+```
+
+**Structure Decision**: Pure Swift refactor; the file layout above is the entirety of the change set.
+
+## Phase 0: Research (`research.md`)
+
+All decisions resolved during spec drafting on 2026-05-08. Key calls captured in `research.md`:
+- 5-minute safety-net interval (chosen over 1 / 10 / 30 minutes).
+- Approach for `refreshSecurityStatus` Docker fallback (read `appState.servers` synchronously).
+- `menuWillOpen` strategy (drop refetch entirely; rely on appState).
+- How to handle "tray just opened, appState empty" race (existing initial fetch on `connect` covers it).
+
+## Phase 1: Design & Contracts
+
+- **`data-model.md`** — declares only the new safety-net timer reference held on the app-level coordinator. No persistent storage.
+- **No `contracts/` directory** — this PR doesn't change any API.
+- **`quickstart.md`** — exact reproduction recipe for the live verification (build tray, swap into app bundle, launch, watch `http.log`).
+- **Agent context update** — runs at the end via `.specify/scripts/bash/update-agent-context.sh claude`.
+
+## Phase 2: Tasks (`tasks.md`)
+
+Generated by `/speckit.tasks` from this plan. Each site change is preceded by a failing XCTest.
+
+## Risks (mirrored from spec)
+
+See [`spec.md`](./spec.md) "Risks & Mitigations". No new risks identified during planning.
+
+## Out of Scope
+
+- Replacing `refreshActivity` / `refreshTokenMetrics` / `refreshSessions` periodics (separate spec; needs SSE design for those domains).
+- Investigating whether `refreshSecurityStatus`'s Docker check could itself become SSE-driven (separate spec).
+- Adding a config key for the safety-net cadence (surface only if user feedback asks).
+- Web UI changes (already covered by spec 047).
+
+## Complexity Tracking
+
+(empty — no Constitution gate violations)

specs/048-tray-refetch-elimination/quickstart.md

@@ -0,0 +1,68 @@
+# Quickstart — Tray Refetch Elimination
+
+## Build
+
+```bash
+cd native/macos/MCPProxy
+SDK=$(xcrun --sdk macosx --show-sdk-path)
+swiftc -target arm64-apple-macosx13.0 -sdk "$SDK" -module-name MCPProxy -emit-executable -O \
+  -o /tmp/MCPProxy-048 \
+  $(find MCPProxy -name "*.swift" -not -path "*/Tests/*" | sort | tr '\n' ' ')
+```
+
+## Run XCTests
+
+```bash
+# From the MCPProxy package root
+swift test --target MCPProxyTests --filter "SSEHandler|SafetyNet"
+```
+
+## Live verification — count `/api/v1/servers` GETs at idle
+
+Reproduces the spec 047 harness with the swap-in bundle. Replace the tray binary inside a clone of `/Applications/MCPProxy.app`, launch, watch `http.log`.
+
+```bash
+pkill -f "MCPProxy-048" 2>/dev/null
+rm -rf /tmp/MCPProxy-048.app
+cp -R /Applications/MCPProxy.app /tmp/MCPProxy-048.app
+cp /tmp/MCPProxy-048 /tmp/MCPProxy-048.app/Contents/MacOS/MCPProxy
+codesign --force --deep --sign - /tmp/MCPProxy-048.app
+open /tmp/MCPProxy-048.app
+
+# Wait for steady state
+until curl -sf -H "X-API-Key: $(jq -r .api_key ~/.mcpproxy/mcp_config.json)" http://127.0.0.1:8080/api/v1/status >/dev/null; do sleep 1; done
+sleep 30   # let the tray finish startup fetches
+
+# Sample 60 s of idle traffic
+START=$(date +%s)
+NOW=$START
+while [ $((NOW-START)) -lt 60 ]; do sleep 5; NOW=$(date +%s); done
+
+LOG=~/Library/Logs/mcpproxy/http.log
+COUNT=$(grep '"path": "/api/v1/servers"' "$LOG" | awk -F'|' '{print $1}' | awk '{print $1}' | awk -v START=$(date -v-60S +%FT%T) '$0 >= START' | wc -l | tr -d ' ')
+echo "GET /api/v1/servers in last 60 s of idle: $COUNT"
+```
+
+**Acceptance**: `$COUNT` should be `0` or `1` (the latter only if the test happened to span a 5-minute safety-net boundary). Before this PR: ~8.
+
+## Live verification — UI reactivity unchanged
+
+Use the same `mcpproxy-ui-test` MCP harness from spec 047:
+
+```bash
+BUNDLE=com.smartmcpproxy.mcpproxy
+K=$(jq -r .api_key ~/.mcpproxy/mcp_config.json)
+
+# Toggle a server, observe the tray reacting via SSE
+curl -H "X-API-Key: $K" -X POST http://127.0.0.1:8080/api/v1/servers/context7/disable
+sleep 2
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_menu_items","arguments":{"path":["Servers (30)"]}}}' \
+  | /tmp/mcpproxy-ui-test --bundle-id "$BUNDLE" 2>/dev/null \
+  | grep '^{' | head -1 \
+  | jq -r '.result.content[0].text' \
+  | jq '.items[] | select(.title | test("context7"; "i")) | .children[0:3]'
+```
+
+Expected: `Disabled / Enable` within 2 s. Re-enable → `Connected (2 tools) / Disable` within 5 s.
+
+Same as spec 047, but the verification now also asserts that no `/api/v1/servers` GET appeared in `http.log` during the toggle (only the SSE-driven update path is exercised).