[codex] Structure bootstrap errors

[juliusmarminge]

Summary

• replace the generic bootstrap error with distinct tagged stat, stream-open, read, and decode failures
• attach file descriptor, platform, and fd path context while preserving original OS and schema causes
• classify unavailable descriptors through catchTags without swallowing unrelated stat failures
• retain existing unavailable, fallback, and timeout behavior

Validation

• vp test run apps/server/src/bootstrap.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized bootstrap I/O error typing and observability; success, timeout, unavailable-fd, and duplication-fallback behavior are unchanged and covered by tests.

Overview
Replaces the single generic BootstrapError with four schema-tagged failures (BootstrapFdStatError, BootstrapInputStreamOpenError, BootstrapEnvelopeReadError, BootstrapEnvelopeDecodeError) exposed as a BootstrapError union, each carrying fd (and platform / fdPath for stream-open) plus the original cause.

readBootstrapEnvelope now fails with the specific tag at stat, stream open, read, and decode boundaries; unavailable fds still yield Option.none() via catchTags on stat/read when errno is EBADF/ENOENT, while non-availability stat errors (e.g. EACCES) propagate. Stream-open messages and context are updated (fd path resolved before the try block).

Tests add fs mocks for configurable openSync failures and fstatSync EACCES, plus cases that assert error type, fields, messages, and preserved causes.

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

Note

Structure bootstrap errors into typed error classes in readBootstrapEnvelope

• Replaces the generic BootstrapError with four specific tagged error classes: BootstrapFdStatError, BootstrapInputStreamOpenError, BootstrapEnvelopeReadError, and BootstrapEnvelopeDecodeError.
• Each error carries the relevant fd and the original cause, with BootstrapInputStreamOpenError also including platform and optional fdPath.
• isFdReady now re-fails with BootstrapFdStatError when fstatSync fails for reasons other than fd unavailability, instead of silently swallowing the error.
• Adds tests covering the new error types for open failures, stat failures, and decode failures in bootstrap.test.ts.

^{Macroscope summarized 9333880.}

[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: 278b0b65-f82f-4908-9d40-4c571b7ffc1d

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-bootstrap-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing a generic BootstrapError with four specific typed error classes, each capturing relevant context (fd, platform, cause). The change improves error observability without altering runtime behavior, and includes comprehensive test coverage for all new error types.

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