fix: keep UDS peer failures structured (#375)

* 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.

* docs: clarify UDS peer socket ownership

CodeRabbit's #375 pass found that connectToPeer now correctly hands socket errors to the caller, but the JSDoc needed to spell out that contract. The lifecycle test also uses a less brittle post-connect timeout so slow CI does not turn the ownership check into a connection-speed race.

Constraint: The raw socket API intentionally detaches its internal listener after successful connect so caller-owned errors are not swallowed.

Rejected: Keep the test timeout at 50ms | it tests scheduler speed instead of socket lifecycle ownership.

Confidence: high

Scope-risk: narrow

Directive: connectToPeer callers must attach their own error listener immediately after awaiting the socket.

Tested: bun test src/utils/__tests__/udsMessaging.test.ts

Tested: bunx tsc --noEmit --pretty false

Tested: bun run lint

Tested: git diff --check

Tested: bun run test:all

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

* fix: close peer socket listener handoff window

CodeRabbit and Claude review found that documenting caller-owned raw socket errors still left a Promise handoff window and a stale timeout-listener risk. The peer connection API now requires a caller error handler and installs it before resolving, while cleanup removes internal error and timeout listeners on every path.

Constraint: Keep the fix precise to PR #375 review feedback and avoid warning suppression or fallback behavior.
Rejected: Leave the behavior documented only | still permits an unhandled socket error window between resolve and caller listener attachment.
Rejected: Keep a no-op internal error listener | would silently swallow caller-owned socket errors.
Confidence: high
Scope-risk: narrow
Directive: Do not add raw connectToPeer callers without providing a real onSocketError handler and capability handshake.
Tested: bun test src/utils/__tests__/udsMessaging.test.ts src/services/AgentSummary/__tests__/agentSummary.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: bun audit
Not-tested: Manual external ACP peer runtime beyond repository tests.

* fix: use a deadline timer for peer connects

The raw socket handoff no longer needs Socket#setTimeout; an ordinary connection deadline keeps the timeout behavior while avoiding an internal socket timeout listener that has no reliable UDS integration path to exercise.

Constraint: Keep Codecov coverage honest without adding ignore pragmas, mocks, or fallback suppression.

Rejected: c8 ignore on the timeout listener | hides the uncovered branch instead of simplifying the lifecycle.

Rejected: keep Socket#setTimeout listener | leaves a socket listener lifecycle to manage for a connect-only deadline.

Confidence: high

Scope-risk: narrow

Directive: Keep connectToPeer errors caller-owned via onSocketError and reject pre-connect failures with UdsPeerConnectionError.

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

Tested: bunx tsc --noEmit --pretty false

Tested: bun run lint

Tested: bun test src/utils/__tests__/udsMessaging.test.ts --coverage --coverage-reporter lcov --coverage-dir coverage-uds

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: bun audit

Not-tested: Manual external ACP peer runtime beyond repository tests.

---------

Co-authored-by: unraid <local@unraid.local>

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

@@ -109,6 +109,10 @@ describe('startAgentSummarization', () => {
     lastTimerHandle = undefined
   })
 
+  function expectDebugLogContaining(fragment: string): void {
+    expect(debugLogs.some(message => message.includes(fragment))).toBe(true)
+  }
+
   test('summarizes bounded transcript once and skips unchanged fingerprints', async () => {
     handle = startTestSummarization()
 
@@ -157,7 +161,7 @@ describe('startAgentSummarization', () => {
 
     expect(forkCalls).toEqual([])
     expect(updateCalls).toEqual([])
-    expect(debugLogs).toContain(
+    expectDebugLogContaining(
       '[AgentSummary] Skipping summary for task-1: no bounded context available',
     )
   })
@@ -171,7 +175,7 @@ describe('startAgentSummarization', () => {
 
     expect(forkCalls).toEqual([])
     expect(updateCalls).toEqual([])
-    expect(debugLogs).toContain(
+    expectDebugLogContaining(
       '[AgentSummary] Skipping summary for task-1: not enough messages (2)',
     )
   })
@@ -188,9 +192,7 @@ describe('startAgentSummarization', () => {
 
     expect(forkCalls).toEqual([])
     expect(updateCalls).toEqual([])
-    expect(debugLogs).toContain(
-      '[AgentSummary] Skipping summary — poor mode active',
-    )
+    expectDebugLogContaining('[AgentSummary] Skipping summary — poor mode active')
     expect(scheduledCount).toBe(initialScheduledCount + 1)
     expect(lastTimerHandle).not.toBe(initialTimerHandle)
   })
@@ -220,9 +222,7 @@ describe('startAgentSummarization', () => {
 
     handle.stop()
 
-    expect(debugLogs).toContain(
-      '[AgentSummary] Stopping summarization for task-1',
-    )
+    expectDebugLogContaining('[AgentSummary] Stopping summarization for task-1')
     expect(clearedHandles).toEqual([pendingHandle])
   })
 })

src/utils/__tests__/teammateMailbox.test.ts

@@ -365,7 +365,11 @@ describe('teammate mailbox retention', () => {
     if (code === undefined) {
       throw new Error('Expected filesystem errno code')
     }
-    expect(['EISDIR', 'EPERM', 'EACCES']).toContain(code)
+    const expectedCodes =
+      process.platform === 'win32'
+        ? ['EISDIR', 'EPERM', 'EACCES']
+        : ['EISDIR']
+    expect(expectedCodes).toContain(code)
     expect((await stat(inboxPath)).isDirectory()).toBe(true)
   })
 

src/utils/__tests__/udsMessaging.test.ts

@@ -275,7 +275,7 @@ describe('UDS inbox retention', () => {
         '../udsClient.js'
       )
 
-      const error = await sendToUdsSocket(path, 'hello', 50).then(
+      const error = await sendToUdsSocket(path, 'hello', 200).then(
         () => undefined,
         err => err,
       )
@@ -301,6 +301,75 @@ describe('UDS inbox retention', () => {
     }
   })
 
+  test('connectToPeer reports connection failures as peer connection errors', async () => {
+    const path = socketPath('uds-connect-error')
+    const { connectToPeer, UdsPeerConnectionError } = await import(
+      '../udsClient.js'
+    )
+
+    const error = await connectToPeer(path, () => {
+      throw new Error('Unexpected post-connect socket error')
+    }).then(
+      () => undefined,
+      err => err,
+    )
+
+    expect(error).toBeInstanceOf(UdsPeerConnectionError)
+    if (!(error instanceof UdsPeerConnectionError)) {
+      throw new Error('Expected UDS peer connection error')
+    }
+    expect(error.socketPath).toBe(path)
+  })
+
+  test('connectToPeer leaves connected socket lifecycle to the caller', async () => {
+    const path = socketPath('uds-connect-lifecycle')
+    if (process.platform !== 'win32') {
+      await mkdir(dirname(path), { recursive: true })
+    }
+
+    const sockets = new Set<Socket>()
+    const receiver = createServer(socket => {
+      sockets.add(socket)
+      socket.on('close', () => {
+        sockets.delete(socket)
+      })
+    })
+    await new Promise<void>((resolve, reject) => {
+      receiver.on('error', reject)
+      receiver.listen(path, () => resolve())
+    })
+
+    let client: Socket | undefined
+    const socketErrors: Error[] = []
+    try {
+      const { connectToPeer } = await import('../udsClient.js')
+      client = await connectToPeer(
+        path,
+        error => {
+          socketErrors.push(error)
+        },
+        1000,
+      )
+      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])
+    } finally {
+      client?.destroy()
+      for (const socket of sockets) {
+        socket.destroy()
+      }
+      await closeServer(receiver)
+      if (process.platform !== 'win32') {
+        await unlink(path).catch(() => undefined)
+      }
+    }
+  })
+
   test('sendUdsMessage fails closed before connecting without an auth token', async () => {
     await expect(
       sendUdsMessage(socketPath('no-auth-token'), { type: 'text', data: 'x' }),

src/utils/udsClient.ts

@@ -266,17 +266,48 @@ export async function sendToUdsSocket(
 
 /**
  * Connect to a peer and return the raw socket for bidirectional communication.
- * The caller is responsible for managing the connection lifecycle.
+ * 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.
  */
-export function connectToPeer(socketPath: string): Promise<Socket> {
+export function connectToPeer(
+  socketPath: string,
+  onSocketError: (error: Error) => void,
+  timeoutMs = 5000,
+): Promise<Socket> {
   return new Promise<Socket>((resolve, reject) => {
-    const conn = createConnection(socketPath, () => {
+    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 {
+      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)
       resolve(conn)
     })
-    conn.on('error', reject)
-    conn.setTimeout(5000, () => {
-      conn.destroy(new Error('Connection timed out'))
-    })
+    conn.on('error', fail)
   })
 }