clide/docs/audits/pty-ipc-error-handling-2026-05-05.md

PTY + IPC error-handling audit

Date: 2026-05-05 Ticket: T-18 Decision ref: D-5

Punch list of error-handling issues in lib/src/pty/, lib/src/ipc/, and lib/src/daemon/. Severity-ranked. Each item references the follow-up ticket where the fix lands.

Critical — silent failures, leaks, races

1. lib/src/pty/native_pty.dart:155-158 — forkpty() failure throws StateError('forkpty() failed') with no errno. Caller can't distinguish ENOMEM/EAGAIN/ENOENT-of-/dev/ptmx. Capture errno before _freeAll (which may trample it) and surface via PtyException. → T-75

2. lib/src/pty/native_pty.dart:160-165 — Child process: chdir and execve returns are ignored. If execve returns (i.e. fails), we fall through to _exit(1) with no diagnostic. Write a one-line error envelope to fd 1 before exiting so the parent's reader sees "exec failed: ENOENT" instead of immediate EOF. → T-75

3. lib/src/pty/native_pty.dart:244-251 — write() ignores _nativeWrite return. Short writes silently drop bytes; -1/EPIPE reported as successful "wrote -1". Loop until full length is written or surface errno on negative returns. → T-75

4. lib/src/pty/native_pty.dart:259-262 — resize() ignores _ioctl and _nativeKill return values. EBADF on a half-closed fd silently no-ops. Set _dead = true on EBADF. → T-75

5. lib/src/pty/native_pty.dart:198-210 — Race: _spawnReader is async but NativePty.start returns immediately. close() racing with isolate spawn can leave the isolate orphaned. Make start await reader spawn or track the spawn-future. → T-76

6. lib/src/pty/native_pty.dart:280-290 — close() sets _dead = true before _nativeClose(_fd), but the reader isolate continues polling on _fd. If a new fd reuses that number, the reader's poll may briefly target the wrong file. Send shutdown signal via SendPort or self-pipe before closing. → T-76

7. lib/src/pty/session.dart:135-153 — Resource leak: if _recvFdAsync, setWinsize, proc.stdout.first.timeout, or _extractPid throws, the spawned ptyc Process and (in some cases) the received masterFd leak. Only line 151 closes masterFd. Wrap post-spawn block in try/catch that kills proc, closes masterFd, and rethrows. → T-76

8. lib/src/pty/session.dart:240 — _recvFdAsync: if Isolate.spawn itself throws, port is leaked. Wrap in try/catch. → T-76

9. lib/src/pty/session.dart:165-176 — write() returns raw libc.write result without checking < 0 / errno or looping for short writes. Same as #3. → T-75

10. lib/src/pty/session.dart:271-275 — Isolate.spawn(...).then(...) is fire-and-forget. If spawn fails, the error is silently swallowed and _readerIsolate remains null forever. Add .catchError or await it. → T-76

11. lib/src/ipc/server.dart:30-39 — broadcast() try/catch (_) swallows write errors with no logging. At least log the kind. → T-77

12. lib/src/ipc/server.dart:107 — client.writeln(resp.encode()) is not awaited and not guarded. If client disconnected mid-dispatch, this throws asynchronously with no onError handler. Wrap in try/catch and remove the client from _clients. → T-77

13. lib/src/ipc/server.dart:83-108 — _handleLine runs await dispatch(msg) with no per-request timeout. A misbehaving handler blocks the connection's read pipeline indefinitely. → T-77

14. lib/src/ipc/server.dart:46-50 — Stale-socket retry deletes the socket file unconditionally on SocketException. If two daemon instances race to start, the second rips the first's live socket out from under it. Try connect() first; refuse if a live daemon answers. → T-77

High — degraded UX / debugging

15. lib/src/daemon/pane_commands.dart:87-96 — _spawn catch-all flattens every failure into tool_error: pane.spawn failed: <toString>. "binary not found", "permission denied", "out of pty fds" all look the same. Map PtyException.errno (ENOENT/EACCES/EMFILE) to distinct hints/codes. → T-79

16. lib/src/daemon/editor_commands.dart:67-76 — Same pattern; editor.open catch-all loses FileSystemException distinctions (ENOENT vs EACCES vs EISDIR). → T-79

17. lib/src/daemon/files_commands.dart:78 — file.readAsStringSync() is unguarded; UTF-8 errors, permission errors, races with deletion turn into a 500-style dispatch error instead of a clean IpcResponse.err. Wrap in try/catch. → T-81

18. lib/src/daemon/files_commands.dart:74 — Path is concatenated with / and never validated. path: "../../../etc/passwd" traverses out of files.root. Resolve and verify the resulting path stays under root.absolute.path. → T-78 (security)

19. lib/src/pty/session.dart:201-234 — close() distinguishes EOF/EBADF/EIO only in comments. The 500ms timeout is silent (onTimeout: () {}). Log the timeout so we know when SIGKILL was actually needed. → T-81

20. lib/src/pty/session.dart:390-394 — Reader isolate treats any negative read return that isn't EINTR as EOF — including transient EAGAIN or recoverable EIO. Inspect errno and log non-EBADF/EIO/0 cases. → T-81

21. lib/src/pty/ffi/scm_rights.dart:115-116 — Returned cmsg-data fd is read without sanity-checking against msgControllen. A malformed peer that sends only a partial cmsg could let us read garbage as an fd. Verify dataOffset + 4 <= msgControllen before deref. → T-81

22. lib/src/ipc/server.dart:41-56 — start() logs to stderr.writeln but the rest of the daemon uses no logger. In the Flutter-host process stderr is often consumed by the engine. Standardize on a logger. → T-80

Medium — cleanliness

23. lib/src/pty/session.dart:390, native_pty.dart:262, 285 — Magic errno/signal numbers (4=EINTR, 9=SIGKILL, 28=SIGWINCH, _kSighup=1). Pull into named constants. → T-80

24. lib/src/pty/ffi/libc.dart:232-245 — errno getter does a lookupFunction on every access (catching ArgumentError every call on macOS). Cache the resolved function pointer. → T-80

25. lib/src/daemon/git_commands.dart:283 — _gitError always reports tool_error. A git push rejection or merge conflict is user-actionable, not a tool failure; could map to IpcExitCode.conflict when stderr matches known patterns. → T-81

26. lib/src/ipc/server.dart:97 — Dispatch error shows dispatch failed: $e (full exception toString). Trim and add the request cmd for log correlation. → T-80

27. lib/src/daemon/pane_commands.dart:136 — registry.write(id, bytes) return value n is shown to caller, but if n == -1 (write failed) we still respond ok. Distinguish. → T-81

28. lib/src/ipc/envelope.dart:88-94 — IpcResponse.fromJson throws TypeError if ok=false but error is missing. No graceful degradation for a malformed peer response. → T-81

29. lib/src/pty/native_pty.dart:111-119 — PATH resolution silently uses the first existing match without checking X_OK. A non-executable file shadows a valid binary further along PATH. → T-81