[codex] Structure cloud HTTP boundary errors

[juliusmarminge]

Stacked on #3243.

Summary

• represent relay configuration and request failures as structured Schema errors with operation, phase, method, URL, response status, and full cause context
• classify HTTP client failures on the error class and keep public messages independent from cause text
• replace broad predicate and single-tag catches in the cloud handlers with exact catchTags mappings
• retain boundary redaction while logging the complete structured cause chain
• remove the valueless CLI error forwarding alias and use namespace imports for Effect HTTP modules

Validation

• vp test apps/server/src/cloud (30 tests)
• vp check (passes; repository baseline warnings only)
• vp run typecheck

---

Note

Medium Risk
Touches cloud link reconciliation and credential/health handlers where mis-mapped catchTags could change which errors surface to clients, though behavior is largely preserved with safer messaging.

Overview
Introduces structured Schema errors for T3 Connect relay boundaries: CloudRelayConfigurationError for invalid T3CODE_RELAY_URL, and CloudRelayRequestError with operation, phase, method, URL, optional status, and full cause. Public message strings are fixed templates and no longer include upstream/cause text; failures are still logged with the full cause via failEnvironmentCloudInternalError.

Relay client calls (relayClientRequest) map encode/send/status/decode failures through CloudRelayRequestError.fromClientFailure instead of String(cause) in 500 responses. Link reconciliation and other cloud handlers now use explicit Effect.catchTags for secret-store, auth, CLI token, relay config/request, and schema errors rather than broad catchIf predicates.

Tests add a reconcileWith harness, assertions that relay errors redact sensitive transport/upstream details, and updated Effect HTTP namespace imports.

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

Note

Structure cloud HTTP boundary errors with typed CloudRelayRequestError and CloudRelayConfigurationError

• Introduces CloudRelayRequestError in http.ts to classify relay client failures by operation and phase (encode-request, send-request, check-response-status, decode-response), producing stable structured messages that do not leak upstream cause details.
• Adds CloudRelayConfigurationError for invalid relay URL config, replacing a generic internal error with a fixed guidance message referencing T3CODE_RELAY_URL.
• Replaces broad catchIf/SecretStoreError catches across all cloud handlers with granular catchTags targeting specific error variants, so unhandled error types now propagate instead of being silently coerced.
• Fixes consumeCloudReplayGuards to treat only SecretStorePersistError as an "already exists" signal; other secret store errors now propagate.
• Behavioral Change: handlers that previously caught wide secret store or auth error unions now only catch specific tags — errors outside those tags will surface as unhandled failures.

^{Macroscope summarized 6c12fe1.}

[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: 6d59a333-89eb-4708-9ef9-9bd37a710ad6

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/cloud-http-error-boundaries

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling to use explicit tag-based matching instead of type predicates, and introduces structured error classes that intentionally redact sensitive upstream information from error messages. The changes are defensive, well-tested, and don't alter business logic.

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