[codex] Structure terminal PTY operation failures

[juliusmarminge]

Summary

• convert synchronous PTY write and resize exceptions from defects into typed terminal errors
• preserve the exact adapter cause and attach thread, terminal, PID, and resize dimensions without copying terminal input data
• apply the same resize boundary to explicit resize, reopen, and attach paths, and only mutate stored dimensions after a successful resize

Verification

• vp test apps/server/src/terminal/Manager.test.ts (46 passed)
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

---

Note

Medium Risk
Changes the terminal error contract and PTY failure paths (write/resize/open); callers matching old TerminalCwdError.reason must use new tags, but behavior is more predictable and input is not leaked on write failures.

Overview
Replaces the monolithic TerminalCwdError (reason + optional cause) with TerminalCwdNotFoundError, TerminalCwdNotDirectoryError, and TerminalCwdStatError (stat failures keep the PlatformError as cause). TerminalCwdError remains a union type for TerminalError.

Adds TerminalWriteError and TerminalResizeError for synchronous PTY write / resize failures, with threadId, terminalId, terminalPid, and resize dimensions; write errors do not include input data.

TerminalManager wraps PTY I/O in Effect.try via resizePtyProcess, applies resize on open/attach/resize only after success, and logs full cause objects instead of error.message strings. Tests cover cwd variants and PTY I/O error shape.

^{Reviewed by Cursor Bugbot for commit 30a32cf. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Structure terminal PTY operation failures into typed errors for cwd, write, and resize

• Replaces the single TerminalCwdError class with a union of TerminalCwdNotFoundError, TerminalCwdNotDirectoryError, and TerminalCwdStatError, each with distinct tags and appropriate cause fields.
• Adds TerminalWriteError and TerminalResizeError tagged errors that carry thread/terminal/PID context and the underlying cause without leaking input data.
• Wraps raw PTY write and resize calls in Effect.try (and a new resizePtyProcess helper) so failures surface as structured errors instead of thrown exceptions.
• Extends the TerminalError union in terminal.ts to include the two new I/O error types.
• Risk: callers that previously matched on TerminalCwdError or caught raw exceptions from PTY operations must now handle the new error variants.

^{Macroscope summarized 30a32cf.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 69e65eab-4f3f-4b0c-8d93-1b467cc9cadc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-terminal-pty-failures

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR restructures terminal PTY error handling by splitting a generic error type into specific variants (NotFound, NotDirectory, StatError) and adding structured error handling for write/resize operations. The changes improve error observability without altering core functionality, and include comprehensive test coverage.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate 7e5a4d6

Dismissing prior approval to re-evaluate 4219331