[codex] Structure web cloud-link failures

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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

[juliusmarminge]

Summary

• replace the generic web cloud-link error bucket and constructor wrappers with structured Schema errors
• preserve nested relay and environment API causes while promoting relay trace IDs and decoded error details through value-adding static mappers
• distinguish configuration, installation, response-mismatch, endpoint parsing, and operation failures without deriving messages from raw cause text
• add focused coverage for relay trace/error promotion and nested environment API cause preservation

Validation

• vp test run apps/web/src/cloud/linkEnvironment.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Overlap

• no open PR modifies either changed file

---

Note

Medium Risk
Touches authentication-adjacent cloud link and relay flows with a breaking error shape for any UI that relied on the old generic error; behavior is largely preserved with safer logging and earlier URL validation.

Overview
Replaces the single generic CloudEnvironmentLinkError with a Schema union of tagged errors (CloudEnvironmentLinkOperationError, relay URL/config, relay client install, and response-mismatch types) and exports isCloudEnvironmentLinkError for narrowing.

Operation failures now use stable action-based messages plus optional traceId, decoded relayError, and environmentError from cause chains via fromManagedRelay / fromEnvironmentApi, instead of string messages built from relay/environment text.

Diagnostics attach only sanitized relay/environment URL fields (length, protocol, hostname) via getUrlDiagnostics; full URLs are not stored on errors. Link flow validates httpBaseUrl with Effect (endpointOrigin, makeCloudEnvironmentHttpApiClient) before relay install prompts, and unlink revoke warnings log the same safe fields instead of raw cause or full relay URLs.

Tests cover structured relay/environment failures, invalid URLs, secret exclusion in errors and revoke logs, and updated RelayClientStatus fixtures.

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

Note

Structure cloud link failures into typed, diagnostic-carrying error classes

• Replaces the previous Data.TaggedError-based CloudEnvironmentLinkError with a hierarchy of Schema.TaggedErrorClass types in linkEnvironment.ts, each carrying sanitized URL diagnostics, environmentId, traceId, and nested relay/environment errors.
• Adds CloudEnvironmentLinkOperationError with static constructors fromManagedRelay and fromEnvironmentApi that normalize errors and redact secrets from URL fields before attaching them as diagnostics.
• Adds specific error classes for distinct failure modes: CloudRelayUrlNotConfiguredError, CloudRelayClientInstallUnsupportedError, CloudRelayClientInstallCancelledError, CloudRelayClientInstallIncompleteError, CloudRelayClientUnavailableAfterInstallError, and CloudEnvironmentLinkResponseMismatchError.
• Introduces isCloudEnvironmentLinkError for reliable discriminated detection of the full error union by callers.
• Behavioral Change: all cloud link operations now emit structured typed errors with standardized messages (Could not <action>[ for environment "id"].); raw relay URLs and error objects are never included in log output.

^{Macroscope summarized 1a444b2.}

[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: 504b5aba-ebf0-4c77-8b0a-d5abf1fc201c

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/web-cloud-link-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors cloud-link error handling by replacing a generic error class with multiple specific structured error types, improving diagnostics while keeping sensitive URL data out of logs. No business logic changes - only error construction and formatting.

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

Dismissing prior approval to re-evaluate 26373cd

Dismissing prior approval to re-evaluate d25d615

[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: Relay install before URL validation
  • Moved endpointOrigin and makeCloudEnvironmentHttpApiClient calls before ensureRelayClientAvailable so URL validation occurs before any relay-client installation side effects.

Or push these changes by commenting:

@cursor push 9ebe9107af

Preview (9ebe9107af)

diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts--- a/apps/web/src/cloud/linkEnvironment.ts+++ b/apps/web/src/cloud/linkEnvironment.ts@@ -628,9 +628,6 @@
environmentId: input.target.environmentId,
});
}
- const relayClient = yield* ManagedRelay.ManagedRelayClient;- yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));-
const origin = yield* endpointOrigin({
environmentId: input.target.environmentId,
httpBaseUrl: input.target.httpBaseUrl,
@@ -640,6 +637,9 @@
httpBaseUrl: input.target.httpBaseUrl,
});
+ const relayClient = yield* ManagedRelay.ManagedRelayClient;+ yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));+
const challenge = yield* relayClient
.createEnvironmentLinkChallenge({
clerkToken: input.clerkToken,

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

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