fix(desktop): don't report an unrelated service on 8080 as a running control plane

AbirAbbas · claude · AbirAbbas · commit 097d511ecca0 · 2026-07-13T10:38:27.000-04:00
checkControlPlane treated any HTTP 200 from {baseUrl}/health as
"healthy", so anything squatting on the popular default port lit the
dashboard green. Found live on Windows: an unrelated dev server answering
{"status":"alive"} on /health showed as a running control plane.

The probe now recognizes an AgentField control plane by its health
payload shape (status: healthy|unhealthy, per routes_core.go). Anything
else reachable on the port reports recognized: false with an explanatory
error, renders as a yellow "Another service is on this port" state, and
is excluded from the nodes cross-check so a foreign /api/v1/nodes
response cannot corrupt agent badges.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/desktop/src/main/agentfield.test.ts b/desktop/src/main/agentfield.test.ts
@@ -170,7 +170,7 @@ describe('checkControlPlane', () => {
     }
     const fetchImpl: FetchLike = async () => jsonResponse(body, 200)
     const result = await checkControlPlane('http://localhost:8080', fetchImpl)
-    expect(result).toEqual({ reachable: true, healthy: true, raw: body })
+    expect(result).toEqual({ reachable: true, recognized: true, healthy: true, raw: body })
   })
 
   // Contract: 503 with an unhealthy body still means reachable, just not healthy.
@@ -179,17 +179,46 @@ describe('checkControlPlane', () => {
     const fetchImpl: FetchLike = async () => jsonResponse(body, 503)
     const result = await checkControlPlane('http://localhost:8080', fetchImpl)
     expect(result.reachable).toBe(true)
+    expect(result.recognized).toBe(true)
     expect(result.healthy).toBe(false)
     expect(result.raw).toEqual(body)
   })
 
