[codex] Structure Codex shadow home errors

[juliusmarminge]

Summary

• replace the generic shadow-home error with structural filesystem, path-conflict, entry-conflict, and private-entry tags
• preserve filesystem causes and exact operation/path context at each failure boundary
• use exact PlatformError catch semantics and remove generic constructor/normalization wrappers
• cover structural conflict data and filesystem cause preservation

Validation

• vp test run apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Error-shape and messaging changes only within Codex shadow home setup; behavior on success paths is unchanged and coverage is expanded in unit tests.

Overview
Replaces the single generic CodexShadowHomeError (detail string + optional cause) with four tagged error types and a Schema.Union type: filesystem failures, path conflict (shadow equals shared home), entry conflict (real file blocks symlink), and private-entry symlink (auth.json must not be a symlink).

Each failure now carries structured fields (sharedHomePath, effectiveHomePath, operation, path, entryName, linkPath, targetPath, and PlatformError as cause on FS errors). Generic toShadowHomeError / normalizeShadowHomeError wrappers are removed in favor of Effect.catchTags({ PlatformError }) at each FS boundary.

Tests assert specific error classes, matchObject payloads, messages, and a new case that FS errors preserve operation and cause when shared home is not a directory.

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

Note

Replace generic CodexShadowHomeError with structured discriminated error variants in materializeCodexShadowHome

• Replaces the single generic CodexShadowHomeError class with a union of four specific error types: CodexShadowHomeFileSystemError, CodexShadowHomePathConflictError, CodexShadowHomeEntryConflictError, and CodexShadowHomePrivateEntrySymlinkError.
• Each error type carries structured fields (e.g. sharedHomePath, effectiveHomePath, operation, path, cause) and a deterministic message, replacing the previous generic wrapping helpers toShadowHomeError and normalizeShadowHomeError.
• Internal helpers (readLinkState, removePrivateSymlink, ensureSymlink, ensureShadowAuthIsPrivate) are updated to accept structured input objects and return the appropriate specific error type.
• Behavioral Change: callers of materializeCodexShadowHome now receive discriminated error variants instead of a single generic class, requiring callers to handle each variant explicitly.

^{Macroscope summarized 9765bfc.}

[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: a0386edf-1522-4c96-8571-31510d3e96af

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-codex-shadow-home-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 single generic error class with multiple specific error types, improving error structure and messages without changing runtime behavior. The changes are well-tested and low risk.

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