feat: add bounded diagnostics and improve UX feedback

Ask and Execute guidance, Runtime state, live announcements, loading states,
retry paths, settings focus, and update failures now provide consistent and
accessible feedback across the desktop experience.

Add bounded redacted Desktop and Agent diagnostic logs, a read-only Agent
diagnostics command, and an explicit opt-in for attaching a small Desktop
diagnostic summary to in-app feedback. Diagnostics stay local by default and
the existing feedback v1 service contract remains compatible.

Release note: 新增可选桌面诊断反馈与 Agent 诊断导出，并统一 Ask/Execute 状态、错误恢复和无障碍反馈；诊断默认保留在本地，仅在用户明确勾选时附加桌面摘要。

src/main/remote-agent/remote-agent-connection-manager.test.ts

@@ -26,6 +26,9 @@ import {
   RemoteAgentConnectionManager,
   type RemoteAgentSshPool
 } from './remote-agent-connection-manager'
+import type {
+  DesktopDiagnosticFailureObserver
+} from '../desktop-diagnostics'
 
 class MemoryStateFile implements ControllerStateFile {
   value?: unknown
@@ -158,7 +161,8 @@ const installation = {
 function harness(
   connectGate?: Promise<void>,
   reconnectResumeGate?: Promise<void>,
-  idleTimeoutMs = 0
+  idleTimeoutMs = 0,
+  observeFailure?: DesktopDiagnosticFailureObserver
 ) {
   let currentTarget = target()
   const release = vi.fn()
@@ -206,6 +210,7 @@ function harness(
     controllerState: new ControllerStateStore(stateFile),
     goodBuddyVersion: '0.11.0',
     idleTimeoutMs,
+    observeFailure,
     connectTransport,
     createProtocolClient: () => {
       const client = new FakeProtocolClient(clients.length)
@@ -482,6 +487,27 @@ describe('RemoteAgentConnectionManager', () => {
     await test.manager.dispose()
   })
 
+  it('does not report acquisition canceled by its caller', async () => {
+    const observeFailure = vi.fn()
+    const test = harness(undefined, undefined, 0, observeFailure)
+    const controller = new AbortController()
+    const cancellation = new Error('caller canceled')
+    test.resolver.resolve.mockImplementationOnce(async () => {
+      controller.abort(cancellation)
+      throw cancellation
+    })
+
+    await expect(
+      test.manager.acquire(
+        'host-1',
+        installation,
+        controller.signal
+      )
+    ).rejects.toBe(cancellation)
+    expect(observeFailure).not.toHaveBeenCalled()
+    await test.manager.dispose()
+  })
+
   it('invalidates every connection for a Host without stopping its daemon', async () => {
     const test = harness()
     const lease = await test.manager.acquire('host-1', installation)
@@ -497,7 +523,8 @@ describe('RemoteAgentConnectionManager', () => {
     const gate = new Promise<void>((resolve) => {
       finishTransport = resolve
     })
-    const test = harness(gate)
+    const observeFailure = vi.fn()
+    const test = harness(gate, undefined, 0, observeFailure)
     const acquiring = test.manager.acquire('host-1', installation)
     await vi.waitFor(() =>
       expect(test.connectTransport).toHaveBeenCalledOnce()
@@ -512,6 +539,7 @@ describe('RemoteAgentConnectionManager', () => {
     })
     expect(test.clients[0]?.disposed).toBe(true)
     expect(test.release).toHaveBeenCalledOnce()
+    expect(observeFailure).not.toHaveBeenCalled()
     await test.manager.dispose()
   })
 
@@ -834,4 +862,46 @@ describe('RemoteAgentConnectionManager', () => {
       test.manager.acquire('host-1', installation)
     ).rejects.toMatchObject({ reason: 'shutdown' })
   })
+
+  it('reports classified connect and disconnect failures once', async () => {
+    const observeFailure = vi.fn()
+    const failed = harness(undefined, undefined, 0, observeFailure)
+    failed.connectTransport.mockRejectedValueOnce(
+      new Error('provider unavailable')
+    )
+
+    await expect(
+      failed.manager.acquire('host-1', installation)
+    ).rejects.toThrow()
+    expect(observeFailure).toHaveBeenCalledWith(
+      expect.objectContaining({
+        component: 'remote-agent',
+        stage: 'connect',
+        code: 'remote.connection.network'
+      })
+    )
+    await failed.manager.dispose()
+
+    observeFailure.mockClear()
+    const connected = harness(
+      undefined,
+      undefined,
+      0,
+      observeFailure
+    )
+    const lease = await connected.manager.acquire(
+      'host-1',
+      installation
+    )
+    connected.clients[0]!.transportClose()
+    expect(observeFailure).toHaveBeenCalledWith(
+      expect.objectContaining({
+        component: 'remote-agent',
+        stage: 'disconnect',
+        code: 'remote.connection.lost'
+      })
+    )
+    lease.release()
+    await connected.manager.dispose()
+  })
 })

src/main/remote-agent/remote-agent-connection-manager.ts

@@ -27,6 +27,9 @@ import {
   AgentProtocolClient,
   type AgentProtocolClientError
 } from './agent-protocol-client'
+import type {
+  DesktopDiagnosticFailureObserver
+} from '../desktop-diagnostics'
 import {
   ControllerStateStore,
   type ControllerAcpRecoveryBinding,
@@ -170,6 +173,9 @@ export class RemoteAgentConnectionManager {
   readonly #goodBuddyVersion: string
   readonly #idleTimeoutMs: number
   readonly #attachTimeoutMs: number
+  readonly #observeFailure:
+    | DesktopDiagnosticFailureObserver
+    | undefined
   readonly #identityKey = randomBytes(32)
   readonly #entries = new Map<string, ConnectionEntry>()
   readonly #hostConnectionStates = new Map<
@@ -192,6 +198,7 @@ export class RemoteAgentConnectionManager {
     createProtocolClient?: (
       transport: AgentAttachTransport
     ) => AgentProtocolClient
+    observeFailure?: DesktopDiagnosticFailureObserver
   }) {
     this.#resolver = options.resolver
     this.#sshPool = options.sshPool
@@ -206,6 +213,7 @@ export class RemoteAgentConnectionManager {
       options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS
     this.#attachTimeoutMs =
       options.attachTimeoutMs ?? DEFAULT_ATTACH_TIMEOUT_MS
+    this.#observeFailure = options.observeFailure
     if (
       this.#goodBuddyVersion.length < 1 ||
       Buffer.byteLength(this.#goodBuddyVersion, 'utf8') > 64
@@ -236,16 +244,30 @@ export class RemoteAgentConnectionManager {
     }
     signal?.throwIfAborted()
     const installation = validateInstallation(installationInput)
-    // One atomic resolver call supplies the complete current host target.
-    const target = await this.#resolver.resolve(hostId)
-    signal?.throwIfAborted()
-    if (target.host.id !== hostId) {
-      throw terminalError(
-        'Resolved SSH Host identity does not match the request',
-        'host-identity'
-      )
+    let target: SshConnectionPoolTarget
+    let identity: RemoteAgentConnectionIdentity
+    try {
+      // One atomic resolver call supplies the complete current host target.
+      target = await this.#resolver.resolve(hostId)
+      signal?.throwIfAborted()
+      if (target.host.id !== hostId) {
+        throw terminalError(
+          'Resolved SSH Host identity does not match the request',
+          'host-identity'
+        )
+      }
+      identity = this.#identity(target, installation)
+    } catch (error) {
+      const classified = classifyConnectionError(error)
+      if (!signal?.aborted) {
+        this.#reportFailure(
+          'connect',
+          `remote.connection.${classified.reason}`,
+          classified
+        )
+      }
+      throw error
     }
-    const identity = this.#identity(target, installation)
     let entry = this.#entries.get(identity.cacheKey)
     if (entry === undefined) {
       if (this.#entries.size >= MAXIMUM_CONNECTIONS) {
@@ -515,6 +537,13 @@ export class RemoteAgentConnectionManager {
       transport?.dispose()
       sshLease?.release()
       const classified = classifyConnectionError(error)
+      if (!isAbortCancellation(entry.controller.signal)) {
+        this.#reportFailure(
+          'connect',
+          `remote.connection.${classified.reason}`,
+          classified
+        )
+      }
       if (
         this.#entries.get(entry.key) === entry &&
         entry.connectionState !== 'disposed'
@@ -914,6 +943,11 @@ export class RemoteAgentConnectionManager {
       error
     )
     entry.connectionState = 'offline'
+    this.#reportFailure(
+      'disconnect',
+      'remote.connection.lost',
+      entry.failure
+    )
     this.#syncHostConnectionState(entry.hostId)
     active?.unsubscribeClose()
     active?.sshLease.release()
@@ -922,6 +956,23 @@ export class RemoteAgentConnectionManager {
     }
   }
 
+  #reportFailure(
+    stage: string,
+    code: string,
+    error: unknown
+  ): void {
+    try {
+      this.#observeFailure?.({
+        component: 'remote-agent',
+        stage,
+        code,
+        error
+      })
+    } catch {
+      // Diagnostics must not alter remote connection behavior.
+    }
+  }
+
   async #persistConnection(
     entry: ConnectionEntry,
     active: ActiveConnection,
@@ -1070,6 +1121,21 @@ export class RemoteAgentConnectionManager {
   }
 }
 
+function isAbortCancellation(signal: AbortSignal): boolean {
+  if (!signal.aborted) {
+    return false
+  }
+  const reason: unknown = signal.reason
+  if (typeof reason !== 'object' || reason === null) {
+    return true
+  }
+  try {
+    return !('name' in reason) || reason.name === 'AbortError'
+  } catch {
+    return true
+  }
+}
+
 function validateInstallation(
   input: RemoteAgentInstallationIdentity
 ): RemoteAgentInstallationIdentity {

src/main/remote-agent/remote-agent-services.ts

@@ -14,6 +14,9 @@ import {
   RemoteAgentConnectionManager,
   type RemoteAgentTargetResolver
 } from './remote-agent-connection-manager'
+import type {
+  DesktopDiagnosticFailureObserver
+} from '../desktop-diagnostics'
 
 const CONTROLLER_STATE_FILE_NAME = 'remote-agent-controller-state.json'
 
@@ -34,6 +37,7 @@ type RemoteAgentServiceFactories = {
     sshPool: SshConnectionPool
     controllerState: ControllerStateStore
     goodBuddyVersion: string
+    observeFailure?: DesktopDiagnosticFailureObserver
   }) => RemoteAgentConnectionManager
 }
 
@@ -45,6 +49,7 @@ export type RemoteAgentServicesOptions = {
   resourcesPath: string
   packaged: boolean
   controlPlanePackageInstaller: Buffer | string
+  observeFailure?: DesktopDiagnosticFailureObserver
   factories?: Partial<RemoteAgentServiceFactories>
 }
 
@@ -103,7 +108,8 @@ export class RemoteAgentServices {
       resolver: this.targetResolver,
       sshPool: this.sshPool,
       controllerState: this.controllerState,
-      goodBuddyVersion: options.goodBuddyVersion
+      goodBuddyVersion: options.goodBuddyVersion,
+      observeFailure: options.observeFailure
     })
   }