[codex] Structure relay Live Activity errors

[juliusmarminge]

Summary

• attach user/device correlation fields to Live Activity registration and target-list persistence failures
• add a structured operation and delivery kind to the shared Live Activity state persistence error
• preserve the original database or schema cause at every persistence boundary
• construct errors directly at each boundary and derive messages from their structured context
• add focused coverage for every service operation failure mapping

Validation

• vp check (passes with 20 pre-existing warnings)
• vp run typecheck
• /Users/julius/.codex/worktrees/d5fa/codething-mvp/node_modules/.bin/vp test infra/relay/src/agentActivity/LiveActivities.test.ts --no-cache (3 tests)

Overlap audit

• no overlap with another active error-audit/service-refactor PR
• these paths also appear in broad draft feat(relay): enforce resource limits #2925 (feat(relay): enforce resource limits); that unrelated overlap is reported here for visibility

---

Note

Low Risk
Observability and error-shape changes only; persistence behavior is unchanged and covered by new failure-mapping tests.

Overview
Relay Live Activity persistence failures now carry structured correlation data instead of only a wrapped cause.

The three tagged errors gain fields such as userId, deviceId, operation, and optional kind, with human-readable message strings derived from that context. Each service method (register, listTargets, markDelivery, markStartQueued, clearStartQueued, invalidateDeliveryToken) maps DB failures at the boundary via Effect.mapError, including wrapping invalidateDeliveryToken in an inner Effect.gen so all branches share the same error shape.

A new test drives a failing fake RelayDb through every operation and asserts userId, deviceId, operation/kind, cause, and messages.

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

Note

Add correlation context fields to Live Activity persistence errors in relay

Enriches the three persistence error classes in LiveActivities.ts with structured context fields so failures are easier to trace.

• LiveActivityRegistrationPersistenceError now includes userId and deviceId; LiveActivityTargetListPersistenceError includes userId; LiveActivityDeliveryMarkPersistenceError includes operation, userId, deviceId, and kind.
• Each error's message getter is updated to embed the relevant identifiers and operation name.
• All LiveActivities service handlers (register, listTargets, markDelivery, markStartQueued, clearStartQueued, invalidateDeliveryToken) now map DB failures to the appropriate enriched error type.
• Tests in LiveActivities.test.ts verify that simulated DB failures produce errors with the expected correlation fields and messages.

^{Macroscope summarized cdef70f.}

[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: 1027e367-6370-4e47-a54a-3eac0389f9f4

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-live-activity-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR adds contextual fields (userId, deviceId, operation) to Live Activity error classes for better debugging. No runtime behavior changes - only error message content is enhanced, with corresponding tests added.

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

Dismissing prior approval to re-evaluate cdef70f