[codex] Structure primary environment target failures

[juliusmarminge]

Summary

• replace plain primary-target configuration and protocol errors with schema errors carrying target source and relevant structured fields
• wrap URL construction failures without copying raw URL values into outer error messages while retaining the exact parser cause
• make primary-target resolution accurately non-null and remove the unreachable generic HTTP-target error

This is stacked on #3409 because both changes share the primary-environment barrel and bootstrap tests.

Validation

• vp test apps/web/src/environments/primary/bootstrap.test.ts apps/web/src/authBootstrap.test.ts (23 tests)
• vp check
• vp run typecheck

---

Note

Medium Risk
Changes bootstrap/connection URL resolution and error surfaces at app startup; mis-handled throws could block connecting, though behavior is largely equivalent with clearer failures.

Overview
Primary environment target resolution now throws Effect Schema tagged errors instead of generic Error strings, with fields for target source (configured, window-origin, desktop-managed), URL kind, protocol, or which desktop bootstrap URLs are missing.

URL parsing goes through a shared parseTargetUrl helper that wraps URL failures in PrimaryEnvironmentUrlInvalidError, keeps the original parser cause, and avoids putting raw configured URLs in user-facing messages. Unsupported window protocols and partial desktop bootstrap data get PrimaryEnvironmentProtocolUnsupportedError and DesktopEnvironmentBootstrapIncompleteError respectively.

readPrimaryEnvironmentTarget is typed as always returning a target (desktop → configured → window origin), so resolvePrimaryEnvironmentHttpUrl drops the old null guard and the unreachable “unable to resolve HTTP base URL” error. The primary environment barrel re-exports the new error classes, type guards, and PrimaryEnvironmentTarget. Bootstrap tests cover invalid env URLs, missing wsBaseUrl, and file: origins.

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

Note

Replace generic errors with structured typed errors for primary environment target failures

• Introduces PrimaryEnvironmentRequestError in auth.ts, a Schema-backed tagged error carrying operation, status, detail, optional pairingLinkId/sessionId, and cause; replaces all BootstrapHttpError and generic Error throws across auth operations.
• Adds three new error classes in target.ts: PrimaryEnvironmentUrlInvalidError (sanitized message, no raw URL leakage), PrimaryEnvironmentProtocolUnsupportedError, and DesktopEnvironmentBootstrapIncompleteError.
• readPrimaryEnvironmentTarget now returns a non-null PrimaryEnvironmentTarget or throws a structured error; callers can no longer receive null.
• Adds Schema.is-based type guards (isPrimaryEnvironmentRequestError, isPrimaryEnvironmentUrlInvalidError, etc.) and exports all new types from index.ts.
• Behavioral Change: all callers that previously caught BootstrapHttpError or checked for null from target resolution must now handle the new error types.

^{Macroscope summarized dc98dcb.}

[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: d57731c1-9877-498a-ab30-812d57cce5f4

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-primary-target-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling to use structured, typed error classes instead of generic Error objects. The changes are mechanical - replacing error constructors and adding type guards - with no changes to when errors are thrown or core runtime behavior.

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

Dismissing prior approval to re-evaluate dc98dcb