From fe984e79b4808cf54c353d6f1de34a92b1173483 Mon Sep 17 00:00:00 2001
From: Jinwoo-H <jinwoo0825@gmail.com>
Date: Wed, 8 Jul 2026 18:03:33 -0400
Subject: [PATCH] Show host connection state for setup-needed targets

Co-authored-by: Orca <help@stably.ai>
---
 .../lib/project-host-setup-options.test.ts    | 29 ++++++++++++++++++-
 .../src/lib/project-host-setup-options.ts     | 26 +++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/src/renderer/src/lib/project-host-setup-options.test.ts b/src/renderer/src/lib/project-host-setup-options.test.ts
index e45e4ed8e8c..75efcc95083 100644
--- a/src/renderer/src/lib/project-host-setup-options.test.ts
+++ b/src/renderer/src/lib/project-host-setup-options.test.ts
@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { getExecutionHostLabel, type ExecutionHostId } from '../../../shared/execution-host'
-import type { ExecutionHostRegistryEntry } from '../../../shared/execution-host-registry'
+import type {
+  ExecutionHostHealth,
+  ExecutionHostRegistryEntry
+} from '../../../shared/execution-host-registry'
 import {
   PROJECT_HOST_SETUP_RUNTIME_CAPABILITY,
   WORKSPACE_RUN_CONTEXT_RUNTIME_CAPABILITY
@@ -216,6 +219,30 @@ describe('buildProjectHostSetupOptions', () => {
     ])
   })
 
+  it.each([
+    ['connecting' as const, 'Connecting to host'],
+    ['disconnected' as const, 'Connect this host to set up projects'],
+    ['error' as const, 'Host connection needs attention']
+  ])(
+    'marks %s hosts unavailable before project setup guidance',
+    (health: ExecutionHostHealth, detail: string) => {
+      const options = buildProjectHostSetupOptions({
+        projectId: 'project-1',
+        eligibleRepos: [repo('local-repo')],
+        hosts: [host('local'), host('ssh:builder', { label: 'Builder', health })],
+        projectHostSetups: [setup('local', 'project-1', 'local', 'local-repo')]
+      })
+
+      expect(options.at(-1)).toMatchObject({
+        id: 'needs-setup:ssh:builder',
+        kind: 'needs-setup',
+        label: 'Builder',
+        detail,
+        isAvailable: false
+      })
+    }
+  )
+
   it('shows pending setup status for known hosts with non-ready setup metadata', () => {
     const options = buildProjectHostSetupOptions({
       projectId: 'project-1',
diff --git a/src/renderer/src/lib/project-host-setup-options.ts b/src/renderer/src/lib/project-host-setup-options.ts
index d173b094bc3..2f7a5790dbe 100644
--- a/src/renderer/src/lib/project-host-setup-options.ts
+++ b/src/renderer/src/lib/project-host-setup-options.ts
@@ -188,6 +188,15 @@ function getHostSetupAvailability(host: ExecutionHostRegistryEntry): {
       detail: 'Orca server version is incompatible'
     }
   }
+  // Why: disconnected hosts cannot confirm project setup or runtime capabilities,
+  // so connection state needs to win over setup guidance.
+  const healthUnavailableDetail = getHostHealthUnavailableDetail(host.health)
+  if (healthUnavailableDetail) {
+    return {
+      isAvailable: false,
+      detail: healthUnavailableDetail
+    }
+  }
   if (host.kind === 'runtime') {
     if (!host.capabilities) {
       return {
@@ -211,6 +220,23 @@ function getHostSetupAvailability(host: ExecutionHostRegistryEntry): {
   }
 }
 
+function getHostHealthUnavailableDetail(
+  health: ExecutionHostRegistryEntry['health']
+): string | null {
+  switch (health) {
+    case 'connecting':
+      return 'Connecting to host'
+    case 'disconnected':
+      return 'Connect this host to set up projects'
+    case 'error':
+      return 'Host connection needs attention'
+    case 'available':
+    case 'blocked':
+    case 'local':
+      return null
+  }
+}
+
 function getPendingSetupDetail(setup: ProjectHostSetup): string {
   switch (setup.setupState) {
     case 'not-set-up':