mac: add attach-only gateway toggle

apps/macos/Sources/Clawdis/AppState.swift

@@ -161,6 +161,14 @@ final class AppState: ObservableObject {
         didSet { self.ifNotPreview { UserDefaults.standard.set(self.webChatPort, forKey: webChatPortKey) } }
     }
 
+    @Published var attachExistingGatewayOnly: Bool {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.attachExistingGatewayOnly, forKey: attachExistingGatewayOnlyKey)
+            }
+        }
+    }
+
     @Published var remoteTarget: String {
         didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteTarget, forKey: remoteTargetKey) } }
     }
@@ -238,6 +246,7 @@ final class AppState: ObservableObject {
         self.webChatSwiftUIEnabled = UserDefaults.standard.object(forKey: webChatSwiftUIEnabledKey) as? Bool ?? false
         let storedPort = UserDefaults.standard.integer(forKey: webChatPortKey)
         self.webChatPort = storedPort > 0 ? storedPort : 18788
+        self.attachExistingGatewayOnly = UserDefaults.standard.bool(forKey: attachExistingGatewayOnlyKey)
 
         if !self.isPreview {
             Task.detached(priority: .utility) { [weak self] in
@@ -353,6 +362,7 @@ extension AppState {
         state.remoteTarget = "user@example.com"
         state.remoteIdentity = "~/.ssh/id_ed25519"
         state.remoteProjectRoot = "~/Projects/clawdis"
+        state.attachExistingGatewayOnly = false
         return state
     }
 }
@@ -380,6 +390,10 @@ enum AppStateStore {
         let stored = UserDefaults.standard.integer(forKey: webChatPortKey)
         return stored > 0 ? stored : 18788
     }
+
+    static var attachExistingGatewayOnly: Bool {
+        UserDefaults.standard.bool(forKey: attachExistingGatewayOnlyKey)
+    }
 }
 
 extension AppState {

apps/macos/Sources/Clawdis/Constants.swift

@@ -28,6 +28,7 @@ let webChatSwiftUIEnabledKey = "clawdis.webChatSwiftUIEnabled"
 let webChatPortKey = "clawdis.webChatPort"
 let modelCatalogPathKey = "clawdis.modelCatalogPath"
 let modelCatalogReloadKey = "clawdis.modelCatalogReload"
+let attachExistingGatewayOnlyKey = "clawdis.gateway.attachExistingOnly"
 let heartbeatsEnabledKey = "clawdis.heartbeatsEnabled"
 let voiceWakeSupported: Bool = ProcessInfo.processInfo.operatingSystemVersion.majorVersion >= 26
 let cliHelperSearchPaths = ["/usr/local/bin", "/opt/homebrew/bin"]

apps/macos/Sources/Clawdis/DebugSettings.swift

@@ -23,6 +23,7 @@ struct DebugSettings: View {
     @State private var portKillStatus: String?
     @State private var pendingKill: DebugActions.PortListener?
     @AppStorage(webChatSwiftUIEnabledKey) private var webChatSwiftUIEnabled: Bool = false
+    @AppStorage(attachExistingGatewayOnlyKey) private var attachExistingGatewayOnly: Bool = false
 
     var body: some View {
         ScrollView(.vertical) {
@@ -57,6 +58,9 @@ struct DebugSettings: View {
                             .foregroundStyle(.secondary)
                     }
                 }
+                Toggle("Only attach to existing gateway (don’t spawn locally)", isOn: self.$attachExistingGatewayOnly)
+                    .toggleStyle(.switch)
+                    .help("When enabled in local mode, the mac app will only connect to an already-running gateway and will not start one itself.")
                 VStack(alignment: .leading, spacing: 4) {
                     Text("Gateway stdout/stderr")
                         .font(.caption.weight(.semibold))

apps/macos/Sources/Clawdis/GatewayProcessManager.swift

@@ -112,6 +112,14 @@ final class GatewayProcessManager: ObservableObject {
             if await self.attachExistingGatewayIfAvailable() {
                 return
             }
+            // Respect debug toggle: only attach, never spawn, when enabled.
+            if AppStateStore.attachExistingGatewayOnly {
+                await MainActor.run {
+                    self.status = .stopped
+                    self.appendLog("[gateway] attach-only enabled; not spawning local gateway\n")
+                }
+                return
+            }
             await self.spawnGateway()
         }
     }

apps/macos/Sources/Clawdis/Utilities.swift

@@ -495,6 +495,10 @@ enum CommandResolver {
             projectRoot: projectRoot)
     }
 
+    static var attachExistingGatewayOnly: Bool {
+        UserDefaults.standard.bool(forKey: attachExistingGatewayOnlyKey)
+    }
+
     static func connectionModeIsRemote() -> Bool {
         self.connectionSettings().mode == .remote
     }