[codex] Structure client persistence errors

[juliusmarminge]

Summary

• make ConnectionPersistenceError derive its message from a typed operation while retaining environment/thread identifiers and a required exact cause
• attach resource context at the web and mobile storage failure boundaries
• remove constructor-only persistence error aliases so each transformation remains visible where the underlying failure occurs
• capture synchronous mobile thread deletion failures instead of allowing them to escape as defects

Validation

• pnpm vp test packages/client-runtime/src/platform/persistence.test.ts packages/client-runtime/src/connection/registry.test.ts apps/web/src/connection/storage.test.ts apps/mobile/src/connection/storage.test.ts
• pnpm vp check
• pnpm vp run typecheck
• pnpm vp run lint:mobile

---

Note

Medium Risk
Touches all client persistence error paths on web and mobile; behavior is mostly observability and error typing, but incorrect mapping could change how registry handles failed removals.

Overview
ConnectionPersistenceError no longer takes a free-form message. It now requires a typed operation, optional environmentId / threadId, and a cause (Schema.Defect()); the user-facing message is derived from operation (e.g. "Could not load thread.").

Web and mobile connection storage drop local persistenceError / shellPersistenceError helpers and construct ConnectionPersistenceError at each failure site, attaching environment (and thread where relevant) plus the underlying failure. Catalog/target mapping no longer wraps transient errors in a custom message—it passes cause through. On mobile, thread file deletion is wrapped in Effect.try so sync delete failures become ConnectionPersistenceError instead of escaping as defects.

Tests add persistence.test.ts for the new shape and update registry tests to use cause instead of message.

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

Note

Structure ConnectionPersistenceError to carry contextual fields and standardize error messages

• Adds environmentId, threadId, and cause fields to ConnectionPersistenceError in persistence.ts; the message getter now produces a standardized 'Could not <operation>' string instead of embedding the original cause text.
• Updates all storage error construction in mobile storage and web storage to build ConnectionPersistenceError directly with contextual fields, removing the shellPersistenceError and persistenceError helper utilities.
• Adds a test in persistence.test.ts verifying the new fields and standardized message format.
• Behavioral Change: error messages no longer include the original cause string; callers that matched on error.message content will need to inspect error.cause instead.

^{Macroscope summarized 9e1df91.}

[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: bf83eefa-dc28-448a-9b7f-64ddd1cbbe0d

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/client-connection-persistence-errors

---

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

[juliusmarminge]

Superseded by the existing connection-persistence owner PR #3255. The remaining catalog-specific structural improvements are being consolidated onto that branch.

[macroscopeapp]

Approvability

Verdict: Approved

This PR restructures ConnectionPersistenceError to carry structured context fields (environmentId, threadId, cause) instead of a formatted message string. The changes are mechanical - same error type, same operations - affecting only error diagnostics rather than runtime behavior.

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