[codex] Structure preferred editor failures

[juliusmarminge]

Summary

Opening a path in the preferred editor represented two distinct precondition failures with one Data.TaggedError whose only field was caller-supplied message text. That made “no environment selected” and “no compatible editor available” indistinguishable except by parsing their messages, and discarded the path and editor-selection context at the async command boundary.

This change gives each failure its own Schema error type. The missing-environment error records the attempted path. The unavailable-editor error records the environment, attempted path, and reported editor IDs. Each message is derived from those fields, and the command error channel now exposes the distinct types directly. There are no reason switches or constructor wrappers.

No behavior test was added for this pure error-model refactor.

Validation

• pnpm vp check (passes with existing repository warnings)
• pnpm vp run typecheck

---

Note

Low Risk
Pure error-model refactor in editor preferences with no runtime behavior change beyond richer failure payloads and messages.

Overview
Preferred-editor open failures are no longer a single Data.TaggedError with a free-form message. They are split into two Effect Schema tagged error classes so callers can branch on type instead of parsing strings.

PreferredEditorEnvironmentRequiredError is returned when no environment is selected; it carries targetPath. PreferredEditorUnavailableError is returned when no compatible editor exists; it carries environmentId, targetPath, and availableEditorIds. User-facing text is computed from those fields via overridden message getters.

useOpenInPreferredEditor’s result error union is updated to expose both types explicitly.

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

Note

Structure preferred editor failures into distinct typed errors in useOpenInPreferredEditor

• Splits the single PreferredEditorUnavailableError into two distinct Schema.TaggedErrorClass types: PreferredEditorEnvironmentRequiredError (no environment selected) and PreferredEditorUnavailableError (no matching editor found).
• PreferredEditorEnvironmentRequiredError carries targetPath and reports that no environment is selected.
• PreferredEditorUnavailableError now carries structured fields: environmentId, targetPath, and availableEditorIds.
• Both errors are defined using effect/Schema instead of effect/Data, enabling schema-based introspection of error fields.

^{Macroscope summarized 09d324b.}

[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: 20d74e4a-4b11-4ac2-ba64-ad19a623bbc6

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/web-preferred-editor-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This is a low-risk refactoring that restructures error classes to use typed fields instead of plain message strings. The error conditions and control flow remain unchanged; only the error data structure is improved.

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

[juliusmarminge]

Superseded by #3324. The richer targetPath/environmentId/availableEditorIds error shape has been applied to the older reviewed PR.