fix: keep UDS peer failures structured

CodeRabbit and Claude cross-review identified that timeout and raw peer connection failures should share one observable error contract. UDS peer failures now use UdsPeerConnectionError consistently, and connectToPeer hands the socket lifecycle back to the caller after a successful connection instead of retaining an internal timeout or error listener.

The tests cover the real socket paths with capability files, timeout behavior, connection failure structure, post-connect listener handoff, AgentSummary rescheduling observations, and platform-specific mailbox directory errno handling.

Constraint: Preserve the 5000ms production timeout default while allowing tests to exercise timeout paths quickly.

Rejected: Suppress CodeRabbit warnings in tests | would hide the real timeout/error contract gap.

Rejected: Keep connectToPeer post-connect error listener | it would silently swallow caller-owned socket errors.

Confidence: high

Scope-risk: narrow

Directive: Keep UDS send/connect timeout and socket-error paths on the same structured peer error contract.

Tested: bun test src/utils/__tests__/udsMessaging.test.ts src/services/AgentSummary/__tests__/agentSummary.test.ts src/utils/__tests__/teammateMailbox.test.ts

Tested: bunx tsc --noEmit --pretty false

Tested: bun run lint

Tested: bun run test:all

Tested: bun test --coverage --coverage-reporter lcov --coverage-dir coverage

Tested: bun run build

Tested: bun run build:vite

Tested: omx ask claude simplify review artifact .omx/artifacts/claude-review-only-cross-check-for-pr-374-on-branch-codex-codecov-r-2026-04-27T08-17-47-309Z.md

Tested: omx ask claude security review artifact .omx/artifacts/claude-security-review-cross-check-for-pr-374-current-working-tree--2026-04-27T08-26-54-079Z.md

Not-tested: GitHub-hosted CodeRabbit refresh until pushed.

src/services/AgentSummary/__tests__/agentSummary.test.ts

@@ -161,9 +161,7 @@ describe('startAgentSummarization', () => {
 
     expect(forkCalls).toEqual([])
     expect(updateCalls).toEqual([])
-    expectDebugLogContaining(
-      '[AgentSummary] Skipping summary for task-1: no bounded context available',
-    )
+    expectDebugLogContaining('no bounded context available')
   })
 
   test('skips summarization before building context when transcript is too short', async () => {
@@ -175,9 +173,7 @@ describe('startAgentSummarization', () => {
 
     expect(forkCalls).toEqual([])
     expect(updateCalls).toEqual([])
-    expectDebugLogContaining(
-      '[AgentSummary] Skipping summary for task-1: not enough messages (2)',
-    )
+    expectDebugLogContaining('not enough messages (2)')
   })
 
   test('skips and reschedules while poor mode is active', async () => {
@@ -192,7 +188,7 @@ describe('startAgentSummarization', () => {
 
     expect(forkCalls).toEqual([])
     expect(updateCalls).toEqual([])
-    expectDebugLogContaining('[AgentSummary] Skipping summary — poor mode active')
+    expectDebugLogContaining('poor mode active')
     expect(scheduledCount).toBe(initialScheduledCount + 1)
     expect(lastTimerHandle).not.toBe(initialTimerHandle)
   })
@@ -222,7 +218,7 @@ describe('startAgentSummarization', () => {
 
     handle.stop()
 
-    expectDebugLogContaining('[AgentSummary] Stopping summarization for task-1')
+    expectDebugLogContaining('Stopping summarization for task-1')
     expect(clearedHandles).toEqual([pendingHandle])
   })
 })

src/utils/__tests__/udsMessaging.test.ts

@@ -307,9 +307,7 @@ describe('UDS inbox retention', () => {
       '../udsClient.js'
     )
 
-    const error = await connectToPeer(path, () => {
-      throw new Error('Unexpected post-connect socket error')
-    }).then(
+    const error = await connectToPeer(path).then(
       () => undefined,
       err => err,
     )
@@ -340,24 +338,13 @@ describe('UDS inbox retention', () => {
     })
 
     let client: Socket | undefined
-    const socketErrors: Error[] = []
     try {
       const { connectToPeer } = await import('../udsClient.js')
-      client = await connectToPeer(
-        path,
-        error => {
-          socketErrors.push(error)
-        },
-        1000,
-      )
+      client = await connectToPeer(path, 50)
       await new Promise(resolve => setTimeout(resolve, 100))
 
       expect(client.destroyed).toBe(false)
-      expect(client.listenerCount('error')).toBe(1)
-
-      const socketError = new Error('post-connect failure')
-      client.emit('error', socketError)
-      expect(socketErrors).toEqual([socketError])
+      expect(client.listenerCount('error')).toBe(0)
     } finally {
       client?.destroy()
       for (const socket of sockets) {

src/utils/udsClient.ts

@@ -266,48 +266,33 @@ export async function sendToUdsSocket(
 
 /**
  * Connect to a peer and return the raw socket for bidirectional communication.
- * The caller owns the post-connect lifecycle through onSocketError, which is
- * attached before the Promise resolves so peer socket errors cannot be
- * swallowed or surface through a listener handoff window.
- * Pre-connect failures reject with UdsPeerConnectionError.
- * This only opens the transport; callers still own any capability handshake.
+ * The caller is responsible for managing the connection lifecycle.
  */
 export function connectToPeer(
   socketPath: string,
-  onSocketError: (error: Error) => void,
   timeoutMs = 5000,
 ): Promise<Socket> {
   return new Promise<Socket>((resolve, reject) => {
     const conn = createConnection(socketPath)
     let settled = false
-    const timeout = setTimeout(
-      fail,
-      timeoutMs,
-      new Error('Connection timed out'),
-    )
-    function cleanupListeners(): void {
-      clearTimeout(timeout)
-      conn.off('error', fail)
-    }
-    function fail(cause: unknown): void {
+    const fail = (cause: unknown) => {
       if (settled) {
         return
       }
       settled = true
-      cleanupListeners()
       conn.destroy()
       reject(new UdsPeerConnectionError(socketPath, cause))
     }
     conn.once('connect', () => {
-      if (settled) {
-        return
-      }
       settled = true
-      cleanupListeners()
-      conn.on('error', onSocketError)
+      conn.setTimeout(0)
+      conn.off('error', fail)
       resolve(conn)
     })
     conn.on('error', fail)
+    conn.setTimeout(timeoutMs, () => {
+      fail(new Error('Connection timed out'))
+    })
   })
 }