[codex] Structure connection persistence failures

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• 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 apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Touches all connection catalog and cache I/O on web and mobile; behavior change where non-transient catalog/migration errors may propagate instead of being swallowed during recovery.

Overview
Connection persistence and local storage now use typed, structured errors instead of ad-hoc string wrappers, with stable user-facing messages that do not echo underlying cause text.

Client runtime adds ConnectionStorageOperationError, availability errors for IndexedDB and desktop secure storage, and ConnectionTransientError.fromStorageFailure. ConnectionPersistenceError drops free-form message in favor of operation, stage, resource, optional environmentId / threadId / path, and cause, with a derived message.

Web and mobile storage layers map each failure boundary (IndexedDB, secure store, file cache, schema encode/decode) to those types. Catalog encode/decode uses shared Schema JSON codecs. Corrupt-catalog recovery uses catchTags for ConnectionTransientError only, so other failures propagate instead of being treated as recoverable corruption.

Mobile legacy migration uses LegacyConnectionMigrationError with stage (parse / decode) and cause instead of embedding cause strings in messages. Tests assert cause chains are preserved while messages stay generic.

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

Note

Structure connection persistence and relay errors with typed fields and redacted URLs

• Replaces interpolated message strings across connection storage, relay, and authorization error paths with structured error types carrying typed fields (stage, resource, operation, backend, cause, environmentId, etc.).
• Adds new error classes in model.ts and persistence.ts: ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a reworked ConnectionPersistenceError with a computed message that excludes the raw cause.
• Redacts sensitive URL data from relay errors and logs: ManagedRelayUrlInvalidError, ManagedRelayDpopProofCreationError, and offline log records now expose only length, protocol, and hostname instead of full URLs or credentials.
• ConnectionBlockedError and ConnectionTransientError are extended to carry optional cause, connectionId, expectedEnvironmentId, and actualEnvironmentId for configuration and authentication failures in bearer, relay, SSH, and DPoP paths.
• Risk: error message text changes across storage, relay, and authorization paths may break any callers that pattern-match on message strings.

^{Macroscope summarized b39a73f.}

[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: a29c1ecb-e335-4b45-82be-fe0d70eb54a9

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

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of string messages, preserving error cause chains and redacting sensitive URL information. Changes are mechanical with no runtime behavior modifications, and include comprehensive tests.

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

Dismissing prior approval to re-evaluate 4d9e86a

Dismissing prior approval to re-evaluate b39a73f