fix(desktop): structured error_kind on chat_agent_error telemetry (#9342)

desktop/macos/Desktop/Sources/AnalyticsManager.swift

@@ -1,4 +1,4 @@
 import AppKit
 import Foundation
 import Sentry
 
@@ -634,11 +634,14 @@
   }
 
   /// Track when the Claude agent bridge fails to start or errors
-  func chatAgentError(error: String, rawError: String? = nil) {
+  func chatAgentError(error: String, rawError: String? = nil, errorKind: String? = nil) {
     var props: [String: Any] = ["error": error]
     if let raw = rawError, raw != error {
       props["raw_error"] = String(raw.prefix(500))
     }
+    if let errorKind {
+      props["error_kind"] = errorKind
+    }
     PostHogManager.shared.track("chat_agent_error", properties: props)
   }
 

desktop/macos/Desktop/Sources/Chat/AgentBridge.swift

@@ -553,6 +553,35 @@ enum BridgeError: LocalizedError {
     }
   }
 
+  /// Stable, low-cardinality category for `chat_agent_error` telemetry so the
+  /// opaque "bridge failed to start" bucket can be split into missing-install /
+  /// launch-failure / crash / provider-config buckets in PostHog (issue #9342).
+  static func telemetryKind(for error: Error) -> String {
+    if let bridgeError = error as? BridgeError {
+      switch bridgeError {
+      case .nodeNotFound: return "bridge.node_not_found"
+      case .bridgeScriptNotFound: return "bridge.script_not_found"
+      case .notRunning: return "bridge.not_running"
+      case .encodingError: return "bridge.encoding_error"
+      case .timeout: return "bridge.timeout"
+      case .processExited: return "bridge.process_exited"
+      case .outOfMemory: return "bridge.out_of_memory"
+      case .stopped: return "bridge.stopped"
+      case .restarting: return "bridge.restarting"
+      case .requestAlreadyActive: return "bridge.request_already_active"
+      case .agentError: return "bridge.agent_error"
+      case .agentRuntimeFailure: return "bridge.agent_runtime_failure"
+      case .quotaExceeded: return "bridge.quota_exceeded"
+      case .authMissing: return "bridge.auth_missing"
+      }
+    }
+    // Non-BridgeError launch failures (e.g. Process spawn errors) carry an
+    // NSError domain+code — POSIX ENOENT distinguishes a missing executable
+    // (install problem) from other launch failures. Bounded cardinality.
+    let nsError = error as NSError
+    return "\(nsError.domain).\(nsError.code)"
+  }
+
   private static func isSessionAuthenticationFailureMessage(_ message: String) -> Bool {
     let normalized = message.lowercased()
     if normalized.contains("invalid_token") || normalized.contains("please sign in") {

desktop/macos/Desktop/Sources/Providers/ChatProvider.swift

@@ -1,4 +1,4 @@
 import SwiftUI
 import Combine
 import CoreGraphics
 import GRDB
@@ -1384,7 +1384,11 @@
                 currentError = card
                 errorMessage = nil
             } else {
-                AnalyticsManager.shared.chatAgentError(error: "AI not available: bridge failed to start", rawError: rawError)
+                AnalyticsManager.shared.chatAgentError(
+                    error: "AI not available: bridge failed to start",
+                    rawError: rawError,
+                    errorKind: BridgeError.telemetryKind(for: error)
+                )
                 errorMessage = "AI not available: \(error.localizedDescription)"
             }
             return false
@@ -4342,7 +4346,11 @@
             } else {
                 rawError = "\(error)"
             }
-            AnalyticsManager.shared.chatAgentError(error: error.localizedDescription, rawError: rawError)
+            AnalyticsManager.shared.chatAgentError(
+                error: error.localizedDescription,
+                rawError: rawError,
+                errorKind: BridgeError.telemetryKind(for: error)
+            )
 
             // Track onboarding errors with full context
             if isOnboarding {

desktop/macos/Desktop/Tests/ChatErrorStateTests.swift

@@ -50,6 +50,29 @@ final class ChatErrorStateMappingTests: XCTestCase {
       BridgeError.quotaExceeded(plan: "free", unit: "msg", used: 100, limit: 100, resetAtUnix: nil)
     ))
   }
+
+  /// `chat_agent_error` telemetry categorization (issue #9342): the generic
+  /// "bridge failed to start" bucket must be split into distinct, stable
+  /// `error_kind` values so PostHog can tell missing-install / launch-failure /
+  /// crash / provider-config failures apart. Distinct causes → distinct kinds.
+  func testTelemetryKindDistinguishesFailureModes() {
+    XCTAssertEqual(BridgeError.telemetryKind(for: BridgeError.nodeNotFound), "bridge.node_not_found")
+    XCTAssertEqual(BridgeError.telemetryKind(for: BridgeError.bridgeScriptNotFound), "bridge.script_not_found")
+    XCTAssertEqual(BridgeError.telemetryKind(for: BridgeError.processExited), "bridge.process_exited")
+    XCTAssertEqual(BridgeError.telemetryKind(for: BridgeError.outOfMemory), "bridge.out_of_memory")
+    XCTAssertEqual(BridgeError.telemetryKind(for: BridgeError.agentError("boom")), "bridge.agent_error")
+
+    // Non-BridgeError launch failures (e.g. Process spawn ENOENT = missing
+    // executable) surface the NSError domain+code, not the opaque bucket.
+    let spawnError = NSError(domain: NSPOSIXErrorDomain, code: 2)
+    XCTAssertEqual(BridgeError.telemetryKind(for: spawnError), "\(NSPOSIXErrorDomain).2")
+
+    // A missing binary and a crash must NOT collapse to the same kind.
+    XCTAssertNotEqual(
+      BridgeError.telemetryKind(for: BridgeError.bridgeScriptNotFound),
+      BridgeError.telemetryKind(for: BridgeError.processExited)
+    )
+  }
 }
 
 final class ChatErrorStateTests: XCTestCase {