+  // Contract: a 200 from something that is NOT an AgentField control plane
+  // (default port 8080 is popular) must not read as healthy. Found live on
+  // Windows: an unrelated dev server answering {"status":"alive"} on /health
+  // lit the dashboard green.
+  it('rejects a foreign 200 /health payload as unrecognized', async () => {
+    const body = { status: 'alive', uptime_s: 3714 }
+    const fetchImpl: FetchLike = async () => jsonResponse(body, 200)
+    const result = await checkControlPlane('http://localhost:8080', fetchImpl)
+    expect(result.reachable).toBe(true)
+    expect(result.recognized).toBe(false)
+    expect(result.healthy).toBe(false)
+    expect(result.error).toContain('does not look like an AgentField control plane')
+  })
+
+  it('rejects a non-JSON 200 response as unrecognized', async () => {
+    const fetchImpl: FetchLike = async () =>
+      new Response('<html>hi</html>', { status: 200, headers: { 'content-type': 'text/html' } })
+    const result = await checkControlPlane('http://localhost:8080', fetchImpl)
+    expect(result.reachable).toBe(true)
+    expect(result.recognized).toBe(false)
+    expect(result.healthy).toBe(false)
+  })
+
   // Contract: network error / timeout -> not reachable, error captured.
   it('maps a rejected fetch to unreachable with an error message', async () => {
     const fetchImpl: FetchLike = async () => {
       throw new TypeError('fetch failed')
     }
     const result = await checkControlPlane('http://localhost:8080', fetchImpl)
-    expect(result).toEqual({ reachable: false, healthy: false, error: 'fetch failed' })
+    expect(result).toEqual({
+      reachable: false,
+      recognized: false,
+      healthy: false,
+      error: 'fetch failed'
+    })
   })
 
   it('probes {baseUrl}/health', async () => {
@@ -287,6 +316,27 @@ describe('getSnapshot', () => {
     expect(badges).toEqual({ 'pr-af': 'running', 'swe-af': 'stopped' })
   })
 
+  it('does not consult the nodes view of an unrecognized service on the port', async () => {
+    const home = await makeHome(REGISTRY_FIXTURE)
+    const requested: string[] = []
+    const fetchImpl: FetchLike = async (input) => {
+      requested.push(String(input))
+      // A foreign service that would answer BOTH endpoints with junk.
+      return jsonResponse({ status: 'alive', nodes: [] })
+    }
+
+    const snapshot = await getSnapshot({ homeDir: home, fetchImpl })
+
+    expect(snapshot.controlPlane.recognized).toBe(false)
+    // Badges fall back to registry statuses — the foreign 200 on /api/v1/nodes
+    // must not flip a running agent to unknown.
+    const badges = Object.fromEntries(
+      snapshot.registry.agents.map((a) => [a.name, a.badge])
+    )
+    expect(badges).toEqual({ 'pr-af': 'running', 'swe-af': 'stopped' })
+    expect(requested.some((url) => url.endsWith('/api/v1/nodes'))).toBe(false)
+  })
+
   it('reports an unreachable control plane and an absent registry gracefully', async () => {
     const home = await makeHome()
     const missing = path.join(home, 'nope')
diff --git a/desktop/src/main/agentfield.ts b/desktop/src/main/agentfield.ts
@@ -43,10 +43,14 @@ function errorMessage(err: unknown): string {
 
 /**
  * Probe GET {baseUrl}/health.
- *  - 200 {"status":"healthy",...}            -> { reachable: true,  healthy: true }
- *  - 503 {"status":"unhealthy",...}          -> { reachable: true,  healthy: false }
+ *  - 200 {"status":"healthy",...}   -> { reachable: true, recognized: true,  healthy: true }
+ *  - 503 {"status":"unhealthy",...} -> { reachable: true, recognized: true,  healthy: false }
  *    (an HTTP response — even 503 — still means the control plane is reachable)
- *  - network error / timeout (3s)            -> { reachable: false, healthy: false, error }
+ *  - any response whose body is not an AgentField health payload
+ *                                   -> { reachable: true, recognized: false, healthy: false, error }
+ *    (default port 8080 is popular — an unrelated dev server answering 200 on
+ *    /health must not light up the dashboard as a running control plane)
+ *  - network error / timeout (3s)   -> { reachable: false, recognized: false, healthy: false, error }
  */
 export async function checkControlPlane(
   baseUrl: string = DEFAULT_BASE_URL,
@@ -62,9 +66,20 @@ export async function checkControlPlane(
     } catch {
       raw = undefined
     }
-    return { reachable: true, healthy: res.ok, raw }
+    const status = isRecord(raw) && typeof raw.status === 'string' ? raw.status : undefined
+    const recognized = status === 'healthy' || status === 'unhealthy'
+    if (!recognized) {
+      return {
+        reachable: true,
+        recognized: false,
+        healthy: false,
+        raw,
+        error: `A service answered ${baseUrl}/health but does not look like an AgentField control plane — another app may be using the port.`
+      }
+    }
+    return { reachable: true, recognized: true, healthy: res.ok && status === 'healthy', raw }
   } catch (err) {
-    return { reachable: false, healthy: false, error: errorMessage(err) }
+    return { reachable: false, recognized: false, healthy: false, error: errorMessage(err) }
   }
 }
 
@@ -197,7 +212,9 @@ export async function getSnapshot(options: SnapshotOptions = {}): Promise<AgentF
     readInstalledAgents(options.homeDir)
   ])
 
-  const nodeIds = controlPlane.reachable
+  // Only cross-check against a recognized control plane; an unrelated service
+  // on the port must not influence the badges.
+  const nodeIds = controlPlane.recognized
     ? await fetchControlPlaneNodes(baseUrl, fetchImpl)
     : null
   const hasControlPlaneView = nodeIds !== null
diff --git a/desktop/src/renderer/src/components/ControlPlaneCard.tsx b/desktop/src/renderer/src/components/ControlPlaneCard.tsx
@@ -8,12 +8,15 @@ export function ControlPlaneCard({ controlPlane }: ControlPlaneCardProps) {
   let dotClass = 'gray'
   let label = 'Checking…'
   if (controlPlane) {
-    if (controlPlane.reachable && controlPlane.healthy) {
+    if (controlPlane.healthy) {
       dotClass = 'green'
       label = 'Running'
-    } else if (controlPlane.reachable) {
+    } else if (controlPlane.reachable && controlPlane.recognized) {
       dotClass = 'yellow'
       label = 'Reachable (unhealthy)'
+    } else if (controlPlane.reachable) {
+      dotClass = 'yellow'
+      label = 'Another service is on this port'
     } else {
       dotClass = 'red'
       label = 'Not reachable'
@@ -30,9 +33,7 @@ export function ControlPlaneCard({ controlPlane }: ControlPlaneCardProps) {
         <span className={`status-dot ${dotClass}`} aria-hidden="true" />
         <span className="status-label">{label}</span>
       </div>
-      {controlPlane && !controlPlane.reachable && controlPlane.error && (
-        <p className="muted small">{controlPlane.error}</p>
-      )}
+      {controlPlane?.error && <p className="muted small">{controlPlane.error}</p>}
     </section>
   )
 }
diff --git a/desktop/src/shared/types.ts b/desktop/src/shared/types.ts
@@ -5,11 +5,17 @@
 export interface ControlPlaneStatus {
   /** An HTTP response came back (any status code, including 503). */
   reachable: boolean
-  /** The health endpoint answered 200 (body reports "healthy"). */
+  /**
+   * The response body looks like an AgentField control plane health payload
+   * (status: "healthy" | "unhealthy"). False when some unrelated service is
+   * squatting on the port — its nodes view must not be trusted.
+   */
+  recognized: boolean
+  /** The health endpoint answered 200 with a body reporting "healthy". */
   healthy: boolean
   /** Raw JSON body of the health response, when one was parseable. */
   raw?: unknown
-  /** Network/timeout error message when unreachable. */
+  /** Network/timeout error when unreachable, or why the payload was rejected. */
   error?: string
 }
 
