[codex] Structure terminal adapter startup defects

[juliusmarminge]

Summary

Terminal adapter startup failures were not consistently diagnosable. Bun's unsupported Windows path died with a bare string, while a rejected node-pty native-module import surfaced as an unstructured defect without host context.

This change preserves the existing fatal startup semantics while making both defects structured. The Bun defect records the unsupported platform. The Node defect records platform and architecture and retains the exact module-load rejection as cause, keeping the original stack chain intact. The external module loader is injectable so the failure boundary can be tested without mocking core logic.

Validation

• vp test apps/server/src/terminal/BunPtyAdapter.test.ts apps/server/src/terminal/NodePtyAdapter.test.ts
• vp check (passes with existing repository warnings)
• vp run typecheck

---

Note

Low Risk
Behavior remains fatal startup defects; changes are limited to error shape, diagnostics, and testability in terminal adapters.

Overview
Terminal adapter startup still fails fatally on unsupported Bun hosts and when node-pty cannot load, but those paths now die with typed Schema.TaggedErrorClass defects instead of bare strings or unstructured rejections.

Bun: BunPtyAdapter.make on win32 dies with BunPtyUnsupportedPlatformError (platform + user-facing message). Node: NodePtyAdapter.make wraps a failed dynamic import in NodePtyModuleLoadError (platform, architecture, original cause) via Effect.tryPromise + orDie. An optional NodePtyModuleLoader hook lets tests simulate load failure without mocking internals.

New effect tests assert the squashed defect shape for both adapters.

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

Note

Structure terminal adapter startup defects with typed error classes

• Adds BunPtyUnsupportedPlatformError to BunPtyAdapter.ts: a tagged Schema error with a platform field, replacing the plain string die on win32.
• Adds NodePtyModuleLoadError to NodePtyAdapter.ts: a tagged Schema error carrying platform, architecture, and the underlying cause, thrown when node-pty fails to load.
• NodePtyAdapter.make now accepts an optional module loader, enabling the new load-failure path to be tested without native modules.
• Behavioral Change: callers catching defects from either adapter must now handle structured error types instead of plain strings or untyped rejections.

^{Macroscope summarized 5681b5c.}

[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: 7d416a7e-51a3-49c2-a4b1-18f93bb74fd5

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/server-residual-terminal-adapters

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR converts unstructured error strings into typed error classes for terminal adapter startup failures. The control flow and error scenarios remain unchanged - this is a structural improvement to error handling that improves testability without affecting runtime behavior.

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