[codex] Structure primary environment request failures

[juliusmarminge]

Summary

• replace unstructured primary-environment HTTP failures with one schema error carrying operation, status, relevant resource identifiers, and the exact cause
• keep user-facing messages derived from safe structured HTTP error fields or code-owned fallbacks
• centralize the meaningful HTTP-to-request-error mapping on the error class and export its schema predicate

Validation

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

---

Note

Medium Risk
Touches auth bootstrap, session/pairing APIs, and error types callers may catch; behavior should stay similar but failure objects and predicates changed.

Overview
Replaces ad-hoc BootstrapHttpError and generic Error throws with a single PrimaryEnvironmentRequestError (Effect Schema tagged error) for primary-environment HTTP calls.

Each failure now carries operation (e.g. exchange-bootstrap-credential, list-pairing-links), status, user-facing detail, optional pairingLinkId / sessionId, and the original cause. Mapping is centralized in PrimaryEnvironmentRequestError.fromCause, which derives status and messages from structured HTTP errors or code-owned fallbacks; bootstrap credential exchange still applies friendly pairing-token copy via formatDetail.

isTransientBootstrapError now treats transient retries using the new error’s status. context.ts descriptor fetch uses the same error type. Public exports add PrimaryEnvironmentRequestError and isPrimaryEnvironmentRequestError.

The invalid-pairing-token test now asserts the structured error shape (including preserved EnvironmentAuthInvalidError cause) instead of only matching a thrown message string.

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

Note

Replace ad-hoc errors with structured PrimaryEnvironmentRequestError in primary environment auth

• Introduces PrimaryEnvironmentRequestError, a tagged error class with operation, status, detail, optional pairingLinkId/sessionId, and cause fields, replacing generic Error and BootstrapHttpError across all primary environment request functions in auth.ts and context.ts.
• Exports isPrimaryEnvironmentRequestError type guard from the primary environment module so callers can discriminate errors by operation and status.
• Updates isTransientBootstrapError to use isPrimaryEnvironmentRequestError instead of the now-removed isBootstrapHttpError.
• Behavioral Change: All primary environment request failures now reject with PrimaryEnvironmentRequestError instead of BootstrapHttpError or generic Error; callers that catch and inspect error types will need to update their checks.

^{Macroscope summarized eee2f35.}

[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: 13e08d2a-2d0c-4909-a89e-fd0e6c334b80

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-environment-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 generic errors with a structured PrimaryEnvironmentRequestError class. The change is mechanical - errors are thrown at the same points with equivalent messages, just with better structure for downstream handling.

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