[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 authentication, cloud linking, health/mint, and relay credential flows across contracts and the environment server; behavior changes are mostly error shape and redaction, but mis-mapped catch tags could surface wrong client messages.

Overview
Cloud HTTP errors move from ad-hoc message strings to reason/operation-coded contract types (EnvironmentHttpBadRequestReason, EnvironmentHttpUnauthorizedReason, EnvironmentHttpInternalOperation, relay operation/phase, conflict reasons). Constructors derive stable user-facing text; wire payloads keep optional fields so message-only legacy bodies still decode during rolling deploys.

Relay outbound calls gain CloudRelayRequestError (phase classification, URL diagnostics without secrets) and CloudRelayConfigurationError for bad T3CODE_RELAY_URL. relayClientRequest maps every HTTP client failure through fromClientFailure instead of stringifying causes into 500s.

failEnvironmentCloudInternalError now takes structured operation context, logs causeTag only (not full cause), and returns EnvironmentHttpInternalServerError with internal cause retained but omitted from encoded JSON (tests assert this).

Cloud handlers switch from broad catchIf / generic secret-store catches to Effect.catchTags with per-failure operation labels. Unauthorized CLI linking uses reason: cloud_cli_authorization_required. Validation and conflict paths use machine reasons instead of inline messages.

Tests cover redaction, legacy decode, reconcile link auth, and mobile link-proof error propagation.

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

Note

Structure cloud HTTP boundary errors with typed reason codes and operation diagnostics

• Adds reason fields to 400, 401, and 409 error payloads (e.g. cloud_cli_authorization_required, invalid_relay_url) and structured operation/relayOperation/relayPhase fields to 500 payloads in environmentHttp.ts.
• Introduces CloudRelayRequestError in http.ts to wrap relay client failures with phase diagnostics (encode-request, send-request, check-response-status, decode-response) and sanitized messages that don't leak sensitive URL parts or upstream details.
• Refactors failEnvironmentCloudInternalError to log a causeTag instead of the raw cause, and replaces broad catchIf catches with Effect.catchTags throughout all cloud HTTP handlers.
• Decoding of all error types remains backward-compatible with legacy message-only payloads.
• Behavioral Change: consumeCloudReplayGuards now only swallows SecretStorePersistError with already-exists semantics; other secret store errors now propagate as failures instead of being silently ignored.

^{Macroscope summarized f785979.}

[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: efa42eef-e932-4888-ad86-e4b2d8cd11ff

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

Refactors HTTP error handling from string messages to structured reason codes with backwards compatibility. Changes are mechanical, add secret-leakage prevention, and include comprehensive tests for the new error structure.

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

Dismissing prior approval to re-evaluate fe10a0b

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Structured cause dropped from logs
  • Added { cause } back to the Effect.logError call in failEnvironmentCloudInternalError so the structured cause chain is preserved in server logs, matching the pattern used by failEnvironmentInternal in auth/http.ts.

Or push these changes by commenting:

@cursor push a6684f6aaa

Preview (a6684f6aaa)

diff --git a/apps/server/src/cloud/http.ts b/apps/server/src/cloud/http.ts
--- a/apps/server/src/cloud/http.ts
+++ b/apps/server/src/cloud/http.ts
@@ -201,7 +201,7 @@
 const failEnvironmentCloudInternalError =
   (message: string) =>
   (cause: unknown): Effect.Effect<never, EnvironmentHttpInternalServerError> =>
-    Effect.logError(message).pipe(
+    Effect.logError(message, { cause }).pipe(
       Effect.flatMap(() => Effect.fail(new EnvironmentHttpInternalServerError({ message, cause }))),
     );

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit fe10a0b. Configure here.}

Dismissing prior approval to re-evaluate f785979