[codex] Structure relay environment link errors

[juliusmarminge]

Summary

• preserve token, payload, JWT, and schema failures as the environment-link error cause
• replace the payload-decode Effect.option cause loss with an explicit mapped error
• attach cloud user, environment, and constrained validation-stage context to link errors

Validation

• vp test infra/relay/src/environments/EnvironmentLinker.test.ts --no-cache
• vp check
• vp run typecheck
• vpr typecheck

Overlap audit

• no active service/error-refactor PR overlaps these files; feat(relay): enforce resource limits #2925 is an unrelated broad feature branch

---

Note

Medium Risk
Touches JWT verification and nonce consumption on the environment-link path; behavior should match prior rejections but error shape and decode-path handling changed, which may affect API/logging consumers.

Overview
Relay environment linking now returns richer, stage-aware errors instead of generic invalid-proof failures.

EnvironmentLinkProofInvalid gains userId, a stage literal (e.g. decode_token, verify_proof, consume_proof_nonce), and an optional cause so JWT decode, schema decode, and verification failures are preserved rather than dropped. Payload decoding no longer uses Effect.option that swallowed errors—it maps failures to decode_payload with the underlying cause. EnvironmentLinkProofExpired also includes userId, and every rejection path in link sets stage (and cause where applicable).

Tests assert tampered proofs fail at verify_proof with a RelayJwtError cause, and replayed JTIs fail at consume_proof_nonce.

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

Note

Add structured context fields and stage discriminants to EnvironmentLinker link errors

• EnvironmentLinkProofInvalid now includes userId, a stage literal (e.g. decode_payload, verify_challenge, consume_proof_nonce), and an optional cause (underlying error).
• EnvironmentLinkProofExpired now includes userId and environmentId, and its message reflects the environmentId.
• All failure paths in EnvironmentLinker.link are updated to populate these fields, with cause propagation for JWT decode/verify errors.
• Tests assert that failures are EnvironmentLinkProofInvalid and validate structured fields including stage and cause._tag.

^{Macroscope summarized 4ea3e5b.}

[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: cc0e2b0f-2fd6-469f-81af-9d03076d863d

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/relay-environment-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR adds structured diagnostic fields (userId, environmentId, stage, cause) to environment link error objects for better debugging. The changes are purely additive and don't affect runtime behavior or control flow.

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