[codex] finish server process and preview Effect cleanup

[juliusmarminge]

What changed

• leaves MCP and orchestration modules untouched for the feat(orchestrator): introduce new orchestrator #2829 overhaul
• keeps namespace imports at actual service-module boundaries while restoring named package and helper imports
• replaces the generic ExternalLauncherError message payload with concrete structured error variants, derived messages, a category schema union, and a public predicate
• inlines the VcsProcess service contract and migrates consumers to VcsProcess.VcsProcess["Service"]
• preserves existing service documentation and updates behavioral coverage for launcher failures and RPC serialization

Validation

• affected backend suites: 8 files, 134 tests passed
• vp check (passes with existing unrelated warnings)
• vp run typecheck

Follow-up to #3191.

---

Note

Medium Risk
Changes the public error shape and breaks instanceof ExternalLauncherError checks; callers must use the union or isExternalLauncherError, though user-facing messages stay similar.

Overview
Replaces the single message-based ExternalLauncherError in contracts with five tagged variants (unknown/unsupported editor, command not found, browser spawn, editor spawn), a schema union type, and isExternalLauncherError. The server launcher now fails with structured fields (editor, command, target, args, cause) and derived message getters instead of hand-written strings.

launchAndUnref takes an error factory callback so spawn failures map to the right variant. Internal EditorLaunch now carries editor and target for those errors.

Tests and shell.openInEditor RPC coverage switch to ExternalLauncherCommandNotFoundError / ExternalLauncherUnknownEditorError and namespace imports (ExternalLauncher.ExternalLauncher, ProcessRunner.ProcessRunner) at service-module boundaries.

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

Note

Replace generic ExternalLauncherError with discriminated error union in external launcher

• Replaces the single ExternalLauncherError class in packages/contracts/src/editor.ts with five specific tagged error classes: ExternalLauncherUnknownEditorError, ExternalLauncherUnsupportedEditorError, ExternalLauncherCommandNotFoundError, ExternalLauncherBrowserSpawnError, and ExternalLauncherEditorSpawnError.
• Adds isExternalLauncherError type guard and exports the union type for runtime discrimination by callers.
• Updates externalLauncher.ts to emit the appropriate specific error at each failure point, passing structured context fields (editor, command, target, args, cause) instead of a generic message string.
• Augments the internal EditorLaunch interface with editor and target fields to carry metadata needed for structured error construction.
• Behavioral Change: callers checking for ExternalLauncherError by class identity will no longer match; they must use isExternalLauncherError or match specific subclasses.

^{Macroscope summarized fa3d309.}

[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: f538803e-2f69-453f-9651-2cf085e6388c

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/effect-service-server-process-preview-followup

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by splitting a generic error class into specific typed error classes with structured fields. The changes are mechanical with no behavioral impact - errors are thrown at the same points with richer context for better debugging.

No code changes detected at fa3d309. Prior analysis still applies.

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

Dismissing prior approval to re-evaluate 2e15534

Dismissing prior approval to re-evaluate 34ac1c1

Dismissing prior approval to re-evaluate 8d0fd5c